diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Readme.md | 2 | ||||
| -rw-r--r-- | docs/source/index.rst | 2 | ||||
| -rw-r--r-- | docs/source/markdown/links/podman-image-diff.1 | 1 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-exec.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-generate-systemd.1.md | 12 | ||||
| -rw-r--r-- | docs/source/markdown/podman-history.1.md | 5 | ||||
| -rw-r--r-- | docs/source/markdown/podman-image-diff.1.md | 46 | ||||
| -rw-r--r-- | docs/source/markdown/podman-image.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-manifest-push.1.md | 18 | ||||
| -rw-r--r-- | docs/source/markdown/podman-network-inspect.1.md | 4 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pod-inspect.1.md | 51 | ||||
| -rw-r--r-- | docs/source/markdown/podman-pull.1.md | 5 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-system-service.1.md | 6 | ||||
| -rw-r--r-- | docs/source/markdown/podman-varlink.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-wait.1.md | 3 | ||||
| -rw-r--r-- | docs/source/markdown/podman.1.md | 6 | ||||
| -rw-r--r-- | docs/tutorials/rootless_tutorial.md | 42 |
19 files changed, 176 insertions, 37 deletions
diff --git a/docs/Readme.md b/docs/Readme.md index 4d10cfa56..987a5b8e4 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -1,7 +1,7 @@ # Podman Documentation The online man pages and other documents regarding Podman can be found at -[Read The Docs](https://podman.readthedocs.io/en/latest/index.html). The man pages +[Read The Docs](https://podman.readthedocs.io). The man pages can be found under the [Commands](https://podman.readthedocs.io/en/latest/Commands.html) link on that page. diff --git a/docs/source/index.rst b/docs/source/index.rst index 9cc8e7af8..1c46f1c8a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,7 +2,7 @@ What is Podman? ================================== -Podman_ is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI_) Containers_ and `Container Images`_. Podman provides a command line interface (CLI) familiar to anyone who has used the Docker `Container Engine`_. Most users can simply alias Docker to Podman (`alias docker=podman`) without any problems. Similiar other common `Container Engines`_ (Docker, CRI-O, containerd), Podman relies on an OCI compliant `Container Runtime`_ (runc, crun, runv, etc) to interface with the operating system and create the running containers.This makes the running containers created by Podman nearly indistinguishable from those created by any other common container engine. +Podman_ is a daemonless, open source, Linux native tool designed to make it easy to find, run, build, share and deploy applications using Open Containers Initiative (OCI_) Containers_ and `Container Images`_. Podman provides a command line interface (CLI) familiar to anyone who has used the Docker `Container Engine`_. Most users can simply alias Docker to Podman (`alias docker=podman`) without any problems. Similar to other common `Container Engines`_ (Docker, CRI-O, containerd), Podman relies on an OCI compliant `Container Runtime`_ (runc, crun, runv, etc) to interface with the operating system and create the running containers.This makes the running containers created by Podman nearly indistinguishable from those created by any other common container engine. Containers under the control of Podman can either be run by root or by a non-privileged user. Podman manages the entire container ecosystem which includes pods, containers, container images, and container volumes using the libpod_ library. Podman specializes in all of the commands and functions that help you to maintain and modify OCI container images, such as pulling and tagging. It allows you to create, run, and maintain those containers and container images in a production environment. diff --git a/docs/source/markdown/links/podman-image-diff.1 b/docs/source/markdown/links/podman-image-diff.1 deleted file mode 100644 index ac4881f98..000000000 --- a/docs/source/markdown/links/podman-image-diff.1 +++ /dev/null @@ -1 +0,0 @@ -.so man1/podman-diff.1 diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 475634fde..3a6077832 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -502,7 +502,7 @@ Current supported mount TYPES are `bind`, `volume`, and `tmpfs`. · dst, destination, target: mount destination spec. - · ro, read-only: true or false (default). + · ro, readonly: true or false (default). Options specific to bind: diff --git a/docs/source/markdown/podman-exec.1.md b/docs/source/markdown/podman-exec.1.md index b24a1f8aa..f44a3d3d9 100644 --- a/docs/source/markdown/podman-exec.1.md +++ b/docs/source/markdown/podman-exec.1.md @@ -13,7 +13,7 @@ podman\-exec - Execute a command in a running container ## OPTIONS -**--detach** +**--detach**, **-d** Start the exec session, but do not attach to it. The command will run in the background and the exec session will be automatically removed when it completes. The **podman exec** command will print the ID of the exec session and exit immediately after it starts. diff --git a/docs/source/markdown/podman-generate-systemd.1.md b/docs/source/markdown/podman-generate-systemd.1.md index fa04f81f9..72031b19b 100644 --- a/docs/source/markdown/podman-generate-systemd.1.md +++ b/docs/source/markdown/podman-generate-systemd.1.md @@ -40,6 +40,18 @@ Override the default stop timeout for the container with the given value. Set the systemd restart policy. The restart-policy must be one of: "no", "on-success", "on-failure", "on-abnormal", "on-watchdog", "on-abort", or "always". The default policy is *on-failure*. +**--container-prefix**=*prefix* + +Set the systemd unit name prefix for containers. The default is *container*. + +**--pod-prefix**=*prefix* + +Set the systemd unit name prefix for pods. The default is *pod*. + +**--separator**=*separator* + +Set the systemd unit name seperator between the name/id of a container/pod and the prefix. The default is *-*. + ## Examples ### Generate and print a systemd unit file for a container diff --git a/docs/source/markdown/podman-history.1.md b/docs/source/markdown/podman-history.1.md index 1a8f8906c..26b213af9 100644 --- a/docs/source/markdown/podman-history.1.md +++ b/docs/source/markdown/podman-history.1.md @@ -37,10 +37,13 @@ Display sizes and dates in human readable format (default *true*). Do not truncate the output (default *false*). +**--notruncate** + +Do not truncate the output + **--quiet**, **-q**=*true|false* Print the numeric IDs only (default *false*). - **--format**=*format* Alter the output for a format like 'json' or a Go template. diff --git a/docs/source/markdown/podman-image-diff.1.md b/docs/source/markdown/podman-image-diff.1.md new file mode 100644 index 000000000..1e7397cd8 --- /dev/null +++ b/docs/source/markdown/podman-image-diff.1.md @@ -0,0 +1,46 @@ +% podman-image-diff(1) + +## NAME +podman-image-diff - Inspect changes on an image's filesystem + +## SYNOPSIS +**podman image diff** [*options*] *name* + +## DESCRIPTION +Displays changes on a container or image's filesystem. The container or image will be compared to its parent layer + +## OPTIONS + +**--format** + +Alter the output into a different format. The only valid format for diff is `json`. + +## EXAMPLE + +``` +# podman diff redis:old redis:alpine +C /usr +C /usr/local +C /usr/local/bin +A /usr/local/bin/docker-entrypoint.sh +``` + +``` +# podman diff --format json redis:old redis:alpine +{ + "changed": [ + "/usr", + "/usr/local", + "/usr/local/bin" + ], + "added": [ + "/usr/local/bin/docker-entrypoint.sh" + ] +} +``` + +## SEE ALSO +podman(1) + +## HISTORY +August 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/markdown/podman-image.1.md b/docs/source/markdown/podman-image.1.md index 1552098ac..dfff57b31 100644 --- a/docs/source/markdown/podman-image.1.md +++ b/docs/source/markdown/podman-image.1.md @@ -14,6 +14,7 @@ The image command allows you to manage images | Command | Man Page | Description | | -------- | ----------------------------------------------- | --------------------------------------------------------------------------- | | build | [podman-build(1)](podman-build.1.md) | Build a container using a Dockerfile. | +| diff | [podman-image-diff(1)](podman-image-diff.1.md) | Inspect changes on an image's filesystem. | | exists | [podman-image-exists(1)](podman-image-exists.1.md) | Check if an image exists in local storage. | | history | [podman-history(1)](podman-history.1.md) | Show the history of an image. | | import | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | @@ -25,6 +26,7 @@ The image command allows you to manage images | push | [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. | | rm | [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. | | save | [podman-save(1)](podman-save.1.md) | Save an image to docker-archive or oci. | +| search | [podman-search(1)](podman-search.1.md) | Search a registry for an image. | | sign | [podman-image-sign(1)](podman-image-sign.1.md) | Create a signature for an image. | | tag | [podman-tag(1)](podman-tag.1.md) | Add an additional name to a local image. | | untag | [podman-untag(1)](podman-untag.1.md) | Removes one or more names from a locally-stored image. | diff --git a/docs/source/markdown/podman-manifest-push.1.md b/docs/source/markdown/podman-manifest-push.1.md index 38d0c5904..ab3287a7c 100644 --- a/docs/source/markdown/podman-manifest-push.1.md +++ b/docs/source/markdown/podman-manifest-push.1.md @@ -19,7 +19,7 @@ The list image's ID and the digest of the image's manifest. Push the images mentioned in the manifest list or image index, in addition to the list or index itself. -**--authfile** *path* +**--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json, which is set using `podman login`. If the authorization state is not found there, $HOME/.docker/config.json is checked, which is set using `docker login`. (Not available for remote commands) @@ -27,22 +27,22 @@ If the authorization state is not found there, $HOME/.docker/config.json is chec Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` -**--cert-dir** *path* +**--cert-dir**=*path* Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) -**--creds** *creds* +**--creds**=*creds* 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. -**--digestfile** *Digestfile* +**--digestfile**=*Digestfile* After copying the image, write the digest of the resulting image to the file. -**--format, -f** +**--format**, **-f**=*format* Manifest list type (oci or v2s2) to use when pushing the list (default is oci). @@ -50,15 +50,19 @@ Manifest list type (oci or v2s2) to use when pushing the list (default is oci). Delete the manifest list or image index from local storage if pushing succeeds. +**--quiet**, **-q** + +When writing the manifest, suppress progress output + **--remove-signatures** Don't copy signatures when pushing images. -**--sign-by** *fingerprint* +**--sign-by**=*fingerprint* Sign the pushed images using the GPG key that matches the specified fingerprint. -**--tls-verify** *bool-value* +**--tls-verify** Require HTTPS and verify certificates when talking to container registries (defaults to true) (Not available for remote commands) diff --git a/docs/source/markdown/podman-network-inspect.1.md b/docs/source/markdown/podman-network-inspect.1.md index ca6875d18..86fa2552e 100644 --- a/docs/source/markdown/podman-network-inspect.1.md +++ b/docs/source/markdown/podman-network-inspect.1.md @@ -10,10 +10,6 @@ podman\-network\-inspect - Displays the raw CNI network configuration for one or Display the raw (JSON format) network configuration. This command is not available for rootless users. ## OPTIONS -**--quiet**, **-q** - -The `quiet` option will restrict the output to only the network names. - **--format**, **-f** Pretty-print networks to JSON or using a Go template. diff --git a/docs/source/markdown/podman-pod-inspect.1.md b/docs/source/markdown/podman-pod-inspect.1.md index 831d28259..bc04b2b32 100644 --- a/docs/source/markdown/podman-pod-inspect.1.md +++ b/docs/source/markdown/podman-pod-inspect.1.md @@ -18,21 +18,50 @@ to run pods such as CRI-O, the last started pod could be from either of those me The latest option is not supported on the remote client. +**-f**, **--format**=*format* + +Change the default output format. This can be of a supported type like 'json' +or a Go template. +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| ----------------- | ----------------------------------------------------------------------------- | +| .ID | Pod ID | +| .Name | Pod name | +| .State | Pod state | +| .Hostname | Pod hostname | +| .Labels | Pod labels | +| .Created | Time when the pod was created | +| .CreateCgroup | Whether cgroup was created | +| .CgroupParent | Pod cgroup parent | +| .CgroupPath | Pod cgroup path | +| .CreateInfra | Whether infrastructure created | +| .InfraContainerID | Pod infrastructure ID | +| .SharedNamespaces | Pod shared namespaces | +| .NumContainers | Number of containers in the pod | +| .Containers | Pod containers | + ## EXAMPLE ``` # podman pod inspect foobar { - "Config": { - "id": "3513ca70583dd7ef2bac83331350f6b6c47d7b4e526c908e49d89ebf720e4693", - "name": "foobar", - "labels": {}, - "cgroupParent": "/libpod_parent", - "UsePodCgroup": true, - "created": "2018-08-08T11:15:18.823115347-05:00" - }, - "State": { - "CgroupPath": "" - }, + + "Id": "3513ca70583dd7ef2bac83331350f6b6c47d7b4e526c908e49d89ebf720e4693", + "Name": "foobar", + "Labels": {}, + "CgroupParent": "/libpod_parent", + "CreateCgroup": true, + "Created": "2018-08-08T11:15:18.823115347-05:00" + "State": "created", + "Hostname": "", + "SharedNamespaces": [ + "uts", + "ipc", + "net" + ] + "CreateInfra": false, + "InfraContainerID": "1020dd70583dd7ff2bac83331350f6b6e007de0d026c908e49d89ebf891d4699" + "CgroupPath": "" "Containers": [ { "id": "d53f8bf1e9730281264aac6e6586e327429f62c704abea4b6afb5d8a2b2c9f2c", diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index aa558526a..5d941219a 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -73,7 +73,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. -**--override-arch**=ARCH +**--override-os**=*OS* +Use OS instead of the running OS for choosing images + +**--override-arch**=*ARCH* Override the machine's default architecture of the image to be pulled. For example, `arm`. diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 4c236b520..1e05b8999 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -511,7 +511,7 @@ Current supported mount TYPEs are **bind**, **volume**, and **tmpfs**. · dst, destination, target: mount destination spec. - · ro, read-only: true or false (default). + · ro, readonly: true or false (default). Options specific to bind: diff --git a/docs/source/markdown/podman-system-service.1.md b/docs/source/markdown/podman-system-service.1.md index a2fefe4dd..48e595641 100644 --- a/docs/source/markdown/podman-system-service.1.md +++ b/docs/source/markdown/podman-system-service.1.md @@ -15,15 +15,11 @@ example *unix:/run/user/1000/podman/podman.sock*) ## OPTIONS -**--timeout**, **-t** +**--time**, **-t** The time until the session expires in _milliseconds_. The default is 1 second. A value of `0` means no timeout and the session will not expire. -**--varlink** - -Use the varlink protocol instead of the REST-based protocol. This option will be deprecated in the future. - **--help**, **-h** Print usage statement. diff --git a/docs/source/markdown/podman-varlink.1.md b/docs/source/markdown/podman-varlink.1.md index 0d2ab1668..0b04d5ba3 100644 --- a/docs/source/markdown/podman-varlink.1.md +++ b/docs/source/markdown/podman-varlink.1.md @@ -19,7 +19,7 @@ The varlink service should generally be done with systemd. See _Configuration_ Print usage statement -**--timeout**, **-t** +**--time**, **-t** The time until the varlink session expires in _milliseconds_. The default is 1 second. A value of `0` means no timeout and the session will not expire. diff --git a/docs/source/markdown/podman-wait.1.md b/docs/source/markdown/podman-wait.1.md index ce1c70a5f..886bbc55b 100644 --- a/docs/source/markdown/podman-wait.1.md +++ b/docs/source/markdown/podman-wait.1.md @@ -15,6 +15,9 @@ After the container stops, the container's return code is printed. ## OPTIONS +**--condition**=*state* +Condition to wait on (default "stopped") + **--help**, **-h** Print usage statement diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 6bac0cc9d..02f23e6cc 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -58,6 +58,9 @@ Podman and libpod currently support an additional `precreate` state which is cal **WARNING**: the `precreate` hook lets you do powerful things, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running your container with `precreate` hooks disabled to see if the problem is due to one of your hooks. +**--identity**=*path* +Path to SSH identity file + **--log-level**=*level* Log messages above specified level: debug, info, warn, error (default), fatal or panic (default: "error") @@ -70,6 +73,9 @@ When namespace is set, created containers and pods will join the given namespace **--network-cmd-path**=*path* Path to the command binary to use for setting up a network. It is currently only used for setting up a slirp4netns network. If "" is used then the binary is looked up using the $PATH environment variable. +**--remote**, **-r**=*url* +URL to access Podman service (default "unix:/run/user/3267/podman/podman.sock") + **--root**=*value* Storage root dir in which data, including images, is stored (default: "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/containers/storage" for other users). diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 8e048c746..440e12062 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -58,7 +58,7 @@ The number of user namespaces that are allowed on the system is specified in the ### /etc/subuid and /etc/subgid configuration -Rootless podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid files. The `shadows-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. These files will need someone with root privileges on the system to add or update the entries within them. The following is a summarization from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com) +Rootless Podman requires the user running it to have a range of UIDs listed in /etc/subuid and /etc/subgid files. The `shadows-utils` or `newuid` package provides these files on different distributions and they must be installed on the system. These files will need someone with root privileges on the system to add or update the entries within them. The following is a summarization from the [How does rootless Podman work?](https://opensource.com/article/19/2/how-does-rootless-podman-work) article by Dan Walsh on [opensource.com](https://opensource.com) Update the /etc/subuid and /etc/subgid with fields for each user that will be allowed to create containers that look like the following. Note that the values for each user must be unique and without any overlap. If there is an overlap, there is a potential for a user to use another’s namespace and they could corrupt it. @@ -110,6 +110,46 @@ The Podman configuration files for root reside in `/usr/share/containers` with o The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`. +### Using volumes + +Rootless Podman is not, and will never be, root; it's not a setuid binary, and gains no privileges when it runs. Instead, Podman makes use of a user namespace to shift the UIDs and GIDs of a block of users it is given access to on the host (via the newuidmap and newgidmap executables) and your own user within the containers that Podman creates. + +If your container runs with the root user, then `root` in the container is actually your user on the host. UID/GID 1 is the first UID/GID specified in your user's mapping in `/etc/subuid` and `/etc/subgid`, etc. If you mount a directory from the host into a container as a rootless user, and create a file in that directory as root in the container, you'll see it's actually owned by your user on the host. + +So, for example, + +``` +> whoami +john + +# a folder which is empty +host> ls /home/john/folder +host> podman run -v /home/john/folder:/container/volume mycontainer /bin/bash + +# Now I'm in the container +root@container> whoami +root +root@container> touch /container/volume/test +root@container> ls -l /container/volume +total 0 +-rw-r--r-- 1 root root 0 May 20 21:47 test +root@container> exit + +# I check again +host> ls -l /home/john/folder +total 0 +-rw-r--r-- 1 john john 0 May 20 21:47 test +``` + +We do recognize that this doesn't really match how many people intend to use rootless Podman - they want their UID inside and outside the container to match. Thus, we provide the `--userns=keep-id` flag, which ensures that your user is mapped to its own UID and GID inside the container. + +It is also helpful to distinguish between running Podman as a rootless user, and a container which is built to run rootless. If the container you're trying you run has a `USER` which is not root, then when mounting volumes you **must** use `--userns=keep-id`. This is because the container user would not be able to become `root` and access the mounted volumes. + +Other considerations in regards to volumes: + +- You should always give the full path to the volume you'd like to mount +- The mount point must exist in the container + ## More information If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/libpod/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment. |