config: let NixOS options for read-only files take Nix paths

A nix:"path" tag types policy.path, dns.extra_records_path and
tls.cert_path as an absolute path or "", and derp.paths as a list of
paths, so pkgs.writeText and ./policy.hujson work. A nix:"external" tag
types key and state files as an absolute path outside the Nix store, so
no private key is copied into the world-readable store.

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 12:19:29 +01:00
1 parent 4185b2481c
commit f43583cbc6
6 files changed
+107 -12

No files matched your search

+15
View File
@@ -313,6 +313,21 @@
];
"oidc.client_secret" = [ "hunter2" ];
"database.postgres.pass" = [ "hunter2" ];
# Relative to the config, which is in the store.
"policy.path" = [
"policy.hujson"
42
];
"tls.cert_path" = [ "cert.pem" ];
"derp.paths" = [ [ "derp.yaml" ] ];
# A key in the store is world-readable.
"noise.private_key_path" = [
./flake.nix
"${./flake.nix}"
"noise_private.key"
];
"tls.key_path" = [ "${./flake.nix}" ];
"database.sqlite.path" = [ "db.sqlite" ];
"dns.extra_records" = map (r: [ ({ name = "grafana.example.com"; } // r) ]) [
{ value = "grafana"; }
{ value = "256.1.1.1"; }
+6 -2
View File
@@ -198,8 +198,8 @@ func mkOption(indent int, attrs [][2]string) string {
}
// nixDescription is k's documentation in Markdown: its doc, its enum
// values, whether it is required and, for a secret, what the NixOS type
// accepts and how NixOS passes it as a file.
// values, whether it is required, for a path or a secret what the NixOS
// type accepts and, for a secret, how NixOS passes it as a file.
func nixDescription(k keyInfo) string {
parts := []string{k.Doc}
@@ -231,6 +231,10 @@ func nixDescription(k keyInfo) string {
parts = append(parts, nixCredential("the value must be `\"\"` or `file:<path>`", credentialName(k.Path), "the secret", "this option"))
case k.Path == providerKey:
parts = append(parts, nixCredential("keep a secret setting out of the Nix store", credentialName(k.Path+".<setting>"), "it", "the setting")+" `name` is not a secret.")
case k.Field.Tag.Get("nix") == "path":
parts = append(parts, "On NixOS, paths must be absolute.")
case k.Field.Tag.Get("nix") == "external":
parts = append(parts, "On NixOS, paths must be absolute and outside the Nix store.")
}
return strings.Join(parts, "\n\n")
+12
View File
@@ -228,6 +228,18 @@ func TestGenerateNixOptions(t *testing.T) {
},
{path: "dns.extra_records.options.value", want: []string{"\n type = t.ip;\n"}, hide: []string{"\n default = "}},
{path: "log.level", want: []string{"\n example = \"debug\";\n"}},
// Files headscale only reads take a Nix path; key and state files
// must be outside the store, so no key is copied into it.
{path: "policy.path", want: []string{"\n type = t.readFile;\n", "On NixOS, paths must be absolute.\n"}},
{path: "dns.extra_records_path", want: []string{"\n type = t.readFile;\n"}},
{path: "tls.cert_path", want: []string{"\n type = t.readFile;\n"}},
{path: "derp.paths", want: []string{"\n type = lib.types.listOf lib.types.path;\n", "On NixOS, paths must be absolute.\n"}},
{path: "noise.private_key_path", want: []string{"\n type = t.stateFile;\n", "On NixOS, paths must be absolute and outside the Nix store.\n"}},
{path: "derp.server.private_key_path", want: []string{"\n type = t.stateFile;\n"}},
{path: "database.sqlite.path", want: []string{"\n type = t.stateFile;\n"}},
{path: "unix_socket", want: []string{"\n type = t.stateFile;\n"}},
{path: "tls.key_path", want: []string{"\n type = t.stateFile;\n"}},
{path: "tls.acme.cache_dir", want: []string{"\n type = t.stateFile;\n"}},
}
for _, tt := range tests {
+22
View File
@@ -23,6 +23,7 @@ var (
errBadExample = errors.New("bad example tag")
errNoMapKey = errors.New("open map without a mapkey tag")
errInvalidDefault = errors.New("a default fails validation")
errBadNixTag = errors.New("bad nix tag")
)
// keyInfo is what the generators know about one node of
@@ -73,6 +74,18 @@ type leafType struct {
const nixStr = "lib.types.str"
// nixFiles types a file a key names, by the key's nix tag and Go type.
// "path" is a file headscale only reads and that holds no secret, so a Nix
// path may copy it to the store; "external" is a key or state file, which
// must stay out of the world-readable store.
var nixFiles = map[string]map[reflect.Type]string{
"path": {
reflect.TypeFor[string](): "t.readFile",
reflect.TypeFor[[]string](): "lib.types.listOf lib.types.path",
},
"external": {reflect.TypeFor[string](): "t.stateFile"},
}
var allowedType = reflect.TypeFor[interface{ Allowed() []string }]()
// leafTypes is the one type table: the page's legend, every key's type
@@ -213,6 +226,15 @@ func (k *keyInfo) describeLeaf(def any, required map[string]string) error {
return err
}
if tag := k.Field.Tag.Get("nix"); tag != "" {
nix, ok := nixFiles[tag][k.Field.Type]
if !ok {
return fmt.Errorf("%w %q on %s", errBadNixTag, tag, k.Field.Type)
}
k.Type.Nix = nix
}
if k.Open {
if k.MapKey == "" {
return errNoMapKey
+42
View File
@@ -173,6 +173,48 @@ func TestLoadExample(t *testing.T) {
}
}
// TestDescribeLeafNixTag: nix:"path" lets a file headscale only reads be a
// Nix path, in the store; nix:"external" keeps a key or state file out of
// it. Any other value, or a tag on another type, is an error, so a secret
// never takes a store path.
func TestDescribeLeafNixTag(t *testing.T) {
str, list := reflect.TypeFor[string](), reflect.TypeFor[[]string]()
tests := []struct {
name string
path string
typ reflect.Type
tag string
want string // Type.Nix
wantErr bool
}{
{name: "path", path: "policy.path", typ: str, tag: `example:"\"/p\"" nix:"path"`, want: "t.readFile"},
{name: "path list", path: "derp.paths", typ: list, tag: `example:"[\"/d\"]" nix:"path"`, want: "lib.types.listOf lib.types.path"},
{name: "external", path: "noise.private_key_path", typ: str, tag: `example:"\"/k\"" nix:"external"`, want: "t.stateFile"},
{name: "untagged", path: "policy.path", typ: str, tag: `example:"\"/p\""`, want: nixStr},
{name: "unknown value", path: "policy.path", typ: str, tag: `nix:"file"`, wantErr: true},
{name: "path on a secret", path: "oidc.client_secret", typ: reflect.TypeFor[types.Secret](), tag: `nix:"path"`, wantErr: true},
{name: "path on an int", path: "database.postgres.port", typ: reflect.TypeFor[int](), tag: `nix:"path"`, wantErr: true},
{name: "external list", path: "derp.paths", typ: list, tag: `nix:"external"`, wantErr: true},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
k := keyInfo{Path: tt.path, Field: reflect.StructField{Type: tt.typ, Tag: reflect.StructTag(tt.tag)}}
err := k.describeLeaf(nil, nil)
if tt.wantErr {
require.ErrorIs(t, err, errBadNixTag)
return
}
require.NoError(t, err)
require.Equal(t, tt.want, k.Type.Nix)
})
}
}
func TestExamples(t *testing.T) {
keys, err := schema()
require.NoError(t, err)
+10 -10
View File
@@ -162,7 +162,7 @@ type Config struct { //nolint:recvcheck // MarshalJSON reads a value, so a Confi
// UnixSocket is where the server serves the API without
// authentication, for the CLI on the same host. The CLI connects to it
// when `cli.address` is empty.
UnixSocket string `example:"\"/run/headscale/headscale.sock\"" koanf:"unix_socket"`
UnixSocket string `example:"\"/run/headscale/headscale.sock\"" koanf:"unix_socket" nix:"external"`
// UnixSocketPermission is the file mode of `unix_socket`, in quoted
// octal (`"0770"`): unquoted, YAML reads `0770` as the number 504.
@@ -268,7 +268,7 @@ type NoiseConfig struct {
// PrivateKeyPath is the file holding the Noise private key, which
// encrypts traffic between headscale and clients, relative to the
// configuration file. A missing file is created with a new key.
PrivateKeyPath string `example:"\"/var/lib/headscale/noise_private.key\"" koanf:"private_key_path"`
PrivateKeyPath string `example:"\"/var/lib/headscale/noise_private.key\"" koanf:"private_key_path" nix:"external"`
}
// PrefixesConfig are the ranges node IPs are allocated from. At least one
@@ -332,7 +332,7 @@ type DNSConfig struct {
// ExtraRecordsPath is a file of extra records, reloaded when it
// changes. The extension picks the format: `.json`, `.hujson`, `.yaml`
// or `.yml`. Mutually exclusive with `dns.extra_records`.
ExtraRecordsPath string `example:"\"/var/lib/headscale/extra-records.json\"" koanf:"extra_records_path"`
ExtraRecordsPath string `example:"\"/var/lib/headscale/extra-records.json\"" koanf:"extra_records_path" nix:"path"`
// Certificates lets nodes get TLS certificates for their MagicDNS
// names with `tailscale cert`. The node runs ACME itself; headscale
@@ -472,7 +472,7 @@ type Nameservers struct {
type SqliteConfig struct {
// Path is the database file, relative to the configuration file;
// `:memory:` keeps the database in memory.
Path string `example:"\"/var/lib/headscale/db.sqlite\"" koanf:"path"`
Path string `example:"\"/var/lib/headscale/db.sqlite\"" koanf:"path" nix:"external"`
// WriteAheadLog applies `database.sqlite.wal_autocheckpoint` and
// compacts the database (`VACUUM`) on shutdown. SQLite runs in WAL
@@ -631,11 +631,11 @@ func (d DatabaseConfig) IsSQLite() bool {
type TLSConfig struct {
// CertPath is the PEM certificate file, relative to the configuration
// file. Setting it turns TLS on.
CertPath string `example:"\"/etc/headscale/tls/cert.pem\"" koanf:"cert_path"`
CertPath string `example:"\"/etc/headscale/tls/cert.pem\"" koanf:"cert_path" nix:"path"`
// KeyPath is the PEM private key file of `tls.cert_path`, relative to
// the configuration file.
KeyPath string `example:"\"/etc/headscale/tls/key.pem\"" koanf:"key_path"`
KeyPath string `example:"\"/etc/headscale/tls/key.pem\"" koanf:"key_path" nix:"external"`
// ACME gets the certificate from an ACME CA such as Let's Encrypt,
// and renews it. Setting `tls.acme.hostname` turns it on.
@@ -665,7 +665,7 @@ type ACMEConfig struct {
// CacheDir is where certificates and ACME account data are stored,
// relative to the configuration file.
CacheDir string `example:"\"/var/cache/headscale/acme\"" koanf:"cache_dir"`
CacheDir string `example:"\"/var/cache/headscale/acme\"" koanf:"cache_dir" nix:"external"`
}
// PKCEConfig configures PKCE (RFC 7636), which protects the OIDC
@@ -751,7 +751,7 @@ type DERPConfig struct {
// Paths are DERP map files. The extension picks the format: `.yaml` or
// `.yml`, or Tailscale JSON as `.json` or `.hujson`, both accepting
// comments and trailing commas.
Paths []string `example:"[\"/etc/headscale/derp.yaml\"]" koanf:"paths"`
Paths []string `example:"[\"/etc/headscale/derp.yaml\"]" koanf:"paths" nix:"path"`
// AutoUpdate reloads `derp.urls` and `derp.paths` every
// `derp.update_frequency`.
@@ -794,7 +794,7 @@ type DERPServerConfig struct {
// relative to the configuration file; required when
// `derp.server.enabled` is true. A missing file is created with a new
// key. It must differ from `noise.private_key_path`.
PrivateKeyPath string `example:"\"/var/lib/headscale/derp_server_private.key\"" koanf:"private_key_path"`
PrivateKeyPath string `example:"\"/var/lib/headscale/derp_server_private.key\"" koanf:"private_key_path" nix:"external"`
// IPv4 is the server's public IPv4 address, published in the DERP map
// so clients reach it without DNS. Empty publishes none.
@@ -861,7 +861,7 @@ type PolicyConfig struct {
// Path is the HuJSON policy file read when `policy.mode` is `file`,
// relative to the configuration file. Empty starts without a policy,
// which allows all traffic.
Path string `example:"\"/etc/headscale/policy.hujson\"" koanf:"path"`
Path string `example:"\"/etc/headscale/policy.hujson\"" koanf:"path" nix:"path"`
// Mode is where the policy is kept: in the file `policy.path`, or in
// the database, edited through the CLI or API.