1podman-system-service(1) General Commands Manual podman-system-service(1)
2
6 podman-system-service - Run an API service
7
10 podman system service [options]
11
14 The podman system service command creates a listening service that an‐
15 swers API calls for Podman. The command is available on Linux systems
16 and is usually executed in systemd services. The command is not avail‐
17 able when the Podman command is executed directly on a Windows or macOS
18 host or in other situations where the Podman command is accessing a re‐
19 mote Podman API service.
20 The REST API provided by podman system service is split into two parts:
23 a compatibility layer offering support for the Docker v1.40 API, and a
24 Podman-native Libpod layer. Documentation for the latter is available
25 at https://docs.podman.io/en/latest/_static/api.html. Both APIs are
26 versioned, but the server does not reject requests with an unsupported
27 version set.
28 Run the command in a systemd service
31 The command podman system service supports systemd socket activation.
32 When the command is run in a systemd service, the API service can
33 therefore be provided on demand. If the systemd service is not already
34 running, it will be activated as soon as a client connects to the lis‐
35 tening socket. Systemd then executes the podman system service command.
36 After some time of inactivity, as defined by the --time option, the
37 command terminates. Systemd sets the podman.service state as inactive.
38 At this point there is no podman system service process running. No un‐
39 necessary compute resources are wasted. As soon as another client con‐
40 nects, systemd activates the systemd service again.
41 The systemd unit files that declares the Podman API service for users
44 are
45 • /usr/lib/systemd/user/podman.service
48 • /usr/lib/systemd/user/podman.socket
50 In the file podman.socket the path of the listening Unix socket is de‐
54 fined by
55 ListenStream=%t/podman/podman.sock
58 The path contains the systemd specifier %t which systemd expands to the
62 value of the environment variable XDG_RUNTIME_DIR (see systemd speci‐
63 fiers in the systemd.unit(5) man page).
64 In addition to the systemd user services, there is also a systemd sys‐
67 tem service podman.service. It runs rootful Podman and is accessed
68 from the Unix socket /run/podman/podman.sock. See the systemd unit
69 files
70 • /usr/lib/systemd/system/podman.service
73 • /usr/lib/systemd/system/podman.socket
75 The podman system service command does not support more than one lis‐
79 tening socket for the API service.
80 Note: The default systemd unit files (system and user) change the log-
83 level option to info from error. This change provides additional infor‐
84 mation on each API call.
85 Run the command directly
88 To support running an API service without using a systemd service, the
89 command also takes an optional endpoint argument for the API in URI
90 form. For example, unix:///tmp/foobar.sock or tcp://localhost:8080.
91 If no endpoint is provided, defaults is used. The default endpoint for
92 a rootful service is unix:///run/podman/podman.sock and rootless is
93 unix://$XDG_RUNTIME_DIR/podman/podman.sock (for example
94 unix:///run/user/1000/podman/podman.sock)
95 Access the Unix socket from inside a container
98 To access the API service inside a container: - mount the socket as a
99 volume - run the container with --security-opt label=disable
100 Security
103 Please note that the API grants full access to all Podman functional‐
104 ity, and thus allows arbitrary code execution as the user running the
105 API, with no ability to limit or audit this access. The API's security
106 model is built upon access via a Unix socket with access restricted via
107 standard file permissions, ensuring that only the user running the ser‐
108 vice will be able to access it. We strongly recommend against making
109 the API socket available via the network (IE, bindings the service to a
110 tcp URL). Even access via Localhost carries risks - anyone with access
111 to the system will be able to access the API. If remote access is re‐
112 quired, we instead recommend forwarding the API socket via SSH, and
113 limiting access on the remote machine to the greatest extent possible.
114 If a tcp URL must be used, using the --cors option is recommended to
115 improve security.
116
119 --cors
120 CORS headers to inject to the HTTP response. The default value is empty
121 string which disables CORS headers.
122 --help, -h
125 Print usage statement.
126 --time, -t
129 The time until the session expires in seconds. The default is 5 sec‐
130 onds. A value of 0 means no timeout, therefore the session does not ex‐
131 pire.
132 The default timeout can be changed via the service_timeout=VALUE field
135 in containers.conf. See containers.conf(5) for more information.
136
139 To start the systemd socket for a rootless service, run as the user:
140 systemctl --user start podman.socket
143 The socket can then be used by for example docker-compose that needs a
147 Docker-compatible API.
148 $ ls $XDG_RUNTIME_DIR/podman/podman.sock
151 /run/user/1000/podman/podman.sock
152 $ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
153 $ docker-compose up
154 To configure the systemd socket to be automatically started after re‐
158 boots, run as the user:
159 systemctl --user enable podman.socket
162 loginctl enable-linger <USER>
163 To start the systemd socket for the rootful service, run:
167 sudo systemctl start podman.socket
170 To configure the socket to be automatically started after reboots, run:
174 sudo systemctl enable podman.socket
177 It is possible to run the API without using systemd socket activation.
181 In this case the API will not be available on demand because the com‐
182 mand will stay terminated after the inactivity timeout has passed. Run
183 an API with an inactivity timeout of 5 seconds without using socket ac‐
184 tivation:
185 podman system service --time 5
188 The default socket was used as no URI argument was provided.
192
195 podman(1), podman-system-connection(1), containers.conf(5)
196
199 January 2020, Originally compiled by Brent Baude <bbaude@redhat.com>
200 November 2020, Updated by Jhon Honce (jhonce at redhat dot com)
201 podman-system-service(1)