How to Use Custom Encryption Keys in Xeams

Why a Custom Encryption Key Matters

Xeams stores several pieces of sensitive information on disk, including credentials. By default these values are protected with a built‑in encryption key that ships inside the product. Because that key is the same in every copy of Xeams, anyone who obtains both the software and your configuration files could, in theory, decrypt those secrets.

A custom encryption key replaces that shared key with one that is unique to your installation and known only to you. Once configured, even if someone gets hold of your configuration files they cannot decrypt the secrets without your key.

Keep a Backup

Store a secure copy of your key or passphrase.
If it is lost, data encrypted with it cannot be recovered.

How It Works

  • You supply a passphrase through an environment variable or a file. Xeams derives an AES key from it.
  • New secrets are encrypted with your key.
  • The passphrase itself is never written into the Xeams configuration. Xeams keeps only a reference to your chosen source, so the secret stays under your control.
  • You may supply a passphrase of any length.

Two ways to provide the key. An environment variable (recommended) keeps the secret out of the file system entirely. A file is also supported, provided you restrict its permissions so that only the account running Xeams can read it. Both are described below.

Method 1 — Environment Variable (Recommended)

Set an environment variable named XEAMS_CUSTOM_KEY_PASSPHRASE to your passphrase. You can change this variable name to any other value of your choice. Xeams reads it automatically at startup. The environment variable must be visible to the account (service) that runs Xeams, and Xeams must be restarted after it is created.

On Windows

Xeams normally runs as a Windows service. Environment variables must therefore be created at the system (machine) level, not just for your interactive login.

Option A — Graphical:
  • Open Start → search for Edit the system environment variables.
  • Click Environment Variables…
  • Under System variables, click New…
  • Variable name: XEAMS_CUSTOM_KEY_PASSPHRASE
  • Variable value: your passphrase
  • Click OK on each dialog.
Option B — Command line (run the Command Prompt as Administrator): 
setx XEAMS_CUSTOM_KEY_PASSPHRASE "your-secret-passphrase" /M
The /M switch writes the variable at the machine level so a service can read it.

Finally, restart Xeams so the service picks up the new variable:
  • Open services.msc, locate the Xeams service, and choose Restart, or
  • run net stop Xeams followed by net start Xeams from an elevated prompt.
A running service does not see a variable created after it started. If a simple service restart does not work, reboot the machine so the service inherits the new system environment.

On Linux

How you set the variable depends on how Xeams is started. Most modern installations use systemd.

Option A — systemd unit file: edit the Xeams service unit (for example /etc/systemd/system/xeams.service) and add an Environment line inside the [Service] section: 
[Service]
Environment="XEAMS_CUSTOM_KEY_PASSPHRASE=your-secret-passphrase"
Option B — systemd EnvironmentFile (keeps the secret out of the unit file). Create a file such as /etc/xeams/xeams.env containing: 
XEAMS_CUSTOM_KEY_PASSPHRASE=your-secret-passphrase
secure it so only root can read it: 
sudo chown root:root /etc/xeams/xeams.env
sudo chmod 600 /etc/xeams/xeams.env
and reference it from the unit file: 
[Service]
EnvironmentFile=/etc/xeams/xeams.env
Then reload systemd and restart Xeams: 
sudo systemctl daemon-reload
sudo systemctl restart xeams
Option C — init / startup script: if Xeams is launched from a shell script, add an export line near the top of that script, before Xeams is started: 
export XEAMS_CUSTOM_KEY_PASSPHRASE="your-secret-passphrase"
then restart the service or the machine.
Placing the passphrase directly in a systemd unit makes it readable by anyone who can read the unit file. For better security, prefer the EnvironmentFile approach with chmod 600 owned by root, or use the file method below.

Method 2 — Key File (with Correct Permissions)

Instead of an environment variable, you can store your passphrase in a plain text file that contains only the passphrase. Point Xeams at it by setting the environment variable XEAMS_CUSTOM_KEY_FILE to the file’s full path, or by entering the path on the Custom Encryption Key page in the Xeams web interface.

The single most important step is to restrict the file’s permissions so that only the account running Xeams can read it.

First, identify the account running Xeams.
  • Linux: check the service unit’s User= directive, or run ps -ef | grep -i xeams and note the owner of the process. Xeams often runs as root or as a dedicated xeams user.
  • Windows: open services.msc, open the Xeams service properties, and look at the Log On tab. It is commonly Local System or a dedicated service account.
On Linux, assuming Xeams runs as user xeams and the file lives at /opt/xeams/config/custom.key: 
sudo chown xeams:xeams /opt/xeams/config/custom.key
sudo chmod 600 /opt/xeams/config/custom.key
chmod 600 grants read/write to the owner only and removes all access for group and other users. Also make sure the containing folder is not world‑readable: 
sudo chmod 700 /opt/xeams/config
On Windows, assuming the file is at C:\Xeams\config\custom.key and the service runs as Local System, remove inherited permissions and grant read access only to the service account and administrators. Run these from an elevated Command Prompt: 
icacls "C:\Xeams\config\custom.key" /inheritance:r
icacls "C:\Xeams\config\custom.key" /grant "SYSTEM:R" "Administrators:R"
If the Xeams service logs on as a dedicated account instead of Local System, grant that account read access in place of SYSTEM: 
icacls "C:\Xeams\config\custom.key" /grant "DOMAIN\XeamsServiceAccount:R"
Xeams reads the secret from your file at startup and never keeps its own copy of it. Only a reference to the file’s location is stored, so your secret remains solely in the file you control.

Configuring and Verifying in Xeams

  • Log in to the Xeams web interface as an administrator and open the Custom Encryption Key page.
  • Enter the name of your environment variable (for example XEAMS_CUSTOM_KEY_PASSPHRASE) or the full path to your key file, then confirm.
  • Once active, the page displays a short fingerprint of the key. This is a non‑reversible identifier — it lets you confirm that the correct key is loaded without ever revealing the key itself.
  • Record the fingerprint. After a restart, or on each server in a cluster, verify that the same fingerprint appears to confirm every instance is using the same key.

Best Practices

  • Prefer an environment variable or a secrets manager over storing the key on disk.
  • If you must use a file, lock down its permissions as shown above and keep it outside any backup that is stored alongside your configuration files.
  • Keep at least one secure, offline backup of the passphrase. Losing it means losing access to any data encrypted with it.
  • Use the fingerprint to verify consistency after restarts and across clustered servers.
  • Never email, chat, or commit the passphrase to source control.