diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/Readme.md | 5 | ||||
| -rw-r--r-- | docs/source/markdown/containers-mounts.conf.5.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman-build.1.md | 39 | ||||
| -rw-r--r-- | docs/source/markdown/podman-create.1.md | 80 | ||||
| -rw-r--r-- | docs/source/markdown/podman-events.1.md | 1 | ||||
| -rw-r--r-- | docs/source/markdown/podman-inspect.1.md | 25 | ||||
| -rw-r--r-- | docs/source/markdown/podman-run.1.md | 59 | ||||
| -rw-r--r-- | docs/source/markdown/podman-search.1.md | 2 | ||||
| -rw-r--r-- | docs/source/markdown/podman.1.md | 2 | ||||
| -rw-r--r-- | docs/tutorials/README.md | 2 |
10 files changed, 151 insertions, 66 deletions
diff --git a/docs/Readme.md b/docs/Readme.md index 12b78d48f..c517052b3 100644 --- a/docs/Readme.md +++ b/docs/Readme.md @@ -50,6 +50,5 @@ 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/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. +so they may investigate how/why the `swagger.yaml` file's CORS-metadata is +incorrect, or the file isn't accessable for some other reason. diff --git a/docs/source/markdown/containers-mounts.conf.5.md b/docs/source/markdown/containers-mounts.conf.5.md index 130c1c523..74492c831 100644 --- a/docs/source/markdown/containers-mounts.conf.5.md +++ b/docs/source/markdown/containers-mounts.conf.5.md @@ -10,7 +10,7 @@ The mounts.conf file specifies volume mount directories that are automatically m The format of the mounts.conf is the volume format `/SRC:/DEST`, one mount per line. For example, a mounts.conf with the line `/usr/share/secrets:/run/secrets` would cause the contents of the `/usr/share/secrets` directory on the host to be mounted on the `/run/secrets` directory inside the container. Setting mountpoints allows containers to use the files of the host, for instance, to use the host's subscription to some enterprise Linux distribution. ## FILES -Some distributions may provide a `/usr/share/containers/mounts.conf` file to provide default mounts, but users can create a `/etc/containers/mounts.conf`, to specify their own special volumes to mount in the container. +Some distributions may provide a `/usr/share/containers/mounts.conf` file to provide default mounts, but users can create a `/etc/containers/mounts.conf`, to specify their own special volumes to mount in the container. When Podman runs in rootless mode, the file `$HOME/.config/containers/mounts.conf` will override the default if it exists. ## HISTORY Aug 2018, Originally compiled by Valentin Rothberg <vrothberg@suse.com> diff --git a/docs/source/markdown/podman-build.1.md b/docs/source/markdown/podman-build.1.md index 821324f84..1e1e1d27e 100644 --- a/docs/source/markdown/podman-build.1.md +++ b/docs/source/markdown/podman-build.1.md @@ -111,17 +111,27 @@ network namespaces can be found. **--cpu-period**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) period +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. -Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-quota**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) quota +Limit the CPU Completely Fair Scheduler (CFS) quota. Limit the container's CPU usage. By default, containers run with the full -CPU resource. This flag tell the kernel to restrict the container's CPU usage -to the quota you specify. +CPU resource. The limit is a number in microseconds. If you provide a number, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-shares**, **-c**=*shares* @@ -374,16 +384,13 @@ not required for Buildah as it supports only Linux. **--pull** -When the flag is enabled, attempt to pull the latest image from the registries -listed in registries.conf if a local image does not exist or the image is newer -than the one in storage. Raise an error if the image is not in any listed -registry and is not present locally. - -If the flag is disabled (with *--pull=false*), do not pull the image from the -registry, unless there is no local image. Raise an error if the image is not -in any registry and is not present locally. +When the option is specified or set to "true", pull the image from the first registry +it is found in as listed in registries.conf. Raise an error if not found in the +registries, even if the image is present locally. -Defaults to *true*. +If the option is disabled (with *--pull=false*), or not specified, pull the image +from the registry only if the image is not present locally. Raise an error if the image +is not found in the registries. **--pull-always** @@ -787,9 +794,9 @@ registries.conf is the configuration file which specifies which container regist ## Troubleshooting -If you are using a useradd command within a Containerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`. This can cause the build to hang forever. Go language does not support sparse files correctly, which can lead to some huge files being created in your container image. +### lastlog sparse file -### Solution +If you are using a useradd command within a Containerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`. This can cause the build to hang forever. Go language does not support sparse files correctly, which can lead to some huge files being created in your container image. If you are using `useradd` within your build script, you should pass the `--no-log-init or -l` option to the `useradd` command. This option tells useradd to stop creating the lastlog file. diff --git a/docs/source/markdown/podman-create.1.md b/docs/source/markdown/podman-create.1.md index 1f229a3a0..e243a5842 100644 --- a/docs/source/markdown/podman-create.1.md +++ b/docs/source/markdown/podman-create.1.md @@ -103,17 +103,27 @@ Write the pid of the `conmon` process to a file. `conmon` runs in a separate pro **--cpu-period**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) period +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. -Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-quota**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) quota +Limit the CPU Completely Fair Scheduler (CFS) quota. Limit the container's CPU usage. By default, containers run with the full -CPU resource. This flag tell the kernel to restrict the container's CPU usage -to the quota you specify. +CPU resource. The limit is a number in microseconds. If you provide a number, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-rt-period**=*microseconds* @@ -169,7 +179,13 @@ PID container CPU CPU share **--cpus**=*number* -Number of CPUs. The default is *0.0* which means no limit. +Number of CPUs. The default is *0.0* which means no limit. This is shorthand +for **--cpu-period** and **--cpu-quota**, so you may only set either +**--cpus** or **--cpu-period** and **--cpu-quota**. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpuset-cpus**=*cpus* @@ -491,7 +507,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`, `tmpfs` and `devpts`. <sup>[[1]](#Footnote1)</sup> +Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup> e.g. @@ -503,33 +519,46 @@ Current supported mount TYPES are `bind`, `volume`, `tmpfs` and `devpts`. <sup>[ type=tmpfs,tmpfs-size=512M,destination=/path/in/container + type=image,source=fedora,destination=/fedora-image,rw=true + type=devpts,destination=/dev/pts Common Options: - · src, source: mount source spec for bind and volume. Mandatory for bind. + · src, source: mount source spec for bind and volume. Mandatory for bind. + + · dst, destination, target: mount destination spec. + + Options specific to volume: - · dst, destination, target: mount destination spec. + · ro, readonly: true or false (default). - · ro, readonly: true or false (default). + Options specific to image: + + · rw, readwrite: true or false (default). Options specific to bind: - · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2). + · ro, readonly: true or false (default). + + · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). - . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. + . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. - . relabel: shared, private. + . relabel: shared, private. Options specific to tmpfs: - · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. + · ro, readonly: true or false (default). + + · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. + + · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. - · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. + · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. - · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default. + · notmpcopyup: Disable copying files from the image to the tmpfs. - · notmpcopyup: Disable copying files from the image to the tmpfs. **--name**=*name* @@ -933,7 +962,7 @@ The _options_ is a comma delimited list and can be: * **rw**|**ro** * **z**|**Z** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** * [**r**]**bind** * [**no**]**exec** * [**no**]**dev** @@ -1019,13 +1048,14 @@ 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. <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 -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. <sup>[[1]](#Footnote1)</sup> +To control mount propagation property of a volume one can use the [**r**]**shared**, +[**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag. +Propagation property can be specified only for bind mounted volumes and not for +internal volumes or named volumes. For mount propagation to work the source mount +point (the 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 point 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 diff --git a/docs/source/markdown/podman-events.1.md b/docs/source/markdown/podman-events.1.md index 0d91cdf17..d0bc3cef8 100644 --- a/docs/source/markdown/podman-events.1.md +++ b/docs/source/markdown/podman-events.1.md @@ -86,6 +86,7 @@ filters are supported: * container=name_or_id * event=event_status (described above) * image=name_or_id + * label=key=value * pod=name_or_id * volume=name_or_id * type=event_type (described above) diff --git a/docs/source/markdown/podman-inspect.1.md b/docs/source/markdown/podman-inspect.1.md index a1dcd1a0e..eb7cf74c6 100644 --- a/docs/source/markdown/podman-inspect.1.md +++ b/docs/source/markdown/podman-inspect.1.md @@ -1,7 +1,7 @@ % podman-inspect(1) ## NAME -podman\-inspect - Display a container or image's configuration +podman\-inspect - Display a container, image, volume, network, or pod's configuration ## SYNOPSIS **podman inspect** [*options*] *name* [...] @@ -9,8 +9,9 @@ podman\-inspect - Display a container or image's configuration ## DESCRIPTION This displays the low-level information on containers and images identified by name or ID. By default, this will render -all results in a JSON array. If the container and image have the same name, this will return container JSON for -unspecified type. If a format is specified, the given template will be executed for each result. +all results in a JSON array. If the inspect type is all, the order of inspection is: containers, images, volumes, network, pods. + So, if a container has the same name as an image, then the container JSON will be returned, and so on. + If a format is specified, the given template will be executed for each result. For more inspection options, see: @@ -25,7 +26,7 @@ For more inspection options, see: **--type**, **-t**=*type* -Return JSON for the specified type. Type can be 'container', 'image' or 'all' (default: all) +Return JSON for the specified type. Type can be 'container', 'image', 'volume', 'network', 'pod', or 'all' (default: all) (Only meaningful when invoked as *podman inspect*) **--format**, **-f**=*format* @@ -38,6 +39,8 @@ The keys of the returned JSON can be used as the values for the --format flag (s Instead of providing the container name or ID, use the last created container. If you use methods other than Podman to run containers such as CRI-O, the last started container could be from either of those methods. +This option can be used to inspect the latest pod created when used with --type pod + The latest option is not supported on the remote client or when invoked as *podman image inspect*. **--size**, **-s** @@ -148,6 +151,20 @@ podman container inspect --latest --format {{.EffectiveCaps}} [CAP_CHOWN CAP_DAC_OVERRIDE CAP_FSETID CAP_FOWNER CAP_MKNOD CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SETFCAP CAP_SETPCAP CAP_NET_BIND_SERVICE CAP_SYS_CHROOT CAP_KILL CAP_AUDIT_WRITE] ``` +``` +# podman inspect myPod --type pod --format "{{.Name}}" +myPod +``` +``` +# podman inspect myVolume --type volume --format "{{.Name}}" +myVolume +``` + +``` +# podman inspect nyNetwork --type network --format "{{.name}}" +myNetwork +``` + ## SEE ALSO podman(1) diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index b86c9b363..0166a344a 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -118,15 +118,27 @@ Write the pid of the **conmon** process to a file. As **conmon** runs in a separ **--cpu-period**=*limit* -Limit the container's CPU usage by setting CPU CFS (Completely Fair Scheduler) period. +Set the CPU period for the Completely Fair Scheduler (CFS), which is a +duration in microseconds. Once the container's CPU quota is used up, it will +not be scheduled to run until the current period ends. Defaults to 100000 +microseconds. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-quota**=*limit* -Limit the CPU CFS (Completely Fair Scheduler) quota. +Limit the CPU Completely Fair Scheduler (CFS) quota. Limit the container's CPU usage. By default, containers run with the full -CPU resource. This flag tell the kernel to restrict the container's CPU usage -to the quota you specify. +CPU resource. The limit is a number in microseconds. If you provide a number, +the container will be allowed to use that much CPU time until the CPU period +ends (controllable via **--cpu-period**). + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpu-rt-period**=*microseconds* @@ -180,7 +192,13 @@ division of CPU shares: **--cpus**=*number* -Number of CPUs. The default is *0.0* which means no limit. +Number of CPUs. The default is *0.0* which means no limit. This is shorthand +for **--cpu-period** and **--cpu-quota**, so you may only set either +**--cpus** or **--cpu-period** and **--cpu-quota**. + +On some systems, changing the CPU limits may not be allowed for non-root +users. For more details, see +https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error **--cpuset-cpus**=*number* @@ -515,7 +533,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**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup> +Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup> e.g. @@ -527,6 +545,8 @@ Current supported mount TYPEs are **bind**, **volume**, **tmpfs** and **devpts** type=tmpfs,tmpfs-size=512M,destination=/path/in/container + type=image,source=fedora,destination=/fedora-image,rw=true + type=devpts,destination=/dev/pts Common Options: @@ -535,11 +555,19 @@ Current supported mount TYPEs are **bind**, **volume**, **tmpfs** and **devpts** · dst, destination, target: mount destination spec. + Options specific to volume: + · ro, readonly: true or false (default). + Options specific to image: + + · rw, readwrite: true or false (default). + Options specific to bind: - · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2). + · ro, readonly: true or false (default). + + · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2). . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. @@ -547,6 +575,8 @@ Current supported mount TYPEs are **bind**, **volume**, **tmpfs** and **devpts** Options specific to tmpfs: + · ro, readonly: true or false (default). + · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. @@ -985,7 +1015,7 @@ The _options_ is a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup> * **rw**|**ro** * **z**|**Z** -* [**r**]**shared**|[**r**]**slave**|[**r**]**private** +* [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable** * [**r**]**bind** * [**no**]**exec** * [**no**]**dev** @@ -1069,12 +1099,13 @@ way mount propagation and that is mounts done on host under that volume 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 -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. <sup>[[1]](#Footnote1)</sup> +[**r**]**slave**, [**r**]**private** or [**r**]**unbindable** propagation flag. +Propagation property can 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. +<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 diff --git a/docs/source/markdown/podman-search.1.md b/docs/source/markdown/podman-search.1.md index fc09d96ea..15a38383a 100644 --- a/docs/source/markdown/podman-search.1.md +++ b/docs/source/markdown/podman-search.1.md @@ -62,7 +62,7 @@ Note: use .Tag only if the --list-tags is set. **--limit**=*limit* -Limit the number of results. This value can be in the range between 1 and 100. The default number of results is 25. +Limit the number of results (default 25). Note: The results from each registry will be limited to this value. Example if limit is 10 and two registries are being searched, the total number of results will be 20, 10 from each (if there are at least 10 matches in each). diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 87337fa3c..2d5110ad9 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -220,7 +220,7 @@ the exit codes follow the `chroot` standard, see below: | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | | [podman-info(1)](podman-info.1.md) | Displays Podman related system information. | | [podman-init(1)](podman-init.1.md) | Initialize one or more containers | -| [podman-inspect(1)](podman-inspect.1.md) | Display a container or image's configuration. | +| [podman-inspect(1)](podman-inspect.1.md) | Display a container, image, volume, network, or pod's configuration. | | [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. | | [podman-load(1)](podman-load.1.md) | Load an image from a container image archive into container storage. | | [podman-login(1)](podman-login.1.md) | Login to a container registry. | diff --git a/docs/tutorials/README.md b/docs/tutorials/README.md index 7f7b4853d..246d235ee 100644 --- a/docs/tutorials/README.md +++ b/docs/tutorials/README.md @@ -12,7 +12,7 @@ Learn how to setup Podman and perform some basic commands with the utility. The steps required to setup rootless Podman are enumerated. -**[Setup Mac/Windows](mac_win_client.md) +**[Setup Mac/Windows](mac_win_client.md)** Special setup for running the Podman remote client on a Mac or Windows PC and connecting to Podman running on a Linux VM are documented. |