Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       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 lis-
       tening 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 un-
       necessary compute resources are wasted.	As soon	as another client con-
       nects, 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  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  sys-
       tem  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 lis-
       tening 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 functional-
       ity, 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 ser-
       vice  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
       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  sec-
       onds. A value of	0 means	no timeout, therefore the session does not ex-
       pire.

       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  com-
       mand will stay terminated after the inactivity timeout has passed.  Run
       an API with an inactivity timeout of 5 seconds without using socket ac-
       tivation.

       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>
       November	2020, Updated by Jhon Honce (jhonce at redhat dot com)

						      podman-system-service(1)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=podman-system-service&sektion=1&manpath=FreeBSD+Ports+14.3.quarterly>

home | help