diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/Tutorials.rst | 2 | ||||
| -rw-r--r-- | docs/source/includes.rst | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-auto-update.1.md | 42 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 36 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pod-ps.1.md | 59 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pull.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 39 |
7 files changed, 123 insertions, 59 deletions
diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst index e48d1e853..cb9ab644d 100644 --- a/docs/source/Tutorials.rst +++ b/docs/source/Tutorials.rst @@ -10,5 +10,5 @@ Here are a number of useful tutorials to get you up and running with Podman. If * `How to sign and distribute container images using Podman <https://github.com/containers/podman/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman. * `Podman remote-client tutorial <https://github.com/containers/podman/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client. * `How to use libpod for custom/derivative projects <https://github.com/containers/podman/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project. -* `How to use Podman's Go bindings <https://github.com/containers/podman/blob/master/docs/tutorials/podman-go-bindings.md>`_: A brief how-to on using Podman's Go bindings in external applications. +* `How to use Podman's Go RESTful bindings <https://github.com/containers/podman/tree/main/pkg/bindings>`_: An introduction to using our RESTful Golang bindings in an external application. * `Common network setups <https://github.com/containers/podman/blob/master/docs/tutorials/basic_networking.md>`_: A basic guide to common network setups for Podman. diff --git a/docs/source/includes.rst b/docs/source/includes.rst index 8d3b6e2db..6e04d77f4 100644 --- a/docs/source/includes.rst +++ b/docs/source/includes.rst @@ -16,4 +16,4 @@ .. _podman run: http://docs.podman.io/en/latest/markdown/podman-run.1.html .. _podman build: http://docs.podman.io/en/latest/markdown/podman-build.1.html .. _podman push: http://docs.podman.io/en/latest/markdown/podman-push.1.html -.. image:: https://github.com/containers/podman/blob/master/logo/podman-logo.png?raw=true +.. image:: https://github.com/containers/podman/blob/main/logo/podman-logo.png?raw=true diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md index 24b910470..106b9b00a 100644 --- a/docs/source/markdown/podman-auto-update.1.md +++ b/docs/source/markdown/podman-auto-update.1.md @@ -41,6 +41,27 @@ If the authorization state is not found there, `$HOME/.docker/config.json` is ch Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**. +#### **--dry-run**=*true|false* + +Check for the availability of new images but do not perform any pull operation or restart any service or container. +The `UPDATED` field indicates the availability of a new image with "pending". + +#### **--format**=*format* + +Change the default output format. This can be of a supported type like 'json' or a Go template. +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | -------------------------------------- | +| .Unit | Name of the systemd unit | +| .ContainerName | Name of the container | +| .ContainerID | ID of the container | +| .Container | ID and name of the container | +| .Image | Name of the image | +| .Policy | Auto-update policy of the container | +| .Updated | Update status: true,false,failed | + + ## EXAMPLES Autoupdate with registry policy @@ -48,26 +69,31 @@ Autoupdate with registry policy ### Start a container $ podman run --label "io.containers.autoupdate=registry" \ --label "io.containers.autoupdate.authfile=/some/authfile.json" \ - -d busybox:latest top + -d --name=test registry.fedoraproject.org/fedora:latest sleep infinity bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d ### Generate a systemd unit for this container $ podman generate systemd --new --files bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d -/home/user/containers/libpod/container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service +/home/user/container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ### Load the new systemd unit and start it -$ mv ./container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ~/.config/systemd/user +$ mv ./container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service ~/.config/systemd/user/container-test.service $ systemctl --user daemon-reload ### 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. $ podman stop bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d $ podman rm bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d -$ systemctl --user start container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service +$ systemctl --user start container-test.service -### Auto-update the container +### Check if a newer image is available +$ podman auto-update --dry-run --format "{{.Image}} {{.Updated}}" +registry.fedoraproject.org/fedora:latest pending + +### Autoupdate the services $ podman auto-update -container-bc219740a210455fa27deacc96d50a9e20516492f1417507c13ce1533dbdcd9d.service +UNIT CONTAINER IMAGE POLICY UPDATED +container-test.service 08fd34e533fd (test) registry.fedoraproject.org/fedora:latest registry false ``` Autoupdate with local policy @@ -80,7 +106,7 @@ be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 ### Generate a systemd unit for this container $ podman generate systemd --new --files be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338 -/home/user/containers/libpod/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service +/home/user/container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ### Load the new systemd unit and start it $ mv ./container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service ~/.config/systemd/user @@ -102,7 +128,7 @@ $ podman commit --change CMD=/bin/bash inspiring_galileo busybox:latest ### Auto-update the container $ podman auto-update -container-be0889fd06f252a2e5141b37072c6bada68563026cb2b2649f53394d87ccc338.service +[...] ``` ## SEE ALSO diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 2c51b312d..1720e6eb6 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -646,7 +646,7 @@ Valid _mode_ values are: - **ns:**_path_: path to a network namespace to join; - **private**: create a new namespace for the container (default) - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options: - - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false. + - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`, which is added to `/etc/hosts` as `host.containers.internal` for your convenience). Default is false. - **mtu=MTU**: Specify the MTU to use for this network. (Default is `65520`). - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`). @@ -858,7 +858,7 @@ Secrets and its storage are managed using the `podman secret` command. Secret Options - `type=mount|env` : How the secret will be exposed to the container. Default mount. -- `target=target` : Target of secret. Defauts to secret name. +- `target=target` : Target of secret. Defaults to secret name. - `uid=0` : UID of secret. Defaults to 0. Mount secret type only. - `gid=0` : GID of secret. Defaults to 0. Mount secret type only. - `mode=0` : Mode of secret. Defaults to 0444. Mount secret type only. @@ -1086,14 +1086,28 @@ Set the user namespace mode for the container. It defaults to the **PODMAN_USERN Valid _mode_ values are: -- **auto[:**_OPTIONS,..._**]**: automatically create a namespace. It is possible to specify these options to `auto`: - - **gidmapping=**_HOST_GID:CONTAINER_GID:SIZE_: to force a GID mapping to be present in the user namespace. - - **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 estimate a size for the user namespace. - - **uidmapping=**_HOST_UID:CONTAINER_UID:SIZE_: to force a UID mapping to be present in the user namespace. -- **container:**_id_: join the user namespace of the specified container. -- **host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). +**auto**[:_OPTIONS,..._]: automatically create a unique user namespace. + +The `--userns=auto` flag, requires that the user name `containers` and a range of subordinate user ids that the Podman container is allowed to use be specified in the /etc/subuid and /etc/subgid files. + +Example: `containers:2147483647:2147483648`. + +Podman allocates unique ranges of UIDs and GIDs from the `containers` subpordinate user ids. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the `size` option. The `auto` options currently does not work in rootless mode + + Valid `auto`options: + + - *gidmapping*=_HOST_GID:CONTAINER_GID:SIZE_: to force a GID mapping to be present in the user namespace. + - *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 estimate a size for the user namespace. + - *uidmapping*=_HOST_UID:CONTAINER_UID:SIZE_: to force a UID mapping to be present in the user namespace. + +**container:**_id_: join the user namespace of the specified container. + +**host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). + - **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:**_namespace_: run the container in the given existing user namespace. + - **private**: create a new namespace for the container. This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. @@ -1353,6 +1367,12 @@ the uids and gids from the host. $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello ``` +### Setting automatic user namespace separated containers + +``` +# podman create --userns=auto:size=65536 ubi8-init +``` + ### Configure timezone in a container ``` diff --git a/docs/source/markdown/podman-pod-ps.1.md b/docs/source/markdown/podman-pod-ps.1.md index c1f5fd5e3..156adccaa 100644 --- a/docs/source/markdown/podman-pod-ps.1.md +++ b/docs/source/markdown/podman-pod-ps.1.md @@ -12,7 +12,9 @@ By default it lists: * pod id * pod name + * the time the pod was created * number of containers attached to pod + * container id of the pod infra container * status of pod as defined by the following table | **Status** | **Description** | @@ -28,15 +30,15 @@ By default it lists: #### **--ctr-names** -Includes the container names in the container info field +Display the container names #### **--ctr-ids** -Includes the container IDs in the container info field +Display the container IDs #### **--ctr-status** -Includes the container statuses in the container info field +Display the container statuses #### **--latest**, **-l** @@ -111,62 +113,55 @@ Print usage statement ``` $ podman pod ps -POD ID NAME STATUS NUMBER OF CONTAINERS -00dfd6fa02c0 jolly_goldstine Running 1 -f4df8692e116 nifty_torvalds Created 2 +POD ID NAME STATUS CREATED INFRA ID # OF CONTAINERS +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 1 +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 2 ``` ``` $ podman pod ps --ctr-names -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0 jolly_goldstine Running [ loving_archimedes ] -f4df8692e116 nifty_torvalds Created [ thirsty_hawking ] [ wizardly_golick ] +POD ID NAME STATUS CREATED INFRA ID NAMES +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 loving_archimedes +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a thirsty_hawking,wizardly_golick ``` ``` $ podman pod ps --ctr-status --ctr-names --ctr-ids -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0 jolly_goldstine Running [ ba465ab0a3a4 loving_archimedes Running ] -f4df8692e116 nifty_torvalds Created [ 331693bff40a thirsty_hawking Created ] [ 8e428daeb89e wizardly_golick Created ] +POD ID NAME STATUS CREATED INFRA ID IDS NAMES STATUS +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 ba465ab0a3a4 loving_archimedes running +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 331693bff40a,8e428daeb89e thirsty_hawking,wizardly_golick configured,configured ``` ``` -$ podman pod ps --format "{{.ID}} {{.ContainerInfo}} {{.Cgroup}}" --ctr-names -00dfd6fa02c0 [ loving_archimedes ] /libpod_parent -f4df8692e116 [ thirsty_hawking ] [ wizardly_golick ] /libpod_parent -``` - -``` -$ podman pod ps --cgroup -POD ID NAME STATUS NUMBER OF CONTAINERS CGROUP USE POD CGROUP -00dfd6fa02c0 jolly_goldstine Running 1 /libpod_parent true -f4df8692e116 nifty_torvalds Created 2 /libpod_parent true +$ podman pod ps --format "{{.ID}} {{.ContainerNames}} {{.Cgroup}}" +00dfd6fa02c0 loving_archimedes /libpod_parent +f4df8692e116 thirsty_hawking,wizardly_golick /libpod_parent ``` ``` $ podman pod ps --sort id --filter ctr-number=2 -POD ID NAME STATUS NUMBER OF CONTAINERS -f4df8692e116 nifty_torvalds Created 2 +POD ID NAME STATUS CREATED INFRA ID # OF CONTAINERS +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 2 ``` ``` $ podman pod ps --ctr-ids -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0 jolly_goldstine Running [ ba465ab0a3a4 ] -f4df8692e116 nifty_torvalds Created [ 331693bff40a ] [ 8e428daeb89e ] +POD ID NAME STATUS CREATED INFRA ID IDS +00dfd6fa02c0 jolly_goldstine Running 31 hours ago ba465ab0a3a4 ba465ab0a3a4 +f4df8692e116 nifty_torvalds Created 10 minutes ago 331693bff40a 331693bff40a,8e428daeb89e ``` ``` $ podman pod ps --no-trunc --ctr-ids -POD ID NAME STATUS CONTAINER INFO -00dfd6fa02c0a2daaedfdf8fcecd06f22ad114d46d167d71777224735f701866 jolly_goldstine Running [ ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 ] -f4df8692e116a3e6d1d62572644ed36ca475d933808cc3c93435c45aa139314b nifty_torvalds Created [ 331693bff40a0ef2f05a3aba73ce49e3243108911927fff04d1f7fc44dda8022 ] [ 8e428daeb89e69b71e7916a13accfb87d122889442b5c05c2d99cf94a3230e9d ] +POD ID NAME STATUS CREATED INFRA ID IDS +00dfd6fa02c0a2daaedfdf8fcecd06f22ad114d46d167d71777224735f701866 jolly_goldstine Running 31 hours ago ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 +f4df8692e116a3e6d1d62572644ed36ca475d933808cc3c93435c45aa139314b nifty_torvalds Created 10 minutes ago 331693bff40a926b6d52b184e116afd15497610c378d5d4c42945dd6e33b75b0 331693bff40a926b6d52b184e116afd15497610c378d5d4c42945dd6e33b75b0,8e428daeb89e69b71e7916a13accfb87d122889442b5c05c2d99cf94a3230e9d ``` ``` $ podman pod ps --ctr-names -POD ID NAME STATUS CONTAINER INFO -314f4da82d74 hi Created [ jovial_jackson ] [ hopeful_archimedes ] [ vibrant_ptolemy ] [ heuristic_jennings ] [ keen_raman ] [ hopeful_newton ] [ mystifying_bose ] [ silly_lalande ] [ serene_lichterman ] ... +POD ID NAME STATUS CREATED INFRA ID NAMES +314f4da82d74 hi Created 17 hours ago a9f2d2165675 jovial_jackson,hopeful_archimedes,vibrant_ptolemy,heuristic_jennings,keen_raman,hopeful_newton,mystifying_bose,silly_lalande,serene_lichterman ... ``` ## pod ps diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 10661e16e..189464d17 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -182,7 +182,7 @@ Storing signatures d6e46aa2470df1d32034c6707c8041158b652f38d2a9ae3d7ad7e7532d22ebe0 ``` -Pull an image by specifiying an authentication file. +Pull an image by specifying an authentication file. ``` $ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 6027a14a5..ce0cf1a2f 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -680,7 +680,7 @@ Valid _mode_ values are: - **ns:**_path_: path to a network namespace to join; - **private**: create a new namespace for the container (default) - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options: - - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false. + - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`, which is added to `/etc/hosts` as `host.containers.internal` for your convenience). Default is false. - **mtu=MTU**: Specify the MTU to use for this network. (Default is `65520`). - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`). - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`). @@ -908,7 +908,7 @@ Secrets and its storage are managed using the `podman secret` command. Secret Options - `type=mount|env` : How the secret will be exposed to the container. Default mount. -- `target=target` : Target of secret. Defauts to secret name. +- `target=target` : Target of secret. Defaults to secret name. - `uid=0` : UID of secret. Defaults to 0. Mount secret type only. - `gid=0` : GID of secret. Defaults to 0. Mount secret type only. - `mode=0` : Mode of secret. Defaults to 0444. Mount secret type only. @@ -1159,14 +1159,28 @@ Set the user namespace mode for the container. It defaults to the **PODMAN_USERN Valid _mode_ values are: -- **auto[:**_OPTIONS,..._**]**: automatically create a namespace. It is possible to specify these options to `auto`: - - **gidmapping=**_HOST_GID:CONTAINER_GID:SIZE_: to force a GID mapping to be present in the user namespace. - - **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 estimate a size for the user namespace. - - **uidmapping=**_HOST_UID:CONTAINER_UID:SIZE_: to force a UID mapping to be present in the user namespace. -- **container:**_id_: join the user namespace of the specified container. -- **host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). +**auto**[:_OPTIONS,..._]: automatically create a unique user namespace. + +The `--userns=auto` flag, requires that the user name `containers` and a range of subordinate user ids that the Podman container is allowed to use be specified in the /etc/subuid and /etc/subgid files. + +Example: `containers:2147483647:2147483648`. + +Podman allocates unique ranges of UIDs and GIDs from the `containers` subpordinate user ids. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the `size` option. The `auto` options currently does not work in rootless mode + + Valid `auto`options: + + - *gidmapping*=_HOST_GID:CONTAINER_GID:SIZE_: to force a GID mapping to be present in the user namespace. + - *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 estimate a size for the user namespace. + - *uidmapping*=_HOST_UID:CONTAINER_UID:SIZE_: to force a UID mapping to be present in the user namespace. + +**container:**_id_: join the user namespace of the specified container. + +**host**: run in the user namespace of the caller. The processes running in the container will have the same privileges on the host as any other process launched by the calling user (default). + - **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:**_namespace_: run the container in the given existing user namespace. + - **private**: create a new namespace for the container. This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**. @@ -1676,6 +1690,15 @@ $ echo "asdf" | podman run --rm -i --entrypoint /bin/cat someimage asdf ``` +### Setting automatic user namespace separated containers + +``` +# podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map +0 2147483647 65536 +# podman run --userns=auto:size=65536 ubi8-micro cat /proc/self/uid_map +0 2147549183 65536 +``` + ### Setting Namespaced Kernel Parameters (Sysctls) The **--sysctl** sets namespaced kernel parameters (sysctls) in the |