Driver installation

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

The Synnax Driver can run as a separate binary on its own machine. This lets one Synnax deployment integrate data acquisition hardware from many host machines.

Step 1 Installation

Choose your operating system below to see the installation instructions:

NI Linux Real-Time

Linux

Windows

macOS

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 and the NI-DAQmx on CompactRIO guide.

SSH access

The Driver is installed over an SSH connection to the cRIO. You can disable SSH after installation, but keeping it enabled makes updates and management easier.

Network access to a Synnax Core

The Driver must be able to reach a Synnax Core over the network. Make sure you have a Core running and its connection parameters on hand.

Install and run the Driver

Open an SSH connection to the cRIO and run:

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

This downloads, installs, and starts the Driver. Next, connect it to your Core.

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

Download the latest binary:

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

Move the binary into a directory on your PATH. Most of our users use /usr/local/bin:

sudo mv synnax-driver-v0.59.2-linux /usr/local/bin/synnax-driver

Give the binary execute permission. You may need sudo for this command:

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

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

Install and start the Driver as a systemd service:

sudo synnax-driver install
sudo synnax-driver start

The install command copies the binary to /usr/local/bin if it is not already there, creates a synnax system user, and registers the synnax-driver service. It also gives the service real-time permission, and writes the udev rule /etc/udev/rules.d/99-synnax-driver-latency.rules, so that Arc automations get precise timing. After you upgrade the Driver, run sudo synnax-driver install again.

To verify the installation, run:

synnax-driver version

You should see the following output:

Synnax Driver v0.59.2

Install and run the Driver

Download the latest Synnax Driver executable for Windows:

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

Move synnax-driver.exe to a permanent location, such as C:\Program Files\Synnax\.

To run the Driver from any terminal, add that directory to your system’s PATH:

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

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

synnax-driver version

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

synnax-driver start --standalone

Install and run the Driver

Download the latest binary:

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

Move the binary into a directory on your PATH. Most of our users use /usr/local/bin:

sudo mv synnax-driver-v0.59.2-macos /usr/local/bin/synnax-driver

Give the binary execute permission. You may need sudo for this command:

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

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

To verify the installation, run:

synnax-driver version

You should see the following output:

Synnax Driver v0.59.2

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

synnax-driver start --standalone

Step 2 Connect to the Synnax Core

To connect to a Core, you need its address, port, username, and password. Run the synnax-driver login command, with sudo on Linux:

synnax-driver login

The command prompts for the Core’s connection parameters, checks that the Core is reachable, then logs in and saves the credentials:

synnax-driver login
Host [localhost]: 10.0.0.45
Port [9090]: 9090
Secure (Y/N) [N]: N
I20260915 10:12:04.118427 41820 login.cpp:32] connection established.
Username: synnax
Password:
I20260915 10:12:09.601240 41820 login.cpp:43] successfully logged in!
I20260915 10:12:09.602113 41820 login.cpp:48] credentials saved successfully!
I20260915 10:12:09.602150 41820 login.cpp:50] start driver: synnax-driver start -s

Connecting to a secure Core

Answer Y to the Secure prompt when the Core uses TLS. The Driver verifies the Core’s certificate against the operating system’s trust store, so a certificate from a public authority such as Let’s Encrypt needs no further setup. Connect using the host name the certificate was issued for, not an IP address.

A Core started with --auto-cert serves a self-signed certificate. Install its CA certificate on the Driver’s machine by following the installing certificates guide. On a machine where you can’t change the trust store, point the Driver at the CA file through its environment instead. On Linux and NI Linux Real-Time, add the line to the environment file at /etc/synnax/driver.env before you run login:

GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/path/to/ca.crt

The service and login read that file, so the setting applies to the login check and to the service. For a foreground start --standalone, and on Windows and macOS where there is no environment file, export the variable in the shell that runs synnax-driver.

Step 3 Check the Driver status

As a final step, check the Driver’s status:

synnax-driver status

On Linux this prints the systemctl status of the synnax-driver service. On NI Linux Real-Time it prints whether the Driver is running and its process ID:

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

Besides the synnax-driver login command, the Driver reads its configuration from command line flags, environment variables, and a configuration file.

Precedence

Earlier sources override later ones:

Command line arguments
Environment variables
The environment file, on Linux and NI Linux Real-Time
Configuration file
Persisted state, written by synnax-driver login and by the Driver itself
Internal defaults

The persisted state file holds the connection parameters saved by login and the identity of the rack the Driver last attached to. It lives at /var/lib/synnax-driver/persisted-state.json on Linux, %LOCALAPPDATA%\synnax-driver\persisted-state.json on Windows, and ~/Library/Application Support/synnax-driver/persisted-state.json on macOS. Use the --state-file flag to move it.

Environment file

On Linux and NI Linux Real-Time, the service and the login command read /etc/synnax/driver.env and set each KEY=VALUE pair it names. For login, a variable already in your environment wins. The file is optional. Only root can read it, so run login with sudo.

start --standalone does not read the file. For a foreground run, set the variables in your shell:

export GRPC_DEFAULT_SSL_ROOTS_FILE_PATH=/path/to/ca.crt
synnax-driver start --standalone

Configuration file

