EasyXrayEnvironment Variables
Complete reference for EasyXray's EASYXRAY_* environment variables — database, panel, logging, memory, node token encryption, and the tunnel health monitor.
EasyXray reads its runtime configuration from EASYXRAY_* environment variables. On a
script install the installer writes them to the service environment file
(/etc/default/easyxray, or /etc/conf.d/easyxray / /etc/sysconfig/easyxray depending on
the distro); for Docker you set them in docker-compose.yml or docker run -e.
Defaults are sensible — set only what you need to change, then restart:
systemctl restart easyxray.
Database
| Variable | Default | Description |
|---|---|---|
EASYXRAY_DB_TYPE | sqlite | Backend: sqlite, or postgres (also accepts postgresql / pg). |
EASYXRAY_DB_FOLDER | /etc/easyxray | Folder for the SQLite database file (EasyXray.db). |
EASYXRAY_DB_DSN | — | PostgreSQL connection string (used when EASYXRAY_DB_TYPE=postgres). |
EASYXRAY_DB_MAX_OPEN_CONNS | — | Max open connections in the PostgreSQL pool. |
EASYXRAY_DB_MAX_IDLE_CONNS | — | Max idle connections in the PostgreSQL pool. |
The default SQLite database path is /etc/easyxray/EasyXray.db. See
Database for the SQLite ↔ PostgreSQL details.
Panel
| Variable | Default | Description |
|---|---|---|
EASYXRAY_PORT | — | Override the panel port (1–65535). Takes precedence over the stored setting. |
EASYXRAY_INIT_WEB_BASE_PATH | / | Initial web base path on first launch (e.g. /mypanel). |
EASYXRAY_ENABLE_FAIL2BAN | true | Enable Fail2ban-based IP-limit enforcement. |
EASYXRAY_SKIP_HSTS | false | Skip the HSTS header — set true when TLS is terminated by a reverse proxy. |
Node token encryption
Node API bearer tokens — and the stored PIA token — are kept in plaintext by
default. Encryption at rest is opt-in and fails closed: with any mode other than
off, the panel refuses to start unless it can load a key.
| Variable | Default | Description |
|---|---|---|
NODE_TOKEN_ENCRYPTION | off | off, migration (reads accept plaintext or ciphertext, writes encrypt), or required (same writes, startup fails without a key). Note the missing EASYXRAY_ prefix. |
EASYXRAY_NODE_TOKEN_KEY_FILE | /etc/easyxray/node_token_key.json | JSON keyring, mode 0600 or stricter (not checked on Windows, where NTFS permissions protect it). Loaded first. |
EASYXRAY_NODE_TOKEN_KEY | — | A single base64 32-byte key, read only when the key file fails to load. Its key id is fixed to env, so it cannot rotate. |
The key file names the active key plus every older key still needed to decrypt:
{ "active": "k1", "keys": { "k1": "<base64 32-byte key>" } }Generate a key with openssl rand -base64 32; keys are never accepted as
command-line arguments. After enabling a mode, re-encrypt the rows already in
the database under the active key:
easyxray encrypt-tokensThat covers node rows; the PIA token is re-encrypted the next time it is read.
To rotate, add the new key to keys, point active at it, keep the old key for
decryption, and run easyxray encrypt-tokens again.
Logging & binaries
| Variable | Default | Description |
|---|---|---|
EASYXRAY_LOG_LEVEL | info | debug, info, notice, warning, or error. |
EASYXRAY_DEBUG | false | Debug mode (forces log level to debug). |
EASYXRAY_LOG_FOLDER | /var/log/easyxray | Log output directory. |
EASYXRAY_BIN_FOLDER | bin | Folder for the Xray-core binary and geosite/geoip files. |
Memory & profiling
The panel keeps memory low via GOGC and periodic releases. These are advanced
knobs — leave them unset unless you're tuning a constrained host.
| Variable | Default | Description |
|---|---|---|
EASYXRAY_GOGC | — | Go GC target percentage; lower = less RAM, slightly more CPU. |
EASYXRAY_MEMORY_RELEASE_INTERVAL | — | Minutes between FreeOSMemory calls; 0 disables. |
EASYXRAY_MEMORY_LIMIT | — | Go soft memory limit in MiB. |
GOMEMLIMIT | — | Go-syntax soft limit (e.g. 400MiB); takes precedence over above. |
EASYXRAY_PPROF | false | Expose pprof profiling on 127.0.0.1:6060. |
Xray
| Variable | Default | Description |
|---|---|---|
XRAY_VMESS_AEAD_FORCED | false | Force VMess AEAD. |
Tunnel health monitor
Optional watchdog: it probes a URL (optionally through a local Xray inbound) and restarts Xray after repeated failures. A restart drops all connected clients, so enable it deliberately.
| Variable | Default | Description |
|---|---|---|
EASYXRAY_TUNNEL_HEALTH_MONITOR | false | Enable the monitor. |
EASYXRAY_TUNNEL_HEALTH_PROXY | — | Proxy to send the probe through, e.g. socks5://127.0.0.1:1080. Empty = only checks host connectivity. |
EASYXRAY_TUNNEL_HEALTH_URL | https://www.cloudflare.com/cdn-cgi/trace | URL to probe. |
EASYXRAY_TUNNEL_HEALTH_INTERVAL | 30s | Interval between probes. |
EASYXRAY_TUNNEL_HEALTH_TIMEOUT | 10s | Per-probe timeout. |
EASYXRAY_TUNNEL_HEALTH_FAILURES | 3 | Consecutive failures before a restart. |
EASYXRAY_TUNNEL_HEALTH_COOLDOWN | 5m | Minimum delay between restarts. |
Unattended install
| Variable | Description |
|---|---|
EASYXRAY_NONINTERACTIVE | Set to 1 (or run with no TTY) to install with zero prompts; generated credentials are written to /etc/easyxray/install-result.env. See Installation. |