Run the command in a systemd service¶

The command podman system service supports systemd socket activation. 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.

The systemd unit files that declares the Podman API service for users are

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

The podman system service command does not support more than one listening socket for the API service.

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.

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 rootless is 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

Security¶

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. 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. We strongly recommend against making the API socket available via the network (IE, bindings the service to a tcp URL). 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, using the --cors option is recommended to improve security.

--cors¶

CORS headers to inject to the HTTP response. The default value is empty string which disables CORS headers.

--help, -h¶

Print usage statement.

--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.

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