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:
- Command line flags. See the CLI reference.
- Environment variables.
- A configuration file.
- The state file, which
synnax-driver loginwrites. - 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.
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 600on the file. In Kubernetes,fsGroupwith the defaultfsGroupChangePolicymakes the file readable by the group at each mount. Set the policy toOnRootMismatch, or removefsGroup, then runchmod 600on 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
synnaxuser 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
synnaxuser exists, they give the directory to root and thesynnaxgroup with mode0751. They give the state file to thesynnaxuser with mode0600. They create theopcuadirectory if it is missing and give it to thesynnaxuser with mode0700. - At the default path without a
synnaxuser, such as on macOS, they set a state directory that root owns to0700. They replace a state file that another user owns with a copy that root owns, with mode0600. - At a
--state-filepath on Linux, when asynnaxuser exists,logingives only the state file to thesynnaxuser with mode0600. 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=4To 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 --standaloneConfiguration 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= localhostThe host of the Core.
port= 9090The port of the Core.
api_key= ""The API key of the Driver’s rack. The Driver logs in as that rack.
username= synnaxThe username to log in with once, to create a rack and its API key. Ignored when an API key is set.
password= seldonThe password to log in with once, to create a rack and its API key. Ignored when an API key is set.
secure= falseConnect to the Core over TLS.
correct_skew= trueKeep the timestamps of hardware-timed NI and LabJack reads in step with the clock of the computer.
clock_skew_threshold= 1000000000The 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= 60The 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= 1The number of seconds between two checks for task operations that have not finished.
shutdown_timeout= 30The number of seconds that the Driver waits for task operations when it stops.
worker_count= 4The number of threads that run task operations. Use a value from 1 to 64.
integrations= allThe device integrations to run:
arc,ethercat,http,labjack,modbus,ni, andopc. The default is every integration that the Driver for your platform has. Linux has nolabjack, macOS has noni, and NI Linux RT has nolabjackormodbus.
For a boolean environment variable, use true or false.