> 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-ssh/configuration.md).

# Configuration

k9-ssh is configured through a single YAML file. The default path is `/opt/k9/etc/k9.yaml`. You can specify an alternate path with the `--config` flag.

## Minimal Configuration

```yaml
system:
  machine_group: "production"
  run_as: "key9"

authentication:
  api_key: "YOUR_API_KEY"
  company_uuid: "YOUR_COMPANY_UUID"

urls:
  query_ssh_keys: "https://ssh-api.k9.io/api/v1/ssh/query/"
```

## Full Configuration Reference

```yaml
system:
  # Required. The Key9 machine group (or comma-delimited groups) this host
  # belongs to. Keys are only returned for users that have access to at least
  # one of these groups.
  machine_group: "production"

  # Required. The OS user that k9-ssh must run as. k9-ssh will exit if the
  # current process user does not match this value. Must match the user set
  # in sshd_config's AuthorizedKeysCommandUser directive.
  run_as: "key9"

  # Optional. Timeout in seconds for API requests. Defaults to 5.
  connection_timeout: 5

authentication:
  # Required. Your Key9 company API key.
  api_key: "YOUR_API_KEY"

  # Required. Your Key9 company UUID.
  company_uuid: "YOUR_COMPANY_UUID"

urls:
  # Required. The Key9 SSH key query endpoint. Do not change unless instructed
  # by Key9 support.
  query_ssh_keys: "https://ssh-api.k9.io/api/v1/ssh/query/"

  # The following URL fields are used by the Key9 NSS library (libnss-k9)
  # and are not required for k9-ssh alone. Include them if you are also
  # deploying the NSS library on this host.
  query_group_name:      "https://ssh-api.k9.io/api/v1/query/group/name"
  query_group_gid:       "https://ssh-api.k9.io/api/v1/query/group/gid"
  query_group_id:        "https://ssh-api.k9.io/api/v1/query/group/id"
  query_shadow_username: "https://ssh-api.k9.io/api/v1/query/shadow/username"
  query_passwd_username: "https://ssh-api.k9.io/api/v1/query/passwd/username"
  query_passwd_uid:      "https://ssh-api.k9.io/api/v1/query/passwd/uid"
  query_passwd_id:       "https://ssh-api.k9.io/api/v1/query/passwd/id"

tail:
  # Used by the k9-tail log shipping component (not required for k9-ssh).
  tail_file:          "/var/log/auth.log"
  waldo_file:         "/opt/k9/cache/auth.waldo"
  client_logging_url: "https://client-logging.k9-api.io/client-logging/api/v1/post"
```

## Field Reference

### `system` section

| Field                | Required | Default | Description                                                                                                                                                |
| -------------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `machine_group`      | Yes      | —       | Comma-delimited Key9 machine group(s) this host belongs to, e.g. `"dev,bastion"`. Keys are scoped to users who have access to one or more of these groups. |
| `run_as`             | Yes      | —       | OS username under which k9-ssh must run. k9-ssh exits immediately if the current user does not match.                                                      |
| `connection_timeout` | No       | `5`     | HTTP timeout (seconds) for Key9 API requests.                                                                                                              |

### `authentication` section

| Field          | Required | Description                                        |
| -------------- | -------- | -------------------------------------------------- |
| `api_key`      | Yes      | Your Key9 company API key from the Key9 dashboard. |
| `company_uuid` | Yes      | Your Key9 company UUID from the Key9 dashboard.    |

These two values are combined into a single `API_KEY` header (`company_uuid:api_key`) on every API request.

### `urls` section

| Field            | Required | Description                                                                                                                                                                                                                               |
| ---------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query_ssh_keys` | Yes      | Base URL for SSH key lookups. k9-ssh appends `{username}/{machine_group}` to this URL when querying. Use `https://` for the Key9 cloud API, or `http://` when pointing at a local [k9-proxy](/key9-identity/k9-ssh/k9-proxy.md) instance. |
| All others       | No       | Used by the Key9 NSS library; leave them at their defaults or omit entirely if not using the NSS library.                                                                                                                                 |

## Machine Groups

Machine groups let you segment access. A user in Key9 must be granted access to at least one of the groups listed in `machine_group` for their keys to be returned by k9-ssh on that host.

You can assign multiple groups to a single host using a comma-delimited list:

```yaml
system:
  machine_group: "bastion,production,monitoring"
```

A single Key9 user can then be granted access to just `bastion` to reach only jump hosts, or to `production` to reach application servers, without any reconfiguration on the hosts themselves.

## File Permissions

The configuration file contains your API credentials and should be readable only by root and the `key9` group:

```bash
sudo chown root:key9 /opt/k9/etc/k9.yaml
sudo chmod 640 /opt/k9/etc/k9.yaml
```

## Command-Line Flags

| Flag       | Default               | Description                                                                       |
| ---------- | --------------------- | --------------------------------------------------------------------------------- |
| `--user`   | (required)            | The OS username being authenticated. sshd passes this automatically via `%u`.     |
| `--remote` | (none)                | Client connection string. sshd passes this automatically via `%C` (OpenSSH 9.4+). |
| `--config` | `/opt/k9/etc/k9.yaml` | Path to the YAML configuration file.                                              |


---

# 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-ssh/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.