config: validate the files a config names

New package hscontrol/config: Files lists each file a config
names with its validator; ReadPrivateKey moves here.

Updates #3443
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 12:19:22 +01:00
1 parent 5de40d9528
commit 0208434691
5 files changed
+463 -20

No files matched your search

+5
View File
@@ -159,6 +159,11 @@ headscale/
Performance-critical.
- `policy/` — `policy/v2/` is **the** policy implementation. The
top-level `policy.go` is thin wrappers. There is no v1 directory.
- `config/` — home for config code outside the `types.Config` struct: the
checks behind `headscale check` (`Files` lists every file a config names,
with its validator) and `ReadPrivateKey`. The loader, defaults,
removed-keys table and `ConfigError` move here next. It imports `types`;
`types`, `derp`, `dns` and `policy` must never import it.
- `routes/`, `dns/`, `derp/`, `types/`, `util/`, `templates/`, `capver/`
— routing, MagicDNS, relay, core types, helpers, client templates,
capability versioning.
+4 -15
View File
@@ -35,6 +35,7 @@ import (
apiv1 "github.com/juanfont/headscale/hscontrol/api/v1"
apiv2 "github.com/juanfont/headscale/hscontrol/api/v2"
"github.com/juanfont/headscale/hscontrol/capver"
"github.com/juanfont/headscale/hscontrol/config"
"github.com/juanfont/headscale/hscontrol/db"
"github.com/juanfont/headscale/hscontrol/derp"
derpServer "github.com/juanfont/headscale/hscontrol/derp/server"
@@ -286,10 +287,7 @@ func NewHeadscale(cfg *types.Config) (*Headscale, error) {
}
if derpServerKey.Equal(*noisePrivateKey) {
return nil, fmt.Errorf(
"DERP server private key and noise private key are the same: %w",
err,
)
return nil, config.ErrSameKey
}
if cfg.DERP.ServerVerifyClients {
@@ -1320,7 +1318,7 @@ func readOrCreatePrivateKey(path string) (*key.MachinePrivate, error) {
return nil, fmt.Errorf("ensuring private key directory: %w", err)
}
privateKey, err := os.ReadFile(path)
machineKey, err := config.ReadPrivateKey(path)
if errors.Is(err, os.ErrNotExist) {
log.Info().Str("path", path).Msg("no private key file at path, creating...")
@@ -1344,18 +1342,9 @@ func readOrCreatePrivateKey(path string) (*key.MachinePrivate, error) {
}
return &machineKey, nil
} else if err != nil {
return nil, fmt.Errorf("reading private key file: %w", err)
}
trimmedPrivateKey := strings.TrimSpace(string(privateKey))
var machineKey key.MachinePrivate
if err = machineKey.UnmarshalText([]byte(trimmedPrivateKey)); err != nil { //nolint:noinlineerr
return nil, fmt.Errorf("parsing private key: %w", err)
}
return &machineKey, nil
return machineKey, err
}
// Change is used to send changes to nodes.
+134
View File
@@ -0,0 +1,134 @@
// Package config checks headscale's configuration and the files it names.
// It imports types; types, derp, dns and policy must never import it.
package config
import (
"crypto/tls"
"errors"
"fmt"
"os"
"strings"
"github.com/juanfont/headscale/hscontrol/derp"
"github.com/juanfont/headscale/hscontrol/dns"
policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/juanfont/headscale/hscontrol/util"
"tailscale.com/types/key"
)
var ErrSameKey = errors.New("noise and DERP private keys must differ")
// File is one file the configuration names.
type File struct {
Key string // config key, e.g. "policy.path"
Path string // as startup resolves it
// CreatedAtStartup marks key files: startup creates them when missing,
// so a missing one is not an error.
CreatedAtStartup bool
// Check parses the file.
Check func() error
}
// Files lists every file cfg names, in config order, with the check for its
// kind. Paths are resolved as startup resolves them.
func Files(cfg *types.Config) []File {
var files []File
if cfg.Policy.Mode == types.PolicyModeFile && cfg.Policy.Path != "" {
p := util.AbsolutePathFromConfigPath(cfg.Policy.Path)
files = append(files, File{Key: "policy.path", Path: p, Check: func() error { return CheckPolicyFile(p) }})
}
for _, p := range cfg.DERP.Paths {
files = append(files, File{Key: "derp.paths", Path: p, Check: func() error { return CheckDERPMapFile(p) }})
}
if p := cfg.DNSConfig.ExtraRecordsPath; p != "" {
files = append(files, File{Key: "dns.extra_records_path", Path: p, Check: func() error { return CheckExtraRecordsFile(p) }})
}
if c, k := cfg.TLS.CertPath, cfg.TLS.KeyPath; c != "" {
files = append(files, File{
Key: "tls.cert_path, tls.key_path",
Path: c + ", " + k,
Check: func() error { _, err := tls.LoadX509KeyPair(c, k); return err },
})
}
noise := cfg.NoisePrivateKeyPath
if noise != "" {
files = append(files, File{
Key: "noise.private_key_path", Path: noise, CreatedAtStartup: true,
Check: func() error { _, err := ReadPrivateKey(noise); return err },
})
}
if d := cfg.DERP.ServerPrivateKeyPath; cfg.DERP.ServerEnabled && d != "" {
files = append(files, File{
Key: "derp.server.private_key_path", Path: d, CreatedAtStartup: true,
Check: func() error { return checkDERPKey(d, noise) },
})
}
return files
}
// CheckPolicyFile checks a policy file as "headscale check policy" does,
// tests and sshTests included.
func CheckPolicyFile(path string) error {
b, err := os.ReadFile(path)
if err != nil {
return err
}
return policyv2.CheckPolicy(b)
}
// CheckDERPMapFile parses a DERP map file as startup loads derp.paths.
func CheckDERPMapFile(path string) error {
_, err := derp.GetDERPMap(types.DERPConfig{Paths: []string{path}})
return err
}
// CheckExtraRecordsFile parses a dns.extra_records_path file.
func CheckExtraRecordsFile(path string) error {
_, _, err := dns.ReadExtraRecordsFromPath(path)
return err
}
// ReadPrivateKey reads and parses a key file.
func ReadPrivateKey(path string) (*key.MachinePrivate, error) {
b, err := os.ReadFile(path)
if err != nil {
return nil, fmt.Errorf("reading private key file: %w", err)
}
var k key.MachinePrivate
err = k.UnmarshalText([]byte(strings.TrimSpace(string(b))))
if err != nil {
return nil, fmt.Errorf("parsing private key: %w", err)
}
return &k, nil
}
func checkDERPKey(derpPath, noisePath string) error {
d, err := ReadPrivateKey(derpPath)
if err != nil {
return err
}
// A noise key that cannot be read fails on its own line.
n, err := ReadPrivateKey(noisePath)
if err == nil && d.Equal(*n) {
return ErrSameKey
}
return nil
}
+315
View File
@@ -0,0 +1,315 @@
package config
import (
"os"
"path/filepath"
"testing"
"github.com/google/go-cmp/cmp"
policyv2 "github.com/juanfont/headscale/hscontrol/policy/v2"
"github.com/juanfont/headscale/hscontrol/types"
"github.com/stretchr/testify/require"
"tailscale.com/types/key"
)
func write(t *testing.T, path, content string) string {
t.Helper()
require.NoError(t, os.WriteFile(path, []byte(content), 0o600))
return path
}
func keyText(t *testing.T) string {
t.Helper()
b, err := key.NewMachine().MarshalText()
require.NoError(t, err)
return string(b)
}
const badGroup = `{"acls":[{"action":"accept","src":["group:missing"],"dst":["*:*"]}]}`
func TestFiles(t *testing.T) {
dir := t.TempDir()
cfg := &types.Config{
NoisePrivateKeyPath: filepath.Join(dir, "noise.key"),
Policy: types.PolicyConfig{Mode: types.PolicyModeFile, Path: filepath.Join(dir, "policy.hujson")},
DERP: types.DERPConfig{
Paths: []string{"a.yaml", "b.yaml"},
ServerEnabled: true,
ServerPrivateKeyPath: filepath.Join(dir, "derp.key"),
},
DNSConfig: types.DNSConfig{ExtraRecordsPath: "records.json"},
TLS: types.TLSConfig{CertPath: "c.pem", KeyPath: "k.pem"},
}
type entry struct {
Key, Path string
CreatedAtStartup bool
}
files := Files(cfg)
got := make([]entry, 0, len(files))
for _, f := range files {
got = append(got, entry{f.Key, f.Path, f.CreatedAtStartup})
}
want := []entry{
{"policy.path", filepath.Join(dir, "policy.hujson"), false},
{"derp.paths", "a.yaml", false},
{"derp.paths", "b.yaml", false},
{"dns.extra_records_path", "records.json", false},
{"tls.cert_path, tls.key_path", "c.pem, k.pem", false},
{"noise.private_key_path", filepath.Join(dir, "noise.key"), true},
{"derp.server.private_key_path", filepath.Join(dir, "derp.key"), true},
}
if diff := cmp.Diff(want, got); diff != "" {
t.Errorf("Files() mismatch (-want +got):\n%s", diff)
}
// A policy in the database and a disabled DERP server name no file.
cfg.Policy.Mode = types.PolicyModeDB
cfg.DERP.ServerEnabled = false
for _, f := range Files(cfg) {
require.NotContains(t, []string{"policy.path", "derp.server.private_key_path"}, f.Key)
}
}
func TestFilesChecks(t *testing.T) {
tests := []struct {
name string
build func(t *testing.T, dir string) *types.Config
key string
wantErr error // errors.Is target
wantMsg string // substring, when no sentinel exists
}{
{
name: "policy valid",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
p := write(t, filepath.Join(dir, "p.hujson"), `{"acls":[{"action":"accept","src":["*"],"dst":["*:*"]}]}`)
return &types.Config{Policy: types.PolicyConfig{Mode: types.PolicyModeFile, Path: p}}
},
key: "policy.path",
},
{
name: "policy with undefined group",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
p := write(t, filepath.Join(dir, "p.hujson"), badGroup)
return &types.Config{Policy: types.PolicyConfig{Mode: types.PolicyModeFile, Path: p}}
},
key: "policy.path",
wantErr: policyv2.ErrGroupNotDefined,
},
{
name: "policy with failing tests",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
p := write(t, filepath.Join(dir, "p.hujson"), `{"acls":[],"tests":[{"src":"alice@","accept":["bob@:22"]}]}`)
return &types.Config{Policy: types.PolicyConfig{Mode: types.PolicyModeFile, Path: p}}
},
key: "policy.path",
wantMsg: "test(s) failed",
},
{
name: "policy empty",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
p := write(t, filepath.Join(dir, "p.hujson"), "")
return &types.Config{Policy: types.PolicyConfig{Mode: types.PolicyModeFile, Path: p}}
},
key: "policy.path",
wantErr: policyv2.ErrPolicyEmpty,
},
{
name: "policy missing",
build: func(_ *testing.T, dir string) *types.Config {
return &types.Config{Policy: types.PolicyConfig{Mode: types.PolicyModeFile, Path: filepath.Join(dir, "nope")}}
},
key: "policy.path",
wantErr: os.ErrNotExist,
},
{
name: "derp map empty",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
return &types.Config{DERP: types.DERPConfig{Paths: []string{write(t, filepath.Join(dir, "d.yaml"), "{}")}}}
},
key: "derp.paths",
wantMsg: "d.yaml",
},
{
name: "extra records valid",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
p := write(t, filepath.Join(dir, "r.json"), `[{"name":"a.example.com","type":"A","value":"100.64.0.1"}]`)
return &types.Config{DNSConfig: types.DNSConfig{ExtraRecordsPath: p}}
},
key: "dns.extra_records_path",
},
{
name: "extra records malformed",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
return &types.Config{DNSConfig: types.DNSConfig{ExtraRecordsPath: write(t, filepath.Join(dir, "r.json"), "{not json")}}
},
key: "dns.extra_records_path",
wantMsg: "unmarshalling records",
},
{
name: "tls pair missing",
build: func(_ *testing.T, dir string) *types.Config {
return &types.Config{TLS: types.TLSConfig{CertPath: filepath.Join(dir, "c.pem"), KeyPath: filepath.Join(dir, "k.pem")}}
},
key: "tls.cert_path, tls.key_path",
wantErr: os.ErrNotExist,
},
{
name: "noise key missing",
build: func(_ *testing.T, dir string) *types.Config {
return &types.Config{NoisePrivateKeyPath: filepath.Join(dir, "sub", "noise.key")}
},
key: "noise.private_key_path",
wantErr: os.ErrNotExist,
},
{
name: "noise key corrupt",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
return &types.Config{NoisePrivateKeyPath: write(t, filepath.Join(dir, "noise.key"), "garbage")}
},
key: "noise.private_key_path",
wantMsg: "parsing private key",
},
{
name: "derp key equals noise key",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
k := keyText(t)
return &types.Config{
NoisePrivateKeyPath: write(t, filepath.Join(dir, "noise.key"), k),
DERP: types.DERPConfig{
ServerEnabled: true,
ServerPrivateKeyPath: write(t, filepath.Join(dir, "derp.key"), k+"\n"),
},
}
},
key: "derp.server.private_key_path",
wantErr: ErrSameKey,
},
{
name: "derp key differs from noise key",
build: func(t *testing.T, dir string) *types.Config {
t.Helper()
return &types.Config{
NoisePrivateKeyPath: write(t, filepath.Join(dir, "noise.key"), keyText(t)),
DERP: types.DERPConfig{
ServerEnabled: true,
ServerPrivateKeyPath: write(t, filepath.Join(dir, "derp.key"), keyText(t)),
},
}
},
key: "derp.server.private_key_path",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir := t.TempDir()
var found bool
for _, f := range Files(tt.build(t, dir)) {
if f.Key != tt.key {
continue
}
found = true
err := f.Check()
switch {
case tt.wantErr != nil:
require.ErrorIs(t, err, tt.wantErr)
case tt.wantMsg != "":
require.ErrorContains(t, err, tt.wantMsg)
default:
require.NoError(t, err)
}
}
require.True(t, found, "no file with key %q", tt.key)
// Checks never create anything.
entries, err := os.ReadDir(dir)
require.NoError(t, err)
for _, e := range entries {
require.False(t, e.IsDir(), "check created %s", e.Name())
}
})
}
}
func TestCheckDERPMapFile(t *testing.T) {
dir := t.TempDir()
require.NoError(t, CheckDERPMapFile(write(t, filepath.Join(dir, "ok.yaml"), `regions:
900:
regionid: 900
regioncode: test
nodes:
- name: 900a
regionid: 900
hostname: derp.example.com
`)))
require.ErrorContains(t, CheckDERPMapFile(write(t, filepath.Join(dir, "bad.yaml"), "regions: [")), "reading DERP map")
require.ErrorIs(t, CheckDERPMapFile(filepath.Join(dir, "missing.yaml")), os.ErrNotExist)
}
func TestCheckExtraRecordsFile(t *testing.T) {
dir := t.TempDir()
require.NoError(t, CheckExtraRecordsFile(write(t, filepath.Join(dir, "ok.json"),
`[{"name":"a.example.com","type":"A","value":"100.64.0.1"}]`)))
err := CheckExtraRecordsFile(write(t, filepath.Join(dir, "bad.json"), `[{"name": "secret-ish"`))
require.ErrorContains(t, err, "bad.json")
require.NotContains(t, err.Error(), "secret-ish", "file content must not be echoed")
require.ErrorIs(t, CheckExtraRecordsFile(filepath.Join(dir, "missing.json")), os.ErrNotExist)
}
func TestReadPrivateKey(t *testing.T) {
dir := t.TempDir()
k := keyText(t)
got, err := ReadPrivateKey(write(t, filepath.Join(dir, "k"), " "+k+"\n"))
require.NoError(t, err)
b, err := got.MarshalText()
require.NoError(t, err)
require.Equal(t, k, string(b))
_, err = ReadPrivateKey(filepath.Join(dir, "missing"))
require.ErrorIs(t, err, os.ErrNotExist)
}
+5 -5
View File
@@ -53,7 +53,7 @@ func NewExtraRecordsManager(path string) (*ExtraRecordsMan, error) {
return nil, fmt.Errorf("%w: %s", ErrPathIsDirectory, path)
}
records, hash, err := readExtraRecordsFromPath(path)
records, hash, err := ReadExtraRecordsFromPath(path)
if err != nil {
closeWatcher()
return nil, fmt.Errorf("reading extra records from path: %w", err)
@@ -183,7 +183,7 @@ func (e *ExtraRecordsMan) UpdateCh() <-chan []tailcfg.DNSRecord {
}
func (e *ExtraRecordsMan) updateRecords() {
records, newHash, err := readExtraRecordsFromPath(e.path)
records, newHash, err := ReadExtraRecordsFromPath(e.path)
if err != nil {
log.Error().Caller().Err(err).Msgf("reading extra records from path: %s", e.path)
return
@@ -222,10 +222,10 @@ func (e *ExtraRecordsMan) updateRecords() {
}
}
// readExtraRecordsFromPath reads a file of [tailcfg.DNSRecord] in the format its
// ReadExtraRecordsFromPath reads a file of [tailcfg.DNSRecord] in the format its
// extension names (see [util.UnmarshalByExt]) and returns the records and the
// hash of the file.
func readExtraRecordsFromPath(path string) ([]tailcfg.DNSRecord, [32]byte, error) {
func ReadExtraRecordsFromPath(path string) ([]tailcfg.DNSRecord, [32]byte, error) {
var zero [32]byte
b, err := os.ReadFile(path)
@@ -244,7 +244,7 @@ func readExtraRecordsFromPath(path string) ([]tailcfg.DNSRecord, [32]byte, error
records, err := util.UnmarshalByExt[[]tailcfg.DNSRecord](path, b)
if err != nil {
return nil, zero, fmt.Errorf("unmarshalling records, content: %q: %w", string(b), err)
return nil, zero, fmt.Errorf("unmarshalling records: %w", err)
}
return records, hash, nil