Command line
MyOwnPKI has three programs. myownpki is the server and its administration commands.
myownpki-agent is the agent for Linux hosts. myownpki-ctl is reserved for a command-line client of
the REST API; in this release it only prints its version. Every program takes --version. Run myownpki
without a command to see its usage.
Exit codes of myownpki: 0 success, 1 the command failed, 2 wrong usage.
myownpki
Almost every command reads the configuration. The file is chosen by --config FILE, then by the
environment variable MYOWNPKI_CONFIG, then by the default /etc/myownpki/config.yaml (on Windows
%ProgramData%\MyOwnPKI\config.yaml). Run the commands that open the data directory as the service
user, for example runuser -u myownpki -- /usr/local/bin/myownpki ….
| Command | What it does | Details |
|---|---|---|
serve with --unseal |
Runs the server. It starts sealed. With --unseal it asks for the passphrase on this terminal once the listeners run. |
Operations §4 |
serve --dev --listen 127.0.0.1:9443 |
The UI prototype with sample data, no TLS, no login, loopback only. For looking at the UI, never for real use. | |
init with --stdin or --demo, --with-ca --ca-base-url URL, --admin-user NAME, --recovery-key-file FILE, --otpauth-file FILE |
Creates the instance: passphrase, recovery key, first admin, second factor. --stdin is for automation. --demo generates every secret into one file and marks the instance as a demo. --with-ca creates an online root and an intermediate for testing. |
Operations §3 |
config check |
Checks the configuration, prints what is in effect, and reads the secret and CA files of notify:. |
Troubleshooting |
healthcheck --timeout 5s |
Asks /healthz of the admin listener on this machine. Exit code 0 means healthy. A sealed server is healthy. |
Operations §4 |
db status, db migrate |
Shows the migration state; runs the migrations (they also run at start). | Operations §9 |
ca list, ca show NAME |
Lists the authorities, or shows one. | |
backup DIR |
A consistent copy of every database into the new directory DIR, while the server runs. |
Operations §6 |
backup verify DIR --checkpoint-key FP |
Runs every restore check on a backup and writes nothing. | |
backup scheduled DIR --keep N |
The timer’s run: backup into DIR/<UTC time>, verify, then prune. |
Operations §6.1 |
backup prune DIR --keep N --dry-run |
Keeps the newest N scheduled backups and deletes older complete ones; never touches anything else. --dry-run only shows what would go. |
|
restore DIR --checkpoint-key FP |
Restores into an empty or missing data directory, with the server stopped. Runs every check first. Run it as root, not as the service user: it builds its work copy next to the data directory (in /var/lib), which the service user cannot write to. Afterward chown -R myownpki:myownpki /var/lib/myownpki. |
Operations §6 |
audit verify with --scope S, --expect-head SEQ:HASH, --checkpoint-key FP |
Verifies the hash chain and the signatures of the audit logs. | Operations §4 |
import legacy DIR with --dry-run, --base-url URL, --root-key offline or online |
Imports a pki.sh directory. Use --dry-run first. |
Operations §5 |
user unlock NAME |
Unlocks a user who is locked out. | Operations §8 |
user reset-2fa NAME with --recovery-key, --new-auth-key, --otpauth-file PATH |
Gives a user a new second-factor secret. Reads the unseal passphrase, or with --recovery-key the recovery key, from standard input. |
|
passphrase change, passphrase reset |
A new passphrase, proven with the current one; or, if it is lost, proven with the recovery key. | Operations §7 |
notify test with --channel email or --channel webhook |
Sends a test message through the configured channels. | Monitoring |
myownpki-agent
The configuration is /etc/myownpki-agent/agent.yaml by default. --config FILE or the environment
variable MYOWNPKI_AGENT_CONFIG change it. The agent ignores HTTPS_PROXY and HTTP_PROXY.
| Command | What it does |
|---|---|
setup --server URL --ca-bundle FILE --root-sha256 HEX with --token-file FILE (a join token or an enrollment pass), --package-format deb, rpm or tarball, --webroot DIR, --hostname FQDN, --acme-directory URL, --low-ports |
Writes the configuration, the systemd unit and its drop-ins (keeping what you added by hand), enrolls the host, and only then enables and starts the service. Run as root. Every option is explained in Adding hosts. |
deployment add NAME with --recipe nginx, postfix, dovecot or proxmox, --name FQDN, --dir DIR or --fullchain, --key, --challenge webroot, standalone or dns-01, --webroot DIR, --hook, --check, --check-name NAME, --dns-provider NAME, --dns-type rfc2136 or cloudflare, --dns-credentials FILE, --dns-nameserver HOST[:PORT], --dns-zone ZONE, --dns-resolver IP[:PORT], --sandbox-write DIR, --low-ports, --acme-directory URL, --create-dirs, --dry-run, --restart |
Adds a deployment to agent.yaml and makes the systemd drop-ins match, in one step. --dry-run shows a diff and writes nothing. Run as root; needs agent 0.3.5, and 0.3.7 for the --dns-* flags and --check-name. Every flag is in Adding hosts; the recipes are on Recipes; dns-01 and wildcard names are on dns-01 and wildcard certificates. |
deployment list, deployment remove NAME with --prune-paths, --dry-run, --restart |
Lists the deployments of agent.yaml (no root needed), or removes one and recomputes the drop-ins. Deployed files and the agent’s state are not touched. |
sandbox sync with --dry-run, --adopt or --prune |
Recomputes 10-paths.conf and 20-low-ports.conf from agent.yaml. Entries it cannot explain are kept and reported; --adopt records them under sandbox.write, --prune drops them. |
enroll --token-file FILE |
Enrolls this host once. setup calls it for you. |
run |
The service. systemd starts it. |
status |
The agent’s identity, the enrollment state and every deployment with its last error. |
config check |
Checks agent.yaml, names every problem, and shows the effective sandbox and whether the drop-ins match it. Since 0.3.7 it also lists each DNS credentials file with its state (ok, missing, wrong mode, wrong owner, …) and never prints a content; it exits 1 when a deployment uses a file that cannot be used. |
myownpki-ctl
myownpki-ctl --version prints the version. The command-line client for the
REST API and the offline mode for root ceremonies are not
implemented yet; use curl with an API token, or pki.sh for an offline root.