diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 6 | ||||
| -rw-r--r-- | docs/source/markdown/podman-generate-systemd.1.md | 125 | ||||
| -rw-r--r-- | docs/source/markdown/podman-generate.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-info.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-play-kube.1.md | 14 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 6 |
6 files changed, 146 insertions, 9 deletions
diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 38b95edc3..f0494ca7d 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -823,6 +823,7 @@ The following examples are all valid: Without this argument the command will be run as root in the container. +**--userns**=*auto*[:OPTIONS] **--userns**=*host* **--userns**=*keep-id* **--userns**=container:container @@ -831,6 +832,11 @@ Without this argument the command will be run as root in the container. Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled. + +- `auto`: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are + **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace. + **uidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a UID mapping to be present in the user namespace. + **gidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a GID mapping to be present in the user namespace. - `container`: join the user namespace of the specified container. - `host`: run in the user namespace of the caller. This is the default if no user namespace options are set. The processes running in the container will have the same privileges on the host as any other process launched by the calling user. - `keep-id`: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user. diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index 57ed9a5eb..fa04f81f9 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -1,7 +1,7 @@ % podman-generate-systemd(1) ## NAME -podman\-generate\-systemd - Generate systemd unit file(s) for a container. Not supported for the remote client +podman\-generate\-systemd - Generate systemd unit file(s) for a container or pod. Not supported for the remote client ## SYNOPSIS **podman generate systemd** [*options*] *container|pod* @@ -18,6 +18,8 @@ Note that this command is not supported for the remote client. 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`. + **--name**, **-n** Use the name of the container for the start, stop, and description in the unit file @@ -25,7 +27,9 @@ Use the name of the container for the start, stop, and description in the unit f **--new** Create a new container via podman-run instead of starting an existing one. This option relies on container configuration files, which may not map directly to podman CLI flags; please review the generated output carefully before placing in production. -Since we use systemd `Type=forking` service, using this option will force the container run with the detached param `-d` +Since we use systemd `Type=forking` service, using this option will force the container run with the detached param `-d`. + +Note: Generating systemd unit files with `--new` flag is not yet supported for pods. **--time**, **-t**=*value* @@ -38,7 +42,10 @@ Set the systemd restart policy. The restart-policy must be one of: "no", "on-su ## Examples -Create and print a systemd unit file for a container running nginx with an *always* restart policy and 1-second timeout to stdout. +### 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. + ``` $ podman create --name nginx nginx:latest $ podman generate systemd --restart-policy=always -t 1 nginx @@ -62,7 +69,42 @@ PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb0073 WantedBy=multi-user.target default.target ``` -Create systemd unit files for a pod with two simple alpine containers. Note that these container services cannot be started or stopped individually via `systemctl`; they are managed by the pod service. You can still use `systemctl status` or journalctl to examine them. +### 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.target +After=network-online.target + +[Service] +Environment=PODMAN_SYSTEMD_UNIT=%n +Restart=on-failure +ExecStartPre=/usr/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=multi-user.target 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 @@ -94,9 +136,82 @@ PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc28769 WantedBy=multi-user.target 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 ```/usr/lib/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: Coping unit files to ```/usr/lib/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. + + +``` +# 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 /usr/lib/systemd/system +$ systemctl enable pod-systemd-po.service +Created symlink /etc/systemd/system/multi-user.target.wants/pod-systemd-po.service → /usr/lib/systemd/system/pod-systemd-po.service. +Created symlink /etc/systemd/system/default.target.wants/pod-systemd-po.service → /usr/lib/systemd/system/pod-systemd-po.service. +$ systemctl is-enabled pod-systemd-po.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`. + +``` +$ 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) +[podman(1)](podman.1.md), [podman-container(1)](podman-container.1.md), systemctl(1), systemd.unit(5), systemd.service(5) ## HISTORY +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) + 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) diff --git a/docs/source/markdown/podman-generate.1.md b/docs/source/markdown/podman-generate.1.md index 50050f2c1..da5d92ea4 100644 --- a/docs/source/markdown/podman-generate.1.md +++ b/docs/source/markdown/podman-generate.1.md @@ -14,7 +14,7 @@ The generate command will create structured output (like YAML) based on a contai | Command | Man Page | Description | |---------|------------------------------------------------------------|-------------------------------------------------------------------------------------| | kube | [podman-generate-kube(1)](podman-generate-kube.1.md) | Generate Kubernetes YAML based on a pod or container. | -| systemd | [podman-generate-systemd(1)](podman-generate-systemd.1.md) | Generate systemd unit file(s) for a container. Not supported for the remote client. | +| systemd | [podman-generate-systemd(1)](podman-generate-systemd.1.md) | Generate systemd unit file(s) for a container or pod. Not supported for the remote client. | ## SEE ALSO diff --git a/docs/source/markdown/podman-info.1.md b/docs/source/markdown/podman-info.1.md index b539f1d3c..d9da4c3f8 100644 --- a/docs/source/markdown/podman-info.1.md +++ b/docs/source/markdown/podman-info.1.md @@ -156,7 +156,7 @@ Run podman info with JSON formatted response: ``` Run podman info and only get the registries information. ``` -$ podman info --format={{".registries"}} +$ podman info --format={{".Registries"}} map[registries:[docker.io quay.io registry.fedoraproject.org registry.access.redhat.com]] ``` diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 2367ff7fe..dd9441800 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -36,6 +36,10 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. +**--network**=*cni networks* + +A comma-separated list of the names of CNI networks the pod should join. + **--quiet**, **-q** Suppress output information when pulling images @@ -62,8 +66,16 @@ $ podman play kube demo.yml 52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 ``` +CNI network(s) can be specified as comma-separated list using ``--network`` +``` +$ podman play kube demo.yml --network cni1,cni2 +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` + +Please take into account that CNI networks must be created first using podman-network-create(1). + ## SEE ALSO -podman(1), podman-container(1), podman-pod(1), podman-generate-kube(1), podman-play(1) +podman(1), podman-container(1), podman-pod(1), podman-generate-kube(1), podman-play(1), podman-network-create(1) ## HISTORY December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index e8b7d56b7..b21eb9da9 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -862,10 +862,14 @@ Sets the username or UID used and optionally the groupname or GID for the specif Without this argument the command will be run as root in the container. -**--userns**=**host**|**keep-id**|**container:**_id_|**ns:**_namespace_ +**--userns**=**auto**|**host**|**keep-id**|**container:**_id_|**ns:**_namespace_ Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled. +- **auto**: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are + **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace. + **uidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a UID mapping to be present in the user namespace. + **gidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a GID mapping to be present in the user namespace. - **host**: run in the user namespace of the caller. This is the default if no user namespace options are set. The processes running in the container will have the same privileges on the host as any other process launched by the calling user. - **keep-id**: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user. - **ns**: run the container in the given existing user namespace. |