Reference: files, ports & systemd unit
File paths
| Path | Mode / owner | What it is |
|---|---|---|
/usr/local/bin/atherops-otel-agent | 0755 root | The agent (wrapper) binary. |
/etc/atherops/config.yaml | editable | Your config. See config.yaml. |
/etc/atherops/credentials.json | 0600 root | {"host_id":"…","api_key":"…"}. Do not edit. Delete to force re-registration. |
/etc/atherops/env | 0600 root | systemd EnvironmentFile (token + key + host id). |
/var/lib/atherops/otelcol/<version>/otelcol-contrib | 0755 | A versioned collector binary. |
/var/lib/atherops/otelcol/current | symlink | Points to the active version directory. |
/var/run/atherops/otelcol.yaml | generated | The collector config the agent renders. Do not edit. |
/etc/systemd/system/atherops-otel-agent.service | root | The systemd unit. |
Ports
All collector-internal ports bind to loopback unless noted. The OTLP receivers bind on all interfaces so apps on the host (and only the host network) can reach them.
| Port | Bound on | Purpose |
|---|---|---|
4317 | 0.0.0.0 | OTLP gRPC receiver; apps send spans here. |
4318 | 0.0.0.0 | OTLP HTTP receiver; apps send spans here. |
8889 | 127.0.0.1 | Collector Prometheus exporter; the agent scrapes this locally. |
9599 | 127.0.0.1 | Agent auth-proxy; collector exports OTLP here, the proxy signs and forwards. |
13133 | 127.0.0.1 | Collector health_check; the supervisor probes this. |
All ports are configurable in config.yaml under ports.
The collector speaks plaintext OTLP to the loopback auth-proxy (:9599). The proxy attaches HMAC headers and forwards to AtherOps. The raw API key never crosses the network. See Architecture.
Backend endpoints the agent calls
| Endpoint | Method | Purpose |
|---|---|---|
/api/v1/agents/register | POST | Register with an install token; returns the API key + host id. |
/api/v1/agents/{host_id}/config | GET | Poll remote config. |
/ingest/agents/heartbeat | POST | Heartbeat (carries X-Agent-Version and X-Collector-Version). |
/ingest | POST | Host metrics (Prometheus text). |
/ingest/traces | POST | Traces (OTLP/JSON). |
/ingest/logs/otlp | POST | Logs (OTLP/JSON). |
The detailed request/auth contract for the ingest endpoints is in the advanced Ingest API reference.
systemd unit
The unit installed at /etc/systemd/system/atherops-otel-agent.service:
[Unit]
Description=AtherOps OTel Agent
Documentation=https://docs.atherops.com/otel-agent
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0
[Service]
Type=simple
User=root
EnvironmentFile=-/etc/atherops/env
ExecStart=/usr/local/bin/atherops-otel-agent
Restart=always
RestartSec=5s
StandardOutput=journal
StandardError=journal
SyslogIdentifier=atherops-otel-agent
NoNewPrivileges=yes
PrivateTmp=yes
ProtectSystem=full
ReadWritePaths=/etc/atherops /var/lib/atherops /var/run/atherops
[Install]
WantedBy=multi-user.target
Notable settings:
Restart=always,RestartSec=5s: systemd restarts the agent if it exits. (The agent in turn supervises the collector; see Architecture.)EnvironmentFile=-/etc/atherops/env: the leading-means a missing env file is not an error.- Hardening:
NoNewPrivileges,PrivateTmp,ProtectSystem=full, and an explicitReadWritePathsallowlist.
Common commands:
systemctl status atherops-otel-agent
systemctl restart atherops-otel-agent
journalctl -u atherops-otel-agent -f