Install on Linux (manual)

Overview#

This page installs the agent as a systemd service, step by step: download and check the binary, create the onagent user, store the token, create the service. You need root access, systemd 235 or later, and the agent's token, copied when you created the agent in Onagre.

1. Download and check the agent#

Read the current version, then download that exact version and its checksum:

VERSION="$(curl -fsSL https://d.onag.re/version)"
curl -fsSLo /tmp/onagent "https://d.onag.re/agent/$VERSION/agent-linux-x64"
echo "$(curl -fsSL "https://d.onag.re/agent/$VERSION/agent-linux-x64.sha256" | cut -d' ' -f1)  /tmp/onagent" | sha256sum -c -

VERSION="$(curl -fsSL https://d.onag.re/version)"
curl -fsSLo /tmp/onagent "https://d.onag.re/agent/$VERSION/agent-linux-arm64"
echo "$(curl -fsSL "https://d.onag.re/agent/$VERSION/agent-linux-arm64.sha256" | cut -d' ' -f1)  /tmp/onagent" | sha256sum -c -

sha256sum must answer OK. Otherwise, do not install the file: download it again. Then check that it runs on this machine — it prints its version, without network or token — and install it:

chmod 0755 /tmp/onagent
DOTNET_BUNDLE_EXTRACT_BASE_DIR=/tmp /tmp/onagent --version
install -m 0755 -o root -g root /tmp/onagent /usr/local/bin/onagent

2. Create the system user#

The agent runs unprivileged, as onagent, without shell nor home directory:

useradd --system --user-group --no-create-home --home-dir /nonexistent --shell /usr/sbin/nologin onagent

3. Store the token#

Keep the token out of the service file, in a file only root can read (systemd reads it before starting the agent as onagent):

install -d -m 0700 /etc/onagent
( umask 077; echo 'TOKEN=<YOUR_TOKEN>' > /etc/onagent/onagent.env )

4. Create the service#

Create /etc/systemd/system/onagent.service:

[Unit]
Description=Onagre Agent
Documentation=https://docs.onagre.io/en/agents/deployment
Wants=network-online.target
After=network-online.target

[Service]
Type=exec
User=onagent
Group=onagent
EnvironmentFile=/etc/onagent/onagent.env
Environment=DOTNET_BUNDLE_EXTRACT_BASE_DIR=/var/cache/onagent
ExecStart=/usr/local/bin/onagent
WorkingDirectory=/
Restart=always
RestartSec=10
RestartPreventExitStatus=78
LimitNOFILE=65535
CacheDirectory=onagent
UMask=0077
StandardOutput=journal
StandardError=journal
SyslogIdentifier=onagent
AmbientCapabilities=CAP_NET_RAW
CapabilityBoundingSet=CAP_NET_RAW
NoNewPrivileges=yes
ProtectSystem=strict
ProtectHome=read-only
PrivateDevices=yes
ProtectKernelTunables=yes
ProtectKernelModules=yes
ProtectKernelLogs=yes
ProtectControlGroups=yes
ProtectClock=yes
ProtectHostname=yes
RestrictSUIDSGID=yes
RestrictRealtime=yes
RestrictNamespaces=yes
LockPersonality=yes
SystemCallArchitectures=native
RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX AF_NETLINK

[Install]
WantedBy=multi-user.target

Then start it, and enable it at boot:

systemctl daemon-reload
systemctl enable --now onagent

5. Check that it is connected#

curl -s http://127.0.0.1:27520/ready

It answers {"status":"Ready"} once the agent is connected — see Health endpoints. In Onagre, the agent shows Connected in Configuration → Agents:

Settings and logs#

Settings are environment variables: add them to /etc/onagent/onagent.env, one NAME=value per line, then systemctl restart onagent. All settings: Agent configuration.

The logs go to the systemd journal:

journalctl -u onagent -f
journalctl -u onagent --since today
journalctl -u onagent -p warning

To keep a log file as well, set LOG=/var/log/onagent/onagent.log and add LogsDirectory=onagent to the service (systemctl edit onagent).

File sensors read files as onagent: for a file only root can read, run setfacl -m u:onagent:r /path/to/file.

Update#

Download and check the new version as in step 1, keep the current binary, replace it, then restart:

install -d -m 0755 /usr/local/lib/onagent
cp /usr/local/bin/onagent /usr/local/lib/onagent/onagent.previous
install -m 0755 -o root -g root /tmp/onagent /usr/local/bin/onagent
systemctl restart onagent
curl -s http://127.0.0.1:27520/ready

If the agent does not get connected again, go back: install -m 0755 /usr/local/lib/onagent/onagent.previous /usr/local/bin/onagent && systemctl restart onagent.

Change the token#

After Revoke and regenerate in Onagre, replace the TOKEN= line of /etc/onagent/onagent.env, then systemctl restart onagent.

Manage the service#