diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/podman-create.1.md | 33 | ||||
| -rw-r--r-- | docs/podman-image-trust.1.md | 30 | ||||
| -rw-r--r-- | docs/podman-run.1.md | 38 | ||||
| -rw-r--r-- | docs/podman-stats.1.md | 9 |
4 files changed, 81 insertions, 29 deletions
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md index 98b1a2a17..2dffaff3b 100644 --- a/docs/podman-create.1.md +++ b/docs/podman-create.1.md @@ -657,18 +657,21 @@ The followings examples are all valid: Without this argument the command will be run as root in the container. -**--userns**="" +**--userns**=host +**--userns**=ns:my_namespace -Set the usernamespace mode for the container. The use of userns is disabled by default. +Set the user namespace mode for the container. The use of userns is disabled by default. - **host**: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`). - **ns**: specify the usernamespace to use. +- `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. +- `ns`: run the container in the given existing user namespace. + +This option is incompatible with --gidmap, --uidmap, --subuid and --subgid **--uts**=*host* Set the UTS mode for the container **host**: use the host's UTS namespace inside the container. - **ns**: specify the usernamespace to use. + **ns**: specify the user namespace to use. Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure. **--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*] @@ -782,8 +785,8 @@ can override the working directory by using the **-w** option. ### Set UID/GID mapping in a new user namespace -If you want to run the container in a new user namespace and define the mapping of -the uid and gid from the host. +Running a container in a new user namespace requires a mapping of +the uids and gids from the host. ``` $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello @@ -804,13 +807,27 @@ KillMode=process WantedBy=multi-user.target ``` +### Rootless Containers + +Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils +be installed. The shadow-utils package must include the newuidmap and newgidmap executables. + +Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released. + +In order for users to run rootless, there must be an entry for their username in /etc/subuid and /etc/subgid which lists the UIDs for their user namespace. + +Rootless podman works better if the fuse-overlayfs and slirp4netns packages are installed. +The fuse-overlay package provides a userspace overlay storage driver, otherwise users need to use +the vfs storage driver, which is diskspace expensive and does not perform well. slirp4netns is +required for VPN, without it containers need to be run with the --net=host flag. + ## FILES **/etc/subuid** **/etc/subgid** ## SEE ALSO -subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8) +subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1) ## HISTORY October 2017, converted from Docker documentation to podman by Dan Walsh for podman <dwalsh@redhat.com> diff --git a/docs/podman-image-trust.1.md b/docs/podman-image-trust.1.md index 668fee0f3..819035040 100644 --- a/docs/podman-image-trust.1.md +++ b/docs/podman-image-trust.1.md @@ -14,19 +14,29 @@ podman\-trust - Manage container registry image trust policy REGISTRY[/REPOSITORY] # DESCRIPTION -Manages which registries you trust as a source of container images based on its location. The location is determined by the transport and the registry host of the image. Using this container image `docker://docker.io/library/busybox` as an example, `docker` is the transport and `docker.io` is the registry host. +Manages which registries you trust as a source of container images based on its location. The location is determined +by the transport and the registry host of the image. Using this container image `docker://docker.io/library/busybox` +as an example, `docker` is the transport and `docker.io` is the registry host. -The trust policy describes a registry scope (registry and/or repository). This trust can use public keys for signed images. +Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull +a remote image from a registry. The trust policy in policy.json describes a registry scope (registry and/or repository) for the trust. This trust can use public keys for signed images. -Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull an image from a registry that is managed by policy.json. +The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry. Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry. -The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry. Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry. See below for examples. +For example, the following list includes valid scope values that could be used in policy.json from most specific to the least specific: + +docker.io/library/busybox:notlatest +docker.io/library/busybox +docker.io/library +docker.io + +If no configuration is found for any of these scopes, the default value (specified by using "default" instead of REGISTRY[/REPOSITORY]) is used. Trust **type** provides a way to: Whitelist ("accept") or -Blacklist ("reject") registries. - +Blacklist ("reject") registries or +Require signature (“signedBy”). Trust may be updated using the command **podman image trust set** for an existing trust scope. @@ -36,10 +46,8 @@ Trust may be updated using the command **podman image trust set** for an existin **-f** **--pubkeysfile** A path to an exported public key on the local system. Key paths - will be referenced in policy.json. Any path may be used but the path - **/etc/pki/containers** is recommended. Options may be used multiple times to - require an image be signed by multiple keys. One of **--pubkeys** or - **--pubkeysfile** is required for the **signedBy** type. + will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to + require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** type. **-t** **--type** The trust type for this policy entry. Accepted values: @@ -84,7 +92,5 @@ Display trust as JSON policy-json(5) # HISTORY - January 2019, updated by Tom Sweeney (tsweeney at redhat dot com) - December 2018, originally compiled by Qi Wang (qiwan at redhat dot com) diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md index 828ae96a8..cef9a6e8a 100644 --- a/docs/podman-run.1.md +++ b/docs/podman-run.1.md @@ -663,7 +663,7 @@ Without this argument the command will be run as root in the container. **--userns**=host **--userns**=ns:my_namespace -Set the user namespace for the container. +Set the user namespace mode for the container. The use of userns is disabled by default. - `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. - `ns`: run the container in the given existing user namespace. @@ -675,7 +675,7 @@ This option is incompatible with --gidmap, --uidmap, --subuid and --subgid Set the UTS mode for the container `host`: use the host's UTS namespace inside the container. -`ns`: specify the usernamespace to use. +`ns`: specify the user namespace to use. **NOTE**: the host mode gives the container access to changing the host's hostname and is therefore considered insecure. @@ -709,6 +709,20 @@ Current supported mount TYPES are bind, and tmpfs. · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. +**--userns**="" + +Set the user namespace mode for the container. The use of userns is disabled by default. + + **host**: use the host user namespace and enable all privileged options (e.g., `pid=host` or `--privileged`). + **ns**: specify the user namespace to use. + +**--uts**=*host* + +Set the UTS mode for the container + **host**: use the host's UTS namespace inside the container. + **ns**: specify the user namespace to use. + Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure. + **--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*] Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman @@ -1074,8 +1088,8 @@ supported sysctls. ### Set UID/GID mapping in a new user namespace -If you want to run the container in a new user namespace and define the mapping of -the uid and gid from the host. +Running a container in a new user namespace requires a mapping of +the uids and gids from the host. ``` $ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello @@ -1096,13 +1110,27 @@ KillMode=process WantedBy=multi-user.target ``` +### Rootless Containers + +Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils +be installed. The shadow-utils package must include the newuidmap and newgidmap executables. + +Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released. + +In order for users to run rootless, there must be an entry for their username in /etc/subuid and /etc/subgid which lists the UIDs for their user namespace. + +Rootless podman works better if the fuse-overlayfs and slirp4netns packages are installed. +The fuse-overlay package provides a userspace overlay storage driver, otherwise users need to use +the vfs storage driver, which is diskspace expensive and does not perform well. slirp4netns is +required for VPN, without it containers need to be run with the --net=host flag. + ## FILES **/etc/subuid** **/etc/subgid** ## SEE ALSO -subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8) +subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1) ## HISTORY September 2018, updated by Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp> diff --git a/docs/podman-stats.1.md b/docs/podman-stats.1.md index 8fc765326..d0b56b2e6 100644 --- a/docs/podman-stats.1.md +++ b/docs/podman-stats.1.md @@ -36,16 +36,17 @@ Valid placeholders for the Go template are listed below: | **Placeholder** | **Description** | | --------------- | --------------- | -| .ID | Container ID | +| .Pod | Pod ID | +| .CID | Container ID | | .Name | Container Name | -| .CPUPerc | CPU percentage | +| .CPU | CPU percentage | | .MemUsage | Memory usage | -| .MemPerc | Memory percentage | +| .Mem | Memory percentage | | .NetIO | Network IO | | .BlockIO | Block IO | | .PIDS | Number of PIDs | - +When using a GO template, you may preceed the format with `table` to print headers. ## EXAMPLE ``` |