Skip to main content

Customizing environment file path

Overview​

The Connhex Edge Agent loads its configuration variables from an environment file at startup. By default this file is at /opt/connhex/configs/agent.env. This guide explains how to move it somewhere else.

Service file location​

The Connhex Edge Agent runs as a systemd service. The service file is installed at:

/lib/systemd/system/connhex-edge-agent.service

This file belongs to the agent and is replaced on every update, so it should not be edited directly. To change how the service runs, use a systemd drop in, as described below.

Customizing the environment file path​

Two settings need to agree: the file systemd reads the variables from, and the path the agent itself writes back to when it stores credentials. Both are set in the same drop in.

Step 1: create the drop in​

sudo systemctl edit connhex-edge-agent

This opens an override file at /etc/systemd/system/connhex-edge-agent.service.d/override.conf.

Step 2: set the new path​

Add the following, replacing the path with your own:

[Service]
EnvironmentFile=
EnvironmentFile=-/home/myuser/connhex/custom-config.env
Environment=CONNHEX_AGENT_ENV_FILE=/home/myuser/connhex/custom-config.env

The first, empty EnvironmentFile= is required: without it systemd would keep reading the default file as well, since these directives accumulate.

CONNHEX_AGENT_ENV_FILE tells the agent where to write. If you omit it, the agent will read your file but save credentials back to the default location, and the two will drift apart.

Step 3: reload systemd​

sudo systemctl daemon-reload

Step 4: restart the service​

sudo systemctl restart connhex-edge-agent.service

Step 5: verify the service​

sudo systemctl status connhex-edge-agent.service

You can confirm which file the service is actually reading with:

systemctl show connhex-edge-agent.service --property=EnvironmentFiles

Important notes​

  • Ensure the new environment file exists at the specified path before restarting the service
  • The file holds credentials: keep it readable only by root, with sudo chmod 600 <path>
  • The user running the service must have read permissions for the environment file
  • If using a custom path, make sure it's accessible and won't be accidentally deleted
  • Drop ins survive agent updates, whereas edits to the service file itself would be overwritten

Troubleshooting​

If the service fails to start after changing the environment file path:

  1. Check the service logs:

    sudo journalctl -u connhex-edge-agent.service -n 50

  2. Verify the file exists and has correct permissions:

    ls -la /path/to/your/agent.env

  3. Confirm the override is in effect:

    systemctl show connhex-edge-agent.service --property=EnvironmentFiles

  4. Ensure the systemd configuration was reloaded after editing

  5. Double-check the syntax in the drop in file