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

--verbose, -v

Sets the log level to debug.

Env SYNNAX_VERBOSE

--insecure, -i

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

Env SYNNAX_INSECURE

--fips

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

Env SYNNAX_FIPS

--mem, -m

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

--help, -h

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.

--auto-cert

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

--debug

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

--no-driver

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

Env SYNNAX_NO_DRIVER

--stop-on-stdin-close

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

--log-file-compress

Compresses old log files on disk.

Env SYNNAX_LOG_FILE_COMPRESS

--disable-channel-name-validation

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.

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

Version

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

synnax version

Synnax v0.60.0

Service (Windows only)

The service commands run the Core as a Windows service named SynnaxCore. Run them in a terminal as an administrator. For the steps, see Run the Core as a service.

The service starts when Windows starts, unless installed with --auto-start=false. 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 C:\ProgramData\Synnax\config.yaml. 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

On Windows, these flags have different defaults:

• --data -> C:\ProgramData\Synnax\data
• --certs-dir -> C:\ProgramData\Synnax\certs
• --log-file-path -> C:\ProgramData\Synnax\logs\synnax.log

Two flags are only for install:

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

service uninstall

Removes the service. It does not stop a running service, and it does not delete config.yaml. Run synnax service stop first.

synnax service uninstall

service start

Starts the service.

synnax service start

service stop

Stops the service.

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