Ubuntu Manpage: podman-system-service

Provided by: podman_4.9.3+ds1-1build2_amd64

NAME

       podman-system-service - Run an API service

SYNOPSIS

       podman system service [options]

DESCRIPTION

The podman system service command creates a listening service that answers API calls for
Podman. The command is available on Linux systems and is usually executed in systemd
services. The command 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.

The REST API provided by podman system service is split into two parts: a compatibility
layer offering support for the Docker v1.40 API, and a Podman-native Libpod layer.
Documentation for the latter is available at
https://docs.podman.io/en/latest/_static/api.html. Both APIs are versioned, but the
server does not reject requests with an unsupported version set.

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

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

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.

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.

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

EXAMPLES

       To start the systemd socket for a rootless service, run as the user:

       systemctl --user start podman.socket

       The socket can then be used by for example docker-compose that needs  a  Docker-compatible
       API.

       $ ls $XDG_RUNTIME_DIR/podman/podman.sock
       /run/user/1000/podman/podman.sock
       $ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
       $ docker-compose up

       To  configure  the  systemd  socket  to be automatically started after reboots, run as the
       user:

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

       To start the systemd socket for the rootful service, run:

       sudo systemctl start podman.socket

       To configure the socket to be automatically started after reboots, run:

       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.

HISTORY