pshd(8) — Daemon

Read this manual locally with man 8 pshd, or download its roff source .

SYNOPSIS

pshd [-f config.yaml] [--check-config]

pshd --version

pshd accepts encrypted UDP connections from psh(1) and starts one shell or command per connection as an authorized Linux account. It runs as root in the foreground and writes diagnostics to standard error. It does not daemonize, create a PID file, generate host keys, or enable a service.

Remote authentication is public-key-only. Each host and user identity requires both Ed25519 and ML-DSA-87 components. DTLS 1.3 uses mandatory hybrid X25519 + ML-KEM-768 key exchange and ChaCha20-Poly1305 encryption. ALPN is exclusively psh/3; older peers and single-component identities cannot connect. There is no password or keyboard-interactive login method.

OPTIONS

-f config.yaml: Read this server YAML file. The default is /etc/psh/pshd.yaml. Installation prefix variables do not change this built-in default.
--check-config: Validate the complete configuration, host private identity, and all referenced authorized public identities, then exit without creating listeners or sessions. This requires root. It does not establish account eligibility, resolve or bind listeners, or test runtime cgroup capabilities.
--version: Print the daemon version and exit. This option does not require root.

REQUIREMENTS

The daemon requires Linux 5.14 or newer, cgroup v2, clone3(2) with CLONE_INTO_CGROUP, and permission to create root-owned per-connection cgroups below /sys/fs/cgroup and write cgroup.kill. Missing support or insufficient permissions rejects connection admission without a fallback. A container that permits configuration validation may still lack the required runtime capabilities.

The host private identity must already exist, be unencrypted, be root-owned, and have mode 0600 or stricter. Generate it explicitly using psh keygen -f /etc/psh/host_psh_hybrid.pem --no-passphrase and keep it separate from client identities. Raw public keys are used; no X.509 certificate is needed.

The configuration and authorized public files must be root-owned regular files without group/world write permission. Symlinks are rejected. Relative key paths resolve from the configuration directory. Keep containing directories administrator-controlled. See psh_config(5) for the complete schema and limits.

ACCOUNT POLICY

The requested account must exist and have an absolute usable home and an executable shell. An empty shell field defaults to /bin/sh. Shells named nologin or false, expired accounts or passwords, UID 0, and the reserved network-worker UID 65534 are rejected. Root login has no enabling option.

After authentication, the broker initializes supplementary groups, drops to the account's UID/GID, changes to its home, and executes its configured shell with a controlled environment. An empty command starts a login shell; otherwise the command string is interpreted by the shell's -c option. PAM integration is not provided.

PRIVILEGE SEPARATION

A root supervisor owns listeners, configuration, the host identity, and connection lifecycle. Each admitted connection has an unprivileged network worker and a privileged authentication and launch broker. Workers exec as UID/GID 65534 with no supplementary groups and a syscall filter. They hold no host private identity and cannot authorize users themselves.

The broker independently checks the complete authorized client pair and both signatures bound to the connection and exact session request. After launch, the broker drops privileges and execs a fresh relay to discard inherited host private-key memory. Supervisor-owned connection cgroups provide independent cleanup of descendant processes.

SIGNALS

SIGHUP: Load and validate replacement configuration and all keys before applying it. Invalid configuration or changed listeners leaves the previous configuration active. Listener changes require a restart.

: A successful reload cancels pending authentications. Removed users or identities terminate their sessions; still-authorized sessions survive. Replacing the host identity closes all existing sessions. Editing an authorization file alone does not terminate existing sessions until reload or restart.

SIGINT, SIGTERM: Stop the daemon and clean up its connections and remote processes.

LIMITS AND LIVENESS

Configuration permits at most 8 listeners, 32 accounts, and 16 authorized-key paths per account. Runtime limits include 64 total connections and 16 pending authentications. Queues and authentication timers are bounded.

Keepalives run every 15 seconds. A connection expires after 120 seconds without authenticated peer traffic and its remote process group is terminated. Client address migration requires encrypted return-path validation. The client coordinates DTLS traffic-key updates for both directions every hour or 1,048,576 authenticated application records sent and received combined, as observed by the client, after any pending TLS exchange or write completes. Lost server datagrams do not count toward this trigger. Upgrade both client and daemon; older daemons may still request overlapping updates. KeyUpdate does not perform fresh key agreement.

FILES

/etc/psh/pshd.yaml: Default server configuration.
/etc/psh/host_psh_hybrid.pem: Host private identity path used by the example configuration.
/etc/psh/authorized/: Administrator-managed public identities referenced by the example configuration.

EXIT STATUS

Return 0 for successful configuration validation, version output, or normal termination. Startup or configuration failures return 1; usage errors return 2.

EXAMPLES

pshd -f /etc/psh/pshd.yaml --check-config
pshd -f /etc/psh/pshd.yaml

CAVEATS

psh is experimental and has not undergone an external security audit. This daemon is not an SSH server and provides no password login, forwarding, file transfer, detached reattachment, or server migration.