podman-system-service - Run an API service

Description

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

Runthecommandinasystemdservice
The command podmansystemservice 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 podmansystemservice 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 podmansystemservice 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 podmansystemservice 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.

Runthecommanddirectly
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)

AccesstheUnixsocketfrominsideacontainer
To access the API service inside a container: - mount the socket as a volume - run the container with
--security-optlabel=disableSecurity
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.

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.

History

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

                                                                                        podman-system-service(1)

Name

       podman-system-service - Run an API service

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.