mirror of
https://github.com/tale/headplane.git
synced 2026-07-26 07:48:14 +00:00
Aarnav Tale
450 lines
9.9 KiB
Markdown
450 lines
9.9 KiB
Markdown
# 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" ]`
|