# Driver installation

> Install the Synnax Driver on a separate machine from the Synnax Core.

The Synnax Driver can also be installed as a separate binary, making it possible to integrate data acquisition hardware from multiple host machines into a single Synnax deployment.

## Step 1 Installation

To get started, you’ll need to install the Synnax Driver. Choose your operating system below to see the installation instructions:

**NI Linux Real-Time**

### Prerequisites

#### Supported hardware and software

The Synnax Driver supports the cRIO-904x and cRIO-905x families of controllers running NI Linux Real-Time 2024 Q1 and later.

#### NI-DAQmx programming mode

Data acquisition hardware connected to the cRIO must be configured to use the NI-DAQmx real-time programming mode.

To change the programming mode, use NI Measurement & Automation Explorer (NI MAX). For detailed instructions, see the [NI CompactRIO User Manual](https://www.ni.com/docs/en-US/bundle/ni-compactrio/page/programming-modes.html) and the [NI-DAQmx on CompactRIO](https://www.ni.com/en/shop/compactrio/what-are-compactrio-controllers/what-is-compactrio-with-ni-daqmx-.html) guide.

#### SSH access

The easiest way to install the Driver is to use an SSH connection to the cRIO. Once the Driver is installed, SSH can be disabled, although we recommend keeping it enabled to install updates and manage the Driver.

#### Network available Synnax Core

In order to function properly, the Driver must be able to connect to a Synnax Core running on the same network. Make sure you have a [Core running](https://docs.synnaxlabs.com/reference/core/quick-start) and have the connection parameters on hand.

### Install and run the Driver

Installing the Driver is as simple as opening an SSH connection to the cRIO and running the following command:

```bash
curl -LO https://github.com/synnaxlabs/synnax/releases/download/driver/v0.58.2/install-driver-nilinuxrt.sh && chmod +x install-driver-nilinuxrt.sh && ./install-driver-nilinuxrt.sh
```

This will download, install, and start the Driver. Once the Driver is installed, we’ll need to configure it to connect to your Core.

**Linux**

> The Driver requires Ubuntu 24.04 LTS or later (glibc 2.39+). Ubuntu 22.04 reaches end of standard support in April 2027.

### Install and run the Driver

To install the Synnax Driver on a Linux distribution, run the following command to download the latest binary:

```bash
curl -LO https://github.com/synnaxlabs/synnax/releases/download/driver/v0.58.2/synnax-driver-v0.58.2-linux
```

We recommend you move the binary into a directory that is in your `PATH`. Most of our users use `/usr/local/bin`:

```bash
sudo mv synnax-driver-v0.58.2-linux /usr/local/bin/synnax-driver
```

Next, give execution permissions to the binary:

```bash
chmod +x /usr/local/bin/synnax-driver
```

You may need to use `sudo` to run the above command if you do not have the necessary permissions.

If running `synnax-driver` returns “command not found”, make sure the directory you chose is on your `PATH`.

Then install and start the Driver as a systemd service:

```bash
sudo synnax-driver install
sudo synnax-driver start
```

This creates a `synnax` system user and registers the `synnax-driver` service.

To verify that the installation was successful, run:

```bash
synnax-driver version
```

You should see the following output:

```text
Synnax Driver v0.58.2
```

**Windows**

### Install and run the Driver

Download the latest Synnax Driver executable for Windows:

```powershell
Invoke-WebRequest -Uri "https://github.com/synnaxlabs/synnax/releases/download/driver/v0.58.2/synnax-driver-v0.58.2-windows.exe" -OutFile "synnax-driver.exe"
```

After downloading, move the `synnax-driver.exe` file to a location on your system, such as `C:\Program Files\Synnax\`.

To make the Driver accessible from any command prompt, add the directory to your system’s `PATH`:

1. Open the Start menu and search for “Environment Variables”
2. Click “Edit the system environment variables”
3. Click the “Environment Variables” button
4. Under “System variables”, find and select “Path”, then click “Edit”
5. Click “New” and add the directory containing `synnax-driver.exe`
6. Click “OK” to save

To verify that the installation was successful, open a new PowerShell terminal and run:

```powershell
synnax-driver version
```

The Driver runs in the foreground on Windows. Start it with:

```powershell
synnax-driver start --standalone
```

**macOS**

### Install and run the Driver

To install the Synnax Driver on macOS, run the following command to download the latest binary:

```bash
curl -LO https://github.com/synnaxlabs/synnax/releases/download/driver/v0.58.2/synnax-driver-v0.58.2-macos
```

We recommend you move the binary into a directory that is in your `PATH`. Most of our users use `/usr/local/bin`:

```bash
sudo mv synnax-driver-v0.58.2-macos /usr/local/bin/synnax-driver
```

Next, give execution permissions to the binary:

```bash
chmod +x /usr/local/bin/synnax-driver
```

You may need to use `sudo` to run the above command if you do not have the necessary permissions.

If running `synnax-driver` returns “command not found”, make sure the directory you chose is on your `PATH`.

To verify that the installation was successful, run:

```bash
synnax-driver version
```

You should see the following output:

```text
Synnax Driver v0.58.2
```

The Driver runs in the foreground on macOS. Start it with:

```bash
synnax-driver start --standalone
```

## Step 2 Connect to the Synnax Core

To connect to a Core, you’ll need to know the Core’s IP address, port, username, and password. Then run the `synnax-driver login` command, with `sudo` on Linux:

```bash
synnax-driver login
```

This will prompt you to enter the Core’s connection parameters. Once you’ve entered the parameters, the Driver will automatically connect to the Core. Here’s an example of the output:

```plaintext
synnax-driver login
host (default: localhost): 10.0.0.45
port (default: 9090): 9090
username: synnax
password:
I20250318 04:57:06.681439 25261 login.cpp:47] connecting to Synnax at 10.0.0.45:9090
I20250318 04:57:06.792840 25261 login.cpp:53] successfully logged in!
I20250318 04:57:06.793918 25261 login.cpp:59] credentials saved successfully
```

## Step 3 Check the Driver status

As a final step, you can check the Driver’s status by running the `synnax-driver status` command:

```bash
synnax-driver status
```

This will print the Driver’s status to the console. Here’s an example of the output:

```plaintext
I20250318 05:07:04.312907  5935 daemon_nilinuxrt.cpp:490] Checking service status
I20250318 05:07:04.346398  5937 version.cpp:21] Synnax Driver v0.39.0 (2025-03-16 00:08:18)
Synnax Driver is running (PID: 28191)
```

On Windows and macOS the Driver runs in the foreground, so its terminal output is its status.

## Configuration methods

In addition to using the `synnax-driver login` command, the Synnax Driver also allows you to configure parameters for the Driver via a configuration file and/or environment variables.

### Precedence

The precedence of the different configuration methods is as follows, with earlier methods taking precedence over later ones:

1. Command line arguments (Highest)
2. Environment variables
3. Configuration file
4. Parameters passed to the `synnax-driver login` command
5. Internal defaults (Lowest)

### Configuration file

The Synnax Driver can optionally read connection parameters from a JSON configuration file with the following format:

```json
{
  // Connection parameters
  "connection": {
    // The host of the Synnax Core.
    "host": "localhost",
    // The port of the Synnax Core.
    "port": 9090,
    // The username to use when logging in to the Synnax Core.
    "username": "synnax",
    // The password to use when logging in to the Synnax Core.
    "password": "password",
    // The path to the CA certificate file to use when connecting
    // to the Synnax Core. This is only required if the Core
    // is configured to use TLS.
    "ca_cert_file": "/path/to/ca.crt",
    // The path to the client certificate file to use when connecting
    // to the Synnax Core. This is only required when the Core is
    // configured to use TLS and client certificates for authentication.
    "client_cert_file": "/path/to/client.crt",
    // The path to the client key file to use when connecting to the
    // Synnax Core. This is only required when the Core is configured
    // to use TLS and client certificates for authentication.
    "client_key_file": "/path/to/client.key"
  },
  "timing": {
    // Enable automatic skew correction for the Driver.
    "correct_skew": true
  },
  "manager": {
    // Duration in seconds before reporting stuck task operations.
    "op_timeout": 60,
    // Interval in seconds between task timeout checks.
    "poll_interval": 1,
    // Maximum time in seconds to wait for task workers during shutdown.
    "shutdown_timeout": 30,
    // Number of worker threads for task operations (1-64).
    "worker_count": 4
  },
  // List of device integrations to enable (overrides defaults).
  "enable_integrations": ["arc", "ethercat", "http", "labjack", "modbus", "ni", "opc"],
  // List of device integrations to disable.
  "disable_integrations": []
}
```

### Environment variables

The Synnax Driver also supports setting connection parameters via environment variables.

```bash
# The host of the Synnax Core.
export SYNNAX_DRIVER_HOST=localhost
# The port of the Synnax Core.
export SYNNAX_DRIVER_PORT=9090
# The username to use when logging in to the Synnax Core.
export SYNNAX_DRIVER_USERNAME=synnax
# The password to use when logging in to the Synnax Core.
export SYNNAX_DRIVER_PASSWORD=password
# The path to the CA certificate file to use when
# connecting to the Synnax Core. This is only required
# if the Core is configured to use TLS.
export SYNNAX_DRIVER_CA_CERT_FILE=/path/to/ca.crt
# The path to the client certificate file to use when
# connecting to the Synnax Core. This is only required when
# the Core is configured to use TLS and client certificates
# for authentication.
export SYNNAX_DRIVER_CLIENT_CERT_FILE=/path/to/client.crt
# The path to the client key file to use when connecting to
# the Synnax Core. This is only required when the Core is
# configured to use TLS and client certificates for authentication.
export SYNNAX_DRIVER_CLIENT_KEY_FILE=/path/to/client.key
# Enable automatic clock skew correction for the Driver.
export SYNNAX_DRIVER_CORRECT_SKEW=true
# Duration in seconds before reporting stuck task operations.
export SYNNAX_DRIVER_OP_TIMEOUT=60
# Interval in seconds between task timeout checks.
export SYNNAX_DRIVER_POLL_INTERVAL=1
# Maximum time in seconds to wait for task workers during shutdown.
export SYNNAX_DRIVER_SHUTDOWN_TIMEOUT=30
# Number of worker threads for task operations (1-64).
export SYNNAX_DRIVER_WORKER_COUNT=4
# Comma-separated list of device integrations to enable.
export SYNNAX_DRIVER_ENABLE_INTEGRATIONS=labjack,ni,opc
# Comma-separated list of device integrations to disable.
export SYNNAX_DRIVER_DISABLE_INTEGRATIONS=modbus
```

## CLI reference

The service commands (`install`, `uninstall`, `stop`, `restart`, `status`, and `logs`) are only available on Linux and NI Linux Real-Time. On Linux, run them with `sudo`. On Windows and macOS, run the Driver in the foreground with `synnax-driver start --standalone` and stop it with Ctrl+C.

### Start

The `start` command starts the installed Driver service. With the `--standalone` flag, it runs the Driver in the foreground, which is the only mode on Windows and macOS.

#### Example usage

```bash
synnax-driver start
```

To run in the foreground instead:

```bash
synnax-driver start --standalone
```

#### Flags

| Flag                     | Default         | Description                                                                                                           |
| ------------------------ | --------------- | --------------------------------------------------------------------------------------------------------------------- |
| `--standalone/-s`        | `false`         | Run the Driver directly within the terminal process.                                                                  |
| `--config/-c`            | `"config.json"` | The path to the configuration file to use for the Driver.                                                             |
| `--debug`                | `false`         | Enable debug logging.                                                                                                 |
| `--host`                 | `"localhost"`   | The host of the Synnax Core.                                                                                          |
| `--port`                 | `9090`          | The port of the Synnax Core.                                                                                          |
| `--username`             | `"synnax"`      | The username to use when logging in to the Synnax Core.                                                               |
| `--password`             | `"seldon"`      | The password to use when logging in to the Synnax Core.                                                               |
| `--ca-cert-file`         | `""`            | The path to the CA certificate file to use when connecting to the Synnax Core.                                        |
| `--client-cert-file`     | `""`            | The path to the client certificate file to use when connecting to the Synnax Core.                                    |
| `--client-key-file`      | `""`            | The path to the client key file to use when connecting to the Synnax Core.                                            |
| `--correct-skew`         | `true`          | Enable automatic clock skew correction for the Driver.                                                                |
| `--op-timeout`           | `60`            | Duration in seconds before reporting stuck task operations. Useful for debugging tasks that may be blocking.          |
| `--poll-interval`        | `1`             | Interval in seconds between task timeout checks.                                                                      |
| `--shutdown-timeout`     | `30`            | Maximum time in seconds to wait for task workers during shutdown. After this timeout, stuck workers will be detached. |
| `--worker-count`         | `4`             | Number of worker threads for task operations. Valid range is 1-64.                                                    |
| `--enable-integrations`  | `[]`            | Comma-separated list of device integrations to enable. Options: arc, ethercat, http, labjack, modbus, ni, opc.        |
| `--disable-integrations` | `[]`            | Comma-separated list of device integrations to disable. Options: arc, ethercat, http, labjack, modbus, ni, opc.       |

### Stop

The `stop` command stops the Driver service. If the Driver is running in the foreground, press Ctrl+C instead.

#### Example usage

```bash
synnax-driver stop
```

### Restart

The `restart` command restarts the Driver. This is equivalent to stopping and then starting the Driver.

#### Example usage

```bash
synnax-driver restart
```

### Login

The `login` command logs in to a Synnax Core. On Linux, run it with `sudo`. If the Driver is already running, restart it to apply the new credentials.

#### Example usage

```bash
synnax-driver login
```

This will prompt you to enter the Core’s connection parameters. Once you’ve entered the parameters, the Driver will automatically connect to the Core. Here’s an example of the output:

```plaintext
synnax-driver login
host (default: localhost): 10.0.0.45
port (default: 9090): 9090
username: synnax
password:
```

### Clear

The `clear` command clears connection parameters configured through the `login` command. On Linux, run it with `sudo`.

#### Example usage

```bash
synnax-driver clear
```

### Status

The `status` command prints the Driver’s status to the console.

#### Example usage

```bash
synnax-driver status
```

### Uninstall

The `uninstall` command removes the service. The binary and the `synnax` user are kept. On Windows and macOS, delete the binary instead.

#### Example usage

```bash
synnax-driver uninstall
```

### Logs

The `logs` command prints the Driver’s logs to the console.

#### Example usage

```bash
synnax-driver logs
```

### Version

The `version` command prints the Driver’s version to the console.

#### Example usage

```bash
synnax-driver version
```