github.com/containers/podman/v5@v5.1.0-rc1/docs/source/markdown/podman-system-service.1.md (about)

     1  % podman-system-service 1
     2  
     3  ## NAME
     4  podman\-system\-service - Run an API service
     5  
     6  ## SYNOPSIS
     7  **podman system service** [*options*]
     8  
     9  ## DESCRIPTION
    10  The **podman system service** command creates a listening service that answers API calls for Podman.
    11  The command is available on Linux systems and is usually executed in systemd services.
    12  The command is not available when the Podman command is executed directly on a Windows or macOS
    13  host or in other situations where the Podman command is accessing a remote Podman API service.
    14  
    15  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.
    16  Documentation for the latter is available at *https://docs.podman.io/en/latest/_static/api.html*.
    17  Both APIs are versioned, but the server does not reject requests with an unsupported version set.
    18  
    19  ### Run the command in a systemd service
    20  
    21  The command **podman system service** supports systemd socket activation.
    22  When the command is run in a systemd service, the API service can therefore be provided on demand.
    23  If the systemd service is not already running, it will be activated as soon as
    24  a client connects to the listening socket. Systemd then executes the
    25  **podman system service** command.
    26  After some time of inactivity, as defined by the __--time__ option, the command terminates.
    27  Systemd sets the _podman.service_ state as inactive. At this point there is no
    28  **podman system service** process running. No unnecessary compute resources are wasted.
    29  As soon as another client connects, systemd activates the systemd service again.
    30  
    31  The systemd unit files that declares the Podman API service for users are
    32  
    33  * _/usr/lib/systemd/user/podman.service_
    34  * _/usr/lib/systemd/user/podman.socket_
    35  
    36  In the file _podman.socket_ the path of the listening Unix socket is defined by
    37  
    38  ```
    39  ListenStream=%t/podman/podman.sock
    40  ```
    41  
    42  The path contains the systemd specifier `%t` which systemd expands to the value of the environment variable
    43  `XDG_RUNTIME_DIR` (see systemd specifiers in the **systemd.unit(5)** man page).
    44  
    45  In addition to the systemd user services, there is also a systemd system service _podman.service_.
    46  It runs rootful Podman and is accessed from the Unix socket _/run/podman/podman.sock_. See the systemd unit files
    47  
    48  * _/usr/lib/systemd/system/podman.service_
    49  * _/usr/lib/systemd/system/podman.socket_
    50  
    51  The **podman system service** command does not support more than one listening socket for the API service.
    52  
    53  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.
    54  
    55  ### Run the command directly
    56  
    57  To support running an API service without using a systemd service, the command also takes an
    58  optional endpoint argument for the API in URI form.  For example, *unix:///tmp/foobar.sock* or *tcp://localhost:8080*.
    59  If no endpoint is provided, defaults is used.  The default endpoint for a rootful
    60  service is *unix:///run/podman/podman.sock* and rootless is *unix://$XDG_RUNTIME_DIR/podman/podman.sock* (for
    61  example *unix:///run/user/1000/podman/podman.sock*)
    62  
    63  ### Access the Unix socket from inside a container
    64  
    65  To access the API service inside a container:
    66  - mount the socket as a volume
    67  - run the container with `--security-opt label=disable`
    68  
    69  ### Security
    70  
    71  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.
    72  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.
    73  We *strongly* recommend against making the API socket available via the network (IE, bindings the service to a *tcp* URL).
    74  Even access via Localhost carries risks - anyone with access to the system will be able to access the API.
    75  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.
    76  If a *tcp* URL must be used, using the *--cors* option is recommended to improve security.
    77  
    78  ## OPTIONS
    79  
    80  #### **--cors**
    81  
    82  CORS headers to inject to the HTTP response. The default value is empty string which disables CORS headers.
    83  
    84  #### **--help**, **-h**
    85  
    86  Print usage statement.
    87  
    88  #### **--time**, **-t**
    89  
    90  The time until the session expires in _seconds_. The default is 5
    91  seconds. A value of `0` means no timeout, therefore the session does not expire.
    92  
    93  The default timeout can be changed via the `service_timeout=VALUE` field in containers.conf.
    94  See **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)** for more information.
    95  
    96  ## EXAMPLES
    97  
    98  Start the user systemd socket for a rootless service.
    99  ```
   100  systemctl --user start podman.socket
   101  ```
   102  
   103  Configure DOCKER_HOST environment variable to point to the Podman socket so that
   104  it can be used via Docker API tools like docker-compose.
   105  ```
   106  $ export DOCKER_HOST=unix://$XDG_RUNTIME_DIR/podman/podman.sock
   107  $ docker-compose up
   108  ```
   109  
   110  Configure the systemd socket to be automatically started after reboots, and run as the specified user.
   111  ```
   112  systemctl --user enable podman.socket
   113  loginctl enable-linger <USER>
   114  ```
   115  
   116  Start the systemd socket for the rootful service.
   117  ```
   118  sudo systemctl start podman.socket
   119  ```
   120  
   121  Configure the socket to be automatically started after reboots.
   122  ```
   123  sudo systemctl enable podman.socket
   124  ```
   125  
   126  It is possible to run the API without using systemd socket activation.
   127  In this case the API will not be available on demand because the command will
   128  stay terminated after the inactivity timeout has passed.
   129  Run an API with an inactivity timeout of 5 seconds without using socket activation.
   130  ```
   131  podman system service --time 5
   132  ```
   133  
   134  The default socket was used as no URI argument was provided.
   135  
   136  ## SEE ALSO
   137  **[podman(1)](podman.1.md)**, **[podman-system-connection(1)](podman-system-connection.1.md)**, **[containers.conf(5)](https://github.com/containers/common/blob/main/docs/containers.conf.5.md)**
   138  
   139  ## HISTORY
   140  January 2020, Originally compiled by Brent Baude `<bbaude@redhat.com>`
   141  November 2020, Updated by Jhon Honce (jhonce at redhat dot com)