OwnNetInfrastructure Ltd.
Subscriber Portal
Documentation

Set up the telemetry agent

The OwnNet agent is a single static binary. This guide takes a Linux host from a bare package to a verified, encrypted telemetry stream in about five minutes.

Requirements

Before you begin, confirm the host meets the baseline:

  • Linux x86_64 or arm64, kernel 4.19 or later
  • Outbound TCP 443 to gw-se.ownnet.club
  • 64 MiB RAM and 512 MiB of buffer disk
  • A tenant ID issued by your OwnNet account manager
Agent versioning. Releases are signature-verified and pinned. The examples below target agent v2.4.x.

Install the agent

Add the repository and install

bash — Debian / Ubuntu
# import the signing key and repository
curl -fsSL https://ownnet.club/packages/ownnet.gpg | sudo gpg --dearmor -o /usr/share/keyrings/ownnet.gpg
echo "deb [signed-by=/usr/share/keyrings/ownnet.gpg] https://ownnet.club/packages stable main" | sudo tee /etc/apt/sources.list.d/ownnet.list
sudo apt update
sudo apt install -y ownnet-agent
bash — RHEL / Rocky / Alma
sudo dnf config-manager --add-repo https://ownnet.club/packages/ownnet.repo
sudo dnf install -y ownnet-agent

Verify the binary: ownnet-agent --version should print 2.4.x.

Provision credentials

Exchange your enrolment secret for a tenant token

The enrolment secret is single-use and valid for 24 hours. Store the resulting token in the system keyring, not in the unit file.

bash — one-time enrolment
# ENROLMENT_SECRET is issued in the subscriber portal
sudo ownnet-agent enroll \
  --tenant "acme-eu-prod" \
  --secret "$ENROLMENT_SECRET" \
  --region "se-stockholm-01"

# -> wrote /etc/ownnet/agent.key (mode 0600)
Rotation. Tokens are valid for 15 minutes and renewed automatically. Revoke a host from the portal — no agent-side action is required.

Write the config

Create /etc/ownnet/agent.toml

/etc/ownnet/agent.toml
[tenant]
id       = "acme-eu-prod"
region   = "se-stockholm-01"

[transport]
endpoint        = "wss://gw-se.ownnet.club/ingest/v1"
tls             = "1.3"
compression     = "zstd"
max_batch_bytes = 4_194_304

[buffer]
path          = "/var/lib/ownnet/buffer"
max_size      = "512MiB"
flush_seconds = 5

[sources.metrics]
enabled  = true
interval = "10s"

[sources.logs]
enabled  = true
paths    = ["/var/log/nginx/access.log"]

[failover]
probe_interval = "5s"
candidates     = ["gw-nl.ownnet.club", "gw-de.ownnet.club"]

Start the service

Enable and start the unit

bash
sudo systemctl enable --now ownnet-agent
sudo systemctl status ownnet-agent --no-pager
bash — Docker alternative
docker run -d --name ownnet-agent --restart unless-stopped \
  -v /etc/ownnet:/etc/ownnet:ro \
  -v /var/lib/ownnet:/var/lib/ownnet \
  ghcr.io/ownnet/agent:2.4

Verify ingestion

Confirm the stream is accepted

bash
ownnet-agent status

# tenant      acme-eu-prod
# gateway     gw-se.ownnet.club (se-stockholm-01)
# transport   connected  TLS 1.3 / H2
# latency     3.2 ms baseline
# buffer      0.4 MiB / 512 MiB
# last ack    10s ago

Ingested series appear in the subscriber portal under Telemetry → Streams within one flush interval.

Troubleshooting

Symptom Likely cause Action
TLS handshake failed Egress proxy terminating TLS Allow direct 443 egress to the gateway hostname
4401 token expired Host clock drift above 60 s Enable NTP on the host, then restart the agent
buffer > 80% Gateway unreachable, replay pending Check ownnet-agent status candidates
tenant not provisioned Enrolment secret unused Re-run ownnet-agent enroll with a fresh secret

Stuck on step 5?

Send the output of ownnet-agent status to our support team.

Open a support request