From bdbce9bcb1e11a982c38bf917805b714f7d78678 Mon Sep 17 00:00:00 2001 From: Daniel J Walsh Date: Thu, 6 May 2021 10:36:59 -0400 Subject: Add documentation on short-names Once we settle on the wording for short-names in podman-pull, I will add the same section to all of the podman commands that use pull. Also ran through all man pages with a spell checker. Signed-off-by: Daniel J Walsh --- docs/source/markdown/podman-build.1.md | 8 ++++---- docs/source/markdown/podman-completion.1.md | 2 +- docs/source/markdown/podman-cp.1.md | 2 +- docs/source/markdown/podman-create.1.md | 8 ++++---- docs/source/markdown/podman-generate-systemd.1.md | 2 +- docs/source/markdown/podman-machine-init.1.md | 2 +- docs/source/markdown/podman-machine-start.1.md | 2 +- docs/source/markdown/podman-machine-stop.1.md | 2 +- docs/source/markdown/podman-machine.1.md | 2 +- docs/source/markdown/podman-network-reload.1.md | 2 +- docs/source/markdown/podman-pod-create.1.md | 2 +- docs/source/markdown/podman-pull.1.md | 25 +++++++++++++++-------- docs/source/markdown/podman-run.1.md | 8 ++++---- docs/source/markdown/podman-system-service.1.md | 2 +- 14 files changed, 39 insertions(+), 30 deletions(-) (limited to 'docs/source') 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 bd2aab4c2..e4631c319 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. @@ -997,8 +997,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 +1108,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: [[1]](#Footnote1) (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: [[1]](#Footnote1) (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 0c412c2a6..3270394ac 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* @@ -1075,8 +1075,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 +1183,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: [[1]](#Footnote1) 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*) -- cgit v1.2.3-54-g00ecf