Skip to main content

Configless and auto-discovery

Configless means there is no file you write for the agent to do its job. The monitoring logic (what to watch, where the logs are, which thresholds apply) arrives from the platform as signed definitions. The agent's part is to know the host well enough that the right definitions match on their own.

What the agent discovers​

  • Processes: name, command line, binary path. Command lines are redacted before they leave the host (passwords, tokens and card-like numbers in arguments become ***).
  • Listening ports: TCP and UDP, with the owning process.
  • Installed packages: dpkg, rpm, apk, and Homebrew on macOS.
  • Service units and their state: systemd units, Windows services.
  • Init system: systemd, OpenRC or sysvinit, so a definition can target one init family or any Linux host.
  • Scheduled jobs: cron entries from the system crontab, cron.d, user spools and the cron.hourly through cron.monthly directories.
  • OS identity: distribution and version.
  • IP addresses: the primary address (found by a routing lookup, no packets sent) and every interface address. The public address is stamped by the platform from the connection itself, so the agent never asks a third-party "what is my IP" service.
  • Capabilities: what the kernel allows (eBPF, live process profiling), so deep probes activate only where they can run.

On Windows the same facts come from native APIs: processes through Toolhelp, services through the Service Control Manager, packages from the registry, ports from the IP helper library.

How matching works​

Each definition carries a match rule: a process name, a listening port, a package, a service unit, an init family, a capability, or a combination that must all hold. When a host's facts satisfy the rule, the definition is pushed to that host and its probes start. Nothing you did not run gets monitored, and nothing runs that was not matched and signed. A host running Apache with mod_php does not match the PHP-FPM definition, because there is no php-fpm process; it matches the mod_php variant instead.

A definition also stops matching when its service stops. That is deliberate, and it is why "is the server running" comes from a package or unit check rather than from the vanished process.

Real paths, not defaults​

Where a probe needs a location, the agent reads the service's own configuration instead of assuming a default: nginx -T for the access and error logs, the server variables of MySQL for the data directory and slow log, doveconf for the Dovecot log, the php-fpm configuration for its pools. Non-standard layouts are found. For the rare case where the service itself reports the wrong path, you can override any location, see Agent configuration.

Change detection​

The agent watches a cheap change signal (package database timestamps plus the set of listening ports) and re-runs discovery within about 30 seconds of a change. A full refresh also runs every 30 minutes. When a fact disappears (a service removed, a port closed) the inventory shown in the console reflects it within seconds.

Discovered entities appear in the console inventory by kind: process, port, package, unit, init, cronjob, host, capability, and net for addresses. Probes add deeper kinds: vhost (a website), service (a recognised service with its version and paths), device, guest, namespace, docker.

Containers are excluded from host discovery​

Processes that run inside containers are filtered out of host discovery by their cgroup markers, so a PostgreSQL inside a container never matches a host-level definition. Containers are the Docker probe's domain, grouped by image, and a Proxmox node does not falsely match the services running inside its guests.

What lives on the host​

Config and state are kept apart, the usual split between /etc and /var/lib. On Windows both fold into %ProgramData%\Wakora.

/etc/wakora/ (root only, mode 0600):

  • identity: the host UUID and the per-host key, stored as ciphertext bound to this machine. Written by wakora --key, not meant for humans.
  • wakora.conf (optional): non-secret location overrides and a handful of agent settings.
  • secrets.conf: credentials for local services, encrypted. Managed with wakora secret.
  • .seed: a random value mixed into the encryption key, so a leaked ciphertext plus a known machine id is still not enough to decrypt.
  • pending-key (transient): exists only while a registration could not reach the platform, and is wiped after the first successful one. See First start.

/var/lib/wakora/: the offline spool, provisioned APM artifacts, staged changes waiting for an operator, and status.json that wakora doctor reads. A downloaded binary or a spool file does not belong in /etc.

What comes from the platform​

Service definitions with their match rules, collection intervals, the alert rule catalog and per-workspace overrides, capability grants you switch in the console, and optional non-secret location overrides. None of it is a file you maintain; it is delivered signed, verified and applied at runtime.

The one thing that never comes from the platform is a secret value. Definitions reference credentials by name; the value is set on the host and stays there. See Secrets stay local.