diff options
Diffstat (limited to 'docs')
40 files changed, 578 insertions, 274 deletions
diff --git a/docs/Readme.md b/docs/Readme.md index 9d3b9d06f..12b78d48f 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -49,7 +49,7 @@ the following: If reloading the page, or clearing your local cache does not fix the problem, it is likely caused by broken metadata needed to protect clients from cross-site-scripting -style attacks. Please [notify a maintainer](https://github.com/containers/libpod#communications) +style attacks. Please [notify a maintainer](https://github.com/containers/podman#communications) so they may investigate how/why the swagger.yaml file's CORS-metadata is incorrect. See [the Cirrus-CI tasks documentation](../contrib/cirrus/README.md#docs-task) for details regarding this situation. diff --git a/docs/source/Tutorials.rst b/docs/source/Tutorials.rst index 0c013c244..1b17bc4c7 100644 --- a/docs/source/Tutorials.rst +++ b/docs/source/Tutorials.rst @@ -4,9 +4,9 @@ Tutorials ========= Here are a number of useful tutorials to get you up and running with Podman. If you are familiar with the Docker `Container Engine`_ the command in Podman_ should be quite familiar. If are brand new to containers, take a look at our `Introduction`. -* `Basic Setup and Use of Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/podman_tutorial.md>`_: Learn how to setup Podman and perform some basic commands with the utility. -* `Basic Setup and Use of Podman in a Rootless environment <https://github.com/containers/libpod/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated. -* `Podman Mac Client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md>`_: Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented. -* `How to sign and distribute container images using Podman <https://github.com/containers/libpod/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman. -* `Podman remote-client tutorial <https://github.com/containers/libpod/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client. -* `How to use libpod for custom/derivative projects <https://github.com/containers/libpod/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project. +* `Basic Setup and Use of Podman <https://github.com/containers/podman/blob/master/docs/tutorials/podman_tutorial.md>`_: Learn how to setup Podman and perform some basic commands with the utility. +* `Basic Setup and Use of Podman in a Rootless environment <https://github.com/containers/podman/blob/master/docs/tutorials/rootless_tutorial.md>`_: The steps required to setup rootless Podman are enumerated. +* `Podman Mac Client tutorial <https://github.com/containers/podman/blob/master/docs/tutorials/mac_client.md>`_: Special setup for running the Podman remote client on a Mac and connecting to Podman running on a Linux VM are documented. +* `How to sign and distribute container images using Podman <https://github.com/containers/podman/blob/master/docs/tutorials/image_signing.md>`_: Learn how to setup and use image signing with Podman. +* `Podman remote-client tutorial <https://github.com/containers/podman/blob/master/docs/tutorials/remote_client.md>`_: A brief how-to on using the Podman remote-client. +* `How to use libpod for custom/derivative projects <https://github.com/containers/podman/blob/master/docs/tutorials/podman-derivative-api.md>`_: How the libpod API can be used within your own project. diff --git a/docs/source/includes.rst b/docs/source/includes.rst index 4794f454a..8d3b6e2db 100644 --- a/docs/source/includes.rst +++ b/docs/source/includes.rst @@ -10,10 +10,10 @@ .. _Container Images: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.dqlu6589ootw .. _Container Registry: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq .. _Container Registries: https://developers.redhat.com/blog/2018/02/22/container-terminology-practical-introduction/#h.4cxnedx7tmvq -.. _libpod: https://github.com/containers/libpod +.. _libpod: https://github.com/containers/podman .. _podman search: http://docs.podman.io/en/latest/markdown/podman-search.1.html .. _podman pull: http://docs.podman.io/en/latest/markdown/podman-pull.1.html .. _podman run: http://docs.podman.io/en/latest/markdown/podman-run.1.html .. _podman build: http://docs.podman.io/en/latest/markdown/podman-build.1.html .. _podman push: http://docs.podman.io/en/latest/markdown/podman-push.1.html -.. image:: https://github.com/containers/libpod/blob/master/logo/podman-logo.png?raw=true +.. image:: https://github.com/containers/podman/blob/master/logo/podman-logo.png?raw=true diff --git a/docs/source/index.rst b/docs/source/index.rst index 18a5554ca..715ca2744 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -2,13 +2,13 @@ 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. 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. +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. The Podman service runs only on Linux platforms, however a REST API and clients are currently under development which will allow Mac and Windows platforms to call the service. There is currently a RESTful based remote client which runs on Mac or Windows platforms that allows the remote client to talk to the Podman server on a Linux platform. In addition to those clients, there is also a Mac client. -If you are completely new to containers, we recommend that you check out the :doc:`Introduction`. For power users or those comming from Docker, check out our :doc:`Tutorials`. For advanced users and contributors, you can get very detailed information about the Podman CLI by looking our :doc:`Commands` page. Finally, for Developers looking at how to interact with the Podman API, please see our API documentation :doc:`Reference`. +If you are completely new to containers, we recommend that you check out the :doc:`Introduction`. For power users or those coming from Docker, check out our :doc:`Tutorials`. For advanced users and contributors, you can get very detailed information about the Podman CLI by looking at our :doc:`Commands` page. Finally, for Developers looking at how to interact with the Podman API, please see our API documentation :doc:`Reference`. .. toctree:: :maxdepth: 2 diff --git a/docs/source/markdown/libpod.conf.5.md b/docs/source/markdown/libpod.conf.5.md deleted file mode 100644 index ca45bccf6..000000000 --- a/docs/source/markdown/libpod.conf.5.md +++ /dev/null @@ -1,114 +0,0 @@ -% libpod.conf(5) - -## NAME -libpod.conf - libpod configuration file - -## DESCRIPTION -The libpod.conf file is the default configuration file for all tools using -libpod to manage containers. - -## OPTIONS - -**image_default_transport**="" - Default transport method for pulling and pushing images - -**runtime**="" - Default OCI runtime to use if nothing is specified in **runtimes** - -**runtimes** - For each OCI runtime, specify a list of paths to look for. The first one found is used. If the paths are empty or no valid path was found, then the `$PATH` environment variable will be used as the fallback. - -**conmon_path**="" - Paths to search for the conmon container manager binary. If the paths are empty or no valid path was found, then the `$PATH` environment variable will be used as the fallback. - -**conmon_env_vars**="" - Environment variables to pass into Conmon - -**cgroup_manager**="" - Specify the CGroup Manager to use; valid values are "systemd" and "cgroupfs" - -**lock_type**="" - Specify the locking mechanism to use; valid values are "shm" and "file". Change the default only if you are sure of what you are doing, in general "file" is useful only on platforms where cgo is not available for using the faster "shm" lock type. You may need to run "podman system renumber" after you change the lock type. - -**init_path**="" - Path to the container-init binary, which forwards signals and reaps processes within containers. Note that the container-init binary will only be used when the `--init` for podman-create and podman-run is set. - -**hooks_dir**=["*path*", ...] - - Each `*.json` file in the path configures a hook for Podman containers. For more details on the syntax of the JSON files and the semantics of hook injection, see `oci-hooks(5)`. Podman and libpod currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated. - - Paths listed later in the array have higher precedence (`oci-hooks(5)` discusses directory precedence). - - For the annotation conditions, libpod uses any annotations set in the generated OCI configuration. - - For the bind-mount conditions, only mounts explicitly requested by the caller via `--volume` are considered. Bind mounts that libpod inserts by default (e.g. `/dev/shm`) are not considered. - - Podman and libpod currently support an additional `precreate` state which is called before the runtime's `create` operation. Unlike the other stages, which receive the container state on their standard input, `precreate` hooks receive the proposed runtime configuration on their standard input. They may alter that configuration as they see fit, and write the altered form to their standard output. - - **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. - -**static_dir**="" - Directory for persistent libpod files (database, etc) - By default this will be configured relative to where containers/storage - stores containers - -**tmp_dir**="" - Directory for temporary files - Must be a tmpfs (wiped after reboot) - -**max_log_size**="" - Maximum size of log files (in bytes) - -**no_pivot_root**="" - Whether to use chroot instead of pivot_root in the runtime - -**cni_config_dir**="" - Directory containing CNI plugin configuration files - -**cni_plugin_dir**="" - Directories where CNI plugin binaries may be located - -**infra_image** = "" - Infra (pause) container image name for pod infra containers. When running a pod, we - start a `pause` process in a container to hold open the namespaces associated with the - pod. This container and process, basically sleep/pause for the lifetime of the pod. - -**infra_command**="" - Command to run the infra container - -**namespace**="" - Default libpod namespace. If libpod is joined to a namespace, it will see only containers and pods - that were created in the same namespace, and will create new containers and pods in that namespace. - The default namespace is "", which corresponds to no namespace. When no namespace is set, all - containers and pods are visible. - -**label**="true|false" - Indicates whether the containers should use label separation by default. - Can be overridden via `--security-opt label=...` on the CLI. - -**num_locks**="" - Number of locks available for containers and pods. Each created container or pod consumes one lock. - The default number available is 2048. - If this is changed, a lock renumbering must be performed, using the `podman system renumber` command. - -**volume_path**="" - Directory where named volumes will be created in using the default volume driver. - By default this will be configured relative to where containers/storage stores containers. - -**network_cmd_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. - -**events_logger**="" - Default method to use when logging events. Valid values are "file", "journald", and "none". - -**detach_keys**="" - Keys sequence used for detaching a container - -## FILES - `/usr/share/containers/libpod.conf`, default libpod configuration path - - `/etc/containers/libpod.conf`, override libpod configuration path - -## HISTORY -Apr 2018, Originally compiled by Nathan Williams <nath.e.will@gmail.com> diff --git a/docs/source/markdown/links/podman-container-umount.1 b/docs/source/markdown/links/podman-container-umount.1 index 789dabbb0..aa4add453 100644 --- a/docs/source/markdown/links/podman-container-umount.1 +++ b/docs/source/markdown/links/podman-container-umount.1 @@ -1 +1 @@ -.so man1/podman-umount.1 +.so man1/podman-unmount.1 diff --git a/docs/source/markdown/links/podman-container-unmount.1 b/docs/source/markdown/links/podman-container-unmount.1 index 789dabbb0..aa4add453 100644 --- a/docs/source/markdown/links/podman-container-unmount.1 +++ b/docs/source/markdown/links/podman-container-unmount.1 @@ -1 +1 @@ -.so man1/podman-umount.1 +.so man1/podman-unmount.1 diff --git a/docs/source/markdown/links/podman-image-umount.1 b/docs/source/markdown/links/podman-image-umount.1 new file mode 100644 index 000000000..129212aab --- /dev/null +++ b/docs/source/markdown/links/podman-image-umount.1 @@ -0,0 +1 @@ +.so man1/podman-image-unmount.1 diff --git a/docs/source/markdown/links/podman-umount.1 b/docs/source/markdown/links/podman-umount.1 new file mode 100644 index 000000000..aa4add453 --- /dev/null +++ b/docs/source/markdown/links/podman-umount.1 @@ -0,0 +1 @@ +.so man1/podman-unmount.1 diff --git a/docs/source/markdown/links/podman-unmount.1 b/docs/source/markdown/links/podman-unmount.1 deleted file mode 100644 index 789dabbb0..000000000 --- a/docs/source/markdown/links/podman-unmount.1 +++ /dev/null @@ -1 +0,0 @@ -.so man1/podman-umount.1 diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md index 1ac2e49a9..cb3ffa92e 100644 --- a/docs/source/markdown/podman-attach.1.md +++ b/docs/source/markdown/podman-attach.1.md @@ -15,7 +15,7 @@ or name, either to view its ongoing output or to control it interactively. You can detach from the container (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** option, or specifying -it in the **libpod.conf** file: see **libpod.conf(5)** for more information. +it in the **containers.conf** file: see **containers.conf(5)** for more information. ## OPTIONS **--detach-keys**=*sequence* @@ -55,4 +55,4 @@ $ podman attach 1234 $ podman attach --no-stdin foobar ``` ## SEE ALSO -podman(1), podman-exec(1), podman-run(1) +podman(1), podman-exec(1), podman-run(1), containers.conf(5) diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 7408a6ad6..a07b55924 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -580,7 +580,7 @@ process. 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. The `OPTIONS` are a comma delimited list and can be: + container. The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup> * [rw|ro] * [z|Z|O] @@ -643,7 +643,7 @@ be specified only for bind mounted volumes and not for internal volumes or named volumes. For mount propagation to work on the source mount point (mount point where source dir is mounted on) has to have the right propagation properties. For shared volumes, the source mount point has to be shared. And for slave volumes, -the source mount has to be either shared or slave. +the source mount has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> Use `df <source-dir>` to determine the source mount and then use `findmnt -o TARGET,PROPAGATION <source-mount-dir>` to determine propagation @@ -651,7 +651,7 @@ properties of source mount, if `findmnt` utility is not available, the source mo can be determined by looking at the mount entry in `/proc/self/mountinfo`. Look at `optional fields` and see if any propagation properties are specified. `shared:X` means the mount is `shared`, `master:X` means the mount is `slave` and if -nothing is there that means the mount is `private`. +nothing is there that means the mount is `private`. <sup>[[1]](#Footnote1)</sup> To change propagation properties of a mount point use the `mount` command. For example, to bind mount the source directory `/foo` do @@ -755,3 +755,6 @@ podman(1), buildah(1), containers-registries.conf(5), crun(8), runc(8), useradd( May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com> December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com> + +## FOOTNOTES +<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately. diff --git a/docs/source/markdown/podman-container.1.md b/docs/source/markdown/podman-container.1.md index 4ea7c7acc..0a6ceea33 100644 --- a/docs/source/markdown/podman-container.1.md +++ b/docs/source/markdown/podman-container.1.md @@ -41,7 +41,7 @@ The container command allows you to manage containers | stats | [podman-stats(1)](podman-stats.1.md) | Display a live stream of one or more container's resource usage statistics. | | stop | [podman-stop(1)](podman-stop.1.md) | Stop one or more running containers. | | top | [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | -| umount | [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem.(Alias unmount) | +| unmount | [podman-unmount(1)](podman-unmount.1.md) | Unmount a working container's root filesystem.(Alias unmount) | | unpause | [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. | | wait | [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. | diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index e0703fd22..b4456225e 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -190,7 +190,7 @@ detached container with **podman attach**. When attached in the tty mode, you can detach from the container (and leave it running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. Configure the keys sequence using the **--detach-keys** option, or specifying -it in the **libpod.conf** file: see **libpod.conf(5)** for more information. +it in the **containers.conf** file: see **containers.conf(5)** for more information. **--detach-keys**=*sequence* @@ -234,6 +234,12 @@ Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sd Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000) +**--disable-content-trust** + +This is a Docker specific option to disable image verification to a Docker +registry and is not supported by Podman. This flag is a NOOP and provided +solely for scripting compatibility. + **--dns**=*dns* Set custom DNS servers. Invalid if using **--dns** and **--network** that is set to 'none' or 'container:<name|id>'. @@ -488,7 +494,7 @@ Tune a container's memory swappiness behavior. Accepts an integer between 0 and Attach a filesystem mount to the container -Current supported mount TYPES are `bind`, `volume`, and `tmpfs`. +Current supported mount TYPES are `bind`, `volume`, and `tmpfs`. <sup>[[1]](#Footnote1)</sup> e.g. @@ -553,7 +559,10 @@ Valid values are: - `<network-name>|<network-id>`: connect to a user-defined network, multiple networks should be comma separated - `ns:<path>`: path to a network namespace to join - `private`: create a new namespace for the container (default) -- `slirp4netns`: use slirp4netns to create a user network stack. This is the default for rootless containers +- `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: + **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. + **port_handler=slirp4netns**: Use the slirp4netns port forwarding. + **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default to false. **--network-alias**=*alias* @@ -738,7 +747,7 @@ Security Options - `seccomp=unconfined` : Turn off seccomp confinement for the container - `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter -Note: Labeling can be disabled for all containers by setting label=false in the **libpod.conf** (`/etc/containers/libpod.conf`) file. +Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file. **--shm-size**=*size* @@ -808,7 +817,7 @@ Create a tmpfs mount Mount a temporary filesystem (`tmpfs`) mount into a container, for example: -$ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image +$ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image This command mounts a `tmpfs` at `/tmp` within the container. The supported mount options are the same as the Linux default `mount` flags. If you do not specify @@ -830,6 +839,10 @@ standard input. Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. +**--umask**=*umask* + +Set the umask inside the container. Defaults to `0022`. + **--uidmap**=*container_uid:host_uid:amount* UID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subuidname` flags. @@ -884,15 +897,20 @@ Set the UTS mode for the container 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. The `OPTIONS` are a comma delimited list and can be: +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 delimited list and can be: <sup>[[1]](#Footnote1)</sup> -* [rw|ro] -* [z|Z] -* [`[r]shared`|`[r]slave`|`[r]private`] -* [`[r]bind`] -* [`noexec`|`exec`] -* [`nodev`|`dev`] -* [`nosuid`|`suid`] +The _options_ is a comma delimited list and can be: + +* **rw**|**ro** +* **z**|**Z** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private** +* [**r**]**bind** +* [**no**]**exec** +* [**no**]**dev** +* [**no**]**suid** +* [**O**] The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume will be mounted into the container at this directory. @@ -905,18 +923,22 @@ the container is removed via the `--rm` flag or `podman rm --volumes`. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths are resolved relative to the directory Podman is run in. Any source that does -not begin with a `.` or `/` it will be treated as the name of a named volume. +not begin with a `.` or `/` will be treated as the name of a named volume. If a volume with that name does not exist, it will be created. Volumes created -with names are not anonymous and are not removed by `--rm` and -`podman rm --volumes`. +with names are not anonymous. They are not removed by the `--rm` option and the +`podman rm --volumes` command. You can specify multiple **-v** options to mount one or more volumes into a container. -You can add `:ro` or `:rw` suffix to a volume to mount it read-only or + `Write Protected Volume Mounts` + +You can add `: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. + `Labeling Volume Mounts` + Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By @@ -930,13 +952,44 @@ content label. Shared volume labels allow all containers to read/write content. The `Z` option tells Podman to label the content with a private unshared label. Only the current container can use a private volume. + `Overlay Volume Mounts` + + The `:O` flag tells Podman to mount the directory from the host as a +temporary storage using the `overlay file system`. The container processes +can modify content within the mountpoint which is stored in the +container storage in a separate directory. In overlay terms, the source +directory will be the lower, and the container storage directory will be the +upper. Modifications to the mount point are destroyed when the container +finishes executing, similar to a tmpfs mount point being unmounted. + + Subsequent executions of the container will see the original source directory +content, any changes from previous container executions no longer exists. + + One use case of the overlay mount is sharing the package cache from the +host into the container to allow speeding up builds. + + Note: + + - The `O` flag conflicts with other options listed above. +Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory must be readable +by the container label. Usually containers can read/execute `container_share_t` +and can read/write `container_file_t`. If you can not change the labels on a +source volume, SELinux container separation must be disabled for the container +to work. + - The source directory mounted into the container with an overlay mount +should not be modified, it can cause unexpected failures. It is recommended +that you do not modify the directory until the container finishes running. + + `Mounts propagation` + By default bind mounted volumes are `private`. That means any mounts done inside container will not be visible on host and vice versa. One can change this behavior by specifying a volume mount propagation property. Making a volume `shared` mounts done under that volume inside container will be visible on host and vice versa. Making a volume `slave` enables only one way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. +will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> To control mount propagation property of volume one can use `:[r]shared`, `:[r]slave` or `:[r]private` propagation flag. Propagation property can @@ -944,9 +997,9 @@ be specified only for bind mounted volumes and not for internal volumes or named volumes. For mount propagation to work source mount point (mount point where source dir is mounted on) has to have right propagation properties. For shared volumes, source mount point has to be shared. And for slave volumes, -source mount has to be either shared or slave. +source mount has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> -If you want to recursively mount a volume and all of it's submounts into a +If you want to recursively mount a volume and all of its submounts into a container, then you can use the `rbind` option. By default the bind option is used, and submounts of the source directory will not be mounted into the container. @@ -971,7 +1024,7 @@ properties of source mount. If `findmnt` utility is not available, then one can look at mount entry for source mount point in `/proc/self/mountinfo`. Look at `optional fields` and see if any propagation properties are specified. `shared:X` means mount is `shared`, `master:X` means mount is `slave` and if -nothing is there that means mount is `private`. +nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup> To change propagation properties of a mount point use `mount` command. For example, if one wants to bind mount source directory `/foo` one can do @@ -1077,14 +1130,13 @@ required for VPN, without it containers need to be run with the --network=host f Environment variables within containers can be set using multiple different options: This section describes the precedence. -Precedence Order: - **--env-host** : Host environment of the process executing Podman is added. - - Container image : Any environment variables specified in the container image. +Precedence order (later entries override earlier entries): - **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. - - **--env** : Any environment variables specified will override previous settings. +- **--env-host** : Host environment of the process executing Podman is added. +- **--http-proxy**: By default, several environment variables will be passed in from the host, such as **http_proxy** and **no_proxy**. See **--http-proxy** for details. +- Container image : Any environment variables specified in the container image. +- **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. +- **--env** : Any environment variables specified will override previous settings. Create containers and set the environment ending with a __*__ and a ***** @@ -1107,7 +1159,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 -subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1) +**subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1). ## HISTORY October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman <dwalsh@redhat.com> @@ -1117,3 +1169,6 @@ November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> + +## FOOTNOTES +<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately. diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index abfc6e9c1..0d91cdf17 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -10,7 +10,7 @@ podman\-events - Monitor Podman events Monitor and print events that occur in Podman. Each event will include a timestamp, a type, a status, name (if applicable), and image (if applicable). The default logging -mechanism is *journald*. This can be changed in libpod.conf by changing the `events_logger` +mechanism is *journald*. This can be changed in containers.conf by changing the `events_logger` value to `file`. Only `file` and `journald` are accepted. A `none` logger is also available but this logging mechanism completely disables events; nothing will be reported by `podman events`. @@ -150,7 +150,7 @@ $ podman events --format json ``` ## SEE ALSO -podman(1) +podman(1), containers.conf(5) ## HISTORY March 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/markdown/podman-image-mount.1.md b/docs/source/markdown/podman-image-mount.1.md new file mode 100644 index 000000000..f98b46571 --- /dev/null +++ b/docs/source/markdown/podman-image-mount.1.md @@ -0,0 +1,76 @@ +% podman-image-mount(1) + +## NAME +podman\-image\-mount - Mount an image's root filesystem + +## SYNOPSIS +**podman image mount** [*options*] [*image* ...] + +## DESCRIPTION +Mounts the specified images' root file system in a location which can be +accessed from the host, and returns its location. + +If you execute the command without any arguments, Podman will list all of the +currently mounted images. + +Rootless mode only supports mounting VFS driver, unless you enter the user namespace +via the `podman unshare` command. All other storage drivers will fail to mount. + +## RETURN VALUE +The location of the mounted file system. On error an empty string and errno is +returned. + +## OPTIONS + +**--all**, **-a** + +Mount all images. + +**--format**=*format* + +Print the mounted images in specified format (json). + +## EXAMPLE + +``` +podman image mount fedora ubi8-init + +/var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged +/var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged +``` + +``` +podman mount + +registry.fedoraproject.org/fedora:latest /var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged +registry.access.redhat.com/ubi8-init:latest /var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged +``` + +``` +podman image mount --format json +[ + { + "id": "00ff39a8bf19f810a7e641f7eb3ddc47635913a19c4996debd91fafb6b379069", + "Names": [ + "sha256:58de585a231aca14a511347bc85b912a6f000159b49bc2b0582032911e5d3a6c" + ], + "Repositories": [ + "registry.fedoraproject.org/fedora:latest" + ], + "mountpoint": "/var/lib/containers/storage/overlay/0ccfac04663bbe8813b5f24502ee0b7371ce5bf3c5adeb12e4258d191c2cf7bc/merged" + }, + { + "id": "bcc2dc9a261774ad25a15e07bb515f9b77424266abf2a1252ec7bcfed1dd0ac2", + "Names": [ + "sha256:d5f260b2e51b3ee9d05de1c31d261efc9af28e7d2d47cedf054c496d71424d63" + ], + "Repositories": [ + "registry.access.redhat.com/ubi8-init:latest" + ], + "mountpoint": "/var/lib/containers/storage/overlay/d66b58e3391ea8ce4c81316c72e22b332618f2a28b461a32ed673e8998cdaeb8/merged" + } +] +``` + +## SEE ALSO +podman(1), podman-image-umount(1), mount(8), podman-unshare(1) diff --git a/docs/source/markdown/podman-image-trust.1.md b/docs/source/markdown/podman-image-trust.1.md index 435d117f1..8b80ca602 100644 --- a/docs/source/markdown/podman-image-trust.1.md +++ b/docs/source/markdown/podman-image-trust.1.md @@ -30,8 +30,8 @@ If no configuration is found for any of these scopes, the default value (specifi Trust **type** provides a way to: -Whitelist ("accept") or -Blacklist ("reject") registries or +Allowlist ("accept") or +Denylist ("reject") registries or Require signature (“signedBy”). Trust may be updated using the command **podman image trust set** for an existing trust scope. diff --git a/docs/source/markdown/podman-image-unmount.1.md b/docs/source/markdown/podman-image-unmount.1.md new file mode 100644 index 000000000..c026c49ac --- /dev/null +++ b/docs/source/markdown/podman-image-unmount.1.md @@ -0,0 +1,43 @@ +% podman-image-unmount(1) + +## NAME +podman\-image\-unmount - Unmount an image's root filesystem + +## SYNOPSIS +**podman image unmount** [*options*] *image* [...] + +**podman image umount** [*options*] *image* [...] + +## DESCRIPTION +Unmounts the specified images' root file system, if no other processes +are using it. + +Image storage increments a mount counter each time a image is mounted. +When a image is unmounted, the mount counter is decremented, and the +image's root filesystem is physically unmounted only when the mount +counter reaches zero indicating no other processes are using the mount. +An unmount can be forced with the --force flag. + +## OPTIONS +**--all**, **-a** + +All of the currently mounted images will be unmounted. + +**--force**, **-f** + +Force the unmounting of specified images' root file system, even if other +processes have mounted it. + +Note: This could cause other processes that are using the file system to fail, +as the mount point could be removed without their knowledge. + +## EXAMPLE + +podman image unmount imageID + +podman image unmount imageID1 imageID2 imageID3 + +podman image unmount --all + +## SEE ALSO +podman(1), podman-image-mount(1), podman-container-mount(1) diff --git a/docs/source/markdown/podman-image.1.md b/docs/source/markdown/podman-image.1.md index dfff57b31..55e95d032 100644 --- a/docs/source/markdown/podman-image.1.md +++ b/docs/source/markdown/podman-image.1.md @@ -17,21 +17,23 @@ The image command allows you to manage images | 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. | -| inspect | [podman-inspect(1)](podman-inspect.1.md) | Display a image or image's configuration. | -| list | [podman-images(1)](podman-images.1.md) | List the container images on the system.(alias ls) | -| load | [podman-load(1)](podman-load.1.md) | Load an image from the docker archive. | -| prune | [podman-image-prune(1)](podman-image-prune.1.md)| Remove all unused images from the local store. | -| pull | [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. | -| 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. | -| tree | [podman-image-tree(1)](podman-image-tree.1.md) | Prints layer hierarchy of an image in a tree format. | -| trust | [podman-image-trust(1)](podman-image-trust.1.md)| Manage container registry image trust policy. | +| import | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | +| inspect | [podman-inspect(1)](podman-inspect.1.md) | Display a image or image's configuration. | +| list | [podman-images(1)](podman-images.1.md) | List the container images on the system.(alias ls) | +| mount | [podman-image-mount(1)](podman-image-mount.1.md) | Mount an image's root filesystem. | +| load | [podman-load(1)](podman-load.1.md) | Load an image from the docker archive. | +| prune | [podman-image-prune(1)](podman-image-prune.1.md) | Remove all unused images from the local store. | +| pull | [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. | +| 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. | +| unmount | [podman-image-unmount(1)](podman-image-unmount.1.md) | Unmount an image's root filesystem. | +| tree | [podman-image-tree(1)](podman-image-tree.1.md) | Prints layer hierarchy of an image in a tree format. | +| trust | [podman-image-trust(1)](podman-image-trust.1.md) | Manage container registry image trust policy. | ## SEE ALSO podman diff --git a/docs/source/markdown/podman-mount.1.md b/docs/source/markdown/podman-mount.1.md index eaed1051e..33c5aece8 100644 --- a/docs/source/markdown/podman-mount.1.md +++ b/docs/source/markdown/podman-mount.1.md @@ -12,9 +12,12 @@ podman\-mount - Mount a working container's root filesystem Mounts the specified containers' root file system in a location which can be accessed from the host, and returns its location. -If you execute the command without any arguments, the tool will list all of the +If you execute the command without any arguments, Podman will list all of the currently mounted containers. +Rootless mode only supports mounting VFS driver, unless you enter the user namespace +via the `podman unshare` command. All other storage drivers will fail to mount. + ## RETURN VALUE The location of the mounted file system. On error an empty string and errno is returned. @@ -27,7 +30,7 @@ Mount all containers. **--format**=*format* -Print the mounted containers in specified format (json) +Print the mounted containers in specified format (json). **--latest**, **-l** @@ -70,4 +73,4 @@ a7060253093b /var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd ``` ## SEE ALSO -podman(1), podman-umount(1), mount(8) +podman(1), podman-umount(1), mount(8), podman-unshare(1) diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 5d941219a..201b10aa6 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -73,6 +73,12 @@ 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. +**--disable-content-trust** + +This is a Docker specific option to disable image verification to a Docker +registry and is not supported by Podman. This flag is a NOOP and provided +solely for scripting compatibility. + **--override-os**=*OS* Use OS instead of the running OS for choosing images diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index f029c8db1..fffd76801 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -71,6 +71,12 @@ Note: This flag can only be set when using the **dir** transport After copying the image, write the digest of the resulting image to the file. (Not available for remote commands) +**--disable-content-trust** + +This is a Docker specific option to disable image verification to a Docker +registry and is not supported by Podman. This flag is a NOOP and provided +solely for scripting compatibility. + **--format**, **-f**=*format* Manifest Type (oci, v2s1, or v2s2) to use when pushing an image to a directory using the 'dir:' transport (default is manifest type of source) diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 54c497ba2..4fdb7f81b 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -208,7 +208,7 @@ Specify the key sequence for detaching a container; _sequence_ is a comma-delimi in which each item can be a single character from the [a-Z] range, or **ctrl**-_value_, where _value_ is one of: **a-z** or **@^[,_**. -This option can also be set in **libpod.conf**(5) file. +This option can also be set in **containers.conf**(5) file. Specifying "" will disable this feature. The default is **ctrl-p,ctrl-q**. @@ -247,6 +247,12 @@ Limit write rate (in bytes per second) to a device (e.g. **--device-write-bps=/d Limit write rate (in IO operations per second) to a device (e.g. **--device-write-iops=/dev/sda:1000**). +**--disable-content-trust** + +This is a Docker specific option to disable image verification to a Docker +registry and is not supported by Podman. This flag is a NOOP and provided +solely for scripting compatibility. + **--dns**=*ipaddr* Set custom DNS servers. Invalid if using **--dns** with **--network** that is set to **none** or **container:**_id_. @@ -495,7 +501,7 @@ Tune a container's memory swappiness behavior. Accepts an integer between *0* an Attach a filesystem mount to the container -Current supported mount TYPEs are **bind**, **volume**, and **tmpfs**. +Current supported mount TYPEs are **bind**, **volume**, and **tmpfs**. <sup>[[1]](#Footnote1)</sup> e.g. @@ -561,7 +567,10 @@ Valid _mode_ values are: - _network-id_: connect to a user-defined network, multiple networks should be comma separated; - **ns:**_path_: path to a network namespace to join; - `private`: create a new namespace for the container (default) -- **slirp4netns**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. +- **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options: + **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default. + **port_handler=slirp4netns**: Use the slirp4netns port forwarding. + **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default to false. **--network-alias**=*alias* @@ -754,9 +763,9 @@ Security Options - **label=disable**: Turn off label separation for the container - **no-new-privileges**: Disable container processes from gaining additional privileges - **seccomp=unconfined**: Turn off seccomp confinement for the container -- **seccomp**=_profile.json_: Whitelisted syscalls seccomp JSON file to be used as a seccomp filter +- **seccomp**=_profile.json_: Allowed syscall list seccomp JSON file to be used as a seccomp filter -Note: Labeling can be disabled for all containers by setting **label=false** in the **libpod.conf**(5) file. +Note: Labeling can be disabled for all containers by setting **label=false** in the **containers.conf**(5) file. **--shm-size**=_number_[_unit_] @@ -871,6 +880,10 @@ standard input. Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones. +**--umask**=*umask* + +Set the umask inside the container. Defaults to `0022`. + **--uidmap**=*container_uid*:*host_uid*:*amount* Run the container in a new user namespace using the supplied mapping. This option conflicts @@ -924,7 +937,7 @@ 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. -The _options_ is a comma delimited list and can be: +The _options_ is a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup> * **rw**|**ro** * **z**|**Z** @@ -933,6 +946,7 @@ The _options_ is a comma delimited list and can be: * [**no**]**exec** * [**no**]**dev** * [**no**]**suid** +* [**O**] The _container-dir_ must be an absolute path. @@ -944,7 +958,7 @@ the container is removed via the **--rm** flag or **podman rm --volumes**. If a volume source is specified, it must be a path on the host or the name of a named volume. Host paths are allowed to be absolute or relative; relative paths are resolved relative to the directory Podman is run in. Any source that does -not begin with a **.** or **/** it will be treated as the name of a named volume. +not begin with a **.** or **/** will be treated as the name of a named volume. If a volume with that name does not exist, it will be created. Volumes created with names are not anonymous and are not removed by **--rm** and **podman rm --volumes**. @@ -955,6 +969,8 @@ container. You can add **:ro** or **:rw** option to mount a volume in read-only or read-write mode, respectively. By default, the volumes are mounted read-write. + `Labeling Volume Mounts` + Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By @@ -966,15 +982,47 @@ objects on the shared volumes. The **z** option tells Podman that two containers share the volume content. As a result, Podman labels the content with a shared content label. Shared volume labels allow all containers to read/write content. The **Z** option tells Podman to label the content with a private unshared label. + + `Overlay Volume Mounts` + + The `:O` flag tells Podman to mount the directory from the host as a +temporary storage using the `overlay file system`. The container processes +can modify content within the mountpoint which is stored in the +container storage in a separate directory. In overlay terms, the source +directory will be the lower, and the container storage directory will be the +upper. Modifications to the mount point are destroyed when the container +finishes executing, similar to a tmpfs mount point being unmounted. + + Subsequent executions of the container will see the original source directory +content, any changes from previous container executions no longer exists. + + One use case of the overlay mount is sharing the package cache from the +host into the container to allow speeding up builds. + + Note: + + - The `O` flag conflicts with other options listed above. +Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory must be readable +by the container label. Usually containers can read/execute `container_share_t` +and can read/write `container_file_t`. If you can not change the labels on a +source volume, SELinux container separation must be disabled for the container +to work. + - The source directory mounted into the container with an overlay mount +should not be modified, it can cause unexpected failures. It is recommended +that you do not modify the directory until the container finishes running. + Only the current container can use a private volume. -By default bind mounted volumes are **private**. That means any mounts done + `Mounts propagation` + +By default bind mounted volumes are `private`. That means any mounts done inside container will not be visible on host and vice versa. One can change this behavior by specifying a volume mount propagation property. Making a volume shared mounts done under that volume inside container will be visible on host and vice versa. Making a volume **slave** enables only one way mount propagation and that is mounts done on host under that volume -will be visible inside container but not the other way around. +will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup> To control mount propagation property of volume one can use [**r**]**shared**, [**r**]**slave** or [**r**]**private** propagation flag. Propagation property can @@ -982,7 +1030,7 @@ be specified only for bind mounted volumes and not for internal volumes or named volumes. For mount propagation to work source mount point (mount point where source dir is mounted on) has to have right propagation properties. For shared volumes, source mount point has to be shared. And for slave volumes, -source mount has to be either shared or slave. +source mount has to be either shared or slave. <sup>[[1]](#Footnote1)</sup> If you want to recursively mount a volume and all of its submounts into a container, then you can use the **rbind** option. By default the bind option is @@ -1009,7 +1057,7 @@ properties of source mount. If **findmnt**(1) utility is not available, then one can look at mount entry for source mount point in _/proc/self/mountinfo_. Look at the "optional fields" and see if any propagation properties are specified. In there, **shared:N** means the mount is shared, **master:N** means mount -is slave, and if nothing is there, the mount is private. +is slave, and if nothing is there, the mount is private. <sup>[[1]](#Footnote1)</sup> To change propagation properties of a mount point, use **mount**(8) command. For example, if one wants to bind mount source directory _/foo_, one can do @@ -1081,7 +1129,7 @@ the exit codes follow the **chroot**(1) standard, see below: **Exit code** _contained command_ exit code - $ podman run busybox /bin/sh -c 'exit 3' + $ podman run busybox /bin/sh -c 'exit 3'; echo $? 3 ## EXAMPLES @@ -1217,14 +1265,16 @@ $ podman run -p 8080:80 -d -i -t fedora/httpd To mount a host directory as a container volume, specify the absolute path to the directory and the absolute path for the container directory separated by a -colon. If the source is a named volume maintained by Podman, it's recommended to -use it's name rather than the path to the volume. Otherwise the volume will be +colon. If the source is a named volume maintained by Podman, it is recommended to +use its name rather than the path to the volume. Otherwise the volume will be considered as an orphan and wiped if you execute **podman volume prune**: ``` $ podman run -v /var/db:/data1 -i -t fedora bash $ podman run -v data:/data2 -i -t fedora bash + +$ podman run -v /var/cache/dnf:/var/cache/dnf:O -ti fedora dnf -y update ``` Using **--mount** flags to mount a host directory as a container folder, specify @@ -1359,10 +1409,11 @@ required for VPN, without it containers need to be run with the **--network=host ## ENVIRONMENT Environment variables within containers can be set using multiple different options, -in the following order of precedence: +in the following order of precedence (later entries override earlier entries): -- **--env-host**: Host environment of the process executing Podman is added. - Container image: Any environment variables specified in the container image. +- **--http-proxy**: By default, several environment variables will be passed in from the host, such as **http_proxy** and **no_proxy**. See **--http-proxy** for details. +- **--env-host**: Host environment of the process executing Podman is added. - **--env-file**: Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. - **--env**: Any environment variables specified will override previous settings. @@ -1386,7 +1437,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 -**subgid**(5), **subuid**(5), **libpod.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1). +**subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1). ## HISTORY September 2018, updated by Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp> @@ -1395,8 +1446,9 @@ October 2017, converted from Docker documentation to Podman by Dan Walsh for Pod November 2015, updated by Sally O'Malley <somalley@redhat.com> -July 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> - June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> April 2014, Originally compiled by William Henry <whenry@redhat.com> based on docker.com source material and internal work. + +## FOOTNOTES +<a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately. diff --git a/docs/source/markdown/podman-system-connection-add.1.md b/docs/source/markdown/podman-system-connection-add.1.md new file mode 100644 index 000000000..5059803a2 --- /dev/null +++ b/docs/source/markdown/podman-system-connection-add.1.md @@ -0,0 +1,46 @@ +% podman-system-connection-add(1) + +## NAME +podman\-system\-connection\-add - Record destination for the Podman service + +## SYNOPSIS +**podman system connection add** [*options*] *name* *destination* + +## DESCRIPTION +Record ssh destination for remote podman service(s). The ssh destination is given as one of: + - [user@]hostname[:port] + - ssh://[user@]hostname[:port] + +The user will be prompted for the remote ssh login password or key file pass phrase as required. The `ssh-agent` is supported if it is running. + +## OPTIONS + +**-d**, **--default**=*false* + +Make the new destination the default for this user. + +**--identity**=*path* + +Path to ssh identity file. If the identity file has been encrypted, Podman prompts the user for the passphrase. +If no identity file is provided and no user is given, Podman defaults to the user running the podman command. +Podman prompts for the login password on the remote server. + +**-p**, **--port**=*port* + +Port for ssh destination. The default value is `22`. + +**--socket-path**=*path* + +Path to the Podman service unix domain socket on the ssh destination host + +## EXAMPLE +``` +$ podman system connection add QA podman.example.com + +$ podman system connection add --identity ~/.ssh/dev_rsa production ssh://root@server.example.com:2222 +``` +## SEE ALSO +podman-system(1) , podman-system-connection(1) , containers.conf(5) + +## HISTORY +June 2020, Originally compiled by Jhon Honce (jhonce at redhat dot com) diff --git a/docs/source/markdown/podman-system-connection-default.1.md b/docs/source/markdown/podman-system-connection-default.1.md new file mode 100644 index 000000000..f324f8c01 --- /dev/null +++ b/docs/source/markdown/podman-system-connection-default.1.md @@ -0,0 +1,20 @@ +% podman-system-connection-default(1) + +## NAME +podman\-system\-connection\-default - Set named destination as default for the Podman service + +## SYNOPSIS +**podman system connection default** *name* + +## DESCRIPTION +Set named ssh destination as default destination for the Podman service. + +## EXAMPLE +``` +$ podman system connection default production +``` +## SEE ALSO +podman-system(1) , podman-system-connection(1) , containers.conf(5) + +## HISTORY +July 2020, Originally compiled by Jhon Honce (jhonce at redhat dot com) diff --git a/docs/source/markdown/podman-system-connection-list.1.md b/docs/source/markdown/podman-system-connection-list.1.md new file mode 100644 index 000000000..f5fb5c8e3 --- /dev/null +++ b/docs/source/markdown/podman-system-connection-list.1.md @@ -0,0 +1,24 @@ +% podman-system-connection-list(1) + +## NAME +podman\-system\-connection\-list - List the destination for the Podman service(s) + +## SYNOPSIS +**podman system connection list** + +**podman system connection ls** + +## DESCRIPTION +List ssh destination(s) for podman service(s). + +## EXAMPLE +``` +$ podman system connection list +Name URI Identity +devl ssh://root@example.com/run/podman/podman.sock ~/.ssh/id_rsa +``` +## SEE ALSO +podman-system(1) , containers.conf(5) + +## HISTORY +July 2020, Originally compiled by Jhon Honce (jhonce at redhat dot com) diff --git a/docs/source/markdown/podman-system-connection-remove.1.md b/docs/source/markdown/podman-system-connection-remove.1.md new file mode 100644 index 000000000..faa767176 --- /dev/null +++ b/docs/source/markdown/podman-system-connection-remove.1.md @@ -0,0 +1,20 @@ +% podman-system-connection-remove(1) + +## NAME +podman\-system\-connection\-remove - Delete named destination + +## SYNOPSIS +**podman system connection remove** *name* + +## DESCRIPTION +Delete named ssh destination. + +## EXAMPLE +``` +$ podman system connection remove production +``` +## SEE ALSO +podman-system(1) , podman-system-connection(1) , containers.conf(5) + +## HISTORY +July 2020, Originally compiled by Jhon Honce (jhonce at redhat dot com) diff --git a/docs/source/markdown/podman-system-connection-rename.1.md b/docs/source/markdown/podman-system-connection-rename.1.md new file mode 100644 index 000000000..819cb697f --- /dev/null +++ b/docs/source/markdown/podman-system-connection-rename.1.md @@ -0,0 +1,20 @@ +% podman-system-connection-rename(1) + +## NAME +podman\-system\-connection\-rename - Rename the destination for Podman service + +## SYNOPSIS +**podman system connection rename** *old* *new* + +## DESCRIPTION +Rename ssh destination from *old* to *new*. + +## EXAMPLE +``` +$ podman system connection rename laptop devel +``` +## SEE ALSO +podman-system(1) , podman-system-connection(1) , containers.conf(5) + +## HISTORY +July 2020, Originally compiled by Jhon Honce (jhonce at redhat dot com) diff --git a/docs/source/markdown/podman-system-connection.1.md b/docs/source/markdown/podman-system-connection.1.md index ed73980d6..86199c6b9 100644 --- a/docs/source/markdown/podman-system-connection.1.md +++ b/docs/source/markdown/podman-system-connection.1.md @@ -1,37 +1,34 @@ % podman-system-connection(1) ## NAME -podman\-system\-connection - Record ssh destination for remote podman service +podman\-system\-connection - Manage the destination(s) for Podman service(s) -## SYNOPSIS -**podman system connection** [*options*] [*ssh destination*] +## SYNOPSISManage the destination(s) for Podman service(s) +**podman system connection** *subcommand* ## DESCRIPTION -Record ssh destination for remote podman service(s). The ssh destination is given as one of: - - [user@]hostname[:port] - - ssh://[user@]hostname[:port] +Manage the destination(s) for Podman service(s). -The user will be prompted for the remote ssh login password or key file pass phrase as required. `ssh-agent` is supported if it is running. +The user will be prompted for the ssh login password or key file pass phrase as required. The `ssh-agent` is supported if it is running. -## OPTIONS +## COMMANDS -**-p**, **--port**=*port* - -Port for ssh destination. The default value is `22`. - -**--socket-path**=*path* - -Path to podman service unix domain socket on the ssh destination host +| Command | Man Page | Description | +| ------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------- | +| add | [podman-system-connection-add(1)](podman-system-connection-add.1.md) | Record destination for the Podman service | +| default | [podman-system-connection-default(1)](podman-system-connection-default.1.md) | Set named destination as default for the Podman service | +| list | [podman-system-connection-list(1)](podman-system-connection-list.1.md) | List the destination for the Podman service(s) | +| remove | [podman-system-connection-remove(1)](podman-system-connection-remove.1.md) | Delete named destination | +| rename | [podman-system-connection-rename(1)](podman-system-connection-rename.1.md) | Rename the destination for Podman service | ## EXAMPLE ``` -$ podman system connection podman.fubar.com - -$ podman system connection --identity ~/.ssh/dev_rsa ssh://root@server.fubar.com:2222 - +$ podman system connection list +Name URI Identity +devl ssh://root@example.com/run/podman/podman.sock ~/.ssh/id_rsa ``` ## SEE ALSO -podman-system(1) , containers.conf(5) , connections.conf(5) +podman-system(1) , containers.conf(5) ## HISTORY June 2020, Originally compiled by Jhon Honce (jhonce at redhat dot com) diff --git a/docs/source/markdown/podman-system-migrate.1.md b/docs/source/markdown/podman-system-migrate.1.md index baabfd14b..29c0ef94b 100644 --- a/docs/source/markdown/podman-system-migrate.1.md +++ b/docs/source/markdown/podman-system-migrate.1.md @@ -33,7 +33,7 @@ This can be used after a system upgrade which changes the default OCI runtime to There are no guarantees that the containers will continue to work under the new runtime, as some runtimes support differing options and configurations. ## SEE ALSO -`podman(1)`, `libpod.conf(5)`, `usermod(8)` +`podman(1)`, `containers.conf(5)`, `usermod(8)` ## HISTORY April 2019, Originally compiled by Giuseppe Scrivano (gscrivan at redhat dot com) diff --git a/docs/source/markdown/podman-system-renumber.1.md b/docs/source/markdown/podman-system-renumber.1.md index 071eefe29..51c085606 100644 --- a/docs/source/markdown/podman-system-renumber.1.md +++ b/docs/source/markdown/podman-system-renumber.1.md @@ -9,9 +9,9 @@ podman\-system\-renumber - Migrate lock numbers to handle a change in maximum nu ## DESCRIPTION **podman system renumber** renumbers locks used by containers and pods. -Each Podman container and pod is allocated a lock at creation time, up to a maximum number controlled by the **num_locks** parameter in **libpod.conf**. +Each Podman container and pod is allocated a lock at creation time, up to a maximum number controlled by the **num_locks** parameter in **containers.conf**. -When all available locks are exhausted, no further containers and pods can be created until some existing containers and pods are removed. This can be avoided by increasing the number of locks available via modifying **libpod.conf** and subsequently running **podman system renumber** to prepare the new locks (and reallocate lock numbers to fit the new struct). +When all available locks are exhausted, no further containers and pods can be created until some existing containers and pods are removed. This can be avoided by increasing the number of locks available via modifying **containers.conf** and subsequently running **podman system renumber** to prepare the new locks (and reallocate lock numbers to fit the new struct). **podman system renumber** must be called after any changes to **num_locks** - failure to do so will result in errors starting Podman as the number of locks available conflicts with the configured number of locks. @@ -20,7 +20,7 @@ When all available locks are exhausted, no further containers and pods can be cr If possible, avoid calling **podman system renumber** while there are other Podman processes running. ## SEE ALSO -`podman(1)`, `libpod.conf(5)` +`podman(1)`, `containers.conf(5)` ## HISTORY February 2019, Originally compiled by Matt Heon (mheon at redhat dot com) diff --git a/docs/source/markdown/podman-system-reset.1.md b/docs/source/markdown/podman-system-reset.1.md index f290e26d5..3294bac9b 100644 --- a/docs/source/markdown/podman-system-reset.1.md +++ b/docs/source/markdown/podman-system-reset.1.md @@ -7,7 +7,7 @@ podman\-system\-reset - Reset storage back to initial state **podman system reset** [*options*] ## DESCRIPTION -**podman system reset** removes all pods, containers, images and volumes. +**podman system reset** removes all pods, containers, images and volumes. Must be run after changing any of the following values in the `containers.conf` file: `static_dir`, `tmp_dir` or `volume_path`. ## OPTIONS **--force**, **-f** diff --git a/docs/source/markdown/podman-system.1.md b/docs/source/markdown/podman-system.1.md index 1f19fd0b6..9ac73237e 100644 --- a/docs/source/markdown/podman-system.1.md +++ b/docs/source/markdown/podman-system.1.md @@ -11,17 +11,16 @@ The system command allows you to manage the podman systems ## COMMANDS -| Command | Man Page | Description | -| ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | -| df | [podman-system-df(1)](podman-system-df.1.md) | Show podman disk usage. | -| connection | [podman-system-connection(1)](podman-system-connection.1.md) | Record ssh destination for remote podman service. | -| info | [podman-system-info(1)](podman-info.1.md) | Displays Podman related system information. | -| migrate | [podman-system-migrate(1)](podman-system-migrate.1.md) | Migrate existing containers to a new podman version. | -| prune | [podman-system-prune(1)](podman-system-prune.1.md) | Remove all unused container, image and volume data. | -| renumber | [podman-system-renumber(1)](podman-system-renumber.1.md) | Migrate lock numbers to handle a change in maximum number of locks. | -| reset | [podman-system-reset(1)](podman-system-reset.1.md) | Reset storage back to initial state. | -| service | [podman-service(1)](podman-system-service.1.md) | Run an API service | - +| Command | Man Page | Description | +| ------- | ------------------------------------------------------------ | -------------------------------------------------------------------- | +| connection | [podman-system-connection(1)](podman-system-connection.1.md) | Manage the destination(s) for Podman service(s) | +| df | [podman-system-df(1)](podman-system-df.1.md) | Show podman disk usage. | +| info | [podman-system-info(1)](podman-info.1.md) | Displays Podman related system information. | +| migrate | [podman-system-migrate(1)](podman-system-migrate.1.md) | Migrate existing containers to a new podman version. | +| prune | [podman-system-prune(1)](podman-system-prune.1.md) | Remove all unused container, image and volume data. | +| renumber | [podman-system-renumber(1)](podman-system-renumber.1.md) | Migrate lock numbers to handle a change in maximum number of locks. | +| reset | [podman-system-reset(1)](podman-system-reset.1.md) | Reset storage back to initial state. | +| service | [podman-system-service(1)](podman-system-service.1.md) | Run an API service | ## SEE ALSO podman(1) diff --git a/docs/source/markdown/podman-umount.1.md b/docs/source/markdown/podman-unmount.1.md index 31a213f28..47c55cc0b 100644 --- a/docs/source/markdown/podman-umount.1.md +++ b/docs/source/markdown/podman-unmount.1.md @@ -1,23 +1,23 @@ -% podman-umount(1) +% podman-unmount(1) ## NAME -podman\-umount - Unmount a working container's root filesystem +podman\-unmount - Unmount a working container's root filesystem ## SYNOPSIS -**podman umount** [*options*] *container* [...] +**podman unmount** [*options*] *container* [...] -**podman container umount** [*options*] *container* [...] +**podman umount** [*options*] *container* [...] **podman container unmount** [*options*] *container* [...] -**podman unmount** [*options*] *container* [...] +**podman container umount** [*options*] *container* [...] ## DESCRIPTION Unmounts the specified containers' root file system, if no other processes are using it. Container storage increments a mount counter each time a container is mounted. -When a container is unmounted, the mount counter is decremented and the +When a container is unmounted, the mount counter is decremented, and the container's root filesystem is physically unmounted only when the mount counter reaches zero indicating no other processes are using the mount. An unmount can be forced with the --force flag. @@ -45,11 +45,11 @@ The latest option is not supported on the remote client. ## EXAMPLE -podman umount containerID +podman container unmount containerID -podman umount containerID1 containerID2 containerID3 +podman unmount containerID1 containerID2 containerID3 -podman umount --all +podman unmount --all ## SEE ALSO -podman(1), podman-mount(1) +podman(1), podman-container-mount(1), podman-image-mount(1) diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index c45c10243..16439c167 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -23,7 +23,7 @@ created by the other. **--cgroup-manager**=*manager* -CGroup manager to use for container cgroups. Supported values are cgroupfs or systemd. Default is systemd unless overridden in the libpod.conf file. +The CGroup manager to use for container cgroups. Supported values are cgroupfs or systemd. Default is systemd unless overridden in the containers.conf file. Note: Setting this flag can cause certain commands to break when called on containers previously created by the other CGroup manager type. Note: CGroup manager is not supported in rootless mode when using CGroups Version V1. @@ -32,7 +32,7 @@ Note: CGroup manager is not supported in rootless mode when using CGroups Versio Path of the configuration directory for CNI networks. (Default: `/etc/cni/net.d`) **--conmon** -Path of the conmon binary (Default path is configured in `libpod.conf`) +Path of the conmon binary (Default path is configured in `containers.conf`) **--events-backend**=*type* @@ -94,7 +94,7 @@ Default state dir configured in `/etc/containers/storage.conf`. **--runtime**=*value* -Name of the OCI runtime as specified in libpod.conf or absolute path to the OCI compatible binary used to run containers. +Name of the OCI runtime as specified in containers.conf or absolute path to the OCI compatible binary used to run containers. **--storage-driver**=*value* @@ -207,7 +207,7 @@ the exit codes follow the `chroot` standard, see below: | [podman-system(1)](podman-system.1.md) | Manage podman. | | [podman-tag(1)](podman-tag.1.md) | Add an additional name to a local image. | | [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | -| [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem. | +| [podman-unmount(1)](podman-unmount.1.md) | Unmount a working container's root filesystem. | | [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. | | [podman-unshare(1)](podman-unshare.1.md) | Run a command inside of a modified user namespace. | | [podman-untag(1)](podman-untag.1.md) | Removes one or more names from a locally-stored image. | @@ -217,11 +217,13 @@ the exit codes follow the `chroot` standard, see below: ## FILES -**libpod.conf** (`/usr/share/containers/libpod.conf`) +**containers.conf** (`/usr/share/containers/containers.conf`, `/etc/containers/containers.conf`, `$HOME/.config/containers/containers.conf`) - libpod.conf is the configuration file for all tools using libpod to manage containers, when run as root. Administrators can override the defaults file by creating `/etc/containers/libpod.conf`. When Podman runs in rootless mode, the file `$HOME/.config/containers/libpod.conf` is created and replaces some fields in the system configuration file. + Podman has builtin defaults for command line options. These defaults can be overridden using the containers.conf configuration files. - Podman uses builtin defaults if no libpod.conf file is found. +Distributions ship the `/usr/share/containers/containers.conf` file with their default settings. Administrators can override fields in this file by creating the `/etc/containers/containers.conf` file. Users can further modify defaults by creating the `$HOME/.config/containers/containers.conf` file. Podman merges its builtin defaults with the specified fields from these files, if they exist. Fields specified in the users file override the administrator's file, which overrides the distribution's file, which override the built-in defaults. + +Podman uses builtin defaults if no containers.conf file is found. **mounts.conf** (`/usr/share/containers/mounts.conf`) @@ -233,13 +235,13 @@ When Podman runs in rootless mode, the file `$HOME/.config/containers/mounts.con Signature verification policy files are used to specify policy, e.g. trusted keys, applicable when deciding whether to accept an image, or individual signatures of that image, as valid. -**registries.conf** (`/etc/containers/registries.conf`) +**registries.conf** (`/etc/containers/registries.conf`, `$HOME/.config/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. Non root users of Podman can create the `$HOME/.config/containers/registries.conf` file to be used instead of the system defaults. -**storage.conf** (`/etc/containers/storage.conf`) +**storage.conf** (`/etc/containers/storage.conf`, `$HOME/.config/contaners/storage.conf`) storage.conf is the storage configuration file for all tools using containers/storage @@ -277,10 +279,10 @@ The Overlay file system (OverlayFS) is not supported in rootless mode. The fuse The Network File System (NFS) and other distributed file systems (for example: Lustre, Spectrum Scale, the General Parallel File System (GPFS)) are not supported when running in rootless mode as these file systems do not understand user namespace. However, rootless Podman can make use of an NFS Homedir by modifying the `$HOME/.config/containers/storage.conf` to have the `graphroot` option point to a directory stored on local (Non NFS) storage. -For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/libpod/blob/master/troubleshooting.md). +For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/podman/blob/master/troubleshooting.md). ## SEE ALSO -`containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `buildah(1)`, `libpod.conf(5)`, `oci-hooks(5)`, `containers-policy.json(5)`, `subuid(5)`, `subgid(5)`, `slirp4netns(1)` +`containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `buildah(1)`, `containers.conf(5)`, `oci-hooks(5)`, `containers-policy.json(5)`, `subuid(5)`, `subgid(5)`, `slirp4netns(1)` ## HISTORY Dec 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/system.rst b/docs/source/system.rst index 2f2b7ea8f..2d93a1d6d 100644 --- a/docs/source/system.rst +++ b/docs/source/system.rst @@ -10,3 +10,5 @@ System :doc:`prune <markdown/podman-system-prune.1>` Remove unused data :doc:`renumber <markdown/podman-system-renumber.1>` Migrate lock numbers + +:doc:`reset <markdown/podman-system-reset.1>` Reset podman storage diff --git a/docs/tutorials/mac_client.md b/docs/tutorials/mac_client.md index bf08e8cc1..f6c9160a8 100644 --- a/docs/tutorials/mac_client.md +++ b/docs/tutorials/mac_client.md @@ -88,7 +88,7 @@ localhost/test latest 4b8c27c343e1 4 weeks ago 253 k8s.gcr.io/pause 3.1 da86e6ba6ca1 20 months ago 747 kB ``` If the conf file is set up, you may simply use Podman as you would on the linux machine. Take a look at -[podman-remote.conf.5.md](https://github.com/containers/libpod/blob/master/docs/podman-remote.conf.5.md) on how to use the conf file: +[podman-remote.conf.5.md](https://github.com/containers/podman/blob/master/docs/podman-remote.conf.5.md) on how to use the conf file: ``` $ podman images diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md index 6605d3359..97268fc41 100644 --- a/docs/tutorials/podman_tutorial.md +++ b/docs/tutorials/podman_tutorial.md @@ -5,7 +5,7 @@ Podman is a utility provided as part of the libpod library. It can be used to c containers. The following tutorial will teach you how to set up Podman and perform some basic commands with Podman. -If you are running on a Mac, you should instead follow the [Mac tutorial](https://github.com/containers/libpod/blob/master/docs/tutorials/mac_client.md) +If you are running on a Mac, you should instead follow the [Mac tutorial](https://github.com/containers/podman/blob/master/docs/tutorials/mac_client.md) to set up the remote Podman client. **NOTE**: the code samples are intended to be run as a non-root user, and use `sudo` where @@ -13,7 +13,7 @@ root escalation is required. ## Installing Podman -For installing or building Podman, please see the [installation instructions](https://github.com/containers/libpod/blob/master/install.md). +For installing or building Podman, please see the [installation instructions](https://github.com/containers/podman/blob/master/install.md). ## Familiarizing yourself with Podman diff --git a/docs/tutorials/remote_client.md b/docs/tutorials/remote_client.md index 36d429417..d4c43dda2 100644 --- a/docs/tutorials/remote_client.md +++ b/docs/tutorials/remote_client.md @@ -19,8 +19,8 @@ system as a user with privileges to the varlink socket (more on this later). ## Building the remote client At this time, the Podman remote-client is not being packaged for any distribution. It must be built from -source. To set up your build environment, see [Installation notes](https://github.com/containers/libpod/blob/master/install.md) and follow the -section [Building from scratch](https://github.com/containers/libpod/blob/master/install.md#building-from-scratch). Once you can successfully +source. To set up your build environment, see [Installation notes](https://github.com/containers/podman/blob/master/install.md) and follow the +section [Building from scratch](https://github.com/containers/podman/blob/master/install.md#building-from-scratch). Once you can successfully build the regular Podman binary, you can now build the remote-client. ``` $ make podman-remote diff --git a/docs/tutorials/rootless_tutorial.md b/docs/tutorials/rootless_tutorial.md index 440e12062..6b83f18d9 100644 --- a/docs/tutorials/rootless_tutorial.md +++ b/docs/tutorials/rootless_tutorial.md @@ -13,17 +13,17 @@ The alternative OCI runtime support for cgroup V2 can be turned on at the comma ``` sudo podman --runtime /usr/bin/crun ``` -or by changing the value for the "Default OCI runtime" in the libpod.conf file either at the system level or at the [user level](#user-configuration-files) from `runtime = "runc"` to `runtime = "crun"`. +or by changing the value for the "Default OCI runtime" in the containers.conf file either at the system level or at the [user level](#user-configuration-files) from `runtime = "runc"` to `runtime = "crun"`. ## Administrator Actions ### Installing Podman -For installing Podman, please see the [installation instructions](https://github.com/containers/libpod/blob/master/install.md). +For installing Podman, please see the [installation instructions](https://github.com/containers/podman/blob/master/install.md). ### Building Podman -For building Podman, please see the [installation instructions](https://github.com/containers/libpod/blob/master/install.md#building-from-scratch). +For building Podman, please see the [installation instructions](https://github.com/containers/podman/blob/master/install.md#building-from-scratch). ### Install slirp4netns @@ -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 `shadow-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. @@ -76,7 +76,7 @@ The format of this file is USERNAME:UID:RANGE This means the user johndoe is allocated UIDS 100000-165535 as well as their standard UID in the /etc/passwd file. NOTE: this is not currently supported with network installs. These files must be available locally to the host machine. It is not possible to configure this with LDAP or Active Directory. -If you update either the /etc/subuid or the /etc/subgid file, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user. This can be done automatically by using the [`podman system migrate`](https://github.com/containers/libpod/blob/master/docs/podman-system-migrate.1.md) command which will stop all the containers for the user and will kill the pause process. +If you update either the /etc/subuid or the /etc/subgid file, you need to stop all the running containers owned by the user and kill the pause process that is running on the system for that user. This can be done automatically by using the [`podman system migrate`](https://github.com/containers/podman/blob/master/docs/podman-system-migrate.1.md) command which will stop all the containers for the user and will kill the pause process. Rather than updating the files directly, the usermod program can be used to assign UIDs and GIDs to a user. @@ -106,9 +106,50 @@ Once the Administrator has completed the setup on the machine and then the confi ### User Configuration Files -The Podman configuration files for root reside in `/usr/share/containers` with overrides in `/etc/containers`. In the rootless environment they reside in `${XDG_CONFIG_HOME}/containers` (usually `~/.config/containers`) and are owned by each individual user. The main files are `libpod.conf` and `storage.conf` and the user can modify these files as they wish. +The Podman configuration files for root reside in `/usr/share/containers` with overrides in `/etc/containers`. In the rootless environment they reside in `${XDG_CONFIG_HOME}/containers` (usually `~/.config/containers`) and are owned by each individual user. -The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`. +The three main configuration files are [containers.conf](https://github.com/containers/common/blob/master/docs/containers.conf.5.md), [storage.conf](https://github.com/containers/storage/blob/master/docs/containers-storage.conf.5.md) and [registries.conf](https://github.com/containers/image/blob/master/docs/containers-registries.conf.5.md). The user can modify these files as they wish. + +#### containers.conf +Podman reads +1. `/usr/share/containers/containers.conf` +2. `/etc/containers/containers.conf` +3. `$HOME/.config/containers/containers.conf` + +if they exist in that order. Each file can override the previous for particular fields. + +#### storage.conf +For `storage.conf` the order is +1. `/etc/containers/storage.conf` +2. `$HOME/.config/containers/storage.conf` + +In rootless podman certain fields in `/etc/containers/storage.conf` are ignored. These fields are: +``` +graphroot="" + container storage graph dir (default: "/var/lib/containers/storage") + Default directory to store all writable content created by container storage programs. + +runroot="" + container storage run dir (default: "/var/run/containers/storage") + Default directory to store all temporary writable content created by container storage programs. +``` +In rootless podman these fields default to +``` +graphroot="$HOME/.local/share/containers/storage" +runroot="$XDG_RUNTIME_DIR/containers" +``` +[$XDG_RUNTIME_DIR](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html#variables) defaults on most systems to `/run/user/$UID`. + +#### registries +Registry configuration is read in by this order +1. `/etc/containers/registries.conf` +2. `/etc/containers/registries.d/*` +3. `HOME/.config/containers/registries.conf` + +The files in the home directory should be used to configure rootless podman for personal needs. These files are not created by default. Users can copy the files from `/usr/share/containers` or `/etc/containers` and modify them. + +#### Authorization files + The default authorization file used by the `podman login` and `podman logout` commands reside in `${XDG_RUNTIME_DIR}/containers/auth.json`. ### Using volumes @@ -152,6 +193,6 @@ Other considerations in regards to volumes: ## 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. +If you are still experiencing problems running Podman in a rootless environment, please refer to the [Shortcomings of Rootless Podman](https://github.com/containers/podman/blob/master/rootless.md) page which lists known issues and solutions to known issues in this environment. For more information on Podman and its subcommands, checkout the asciiart demos on the [README.md](../../README.md#commands) page or the [podman.io](https://podman.io) web site. |