cli: check policies offline by default

Fixes #3355
This commit is contained in:
Kristoffer Dalby committed 2026-11-06 15:38:33 +00:00
1 parent 579878ce21
commit 4b2eaba1ed
10 files changed
+289 -91

No files matched your search

+1
View File
@@ -178,6 +178,7 @@ is not connected, or refuses is "not found". See [the client docs](https://heads
- `--output json` / `--output yaml` now emit the API's shape — camelCase fields, string-encoded IDs, RFC3339 timestamps — instead of the old Protobuf encoding [#3324](https://github.com/juanfont/headscale/pull/3324)
- `headscale policy` renames the database-bypass flag from `--bypass-grpc-and-access-database-directly` to `--bypass-server-and-access-database-directly` [#3324](https://github.com/juanfont/headscale/pull/3324)
- `headscale policy check` is now `headscale check policy`. It checks offline by default (syntax, shape, references) and needs no server, database or config. `--database` (was `--bypass-grpc-and-access-database-directly`) and `--server` (was the default) also run `tests` and `sshTests`. [#3355](https://github.com/juanfont/headscale/issues/3355)
#### NixOS module
+103 -2
View File
@@ -1,12 +1,113 @@
package cli
import "github.com/spf13/cobra"
import (
"context"
"fmt"
"net/http"
"os"
clientv1 "github.com/juanfont/headscale/gen/client/v1"
policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
"github.com/spf13/cobra"
)
func init() {
rootCmd.AddCommand(checkCmd)
checkPolicyCmd.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
checkPolicyCmd.Flags().Bool("database", false, "Open the database directly (no running server required) to resolve users and run tests and sshTests")
checkPolicyCmd.Flags().Bool("server", false, "Ask a running server to check the policy, including tests and sshTests")
checkPolicyCmd.MarkFlagsMutuallyExclusive("database", "server")
mustMarkRequired(checkPolicyCmd, "file")
checkCmd.AddCommand(checkPolicyCmd)
}
var checkCmd = &cobra.Command{
Use: "check",
Short: "Check configuration or policy without a running server",
Short: "Check configuration or policy files",
}
var checkPolicyCmd = &cobra.Command{
Use: "policy",
Short: "Check the Policy file for errors",
Long: `
Check validates the policy's syntax, shape and references without a server,
database or config. Pass --database to open the database directly, or
--server to ask a running headscale, to also run "tests" and "sshTests"
against the live users and nodes.`,
RunE: func(cmd *cobra.Command, args []string) error {
policyPath, _ := cmd.Flags().GetString("file")
policyBytes, err := os.ReadFile(policyPath)
if err != nil {
return fmt.Errorf("reading policy file: %w", err)
}
out := cmd.OutOrStdout()
useDB, _ := cmd.Flags().GetBool("database")
useServer, _ := cmd.Flags().GetBool("server")
switch {
case useDB:
err = loadConfig()
if err != nil {
return err
}
d, err := openBypassDB(cmd)
if err != nil {
return err
}
defer d.Close()
err = validateOfflinePolicy(d, policyBytes)
if err != nil {
return err
}
case useServer:
err = loadConfig()
if err != nil {
return err
}
policyStr := string(policyBytes)
err = withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
resp, err := client.CheckPolicyWithResponse(ctx, clientv1.CheckPolicyJSONRequestBody{
Policy: &policyStr,
})
if err != nil {
return err
}
if resp.StatusCode() != http.StatusOK {
return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
}
return nil
})
if err != nil {
return err
}
default:
var pol *policyv2.Policy
pol, err = policyv2.ParsePolicy(policyBytes)
if err != nil {
return err
}
fmt.Fprintln(out, "Policy is valid")
if pol != nil && (len(pol.Tests) > 0 || len(pol.SSHTests) > 0) {
fmt.Fprintln(out, "tests and sshTests were not run; use --database or --server to run them")
}
return nil
}
fmt.Fprintln(out, "Policy is valid")
return nil
},
}
+139
View File
@@ -1,8 +1,17 @@
package cli
import (
"bytes"
"fmt"
"os"
"path/filepath"
"testing"
"github.com/juanfont/headscale/hscontrol/db"
policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/spf13/cobra"
"github.com/spf13/viper"
"github.com/stretchr/testify/require"
)
@@ -25,3 +34,133 @@ func TestSkipsInitConfig(t *testing.T) {
})
}
}
func newCheckPolicyCmd(t *testing.T, path string, database bool) (*cobra.Command, *bytes.Buffer) {
t.Helper()
cmd := &cobra.Command{}
cmd.Flags().String("file", path, "")
cmd.Flags().Bool("database", database, "")
cmd.Flags().Bool("server", false, "")
cmd.Flags().Bool("force", true, "")
var buf bytes.Buffer
cmd.SetOut(&buf)
return cmd, &buf
}
func TestCheckPolicy(t *testing.T) {
const (
valid = `{"acls":[{"action":"accept","src":["*"],"dst":["*:*"]}]}`
failingTest = `{"acls":[],"tests":[{"src":"alice@","accept":["bob@:22"]}]}`
passingTest = `{"acls":[{"action":"accept","src":["alice@"],"dst":["bob@:22"]}],"tests":[{"src":"alice@","accept":["bob@:22"]}]}` //nolint:gosec // policy fixture
)
writePolicy := func(t *testing.T, body string) string {
t.Helper()
p := filepath.Join(t.TempDir(), "policy.hujson")
require.NoError(t, os.WriteFile(p, []byte(body), 0o600))
return p
}
t.Run("valid", func(t *testing.T) {
cmd, out := newCheckPolicyCmd(t, writePolicy(t, valid), false)
require.NoError(t, checkPolicyCmd.RunE(cmd, nil))
require.Equal(t, "Policy is valid\n", out.String())
})
t.Run("tests not run offline", func(t *testing.T) {
cmd, out := newCheckPolicyCmd(t, writePolicy(t, failingTest), false)
require.NoError(t, checkPolicyCmd.RunE(cmd, nil))
require.Contains(t, out.String(), "Policy is valid")
require.Contains(t, out.String(), "tests and sshTests were not run")
})
t.Run("undefined group", func(t *testing.T) {
cmd, _ := newCheckPolicyCmd(t, writePolicy(t, `{"acls":[{"action":"accept","src":["group:missing"],"dst":["*:*"]}]}`), false)
require.ErrorIs(t, checkPolicyCmd.RunE(cmd, nil), policyv2.ErrGroupNotDefined)
})
t.Run("empty file", func(t *testing.T) {
cmd, out := newCheckPolicyCmd(t, writePolicy(t, ""), false)
require.NoError(t, checkPolicyCmd.RunE(cmd, nil))
require.Equal(t, "Policy is valid\n", out.String())
})
t.Run("broken config ignored offline", func(t *testing.T) {
bad := filepath.Join(t.TempDir(), "bad.yaml")
require.NoError(t, os.WriteFile(bad, []byte("server_url: ["), 0o600))
t.Setenv("HEADSCALE_CONFIG", bad)
cmd, _ := newCheckPolicyCmd(t, writePolicy(t, valid), false)
require.NoError(t, checkPolicyCmd.RunE(cmd, nil))
})
for _, tt := range []struct {
name string
policy string
invalid bool
}{
{"database passing", passingTest, false},
{"database failing", failingTest, true},
} {
t.Run(tt.name, func(t *testing.T) {
viper.Reset()
t.Cleanup(viper.Reset)
dir := t.TempDir()
configPath := filepath.Join(dir, "config.yaml")
config := fmt.Sprintf(`server_url: https://headscale.example.com
noise:
private_key_path: noise_private.key
prefixes:
v4: 100.64.0.0/10
database:
type: sqlite3
sqlite:
path: %q
policy:
mode: database
dns:
magic_dns: false
override_local_dns: false
`, filepath.Join(dir, "headscale.db"))
require.NoError(t, os.WriteFile(configPath, []byte(config), 0o600))
old := cfgFile
cfgFile = configPath
t.Cleanup(func() { cfgFile = old })
require.NoError(t, types.LoadConfig(configPath, true))
cfg, err := types.LoadServerConfig()
require.NoError(t, err)
database, err := db.NewHeadscaleDatabase(cfg)
require.NoError(t, err)
for _, name := range []string{"alice", "bob"} {
user := database.CreateUserForTest(name)
database.CreateRegisteredNodeForTest(user, name+"-node")
}
require.NoError(t, database.Close())
viper.Reset()
cmd, out := newCheckPolicyCmd(t, writePolicy(t, tt.policy), true)
err = checkPolicyCmd.RunE(cmd, nil)
if tt.invalid {
require.ErrorContains(t, err, "test(s) failed")
} else {
require.NoError(t, err)
require.Equal(t, "Policy is valid\n", out.String())
}
})
}
}
+14 -63
View File
@@ -20,6 +20,8 @@ const (
var errAborted = errors.New("command aborted by user")
var errPolicyCheckRemoved = errors.New(`"policy check" was removed in 0.30, use "headscale check policy"`)
// bypassDatabase opens the database directly, bypassing the running server.
// The caller must close the returned handle.
func bypassDatabase() (*db.HSDatabase, error) {
@@ -81,11 +83,19 @@ func init() {
setPolicy.Flags().BoolP(bypassFlag, "", false, "Uses the headscale config to directly access the database, bypassing the API and does not require the server to be running")
mustMarkRequired(setPolicy, "file")
policyCmd.AddCommand(setPolicy)
policyCmd.AddCommand(removedPolicyCheckCmd)
}
checkPolicy.Flags().StringP("file", "f", "", "Path to a policy file in HuJSON format")
checkPolicy.Flags().BoolP(bypassFlag, "", false, "Open the database directly (no running server required) to resolve user references and to evaluate the policy's tests and sshTests blocks. Required when those checks are needed.")
mustMarkRequired(checkPolicy, "file")
policyCmd.AddCommand(checkPolicy)
// removedPolicyCheckCmd turns "unknown shorthand flag: 'f'" into a pointer to
// the replacement.
var removedPolicyCheckCmd = &cobra.Command{
Use: "check",
Hidden: true,
DisableFlagParsing: true,
Args: cobra.ArbitraryArgs,
RunE: func(*cobra.Command, []string) error {
return errPolicyCheckRemoved
},
}
var policyCmd = &cobra.Command{
@@ -199,62 +209,3 @@ var setPolicy = &cobra.Command{
return nil
},
}
var checkPolicy = &cobra.Command{
Use: "check",
Short: "Check the Policy file for errors",
Long: `
Check validates the policy against the server's live users and nodes,
running any "tests" or "sshTests" block. By default the command calls a
running headscale over its API; pass --` + bypassFlag + ` to
open the database directly when headscale is not running.`,
RunE: func(cmd *cobra.Command, args []string) error {
policyPath, _ := cmd.Flags().GetString("file")
policyBytes, err := os.ReadFile(policyPath)
if err != nil {
return fmt.Errorf("reading policy file: %w", err)
}
if bypass, _ := cmd.Flags().GetBool(bypassFlag); bypass {
d, err := openBypassDB(cmd)
if err != nil {
return err
}
defer d.Close()
err = validateOfflinePolicy(d, policyBytes)
if err != nil {
return err
}
fmt.Println("Policy is valid")
return nil
}
policyStr := string(policyBytes)
err = withClient(func(ctx context.Context, client *clientv1.ClientWithResponses) error {
resp, err := client.CheckPolicyWithResponse(ctx, clientv1.CheckPolicyJSONRequestBody{
Policy: &policyStr,
})
if err != nil {
return err
}
if resp.StatusCode() != http.StatusOK {
return apiError(resp.StatusCode(), resp.ApplicationproblemJSONDefault)
}
return nil
})
if err != nil {
return err
}
fmt.Println("Policy is valid")
return nil
},
}
+4 -3
View File
@@ -40,13 +40,14 @@ func init() {
})
}
// skipsInitConfig reports whether args select the check command group, which
// must work without a loadable config. Find runs lazily because init order
// skipsInitConfig reports whether args select the check command group or a
// removed-command stub, which must work without a loadable config. Find runs lazily because init order
// across files is not guaranteed to have registered every command.
func skipsInitConfig(args []string) bool {
cmd, _, err := rootCmd.Find(args)
return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd)
return err == nil && (cmd == checkCmd || cmd.HasParent() && cmd.Parent() == checkCmd ||
cmd == removedPolicyCheckCmd)
}
func loadConfig() error {
+5
View File
@@ -416,3 +416,8 @@ dns:
})
}
}
func TestRemovedPolicyCheck(t *testing.T) {
require.ErrorIs(t, removedPolicyCheckCmd.RunE(removedPolicyCheckCmd, nil), errPolicyCheckRemoved)
require.True(t, skipsInitConfig([]string{"policy", "check", "-f", "x"}))
}
+1 -1
View File
@@ -153,7 +153,7 @@ Headscale checks if the policy is valid during startup and refuses to start if i
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-server-and-access-database-directly > policy.json`
- Edit and fixup `policy.json`. Use the command `headscale policy check --file policy.json` to validate the policy.
- Edit and fixup `policy.json`. Use the command `headscale check policy --file policy.json` to validate the policy.
- Load the modified policy: `headscale policy set --bypass-server-and-access-database-directly --file policy.json`
- Start Headscale as usual.
+1 -1
View File
@@ -3176,7 +3176,7 @@ func TestSetPolicy_DuplicateUsername(t *testing.T) {
require.NotNil(t, filter, "filter must remain populated after rejected SetPolicy")
}
// Empty users → syntax-only check, used by `headscale policy check`.
// Empty users → policy manager skips user-reference validation (syntax-only).
func TestValidateUserReferences_EmptyUsersTolerant(t *testing.T) {
polB := []byte(`{
"groups": {"group:admins": ["yala@"]},
+4 -3
View File
@@ -17,9 +17,10 @@ import (
// Tailscale's policy file `tests` block validates a policy against operator
// assertions: from a given src, named dst:port pairs must be accepted, and
// (optionally) other dst:port pairs must be denied. They run at user-write
// boundaries — `headscale policy set`, file-mode reload after a change,
// `headscale policy check` — and reject the write if any assertion fails.
// (optionally) other dst:port pairs must be denied. `headscale policy set`
// and file-mode reload after a change reject the write if any assertion
// fails; `headscale check policy --database` and `--server` run the
// assertions and report failures without applying the policy.
// Boot-time reload of an already-stored policy does not run them, so a
// stale referenced entity (e.g. a deleted user) cannot lock the server out.
//
+17 -18
View File
@@ -15,15 +15,15 @@ import (
"tailscale.com/tailcfg"
)
// TestPolicyCheckCommand exercises `headscale policy check` across the
// TestPolicyCheckCommand exercises `headscale check policy` across the
// matrix that nblock asked about on PR #3229:
//
// - policyMode: server runs with policy_mode=file vs policy_mode=database.
// `check` reads from `--file`, so the server-side mode should not
// change the outcome; running both proves that.
// - fixture: ACL only, ACL with passing tests, ACL with failing tests.
// - bypass: no-bypass talks to the server over gRPC; bypass opens the
// database directly.
// - checkMode: offline parses only; database opens the database directly;
// server asks the running server. Only the last two run tests.
//
// Each policy mode shares one scenario across its sequential checks because
// policy_mode is fixed at boot. The two users + two nodes give the tests
@@ -82,29 +82,24 @@ func TestPolicyCheckCommand(t *testing.T) {
type row struct {
name string
fixture fixture
bypass bool
checkMode string
wantErr string
wantStdout string
}
modes := []types.PolicyMode{types.PolicyModeFile, types.PolicyModeDB}
bypasses := []bool{false, true}
rows := make([]row, 0, len(fixtures)*len(bypasses))
checkModes := []string{"offline", "database", "server"}
rows := make([]row, 0, len(fixtures)*len(checkModes))
for _, f := range fixtures {
for _, bypass := range bypasses {
suffix := "no-bypass"
if bypass {
suffix = "bypass"
}
for _, checkMode := range checkModes {
r := row{
name: f.name + "-" + suffix,
name: f.name + "-" + checkMode,
fixture: f,
bypass: bypass,
checkMode: checkMode,
wantStdout: "Policy is valid",
}
if f.name == "acl-plus-failing-tests" {
if f.name == "acl-plus-failing-tests" && checkMode != "offline" {
r.wantErr = "test(s) failed"
r.wantStdout = ""
}
@@ -175,12 +170,16 @@ func TestPolicyCheckCommand(t *testing.T) {
}, integrationutil.StatusReadyTimeout, integrationutil.FastPoll, "policy check must not alter the live policy")
})
cmd := []string{"headscale", "policy", "check", "-f", policyFilePath} //nolint:goconst // CLI invocation
if tt.bypass {
cmd := []string{"headscale", "check", "policy", "-f", policyFilePath} //nolint:goconst // CLI invocation
switch tt.checkMode {
case "database":
// --force suppresses the "is the server running?"
// confirmation prompt so the command can run
// non-interactively under the test harness.
cmd = append(cmd, "--bypass-server-and-access-database-directly", "--force")
cmd = append(cmd, "--database", "--force")
case "server":
cmd = append(cmd, "--server")
}
stdout, err := headscale.Execute(cmd)