Provided by: podman_3.4.4+ds1-1ubuntu1_amd64 bug

NAME

       podman-generate-systemd - Generate systemd unit file(s) for a container or pod

SYNOPSIS

       podman generate systemd [options] container|pod

DESCRIPTION

       podman  generate  systemd  will  create  a systemd unit file that can be used to control a
       container or pod.  By default, the command will print the content of  the  unit  files  to
       stdout.

       _Note:  If  you use this command with the remote client, you would still have to place the
       generated units on the remote system.  Moreover, please make sure that the  XDG_RUNTIMEDIR
       environment    variable    is    set.    If   unset,   you   may   set   it   via   export
       XDG_RUNTIME_DIR=/run/user/$(id -u).

OPTIONS

   --files, -f
       Generate  files  instead  of  printing  to  stdout.   The  generated   files   are   named
       {container,pod}-{ID,name}.service and will be placed in the current working directory.

       Note: On a system with SELinux enabled, the generated files will inherit contexts from the
       current working directory. Depending on the SELinux setup, changes to the generated  files
       using  restorecon,  chcon,  or  semanage  may be required to allow systemd to access these
       files. Alternatively, use the -Z option when running mv or cp.

   --format=format
       Print the created units in specified format (json). If --files is specified the  paths  to
       the created files will be printed instead of the unit content.

   --name, -n
       Use the name of the container for the start, stop, and description in the unit file

   --new
       Using  this  flag  will  yield unit files that do not expect containers and pods to exist.
       Instead, new containers and pods are created based on their configuration files.  The unit
       files  are  created  best  effort  and  may  need  to be further edited; please review the
       generated files carefully before using them in production.

       Note that --new only works on containers and  pods  created  directly  via  Podman  (i.e.,
       podman  [container] {create,run} or podman pod create).  It does not work on containers or
       pods created via the REST API or via podman play kube.

   --no-header
       Do not generate the header including  meta  data  such  as  the  Podman  version  and  the
       timestamp.

   --time, -t=value
       Override the default stop timeout for the container with the given value.

   --restart-policy=policy
       Set  the  systemd  restart policy.  The restart-policy must be one of: "no", "on-success",
       "on-failure", "on-abnormal", "on-watchdog", "on-abort", or "always".  The  default  policy
       is on-failure.

   --container-prefix=prefix
       Set the systemd unit name prefix for containers. The default is container.

   --pod-prefix=prefix
       Set the systemd unit name prefix for pods. The default is pod.

   --separator=separator
       Set the systemd unit name separator between the name/id of a container/pod and the prefix.
       The default is -.

