kogutdocs

    Type to search page titles, headings and text.

    Agent

    Install the agent

    Install and connect the agent on a Linux server.

    The agent collects host metrics, containers, and systemd states. It needs no inbound port. The full kogut binary runs it, and so does the smaller agent-only build.

    Get a host token

    1. Set kogut’s public URL to an HTTPS address.
    2. Open Hosts → Add a server, name the host, and click Create install command.
    3. Copy the command. The panel shows the token only once.

    Each token reports only for its host. To replace a lost token, add the server again with the same name; the old token stops working.

    Install the agent

    Linux

    Run the install command on x86_64 or arm64 Linux:

    curl -fsSL https://kogut.dev/install | sudo sh -s -- agent --server https://kogut.acme.com --token <token>

    The script downloads the agent-only build and checks its checksum, installs /usr/local/bin/kogut, writes /etc/kogut/agent.env with mode 0600, and starts kogut-agent.service. Where /usr/local/bin/kogut already runs the server, it installs the full binary instead. Options are in install-script settings.

    Docker

    Use the Compose file in Docker. It runs the ghcr.io/piotrkowski/kogut-agent image, mounts the host read-only, and keeps unsent data in a volume. A containerised agent does not report systemd units or their logs.

    NixOS

    Enable the NixOS module:

    {
	services.kogut-agent = {
		enable = true;
		server = "https://kogut.acme.com";
		tokenFile = "/run/secrets/kogut-agent-token";
	};
}

    The module passes the token as a systemd credential, outside the Nix store. See NixOS.

    Metrics appear under Hosts within a minute. The host’s Discovered list suggests checks for its services.

    Check the service

    For a systemd installation:

    systemctl status kogut-agent
journalctl -u kogut-agent -f

    The service runs as a dynamic user with extra groups for container access and incident logs. See Permissions before changing them.

    Collected data

    The host page shows CPU, memory, swap, load, filesystems, disk and network throughput, temperatures, and containers and systemd services with their states, CPU, and memory. Container and service CPU and memory need cgroup v2, and services also systemd’s CPU and memory accounting; both are the default on current distributions. An agent in a container reports no services. Containers of a service raise alerts of their own.

    History older than raw metrics comes from five-minute and hourly rollups, which keep the 30 largest containers and services of each host. A container keeps its history across restarts and recreation under the same name; a renamed one starts anew. While CPU, memory, a disk, or swap is over its alert limit, the host page says so at the top and, for CPU and memory, names the top containers and services.

    Service states are checked with every sample. The agent sends the list when a state changes and once a minute otherwise; a service’s CPU is its average since the last list. Each service’s highest CPU and memory are shown as far back as raw metrics are kept (host_metrics, a day by default). Restart counts are refreshed every 5 minutes.

    The agent reports OS and hardware details at startup, discovers services hourly, and sends logs only when the server requests them for an incident. See Agent data.

    Configure the connection

    The agent has no config file; the server supplies metric intervals and checks. To start it by hand:

    kogut agent --server https://kogut.acme.com --token <token>

    See the CLI reference and agent environment variables for token files, failover servers, state storage, and certificate pinning.

    Connection and buffering

    The agent validates certificates against its bundled Mozilla root store. Plain HTTP is accepted only for loopback and Tailscale addresses unless explicitly allowed.

    Keep the agent’s state directory writable and persistent. While the server is unreachable, the agent buffers up to one hour or 20 MiB, then drops the oldest data, and sends the buffer with the original timestamps when the connection returns.

    Update agents after the server; see Agent compatibility. An older agent skips check types and options it does not know, runs its other checks, and logs “update the agent” for each skipped check. Older agents also send HTTP checks without newer request headers and report neither container exit codes nor OOM kills.

    Pin the server key

    Set KOGUT_SERVER_KEY to the SHA-256 pin of the certificate’s public key (SubjectPublicKeyInfo). Print the pin from the live certificate:

    echo | openssl s_client -connect kogut.acme.com:443 -servername kogut.acme.com 2>/dev/null \
	| openssl x509 -pubkey -noout \
	| openssl pkey -pubin -outform der \
	| sha256sum | awk '{print "sha256:" $1}'

    Most certificate renewals change the key, and a pinned agent refuses the server until its pin is updated. While switching keys, list the old and new pins separated by a comma. Pinning is checked in addition to certificate validation.

    Remove the agent

    Stop the service and remove its configuration:

    sudo systemctl disable --now kogut-agent
sudo rm /etc/systemd/system/kogut-agent.service /etc/kogut/agent.env
sudo systemctl daemon-reload

    The host’s history stays until retention removes it. Removing the agent does not revoke its token; adding the host again with the same name replaces it.