Enterprise

CLI reference

Commands and flags of the Synnax Core CLI.

The synnax command starts and manages a Synnax Core. This page lists its commands, flags, environment variables, and configuration file keys.

Start

The start command starts the Synnax Core.

Example

Use the -i and -m flags to start a Core in insecure mode with an in-memory data store:

synnax start -l localhost:9090 -im

Flags

You can also set each flag with its environment variable. A flag on the command line takes precedence over its environment variable. In an environment variable, separate list values with spaces, not commas.

--listen, -l<address> = "localhost:9090"

The address that clients and other Cores use to reach this Core. The host must be a name or address they can reach, and the TLS certificate must cover it. The Core binds the port on every network interface. To bind more than one address, each with its own certificate, give a list of listeners in a configuration file. See Serve multiple listeners.

Env SYNNAX_LISTEN

--data, -d<path> = "synnax-data"

The folder where the Core keeps its data.

Env SYNNAX_DATA

Sets the log level to debug.

Env SYNNAX_VERBOSE

Turns off TLS. Users still log in. Do not use it in production.

Env SYNNAX_INSECURE

Restricts password hashing to PBKDF2. The Core refuses passwords stored with another algorithm until an administrator sets them again.

Env SYNNAX_FIPS

Keeps all data in memory. The Core writes nothing to disk, and loses all data when it stops. Use it for tests and development, not for production.

Env SYNNAX_MEM

Prints the help message for the start command.

--config, -c<path> = "/usr/local/synnax/config.yaml"

A JSON, YAML, or TOML file that sets the Core’s configuration in place of flags or environment variables. See Configuration files. The Core ignores a file that is missing or cannot be read, with no message.

Creates a CA and a certificate for the --listen host in --certs-dir, and replaces the certificate when the host changes. See Set up TLS.

Env SYNNAX_AUTO_CERT

--certs-dir<path> = "/usr/local/synnax/certs"

The folder that holds the TLS certificates of the Core.

Env SYNNAX_CERTS_DIR

--ca-cert<path> = "ca.crt"

The CA certificate file, relative to --certs-dir. Optional: the Core starts without it.

Env SYNNAX_CA_CERT

--ca-key<path> = "ca.key"

The CA key file, relative to --certs-dir. --auto-cert uses it to sign the certificate of the Core.

Env SYNNAX_CA_KEY

--node-cert<path> = "node.crt"

The certificate file of the Core, relative to --certs-dir.

Env SYNNAX_NODE_CERT

--node-key<path> = "node.key"

The key file of the Core, relative to --certs-dir.

Env SYNNAX_NODE_KEY

--username<string> = "synnax"

The username of the root user. The Core applies it at every start. See the root user.

Env SYNNAX_USERNAME

--password<string> = "seldon"

The password of the root user. At every start, the Core sets the root password to this value. See the root user.

Env SYNNAX_PASSWORD

--license-key<string>

The license key to activate at start. It shows in the process list, so prefer --license-file or the environment variable. See Activate a license.

Env SYNNAX_LICENSE_KEY

--license-file<path>

A file that holds the license key to activate at start, such as the .lic file from the portal. When --license-key is also set, the key wins. See activate at start.

Env SYNNAX_LICENSE_FILE

Serves a metrics page and profiling routes to every network with no login, and turns on development logging. Do not use it in production. For debug logs, use --verbose.

Env SYNNAX_DEBUG

--session-idle-timeout<duration> = "168h"

Ends a login session after this long with no request from its client.

Env SYNNAX_SESSION_IDLE_TIMEOUT

--slow-consumer-timeout<duration> = "2.5s"

The time after which the Core closes a telemetry streamer that stops receiving messages. You rarely need to change it.

Env SYNNAX_SLOW_CONSUMER_TIMEOUT

Disables the Driver embedded in the Core. Use it to run Synnax without device integrations.

Env SYNNAX_NO_DRIVER

Skips the backup of the metadata before a new version first opens the data, so the Core cannot undo a failed update. Use it only when you snapshot the data folder before each update. The Core still refuses data that a newer Core opened. See When an update fails.

Env SYNNAX_NO_UPDATE_BACKUP

Stops the Core when its standard input closes. A line stop on standard input always stops the Core. Use it when a parent process starts the Core and holds its standard input, so that the Core stops if the parent exits. Do not set it for a Core that runs as a service, because a service has no standard input.

Env SYNNAX_STOP_ON_STDIN_CLOSE

--disable-integrations<list>

The device integrations to disable. All integrations are enabled by default. The options are arc, ethercat, http, labjack, modbus, ni, and opc.

Env SYNNAX_DISABLE_INTEGRATIONS

--enable-integrations<list>

The device integrations to enable, when you want only some of them. All integrations are enabled by default. The options are arc, ethercat, http, labjack, modbus, ni, and opc.

Env SYNNAX_ENABLE_INTEGRATIONS

--task-op-timeout<duration> = "60s"

The time after which the embedded Driver reports a task operation as stuck. Use it to debug tasks that block.

Env SYNNAX_TASK_OP_TIMEOUT

