podman-system-service(1)

💖 podman-system-service — like, the manual page, but make it make sense 💖

okay bestie, gather round. this is podman-system-service(1) from the General Commands Manual, and we're gonna get you comfy with it. no cap.

---

✨ NAME ✨

podman-system-service — Run an API service 🫶

---

🌸 SYNOPSIS 🌸

podman system service [options]

---

🦋 DESCRIPTION 🦋

so the podman system service command spins up a listening service that answers API calls for Podman. iconic behavior fr. it's available on Linux systems and is usually executed in systemd services. it is not available when the Podman command is executed directly on a Windows or macOS host, or in other situations where the Podman command is accessing a remote Podman API service. so don't come for it there, it's not gonna answer 💀

the REST API that podman system service hands you is split into two parts:

• a compatibility layer offering support for the Docker v1.40 API, and
• a Podman-native Libpod layer.

docs for the Libpod layer live at https://docs.podman.io/en/latest/_static/api.html. both APIs are versioned, but heads up — the server does not reject requests with an unsupported version set. yeah. it's giving "we don't gatekeep" 🙈

🎀 Run the command in a systemd service 🎀

podman system service supports systemd socket activation, which is the slayest part honestly. when the command is run in a systemd service, the API service can therefore be provided on demand. if the systemd service is not already running, it will be activated as soon as a client connects to the listening socket. systemd then executes the podman system service command. after some time of inactivity — as defined by the --time option — the command terminates. systemd sets the podman.service state as inactive. at this point there is no podman system service process running. no unnecessary compute resources are wasted ✨. as soon as another client connects, systemd activates the systemd service again. main character energy: shows up only when needed, dips when the vibe fades.

the systemd unit files that declare the Podman API service for users are:

• /usr/lib/systemd/user/podman.service
• /usr/lib/systemd/user/podman.socket

in the file podman.socket the path of the listening Unix socket is defined by:

ListenStream=%t/podman/podman.sock

the path contains the systemd specifier %t, which systemd expands to the value of the environment variable XDG_RUNTIME_DIR (see systemd specifiers in the systemd.unit(5) man page).

in addition to the systemd user services, there is also a systemd system service podman.service. it runs rootful Podman and is accessed from the Unix socket /run/podman/podman.sock. see the systemd unit files:

• /usr/lib/systemd/system/podman.service
• /usr/lib/systemd/system/podman.socket

the podman system service command does not support more than one listening socket for the API service. one socket only, bestie, that's the rule 🚫

Note: the default systemd unit files (system and user) change the log-level option to info from error. this change provides additional information on each API call. more receipts, less silence 👑

🌈 Run the command directly 🌈

to support running an API service without using a systemd service, the command also takes an optional endpoint argument for the API in URI form. for example, unix:///tmp/foobar.sock or tcp://localhost:8080. if no endpoint is provided, defaults is used. the default endpoint for a rootful service is unix:///run/podman/podman.sock and for a rootless one it's unix://$XDG_RUNTIME_DIR/podman/podman.sock (for example unix:///run/user/1000/podman/podman.sock).

🧚 Access the Unix socket from inside a container 🧚

to access the API service inside a container:

• mount the socket as a volume
• run the container with --security-opt label=disable

that's it, that's the recipe 🍓

💀 Security 💀

okay this is the serious part, no skipping, i mean it.

please note that the API grants full access to all Podman functionality, and thus allows arbitrary code execution as the user running the API, with no ability to limit or audit this access. it's giving "you handed them the whole house keys and also your diary."

the API's security model is built upon access via a Unix socket with access restricted via standard file permissions, ensuring that only the user running the service will be able to access it. TLS can be used to secure this socket by requiring clients to present a certificate signed by a trusted certificate authority ("CA"), as well as to allow the client to verify the identity of the API.

we strongly recommend against making the API socket available via the network (IE, bindings the service to a tcp URL) without enabling mutual TLS to authenticate the client. even access via Localhost carries risks — anyone with access to the system will be able to access the API. if remote access is required, we instead recommend forwarding the API socket via SSH, and limiting access on the remote machine to the greatest extent possible. if a tcp URL must be used without TLS, using the --cors option is recommended to improve security.

tl;dr: this thing is powerful and it does not play. protect the socket like it's your notes app 🫣

---

✨ OPTIONS ✨

• --cors — CORS headers to inject to the HTTP response. the default value is empty string, which disables CORS headers.
• --help, -h — Print usage statement. the classic, the icon, the "wait what were the flags again" button 💅
• --time, -t — The time until the session expires in seconds. the default is 5 seconds. a value of 0 means no timeout, therefore the session does not expire. she lives forever, periodt.
• --tls-cert=path — Path to a PEM file containing the TLS certificate to present to clients. --tls-key must also be provided. besties come in pairs 🫶
• --tls-client-ca=path — Path to a PEM file containing the TLS certificate bundle to validate client connections against. connections that present no certificate, or a certificate not signed by one of these certificates, will be rejected. rejected. blocked. unfollowed 😭
• --tls-key=path — Path to a PEM file containing the private key matching --tls-cert. --tls-cert must also be provided. (see, told you: pairs 💞)

the default timeout can be changed via the service_timeout=VALUE field in containers.conf. see containers.conf(5) for more information.

---

🌟 EXAMPLES 🌟

Start the user systemd socket for a rootless service:

systemctl --user start podman.socket

Configure DOCKER_HOST environment variable to point to the Podman socket so that it can be used via Docker API tools like docker-compose:

$ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
$ docker-compose up

Configure the systemd socket to be automatically started after reboots, and run as the specified user:

systemctl --user enable podman.socket
loginctl enable-linger <USER>

Start the systemd socket for the rootful service:

sudo systemctl start podman.socket

Configure the socket to be automatically started after reboots:

sudo systemctl enable podman.socket

It is possible to run the API without using systemd socket activation. in this case the API will not be available on demand, because the command will stay terminated after the inactivity timeout has passed. run an API with an inactivity timeout of 5 seconds without using socket activation:

podman system service --time 5

The default socket was used as no URI argument was provided.

Run an API service with a custom socket path and no timeout:

podman system service --time 0 unix:///var/run/mypodman.sock

This starts the API service listening on the custom socket /var/run/mypodman.sock with no inactivity timeout (runs indefinitely). obsessed with her honestly 🥰

---

🫶 SEE ALSO 🫶

podman(1), podman-system-connection(1), containers.conf(5)

---

📜 HISTORY 📜

• January 2020, Originally compiled by Brent Baude <bbaude@redhat.com>
• November 2020, Updated by Jhon Honce (jhonce at redhat dot com)

---

and that's the whole page, bestie! 💖 this was podman-system-service(1) straight out of the General Commands Manual — same manual name you saw at the top, same one riding along at the bottom of the original, so nothing got left behind. go forth, start your socket, protect your socket, and stan a service that knows when to log off 🌸🦋✨