Pass a JSON file with the --config flag. Every key is optional and has the same meaning as the flag of the same name in the CLI reference. The file must not contain comments.

{
  "connection": {
    "host": "localhost",
    "port": 9090,
    "username": "synnax",
    "password": "password",
    "secure": false
  },
  "timing": {
    "correct_skew": true
  },
  "manager": {
    "op_timeout": 60,
    "poll_interval": 1,
    "shutdown_timeout": 30,
    "worker_count": 4
  },
  "remote_info": {
    "rack_key": 65537,
    "cluster_key": "6f2c7a1e-3b9d-4c58-9e21-0d8f5a7b3c44"
  },
  "integrations": ["arc", "ethercat", "http", "labjack", "modbus", "ni", "opc"]
}

The integrations list replaces the default set. Omit remote_info to let the Driver create a rack on first start and remember it in the persisted state file.

Environment variables

Every configuration key is also readable from an environment variable named SYNNAX_DRIVER_ followed by the key in upper case. Integrations can’t be set from the environment.

The Linux and NI Linux Real-Time service does not inherit your shell. It reads /etc/synnax/driver.env, one KEY=value per line, each time it starts. Lines start with the variable name, with no export. The install command creates the file, owned by root with mode 600, so only root can read the password in it. Edit it with sudo and restart the service after editing it.

# The host of the Synnax Core.
SYNNAX_DRIVER_HOST=localhost
# The port of the Synnax Core.
SYNNAX_DRIVER_PORT=9090
# The username to use when logging in to the Synnax Core.
SYNNAX_DRIVER_USERNAME=synnax
# The password to use when logging in to the Synnax Core.
SYNNAX_DRIVER_PASSWORD=password
# Whether to connect to the Synnax Core over TLS.
SYNNAX_DRIVER_SECURE=false
# Enable automatic clock skew correction for the Driver.
SYNNAX_DRIVER_CORRECT_SKEW=true
# Duration in seconds before reporting stuck task operations.
SYNNAX_DRIVER_OP_TIMEOUT=60
# Interval in seconds between task timeout checks.
SYNNAX_DRIVER_POLL_INTERVAL=1
# Maximum time in seconds to wait for task workers during shutdown.
SYNNAX_DRIVER_SHUTDOWN_TIMEOUT=30
# Number of worker threads for task operations (1-64).
SYNNAX_DRIVER_WORKER_COUNT=4
# The key of an existing rack in the Core to attach to.
SYNNAX_DRIVER_RACK_KEY=65537
# The key of the Core that owns the rack.
SYNNAX_DRIVER_CLUSTER_KEY=6f2c7a1e-3b9d-4c58-9e21-0d8f5a7b3c44

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

synnax-driver start

To run in the foreground instead:

synnax-driver start --standalone

Flags

Flag	Default	Description
`--standalone/-s`	`false`	Run the Driver in the foreground instead of as a service.
`--config`	`""`	The path to the configuration file to use for the Driver. No file is read when unset.
`--state-file`	`""`	The path to the persisted state file. Defaults to a platform-specific location, see Precedence.
`--debug`	`false`	Enable debug logging.
`--no-color`	`false`	Disable color in log output.
`--disable-sig-stop`	`false`	Keep running when the process receives SIGINT or SIGTERM.
`--disable-stdin-stop`	`false`	Stop reading stdin for a `STOP` line. Set this when the Driver runs without a terminal.
`--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.
`--secure`	`false`	Whether to connect to the Synnax Core over TLS. Pass a value, as in `--secure=true`.
`--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.
`--rack-key`	`0`	The key of an existing rack in the Core to attach to.
`--cluster-key`	`""`	The key of the Core that owns the rack.
`--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

synnax-driver stop

Restart

The restart command stops and then starts the Driver service.

Example usage

synnax-driver restart

The login command saves the connection parameters for a Synnax Core. On Linux, run it with sudo. If the Driver is already running, restart it to apply the new credentials.

Example usage

synnax-driver login

The command prompts for the Core’s connection parameters:

synnax-driver login
Host [localhost]: 10.0.0.45
Port [9090]: 9090
Secure (Y/N) [N]: N
Username: synnax
Password:

Clear

The clear command clears the persisted state file: the connection parameters saved by the login command and the cached rack identity. The next start creates a new rack. On Linux, run it with sudo.

Example usage

synnax-driver clear

Status

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

Example usage

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

synnax-driver uninstall

Logs

The logs command streams the Driver’s logs to the console until you press Ctrl+C.

Example usage

synnax-driver logs

Version

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

Example usage

synnax-driver version

Get started

Task basics

Driver installation

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

Step 1 Installation

Prerequisites

Supported hardware and software

NI-DAQmx programming mode

SSH access

Network access to a Synnax Core

Install and run the Driver

Install and run the Driver

Install and run the Driver

Install and run the Driver

Step 2 Connect to the Synnax Core

Connecting to a secure Core

Step 3 Check the Driver status

Configuration methods

Precedence

Environment file

Configuration file

Environment variables

CLI reference

Start

Example usage

Flags

Stop

Example usage

Restart

Example usage

Login

Example usage

Clear

Example usage

Status

Example usage

Uninstall

Example usage

Logs

Example usage

Version

Example usage