diff options
Diffstat (limited to 'docs/source')
| -rw-r--r-- | docs/source/Introduction.rst | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-build.1.md | 17 | ||||
| -rw-r--r-- | docs/source/markdown/podman-container-runlabel.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 36 | ||||
| -rw-r--r-- | docs/source/markdown/podman-generate-kube.1.md | 12 | ||||
| -rw-r--r-- | docs/source/markdown/podman-generate.1.md | 6 | ||||
| -rw-r--r-- | docs/source/markdown/podman-play-kube.1.md | 26 | ||||
| -rw-r--r-- | docs/source/markdown/podman-play.1.md | 6 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 35 | ||||
| -rw-r--r-- | docs/source/markdown/podman-system-service.1.md | 6 | ||||
| -rw-r--r-- | docs/source/markdown/podman-unshare.1.md | 37 | ||||
| -rw-r--r-- | docs/source/markdown/podman.1.md | 4 |
12 files changed, 161 insertions, 28 deletions
diff --git a/docs/source/Introduction.rst b/docs/source/Introduction.rst index 9fdce6962..3fa86f868 100644 --- a/docs/source/Introduction.rst +++ b/docs/source/Introduction.rst @@ -32,7 +32,7 @@ There’s an old saying that “nobody runs an operating system just to run an o Sometimes we can find a publicly available container image for the exact workload we’re looking for and it will already be packaged exactly how we want. But, more often than not, there’s something that we want to add, remove, or customize. It could be as simple as a configuration setting for security or performance, or as complex as adding a complex workload. Either way, containers make it fairly easy to make the changes we need. -Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build the new and can easily be shared with others publicly using tools like GitHub. +Container Images aren’t actually images, they’re repositories often made up of multiple layers. These layers can easily be added, saved, and shared with others by using a Containerfile (Dockerfile). This single file often contains all the instructions needed to build a new container image and can easily be shared with others publicly using tools like GitHub. Here's an example of how to build a Nginx web server on top of a Debian base image using the Dockerfile maintained by Nginx and published in GitHub:: diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 1bb3c2c3a..876bfe412 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -12,8 +12,8 @@ podman\-build - Build a container image using a Containerfile **podman build** Builds an image using instructions from one or more Containerfiles or Dockerfiles and a specified build context directory. A Containerfile uses the same syntax as a Dockerfile internally. For this -document, a file referred to as a Containerfile can be a file named either -'Containerfile' or 'Dockerfile'. +document, a file referred to as a Containerfile can be a file named +either 'Containerfile' or 'Dockerfile'. The build context directory can be specified as the http(s) URL of an archive, git repository or Containerfile. @@ -692,6 +692,7 @@ Set the architecture variant of the image to be pulled. * [rw|ro] * [z|Z|O] + * [U] * [`[r]shared`|`[r]slave`|`[r]private`] The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR` @@ -707,6 +708,18 @@ You can add the `:ro` or `:rw` suffix to a volume to mount it read-only or read-write mode, respectively. By default, the volumes are mounted read-write. See examples. + `Chowning Volume Mounts` + +By default, Podman does not change the owner and group of source volume +directories mounted. When running using user namespaces, the UID and GID inside +the namespace may correspond to another UID and GID on the host. + +The `:U` suffix tells Podman to use the correct host UID and GID based on the +UID and GID within the namespace, to change recursively the owner and group of +the source volume. + +**Warning** use with caution since this will modify the host filesystem. + `Labeling Volume Mounts` Labeling systems like SELinux require that proper labels are placed on volume diff --git a/docs/source/markdown/podman-container-runlabel.1.md b/docs/source/markdown/podman-container-runlabel.1.md index 84d283cf8..9557303b6 100644 --- a/docs/source/markdown/podman-container-runlabel.1.md +++ b/docs/source/markdown/podman-container-runlabel.1.md @@ -13,7 +13,7 @@ exist, `podman container runlabel` will just exit. If the container image has a LABEL INSTALL instruction like the following: -`LABEL INSTALL /usr/bin/podman run -t -i --rm \${OPT1} --privileged -v /:/host --net=host --ipc=host --pid=host -e HOST=/host -e NAME=\${NAME} -e IMAGE=\${IMAGE} -e CONFDIR=\/etc/${NAME} -e LOGDIR=/var/log/\${NAME} -e DATADIR=/var/lib/\${NAME} \${IMAGE} \${OPT2} /bin/install.sh \${OPT3}` +`LABEL INSTALL /usr/bin/podman run -t -i --rm \${OPT1} --privileged -v /:/host --net=host --ipc=host --pid=host -e HOST=/host -e NAME=\${NAME} -e IMAGE=\${IMAGE} -e CONFDIR=/etc/\${NAME} -e LOGDIR=/var/log/\${NAME} -e DATADIR=/var/lib/\${NAME} \${IMAGE} \${OPT2} /bin/install.sh \${OPT3}` `podman container runlabel` will set the following environment variables for use in the command: diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 927b3df33..ae6dfe03b 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -781,6 +781,12 @@ If container is running in --read-only mode, then mount a read-write tmpfs on /r If another container with the same name already exists, replace and remove it. The default is **false**. +#### **\-\-requires**=**container** + +Specify one or more requirements. +A requirement is a dependency container that will be started before this container. +Containers can be specified by name or ID, with multiple containers being separated by commas. + #### **\-\-restart**=*policy* Restart policy to follow when containers exit. @@ -1069,9 +1075,14 @@ See examples. `Chowning Volume Mounts` -By default, Podman does not change the owner and group of source volume directories mounted into containers. If a container is created in a new user namespace, the UID and GID in the container may correspond to another UID and GID on the host. +By default, Podman does not change the owner and group of source volume +directories mounted into containers. If a container is created in a new user +namespace, the UID and GID in the container may correspond to another UID and +GID on the host. -The `:U` suffix tells Podman to use the correct host UID and GID based on the UID and GID within the container, to change recursively the owner and group of the source volume. +The `:U` suffix tells Podman to use the correct host UID and GID based on the +UID and GID within the container, to change recursively the owner and group of +the source volume. **Warning** use with caution since this will modify the host filesystem. @@ -1250,6 +1261,25 @@ $ podman create --tz=Asia/Shanghai alpine date $ podman create --tz=US/Eastern alpine date ``` +### Adding dependency containers + +Podman will make sure the first container, container1, is running before the second container (container2) is started. + +``` +$ podman create --name container1 -t -i fedora bash +$ podman create --name container2 --requires container1 -t -i fedora bash +$ podman start --attach container2 +``` + +Multiple containers can be required. + +``` +$ podman create --name container1 -t -i fedora bash +$ podman create --name container2 -t -i fedora bash +$ podman create --name container3 --requires container1,container2 -t -i fedora bash +$ podman start --attach container3 +``` + ### Rootless Containers Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils @@ -1297,7 +1327,7 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**podman**(1), **podman-secret**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-kill**(1), **podman-stop**(1), +**podman**(1), **podman-secret**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-start*(1), **podman-kill**(1), **podman-stop**(1), **podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**. ## HISTORY diff --git a/docs/source/markdown/podman-generate-kube.1.md b/docs/source/markdown/podman-generate-kube.1.md index 90b4c59fb..a426d2c3c 100644 --- a/docs/source/markdown/podman-generate-kube.1.md +++ b/docs/source/markdown/podman-generate-kube.1.md @@ -1,14 +1,16 @@ % podman-generate-kube(1) ## NAME -podman-generate-kube - Generate Kubernetes YAML based on a pod or container +podman-generate-kube - Generate Kubernetes YAML based on containers, pods or volumes ## SYNOPSIS -**podman generate kube** [*options*] *container...* | *pod* +**podman generate kube** [*options*] *container...* | *pod...* | *volume...* ## DESCRIPTION -**podman generate kube** will generate Kubernetes Pod YAML (v1 specification) from Podman from one or more containers or a single pod. Whether -the input is for containers or a pod, Podman will always generate the specification as a Pod. The input may be in the form -of a pod or one or more container names or IDs. +**podman generate kube** will generate Kubernetes YAML (v1 specification) from Podman containers, pods or volumes. Whether +the input is for containers or pods, Podman will always generate the specification as a Pod. The input may be in the form +of one or more containers, pods or volumes names or IDs. + +`Podman Containers or Pods` Volumes appear in the generated YAML according to two different volume types. Bind-mounted volumes become *hostPath* volume types and named volumes become *persistentVolumeClaim* volume types. Generated *hostPath* volume types will be one of three subtypes depending on the state of the host path: *DirectoryOrCreate* when no file or directory exists at the host, *Directory* when host path is a directory, or *File* when host path is a file. The value for *claimName* for a *persistentVolumeClaim* is the name of the named volume registered in Podman. diff --git a/docs/source/markdown/podman-generate.1.md b/docs/source/markdown/podman-generate.1.md index 82c67fdb1..c2060d1a4 100644 --- a/docs/source/markdown/podman-generate.1.md +++ b/docs/source/markdown/podman-generate.1.md @@ -1,19 +1,19 @@ % podman-generate(1) ## NAME -podman\-generate - Generate structured data based for a containers and pods +podman\-generate - Generate structured data based on containers, pods or volumes ## SYNOPSIS **podman generate** *subcommand* ## DESCRIPTION -The generate command will create structured output (like YAML) based on a container or pod. +The generate command will create structured output (like YAML) based on a container, pod or volume. ## COMMANDS | Command | Man Page | Description | |---------|------------------------------------------------------------|-------------------------------------------------------------------------------------| -| kube | [podman-generate-kube(1)](podman-generate-kube.1.md) | Generate Kubernetes YAML based on a pod or container. | +| kube | [podman-generate-kube(1)](podman-generate-kube.1.md) | Generate Kubernetes YAML based on containers, pods or volumes. | | systemd | [podman-generate-systemd(1)](podman-generate-systemd.1.md) | Generate systemd unit file(s) for a container or pod. | diff --git a/docs/source/markdown/podman-play-kube.1.md b/docs/source/markdown/podman-play-kube.1.md index 6206a2ea9..1074c27f8 100644 --- a/docs/source/markdown/podman-play-kube.1.md +++ b/docs/source/markdown/podman-play-kube.1.md @@ -1,22 +1,40 @@ % podman-play-kube(1) ## NAME -podman-play-kube - Create pods and containers based on Kubernetes YAML +podman-play-kube - Create containers, pods or volumes based on Kubernetes YAML ## SYNOPSIS **podman play kube** [*options*] *file.yml|-* ## DESCRIPTION -**podman play kube** will read in a structured file of Kubernetes YAML. It will then recreate the pod and containers described in the YAML. The containers within the pod are then started and the ID of the new Pod is output. If the yaml file is specified as "-" then `podman play kube` with read the yaml file from stdin. +**podman play kube** will read in a structured file of Kubernetes YAML. It will then recreate the containers, pods or volumes described in the YAML. Containers within a pod are then started and the ID of the new Pod or the name of the new Volume is output. If the yaml file is specified as "-" then `podman play kube` will read the YAML file from stdin. Ideally the input file would be one created by Podman (see podman-generate-kube(1)). This would guarantee a smooth import and expected results. +Currently, the supported Kubernetes kinds are: +- Pod +- Deployment +- PersistentVolumeClaim + +`Kubernetes Pods or Deployments` + Only two volume types are supported by play kube, the *hostPath* and *persistentVolumeClaim* volume types. For the *hostPath* volume type, only the *default (empty)*, *DirectoryOrCreate*, *Directory*, *FileOrCreate*, *File*, and *Socket* subtypes are supported. The *CharDevice* and *BlockDevice* subtypes are not supported. Podman interprets the value of *hostPath* *path* as a file path when it contains at least one forward slash, otherwise Podman treats the value as the name of a named volume. When using a *persistentVolumeClaim*, the value for *claimName* is the name for the Podman named volume. Note: *hostPath* volume types created by play kube will be given an SELinux private label (Z) Note: If the `:latest` tag is used, Podman will attempt to pull the image from a registry. If the image was built locally with Podman or Buildah, it will have `localhost` as the domain, in that case, Podman will use the image from the local store even if it has the `:latest` tag. +`Kubernetes PersistentVolumeClaims` + +A Kubernetes PersistentVolumeClaim represents a Podman named volume. Only the PersistentVolumeClaim name is required by Podman to create a volume. Kubernetes annotations can be used to make use of the available options for Podman volumes. + +- volume.podman.io/driver +- volume.podman.io/device +- volume.podman.io/type +- volume.podman.io/uid +- volume.podman.io/gid +- volume.podman.io/mount-options + ## OPTIONS #### **\-\-authfile**=*path* @@ -44,6 +62,10 @@ The [username[:password]] to use to authenticate with the registry if required. If one or both values are not supplied, a command line prompt will appear and the value can be entered. The password is entered without echo. +#### **\-\-ip**=*IP address* + +Assign a static ip address to the pod. This option can be specified several times when play kube creates more than one pod. + #### **\-\-log-driver**=driver Set logging driver for all created containers. diff --git a/docs/source/markdown/podman-play.1.md b/docs/source/markdown/podman-play.1.md index 364baad60..39101ad31 100644 --- a/docs/source/markdown/podman-play.1.md +++ b/docs/source/markdown/podman-play.1.md @@ -1,20 +1,20 @@ % podman-play(1) ## NAME -podman\-play - Play pods and containers based on a structured input file +podman\-play - Play containers, pods or volumes based on a structured input file ## SYNOPSIS **podman play** *subcommand* ## DESCRIPTION -The play command will recreate pods and containers based on the input from a structured (like YAML) +The play command will recreate containers, pods or volumes based on the input from a structured (like YAML) file input. Containers will be automatically started. ## COMMANDS | Command | Man Page | Description | | ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | -| kube | [podman-play-kube(1)](podman-play-kube.1.md) | Create pods and containers based on Kubernetes YAML. | +| kube | [podman-play-kube(1)](podman-play-kube.1.md) | Create containers, pods or volumes based on Kubernetes YAML. | ## SEE ALSO podman, podman-pod(1), podman-container(1), podman-generate(1), podman-play(1), podman-play-kube(1) diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 4c096ecfe..40b271828 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -825,6 +825,12 @@ If container is running in **\-\-read-only** mode, then mount a read-write tmpfs If another container with the same name already exists, replace and remove it. The default is **false**. +#### **\-\-requires**=**container** + +Specify one or more requirements. +A requirement is a dependency container that will be started before this container. +Containers can be specified by name or ID, with multiple containers being separated by commas. + #### **\-\-restart**=*policy* Restart policy to follow when containers exit. @@ -1149,9 +1155,14 @@ read-write mode, respectively. By default, the volumes are mounted read-write. `Chowning Volume Mounts` -By default, Podman does not change the owner and group of source volume directories mounted into containers. If a container is created in a new user namespace, the UID and GID in the container may correspond to another UID and GID on the host. +By default, Podman does not change the owner and group of source volume +directories mounted into containers. If a container is created in a new user +namespace, the UID and GID in the container may correspond to another UID and +GID on the host. -The `:U` suffix tells Podman to use the correct host UID and GID based on the UID and GID within the container, to change recursively the owner and group of the source volume. +The `:U` suffix tells Podman to use the correct host UID and GID based on the +UID and GID within the container, to change recursively the owner and group of +the source volume. **Warning** use with caution since this will modify the host filesystem. @@ -1612,6 +1623,24 @@ $ podman run --tz=Asia/Shanghai alpine date $ podman run --tz=US/Eastern alpine date ``` +### Adding dependency containers + +The first container, container1, is not started initially, but must be running before container2 will start. +The `podman run` command will start the container automatically before starting container2. + +``` +$ podman create --name container1 -t -i fedora bash +$ podman run --name container2 --requires container1 -t -i fedora bash +``` + +Multiple containers can be required. + +``` +$ podman create --name container1 -t -i fedora bash +$ podman create --name container2 -t -i fedora bash +$ podman run --name container3 --requires container1,container2 -t -i fedora bash +``` + ### Rootless Containers Podman runs as a non root user on most systems. This feature requires that a new enough version of **shadow-utils** @@ -1657,7 +1686,7 @@ b NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -**podman**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-kill**(1), **podman-stop**(1), +**podman**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-start**(1), **podman-kill**(1), **podman-stop**(1), **podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**. ## HISTORY diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index 83ede074c..5ad4eff5b 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -8,10 +8,10 @@ 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*. +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 -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*) +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*) To access the API service inside a container: - mount the socket as a volume diff --git a/docs/source/markdown/podman-unshare.1.md b/docs/source/markdown/podman-unshare.1.md index 239213981..4451ad79c 100644 --- a/docs/source/markdown/podman-unshare.1.md +++ b/docs/source/markdown/podman-unshare.1.md @@ -24,6 +24,19 @@ The unshare session defines two environment variables: - **CONTAINERS_GRAPHROOT**: the path to the persistent container's data. - **CONTAINERS_RUNROOT**: the path to the volatile container's data. +## OPTIONS + +#### **\-\-help**, **-h** + +Print usage statement + +#### **\-\-rootless-cni** + +Join the rootless network namespace used for CNI networking. It can be used to +connect to a rootless container via IP address (CNI networking). This is otherwise +not possible from the host network namespace. +_Note: Using this option with more than one unshare session can have unexpected results._ + ## EXAMPLE ``` @@ -35,6 +48,30 @@ $ podman unshare cat /proc/self/uid_map /proc/self/gid_map 1 10000 65536 0 1000 1 1 10000 65536 + +$ podman unshare --rootless-cni ip addr +1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 + inet 127.0.0.1/8 scope host lo + valid_lft forever preferred_lft forever + inet6 ::1/128 scope host + valid_lft forever preferred_lft forever +2: tap0: <BROADCAST,UP,LOWER_UP> mtu 65520 qdisc fq_codel state UNKNOWN group default qlen 1000 + link/ether 36:0e:4a:c7:45:7e brd ff:ff:ff:ff:ff:ff + inet 10.0.2.100/24 brd 10.0.2.255 scope global tap0 + valid_lft forever preferred_lft forever + inet6 fe80::340e:4aff:fec7:457e/64 scope link + valid_lft forever preferred_lft forever +3: cni-podman2: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP group default qlen 1000 + link/ether 5e:3a:71:d2:b4:3a brd ff:ff:ff:ff:ff:ff + inet 10.89.1.1/24 brd 10.89.1.255 scope global cni-podman2 + valid_lft forever preferred_lft forever + inet6 fe80::5c3a:71ff:fed2:b43a/64 scope link + valid_lft forever preferred_lft forever +4: vethd4ba3a2f@if3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue master cni-podman2 state UP group default + link/ether 8a:c9:56:32:17:0c brd ff:ff:ff:ff:ff:ff link-netnsid 0 + inet6 fe80::88c9:56ff:fe32:170c/64 scope link + valid_lft forever preferred_lft forever ``` diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 5755b45ac..87bcd8802 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -223,7 +223,7 @@ the exit codes follow the `chroot` standard, see below: | [podman-events(1)](podman-events.1.md) | Monitor Podman events | | [podman-exec(1)](podman-exec.1.md) | Execute a command in a running container. | | [podman-export(1)](podman-export.1.md) | Export a container's filesystem contents as a tar archive. | -| [podman-generate(1)](podman-generate.1.md) | Generate structured data based for a containers and pods. | +| [podman-generate(1)](podman-generate.1.md) | Generate structured data based on containers, pods or volumes. | | [podman-healthcheck(1)](podman-healthcheck.1.md) | Manage healthchecks for containers | | [podman-history(1)](podman-history.1.md) | Show the history of an image. | | [podman-image(1)](podman-image.1.md) | Manage images. | @@ -242,7 +242,7 @@ the exit codes follow the `chroot` standard, see below: | [podman-mount(1)](podman-mount.1.md) | Mount a working container's root filesystem. | | [podman-network(1)](podman-network.1.md) | Manage Podman CNI networks. | | [podman-pause(1)](podman-pause.1.md) | Pause one or more containers. | -| [podman-play(1)](podman-play.1.md) | Play pods and containers based on a structured input file. | +| [podman-play(1)](podman-play.1.md) | Play containers, pods or volumes based on a structured input file. | | [podman-pod(1)](podman-pod.1.md) | Management tool for groups of containers, called pods. | | [podman-port(1)](podman-port.1.md) | List port mappings for a container. | | [podman-ps(1)](podman-ps.1.md) | Prints out information about containers. | |