v0.61.4
ReferenceEnterpriseStandalone DriverConfigurationEnterprise

Configure a standalone Driver

Set the connection, task, and integration parameters of a standalone Driver with its state file, a configuration file, environment variables, or flags.

A standalone Driver reads its parameters from five sources. A source higher in the list overrides the sources below it:

  1. Command line flags. See the CLI reference.
  2. Environment variables.
  3. A configuration file.
  4. The state file, which synnax-driver login writes.
  5. The defaults.

The parameter flags and the configuration file apply only to synnax-driver start --standalone. The service always starts with the same command. To configure the service, use login and, except on Windows, the environment file. On Linux, run login once, also when the environment file holds the connection: login creates the state file, and the service user cannot.

State file

The state file holds the connection parameters and the API key that login saves. Only its owner and the administrators can read it. On Windows and macOS, while the service is installed, every command uses the path of the computer, so run each command with admin rights. Without the service, commands use the path of the user.

Operating system Path
Linux, NI Linux RT /var/lib/synnax-driver/persisted-state.json
Windows, service C:\ProgramData\synnax-driver\persisted-state.json
Windows %LOCALAPPDATA%\synnax-driver\persisted-state.json
macOS, service /Library/Application Support/synnax-driver/persisted-state.json
macOS ~/Library/Application Support/synnax-driver/persisted-state.json

install moves the login and the OPC UA certificates in the path of the user to the path of the computer, when the path of the computer holds no login yet.

The --state-file flag of start --standalone, login, and clear sets a different path. The service always uses the default path.

On Linux and macOS, the Driver creates a missing state directory with mode 0700 and a missing state file with mode 0600. From Driver 0.61.5, start and clear do not change the mode or owner of a state directory or state file that exists. When root runs start or clear at the default path on Linux and a synnax user exists, they give a state directory that they create to root and the synnax group with mode 0751, and a state file that they create to the synnax user with mode 0600, as install does. start, login, and clear fail when:

  • Other users can read the state file. To fix it, run chmod 600 on the file. In Kubernetes, fsGroup with the default fsGroupChangePolicy makes the file readable by the group at each mount. Set the policy to OnRootMismatch, or remove fsGroup, then run chmod 600 on the file once.
  • A different user owns the state file. The user that runs the Driver must own it. When root runs the Driver, the synnax user can also own it.
  • The state directory or the state file is a symbolic link, such as a file in a mounted Kubernetes Secret.

The Driver does not examine the mode of the state directory. A relative --state-file path starts at the working directory.

Only install and login change the owners and modes of existing paths, and only when root runs them:

  • At the default path on Linux, when a synnax user exists, they give the directory to root and the synnax group with mode 0751. They give the state file to the synnax user with mode 0600. They create the opcua directory if it is missing and give it to the synnax user with mode 0700.
  • At the default path without a synnax user, such as on macOS, they set a state directory that root owns to 0700. They replace a state file that another user owns with a copy that root owns, with mode 0600.
  • At a --state-file path on Linux, when a synnax user exists, login gives only the state file to the synnax user with mode 0600. It does not change its directory.

A root login makes the checks above before it makes these changes. It makes the changes also when a check fails, and then fails.

On macOS without the service, run login without sudo if the Driver runs as your user: a sudo login leaves the state file, and a state directory that it creates, to root, and start fails until you give them back with chown.

From Driver 0.61.0 to 0.61.4, start, login, and clear also change the owners and modes of existing paths at each run. They set the state file to mode 0600 at any path, and at the default path they also change the directory. They replace the values that a setup step, such as an init container, gives these paths.

To remove the saved login, run synnax-driver clear. Run login again before the next start.

Environment variables

The Driver reads each parameter from a variable named SYNNAX_DRIVER_ and the key in upper case. The integrations have no variable.

SYNNAX_DRIVER_HOST=10.0.0.45
SYNNAX_DRIVER_PORT=9090
SYNNAX_DRIVER_API_KEY=syk_...
SYNNAX_DRIVER_SECURE=false
SYNNAX_DRIVER_CORRECT_SKEW=true
SYNNAX_DRIVER_OP_TIMEOUT=60
SYNNAX_DRIVER_POLL_INTERVAL=1
SYNNAX_DRIVER_SHUTDOWN_TIMEOUT=30
SYNNAX_DRIVER_WORKER_COUNT=4

To learn what each parameter does, see Parameters.

Environment file

On Linux, NI Linux Real-Time, and macOS, the service and login read /etc/synnax/driver.env. Write one KEY=value on each line, with no export. login uses the file only for variables such as GRPC_DEFAULT_SSL_ROOTS_FILE_PATH. It does not read the SYNNAX_DRIVER_ variables. On macOS, login reads the file only while the service is installed.

install creates the file. Only root can read it, so edit it and run login as root: with sudo on Linux and macOS, and as admin on NI Linux Real-Time. Restart the service after you edit the file.

start --standalone does not read the file. For a Driver in a terminal, export the variables in the shell:

export SYNNAX_DRIVER_WORKER_COUNT=8
synnax-driver start --standalone

Configuration file

Give a JSON file to start --standalone with the --config flag. Each key is optional. The file cannot hold comments.

{
  "connection": {
    "host": "10.0.0.45",
    "port": 9090,
    "api_key": "syk_...",
    "secure": false
  },
  "timing": {
    "correct_skew": true
  },
  "manager": {
    "op_timeout": 60,
    "poll_interval": 1,
    "shutdown_timeout": 30,
    "worker_count": 4
  },
  "integrations": ["arc", "ethercat", "http", "labjack", "modbus", "ni", "opc"]
}

The integrations list replaces the default list.

A Driver with no API key logs in once with username and password, creates a rack and its API key, and saves the key in the state file. An upgraded Driver that saved a rack before does this at its first start and keeps its rack. If that user cannot create racks, the Driver keeps logging in with the password and tries again at each start. Once a key is saved, the Driver ignores a username and password and logs a warning.

Parameters

host= localhost

The host of the Core.

port= 9090

The port of the Core.

api_key= ""

The API key of the Driver’s rack. The Driver logs in as that rack.

username= synnax

The username to log in with once, to create a rack and its API key. Ignored when an API key is set.

password= seldon

The password to log in with once, to create a rack and its API key. Ignored when an API key is set.

secure= false

Connect to the Core over TLS.

correct_skew= true

Keep the timestamps of hardware-timed NI and LabJack reads in step with the clock of the computer.

clock_skew_threshold= 1000000000

The difference between the clock of the computer and the clock of the Core, in nanoseconds, above which the rack status shows the warning Clock out of sync with the Core. In the configuration file, it goes in connection.

op_timeout= 60

The number of seconds after which a task operation that has not finished, such as a start, gives the task the error “Failed to complete task operation”.

poll_interval= 1

The number of seconds between two checks for task operations that have not finished.

shutdown_timeout= 30

The number of seconds that the Driver waits for task operations when it stops.

worker_count= 4

The number of threads that run task operations. Use a value from 1 to 64.

integrations= all

The device integrations to run: arc, ethercat, http, labjack, modbus, ni, and opc. The default is every integration that the Driver for your platform has. Linux has no labjack, macOS has no ni, and NI Linux RT has no labjack or modbus.

For a boolean environment variable, use true or false.