diff options
Diffstat (limited to 'docs/source')
19 files changed, 99 insertions, 46 deletions
diff --git a/docs/source/conf.py b/docs/source/conf.py index 52869baf4..7a180e5ef 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -44,6 +44,10 @@ exclude_patterns = [] master_doc = "index" +# Configure smartquotes to only transform quotes and ellipses, not dashes +smartquotes_action = "qe" + + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md index f298d6bf6..12e8bc70f 100644 --- a/docs/source/markdown/podman-auto-update.1.md +++ b/docs/source/markdown/podman-auto-update.1.md @@ -14,7 +14,7 @@ The label "image" is an alternative to "registry" maintained for backwards compa An image is considered updated if the digest in the local storage is different than the one of the remote image. If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container. -The registry policy requires a requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. +The registry policy requires a fully-qualified image reference (e.g., quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary to know which image to actually check and pull. If an image ID was used, Podman would not know which image to check/pull anymore. diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 9fc4ffb5b..1d6aa3d40 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -657,8 +657,8 @@ specified, `podman` will assume that the specified group name is also a suitable user name to use as the default setting for this option. **NOTE:** When this option is specified by a rootless user, the specified -mappings are relative to the rootless usernamespace in the container, rather -than being relative to the host as it would be when run rootful. +mappings are relative to the rootless user namespace in the container, rather +than being relative to the host as it would be when run rootfull. #### **\-\-userns-gid-map-group**=*group* @@ -672,8 +672,8 @@ specified, `podman` will assume that the specified user name is also a suitable group name to use as the default setting for this option. **NOTE:** When this option is specified by a rootless user, the specified -mappings are relative to the rootless usernamespace in the container, rather -than being relative to the host as it would be when run rootful. +mappings are relative to the rootless user namespace in the container, rather +than being relative to the host as it would be when run rootfull. #### **\-\-uts**=*how* diff --git a/docs/source/markdown/podman-completion.1.md b/docs/source/markdown/podman-completion.1.md index 964f3264e..cff9c7878 100644 --- a/docs/source/markdown/podman-completion.1.md +++ b/docs/source/markdown/podman-completion.1.md @@ -41,7 +41,7 @@ If shell completion is not already enabled in the environment you will need to e To make it available for all zsh sessions run: `podman completion zsh -f "${fpath[1]}/_podman"` -Once you reload the shell the autocompletion should be working. +Once you reload the shell the auto-completion should be working. ### FISH diff --git a/docs/source/markdown/podman-cp.1.md b/docs/source/markdown/podman-cp.1.md index bafbbdf3b..f245ad1aa 100644 --- a/docs/source/markdown/podman-cp.1.md +++ b/docs/source/markdown/podman-cp.1.md @@ -31,7 +31,7 @@ Assuming a path separator of /, a first argument of **src_path** and second argu - **dest_path** exists and is a file - the destination is overwritten with the source file's contents - **dest_path** exists and is a directory - - the file is copied into this directory using the basename from **src_path** + - the file is copied into this directory using the base name from **src_path** **src_path** specifies a directory - **dest_path** does not exist diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 25b2fe11a..b4593e07a 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -87,7 +87,7 @@ Attach to STDIN, STDOUT or STDERR. In foreground mode (the default when **-d** is not specified), **podman run** can start the process in the container and attach the console to the process's standard input, output, and standard -error. It can even pretend to be a TTY (this is what most commandline +error. It can even pretend to be a TTY (this is what most command line executables expect) and pass along signals. The **-a** option can be set for each of stdin, stdout, and stderr. @@ -840,7 +840,7 @@ Specify the policy to select the seccomp profile. If set to *image*, Podman will Note that this feature is experimental and may change in the future. -#### **\-\-secret**=*secret* +#### **\-\-secret**=*secret*[,opt=opt ...] Give the container access to a secret. Can be specified multiple times. @@ -848,12 +848,17 @@ A secret is a blob of sensitive data which a container needs at runtime but should not be stored in the image or in source control, such as usernames and passwords, TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size). -Secrets are copied and mounted into the container when a container is created. If a secret is deleted using -`podman secret rm`, the container will still have access to the secret. If a secret is deleted and -another secret is created with the same name, the secret inside the container will not change; the old -secret value will still remain. +When secrets are specified as type `mount`, the secrets are copied and mounted into the container when a container is created. +When secrets are specified as type `env`, the secret will be set as an environment variable within the container. +Secrets are written in the container at the time of container creation, and modifying the secret using `podman secret` commands +after the container is created will not affect the secret inside the container. -Secrets are managed using the `podman secret` command. +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. #### **\-\-security-opt**=*option* @@ -952,7 +957,7 @@ The `container_manage_cgroup` boolean must be enabled for this to be allowed on #### **\-\-timeout**=*seconds* -Maximimum time a container is allowed to run before conmon sends it the kill +Maximum time a container is allowed to run before conmon sends it the kill signal. By default containers will run until they exit or are stopped by `podman stop`. @@ -997,8 +1002,8 @@ option conflicts with the **\-\-userns** and **\-\-subuidname** options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. -The _from_uid_ value is based upon the user running the command, either rootful or rootless users. -* rootful user: *container_uid*:*host_uid*:*amount* +The _from_uid_ value is based upon the user running the command, either rootfull or rootless users. +* rootfull user: *container_uid*:*host_uid*:*amount* * rootless user: *container_uid*:*intermediate_uid*:*amount* When **podman create** is called by a privileged user, the option **\-\-uidmap** @@ -1108,7 +1113,7 @@ Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume in the host to the container. If no such named volume exists, Podman will -create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.) +create one. The `OPTIONS` are a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> (Note when using the remote client, the volumes will be mounted from the remote server, not necessarily the client machine.) The _options_ is a comma-separated list and can be: diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index 1d427d35b..7dccc5c1f 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -236,7 +236,7 @@ bb310a0780ae docker.io/library/alpine:latest /bin/sh 3 minutes ago Created [**podman**(1)](podman.1.md), [**podman-container**(1)](podman-container.1.md), **systemctl**(1), **systemd.unit**(5), **systemd.service**(5), **conmon**(8). ## 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) +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) diff --git a/docs/source/markdown/podman-machine-init.1.md b/docs/source/markdown/podman-machine-init.1.md index 946f959bf..8947967aa 100644 --- a/docs/source/markdown/podman-machine-init.1.md +++ b/docs/source/markdown/podman-machine-init.1.md @@ -10,7 +10,7 @@ podman\-machine\-init - Initialize a new virtual machine Initialize a new virtual machine for Podman. -Podman on MacOS requires a virtual machine. This is because containers are Linux - +Podman on macOS requires a virtual machine. This is because containers are Linux - containers do not run on any other OS because containers' core functionality are tied to the Linux kernel. diff --git a/docs/source/markdown/podman-machine-start.1.md b/docs/source/markdown/podman-machine-start.1.md index b430f51eb..b21bbd65c 100644 --- a/docs/source/markdown/podman-machine-start.1.md +++ b/docs/source/markdown/podman-machine-start.1.md @@ -10,7 +10,7 @@ podman\-machine\-start - Start a virtual machine Starts a virtual machine for Podman. -Podman on MacOS requires a virtual machine. This is because containers are Linux - +Podman on macOS requires a virtual machine. This is because containers are Linux - containers do not run on any other OS because containers' core functionality are tied to the Linux kernel. diff --git a/docs/source/markdown/podman-machine-stop.1.md b/docs/source/markdown/podman-machine-stop.1.md index 33c67f70b..e2037144c 100644 --- a/docs/source/markdown/podman-machine-stop.1.md +++ b/docs/source/markdown/podman-machine-stop.1.md @@ -10,7 +10,7 @@ podman\-machine\-stop - Stop a virtual machine Stops a virtual machine. -Podman on MacOS requires a virtual machine. This is because containers are Linux - +Podman on macOS requires a virtual machine. This is because containers are Linux - containers do not run on any other OS because containers' core functionality are tied to the Linux kernel. diff --git a/docs/source/markdown/podman-machine.1.md b/docs/source/markdown/podman-machine.1.md index 693f42fe3..40f69c0ba 100644 --- a/docs/source/markdown/podman-machine.1.md +++ b/docs/source/markdown/podman-machine.1.md @@ -7,7 +7,7 @@ podman\-machine - Manage Podman's virtual machine **podman machine** *subcommand* ## DESCRIPTION -`podman machine` is a set of subcommands that manage Podman's virtual machine on MacOS. +`podman machine` is a set of subcommands that manage Podman's virtual machine on macOS. ## SUBCOMMANDS diff --git a/docs/source/markdown/podman-network-reload.1.md b/docs/source/markdown/podman-network-reload.1.md index a4204a397..8f88585f2 100644 --- a/docs/source/markdown/podman-network-reload.1.md +++ b/docs/source/markdown/podman-network-reload.1.md @@ -9,7 +9,7 @@ podman\-network\-reload - Reload network configuration for containers ## DESCRIPTION Reload one or more container network configurations. -Rootful Podman relies on iptables rules in order to provide network connectivity. If the iptables rules are deleted, +Rootfull Podman relies on iptables rules in order to provide network connectivity. If the iptables rules are deleted, this happens for example with `firewall-cmd --reload`, the container loses network connectivity. This command restores the network connectivity. diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index 6f3d7f1ca..701c0edf6 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -82,7 +82,7 @@ Assign a name to the pod. #### **\-\-network**=*mode*, **\-\-net** Set network mode for the pod. Supported values are -- **bridge**: Create a network stack on the default bridge. This is the default for rootful containers. +- **bridge**: Create a network stack on the default bridge. This is the default for rootfull containers. - **host**: Do not create a network namespace, all containers in the pod will use the host's network. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. - Comma-separated list of the names of CNI networks the pod should join. - **slirp4netns[:OPTIONS,...]**: use slirp4netns to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options: diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 79563fb57..2e038fd70 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -13,13 +13,8 @@ podman\-pull - Pull an image from a registry **podman image pull** [*options*] [*transport*]*name*[:*tag*|@*digest*] ## DESCRIPTION -Copies an image from a registry onto the local machine. **podman pull** pulls an -image from Docker Hub if a registry is not specified in the command line argument. -If an image tag is not specified, **podman pull** defaults to the image with the -**latest** tag (if it exists) and pulls it. After the image is pulled, podman will -print the full image ID. **podman pull** can also pull an image -using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull -images from archives and local storage using different transports. +Copies an image from a registry onto the local machine. The **podman pull** command pulls an +image. If the image reference in the command line argument does not contain a registry, it is referred to as a`short-name` reference. If the image is a 'short-name' reference, Podman will prompt the user for the specific container registry to pull the image from, if an alias for the short-name has not been specified in the short-name-aliases.conf. If an image tag is not specified, **podman pull** defaults to the image with the **latest** tag (if it exists) and pulls it. After the image is pulled, podman will print the full image ID. **podman pull** can also pull an image using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull images from archives and local storage using different transports. ## Image storage Images are stored in local image storage. @@ -201,9 +196,23 @@ Storing signatures ## FILES +**short-name-aliases.conf** (`/var/cache/containers/short-name-aliases.conf`, `$HOME/.cache/containers/short-name-aliases.conf`) + +When users specify images that do not include the container registry where the +image is stored, this is called a short name. The use of unqualified-search registries entails an ambiguity as it is unclear from which registry a given image, referenced by a short name, may be pulled from. + +Using short names is subject to the risk of hitting squatted registry namespaces. If the unqualified-search registries are set to ["public-registry.com", "my-private-registry.com"] an attacker may take over a namespace of `public-registry.com` such that an image may be pulled from `public-registry.com` instead of the intended source `my-private-registry.com`. + +While it is highly recommended to always use fully-qualified image references, existing deployments using short names may not be easily changed. To circumvent the aforementioned ambiguity, so called short-name aliases can be configured that point to a fully-qualified image reference. Distributions often ship a default shortnames.conf expansion file in /etc/containers/registries.conf.d/ directory. Administrators can use this directory to add their own local short-name expansion files. + +When pulling an image, if the user does not specify the complete registry, container engines attempt to expand the short-name into a full name. If the command is executed with a tty, the user will be prompted to select a registry from the +default list unqualified registries defined in registries.conf. The user's selection is then stored in a cache file to be used in all future short-name expansions. Rootfull short-names are stored in /var/cache/containers/short-name-aliases.conf. Rootless short-names are stored in the $HOME/.cache/containers/short-name-aliases.conf file. + +For more information on short-names, see `containers-registries.conf(5)` + **registries.conf** (`/etc/containers/registries.conf`) - registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. +registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 8689014c0..f371cacbf 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -150,7 +150,7 @@ Default is **enabled**. The **enabled** option will create a new cgroup under the cgroup-parent. The **disabled** option will force the container to not create CGroups, and thus conflicts with CGroup options (**\-\-cgroupns** and **\-\-cgroup-parent**). The **no-conmon** option disables a new CGroup only for the **conmon** process. -The **split** option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **\-\-cgroup-parent** with **split**. +The **split** option splits the current CGroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set **\-\-cgroup-parent** with **split**. #### **\-\-cgroup-parent**=*path* @@ -892,7 +892,7 @@ Specify the policy to select the seccomp profile. If set to *image*, Podman will Note that this feature is experimental and may change in the future. -#### **\-\-secret**=*secret* +#### **\-\-secret**=*secret*[,opt=opt ...] Give the container access to a secret. Can be specified multiple times. @@ -900,12 +900,17 @@ A secret is a blob of sensitive data which a container needs at runtime but should not be stored in the image or in source control, such as usernames and passwords, TLS certificates and keys, SSH keys or other important generic strings or binary content (up to 500 kb in size). -Secrets are copied and mounted into the container when a container is created. If a secret is deleted using -`podman secret rm`, the container will still have access to the secret. If a secret is deleted and -another secret is created with the same name, the secret inside the container will not change; the old -secret value will still remain. +When secrets are specified as type `mount`, the secrets are copied and mounted into the container when a container is created. +When secrets are specified as type `env`, the secret will be set as an environment variable within the container. +Secrets are written in the container at the time of container creation, and modifying the secret using `podman secret` commands +after the container is created will not affect the secret inside the container. -Secrets are managed using the `podman secret` command +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. #### **\-\-security-opt**=*option* @@ -1025,7 +1030,7 @@ setsebool -P container_manage_cgroup true #### **\-\-timeout**=*seconds* -Maximimum time a container is allowed to run before conmon sends it the kill +Maximum time a container is allowed to run before conmon sends it the kill signal. By default containers will run until they exit or are stopped by `podman stop`. @@ -1075,8 +1080,8 @@ option conflicts with the **\-\-userns** and **\-\-subuidname** options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges. -The _from_uid_ value is based upon the user running the command, either rootful or rootless users. -* rootful user: *container_uid*:*host_uid*:*amount* +The _from_uid_ value is based upon the user running the command, either rootfull or rootless users. +* rootfull user: *container_uid*:*host_uid*:*amount* * rootless user: *container_uid*:*intermediate_uid*:*amount* When **podman run** is called by a privileged user, the option **\-\-uidmap** @@ -1183,7 +1188,7 @@ Create a bind mount. If you specify _/HOST-DIR_:_/CONTAINER-DIR_, Podman bind mounts _host-dir_ in the host to _CONTAINER-DIR_ in the Podman container. Similarly, _SOURCE-VOLUME_:_/CONTAINER-DIR_ will mount the volume in the host to the container. If no such named volume exists, Podman will -create one. (Note when using the remote client, the volumes will be mounted from the remote server, not necessarly the client machine.) +create one. (Note when using the remote client, the volumes will be mounted from the remote server, not necessarily the client machine.) The _options_ is a comma-separated list and can be: <sup>[[1]](#Footnote1)</sup> diff --git a/docs/source/markdown/podman-save.1.md b/docs/source/markdown/podman-save.1.md index 0036a9379..cae0c4b05 100644 --- a/docs/source/markdown/podman-save.1.md +++ b/docs/source/markdown/podman-save.1.md @@ -45,6 +45,7 @@ Save image to **oci-archive, oci-dir** (directory with oci manifest type), or ** #### **\-\-multi-image-archive**, **-m** Allow for creating archives with more than one image. Additional names will be interpreted as images instead of tags. Only supported for **docker-archive**. +The default for this option can be modified via the `multi_image_archive="true"|"false"` flag in containers.conf. #### **\-\-quiet**, **-q** @@ -99,7 +100,7 @@ Storing signatures ``` ## SEE ALSO -podman(1), podman-load(1) +podman(1), podman-load(1), containers.conf(5) ## HISTORY July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/markdown/podman-secret-create.1.md b/docs/source/markdown/podman-secret-create.1.md index f5a97a0f3..7aacca3fe 100644 --- a/docs/source/markdown/podman-secret-create.1.md +++ b/docs/source/markdown/podman-secret-create.1.md @@ -20,6 +20,10 @@ Secrets will not be committed to an image with `podman commit`, and will not be ## OPTIONS +#### **\-\-env**=*false* + +Read secret data from environment variable + #### **\-\-driver**=*driver* Specify the secret driver (default **file**, which is unencrypted). diff --git a/docs/source/markdown/podman-start.1.md b/docs/source/markdown/podman-start.1.md index 626e6e368..7085f3f47 100644 --- a/docs/source/markdown/podman-start.1.md +++ b/docs/source/markdown/podman-start.1.md @@ -42,6 +42,31 @@ Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and Start all the containers created by Podman, default is only running containers. +#### **\-\-filter**, **-f** + +Filter what containers are going to be started from the given arguments. +Multiple filters can be given with multiple uses of the --filter flag. +Filters with the same key work inclusive with the only exception being +`label` which is exclusive. Filters with different keys always work exclusive. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID (accepts regex) | +| name | [Name] Container's name (accepts regex) | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: 'created', 'exited', 'paused', 'running', 'unknown' | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | +| pod | [Pod] name or full or partial ID of pod | +| network | [Network] name or full ID of network | + + ## EXAMPLE podman start mywebserver diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 5ad4eff5b..fddcece60 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -9,7 +9,7 @@ podman\-system\-service - Run an API service ## DESCRIPTION The **podman system service** command creates a listening service that will answer API calls for Podman. You may optionally provide an endpoint for the API in URI form. For example, *unix:///tmp/foobar.sock* or *tcp:localhost:8080*. -If no endpoint is provided, defaults will be used. The default endpoint for a rootful +If no endpoint is provided, defaults will be used. The default endpoint for a rootfull service is *unix:///run/podman/podman.sock* and rootless is *unix://$XDG_RUNTIME_DIR/podman/podman.sock* (for example *unix:///run/user/1000/podman/podman.sock*) |