Reference
CLI reference
podos is one binary with subcommands. Every command prints its own help:
podos --help
podos deploy --help
podos help env set
Flags are written with two dashes (--env); one dash also works. The common
ones also have a one-letter form (-e); see Short flags. For env,
secret, file and logs, flags may come before or after the other arguments.
Command overview
| Command | Purpose | Status |
|---|---|---|
podos setup |
Prepare this server: data directory, secrets key, database (Available internal CA, first admin token, network, proxy and TLS settings) | Available |
podos daemon |
Run the daemon | Available |
podos init |
Write a starter manifest | Available |
podos manifest validate |
Validate the manifest and show what would be deployed | Available |
podos deploy |
Deploy the application | Available |
podos ps |
List the containers of an environment | Available |
podos logs |
Show the logs of a service | Available |
podos down |
Remove an environment's deployment, with its data (--delete-volumes Available) |
Available |
podos env |
Manage env values (set, list, unset; create Available) |
Available |
podos secret |
Manage secrets (set, list, unset) |
Available |
podos file |
Manage files mounted into containers (set, list, get, unset) |
Available |
podos cert |
Manage uploaded TLS certificates (set, list, remove) |
Available |
podos image pull |
Pull an image into a local content store (developer command) | Available |
podos version |
Print the version, limits or licenses | Available |
podos login |
Save the address, CA and token of a server as a context | Available |
podos logout |
Delete the saved token of a context | Available |
podos context |
List and switch between servers (list, use, remove) |
Available |
podos whoami |
Show which token the selected server sees | Available |
podos token |
Manage API tokens (create, list, revoke) |
Available |
podos ca fingerprint |
Print the fingerprint of the server's CA | Available |
podos releases |
List the releases of an environment | Available |
All commands in this list are in the code on the main branch; there are no release binaries yet.
Exit codes
All commands use the same exit codes:
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | The operation failed or was refused, including a server certificate that does not match the saved CA. Fix the cause and try again. |
| 2 | Usage error: unknown command or flag, missing argument. |
| 3 | Try again later: the daemon is unreachable, busy or rate limited, another deployment is running, you disconnected before the result, or a followed log stream was replaced by a redeploy. |
Connecting to the daemon
On the server, client commands talk to the daemon over a Unix socket that only root can use, so run them as root. Available From another machine they talk to the daemon's HTTPS API with a token saved in a context; see Several servers with contexts.
A command picks its server in this order, first match wins:
- the flag
--context NAMEof the command; - the global flag
--socket PATH, before the command (podos --socket /run/podos/podos.sock ps), or the command's own--socketflag: the local socket; - the environment variable
PODOS_CONTEXT; - the environment variable
PODOS_SOCKET: the local socket; - Available the
contextkey of the manifest for the environment (see Binding an environment to a server); - Available the current context, set by
podos login --useorpodos context use. A firstpodos loginalso sets it, but only when there is no current context and no podos daemon answers on this machine's local socket; - the local socket.
--context and --socket together are a usage error. The context name
local is built in and always means the daemon socket on this machine.
The local socket is found in this order: --socket, PODOS_SOCKET,
$PODOS_RUN_DIR/podos.sock, /run/podos/podos.sock.
Available Every command that talks to a server other than the local socket prints on standard error which context and URL it uses and what chose it.
Contexts are kept in $XDG_CONFIG_HOME/podos/contexts.json (default
~/.config/podos/contexts.json), mode 0600, in a directory with mode 0700.
The file holds tokens; a file that others can read or write is refused.
Proxy environment variables are ignored for server connections.
Choosing the project and environment
deploy reads the manifest. ps, logs, releases, down, env and secret work
on one project and environment, chosen like this:
- Project:
--project, else theprojectof the manifest in--dir(default: the current directory). - Environment:
--env, else the manifest's only environment. When the manifest declares several,--envis required. When the project comes from--projectand differs from the manifest's,--envis required.
So in an application directory with a single-environment manifest, no flags
are needed. Elsewhere, give both: podos ps --project shop --env prod.
Available When both are missing, the error names both, for example
--project is required and --env is required: there is no manifest in the application directory to take them from.
These flags are shared by ps, logs, releases, down, env and secret:
| Flag | Meaning |
|---|---|
-d, --dir DIR |
Application directory holding the manifest. Default: the current directory. |
-p, --project NAME |
Project. Default: from the manifest. |
-e, --env NAME |
Environment. Default: the manifest's only environment. |
--socket PATH |
Daemon socket. Default: see above. |
-c, --context NAME |
Available Server to use: a context made with podos login, or local. Default: see Connecting to the daemon. |
Available podos cert takes the same flags. deploy takes --dir, --env,
--socket and --context.
Short flags
The common flags have a one-letter form. A letter means the same in every command that has the long flag.
| Short | Long | Commands that have it |
|---|---|---|
-p |
--project |
ps, logs, releases, down, env, secret, file, cert, init, token create |
-e |
--env |
deploy, manifest validate, ps, logs, releases, down, env, secret, file, cert, token create |
-c |
--context |
every command that talks to a server, including deploy, whoami and token |
-d |
--dir |
deploy, manifest validate, init, ps, logs, releases, down, env, secret, file, cert |
-j |
--json |
ps, releases, file list, cert list, token list, context list, whoami, manifest validate, image pull |
-y |
--yes |
down, the command that asks for confirmation |
-f |
--follow |
logs |
-t |
--tail |
logs |
-r |
--replica |
logs |
-h is help. Help prints both forms on one line, for example
-e, --env string.
When you give both forms of one flag, the last one wins. Flags that delete
data or weaken security (--delete-volumes, --raw, --secrets-write),
--socket, and every flag of podos daemon and podos setup have no short
form on purpose, so that a typo cannot trigger them.
podos logs web -p demo -e prod -f -t 20
podos setup
podos setup [flags]
Run once, as root, on the server. Creates the data directory (mode 0700),
the secrets key, the state database, Available the internal certificate
authority (CA) and the first admin token. It also checks that crun,
conmon, systemctl and systemd-run are installed and prints their
versions. Available It also checks that nft is installed and that the
kernel is Linux 5.6 or newer.
Available The first admin token is printed once, and only to a terminal, or
written to the file named by --token-file. Only its hash is stored. The
CA fingerprint is printed on every run; compare it when you run
podos login from another machine.
Running it again on a set-up server changes nothing and prints no token,
unless you pass --new-admin-token. It never creates a new key or database
next to an existing one, and refuses while a daemon runs. It needs no
network access.
| Flag | Meaning |
|---|---|
--data-dir DIR |
Data directory. Default: $PODOS_DATA_DIR, then /var/lib/podos. |
--listen ADDR:PORT |
Available Save the HTTPS listen address of podos daemon, for example 0.0.0.0:8443. |
--tls-name NAME |
Available Save a DNS name or IP address of this server for the HTTPS certificate. Repeatable. Needed with --listen on all interfaces. |
--token-file PATH |
Available Write the admin token to this absolute path (mode 0600, never over an existing file) instead of printing it. Required when standard output is not a terminal. |
--new-admin-token |
Available Create another admin token on a server that is already set up. |
--web |
Available Do the first setup in a browser: prepare the server, create no admin token, and print the address and a one-time setup code. Needs --listen and --tls-name. See below. |
--web-ui on|off |
Available Serve the web UI on the HTTPS listener. Saved; default on. |
--ingress on|off |
Available Serve domains through the built-in proxy. Saved; default on. |
--http-listen ADDR:PORT |
Available Save the proxy's HTTP address. Default :80. |
--https-listen ADDR:PORT |
Available Save the proxy's HTTPS address. Default :443. |
--acme-email EMAIL |
Available Enable tls = "auto" (Let's Encrypt): save EMAIL as the contact and agree to the certificate authority's terms of service (https://letsencrypt.org/repository/). Only this setting enables auto. |
--network-pool CIDR |
Available The range application networks are carved from, in /24 slices. Default 10.88.0.0/16; it must be inside a private range. |
--strict-egress |
Available Containers may not reach private networks, other than those given with --allow-egress. |
--allow-egress CIDR |
Available With --strict-egress: a prefix containers may still reach. Repeatable. |
--reset NAME |
Available Turn a saved setting off again: listen, http-listen, https-listen, acme-email, network-pool, strict-egress, allow-egress. Repeatable. An empty flag value never resets anything. |
--check-state |
Available Check that this binary can open the state database in the data directory, without changing it, and exit. Read-only; the install script uses it before an upgrade. |
--print-modprobe-blacklist |
Available Print the modprobe blacklist for this host and exit. Read-only; the install script uses it to write /etc/modprobe.d/podos-blacklist.conf. |
Available With --web (and --listen ADDR:PORT --tls-name NAME) the first
setup is finished in a browser. podos setup prepares everything that cannot
be done remotely, creates no admin token, and prints the address, a one-time
setup code (30 minutes, paused after every five wrong attempts, void after 40)
and the CA fingerprint. The admin token is shown once, at the end of the
wizard. The web UI is served by the HTTPS listener; --web-ui off turns that
off. See Web UI. --web cannot be combined with
--token-file or --new-admin-token. While the setup is pending, running
podos setup --web again issues a new code.
Settings are saved and merged: a flag changes only its own setting. They are
saved in settings.json in the data directory.
sudo podos setup --acme-email admin@example.com
sudo podos setup --strict-egress --allow-egress 10.0.5.0/24
sudo podos setup --reset strict-egress
Without --acme-email, a route with tls = "auto" is reported as broken in
podos ps and everything else works. Let's Encrypt has only been tested
against a test ACME server, not yet against the real service.
Back up the secrets key and the database together; secrets cannot be recovered without the key.
Available After its normal output, podos setup prints a warning on
standard error when Docker's firewall drops forwarded packets by default,
with the steps that fix it. It also checks incoming packets, recognises ufw
and firewalld, and prints the exact commands for each. The exit code does
not change, and Podos never changes another firewall. See
Next to Docker or another firewall.
podos daemon
podos daemon [flags]
Runs the daemon until it receives SIGINT or SIGTERM. Run it as root, after
podos setup. It listens on a Unix socket (podos.sock, mode 0600, root
only; root there is an administrator). Available With --listen it also
serves the API over HTTPS for remote use with bearer tokens; without it, no
TCP port is open. The HTTPS certificate comes from the internal CA, covers
the --tls-name names, and is renewed and reloaded without a restart. Plain
HTTP is never offered. Available The same address serves the
web UI unless --web-ui off. Containers keep running when the daemon stops; when
it starts again it finds them. Available The daemon also runs the built-in
proxy on ports 80 and 443 (see --ingress).
| Flag | Meaning |
|---|---|
--data-dir DIR |
Data directory. Default: $PODOS_DATA_DIR, then /var/lib/podos. |
--run-dir DIR |
Runtime directory holding podos.sock. Default: $PODOS_RUN_DIR, then /run/podos. |
--listen ADDR:PORT |
Available Serve the API over HTTPS on this address, for example 0.0.0.0:8443. Default: $PODOS_LISTEN, then the setting saved by podos setup --listen, then off. |
--tls-name NAME |
Available DNS name or IP address clients use for this server. The certificate covers it and other Host names are refused. Repeatable. Default: $PODOS_TLS_NAMES, then the saved setting, then the listen address. |
--ingress on|off |
Available Serve domains through the built-in proxy. Default: the setting saved by podos setup --ingress, then on. |
--web-ui on|off |
Available Serve the web UI on the HTTPS listener. Default: the saved setting, then on. Never served on the Unix socket. |
--http-listen ADDR:PORT |
Available Proxy address for HTTP. Default: the saved setting, then :80. |
--https-listen ADDR:PORT |
Available Proxy address for HTTPS. Default: the saved setting, then :443. |
--acme-directory URL |
Available ACME directory to use, https only. Default: Let's Encrypt production. For example Let's Encrypt staging or a private CA. Flag only; podos setup does not save it. |
--acme-ca-file PATH |
Available PEM file with the only root certificates trusted for the ACME connection, instead of the system roots (a private CA). Use an absolute path. The file must be a regular file, not a symbolic link, owned by root or the daemon's user, and not writable by group or others; its directory must not be writable by group or others either, so a file in /tmp is refused. Flag only. |
--system-reserve-memory SIZE |
Available Memory kept for the system and out of the containers' ceiling, for example 512M or 1G. Default: 10% of the server's memory, at least 256 MiB and at most 2 GiB. Flag only. |
--min-free-disk SIZE |
Available Free space on the data directory's file system below which deploys and image pulls are refused, for example 2G. Default: the larger of 1 GiB and 5% of the file system, at most 10 GiB. Flag only. |
--files-memory SIZE |
Available Size of the memory file system that holds secret files and templates with secrets, for example 64M. Counted inside the system reserve and at most half of it. Default: 2% of the server's memory, at least 16 MiB and at most 256 MiB. Plain files go to the data disk. Flag only. See Limits. |
--build-timeout DURATION |
Available Deadline of one build on this server, for example 20m. Between 1 minute and 6 hours. Default 15m. Flag only. |
--build-memory SIZE |
Available Memory ceiling of the builder, all builds together, for example 2G. At least 256 MiB. Default: half of the server's memory, at least 512 MiB and at most 8 GiB. Flag only. |
--build-cache-max SIZE |
Available Largest size of the build cache, for example 5G. At least 256 MiB. Default 10 GiB. Flag only. |
--build-context-max SIZE |
Available Largest source a build accepts, for example 100M. At least 1 MiB. Default 256 MiB. Flag only. |
--build-parallel N |
Available Builds that run at once, 1 to 8. Default: the number of CPUs, at most 4. Sources are always received in parallel. Flag only. |
--build-tool-dir DIR |
Available Directory searched for buildkitd, buildctl and crun before /usr/local/lib/podos/bin. For development; absolute path; repeatable. |
--network-prefix PREFIX |
Available Interface name prefix of the application networks. For development; default pd. |
--network-table NAME |
Available nftables table name. For development; default podos. |
--registry-allow-private HOST:PORT |
Allow a registry on an internal network. For development; repeatable. |
--registry-plain-http HOST:PORT |
Allow a registry over plain HTTP. For development; repeatable. |
Without the two registry flags, registries on internal addresses and plain
HTTP are refused. A plain-HTTP registry must also be listed with
--registry-allow-private, unless it is a loopback address such as
127.0.0.1:5000.
Available The install script installs a systemd
unit that runs podos daemon without flags. The settings then come from
podos setup. The flags above marked "flag only", such as the build flags,
are not saved by podos setup. To use one, put it in a drop-in file
(systemctl edit podos) that clears and sets ExecStart, for example:
[Service]
ExecStart=
ExecStart=/usr/local/bin/podos daemon --build-parallel 2
The unit file itself is replaced on upgrade; a drop-in is kept.
How builds use these limits is described in Build from source.
podos init
podos init [flags]
Writes a starter podos.toml (or podos.yaml) into the application
directory. It never overwrites an existing manifest. With a Dockerfile in
the directory the service uses build = "."; otherwise you fill in
image. With several environments it also writes an override file per
environment, holding only comments that show an example.
| Flag | Meaning |
|---|---|
-d, --dir DIR |
Application directory. Default: the current directory. |
-p, --project NAME |
Project name. Default: the directory name, when it is a valid name. |
--environments LIST |
Comma-separated environments, for example test,prod. Default: a single prod environment. |
--format FORMAT |
toml or yaml. Default: toml. |
podos init --project shop --environments test,prod
podos manifest validate
podos manifest validate [flags]
Loads podos.toml, podos.yaml or podos.yml from --dir, with any
podos.<environment>.* override files, and reports every problem found.
On success it prints what would be deployed in each environment. It works
offline and needs no daemon.
| Flag | Meaning |
|---|---|
-d, --dir DIR |
Application directory. Default: the current directory. |
-e, --env NAME |
Validate one environment. Default: all. |
-j, --json |
Print the resolved manifest as JSON, one line per environment. |
Exit code 0 when valid, 1 when problems were found.
podos deploy
podos deploy [flags]
Validates the manifest locally, sends the resolved manifest for --env to
the daemon and follows the progress until the release is active or has
failed. With several environments declared, --env is required.
Press Ctrl+C to disconnect: the daemon finishes the deployment anyway; check
podos ps. Available A build in progress is cancelled on the server.
Available A service with build = "DIR" is built on the server first. The
directory is packaged (inside a Git work tree the files Git does not ignore,
otherwise every file; then .dockerignore is applied), uploaded, and built
with BuildKit from its Dockerfile while the build log is shown. The release
uses the image that came back. A failing build stops the deploy and the
running release stays. Without a manifest, a directory with a Dockerfile
is deployed as service web of a project named like the directory. See
Build from source.
| Flag | Meaning |
|---|---|
-d, --dir DIR |
Application directory. Default: the current directory. |
-e, --env NAME |
Environment to deploy. Required when the manifest declares several. |
--socket PATH |
Daemon socket. |
-c, --context NAME |
Available Server to use. See Connecting to the daemon. |
| Exit code | Meaning |
|---|---|
| 0 | The release is active. |
| 1 | The release failed or was refused (failed, invalid, manifest problems). Available Also a build that failed. Fix it and deploy again. |
| 2 | Usage error. |
| 3 | Try again later: daemon unreachable or busy, another deployment in progress, or you disconnected and the outcome is not known yet. Available Also a full build queue or a build that waited too long. |
When a deployment fails, the error shows the last lines of the failing container's output. The values of the service's secrets are replaced in those lines on a best-effort basis only: encoded forms, values shorter than 4 characters and partial values are not caught.
Available A service with build is refused when the server has no BuildKit or
its crun is older than 1.15 (the message says so; image still works).
Available A release is refused when a published port is in use on the server,
when tls = "cert:NAME" names a certificate that does not exist or does not
cover the domains, or when a domain belongs to another project. The error
names the service and the value. See Limits.
podos ps
podos ps [flags]
Lists the containers of the project and environment: service, replica, container ID, release, status, Available ready, restarts, and start time (UTC). A stopped container shows its exit code and reason.
Available READY is yes, starting or no, and - until the daemon
has checked the containers once after it started. RESTARTS is the number of
consecutive failures before this container. Below the table, podos ps
lists the services that are not ok, with the class of their last error, and
findings about the project's domains (for example a missing certificate
or tls = "auto" without --acme-email).
| Flag | Meaning |
|---|---|
-j, --json |
Print the daemon's answer as JSON. |
-d, --dir, -p, --project, -e, --env, --socket, -c, --context |
See Choosing the project and environment. |
podos logs
podos logs [flags] SERVICE
Shows the output of the containers of SERVICE, merged in time order. Each
line starts with the service and replica (web/0); stderr lines are marked
with ! after the replica (web/0!).
| Flag | Meaning |
|---|---|
-t, --tail N |
Lines per replica to start with: 0 to 10000, or all. Default 100. 0 with --follow shows only new lines. |
-f, --follow |
Keep streaming new lines until Ctrl+C, until the containers exit, or until a redeploy replaces them. |
--since DURATION |
Only lines newer than this, for example 10m or 2h. |
-r, --replica N |
Only this replica. Default: all. |
--timestamps |
Show the time of each line (UTC). |
--raw |
Print bare lines, without prefix or cleaning of control characters. For pipes only, never to a terminal. |
-d, --dir, -p, --project, -e, --env, --socket, -c, --context |
See Choosing the project and environment. |
Container output is untrusted: control characters are replaced by ?
unless you pass --raw. Container output can contain secrets by design;
podos logs shows it as the container wrote it.
With --follow, the command ends with exit code 3 when a redeploy replaces
the containers it follows; run it again to follow the new ones.
podos logs web --tail 20 --timestamps
podos logs web -f --tail 0
podos logs web --replica 1 --since 10m
podos logs web -p demo -e prod -f -t 20 # the same flags, short forms
podos down
podos down [flags]
Stops and removes all containers of the project and environment and
deletes the environment: its releases and its env values and secrets,
which cannot be recovered. The project itself is kept. Available It also
removes the environment's network, its domains, its published ports and its
uploaded certificates.
Volume data is kept on the server unless you pass --delete-volumes.
You are asked to type the environment name to confirm, unless you pass
--yes. When standard input is not a terminal, --yes is required.
| Flag | Meaning |
|---|---|
-y, --yes |
Do not ask for confirmation. |
--delete-volumes |
Available Also delete the data of the environment's volumes. It has no short form. |
-d, --dir, -p, --project, -e, --env, --socket, -c, --context |
See Choosing the project and environment. |
podos env
Env values are stored per project and environment, in clear text, and
used in the manifest as ${env.NAME}. Setting a value creates the project
and environment on the server if needed.
podos env set [flags] KEY=VALUE...
podos env list [flags]
podos env unset [flags] KEY...
podos env create [flags]
podos env set LOG_LEVEL=info WORKERS=4
podos env list --env test
podos env unset WORKERS
env list shows name, update time (UTC) and value. Names match
[A-Za-z_][A-Za-z0-9_]*, at most 256 characters, and must not start with
PODOS_.
Values given as arguments appear in your shell history and in the process
list of the machine. Put secrets in podos secret set instead.
Available env create creates the environment in the project and does
nothing if it exists. It needs a project-admin or admin token, because
a deploy token may only use environments that exist; only an admin creates a
project. As root on the local socket you are an admin.
podos env create --project shop --env test
Flags: -d, --dir, -p, --project, -e, --env, --socket, -c, --context; see
Choosing the project and environment.
podos secret
Secrets are stored encrypted and are write-only: they cannot be read back
through Podos. They reach containers as ${secret.NAME}.
podos secret set [flags] NAME
podos secret list [flags]
podos secret unset [flags] NAME...
secret set reads the value from standard input when it is not a terminal
(one trailing newline is removed), or asks for it twice without echo on a
terminal. The value is never accepted as an argument or environment
variable, and never printed.
podos secret set DB_PASSWORD # prompted twice, no echo
podos secret set TLS_KEY < key.pem # from a file
podos secret list # names and update times only
podos secret unset DB_PASSWORD
Flags: -d, --dir, -p, --project, -e, --env, --socket, -c, --context; see
Choosing the project and environment.
podos file
Available Files are stored per project and environment and mounted into
services with files.NAME in the manifest, read-only. Setting a file creates
the project and environment on the server if needed. See
Files in containers.
podos file set [flags] NAME PATH
podos file list [flags]
podos file get [flags] NAME
podos file unset [flags] NAME...
podos file set NGINX_CONF ./default.conf # a plain file
podos file set --secret TLS_KEY ./site.key # encrypted, never shown again
generate-config | podos file set APP_CONFIG - # from standard input
podos file list
podos file get NGINX_CONF
podos file unset NGINX_CONF
file setstores the contents of the local file PATH, or of standard input for-, which must not be a terminal. A file is at most 1 MiB. With--secretthe file is stored encrypted, mounted from memory only and never shown again; that needs permission to write secrets, and the file must not be empty. The kind of a name cannot change: remove the file first. It warns when a plain file looks like a secret (a key name, a private key, a URL with a password).file listshows name, kind (plain or secret), size, a short digest, the update time (UTC) and the services of the running release that mount each file. The digest of a secret file is that of its encrypted form, so it changes at everyfile set. Contents are never listed.file getwrites a plain file to standard output. A secret file is never shown, to anyone. To a terminal only clean text is printed (valid UTF-8, no control characters other than newline and tab); for anything else redirect to a file or a pipe, or use--raw.file unsetremoves files without asking for confirmation. Running containers keep what they have and a rollback still mounts what the old release pinned, but the next deploy that names a removed file is refused until it is set again. Removing a secret file needs permission to write secrets.
A change takes effect at the next podos deploy: a release pins the contents
of its files.
| Flag | Meaning |
|---|---|
--secret |
file set: store the file encrypted and never show its content again. It has no short form. |
-j, --json |
file list: print the files as JSON. |
--raw |
file get: print the bytes even to a terminal, without checking them. It has no short form. |
-d, --dir, -p, --project, -e, --env, --socket, -c, --context |
See Choosing the project and environment. |
podos cert
Available Uploaded TLS certificates belong to a project and environment. A
service uses one with tls = "cert:NAME".
podos cert set [flags] NAME
podos cert list [flags]
podos cert remove [flags] NAME...
cert set uploads the certificate chain (--cert, PEM, leaf first) and its
unencrypted private key (--key, PEM) under NAME. The key is sent to the
server, stored encrypted and never shown again. The certificate must cover
the service's domains when you deploy. It needs permission to write secrets.
cert set takes effect at once, without a redeploy.
cert list shows the names, the hosts covered and the expiry, never key
material; --json prints it as JSON.
cert remove removes certificates. The routes of services that still use one
are not served at once: their HTTPS handshakes fail and podos ps reports
the missing certificate; other routes are unaffected. The next
podos deploy of such a service is refused until the certificate exists
again.
| Flag | Meaning |
|---|---|
--cert FILE |
cert set: PEM file with the certificate chain, leaf first. |
--key FILE |
cert set: PEM file with the unencrypted private key. |
-j, --json |
cert list: print the certificates as JSON. |
-d, --dir, -p, --project, -e, --env, --socket, -c, --context |
See Choosing the project and environment. |
podos cert set shop-cert --cert fullchain.pem --key privkey.pem
podos cert list
podos cert remove shop-cert
podos image pull
podos image pull [flags] REFERENCE
A developer and diagnostic command. Resolves REFERENCE on its registry,
downloads the manifest, config and layers into the content store under
--root, and verifies every blob against its digest. Anonymous pulls only.
It does not talk to the daemon; the daemon pulls images itself during
podos deploy. Do not point --root at the daemon's data directory.
| Flag | Meaning |
|---|---|
--root DIR |
Content store directory. Required; created with mode 0700 if missing. |
--platform OS/ARCH[/VARIANT] |
Platform to pull. Default: Linux on the architecture of this machine. |
-j, --json |
Print the result as one JSON object. |
--allow-private HOST:PORT |
Allow a registry, token realm or redirect target on an internal address. Repeatable. |
--plain-http HOST:PORT |
Allow a registry over plain HTTP. Repeatable. |
podos version
podos version [flags]
podos --version
| Flag | Meaning |
|---|---|
--limits |
Print the limits of this version. |
--licenses |
Print the licenses of the third-party software in this binary. |
podos login
Available
podos login [flags] https://HOST:PORT
Connects to a server's HTTPS API, shows the fingerprint of its CA and, after
you confirm that it matches what podos setup printed on the server (or
what podos ca fingerprint prints there), saves the CA with the address and
your token as a named context. From then on the server is verified strictly
against that CA. If the CA ever differs, every command fails and nothing is
trusted again silently (trust on first use).
The token is read from a prompt without echo, from standard input, or from
PODOS_TOKEN. There is no flag for it, so it never appears in a process
list. Without a terminal, give --ca-fingerprint.
| Flag | Meaning |
|---|---|
--name NAME |
Name of the context. Default: the first label of the server's host name. |
--ca-fingerprint SHA256:... |
Fingerprint of the server's CA, for use without a terminal. It must match what the server presents. |
--use |
Make the new context the current one at once. Default: only when there is no current context and no podos daemon answers on this machine's local socket. Otherwise the context is saved and the podos context use hint is printed. |
podos login https://server.example.com:8443 --name prod-eu --use
podos logout
Available
podos logout [NAME]
Deletes the token saved in the context NAME (default: the current context).
The server address and CA are kept. The token stays valid on the server
until it is revoked with podos token revoke.
podos context
Available
podos context list [-j | --json]
podos context use NAME
podos context remove NAME
list shows the contexts and marks the current one with *; tokens are
never shown. use makes a context the one used when no --context,
PODOS_CONTEXT or manifest context applies. remove deletes a context
with its saved token and CA; the token stays valid on the server until
revoked. local is built in, means the daemon socket on this machine, and
can be selected with use but not removed.
podos whoami
Available
podos whoami [-j | --json] [-c | --context NAME] [--socket PATH]
Asks the selected server which token you are: its name, kind, scope and expiry, and which context and address the answer came from. The token itself is never shown.
podos token
Available Tokens give remote clients access to the HTTPS API. Run these
commands as root on the server, or with an admin token. A
project-admin token can create tokens inside its own
project. See
Security model.
podos token create --name NAME [flags]
podos token list [-j | --json]
podos token revoke NAME|ID
create prints the token once on standard output; only its hash is stored,
so it cannot be shown again.
| Flag | Meaning |
|---|---|
--name NAME |
Name of the token. Required; lowercase letters, digits and hyphens. |
--kind KIND |
admin, project-admin, deploy or read. Default: read. |
-p, --project NAME |
Project the token is limited to. Required for every kind but admin. |
-e, --env ENV |
Limit a deploy or read token to this environment of the project. |
--secrets-write |
Let a deploy token set and delete secrets. It has no short form. |
--expires DURATION |
Lifetime, for example 90d, 12w or 36h. Default: never expires. |
-c, --context NAME, --socket PATH |
Server to use. |
The kinds:
| Kind | Can do |
|---|---|
admin |
Everything. Only an admin creates admin tokens. |
project-admin |
Everything in one project except cascading deletes: environments, tokens and all that is in them. Creates tokens inside its own project. |
deploy |
Releases and values in a project, optionally one environment. Secrets only with --secrets-write. |
read |
Read access in a project, optionally one environment. |
A deploy token can read its environment's secrets indirectly, through the containers it deploys.
list shows kind, scope, status and last use; neither tokens nor hashes are
ever shown. revoke takes the name or ID, never the token itself, and the
token stops working at once.
podos token create --name ci-shop-test --kind deploy --project shop --env test --expires 90d
podos token list
podos token revoke ci-shop-test
podos ca fingerprint
Available
podos ca fingerprint [--data-dir DIR] [--socket PATH]
Run as root on the server. Prints the SHA-256 fingerprint of the server's
CA, the one podos login asks you to compare. It is public and changes
nothing. It works while the daemon runs; it then asks the daemon on its
socket.
podos releases
Available
podos releases [flags]
Lists the newest releases of the project and environment with their
status, age and, for failed releases, the first line of the failure reason.
Secrets in a reason are replaced by ***. Available When a rollout failed and
was rolled back automatically, the reason says why.
| Flag | Meaning |
|---|---|
--limit N |
How many releases to show, newest first, 1 to 1000. Default 20. |
--full |
Show the whole failure reason, not just its first line. |
-j, --json |
Print the releases as JSON. |
-d, --dir, -p, --project, -e, --env, --socket, -c, --context |
See Choosing the project and environment. |
Environment variables
| Variable | Used by | Meaning |
|---|---|---|
PODOS_DATA_DIR |
setup, daemon, ca fingerprint |
Data directory. Default /var/lib/podos. |
PODOS_RUN_DIR |
daemon, client commands |
Runtime directory holding podos.sock. Default /run/podos. |
PODOS_SOCKET |
client commands | Path of the daemon socket. Selects the local socket. |
PODOS_CONTEXT |
client commands | Available Name of the context to use. Beaten by --context and --socket. |
PODOS_TOKEN |
login |
Available The token to save, instead of a prompt. |
PODOS_LISTEN |
daemon |
Available HTTPS listen address, as --listen. |
PODOS_TLS_NAMES |
daemon |
Available Names for the HTTPS certificate, as --tls-name. |
XDG_CONFIG_HOME |
client commands | Available Parent of the podos/ directory holding contexts.json. Default ~/.config. |