mirror of
https://github.com/containers/podman
synced 2024-10-19 08:44:11 +00:00
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 <dwalsh@redhat.com>
This commit is contained in:
parent
44184167e4
commit
bdbce9bcb1
2
Makefile
2
Makefile
|
@ -349,7 +349,7 @@ podman-remote-windows: ## Build podman-remote for Windows
|
|||
bin/windows/podman.exe
|
||||
|
||||
.PHONY: podman-remote-darwin
|
||||
podman-remote-darwin: ## Build podman-remote for MacOS
|
||||
podman-remote-darwin: ## Build podman-remote for macOS
|
||||
$(MAKE) \
|
||||
CGO_ENABLED=0 \
|
||||
GOOS=darwin \
|
||||
|
|
|
@ -658,7 +658,7 @@ 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 user namespace in the container, rather
|
||||
than being relative to the host as it would be when run rootful.
|
||||
than being relative to the host as it would be when run rootfull.
|
||||
|
||||
#### **\-\-userns-gid-map-group**=*group*
|
||||
|
||||
|
@ -673,7 +673,7 @@ 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 user namespace in the container, rather
|
||||
than being relative to the host as it would be when run rootful.
|
||||
than being relative to the host as it would be when run rootfull.
|
||||
|
||||
#### **\-\-uts**=*how*
|
||||
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -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: <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:
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
|
||||
|
||||
|
|
|
@ -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.
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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,6 +196,20 @@ 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.
|
||||
|
|
|
@ -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: <sup>[[1]](#Footnote1)</sup>
|
||||
|
||||
|
|
|
@ -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*)
|
||||
|
||||
|
|
|
@ -1,2 +1,2 @@
|
|||
# [Podman Mac Client tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md)
|
||||
This tutorial has moved! You can find out how to set up Podman on MacOS (as well as Windows) [here](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md)
|
||||
This tutorial has moved! You can find out how to set up Podman on macOS (as well as Windows) [here](https://github.com/containers/podman/blob/master/docs/tutorials/mac_win_client.md)
|
||||
|
|
|
@ -1,4 +1,4 @@
|
|||
# Podman Remote clients for MacOS and Windows
|
||||
# Podman Remote clients for macOS and Windows
|
||||
|
||||
## Introduction
|
||||
|
||||
|
@ -18,7 +18,7 @@ Once you have downloaded the installer, simply double click the installer and Po
|
|||
|
||||
Podman must be run at a command prompt using the Windows ‘cmd” or powershell applications.
|
||||
|
||||
### MacOS
|
||||
### macOS
|
||||
|
||||
The Mac Client is available through [Homebrew](https://brew.sh/). You can download homebrew via the instructions on their site. Install podman using:
|
||||
```
|
||||
|
|
|
@ -536,7 +536,7 @@ containers and pods in a way which fits very nicely in many production environme
|
|||
|
||||
|
||||
## References
|
||||
- Podman is available for most major distributions along with MacOS and Windows.
|
||||
- Podman is available for most major distributions along with macOS and Windows.
|
||||
Installation details are available on the [Podman official website](https://podman.io/getting-started/).
|
||||
|
||||
- Documentation can be found at the [Podman Docs page](https://docs.podman.io).
|
||||
|
|
Loading…
Reference in a new issue