psh_config(5) — Configuration

Read this manual locally with man 5 psh_config, or download its roff source .

NAME

psh_config - client and server YAML configuration for pirate-shell

psh(1) and pshd(8) use separate, strict YAML schemas with version: 1. The schema version is independent of the psh/3 wire protocol. Unknown fields are errors. Fields and alias names are case-sensitive.

The default client file is ~/.config/psh/config.yaml; use psh -F to select another file. The default file may be absent, in which case built-in identity and trust-store paths apply. An existing default file or explicitly selected file must pass validation; CLI overrides do not bypass schema checks.

The default server file is /etc/psh/pshd.yaml; use pshd -f to override it. All server fields are required. The daemon never creates missing identities.

YAML RULES

Each file must contain one mapping document with no YAML version or tag directives. Anchors, aliases, explicit tags, merge keys, duplicate mapping keys, unknown fields, multiple documents, and NUL bytes are rejected. Values are interpreted by the schema, not YAML implicit type resolution.

Files are limited to 65,536 bytes, 4096 parsed nodes, and nesting depth 16. Scalar values must be shorter than 1024 bytes. Schema strings must be nonempty and contain no ASCII control characters. Resolved file paths are at most 1023 bytes; hostnames, aliases, and listen strings are at most 255 bytes; usernames are at most 63 bytes.

Configuration files must be regular files, not symlinks, and must not be group/world writable. Server files must be owned by root; client files must be owned by the client's effective user. Keeping containing directories protected is also the administrator's or user's responsibility.

PATHS

All relative file paths inside YAML resolve against the directory containing that configuration file. Absolute paths remain absolute. No tilde, environment-variable, glob, or shell expansion is performed. For example, identity: id_psh_hybrid.pem in /home/alice/.config/psh/config.yaml names /home/alice/.config/psh/id_psh_hybrid.pem.

Relative paths supplied as command-line options instead use the process's current working directory.

CLIENT SCHEMA

version: Required scalar with exact value 1.
identity: Required path to the global paired private identity. A host entry or -i can override it. The file must be owned by the effective user and have mode 0600 or stricter. Both identity components must be plaintext or both encrypted with one local passphrase. Batch connections cannot unlock encrypted identities.
known_hosts: Required path to the host trust store. This is a separate strict text format, not YAML or OpenSSH known_hosts. The store and its protected .lock sidecar must be kept together. The client creates a missing store, but a custom parent directory must already exist. Override with --known-hosts.
hosts: Optional mapping of at most 32 aliases to host mappings. An empty mapping is allowed. Each entry accepts only the fields below.

Host mapping fields

hostname: Required connection hostname or IP address. Specify the port separately. IPv6 addresses here do not use listen-address brackets.
user: Required remote account name: alphanumeric characters, underscore, hyphen, and period. An explicit user in user@alias overrides it. Server account policy still applies.
port: Optional decimal UDP port from 1 through 65535. Default: 2222. Override with -p.
identity: Optional paired private-identity path. Default: global identity. This relative path also resolves from the configuration directory, not the host entry or working directory. Override with -i.

Selection and defaults

An exact alias match supplies hostname, user, port, and identity. An explicit target user overrides the alias user; command-line port, identity, and trust-store options override their configured values. Without an alias, the target itself is the hostname and the local effective account name is the default remote user. There is no wildcard matching or alias chaining.

Without a client file, identity defaults to ~/.config/psh/id_psh_hybrid.pem and the trust store to ~/.config/psh/known_hosts, using the effective account's home directory from the account database. The default configuration lookup separately uses HOME when nonempty, falling back to that account's home. It must be absolute. XDG_CONFIG_HOME is not used.

psh host trust and psh host forget do not load this configuration or expand aliases. Supply the actual hostname, port, and any custom trust-store path explicitly.

Client example

version: 1
identity: id_psh_hybrid.pem
known_hosts: known_hosts
hosts:


  lab:


    hostname: lab.example.net


    user: alice


    port: 2222


  alternate:


    hostname: other.example.net


    user: alice


    identity: alternate_psh_hybrid.pem

SERVER SCHEMA

version: Required scalar with exact value 1.
listen: Required sequence of 1 through 8 distinct listen strings, each specifying host:port or [IPv6]:port. The port must be decimal, 1 through 65535; whitespace is forbidden. Hostnames are resolved when creating listeners; explicit addresses avoid resolution ambiguity. Use 0.0.0.0 for IPv4 wildcard and [::] for IPv6 wildcard. IPv6 listeners are IPv6-only, so configure both for dual-stack service. Listener changes cannot be applied by reload.
host_key: Required path to an unencrypted paired host private identity. It must be a root-owned regular file with mode 0600 or stricter; symlinks are rejected. Generate explicitly with psh keygen -f PATH --no-passphrase. The daemon uses raw public keys and needs no X.509 certificate.
users: Required mapping of 1 through 32 usernames to account mappings. Names may contain alphanumeric characters, underscore, hyphen, and period. The literal name root is forbidden. At session launch, accounts with UID 0 or reserved UID 65534, expired accounts/passwords, and disabled shells are also rejected.

Account mapping fields

authorized_keys: Required sequence of 1 through 16 distinct public-identity file paths. Each file must contain exactly one complete paired SPKI PEM identity: Ed25519 followed by ML-DSA-87. Components from different files cannot be combined for authorization. These are not OpenSSH authorized_keys lines.

: Files must be root-owned regular files without group/world write permission; symlinks are rejected. Key files are bounded to 64 KiB and are strictly parsed. Directories should remain administrator-controlled. Only these public files, not client private identities, belong on the server.

Server example

version: 1
listen:


  - '0.0.0.0:2222'


  - '[::]:2222'
host_key: host_psh_hybrid.pem
users:


  alice:


    authorized_keys:


      - authorized/alice.pub.pem

VALIDATION AND RELOAD

pshd -f FILE --check-config requires root and validates the server schema, host private identity, and all referenced authorized public identities. It does not bind listeners, establish account eligibility, or verify runtime cgroup support.

SIGHUP loads and validates the complete replacement before applying it. Invalid configuration or changed listeners preserves the old configuration. A successful reload cancels pending authentications and terminates sessions whose user or complete identity is no longer authorized. Host-key replacement closes all existing sessions. Listener changes require restarting the daemon.

SECURITY POLICY

There are no configuration switches for password or keyboard-interactive login, root login, weaker crypto, or legacy peers. Both endpoints require psh/3 paired identities and complete-pair host trust. Local key passphrases protect private files and are never a remote login method.

FILES

~/.config/psh/config.yaml: Default client configuration.
/etc/psh/pshd.yaml: Default server configuration.
/usr/local/share/psh/examples/client.yaml: Installed client example with default prefix.
/usr/local/share/psh/examples/server.yaml: Installed server template with default prefix.