--task-poll-interval<duration> = "1s"

The time between task timeout checks in the embedded Driver.

Env SYNNAX_TASK_POLL_INTERVAL

--task-shutdown-timeout<duration> = "30s"

The longest time the embedded Driver waits for task workers when it shuts down. After this time, it detaches workers that are stuck.

Env SYNNAX_TASK_SHUTDOWN_TIMEOUT

--task-worker-count<int> = 4

The number of worker threads for task operations in the embedded Driver, from 1 to 64.

Env SYNNAX_TASK_WORKER_COUNT

--log-file-path<path> = "./synnax-logs/synnax.log"

The file where the Core writes its logs.

Env SYNNAX_LOG_FILE_PATH

--log-file-max-size<int> = 50

The largest size of a log file, in MB, before the Core starts a new one.

Env SYNNAX_LOG_FILE_MAX_SIZE

--log-file-max-backups<int> = 5

The number of old log files to keep before the Core deletes them.

Env SYNNAX_LOG_FILE_MAX_BACKUPS

--log-file-max-age<int> = 30

The number of days to keep old log files before the Core deletes them.

Env SYNNAX_LOG_FILE_MAX_AGE

Compresses old log files on disk.

Env SYNNAX_LOG_FILE_COMPRESS

Lets channels have any name, including special characters and spaces. By default, a channel name can contain only letters, digits, and underscores, and cannot start with a digit.

Env SYNNAX_DISABLE_CHANNEL_NAME_VALIDATION

Configuration files

The Core also reads a configuration file in JSON, YAML, or TOML. Each key has the name of its flag. Environment variables and flags take precedence over the file.

By default, the Core reads /usr/local/synnax/config.yaml. To use a different file, set --config. The SYNNAX_CONFIG environment variable has no effect.

Example files:

{
  "listen": "localhost:9090",
  "data": "/usr/local/synnax/data",
  "verbose": true,
  "insecure": false,
  "mem": false,
  "certs-dir": "/usr/local/synnax/certs",
  "ca-cert": "ca.crt",
  "node-cert": "node.crt",
  "node-key": "node.key",
  "username": "synnax",
  "password": "seldon",
  "license-file": "/usr/local/synnax/synnax.lic",
  "debug": false,
  "session-idle-timeout": "168h",
  "slow-consumer-timeout": "2.5s",
  "no-driver": false,
  "disable-integrations": [],
  "enable-integrations": [],
  "task-op-timeout": "60s",
  "task-poll-interval": "1s",
  "task-shutdown-timeout": "30s",
  "task-worker-count": 4,
  "log-file-path": "./synnax-logs/synnax.log",
  "log-file-max-size": 50,
  "log-file-max-backups": 5,
  "log-file-max-age": 30,
  "log-file-compress": true,
  "disable-channel-name-validation": false
}

listen: localhost:9090
data: /usr/local/synnax/data
verbose: true
insecure: false
mem: false
certs-dir: /usr/local/synnax/certs
ca-cert: ca.crt
node-cert: node.crt
node-key: node.key
username: synnax
password: seldon
license-file: /usr/local/synnax/synnax.lic
no-driver: false
disable-integrations: []
enable-integrations: []
task-op-timeout: 60s
task-poll-interval: 1s
task-shutdown-timeout: 30s
task-worker-count: 4
log-file-path: ./synnax-logs/synnax.log
log-file-max-size: 50
log-file-max-backups: 5
log-file-max-age: 30
log-file-compress: true
disable-channel-name-validation: false

listen = "localhost:9090"
data = "/usr/local/synnax/data"
verbose = true
insecure = false
mem = false
certs-dir = "/usr/local/synnax/certs"
ca-cert = "ca.crt"
node-cert = "node.crt"
node-key = "node.key"
username = "synnax"
password = "seldon"
license-file = "/usr/local/synnax/synnax.lic"
no-driver = false
disable-integrations = []
enable-integrations = []
task-op-timeout = "60s"
task-poll-interval = "1s"
task-shutdown-timeout = "30s"
task-worker-count = 4
log-file-path = "./synnax-logs/synnax.log"
log-file-max-size = 50
log-file-max-backups = 5
log-file-max-age = 30
log-file-compress = true
disable-channel-name-validation = false

Multiple listeners

The listen key takes a single address, as above, or a list of listeners, each with its own address and certificate. The list works only in a configuration file, and cannot be combined with --auto-cert, --node-cert, or --node-key. See Serve multiple listeners.

listen:
  - address: core01.example.com:9090
    cert:
      source: auto
    advertise: true
  - address: node01.example-tailnet.ts.net:9091
    cert:
      source: tailscale
    name: console

Fields of a listener:

address Required: The host:port the listener binds to. Unique across listeners.
cert.source: The certificate source: file, auto, or tailscale. Required unless the Core starts with --insecure. See Certificate sources.
cert.cert: For a file source, the path to the PEM certificate. If cert and key are both empty, the listener uses the node certificate.
cert.key: For a file source, the path to the PEM private key.
advertise: Marks this listener’s address as the one the embedded Driver connects to. At most one listener may set it; the first listener is advertised if none do.
name: An optional label. The Core does not use it.
loopback: Binds the listener to the loopback interface only, so no other machine can reach it. The address host must be localhost or 127.0.0.1. By default, a listener binds its port on every network interface.

