podman-system-service(1) General Commands Manual podman-system-service(1)
NAME
podman-system-service - Run an API service
SYNOPSIS
podman system service [options]
DESCRIPTION
The podman system service command creates a listening service that an-
swers API calls for Podman. The command is available on Linux systems
and is usually executed in systemd services. The command is not avail-
able when the Podman command is executed directly on a Windows or macOS
host or in other situations where the Podman command is accessing a re-
mote 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 there-
fore be provided on demand. If the systemd service is not already run-
ning, 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, sys-
temd 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 de-
fined 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 speci-
fiers 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 listen-
ing 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 infor-
mation 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 stan-
dard 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 re-
quired, we instead recommend forwarding the API socket via SSH, and lim-
iting access on the remote machine to the greatest extent possible. If
a tcp URL must be used, using the --cors option is recommended to im-
prove 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
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 activa-
tion.
podman system service --time 5
The default socket was used as no URI argument was provided.
SEE ALSO
podman(1), podman-system-connection(1), containers.conf(5)
HISTORY
January 2020, Originally compiled by Brent Baude <bbaude@redhat.com> No-
vember 2020, Updated by Jhon Honce (jhonce at redhat dot com)
podman-system-service(1)
Generated by dwww version 1.16 on Tue Dec 16 06:03:55 CET 2025.