diff --git a/CHANGELOG.md b/CHANGELOG.md index 0fc960c2..2a4d2950 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -93,6 +93,8 @@ upstream is changed. groups, email and domain [#2663](https://github.com/juanfont/headscale/pull/2663) - Policy will now reject invalid fields, making it easier to spot spelling errors [#2764](https://github.com/juanfont/headscale/pull/2764) +- Add FAQ entry on how to recover from an invalid policy in the database + [#2776](https://github.com/juanfont/headscale/pull/2776) ## 0.26.1 (2025-06-06) diff --git a/docs/about/faq.md b/docs/about/faq.md index 49127bf4..e67a47d9 100644 --- a/docs/about/faq.md +++ b/docs/about/faq.md @@ -143,3 +143,19 @@ in their output of `tailscale status`. Traffic is still filtered according to th ping` which is always allowed in either direction. See also . + +## My policy is stored in the database and Headscale refuses to start due to an invalid policy. How can I recover? + +Headscale checks if the policy is valid during startup and refuses to start if it detects an error. The error message +indicates which part of the policy is invalid. Follow these steps to fix your policy: + +- Dump the policy to a file: `headscale policy get --bypass-grpc-and-access-database-directly > policy.json` +- Edit and fixup `policy.json`. Use the command `headscale policy check --file policy.json` to validate the policy. +- Load the modified policy: `headscale policy set --bypass-grpc-and-access-database-directly --file policy.json` +- Start Headscale as usual. + +!!! warning "Full server configuration required" + + The above commands to get/set the policy require a complete server configuration file including database settings. A + minimal config to [control Headscale via remote CLI](../ref/remote-cli.md) is not sufficient. You may use `headscale + -c /path/to/config.yaml` to specify the path to an alternative configuration file.