Environment variables

Variables the CLI and the agent read - for unattended enrolment, for moving the agent's files, and for reproducing faults.

Every variable starts with SX_. There are two kinds, read by different processes, and which process reads a variable decides where you have to set it - the part people get wrong. The precedence note at the end of this page has the details.

Flag variables carry the value of a command-line flag: SX_ and the flag name in capitals, with underscores for dashes, so --enrollment-key becomes SX_ENROLLMENT_KEY. The command you run reads them, so set them on that command.
Agent variables change how the agent itself behaves. Only the agent reads them, so they have to be in the environment of its system service.

Flag variables

Variable	Read by	Purpose
`SX_ENROLLMENT_KEY`	`start`, `enroll`	The enrollment key, as `--enrollment-key`. Unlike the flag, it does not show up in the process list
`SX_ENROLLMENT_KEY_FILE`	`start`, `enroll`	A file that holds the key, as `--enrollment-key-file`
`SX_HOSTNAME`	`start`, `enroll`	The name the device appears under, as `--hostname`
`SX_LOG_LEVEL`	most commands, and the agent	The log level, as `--log-level`. In the service's environment it sets the level the agent logs at
`SX_` and any flag of `start`	`start` only	For example `SX_DISABLE_DNS=true`. Like the flags, they only count when `start` runs on a disconnected device: on a connected device, `start` changes nothing. To change a setting there, use `sxaccess stop && SX_DISABLE_DNS=true sxaccess start`. Run it as one line: a connection that goes through SXAccess, such as an SSH session to this machine, drops until `start` has finished. It does not work in a session opened with `sxaccess shell`: stopping the agent closes that session and ends the command, so use the console or an OpenSSH session. `SX_PROFILE` is an exception: like `--profile`, it makes `start` reconnect with that identity, even on a connected device. `SX_TENANT=<organization-id>` only counts when the device enrols. `enroll` reads none of these, so `SX_NO_BROWSER`, `SX_PROFILE` and `SX_TENANT` do nothing there
`SX_MANAGEMENT_URL`	`start`, `enroll`	The management service. Its address is built in: set this only when support asks you to

Agent variables

Only the agent reads these, so setting one in your shell or in front of a sxaccess command does nothing: put it in the service's environment as shown below. Most are for reproducing a fault or for an unusual host, not for permanent configuration.

Variable	Effect
`SX_STATE_ROOT`	The folder for the agent's keys, identities and state, by default `/var/lib/sxaccess`. The device's keys live there: pointed at an empty folder, the agent creates new ones, and the next sign-in adds a new device
`SX_DNS_STATE_PATH`	One fixed file, shared by every identity, for the record of system changes the agent undoes after a crash: DNS, routes, firewall rules and the network selection. See What the agent has stored
`SX_RESOLV_RECOVERY_PATH`	Linux. Where the agent keeps a copy of `resolv.conf` so it can restore it after an unclean shutdown; by default `resolv.conf` in the state folder
`SX_RELAY_ONLY`	With `true`, every connection to another device stays on the relay and never moves to a direct path. Use it to reproduce a relayed path on purpose
`SX_USERSPACE_STACK`	With `true`, the agent runs the tunnel in its own network stack, without a tunnel interface, and leaves the system's routes and DNS alone. Programs on the machine then reach your network through the agent's SOCKS5 proxy
`SX_SOCKS_PORT`	The port of that SOCKS5 proxy, by default 1080. It listens on every interface of the machine; `SX_USERSPACE_NO_SOCKS=true` leaves it out. Only with `SX_USERSPACE_STACK=true`
`SX_LOG_LAYOUT`	`json` or `syslog` changes the layout of the agent's log lines; anything else gives plain text
`SX_LOG_FILE_MB`	The size in MB at which the agent starts a new log file, by default 15. It keeps up to ten older files, compressed, for up to 30 days
`SX_DISABLE_PROFILES`	With `true`, identity changes are off on this machine: the agent refuses to add, remove or switch identities, and to save the settings that `start` passes

shell - agent variables: list every one in the same run

sudo sxaccess agent reconfigure --service-env SX_RELAY_ONLY=true,SX_LOG_FILE_MB=50

shell - back to no extra variables

sudo sxaccess agent reconfigure

shell - flag variables go on the command that reads them

SX_ENROLLMENT_KEY='A6160...' sxaccess start

Precedence, and where a variable has to be set

An environment variable overrides the command-line flag, not the other way round. A command parses its flags and then applies every matching SX_ variable over the top, so a variable left in a shell startup file or a unit file quietly wins over the flag you just typed.

Which process reads a variable matters just as much. start reads the variables of the global flags and of its own flags. enroll, info, stop and the other commands that talk to the agent read only those of the global flags, and the sxaccess tenant commands read none. The agent reads the variables of the global flags and the agent variables above, from the environment of its system service, which is not your shell's.

To give the agent an environment, run sudo sxaccess agent reconfigure --service-env with every variable it should have, as shown above. It registers the service again and restarts a running agent, so there is nothing else to restart. Each run replaces the whole environment: a later agent reconfigure without --service-env drops every variable set before. agent install takes the same flag, but only works on a machine where the service is not installed yet.