# NixOS module options

All options must be under `services.headplane`.

For example: `settings.headscale.config_path` becomes `services.headplane.settings.headscale.config_path`.

## debug

_Description:_ Enable debug logging

_Type:_ boolean

_Default:_ `false`

## enable

_Description:_ Whether to enable headplane.

_Type:_ boolean

_Default:_ `false`

_Example:_ `true`

## package

_Description:_ The headplane package to use.

_Type:_ package

_Default:_ `pkgs.headplane`

## settings

_Description:_ Headplane configuration options. Generates a YAML config file.
See: https://github.com/tale/headplane/blob/main/config.example.yaml

_Type:_ submodule

_Default:_ `{ }`

## settings.headscale

_Description:_ Headscale specific settings for Headplane integration.

_Type:_ submodule

_Default:_ `{ }`

## settings.headscale.api_key_path

_Description:_ Path to a file containing the Headscale API key.
Required for OIDC authentication and the Headplane agent.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"config.sops.secrets.headscale_api_key.path"`

## settings.headscale.config_path

_Description:_ Path to the Headscale configuration file.
This is optional, but HIGHLY recommended for the best experience.
If this is read only, Headplane will show your configuration settings
in the Web UI, but they cannot be changed.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"/etc/headscale/config.yaml"`

## settings.headscale.config_strict

_Description:_ Deprecated. Headplane no longer validates the complete Headscale configuration and this option has no effect.

_Type:_ boolean

_Default:_ `true`

## settings.headscale.dns_records_path

_Description:_ If you are using `dns.extra_records_path` in your Headscale configuration, Headplane reads that path automatically. Set this only when Headplane needs to access the same file at a different path.
Ensure that the file is both readable and writable by the Headplane process.
When using this, Headplane will no longer need to automatically restart Headscale for DNS record changes.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"/var/lib/headplane/extra_records.json"`

## settings.headscale.public_url

_Description:_ Public URL if differrent. This affects certain parts of the web UI.

_Type:_ null or string

_Default:_ `null`

_Example:_ `"https://headscale.example.com"`

## settings.headscale.tls_cert_path

_Description:_ Path to a file containing the TLS certificate.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"config.sops.secrets.tls_cert.path"`

## settings.headscale.url

_Description:_ The URL to your Headscale instance.
All API requests are routed through this URL.
THIS IS NOT the gRPC endpoint, but the HTTP endpoint.
IMPORTANT: If you are using TLS this MUST be set to `https://`.

_Type:_ string

_Default:_ `"http://127.0.0.1:8080"`

_Example:_ `"https://headscale.example.com"`

## settings.integration

_Description:_ Integration configurations for Headplane to interact with Headscale.

_Type:_ submodule

_Default:_ `{ }`

## settings.integration.agent

_Description:_ Agent configuration for the Headplane agent.

_Type:_ submodule

_Default:_ `{ }`

## settings.integration.agent.cache_ttl

_Description:_ How long to cache agent information (in milliseconds).
If you want data to update faster, reduce the TTL, but this will increase the frequency of requests to Headscale.

_Type:_ signed integer

_Default:_ `180000`

## settings.integration.agent.enabled

_Description:_ The Headplane agent periodically syncs node information (version, OS, etc.)
from your Tailnet. It auto-generates ephemeral pre-auth keys using
headscale.api_key, so no manual key configuration is needed.
Requires Headscale 0.28 or newer.

_Type:_ boolean

_Default:_ `false`

## settings.integration.agent.executable_path

_Description:_ Path to the Headplane agent binary.
The default is correct if using the NixOS module package.

_Type:_ absolute path

_Default:_ `"/usr/libexec/headplane/agent"`

## settings.integration.agent.host_name

_Description:_ Optionally change the name of the agent in the Tailnet

_Type:_ string

_Default:_ `"headplane-agent"`

## settings.integration.agent.package

_Description:_ The headplane-agent package to use.

_Type:_ package

_Default:_ `pkgs.headplane-agent`

## settings.integration.agent.work_dir

_Description:_ Do not change this unless you are running a custom deployment.
The work_dir represents where the agent will store its data to be able to automatically reauthenticate with your Tailnet.
It needs to be writable by the user running the Headplane process.

_Type:_ absolute path

_Default:_ `"/var/lib/headplane/agent"`

## settings.integration.proc

_Description:_ Native process integration settings.

_Type:_ submodule

_Default:_ `{ }`

## settings.integration.proc.enabled

_Description:_ Enable "Native" integration that works when Headscale and
Headplane are running outside of a container. There is no additional
configuration, but you need to ensure that the Headplane process
can terminate the Headscale process.

_Type:_ boolean

_Default:_ `true`

## settings.oidc

_Description:_ OIDC Configuration for authentication.

_Type:_ submodule

_Default:_ `{ }`

## settings.oidc.client_id

_Description:_ The client ID for the OIDC client.

_Type:_ string

