Running Edge as a Systemd Service

Running Expanso Edge as a systemd service is the recommended approach for production Linux deployments. Systemd handles automatic startup on boot, restarts if the process crashes, and integrates with standard Linux logging tools.

Prerequisites

Before you start, make sure you have:

• A Linux system with systemd (most modern distributions)
• Root or sudo access
• Expanso Edge binary installed (see the Installation guide)
• A bootstrap token from Expanso Cloud

Directory Structure

Expanso Edge uses two main directories on Linux:

/etc/expanso/
├── edge-config.yaml      # Main configuration
└── bootstrap.env         # Bootstrap token (chmod 600)

/var/lib/expanso/
├── .credentials/         # Auto-created after bootstrap
├── buffer/               # Store-and-forward during outages
└── config.d/             # Dynamic config overrides

Directory	Purpose
/etc/expanso/	Configuration files, including the main config and environment file for secure token storage
/var/lib/expanso/	Runtime data: credentials created after bootstrap, offline message buffer, and dynamic configuration overrides

Setup Sequence

Follow these steps to set up Expanso Edge as a systemd service.

Step 1: Create User and Directories

Create a dedicated system user and the required directories:

# Create system user with no login shell
sudo useradd -r -s /bin/false expanso

# Create directories
sudo mkdir -p /etc/expanso /var/lib/expanso

# Set ownership
sudo chown expanso:expanso /var/lib/expanso

Why a Dedicated User?

Using a system user with no login shell improves security by limiting what the edge process can access.

Step 2: Install the Edge Binary

Download and install the binary from GitHub releases:

# Download latest release
curl -L https://github.com/expanso-io/expanso/releases/latest/download/expanso-edge-linux-amd64 \
  -o /tmp/expanso-edge

# Install
chmod +x /tmp/expanso-edge
sudo mv /tmp/expanso-edge /usr/local/bin/

# Verify installation
expanso-edge version

The binary is a single statically-compiled file with no external dependencies.

Step 3: Configure the Bootstrap Token

Store the bootstrap token in an environment file with restricted permissions:

# Create environment file (replace with your actual token)
echo "EXPANSO_EDGE_BOOTSTRAP_TOKEN=ebt_v1_your_token_here" \
  | sudo tee /etc/expanso/bootstrap.env > /dev/null

# Restrict permissions to root only
sudo chmod 600 /etc/expanso/bootstrap.env
sudo chown root:root /etc/expanso/bootstrap.env

Token Security

Bootstrap tokens are single-use, time-limited credentials for initial node registration. Never store them in configuration files or commit them to version control. The environment file approach keeps the token readable only by root, and systemd loads it before starting the service.

Step 4: Run Initial Bootstrap

Register the node with Expanso Cloud:

sudo -u expanso expanso-edge bootstrap --token="$TOKEN"

This creates credentials in /var/lib/expanso/.credentials/ that the service uses for subsequent connections. After bootstrap succeeds, the node receives long-term credentials and no longer needs the bootstrap token.

Step 5: Create the Systemd Service

Create the service file at /etc/systemd/system/expanso-edge.service:

[Unit]
Description=Expanso Edge Node
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=expanso
Group=expanso
EnvironmentFile=-/etc/expanso/bootstrap.env
ExecStart=/usr/local/bin/expanso-edge run \
  --config=/etc/expanso/edge-config.yaml \
  --data-dir=/var/lib/expanso
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Service File Options

• EnvironmentFile=-: The - prefix makes the file optional—if it doesn't exist, systemd won't fail to start the service
• Restart=always: Automatically restarts the service if it exits for any reason
• RestartSec=10: Waits 10 seconds before restarting to avoid rapid restart loops

Step 6: Enable and Start the Service

# Reload systemd to pick up the new service file
sudo systemctl daemon-reload

# Enable the service to start on boot
sudo systemctl enable --now expanso-edge

# Check status
sudo systemctl status expanso-edge

The service will now start automatically on boot and restart if it crashes.

Custom Bootstrap URL

For self-hosted or on-premises control planes, specify a custom bootstrap URL instead of the default Expanso Cloud endpoint.

During initial bootstrap:

expanso-edge bootstrap --token "$TOKEN" --url "https://bootstrap.mycompany.com"

In the run command (for ongoing use):

expanso-edge run --bootstrap-url "https://bootstrap.mycompany.com"

This is useful for air-gapped environments or organizations running their own Expanso control plane.

Viewing Logs

Expanso Edge integrates with journald when running as a systemd service:

Location	Purpose
journalctl -u expanso-edge -f	Primary logs (systemd journal)
/var/log/expanso-edge.log	Optional file output (set in config)
/var/lib/expanso/buffer/	Offline message buffer

View recent logs:

sudo journalctl -u expanso-edge -n 100

Follow logs in real-time:

sudo journalctl -u expanso-edge -f

Filter by time range:

sudo journalctl -u expanso-edge --since "1 hour ago"

Offline Message Buffer

The offline message buffer in /var/lib/expanso/buffer/ stores data when the edge node can't reach its destinations. These files are automatically forwarded when connectivity returns.

Managing the Service

Use standard systemctl commands to manage the edge node:

# Check status
sudo systemctl status expanso-edge

# Restart
sudo systemctl restart expanso-edge

# Stop for maintenance
sudo systemctl stop expanso-edge

# View recent logs
sudo journalctl -u expanso-edge -n 50

What's Next?

• Edge Node Configuration: Configure logging, metrics, and performance tuning
• Edge Deployment: Deploy pipelines to your edge nodes
• Monitoring: Set up monitoring and observability