For the complete documentation index, see llms.txt. This page is also available as Markdown.

Configuration

k9-tail reads its configuration from a YAML file located at:

/opt/k9/etc/k9.yaml

This path is fixed and cannot be changed via command-line flags. The same file is shared with other Key9 components. A template is available in the k9-ssh repository.

Configuration file structure

authentication:
  api_key: "your-api-key"
  company_uuid: "your-company-uuid"

tail:
  tail_file: "/var/log/auth.log"
  waldo_file: "/var/lib/k9/waldo"
  client_logging_url: "https://api.k9.io/client/logging"

Field reference

authentication section

Field
Type
Required
Description

api_key

string

Yes

API key issued by Key9 for your account

company_uuid

string

Yes

UUID identifying your organization in Key9

These two values are combined to form the API_KEY HTTP header sent with every log submission:

tail section

Field
Type
Required
Description

tail_file

string

Yes

Path to the authentication log file to monitor

waldo_file

string

Yes

Path where k9-tail stores its file position state

client_logging_url

string

Yes

HTTPS endpoint for the Key9 client logging API

tail_file

The authentication log to follow. On most Debian/Ubuntu systems this is /var/log/auth.log. On RHEL/CentOS systems it may be /var/log/secure.

waldo_file

k9-tail writes a small state file here containing the current byte offset of tail_file. This prevents duplicate log submissions if the process is restarted.

  • The file is created automatically if it does not exist.

  • It is updated every 5 seconds during normal operation and immediately upon a graceful shutdown.

  • File permissions are set to 0600 (owner read/write only).

  • If tail_file is truncated (e.g., log rotation), the waldo position is reset to zero automatically.

client_logging_url

The Key9 API endpoint that receives log events. This value must use https:// — k9-tail will refuse to start if an HTTP URL is provided.

Validation

On startup, k9-tail validates that all five fields are present and that client_logging_url uses HTTPS. If any check fails, the process exits immediately with a descriptive error message.

Last updated