_Default:_ `""`

_Example:_ `"your-client-id"`

## settings.oidc.client_secret_path

_Description:_ Path to a file containing the OIDC client secret.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"config.sops.secrets.oidc_client_secret.path"`

## settings.oidc.disable_api_key_login

_Description:_ Whether to disable API key login.

_Type:_ boolean

_Default:_ `false`

## settings.oidc.default_role

_Description:_ Role assigned to newly created OIDC users after the first owner is bootstrapped.
The owner role is reserved for the first-login bootstrap.

_Type:_ one of "admin", "network_admin", "it_admin", "auditor", "viewer", "member"

_Default:_ `"member"`

## settings.oidc.headscale_api_key_path

_Description:_ DEPRECATED: Use `headscale.api_key_path` instead.
Path to a file containing the Headscale API key.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"config.sops.secrets.headscale_api_key.path"`

## settings.oidc.issuer

_Description:_ URL to OpenID issuer.

_Type:_ string

_Default:_ `""`

_Example:_ `"https://provider.example.com/issuer-url"`

## settings.oidc.redirect_uri

_Description:_ This should point to your publicly accessible URL
for your Headplane instance with /admin/oidc/callback.

_Type:_ string

_Default:_ `""`

_Example:_ `"https://headscale.example.com/admin/oidc/callback"`

## settings.oidc.role_claim

_Description:_ Optional OIDC claim containing the Headplane role to assign to newly created users.
A valid role claim takes precedence over default_role.

_Type:_ null or string

_Default:_ `null`

_Example:_ `"headplane_role"`

## settings.oidc.token_endpoint_auth_method

_Description:_ The token endpoint authentication method.

_Type:_ one of "client_secret_post", "client_secret_basic", "client_secret_jwt"

_Default:_ `"client_secret_post"`

## settings.server

_Description:_ Server configuration for Headplane web application.

_Type:_ submodule

_Default:_ `{ }`

## settings.server.cookie_secret_path

_Description:_ Path to a file containing the cookie secret.
The secret must be exactly 32 characters long.

_Type:_ null or absolute path

_Default:_ `null`

_Example:_ `"config.sops.secrets.headplane_cookie.path"`

## settings.server.cookie_secure

_Description:_ Should the cookies only work over HTTPS?
Set to false if running via HTTP without a proxy.
Recommended to be true in production.

_Type:_ boolean

_Default:_ `true`

## settings.server.data_path

_Description:_ The path to persist Headplane specific data.
All data going forward is stored in this directory, including the internal database and any cache related files.
Data formats prior to 0.6.1 will automatically be migrated.

_Type:_ absolute path

_Default:_ `"/var/lib/headplane"`

_Example:_ `"/var/lib/headplane"`

## settings.server.host

_Description:_ The host address to bind to.

_Type:_ string

_Default:_ `"127.0.0.1"`

_Example:_ `"0.0.0.0"`

## settings.server.port

_Description:_ The port to listen on.

_Type:_ 16 bit unsigned integer; between 0 and 65535 (both inclusive)

_Default:_ `3000`

## settings.server.proxy_auth

_Description:_ Proxy authentication configuration.

_Type:_ submodule

_Default:_ `{ }`

## settings.server.proxy_auth.allowed_cidrs

_Description:_ Direct client CIDR ranges allowed to bypass Headplane's login flow.
These should be the addresses your trusted reverse proxy uses to connect
to Headplane. Requires headscale.api_key_path.

_Type:_ list of string

_Default:_ `[ "127.0.0.1/32" "::1/128" ]`

_Example:_ `[ "10.0.0.0/24" ]`

## settings.server.proxy_auth.email_header

_Description:_ Optional header containing the authenticated user's email address.

_Type:_ null or string

_Default:_ `null`

## settings.server.proxy_auth.enabled

_Description:_ Whether to trust reverse proxy authentication for allowed client CIDRs.

_Type:_ boolean

_Default:_ `false`

## settings.server.proxy_auth.ip_header

_Description:_ Optional header containing the original client IP, such as X-Forwarded-For or X-Real-IP.

_Type:_ null or string

_Default:_ `null`

## settings.server.proxy_auth.name_header

_Description:_ Optional header containing the authenticated user's display name.

_Type:_ null or string

_Default:_ `null`

## settings.server.proxy_auth.picture_header

_Description:_ Optional header containing the authenticated user's profile picture URL.

_Type:_ null or string

_Default:_ `null`

## settings.server.proxy_auth.user_header

_Description:_ Header containing the stable authenticated proxy user identity.

_Type:_ string

_Default:_ `"Remote-User"`

## settings.server.proxy_auth.trusted_proxy_cidrs

_Description:_ Direct proxy CIDR ranges trusted to supply ip_header.
Only used when ip_header is set.

_Type:_ list of string

_Default:_ `[ "127.0.0.1/32" "::1/128" ]`

_Example:_ `[ "127.0.0.1/32" ]`