summaryrefslogtreecommitdiff
path: root/docs/source
diff options
context:
space:
mode:
authorOpenShift Merge Robot <openshift-merge-robot@users.noreply.github.com>2021-05-07 10:23:26 -0400
committerGitHub <noreply@github.com>2021-05-07 10:23:26 -0400
commit5616887f62b4bed1031cdade8bd602bc2cb9d8f4 (patch)
tree63e764cf61e5ace949ea2cc9ae891e9a47da1b13 /docs/source
parentaa5cd674aec28ecf207d6982797b1bb000a2b322 (diff)
parentbdbce9bcb1e11a982c38bf917805b714f7d78678 (diff)
downloadpodman-5616887f62b4bed1031cdade8bd602bc2cb9d8f4.tar.gz
podman-5616887f62b4bed1031cdade8bd602bc2cb9d8f4.tar.bz2
podman-5616887f62b4bed1031cdade8bd602bc2cb9d8f4.zip
Merge pull request #10249 from rhatdan/man1
[CI:DOCS] Add documentation on short-names
Diffstat (limited to 'docs/source')
-rw-r--r--docs/source/markdown/podman-build.1.md8
-rw-r--r--docs/source/markdown/podman-completion.1.md2
-rw-r--r--docs/source/markdown/podman-cp.1.md2
-rw-r--r--docs/source/markdown/podman-create.1.md8
-rw-r--r--docs/source/markdown/podman-generate-systemd.1.md2
-rw-r--r--docs/source/markdown/podman-machine-init.1.md2
-rw-r--r--docs/source/markdown/podman-machine-start.1.md2
-rw-r--r--docs/source/markdown/podman-machine-stop.1.md2
-rw-r--r--docs/source/markdown/podman-machine.1.md2
-rw-r--r--docs/source/markdown/podman-network-reload.1.md2
-rw-r--r--docs/source/markdown/podman-pod-create.1.md2
-rw-r--r--docs/source/markdown/podman-pull.1.md25
-rw-r--r--docs/source/markdown/podman-run.1.md8
-rw-r--r--docs/source/markdown/podman-system-service.1.md2
14 files changed, 39 insertions, 30 deletions
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 d59793f28..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.
@@ -1002,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**
@@ -1113,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 0ab8f04db..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*
@@ -1080,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**
@@ -1188,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-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*)