From 5ab9686460e6759c392fcb5a0df0ee9762a4c73e Mon Sep 17 00:00:00 2001 From: StealthBadger747 Date: Wed, 30 Jul 2025 18:28:48 +0500 Subject: [PATCH] Update the configuration README Revert flake.nix and package.nix to main; drop wasm.nix --- docs/Configuration.md | 47 +++++++++++++++++++++++++++++++++++++++++++ flake.nix | 6 ++---- nix/package.nix | 25 +++++++---------------- nix/wasm.nix | 35 -------------------------------- 4 files changed, 56 insertions(+), 57 deletions(-) delete mode 100644 nix/wasm.nix diff --git a/docs/Configuration.md b/docs/Configuration.md index 0c3770b..5c8bdaf 100644 --- a/docs/Configuration.md +++ b/docs/Configuration.md @@ -30,6 +30,53 @@ Setting this also tells Headplane to load the relative `.env` file into the envi > environment variables meaning you cannot specify variables such as > `HEADPLANE_DEBUG_LOG=true` or `HEADPLANE_CONFIG_PATH=/etc/headplane/config.yaml`. +## Sensitive Values +Headplane supports a dual-mode pattern for providing certain sensitive configuration values, such as secrets, keys, and private certificates. For each such field, you can either: + +1. Set the value directly in the configuration file (e.g., `cookie_secret: "your-32-character-long-secret"`) +2. Provide a path to a file containing the value using the `_path` suffixed key (e.g., `cookie_secret_path: "/path/to/your/cookie_secret_file"`) + +When using a `_path` option, the content of the specified file will be read and used as the value for the setting. These paths can include environment variable interpolation (e.g., `${CREDENTIALS_DIRECTORY}/my_secret_file`), which is useful for integration with tools like systemd's `LoadCredential`. + +**Important Rules for Dual-Mode Fields:** +- You **cannot** set both the direct value (e.g., `cookie_secret`) and its corresponding `_path` (e.g., `cookie_secret_path`) simultaneously. Doing so will result in a configuration error. +- If a `_path` is provided, the corresponding direct value field (if also present and not null) will usually be ignored or may cause validation errors depending on the specific field and loader logic. It's best to provide only one. +- The same dual-mode pattern works with environment variables. You can set `HEADPLANE_OIDC__CLIENT_SECRET` for a direct value or `HEADPLANE_OIDC__CLIENT_SECRET_PATH` to specify a path to a file containing the secret. + +**Note on Path Processing:** +Headplane uses a whitelist approach to determine which `_path` fields should have their content loaded as secrets. Only the explicitly whitelisted paths below will have their file content read and used as configuration values. All other paths with a `_path` suffix will have environment variables interpolated but will not have their content loaded. + +The following configuration options in Headplane are treated as secret paths: + +- **Server Settings (`server.*`):** + - `cookie_secret_path` (for web session encoding) + - *Note:* Either `cookie_secret` or `cookie_secret_path` must be provided for web session security. + +- **Headscale Connection Settings (`headscale.*`):** + - `tls_cert_path` (custom TLS certificate for connecting to Headscale) + - *Note:* This is treated as a regular path, not a secret path, so it will not have its content loaded. + +- **Integration Agent Settings (`integration.agent.*`):** + - `pre_authkey_path` (pre-auth key for the Headplane agent to connect to the Tailnet) + - *Note:* Either `pre_authkey` or `pre_authkey_path` must be provided when the agent is enabled. + +- **OIDC Settings (`oidc.*`):** + - `client_secret_path` (OIDC client secret) + - *Note:* Either `client_secret` or `client_secret_path` must be provided for OIDC authentication. + - `headscale_api_key_path` (Headscale API key used by Headplane during the OIDC authentication flow) + - *Note:* Either `headscale_api_key` or `headscale_api_key_path` must be provided for OIDC integration. + +**Distinction for Non-Secret Paths:** +Other configuration fields that end with `_path` are treated as regular paths and will not have their content loaded. For example: +- `server.agent.cache_path` (default: `/var/lib/headplane/agent_cache.json`): This is a direct file path where Headplane will *store* its agent cache data. +- `headscale.config_path`: This is an optional path to Headscale's `config.yaml` file, which Headplane might read or use for validation. + +All path fields (both secret and non-secret) support environment variable interpolation using the `${VAR_NAME}` syntax. + +The path-based secret loading mechanism also works with environment variables. For instance: +- `HEADPLANE_OIDC__CLIENT_SECRET_PATH=/path/to/secret/file` will load the OIDC client secret from the specified file +- `HEADPLANE_SERVER__COOKIE_SECRET_PATH=${CREDENTIALS_DIRECTORY}/cookie_secret` will use environment variable interpolation in the path + ## Debugging To enable debug logging, set the **`HEADPLANE_DEBUG_LOG=true`** environment variable. This will enable all debug logs for Headplane, which could fill up log space very quickly. diff --git a/flake.nix b/flake.nix index afe0e4f..9229532 100644 --- a/flake.nix +++ b/flake.nix @@ -29,8 +29,7 @@ rec { in rec { formatter = pkgs.alejandra; packages = { - hp_ssh_wasm = pkgs.callPackage ./nix/wasm.nix {}; - headplane = pkgs.callPackage ./nix/package.nix { hp_ssh_wasm = packages.hp_ssh_wasm; }; + headplane = pkgs.callPackage ./nix/package.nix {}; headplane-agent = pkgs.callPackage ./nix/agent.nix {}; }; checks.default = pkgs.symlinkJoin { @@ -62,8 +61,7 @@ rec { }) // { overlays.default = final: prev: { - hp_ssh_wasm = final.callPackage ./nix/wasm.nix {}; - headplane = final.callPackage ./nix/package.nix { hp_ssh_wasm = final.hp_ssh_wasm; }; + headplane = final.callPackage ./nix/package.nix {}; headplane-agent = final.callPackage ./nix/agent.nix {}; }; nixosModules.headplane = import ./nix/module.nix; diff --git a/nix/package.nix b/nix/package.nix index 2208f51..b43a7cc 100644 --- a/nix/package.nix +++ b/nix/package.nix @@ -5,19 +5,12 @@ nodejs_22, pnpm_10, stdenv, - hp_ssh_wasm, ... }: -let - pkg = builtins.fromJSON (builtins.readFile ../package.json); - pname = pkg.name; - version = pkg.version; - src = ../.; -in stdenv.mkDerivation (finalAttrs: { - pname = pname; - version = version; - src = src; + pname = "headplane"; + version = (builtins.fromJSON (builtins.readFile ../package.json)).version; + src = ../.; nativeBuildInputs = [ makeWrapper @@ -29,14 +22,12 @@ stdenv.mkDerivation (finalAttrs: { dontCheckForBrokenSymlinks = true; pnpmDeps = pnpm_10.fetchDeps { - inherit pname version src; - hash = "sha256-GNSpFqPobX6MDPUXxz2XwdZ2Wt7boN8aok52pGgpGoM="; + inherit (finalAttrs) pname version src; + hash = "sha256-hu3028V/EWimYB1TGn7g06kJRIpZA6cuOIjPMEc8ddw="; }; buildPhase = '' runHook preBuild - cp ${hp_ssh_wasm}/hp_ssh.wasm app/hp_ssh.wasm - cp ${hp_ssh_wasm}/wasm_exec.js app/wasm_exec.js pnpm build runHook postBuild ''; @@ -45,12 +36,10 @@ stdenv.mkDerivation (finalAttrs: { runHook preInstall mkdir -p $out/{bin,share/headplane} cp -r build $out/share/headplane/ - cp -r node_modules $out/share/headplane/ - cp -r drizzle $out/share/headplane/ sed -i "s;$PWD;../..;" $out/share/headplane/build/server/index.js makeWrapper ${lib.getExe nodejs_22} $out/bin/headplane \ - --chdir $out/share/headplane \ - --add-flags $out/share/headplane/build/server/index.js + --chdir $out/share/headplane \ + --add-flags $out/share/headplane/build/server/index.js runHook postInstall ''; }) diff --git a/nix/wasm.nix b/nix/wasm.nix deleted file mode 100644 index e53b37e..0000000 --- a/nix/wasm.nix +++ /dev/null @@ -1,35 +0,0 @@ -{ buildGoModule, go, lib, ... }: - -let - pkg = builtins.fromJSON (builtins.readFile ../package.json); - pname = "hp_ssh-wasm"; - version = pkg.version; - wasmExecJs = - if builtins.pathExists "${go}/share/go/lib/wasm/wasm_exec.js" then - "${go}/share/go/lib/wasm/wasm_exec.js" - else if builtins.pathExists "${go}/lib/wasm/wasm_exec.js" then - "${go}/lib/wasm/wasm_exec.js" - else - "${go}/share/go/misc/wasm/wasm_exec.js"; -in -buildGoModule rec { - inherit pname version; - src = ../.; - subPackages = [ "cmd/hp_ssh" ]; - vendorHash = "sha256-3hZzDORAH+D4FW6SkOv3Enddd+q36ZALryvCPD9E5Ac="; - env.CGO_ENABLED = 0; - - nativeBuildInputs = [ go ]; - - buildPhase = '' - export GOOS=js - export GOARCH=wasm - go build -o hp_ssh.wasm ./cmd/hp_ssh - ''; - - installPhase = '' - mkdir -p $out - cp hp_ssh.wasm $out/ - cp ${wasmExecJs} $out/wasm_exec.js - ''; -}