github.com/containers/podman/v2@v2.2.2-0.20210501105131-c1e07d070c4c/docs/source/markdown/podman-generate-systemd.1.md (about) 1 % podman-generate-systemd(1) 2 3 ## NAME 4 podman\-generate\-systemd - Generate systemd unit file(s) for a container or pod. Not supported for the remote client 5 6 ## SYNOPSIS 7 **podman generate systemd** [*options*] *container|pod* 8 9 ## DESCRIPTION 10 **podman generate systemd** will create a systemd unit file that can be used to control a container or pod. 11 By default, the command will print the content of the unit files to stdout. 12 13 _Note: If you use this command with the remote client, you would still have to place the generated units on the remote system._ 14 15 ## OPTIONS 16 17 #### **--files**, **-f** 18 19 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. 20 21 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`. 22 23 #### **--format**=*format* 24 25 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. 26 27 #### **--name**, **-n** 28 29 Use the name of the container for the start, stop, and description in the unit file 30 31 #### **--new** 32 33 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. 34 35 #### **--time**, **-t**=*value* 36 37 Override the default stop timeout for the container with the given value. 38 39 #### **--restart-policy**=*policy* 40 41 Set the systemd restart policy. The restart-policy must be one of: "no", "on-success", "on-failure", "on-abnormal", 42 "on-watchdog", "on-abort", or "always". The default policy is *on-failure*. 43 44 #### **--container-prefix**=*prefix* 45 46 Set the systemd unit name prefix for containers. The default is *container*. 47 48 #### **--pod-prefix**=*prefix* 49 50 Set the systemd unit name prefix for pods. The default is *pod*. 51 52 #### **--separator**=*separator* 53 54 Set the systemd unit name separator between the name/id of a container/pod and the prefix. The default is *-*. 55 56 ## EXAMPLES 57 58 ### Generate and print a systemd unit file for a container 59 60 Generate a systemd unit file for a container running nginx with an *always* restart policy and 1-second timeout to stdout. 61 62 ``` 63 $ podman create --name nginx nginx:latest 64 $ podman generate systemd --restart-policy=always -t 1 nginx 65 # container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service 66 # autogenerated by Podman 1.8.0 67 # Wed Mar 09 09:46:45 CEST 2020 68 69 [Unit] 70 Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service 71 Documentation=man:podman-generate-systemd(1) 72 73 [Service] 74 Restart=always 75 ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 76 ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 77 KillMode=none 78 Type=forking 79 PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid 80 81 [Install] 82 WantedBy=multi-user.target default.target 83 ``` 84 85 ### Generate systemd unit file for a container with `--new` flag 86 87 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. 88 89 ``` 90 $ sudo podman generate systemd --new --files --name bb310a0780ae 91 # container-busy_moser.service 92 # autogenerated by Podman 1.8.3 93 # Fri Apr 3 09:40:47 EDT 2020 94 95 [Unit] 96 Description=Podman container-busy_moser.service 97 Documentation=man:podman-generate-systemd(1) 98 Wants=network.target 99 After=network-online.target 100 101 [Service] 102 Environment=PODMAN_SYSTEMD_UNIT=%n 103 Restart=on-failure 104 ExecStartPre=/bin/rm -f %t/%n-pid %t/%n-cid 105 ExecStart=/usr/local/bin/podman run --conmon-pidfile %t/%n-pid --cidfile %t/%n-cid --cgroups=no-conmon -d -dit alpine 106 ExecStop=/usr/local/bin/podman stop --ignore --cidfile %t/%n-cid -t 10 107 ExecStopPost=/usr/local/bin/podman rm --ignore -f --cidfile %t/%n-cid 108 PIDFile=%t/%n-pid 109 KillMode=none 110 Type=forking 111 112 [Install] 113 WantedBy=multi-user.target default.target 114 ``` 115 116 ### Generate systemd unit files for a pod with two simple alpine containers 117 118 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. 119 120 You can still use `systemctl status` or `journalctl` to examine container or pod unit files. 121 ``` 122 $ podman pod create --name systemd-pod 123 $ podman create --pod systemd-pod alpine top 124 $ podman create --pod systemd-pod alpine top 125 $ podman generate systemd --files --name systemd-pod 126 /home/user/pod-systemd-pod.service 127 /home/user/container-amazing_chandrasekhar.service 128 /home/user/container-jolly_shtern.service 129 $ cat pod-systemd-pod.service 130 # pod-systemd-pod.service 131 # autogenerated by Podman 1.8.0 132 # Wed Mar 09 09:52:37 CEST 2020 133 134 [Unit] 135 Description=Podman pod-systemd-pod.service 136 Documentation=man:podman-generate-systemd(1) 137 Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service 138 Before=container-amazing_chandrasekhar.service container-jolly_shtern.service 139 140 [Service] 141 Restart=on-failure 142 ExecStart=/usr/bin/podman start 77a818221650-infra 143 ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra 144 KillMode=none 145 Type=forking 146 PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid 147 148 [Install] 149 WantedBy=multi-user.target default.target 150 ``` 151 152 ### Installation of generated systemd unit files. 153 154 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. 155 156 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`. 157 158 Note: Coping unit files to ```/etc/systemd/system``` and enabling it marks the unit file to be automatically started at boot. And smillarly, coping a unit file to ```$HOME/.config/systemd/user``` and enabling it marks the unit file to be automatically started on user login. 159 160 161 ``` 162 # Generated systemd files. 163 $ podman pod create --name systemd-pod 164 $ podman create --pod systemd-pod alpine top 165 $ podman generate systemd --files --name systemd-pod 166 167 # Copy all the generated files. 168 169 $ sudo cp pod-systemd-pod.service container-great_payne.service /etc/systemd/system 170 $ systemctl enable pod-systemd-pod.service 171 Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service. 172 Created symlink /etc/systemd/system/default.target.wants/pod-systemd-pod.service → /etc/systemd/system/pod-systemd-pod.service. 173 $ systemctl is-enabled pod-systemd-pod.service 174 enabled 175 ``` 176 To run the user services placed in `$HOME/.config/systemd/user` on first login of that user, enable the service with --user flag. 177 178 ``` 179 $ systemctl --user enable <.service> 180 ``` 181 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 182 183 ``` 184 $ loginctl enable-linger <username> 185 ``` 186 ### Use `systemctl` to perform operations on generated installed unit files. 187 188 Create and enable systemd unit files for a pod using the above examples as reference and use `systemctl` to perform operations. 189 190 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`. 191 192 ``` 193 $ systemctl --user start pod-systemd-pod.service 194 $ podman pod ps 195 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID 196 0815c7b8e7f5 systemd-pod Running 29 minutes ago 2 6c5d116f4bbe 197 $ sudo podman ps # 0 Number of pods on root. 198 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 199 $ systemctl stop pod-systemd-pod.service 200 $ podman pod ps 201 POD ID NAME STATUS CREATED # OF CONTAINERS INFRA ID 202 272d2813c798 systemd-pod Exited 29 minutes ago 2 6c5d116f4bbe 203 ``` 204 205 Create a simple alpine container and generate the systemd unit file with `--new` flag. 206 Enable the service and control operations using the systemctl commands. 207 208 Note: When starting the container using `systemctl start` rather than altering the already running container it spins up a "new" container with similar configuration. 209 210 ``` 211 # Enable the service. 212 213 $ sudo podman ps -a 214 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 215 bb310a0780ae docker.io/library/alpine:latest /bin/sh 2 minutes ago Created busy_moser 216 $ sudo systemctl start container-busy_moser.service 217 $ sudo podman ps -a 218 CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 219 772df2f8cf3b docker.io/library/alpine:latest /bin/sh 1 second ago Up 1 second ago distracted_albattani 220 bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created busy_moser 221 ``` 222 ## SEE ALSO 223 [podman(1)](podman.1.md), [podman-container(1)](podman-container.1.md), systemctl(1), systemd.unit(5), systemd.service(5) 224 225 ## HISTORY 226 April 2020, Updated details and added usecase to use generated .service files as root and non-root, by Sujil Shah (sushah at redhat dot com) 227 228 August 2019, Updated with pod support by Valentin Rothberg (rothberg at redhat dot com) 229 230 April 2019, Originally compiled by Brent Baude (bbaude at redhat dot com)