> For the complete documentation index, see [llms.txt](https://docs.k9.io/key9-identity/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.k9.io/key9-identity/k9-tail/configuration.md).

# 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](https://github.com/k9io/k9-ssh/blob/main/etc/k9.yaml).

## Configuration file structure

```yaml
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:

```
API_KEY: <company_uuid>:<api_key>
```

### `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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.k9.io/key9-identity/k9-tail/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.