From 04ef0aa44e6e6d8ff18ba3a7aa81bcff63e95437 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Thu, 15 May 2025 23:32:07 -0600 Subject: [PATCH 1/7] docs: add systemd agent service configuration to Polykey CLI guide --- .../running-the-agent-with-systemd.md | 193 ++++++++++++++++++ 1 file changed, 193 insertions(+) create mode 100644 docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md diff --git a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md new file mode 100644 index 0000000..f806bad --- /dev/null +++ b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md @@ -0,0 +1,193 @@ +# Polykey Agent: Service and Programs Module Documentation + +This guide introduces and explains the newly added `services` and `programs` +modules for managing the Polykey Agent using `systemd`. These modules were +introduced as part of a broader effort to improve automation, reliability, and +user experience across both user-level and system-wide contexts. + +--- + +## Background + +The Polykey Agent is a long-lived background process that facilitates secure +secret management and distributed key infrastructure. Traditionally, users had +to manually start the agent from the terminal. To streamline this, two modules +were introduced: + +- `programs`: Configures **user-level services** for personal development and + desktop use. +- `services`: Configures **system-level services** for shared machines and + server environments. + +These modules utilize `systemd`, a service manager used in most Linux +distributions. + +--- + +## What is `systemd`? + +`systemd` is the default init and service manager in most Linux distros. It +allows you to: + +- Start, stop, and restart background services. +- Automatically launch services at boot or login. +- View logs and monitor service health. + +`systemd` uses unit files (like `.service`) to define how services behave. + +--- + +## Key Concepts + +### User vs System Services + +| Mode | Controlled By | Suitable For | Config Path | +| ---------- | ------------- | ------------------------------- | ------------------------- | +| **User** | Regular user | Local development, personal use | `~/.config/systemd/user/` | +| **System** | Root/admin | Shared systems, production use | `/etc/systemd/system/` | + +The new modules are designed to target both these contexts. + +--- + +## Programs Module (User Services) + +The `programs` module sets up a user-level `systemd` service that: + +- Starts the agent on login. +- Runs the agent under the current user. +- Stores logs in the user's journal. + +### Setup Instructions (User Mode) + +1. Ensure the Polykey binary is installed and accessible via `$PATH`. +2. Copy the service file to: + + ```sh + mkdir -p ~/.config/systemd/user + cp polykey-agent.service ~/.config/systemd/user/ + ``` + +3. Enable and start the service: + + ```sh + systemctl --user daemon-reload + systemctl --user enable polykey-agent + systemctl --user start polykey-agent + ``` + +4. Verify it's running: + + ```sh + systemctl --user status polykey-agent + journalctl --user -u polykey-agent + ``` + +--- + +## Services Module (System Services) + +The `services` module sets up a root-owned service that: + +- Runs globally for all users. +- Is launched at boot. +- Is managed from `/etc/systemd/system/`. + +### Setup Instructions (System Mode) + +1. Copy the service file to: + + ```sh + sudo cp polykey-agent.service /etc/systemd/system/ + ``` + +2. Enable and start the service: + + ```sh + sudo systemctl daemon-reload + sudo systemctl enable polykey-agent + sudo systemctl start polykey-agent + ``` + +3. Check status: + + ```sh + sudo systemctl status polykey-agent + sudo journalctl -u polykey-agent + ``` + +--- + +## Configuration Details + +The service files can be customized: + +- `ExecStart` can point to any valid Polykey binary. +- `Environment` variables like `NODE_ENV`, `POLYKEY_DATA_PATH` can be passed in. +- Restart policies and timeouts can be modified. + +To override a system service without editing the base file: + +```sh +sudo systemctl edit polykey-agent +``` + +--- + +## Handling Secrets & Recovery Codes + +The new modules support secure handling of recovery codes and agent secrets: + +- Set environment variables or use configuration files in the home directory. +- Avoid running agents as root unless necessary. +- For system mode, ensure secrets are stored in restricted root-only paths. + +--- + +## Troubleshooting + +- **"Service not found"**: + + - Run `daemon-reload` after copying or editing unit files. + +- **"Permission denied"**: + + - Ensure system-level services are started with `sudo`. + +- **Service not starting**: + + - Run `journalctl -u polykey-agent` for logs. + +- **User services not auto-starting**: + + - Check that `linger` is enabled for the user: + + ```sh + sudo loginctl enable-linger $USER + ``` + +--- + +## Use Cases + +- **Developers**: Enable `programs` to automatically start the agent at login. +- **Sysadmins**: Deploy `services` module for always-on availability of the + agent across all users. +- **Security-sensitive installations**: Customize environment securely and + inspect logs via `journalctl`. + +--- + +## Next Steps + +- Finalize documentation with visual diagrams (systemd flow, unit layering). +- Incorporate examples of overriding default behavior. +- Validate this guide on different distros (e.g. Ubuntu, Fedora, Arch). + +--- + +## Related References + +- [systemd documentation](https://www.freedesktop.org/wiki/Software/systemd/) +- [Polykey PR #138](https://github.com/MatrixAI/Polykey-CLI/pull/138) +- [CLI Installation Guide](./installation.md) From 0413b4bfb78264920d9e7539458bf1d9b344181c Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Thu, 15 May 2025 23:45:49 -0600 Subject: [PATCH 2/7] docs: update sidebar --- sidebars.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/sidebars.ts b/sidebars.ts index a53815d..a0296c9 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -24,6 +24,7 @@ const sidebars: SidebarsConfig = { 'Getting-Started/polykey-cli/sharing-vaults', 'Getting-Started/polykey-cli/managing-multiple-nodes', 'Getting-Started/polykey-cli/using-environment-variables', + 'Gettin-Started/polykey-cli/running-the-agent-with-systemd.md', ], }, ], From aee4d397940389a9de49b067e55d4a94e3661245 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Thu, 15 May 2025 23:51:14 -0600 Subject: [PATCH 3/7] fix: correct sidebar path typo for agent systemd doc --- sidebars.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars.ts b/sidebars.ts index a0296c9..79bdbd3 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -24,7 +24,7 @@ const sidebars: SidebarsConfig = { 'Getting-Started/polykey-cli/sharing-vaults', 'Getting-Started/polykey-cli/managing-multiple-nodes', 'Getting-Started/polykey-cli/using-environment-variables', - 'Gettin-Started/polykey-cli/running-the-agent-with-systemd.md', + 'Getting-Started/polykey-cli/running-the-agent-with-systemd.md', ], }, ], From b32e5a80a1806d17d57cacb6c96dc82627fdfb47 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Thu, 15 May 2025 23:57:46 -0600 Subject: [PATCH 4/7] fix: correct sidebar doc ID for systemd agent guide --- sidebars.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sidebars.ts b/sidebars.ts index 79bdbd3..c6bc0dc 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -24,7 +24,7 @@ const sidebars: SidebarsConfig = { 'Getting-Started/polykey-cli/sharing-vaults', 'Getting-Started/polykey-cli/managing-multiple-nodes', 'Getting-Started/polykey-cli/using-environment-variables', - 'Getting-Started/polykey-cli/running-the-agent-with-systemd.md', + 'Getting-Started/polykey-cli/running-the-agent-with-systemd', ], }, ], From 4c010b5c3b8c5b572c0a6e0d2ce7d0fc52f63b41 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 21 May 2025 15:17:36 -0600 Subject: [PATCH 5/7] docs: address reviewer suggestions and fix NixOS section --- .../running-the-agent-with-systemd.md | 169 +++++++++--------- 1 file changed, 83 insertions(+), 86 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md index f806bad..d9201fd 100644 --- a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md +++ b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md @@ -5,8 +5,6 @@ modules for managing the Polykey Agent using `systemd`. These modules were introduced as part of a broader effort to improve automation, reliability, and user experience across both user-level and system-wide contexts. ---- - ## Background The Polykey Agent is a long-lived background process that facilitates secure @@ -14,20 +12,24 @@ secret management and distributed key infrastructure. Traditionally, users had to manually start the agent from the terminal. To streamline this, two modules were introduced: -- `programs`: Configures **user-level services** for personal development and +- **programs:** Configures user-level services for personal development and desktop use. -- `services`: Configures **system-level services** for shared machines and - server environments. +- **services:** Configures system-level services for shared machines and server + environments. These modules utilize `systemd`, a service manager used in most Linux distributions. +git st +:::note Note +On NixOS, Polykey is not configured through .service files, but +instead through the Home Manager or Nix configuration. See the NixOS integration +section below. +::: ---- - -## What is `systemd`? +## What is systemd? -`systemd` is the default init and service manager in most Linux distros. It -allows you to: +systemd is the default init and service manager in most Linux distros. It allows +you to: - Start, stop, and restart background services. - Automatically launch services at boot or login. @@ -35,11 +37,9 @@ allows you to: `systemd` uses unit files (like `.service`) to define how services behave. ---- - -## Key Concepts +### Key Concepts -### User vs System Services +**User vs System Services** | Mode | Controlled By | Suitable For | Config Path | | ---------- | ------------- | ------------------------------- | ------------------------- | @@ -48,75 +48,69 @@ allows you to: The new modules are designed to target both these contexts. ---- - -## Programs Module (User Services) +#### Programs Module (User Services) The `programs` module sets up a user-level `systemd` service that: - Starts the agent on login. - Runs the agent under the current user. -- Stores logs in the user's journal. +- Stores logs in the user’s journal. ### Setup Instructions (User Mode) 1. Ensure the Polykey binary is installed and accessible via `$PATH`. 2. Copy the service file to: - ```sh - mkdir -p ~/.config/systemd/user - cp polykey-agent.service ~/.config/systemd/user/ - ``` +```sh +mkdir -p ~/.config/systemd/user +cp polykey-agent.service ~/.config/systemd/user/ +``` 3. Enable and start the service: - ```sh - systemctl --user daemon-reload - systemctl --user enable polykey-agent - systemctl --user start polykey-agent - ``` - -4. Verify it's running: +```shell +systemctl --user daemon-reload +systemctl --user enable polykey-agent +systemctl --user start polykey-agent +``` - ```sh - systemctl --user status polykey-agent - journalctl --user -u polykey-agent - ``` +4. Verify it’s running: ---- +```shell +systemctl --user status polykey-agent +journalctl --user -u polykey-agent +``` -## Services Module (System Services) +#### Services Module (System Services) -The `services` module sets up a root-owned service that: +The services module sets up a root-owned service that: - Runs globally for all users. - Is launched at boot. - Is managed from `/etc/systemd/system/`. -### Setup Instructions (System Mode) +##### Setup Instructions (System Mode) 1. Copy the service file to: - ```sh - sudo cp polykey-agent.service /etc/systemd/system/ - ``` +```shell +sudo cp polykey-agent.service /etc/systemd/system/ +``` 2. Enable and start the service: - ```sh - sudo systemctl daemon-reload - sudo systemctl enable polykey-agent - sudo systemctl start polykey-agent - ``` +```shell +sudo systemctl daemon-reload +sudo systemctl enable polykey-agent +sudo systemctl start polykey-agent +``` 3. Check status: - ```sh - sudo systemctl status polykey-agent - sudo journalctl -u polykey-agent - ``` - ---- +```shell +sudo systemctl status polykey-agent +sudo journalctl -u polykey-agent +``` ## Configuration Details @@ -128,13 +122,14 @@ The service files can be customized: To override a system service without editing the base file: -```sh +```shell sudo systemctl edit polykey-agent ``` ---- +**Note for NixOS users:** These overrides are not applicable. See the next +section. -## Handling Secrets & Recovery Codes +### Handling Secrets & Recovery Codes The new modules support secure handling of recovery codes and agent secrets: @@ -142,52 +137,54 @@ The new modules support secure handling of recovery codes and agent secrets: - Avoid running agents as root unless necessary. - For system mode, ensure secrets are stored in restricted root-only paths. ---- +#### Troubleshooting -## Troubleshooting +- **“Service not found”:** -- **"Service not found"**: +* Run `daemon-reload` after copying or editing unit files. (Not needed in NixOS) - - Run `daemon-reload` after copying or editing unit files. +- **“Permission denied”:** -- **"Permission denied"**: +* Ensure system-level services are started with `sudo`. - - Ensure system-level services are started with `sudo`. +- **Service not starting:** -- **Service not starting**: +* Run `journalctl -u polykey-agent` for logs. - - Run `journalctl -u polykey-agent` for logs. +- **User services not auto-starting:** -- **User services not auto-starting**: +* Check that `linger` is enabled for the user: - - Check that `linger` is enabled for the user: - - ```sh - sudo loginctl enable-linger $USER - ``` - ---- +```shell +sudo loginctl enable-linger $USER +``` -## Use Cases +### NixOS Integration -- **Developers**: Enable `programs` to automatically start the agent at login. -- **Sysadmins**: Deploy `services` module for always-on availability of the - agent across all users. -- **Security-sensitive installations**: Customize environment securely and - inspect logs via `journalctl`. +On NixOS, service setup is handled via Home Manager or system configuration, not +.service files. Here’s a basic example of configuring Polykey in home.nix: ---- +```nix + polykey = rec { + enable = true; + passwordFilePath = "/home/user/.polykeypass"; + recoveryCodeOutPath = "/home/user/.polykeyrecovery"; + }; +``` -## Next Steps +- enable will activate the service. +- passwordFilePath provides the path to read the vault password. +- recoveryCodeOutPath sets the location to write recovery codes. -- Finalize documentation with visual diagrams (systemd flow, unit layering). -- Incorporate examples of overriding default behavior. -- Validate this guide on different distros (e.g. Ubuntu, Fedora, Arch). +**More references:** ---- +- Polykey Nixpkg (private) +- Home Manager Infra Docs -## Related References +**Use Cases** -- [systemd documentation](https://www.freedesktop.org/wiki/Software/systemd/) -- [Polykey PR #138](https://github.com/MatrixAI/Polykey-CLI/pull/138) -- [CLI Installation Guide](./installation.md) +- Developers: Enable `programs` to automatically start the agent at login. +- Sysadmins: Deploy `services` module for always-on availability of the agent + across all users. +- Security-sensitive installations: Customize environment securely and inspect + logs via `journalctl`. From 693435075dc251696975276252cade28a1b840b5 Mon Sep 17 00:00:00 2001 From: Christina Kelley Date: Wed, 21 May 2025 16:35:31 -0600 Subject: [PATCH 6/7] docs: fix broken sidebar link and clean build cache --- .../polykey-cli/running-the-agent-with-systemd.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md index d9201fd..12b7c42 100644 --- a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md +++ b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md @@ -18,13 +18,9 @@ were introduced: environments. These modules utilize `systemd`, a service manager used in most Linux -distributions. -git st -:::note Note -On NixOS, Polykey is not configured through .service files, but -instead through the Home Manager or Nix configuration. See the NixOS integration -section below. -::: +distributions. git st :::note Note On NixOS, Polykey is not configured through +.service files, but instead through the Home Manager or Nix configuration. See +the NixOS integration section below. ::: ## What is systemd? From 83b2a38127816d3137aaaab8944dd812c675ca5c Mon Sep 17 00:00:00 2001 From: Brynley Llewellyn-Roux Date: Mon, 2 Jun 2025 12:34:46 +1000 Subject: [PATCH 7/7] fix: ignore linting for note line --- .../polykey-cli/running-the-agent-with-systemd.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md index 12b7c42..2502377 100644 --- a/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md +++ b/docs/Getting-Started/polykey-cli/running-the-agent-with-systemd.md @@ -18,9 +18,14 @@ were introduced: environments. These modules utilize `systemd`, a service manager used in most Linux -distributions. git st :::note Note On NixOS, Polykey is not configured through +distributions. + + +:::note Note +On NixOS, Polykey is not configured through .service files, but instead through the Home Manager or Nix configuration. See -the NixOS integration section below. ::: +the NixOS integration section below. +::: ## What is systemd?