Agent Operations

Use this page after installing the Insaion Agent. It covers routine service management, configuration changes, logs, support bundles, updates, and troubleshooting for systemd and Docker deployments.

Service management

Systemd

The agent runs as insaion-agent.service:

sudo systemctl status insaion-agent
sudo systemctl restart insaion-agent
sudo systemctl stop insaion-agent
sudo systemctl start insaion-agent

Docker

Manage the container with standard Docker commands:

# Check status
docker ps -a --filter name=insaion-agent

# Restart, stop, or start
docker restart insaion-agent
docker stop insaion-agent
docker start insaion-agent

Configure the agent

Systemd

Runtime configuration is stored in /etc/default/insaion-agent. Edit the file and restart the service to apply changes:

sudo nano /etc/default/insaion-agent
sudo systemctl restart insaion-agent

Docker

Docker configuration is supplied through environment variables. To make a persistent change, stop and remove the container, then run the command generated by the Add Device wizard again with the updated values:

docker stop insaion-agent
docker rm insaion-agent
# Run the updated docker command from the Add Device wizard.

Removing the container does not remove agent state stored in the mounted /var/lib/insaion-agent host directory.

Common variables

ENROLLMENT_KEY: automatically register the device without manual pairing
ROS_DISTRO: ROS2 distribution sourced before launch
CUSTOM_ROS_SETUP: path to an additional ROS workspace setup script
RMW_IMPLEMENTATION: DDS middleware selection, such as CycloneDDS or Fast DDS
ROS_DOMAIN_ID: ROS domain ID for discovery isolation
ROS_AUTOMATIC_DISCOVERY_RANGE: ROS discovery range
ROS_STATIC_PEERS: static peer list for ROS discovery
ROS_LOCALHOST_ONLY: restrict ROS traffic to localhost when required
FASTRTPS_DEFAULT_PROFILES_FILE: Fast DDS profile path
ROS_DISCOVERY_SERVER: Fast DDS discovery server address
CYCLONEDDS_URI: CycloneDDS configuration URI
ZENOH_ROUTER_CONFIG_URI: Zenoh router configuration location
ZENOH_SESSION_CONFIG_URI: Zenoh session configuration location
ZENOH_ROUTER_CHECK_ATTEMPTS: retry count for Zenoh router availability checks

Logging and diagnostics

The agent uses a standardized log format across its components. Each record includes a timestamp, severity level, and thread identifier. Persistent agent logs also include the source file and line number. Output from managed Telegraf and ReductStore processes is captured in the same stream with a component tag, making events easier to follow in chronological order. For systemd, follow live service logs with:

sudo journalctl -u insaion-agent -f

For Docker, use:

docker logs -f insaion-agent

The agent also keeps rotating logs and recent diagnostic snapshots under /var/lib/insaion-agent/. Mount this directory as persistent storage in Docker to retain diagnostics across container restarts.

Create a support bundle

When reporting an issue, generate a redacted support bundle:

sudo insaion-agent --support-bundle

The command requests a fresh diagnostic snapshot without stopping the running service. It writes a compressed .tar.gz archive to /tmp and prints the full path when complete. Choose a specific output path with:

sudo insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz

The bundle includes available agent and service logs, runtime status, recent failure and shutdown diagnostics, host health information, Telegraf configuration, and ROS2 graph information when ROS2 is enabled. Configuration secrets are replaced with [REDACTED], and device tokens are not included. Review the archive before attaching it to an issue or sending it to Insaion support. For Docker, create the bundle inside the container and copy it to the host:

docker exec insaion-agent insaion-agent --support-bundle --output /tmp/insaion-support.tar.gz
docker cp insaion-agent:/tmp/insaion-support.tar.gz ./insaion-support.tar.gz

Update the agent

Systemd

If the Insaion package repository is still configured, update the agent with the standard system upgrade workflow:

sudo apt update
sudo apt upgrade

This upgrades the agent together with other eligible system packages. The package preserves /etc/default/insaion-agent and the state stored under /var/lib/insaion-agent, then restarts the service after the agent upgrade. You can also re-run the installation command generated by the Add Device wizard. This is useful when you want to update only the agent or restore its package repository configuration. If APT keeps the agent back or reports a Telegraf version conflict, re-run the current installation command to remove package holds created by older installer versions, then run the upgrade again.

Docker

Pull the current image and recreate the container with the same configuration and persistent state mount:

docker stop insaion-agent
docker rm insaion-agent
docker pull ghcr.io/insaion/agent:latest-jazzy
# Run the updated docker command from the Add Device wizard.

Replace latest-jazzy with the image tag used by your deployment.

Troubleshooting

The service or container is not running

For systemd:

sudo systemctl status insaion-agent
sudo journalctl -u insaion-agent --since "30 minutes ago" --no-pager

For Docker:

docker ps -a --filter name=insaion-agent
docker logs insaion-agent --tail 100

The device does not register automatically

Confirm that ENROLLMENT_KEY is present in the systemd configuration:

sudo grep '^ENROLLMENT_KEY=' /etc/default/insaion-agent
sudo systemctl restart insaion-agent

For Docker, verify that the variable was supplied to the container:

docker inspect insaion-agent | grep ENROLLMENT_KEY

If it is missing, recreate the container using the command from the Add Device wizard.

The pairing page is not reachable

Confirm that the agent is running, then test the local endpoint:

curl http://localhost:9090

The pairing page is available only while the device is not registered.

Custom ROS messages are missing

Set CUSTOM_ROS_SETUP to the workspace setup.bash path. For Docker, also mount that workspace into the container at the configured path. Restart or recreate the agent after the change.

DDS settings are not applied

Check the configured middleware variables and verify that referenced files exist:

sudo grep -E 'RMW_IMPLEMENTATION|CYCLONEDDS_URI|FASTRTPS' /etc/default/insaion-agent
ls -la /path/to/dds/config/file

For Docker, confirm that the same paths are mounted inside the container.

Docker state is not persisting

Confirm that /var/lib/insaion-agent is mounted and writable on the host:

docker inspect insaion-agent | grep -A 5 '/var/lib/insaion-agent'
ls -la /var/lib/insaion-agent
sudo touch /var/lib/insaion-agent/test && sudo rm /var/lib/insaion-agent/test

If an issue remains unresolved, create a support bundle and include it with the issue report.

Getting Started

Insaion Agent

Insaion Copilot

Devices

Sites

Monitoring

Alarms

Logs

Settings

Reference

Service management

Systemd

Docker

Configure the agent

Systemd

Docker

Common variables

Logging and diagnostics

Create a support bundle

Update the agent

Systemd

Docker

Troubleshooting

The service or container is not running

The device does not register automatically

The pairing page is not reachable

Custom ROS messages are missing

DDS settings are not applied

Docker state is not persisting

​Service management

​Systemd

​Docker

​Configure the agent

​Systemd

​Docker

​Common variables

​Logging and diagnostics

​Create a support bundle

​Update the agent

​Systemd

​Docker

​Troubleshooting

​The service or container is not running

​The device does not register automatically

​The pairing page is not reachable

​Custom ROS messages are missing

​DDS settings are not applied

​Docker state is not persisting

Service management

Systemd

Docker

Configure the agent

Systemd

Docker

Common variables

Logging and diagnostics

Create a support bundle

Update the agent

Systemd

Docker

Troubleshooting

The service or container is not running

The device does not register automatically

The pairing page is not reachable

Custom ROS messages are missing

DDS settings are not applied

Docker state is not persisting