EXAMPLES

   Generate and print a systemd unit file for a container
       Generate a systemd unit file for a container running nginx with an always  restart  policy
       and 1-second timeout to stdout. Note that the RequiresMountsFor option in the Unit section
       ensures that the container storage for both the GraphRoot  and  the  RunRoot  are  mounted
       prior  to  starting the service. For systems with container storage on disks like iSCSI or
       other remote block protocols, this ensures that  Podman  is  not  executed  prior  to  any
       necessary storage operations coming online.

              $ podman create --name nginx nginx:latest
              $ podman generate systemd --restart-policy=always -t 1 nginx
              # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
              # autogenerated by Podman 1.8.0
              # Wed Mar 09 09:46:45 CEST 2020

              [Unit]
              Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service
              Documentation=man:podman-generate-systemd(1)
              Wants=network-online.target
              After=network-online.target
              RequiresMountsFor=/var/run/container/storage

              [Service]
              Restart=always
              ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
              ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6
              KillMode=none
              Type=forking
              PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid

              [Install]
              WantedBy=default.target

   Generate systemd unit file for a container with --new flag
       The  --new  flag generates systemd unit files that create and remove containers at service
       start and stop commands (see ExecStartPre and ExecStopPost  service  actions).  Such  unit
       files  are  not  tied  to  a  single  machine  and  can easily be shared and used on other
       machines.

              $ sudo podman generate systemd --new --files --name bb310a0780ae
              # container-busy_moser.service
              # autogenerated by Podman 1.8.3
              # Fri Apr  3 09:40:47 EDT 2020

              [Unit]
              Description=Podman container-busy_moser.service
              Documentation=man:podman-generate-systemd(1)
              Wants=network-online.target
              After=network-online.target
              RequiresMountsFor=/var/run/container/storage

              [Service]
              Environment=PODMAN_SYSTEMD_UNIT=%n
              Restart=on-failure
              ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid
              ExecStart=/usr/local/bin/podman run --conmon-pidfile %t/%n-pid --cidfile %t/%n-cid --cgroups=no-conmon -d -dit alpine
              ExecStop=/usr/local/bin/podman stop --ignore --cidfile %t/%n-cid -t 10
              ExecStopPost=/usr/local/bin/podman rm --ignore -f --cidfile %t/%n-cid
              PIDFile=%t/%n-pid
              KillMode=none
              Type=forking

              [Install]
              WantedBy=default.target

   Generate systemd unit files for a pod with two simple alpine containers
       Note systemctl should only be used on the pod unit  and  one  should  not  start  or  stop
       containers  individually  via systemctl, as they are managed by the pod service along with
       the internal infra-container.

       You can still use systemctl status or journalctl to examine container or pod unit files.

              $ podman pod create --name systemd-pod
              $ podman create --pod systemd-pod alpine top
              $ podman create --pod systemd-pod alpine top
              $ podman generate systemd --files --name systemd-pod
              /home/user/pod-systemd-pod.service
              /home/user/container-amazing_chandrasekhar.service
              /home/user/container-jolly_shtern.service
              $ cat pod-systemd-pod.service
              # pod-systemd-pod.service
              # autogenerated by Podman 1.8.0
              # Wed Mar 09 09:52:37 CEST 2020

              [Unit]
              Description=Podman pod-systemd-pod.service
              Documentation=man:podman-generate-systemd(1)
              Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service
              Before=container-amazing_chandrasekhar.service container-jolly_shtern.service
              Wants=network-online.target
              After=network-online.target
              RequiresMountsFor=/var/run/container/storage

              [Service]
              Restart=on-failure
              ExecStart=/usr/bin/podman start 77a818221650-infra
              ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra
              KillMode=none
              Type=forking
              PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid

              [Install]
              WantedBy=default.target

   Installation of generated systemd unit files.
       Podman-generated unit files include  an  [Install]  section,  which  carries  installation
       information  for  the  unit. It is used by the enable and disable commands of systemctl(1)
       during installation.

       Once you have generated the systemd unit file, you can copy the generated systemd file  to
       /etc/systemd/system  for  installing  as a root user and to $HOME/.config/systemd/user for
       installing it as a non-root user. Enable the copied unit file  or  files  using  systemctl
       enable.

       Note:  Copying unit files to /etc/systemd/system and enabling it marks the unit file to be
       automatically   started   at   boot.   And   similarly,   copying   a   unit    file    to
       $HOME/.config/systemd/user and enabling it marks the unit file to be automatically started
       on user login.

              # Generated systemd files.
              $ podman pod create --name systemd-pod
              $ podman create --pod systemd-pod alpine top
              $ podman generate systemd --files --name systemd-pod

              # Copy all the generated files.

              $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system
              $ systemctl enable pod-systemd-pod.service
              Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service.
              $ systemctl is-enabled pod-systemd-pod.service
              enabled

       To run the user services placed in $HOME/.config/systemd/user on first login of that user,
       enable the service with --user flag.

              $ systemctl --user enable <.service>

       The  systemd  user  instance  is killed after the last session for the user is closed. The
       systemd user instance can be kept running  ever  after  the  user  logs  out  by  enabling
       lingering using

              $ loginctl enable-linger <username>

   Use systemctl to perform operations on generated installed unit files.
       Create  and  enable systemd unit files for a pod using the above examples as reference and
       use systemctl to perform operations.

       Since systemctl defaults to using the root user, all the changes using the  systemctl  can
       be  seen  by  appending sudo to the podman cli commands. To perform systemctl actions as a
       non-root user use the --user flag when interacting with systemctl.

       Note: If the previously created containers or pods are using  shared  resources,  such  as
       ports, make sure to remove them before starting the generated systemd units.

              $ systemctl --user start pod-systemd-pod.service
              $ podman pod ps
              POD ID         NAME          STATUS    CREATED          # OF CONTAINERS   INFRA ID
              0815c7b8e7f5   systemd-pod   Running   29 minutes ago   2                 6c5d116f4bbe
              $ sudo podman ps # 0 Number of pods on root.
              CONTAINER ID  IMAGE  COMMAND  CREATED  STATUS  PORTS  NAMES
              $ systemctl stop pod-systemd-pod.service
              $ podman pod ps
              POD ID         NAME          STATUS   CREATED          # OF CONTAINERS   INFRA ID
              272d2813c798   systemd-pod   Exited   29 minutes ago   2                 6c5d116f4bbe

       Create  a  simple  alpine  container  and  generate the systemd unit file with --new flag.
       Enable the service and control operations using the systemctl commands.

       Note: When starting the container using systemctl start rather than altering  the  already
       running container it spins up a "new" container with similar configuration.

              # Enable the service.

              $ sudo podman ps -a
              CONTAINER ID  IMAGE                            COMMAND  CREATED        STATUS     PORTS  NAMES
              bb310a0780ae  docker.io/library/alpine:latest  /bin/sh  2 minutes ago  Created           busy_moser
              $ sudo systemctl start container-busy_moser.service
              $ sudo podman ps -a
              CONTAINER ID  IMAGE                            COMMAND  CREATED        STATUS            PORTS      NAMES
              772df2f8cf3b  docker.io/library/alpine:latest  /bin/sh  1 second ago   Up 1 second ago              distracted_albattani
              bb310a0780ae  docker.io/library/alpine:latest  /bin/sh  3 minutes ago  Created                      busy_moser

SEE ALSO

       [podman(1)],  [podman-container(1)],  systemctl(1),  systemd.unit(5),  systemd.service(5),
       conmon(8).

HISTORY

       April 2020, Updated details and added use case to use generated .service files as root and
       non-root, by Sujil Shah (sushah at redhat dot com)

       August 2019, Updated with pod support by Valentin Rothberg (rothberg at redhat dot com)

       April 2019, Originally compiled by Brent Baude (bbaude at redhat dot com)

                                                                     podman-generate-systemd(1)()