Exit codes

Code	Meaning
0	The Core stopped.
1	The Core failed. A later start can succeed, for example after another process frees the port.
65	The Core refuses its data: a newer Core opened it, a restore did not finish, or an update to this version failed.
78	A flag, a config value, or a certificate is not valid.

After code 65 or 78, the Core fails the same way at each start until you fix the cause.

Cert

The cert commands create the files that --auto-cert creates, without starting the Core. They take --certs-dir, --ca-cert, --ca-key, --node-cert, and --node-key with the same defaults as start, and also:

--key-size -> the key size in bits. Default 2048.
--allow-key-reuse -> lets the CA key sign more than one certificate. Default false.

cert ca

Creates ca.crt and ca.key.

synnax cert ca

cert node

Creates node.crt and node.key for one or more hosts, signed by the CA. It needs the CA files and does not replace node files that exist.

synnax cert node synnax.example.com

Update

The update command updates the Core to a new version. Run it as an administrator:

sudo synnax update 0.61.0

The command downloads the Core for the computer from the Synnax releases and checks its signature. It does not install a file that fails the check. To update without internet access, download the binary on another computer and pass it with --file:

sudo synnax update --file ./synnax-v0.61.0-linux

The command checks that the new Core is for the computer and not older than the installed Core. For a Core service, it stops the service, puts the new binary in place of the old one, and starts the service. It then waits for the new Core to commit the update. If the new Core fails, the command puts the old Core back and starts it. Without a service, it only replaces the binary that runs the command, so stop the Core first and start it after. The old binary stays next to the new one, with an .old extension. When the installed Core is the same version, the command does nothing. It refuses while an update of the data has not finished. For a service, the new binary can also run the command, such as for an update from a Core that has no update command.

--file -> the Core binary to update to, in place of a version.
--timeout -> how long to wait for the new Core to commit the update. Default 10m.

Before a new version first opens the data, the Core backs up its metadata. The subcommands use these backups. Stop the Core first. Without --data, they use the data folder of the Core service, or synnax-data when there is no service. See Go back to an earlier version.

update undo

Restores the backup of the last update, or the named backup, and prints the Core version to run on the data:

synnax update undo
synnax update undo 1793000000-0.60.1

When the .old binary from synnax update is that version, the command also puts it back. Without a name, when the last update is already undone, the command only puts back the .old binary, and refuses when that binary is not the version before the update. For the Linux service, run it with sudo. The command gives the restored files to the owner of the data folder.

update history

Lists the backups, oldest first:

synnax update history

update retry

After a failed update, the Core does not start the failed version on the data. Fix the cause, then run this command, and the next start of that version updates the data again:

synnax update retry

See When an update fails.

Version

The version command, or synnax --version, prints the version of the Core:

synnax version

Synnax v0.60.1

Service

The service commands run the Core as a service on Linux and Windows. Run them as root or as an administrator. For the steps, see Run the Core as a service.

On Linux, the service is the systemd unit synnax, and it runs as the synnax system user. When the Core exits, systemd starts it again after 5 seconds, except after exit code 65 or 78. The service writes its log to the log file and to the journal.

On Windows, the service is named SynnaxCore. When the Core crashes, Windows restarts it after 5 seconds, then 30 seconds, then 60 seconds. The count resets each day. The service writes its log to the log file, not to the Windows Event Log.

service install

Installs the service. It takes every start flag and writes them to a config file. The service reads only that file, and ignores SYNNAX_* environment variables. When the file exists, install does not change it.

synnax service install --listen=synnax.example.com:9090 --auto-cert

These flags have different defaults for a service:

Flag	Linux	Windows
Config file	`/etc/synnax/config.yaml`	`C:\ProgramData\Synnax\config.yaml`
`--data`	`/var/lib/synnax/data`	`C:\ProgramData\Synnax\data`
`--certs-dir`	`/var/lib/synnax/certs`	`C:\ProgramData\Synnax\certs`
`--log-file-path`	`/var/lib/synnax/logs/synnax.log`	`C:\ProgramData\Synnax\logs\synnax.log`

Two flags are only for install:

--auto-start -> start the service when the computer starts. Default true.
--delayed-start -> on Windows, start the service after Windows finishes starting. Default false. With --delayed-start, the service starts automatically even with --auto-start=false.

On Linux, install also creates the synnax system user.

service uninstall

Removes the service. It does not delete the config file. On Windows, it does not stop a running service, so run synnax service stop first. On Linux, it stops the service.

synnax service uninstall

service start

Starts the service.

synnax service start

service stop

Stops the service and waits until the Core exits.

synnax service stop

service status

Shows whether the service is installed and running, its version, its data folder, log file, certificate folder, listen address, and whether it runs with --insecure. When the service is stopped, it also shows the last 10 warnings and errors.

synnax service status

Previous in Standalone Driver

CLI reference

Troubleshooting