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: ```cmd 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listen)`
= "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](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#configuration-files). See [Serve multiple listeners](https://docs.synnaxlabs.com/reference/enterprise/listeners). Env `SYNNAX_LISTEN` * [`--data`, `-d`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#data)` = "synnax-data"` The folder where the Core keeps its data. Env `SYNNAX_DATA` * [`--verbose`, `-v`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#verbose) Sets the log level to debug. Env `SYNNAX_VERBOSE` * [`--insecure`, `-i`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#insecure) Turns off TLS. Users still log in. Do not use it in production. Env `SYNNAX_INSECURE` * [`--fips`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#mem) 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#help) Prints the help message for the `start` command. * [`--config`, `-c`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#config)` = "/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](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#configuration-files). The Core ignores a file that is missing or cannot be read, with no message. * [`--auto-cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#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](https://docs.synnaxlabs.com/reference/enterprise/tls#use-a-self-signed-certificate). Env `SYNNAX_AUTO_CERT` * [`--certs-dir`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#certs-dir)` = "/usr/local/synnax/certs"` The folder that holds the TLS certificates of the Core. Env `SYNNAX_CERTS_DIR` * [`--ca-cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#ca-cert)` = "ca.crt"` The CA certificate file, relative to `--certs-dir`. Optional: the Core starts without it. Env `SYNNAX_CA_CERT` * [`--ca-key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#ca-key)` = "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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#node-cert)` = "node.crt"` The certificate file of the Core, relative to `--certs-dir`. Env `SYNNAX_NODE_CERT` * [`--node-key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#node-key)` = "node.key"` The key file of the Core, relative to `--certs-dir`. Env `SYNNAX_NODE_KEY` * [`--username`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#username)` = "synnax"` The username of the root user. The Core applies it at every start. See [the root user](https://docs.synnaxlabs.com/reference/enterprise/users#the-root-user). Env `SYNNAX_USERNAME` * [`--password`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#password)` = "seldon"` The password of the root user. At every start, the Core sets the root password to this value. See [the root user](https://docs.synnaxlabs.com/reference/enterprise/users#the-root-user). Env `SYNNAX_PASSWORD` * [`--license-key`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#license-key)`` 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](https://docs.synnaxlabs.com/reference/enterprise/license). Env `SYNNAX_LICENSE_KEY` * [`--license-file`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#license-file)`` 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](https://docs.synnaxlabs.com/reference/enterprise/license#activate-at-start). Env `SYNNAX_LICENSE_FILE` * [`--debug`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#session-idle-timeout)` = "168h"` Ends a login session after this long with no request from its client. Env `SYNNAX_SESSION_IDLE_TIMEOUT` * [`--slow-consumer-timeout`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#slow-consumer-timeout)` = "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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#no-driver) Disables the Driver embedded in the Core. Use it to run Synnax without device integrations. Env `SYNNAX_NO_DRIVER` * [`--no-update-backup`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#no-update-backup) 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](https://docs.synnaxlabs.com/reference/enterprise/upgrade#when-an-update-fails). Env `SYNNAX_NO_UPDATE_BACKUP` * [`--stop-on-stdin-close`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#disable-integrations)`` 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#enable-integrations)`` 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-op-timeout)` = "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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-poll-interval)` = "1s"` The time between task timeout checks in the embedded Driver. Env `SYNNAX_TASK_POLL_INTERVAL` * [`--task-shutdown-timeout`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-shutdown-timeout)` = "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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#task-worker-count)` = 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-path)` = "./synnax-logs/synnax.log"` The file where the Core writes its logs. Env `SYNNAX_LOG_FILE_PATH` * [`--log-file-max-size`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-max-size)` = 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-max-backups)` = 5` The number of old log files to keep before the Core deletes them. Env `SYNNAX_LOG_FILE_MAX_BACKUPS` * [`--log-file-max-age`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-max-age)` = 30` The number of days to keep old log files before the Core deletes them. Env `SYNNAX_LOG_FILE_MAX_AGE` * [`--log-file-compress`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#log-file-compress) Compresses old log files on disk. Env `SYNNAX_LOG_FILE_COMPRESS` * [`--disable-channel-name-validation`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#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: **JSON** ```json { "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 } ``` **YAML** ```yaml 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 ``` **TOML** ```toml 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](https://docs.synnaxlabs.com/reference/enterprise/listeners). ```yaml 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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-address)\* Required The `host:port` the listener binds to. Unique across listeners. * [`cert.source`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-cert-source) The certificate source: `file`, `auto`, or `tailscale`. Required unless the Core starts with `--insecure`. See [Certificate sources](https://docs.synnaxlabs.com/reference/enterprise/listeners#certificate-sources). * [`cert.cert`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-cert-key) For a `file` source, the path to the PEM private key. * [`advertise`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-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`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-name) An optional label. The Core does not use it. * [`loopback`](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#listener-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`. ```bash 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. ```bash synnax cert node synnax.example.com ``` ## Update The `update` command updates the Core to a new version. Run it as an administrator: ```bash 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`: ```bash 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](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#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](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#service), or `synnax-data` when there is no service. See [Go back to an earlier version](https://docs.synnaxlabs.com/reference/enterprise/upgrade#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: ```bash 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: ```bash 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: ```bash synnax update retry ``` See [When an update fails](https://docs.synnaxlabs.com/reference/enterprise/upgrade#when-an-update-fails). ## Version The `version` command, or `synnax --version`, prints the version of the Core: ```bash synnax version ``` ```text 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](https://docs.synnaxlabs.com/reference/enterprise/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](https://docs.synnaxlabs.com/reference/enterprise/cli-reference#exit-codes) 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. ```bash 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. ```bash synnax service uninstall ``` ### service start Starts the service. ```bash synnax service start ``` ### service stop Stops the service and waits until the Core exits. ```bash 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. ```bash synnax service status ```