diff options
Diffstat (limited to 'docs')
21 files changed, 365 insertions, 308 deletions
diff --git a/docs/MANPAGE_SYNTAX.md b/docs/MANPAGE_SYNTAX.md index c9b677688..553f5d977 100644 --- a/docs/MANPAGE_SYNTAX.md +++ b/docs/MANPAGE_SYNTAX.md @@ -4,7 +4,8 @@ podman\-command - short description ## SYNOPSIS -(Shows the command structure.) +(Shows the command structure. If the command can be written in two different ways, both of them have to be shown.\ +Many manpages include the OPTIONS **--all**, **-a** and/or **--latest**, **-l**. In this case there is no `container name` or `ID` needed after the initial command. Because most of the other OPTIONS still need the `container name` or ` ID`, it is defined that the *container* argument in the command should **not** be put in brackets. It should also be noted in the *IMPORTANT* section in the description of the OPTION with the following sentence: *IMPORTANT: This OPTION does not need a container name or ID as input argument.*.) **podman command** [*optional*] *mandatory value* @@ -16,7 +17,7 @@ podman\-command - short description **podman subcommand command** [*optional*] *value1* | *value2* -(If an optinal value follows a mandatory one.) +(If an optional value follows a mandatory one.) **podman command** [*optional*] *value1* | *value2* [*optional*] @@ -30,26 +31,36 @@ podman\-command - short description ## DESCRIPTION **podman command** is always the beginning of the DESCRIPTION section. Putting the command as the first part of the DESCRIPTION ensures uniformity. All commands mentioned in the text retain their appearance and form.\ -Example sentence: The command **podman command** is an example command. +Example for the first sentence: **podman command** is an example command. Commands or files that are quoted from other podman manpages or podman repositories have to be linked to those. Non-podman commands are not to be linked.\ -Example sentence: You can use **[podman-run](podman-run.1.md)** or **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for the problem. +Example sentence: Use **[podman-run](podman-run.1.md)** or **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for the problem. -It should also be specified if the command can only be run as root. In addition, it should be described when a command, OPTION, or other content cannot be executed with the remote client or in combination with other commands, OPTIONS, or content. In this case, the following sentence is put at the end of a command, OPTION, or content: *IMPORTANT: This option/command/other is not available with the command/OPTION/content/remote Podman client*. For a command, this should be done in the DESCRIPTION section. For the OPTIONS, it should be done in the DESCRIPTION of the specified OPTION. Do not use pronouns in the man pages, especially the word `you`. +It should also be specified if the command can only be run as root. In addition, it should be described when a command, OPTION, or other content cannot be executed with the remote client or in combination with other commands, OPTIONS, or content. In this case, the following sentence is put at the end of a command, OPTION, or content: *IMPORTANT: This OPTION/command/other is not available with the command/OPTION/content/remote Podman client*. For a command, this should be done in the DESCRIPTION section. For the OPTIONS, it should be done in the DESCRIPTION of the specified OPTION. + +Do not use pronouns in the man pages, especially the word `you`. + +There should be **no** new line after H2-headers (`##`). ## OPTIONS All flags are referred to as OPTIONS. The term flags should not be used. All OPTIONS are listed in this section. OPTIONS that appear in descriptions of other OPTIONS and sections retain their appearance, for example: **--exit**. OPTIONS that are quoted from other podman manpages or podman repositories have to be linked to those.\ -Example sentence: You can use **[podman-generate-systemd --new](podman-generate-systemd.1.md#--new)** for the problem. +Example sentence: Use **[podman-generate-systemd --new](./source/markdown/podman-generate-systemd.1.md#--new)** for the problem. + + Each OPTION should be explained to the fullest extent below the OPTION itself. Each OPTION is behind an H4-header (`####`). If the OPTION has a default argument, it has to be explained in the description of the OPTION. If the OPTION is also not available with a command/OPTION/content/remote Podman client, the sentence about the default argument should the second to last sentence. The sentence about the default argument should be in a new line as well as the *IMPORTANT* sentence. - Each OPTION should be explained to the fullest extent below the OPTION itself. Each OPTION is behind an H4-header (`####`). If the OPTION has a default argument, it has to be explained in the description of the OPTION. If the OPTION is also not available with the remote client, the sentence about the default argument should the second to last sentence. + All OPTIONS are to be sorted in alphabetical order. + + Tables should be used when there is a different definition for different arguments and these have to be explained. This is shown with the OPTION **--test**.\ + Lists should be used when arguments are used that do not need a definition for each argument and a single description explains them. An example is shown with **[podman-commit --change](./source/markdown/podman-commit.1.md#--change--cinstruction)** #### **--version**, **-v** -OPTIONS can be put after the command in two different ways. Eather the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front.\ -Example: The default is **false**. *IMPORTANT: This option is not available with the remote Podman client*. +OPTIONS can be put after the command in two different ways. Either the long version with **--option** or as the short version **-o**. If there are two ways to write an OPTION they are separated by a comma. If there are two versions of one command the long version is always shown in front. If the arguments behind the OPTION are boolean, it is not shown behind the OPTION itself. The default boolean argument is shown in the same way normal default arguments are displayed.\ +Example: The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client.* #### **--exit** @@ -57,15 +68,17 @@ An example of an OPTION that has only one possible structure. Thus, it cannot be #### **--answer**=, **-a**=**active** | *disable* -The "answer" option above is an example of an OPTION that accepts two possible arguments as inputs. If there is a default argument that is selected when the OPTION is not used in the command, it is shown in **bold**. If the OPTION is used it must include an argument afterwards. It must always be ensured that the standard argument is in the first position after the OPTION. In this example, there are two different ways to execute the command. Both possible OPTIONS have to be shown with the arguments following them. The default value is shown as **active**. +The **--answer** OPTION above is an example of an OPTION that accepts two possible arguments as inputs. If there is a default argument that is selected when the OPTION is not used in the command, it is shown in **bold**. If the OPTION is used it must include an argument afterwards. It must always be ensured that the standard argument is in the first position after the OPTION. In this example, there are two different ways to execute the command. Both possible OPTIONS have to be shown with the arguments following them.\ +The default value is shown as **active**. #### **--status**=**good** | *better* | *best* -This is an example of three arguments following an OPTION. If the number of arguments is greater than three, the arguments are **not** listed after the equal sign. The arguments have to be shown in a table like in **--test**=**_test_**, regardless of the number of arguments. The default value is shown as **good**. +This is an example of three arguments following an OPTION. If the number of arguments is greater than three, the arguments are **not** listed after the equal sign. The arguments have to be shown in a table like in **--test**=**_test_**. This form should also be used if the understanding of the content is in danger of becoming incomprehensible. An example for this is **[podman-container-prune --filters](./source/markdown/podman-container-prune.1.md#--filterfilters)**.\ +The default value is shown as **good**. #### **--test**=**test** -OPTIONS that are followed by an equal sign include an argument after the equal sign in **bold**. If there is a default argument, that is used if the OPTION is not specified in the command, the argument after the eqaul sign is displayed in **bold**. All arguments must be listed and explained in the text below the OPTION. +OPTIONS that are followed by an equal sign include an argument after the equal sign in **bold** or *italic*. If there is a default argument, that is used if the OPTION is not specified in the command, the argument after the equal sign is displayed in **bold**. All arguments must be listed and explained in the text below the OPTION. | Argument | Description | | ------------------ | --------------------------------------------------------------------------- | @@ -75,8 +88,8 @@ OPTIONS that are followed by an equal sign include an argument after the equal s | *example four* | Example: Can be combined with **--exit**. | | *example five* | The fifth description | -The table shows an example for a listing of arguments. The contents in the table should be aligned left. If the content in the table conflicts with this, it can be aligned in a way that supports the understanding of the content. If there is a default argument, it **must** listed as the first entry in the table. The default value is shown as **example one**. - +The table shows an example for a listing of arguments. The contents in the table should be aligned left. If the content in the table conflicts with this, it can be aligned in a way that supports the understanding of the content. If there is a default argument, it **must** listed as the first entry in the table.\ +The default value is shown as **example one**. If the number of arguments is smaller than four they have to be listed behind the OPTION as seen in the OPTION **--status**. @@ -102,18 +115,26 @@ All EXAMPLES are listed in this section. This section should be at the end of ea Description of the EXAMPLE ``` +### Example comment $ podman command - $ podman command -o - $ cat $HOME/Dockerfile | podman command --option ``` Description of the EXAMPLE two ``` -$ podman command --redhat +# podman command --status=better +``` +## SEE ALSO +All commands, including commands with OPTIONS, and config-files mentioned in the manpage have to be listed here. Podman commands, including commands with OPTIONS, and config-files have to be linked. If a command is mentioned several times with different OPTIONS it just have to be linked once. All other commands, including commands with OPTIONS, and config-files just have to be mentioned. If a command is mentioned several times with different OPTIONS it just has to be linked once. -$ podman command --redhat better +Example: +**[podman(1)](podman.1.md)**, **[podman-run(1)](podman-run.1.md)**, **[podman-create(1)](podman-create.1.md)** -$ podman command --redhat=better -``` +## HISTORY +Normally, the dates of changes, the content of the changes and the person who provided them is listed here. Most manpages don't keep this record. + +Example:\ +December 2021, Originally compiled by Alexander Richter <example@redhat.com> + +`A new line is needed of the end of every manpage.` diff --git a/docs/source/markdown/podman-attach.1.md b/docs/source/markdown/podman-attach.1.md index 092772916..b86b981d2 100644 --- a/docs/source/markdown/podman-attach.1.md +++ b/docs/source/markdown/podman-attach.1.md @@ -10,17 +10,19 @@ podman\-attach - Attach to a running container ## DESCRIPTION **podman attach** attaches to a running *container* using the *container's name* or *ID*, to either view its ongoing output or to control it interactively.\ -The *container* can detached from (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 `containers.conf` file: see **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. +The *container* can detached from (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 `containers.conf` file: see **[containers.conf(5)](https://github.com/containers/common/blob/master/docs/containers.conf.5.md)** for more information. ## OPTIONS #### **--detach-keys**=**sequence** -Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is `ctrl-p,ctrl-q`. +Specify the key **sequence** for detaching a *container*. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature.\ +The default is `ctrl-p,ctrl-q`. #### **--latest**, **-l** -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. The default is **false**.\ -*IMPORTANT: This option is not available with the remote Podman client* +Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.* #### **--no-stdin** @@ -28,10 +30,10 @@ Do not attach STDIN. The default is **false**. #### **--sig-proxy** -Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is **true**. +Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied.\ +The default is **true**. ## EXAMPLES - Attach to a container called "foobar". ``` $ podman attach foobar diff --git a/docs/source/markdown/podman-auto-update.1.md b/docs/source/markdown/podman-auto-update.1.md index 52a9a3fec..24b910470 100644 --- a/docs/source/markdown/podman-auto-update.1.md +++ b/docs/source/markdown/podman-auto-update.1.md @@ -9,8 +9,7 @@ podman\-auto-update - Auto update containers according to their auto-update poli ## DESCRIPTION **podman auto-update** looks up containers with a specified `io.containers.autoupdate` label (i.e., the auto-update policy). -If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. -The label `image` is an alternative to `registry` maintained for backwards compatibility. +If the label is present and set to `registry`, Podman reaches out to the corresponding registry to check if the image has been updated. The label `image` is an alternative to `registry` maintained for backwards compatibility. An image is considered updated if the digest in the local storage is different than the one of the remote image. If an image must be updated, Podman pulls it down and restarts the systemd unit executing the container. @@ -35,7 +34,6 @@ Systemd units that start and stop a container cannot run a new image. Podman ships with a `podman-auto-update.service` systemd unit. This unit is triggered daily at midnight by the `podman-auto-update.timer` systemd timer. The timer can be altered for custom time-based updates if desired. The unit can further be invoked by other systemd units (e.g., via the dependency tree) or manually via **systemctl start podman-auto-update.service**. ## OPTIONS - #### **--authfile**=*path* Path of the authentication file. Default is `${XDG_RUNTIME_DIR}/containers/auth.json`, which is set using **[podman login](podman-login.1.md)**. @@ -44,7 +42,6 @@ If the authorization state is not found there, `$HOME/.docker/config.json` is ch Note: There is also the option to override the default path of the authentication file by setting the `REGISTRY_AUTH_FILE` environment variable. This can be done with **export REGISTRY_AUTH_FILE=_path_**. ## EXAMPLES - Autoupdate with registry policy ``` diff --git a/docs/source/markdown/podman-commit.1.md b/docs/source/markdown/podman-commit.1.md index 92574cdc5..87b7e8aea 100644 --- a/docs/source/markdown/podman-commit.1.md +++ b/docs/source/markdown/podman-commit.1.md @@ -15,7 +15,6 @@ If `image` does not begin with a registry name component, `localhost` will be ad If `image` is not provided, the values for the `REPOSITORY` and `TAG` values of the created image will each be set to `<none>`. ## OPTIONS - #### **--author**, **-a**=*author* Set the author for the committed image. @@ -23,13 +22,24 @@ Set the author for the committed image. #### **--change**, **-c**=*instruction* Apply the following possible instructions to the created image: -**CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **ONBUILD** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR** + +- *CMD* +- *ENTRYPOINT* +- *ENV* +- *EXPOSE* +- *LABEL* +- *ONBUILD* +- *STOPSIGNAL* +- *USER* +- *VOLUME* +- *WORKDIR* Can be set multiple times. #### **--format**, **-f** =**oci** | *docker* -Set the format of the image manifest and metadata. The currently supported formats are **oci** and *docker*. The default is **oci**. +Set the format of the image manifest and metadata. The currently supported formats are **oci** and *docker*.\ +The default is **oci**. #### **--iidfile**=*ImageIDfile* @@ -37,7 +47,8 @@ Write the image ID to the file. #### **--include-volumes** -Include in the committed image any volumes added to the container by the **--volume** or **--mount** OPTIONS to the **[podman create](podman-create.1.md)** and **[podman run](podman-run.1.md)** commands. The default is **false**. +Include in the committed image any volumes added to the container by the **--volume** or **--mount** OPTIONS to the **[podman create](podman-create.1.md)** and **[podman run](podman-run.1.md)** commands.\ +The default is **false**. #### **--message**, **-m**=*message* @@ -46,14 +57,15 @@ Set commit message for committed image.\ #### **--pause**, **-p** -Pause the container when creating an image. The default is **false**. +Pause the container when creating an image.\ +The default is **false**. #### **--quiet**, **-q** -Suppresses output. The default is **false**. +Suppresses output.\ +The default is **false**. ## EXAMPLES - Create image from container with entrypoint and label ``` $ podman commit --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change "LABEL blue=image" reverent_golick image-committed diff --git a/docs/source/markdown/podman-completion.1.md b/docs/source/markdown/podman-completion.1.md index 4ebe4e2e1..639332365 100644 --- a/docs/source/markdown/podman-completion.1.md +++ b/docs/source/markdown/podman-completion.1.md @@ -4,60 +4,61 @@ podman\-completion - Generate shell completion scripts ## SYNOPSIS -**podman completion** [*options*] *bash*|*zsh*|*fish*|*powershell* +**podman completion** [*options*] *bash* | *zsh* | *fish* | *powershell* ## DESCRIPTION -The completion command generates shell completion scripts for a variety of shells. Supported shells are **bash**, **zsh**, **fish** and **powershell**. +**podman completion** generates shell completion scripts for a variety of shells. Supported shells are *bash*, *zsh*, *fish* and *powershell*. -These script are used by the shell to provide suggestions and complete commands when you are typing the command and press [TAB]. +These script are used by the shell to provide suggestions and complete commands when the command is typed and `[TAB]` is pressed. Usually these scripts are automatically installed via the package manager. ## OPTIONS -#### **--file**, **-f** +#### **--file**, **-f**=*file* -Write the generated output to file. +Write the generated output to a file. #### **--no-desc** -Do not provide description in the completions. +Do not provide description in the completions.\ +The default is **false**. ## Installation ### BASH -Make sure you have `bash-completion` installed on the system. +`bash-completion` has to be installed on the system. -To load the completion script into the current session run: -`source <(podman completion bash)` +To load the completion script into the current session run:\ +**source <(podman completion bash)**. -To make it available for all bash sessions run: -`podman completion bash -f /etc/bash_completion.d/podman` +To make it available for all bash sessions run:\ +**podman completion -f /etc/bash_completion.d/podman bash**. ### ZSH -If shell completion is not already enabled in the environment you will need to enable it. You can execute the following once: -`echo "autoload -U compinit; compinit" >> ~/.zshrc` +Shell completion needs to be already enabled in the environment. The following can be executed:\ +**echo "autoload -U compinit; compinit" >> ~/.zshrc** -To make it available for all zsh sessions run: -`podman completion zsh -f "${fpath[1]}/_podman"` +To make it available for all zsh sessions run:\ +**podman completion -f "${fpath[1]}/_podman zsh"** -Once you reload the shell the auto-completion should be working. +Once the shell is reloaded the auto-completion should be working. ### FISH To load the completion script into the current session run: -`podman completion fish | source` +**podman completion fish | source** To make it available for all fish sessions run: -`podman completion fish -f ~/.config/fish/completions/podman.fish` +**podman completion -f ~/.config/fish/completions/podman.fish fish** ### POWERSHELL To load the completion script into the current session run: -`podman.exe completion powershell | Out-String | Invoke-Expression` +**podman.exe completion powershell | Out-String | Invoke-Expression** To make it available in all powershell sessions that a user has, write the completion output to a file and source that to the user's powershell profile. -More information about profiles is available with `Get-Help about_Profiles`. +More information about profiles is available with **Get-Help about_Profiles**. ## SEE ALSO -[podman(1)](podman.1.md) +**[podman(1)](podman.1.md)**, zsh(1), fish(1), powershell(1) diff --git a/docs/source/markdown/podman-container-checkpoint.1.md b/docs/source/markdown/podman-container-checkpoint.1.md index 271a44c9d..56fd848ac 100644 --- a/docs/source/markdown/podman-container-checkpoint.1.md +++ b/docs/source/markdown/podman-container-checkpoint.1.md @@ -4,96 +4,109 @@ podman\-container\-checkpoint - Checkpoints one or more running containers ## SYNOPSIS -**podman container checkpoint** [*options*] *container* ... +**podman container checkpoint** [*options*] *container* [*container* ...] ## DESCRIPTION -Checkpoints all the processes in one or more containers. You may use container IDs or names as input. +**podman container checkpoint** checkpoints all the processes in one or more *containers*. A *container* can be restored from a checkpoint with **[podman-container-restore](podman-container-restore.1.md)**. The *container IDs* or *names* are used as input. ## OPTIONS #### **--all**, **-a** -Checkpoint all running containers. +Checkpoint all running *containers*.\ +The default is **false**.\ +*IMPORTANT: This OPTION does not need a container name or ID as input argument.* -#### **--compress**, **-c** +#### **--compress**, **-c**=**zstd** | *none* | *gzip* Specify the compression algorithm used for the checkpoint archive created -with the **--export, -e** option. Possible algorithms are *gzip*, *none* -and *zstd*. If no compression algorithm is specified Podman will use -*zstd*. - +with the **--export, -e** OPTION. Possible algorithms are **zstd**, *none* +and *gzip*.\ One possible reason to use *none* is to enable faster creation of checkpoint archives. Not compressing the checkpoint archive can result in faster checkpoint -archive creation. - -``` -# podman container checkpoint -l --compress=none --export=dump.tar -# podman container checkpoint -l --compress=gzip --export=dump.tar.gz -``` +archive creation.\ +The default is **zstd**. -#### **--export**, **-e** +#### **--export**, **-e**=*archive* Export the checkpoint to a tar.gz file. The exported checkpoint can be used -to import the container on another system and thus enabling container live -migration. This checkpoint archive also includes all changes to the container's -root file-system, if not explicitly disabled using **--ignore-rootfs** +to import the *container* on another system and thus enabling container live +migration. This checkpoint archive also includes all changes to the *container's* +root file-system, if not explicitly disabled using **--ignore-rootfs**. #### **--ignore-rootfs** -This only works in combination with **--export, -e**. If a checkpoint is -exported to a tar.gz file it is possible with the help of **--ignore-rootfs** -to explicitly disable including changes to the root file-system into -the checkpoint archive file. +If a checkpoint is exported to a tar.gz file it is possible with the help of **--ignore-rootfs** to explicitly disable including changes to the root file-system into the checkpoint archive file.\ +The default is **false**.\ +*IMPORTANT: This OPTION only works in combination with **--export, -e**.* #### **--ignore-volumes** -This option must be used in combination with the **--export, -e** option. -When this option is specified, the content of volumes associated with -the container will not be included into the checkpoint tar.gz file. +This OPTION must be used in combination with the **--export, -e** OPTION. +When this OPTION is specified, the content of volumes associated with +the *container* will not be included into the checkpoint tar.gz file.\ +The default is **false**. #### **--keep**, **-k** -Keep all temporary log and statistics files created by CRIU during checkpointing. These files -are not deleted if checkpointing fails for further debugging. If checkpointing succeeds these -files are theoretically not needed, but if these files are needed Podman can keep the files -for further analysis. +Keep all temporary log and statistics files created by CRIU during checkpointing. These files are not deleted if checkpointing fails for further debugging. If checkpointing succeeds these files are theoretically not needed, but if these files are needed Podman can keep the files for further analysis.\ +The default is **false**. #### **--latest**, **-l** -Instead of providing the container name or ID, checkpoint the last created container. (This option is not available with the remote Podman client) +Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.* #### **--leave-running**, **-R** -Leave the container running after checkpointing instead of stopping it. +Leave the *container* running after checkpointing instead of stopping it.\ +The default is **false**. #### **--pre-checkpoint**, **-P** -Dump the container's memory information only, leaving the container running. Later -operations will supersede prior dumps. It only works on runc 1.0-rc3 or higher. +Dump the *container's* memory information only, leaving the *container* running. Later +operations will supersede prior dumps. It only works on `runc 1.0-rc3` or `higher`.\ +The default is **false**. #### **--tcp-established** -Checkpoint a container with established TCP connections. If the checkpoint -image contains established TCP connections, this options is required during -restore. Defaults to not checkpointing containers with established TCP -connections. +Checkpoint a *container* with established TCP connections. If the checkpoint +image contains established TCP connections, this OPTION is required during +restore. Defaults to not checkpointing *containers* with established TCP +connections.\ +The default is **false**. #### **--with-previous** -Check out the container with previous criu image files in pre-dump. It only works -without **--pre-checkpoint** or **-P**. It only works on runc 1.0-rc3 or higher. +Check out the *container* with previous criu image files in pre-dump. It only works on `runc 1.0-rc3` or `higher`.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with **--pre-checkpoint***. -## EXAMPLE -podman container checkpoint mywebserver +## EXAMPLES +Make a checkpoint for the container "mywebserver". +``` +# podman container checkpoint mywebserver +``` -podman container checkpoint 860a4b23 +Dumps the container's memory information of the latest container into an archive. +``` +# podman container checkpoint -P -e pre-checkpoint.tar.gz -l +``` -podman container checkpoint -P -e pre-checkpoint.tar.gz -l +Keep the container's memory information from an older dump and add the new container's memory information. +``` +# podman container checkpoint --with-previous -e checkpoint.tar.gz -l +``` -podman container checkpoint --with-previous -e checkpoint.tar.gz -l +Dump the container's memory information of the latest container into an archive with the specified compress method. +``` +# podman container checkpoint -l --compress=none --export=dump.tar +# podman container checkpoint -l --compress=gzip --export=dump.tar.gz +``` ## SEE ALSO -podman(1), podman-container-restore(1) +**[podman(1)](podman.1.md)**, **[podman-container-restore(1)](podman-container-restore.1.md)** ## HISTORY September 2018, Originally compiled by Adrian Reber <areber@redhat.com> diff --git a/docs/source/markdown/podman-container-cleanup.1.md b/docs/source/markdown/podman-container-cleanup.1.md index 19d0b7818..29e34f1cf 100644 --- a/docs/source/markdown/podman-container-cleanup.1.md +++ b/docs/source/markdown/podman-container-cleanup.1.md @@ -4,51 +4,54 @@ podman\-container\-cleanup - Cleanup the container's network and mountpoints ## SYNOPSIS -**podman container cleanup** [*options*] *container* +**podman container cleanup** [*options*] *container* [*container* ...] ## DESCRIPTION -**podman container cleanup** cleans up exited containers by removing all mountpoints and network configuration from the host. The container name or ID can be used. The cleanup command does not remove the containers. Running containers will not be cleaned up. -Sometimes container's mount points and network stacks can remain if the podman command was killed or the container ran in daemon mode. This command is automatically executed when you run containers in daemon mode by the conmon process when the container exits. +**podman container cleanup** cleans up exited *containers* by removing all mountpoints and network configuration from the host. The *container name* or *ID* can be used. The cleanup command does not remove the *containers*. Running *containers* will not be cleaned up.\ +Sometimes container mount points and network stacks can remain if the podman command was killed or the *container* ran in daemon mode. This command is automatically executed when *containers* are run in daemon mode by the `conmon process` when the *container* exits. ## OPTIONS - #### **--all**, **-a** -Cleanup all containers. +Cleanup all *containers*.\ +The default is **false**.\ +*IMPORTANT: This OPTION does not need a container name or ID as input argument.* -#### **--exec**=_session_ +#### **--exec**=*session* -Clean up an exec session for a single container. -Can only be specified if a single container is being cleaned up (conflicts with **--all** as such). -If **--rm** is not specified, temporary files for the exec session will be cleaned up; if it is, the exec session will be removed from the container. -Conflicts with **--rmi** as the container is not being cleaned up so the image cannot be removed. +Clean up an exec session for a single *container*. +Can only be specified if a single *container* is being cleaned up (conflicts with **--all** as such). If **--rm** is not specified, temporary files for the exec session will be cleaned up; if it is, the exec session will be removed from the *container*.\ +*IMPORTANT: Conflicts with **--rmi** as the container is not being cleaned up so the image cannot be removed.* #### **--latest**, **-l** -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 is not available with the remote Podman client) + +Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.* #### **--rm** -After cleanup, remove the container entirely. +After cleanup, remove the *container* entirely.\ +The default is **false**. #### **--rmi** -After cleanup, remove the image entirely. - -## EXAMPLE - -`podman container cleanup mywebserver` - -`podman container cleanup mywebserver myflaskserver 860a4b23` - -`podman container cleanup 860a4b23` +After cleanup, remove the image entirely.\ +The default is **false**. -`podman container cleanup -a` +## EXAMPLES +Cleanup the container "mywebserver". +``` +$ podman container cleanup mywebserver +``` -`podman container cleanup --latest` +Cleanup the containers with the names "mywebserver", "myflaskserver", "860a4b23". +``` +$ podman container cleanup mywebserver myflaskserver 860a4b23 +``` ## SEE ALSO -**podman**(1), **podman-container**(1), **conmon**(8). +**[podman(1)](podman.1.md)**, **[podman-container(1)](podman-container.1.md)**, conmon(8) ## HISTORY Jun 2018, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/markdown/podman-container-exists.1.md b/docs/source/markdown/podman-container-exists.1.md index 381d968ab..d059276d7 100644 --- a/docs/source/markdown/podman-container-exists.1.md +++ b/docs/source/markdown/podman-container-exists.1.md @@ -1,42 +1,43 @@ % podman-container-exists(1) ## NAME -podman-container-exists - Check if a container exists in local storage +podman\-container\-exists - Check if a container exists in local storage ## SYNOPSIS **podman container exists** [*options*] *container* ## DESCRIPTION -**podman container exists** checks if a container exists in local storage. The **ID** or **Name** -of the container may be used as input. Podman will return an exit code -of `0` when the container is found. A `1` will be returned otherwise. An exit code of `125` indicates there -was an issue accessing the local storage. +**podman container exists** checks if a container exists in local storage. The *container ID* or *name* is used as input. Podman will return an exit code +of `0` when the container is found. A `1` will be returned otherwise. An exit code of `125` indicates there was an issue accessing the local storage. ## OPTIONS +#### **--external** -#### **--external**=*true|false* -Check for external containers as well as Podman containers. These external containers are generally created via other container technology such as Buildah or CRI-O. +Check for external *containers* as well as Podman *containers*. These external *containers* are generally created via other container technology such as `Buildah` or `CRI-O`.\ +The default is **false**. **-h**, **--help** -Print usage statement + +Prints usage statement.\ +The default is **false**. ## EXAMPLES -Check if an container called `webclient` exists in local storage (the container does actually exist). +Check if an container called "webclient" exists in local storage. Here, the container does exist. ``` $ podman container exists webclient $ echo $? 0 ``` -Check if an container called `webbackend` exists in local storage (the container does not actually exist). +Check if an container called "webbackend" exists in local storage. Here, the container does not exist. ``` $ podman container exists webbackend $ echo $? 1 ``` -Check if an container called `ubi8-working-container` created via Buildah exists in local storage (the container does not actually exist). +Check if an container called "ubi8-working-container" created via Buildah exists in local storage. Here, the container does not exist. ``` $ podman container exists --external ubi8-working-container $ echo $? @@ -44,7 +45,7 @@ $ echo $? ``` ## SEE ALSO -podman(1) +**[podman(1)](podman.1.md)** ## HISTORY -November 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) +November 2018, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/markdown/podman-container-prune.1.md b/docs/source/markdown/podman-container-prune.1.md index b199f9ebb..06014897f 100644 --- a/docs/source/markdown/podman-container-prune.1.md +++ b/docs/source/markdown/podman-container-prune.1.md @@ -1,7 +1,7 @@ % podman-container-prune(1) ## NAME -podman-container-prune - Remove all stopped containers from local storage +podman\-container\-prune - Remove all stopped containers from local storage ## SYNOPSIS **podman container prune** [*options*] @@ -10,35 +10,37 @@ podman-container-prune - Remove all stopped containers from local storage **podman container prune** removes all stopped containers from local storage. ## OPTIONS - #### **--filter**=*filters* Provide filter values. -The --filter flag format is of “key=value”. If there is more than one filter, then pass multiple flags (e.g., --filter "foo=bar" --filter "bif=baz") +The *filters* argument format is of `key=value`. If there is more than one *filter*, then pass multiple OPTIONS: **--filter** *foo=bar* **--filter** *bif=baz*. Supported filters: -- `until` (_timestamp_) - only remove containers and images created before given timestamp -- `label` (label=_key_, label=_key=value_, label!=_key_, or label!=_key=value_) - only remove containers and images, with (or without, in case label!=... is used) the specified labels. +| Filter | Description | +| :----------------: | --------------------------------------------------------------------------- | +| *until* | Only remove containers and images created before given timestamp. | +| *label* | Only remove containers and images, with (or without, in case label!=[...] is used) the specified labels. | -The until filter can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. +The `until` *filter* can be Unix timestamps, date formatted timestamps, or Go duration strings (e.g. 10m, 1h30m) computed relative to the machine’s time. -The label filter accepts two formats. One is the label=... (label=_key_ or label=_key=value_), which removes containers with the specified labels. The other format is the label!=... (label!=_key_ or label!=_key=value_), which removes containers without the specified labels. +The `label` *filter* accepts two formats. One is the `label`=*key*, `label`=*key*=*value*, which removes containers with the specified labels. The other format is the `label!`=*key*, or `label!`=*key*=*value*, which removes containers without the specified labels. #### **--force**, **-f** -Do not provide an interactive prompt for container removal. +Do not provide an interactive prompt for container removal.\ +The default is **false**. **-h**, **--help** -Print usage statement +Print usage statement.\ +The default is **false**. ## EXAMPLES - Remove all stopped containers from local storage ``` -$ sudo podman container prune +$ podman container prune WARNING! This will remove all stopped containers. Are you sure you want to continue? [y/N] y 878392adf2e6c5c9bb1fc19b69d37d2e98c8abf9d539c0bce4b15b46bbcce471 @@ -51,7 +53,7 @@ fff1c5b6c3631746055ec40598ce8ecaa4b82aef122f9e3a85b03b55c0d06c23 Remove all stopped containers from local storage without confirmation. ``` -$ sudo podman container prune -f +$ podman container prune -f 878392adf2e6c5c9bb1fc19b69d37d2e98c8abf9d539c0bce4b15b46bbcce471 37664467fbe3618bf9479c34393ac29c02696675addf1750f9e346581636cde7 ed0c6468b8e1cb641b4621d1fe30cb477e1fefc5c0bceb66feaf2f7cb50e5962 @@ -63,15 +65,15 @@ fff1c5b6c3631746055ec40598ce8ecaa4b82aef122f9e3a85b03b55c0d06c23 Remove all stopped containers from local storage created within last 10 minutes ``` -$ sudo podman container prune --filter until="10m" +$ podman container prune --filter until="10m" WARNING! This will remove all stopped containers. Are you sure you want to continue? [y/N] y 3d366295e33d8cc612c4d873199bacadd55088d90d17dcafaa9a2d317ad50b4e ``` ## SEE ALSO -podman(1), podman-ps +**[podman(1)](podman.1.md)**, **[podman-ps](podman-ps.1.md)** ## HISTORY -December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) -December 2020, converted filter information from docs.docker.com documentation by Dan Walsh (dwalsh at redhat dot com) +December 2018, Originally compiled by Brent Baude <bbaude@redhat.com>\ +December 2020, converted filter information from docs.docker.com documentation by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/markdown/podman-container-restore.1.md b/docs/source/markdown/podman-container-restore.1.md index 82bf76d1e..21021b952 100644 --- a/docs/source/markdown/podman-container-restore.1.md +++ b/docs/source/markdown/podman-container-restore.1.md @@ -4,120 +4,131 @@ podman\-container\-restore - Restores one or more containers from a checkpoint ## SYNOPSIS -**podman container restore** [*options*] *container* ... +**podman container restore** [*options*] *container* [*container* ...] ## DESCRIPTION -Restores a container from a checkpoint. You may use container IDs or names as input. +**podman container restore** restores a container from a checkpoint. The *container IDs* or *names* are used as input. ## OPTIONS +#### **--all**, **-a** + +Restore all checkpointed *containers*.\ +The default is **false**.\ +*IMPORTANT: This OPTION does not need a container name or ID as input argument.* + #### **--keep**, **-k** -Keep all temporary log and statistics files created by CRIU during +Keep all temporary log and statistics files created by `CRIU` during checkpointing as well as restoring. These files are not deleted if restoring fails for further debugging. If restoring succeeds these files are theoretically not needed, but if these files are needed Podman can keep the files for further analysis. This includes the checkpoint directory with all files created during checkpointing. The size required by the checkpoint directory is roughly the same as the amount of memory required by the -processes in the checkpointed container. - -Without the **-k**, **--keep** option the checkpoint will be consumed and cannot be used -again. - -#### **--all**, **-a** - -Restore all checkpointed containers. +processes in the checkpointed *container*.\ +Without the **--keep**, **-k** option the checkpoint will be consumed and cannot be used again.\ +The default is **false**. #### **--latest**, **-l** -Instead of providing the container name or ID, restore the last created container. (This option is not available with the remote Podman client) - -#### **--tcp-established** - -Restore a container with established TCP connections. If the checkpoint image -contains established TCP connections, this option is required during restore. -If the checkpoint image does not contain established TCP connections this -option is ignored. Defaults to not restoring containers with established TCP -connections. - -#### **--import**, **-i** - -Import a checkpoint tar.gz file, which was exported by Podman. This can be used -to import a checkpointed container from another host. Do not specify a *container* -argument when using this option. - -#### **--import-previous** - -Import a pre-checkpoint tar.gz file which was exported by Podman. This option -must be used with **-i** or **--import**. It only works on runc 1.0-rc3 or higher. - -#### **--name**, **-n** - -This is only available in combination with **--import, -i**. If a container is restored -from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This -way it is possible to restore a container from a checkpoint multiple times with different -names. - -If the **--name, -n** option is used, Podman will not attempt to assign the same IP -address to the container it was using before checkpointing as each IP address can only -be used once and the restored container will have another IP address. This also means -that **--name, -n** cannot be used in combination with **--tcp-established**. +Instead of providing the *container ID* or *name*, use the last created *container*. If other methods than Podman are used to run *containers* such as `CRI-O`, the last started *container* could be from either of those methods.\ +The default is **false**.\ +*IMPORTANT: This OPTION is not available with the remote Podman client. This OPTION does not need a container name or ID as input argument.* #### **--ignore-rootfs** -This is only available in combination with **--import, -i**. If a container is restored -from a checkpoint tar.gz file it is possible that it also contains all root file-system -changes. With **--ignore-rootfs** it is possible to explicitly disable applying these -root file-system changes to the restored container. +If a *container* is restored from a checkpoint tar.gz file it is possible that it also contains all root file-system changes. With **--ignore-rootfs** it is possible to explicitly disable applying these root file-system changes to the restored *container*.\ +The default is **false**.\ +*IMPORTANT: This OPTION is only available in combination with **--import, -i**.* #### **--ignore-static-ip** -If the container was started with **--ip** the restored container also tries to use that +If the *container* was started with **--ip** the restored *container* also tries to use that IP address and restore fails if that IP address is already in use. This can happen, if -a container is restored multiple times from an exported checkpoint with **--name, -n**. +a *container* is restored multiple times from an exported checkpoint with **--name, -n**. Using **--ignore-static-ip** tells Podman to ignore the IP address if it was configured -with **--ip** during container creation. +with **--ip** during *container* creation. + +The default is **false**. #### **--ignore-static-mac** -If the container was started with **--mac-address** the restored container also +If the *container* was started with **--mac-address** the restored *container* also tries to use that MAC address and restore fails if that MAC address is already -in use. This can happen, if a container is restored multiple times from an +in use. This can happen, if a *container* is restored multiple times from an exported checkpoint with **--name, -n**. Using **--ignore-static-mac** tells Podman to ignore the MAC address if it was -configured with **--mac-address** during container creation. +configured with **--mac-address** during *container* creation. + +The default is **false**. #### **--ignore-volumes** This option must be used in combination with the **--import, -i** option. -When restoring containers from a checkpoint tar.gz file with this option, -the content of associated volumes will not be restored. +When restoring *containers* from a checkpoint tar.gz file with this option, +the content of associated volumes will not be restored.\ +The default is **false**. -#### **--publish**, **-p** +#### **--import**, **-i**=*file* -Replaces the ports that the container publishes, as configured during the -initial container start, with a new set of port forwarding rules. +Import a checkpoint tar.gz file, which was exported by Podman. This can be used +to import a checkpointed *container* from another host.\ +*IMPORTANT: This OPTION does not need a container name or ID as input argument.* -``` -# podman run --rm -p 2345:80 -d webserver -# podman container checkpoint -l --export=dump.tar -# podman container restore -p 5432:8080 --import=dump.tar -``` +#### **--import-previous**=*file* -For more details please see **podman run --publish**. +Import a pre-checkpoint tar.gz file which was exported by Podman. This option +must be used with **-i** or **--import**. It only works on `runc 1.0-rc3` or `higher`. -## EXAMPLE +#### **--name**, **-n**=*name* + +If a *container* is restored from a checkpoint tar.gz file it is possible to rename it with **--name, -n**. This way it is possible to restore a *container* from a checkpoint multiple times with different +names. + +If the **--name, -n** option is used, Podman will not attempt to assign the same IP +address to the *container* it was using before checkpointing as each IP address can only +be used once and the restored *container* will have another IP address. This also means +that **--name, -n** cannot be used in combination with **--tcp-established**.\ +*IMPORTANT: This OPTION is only available in combination with **--import, -i**.* + +#### **--publish**, **-p**=*port* + +Replaces the ports that the *container* publishes, as configured during the +initial *container* start, with a new set of port forwarding rules. + +For more details please see **[podman run --publish](podman-run.1.md#--publish)**. + +#### **--tcp-established** -podman container restore mywebserver +Restore a *container* with established TCP connections. If the checkpoint image +contains established TCP connections, this option is required during restore. +If the checkpoint image does not contain established TCP connections this +option is ignored. Defaults to not restoring *containers* with established TCP +connections.\ +The default is **false**. -podman container restore 860a4b23 +## EXAMPLE +Restores the container "mywebserver". +``` +# podman container restore mywebserver +``` -podman container restore --import-previous pre-checkpoint.tar.gz --import checkpoint.tar.gz +Import a checkpoint file and a pre-checkpoint file. +``` +# podman container restore --import-previous pre-checkpoint.tar.gz --import checkpoint.tar.gz +``` + +Remove the container "mywebserver". Make a checkpoint of the container and export it. Restore the container with other port ranges from the exported file. +``` +$ podman run --rm -p 2345:80 -d webserver +# podman container checkpoint -l --export=dump.tar +# podman container restore -p 5432:8080 --import=dump.tar +``` ## SEE ALSO -podman(1), podman-container-checkpoint(1), podman-run(1) +**[podman(1)](podman.1.md)**, **[podman-container-checkpoint(1)](podman-container-checkpoint.1.md)**, **[podman-run(1)](podman-run.1.md)** ## HISTORY September 2018, Originally compiled by Adrian Reber <areber@redhat.com> diff --git a/docs/source/markdown/podman-image-unmount.1.md b/docs/source/markdown/podman-image-unmount.1.md index 62e879fa1..2fedb8f58 100644 --- a/docs/source/markdown/podman-image-unmount.1.md +++ b/docs/source/markdown/podman-image-unmount.1.md @@ -12,7 +12,7 @@ podman\-image\-unmount - Unmount an image's root filesystem 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. +Image storage increments a mount counter each time an 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. diff --git a/docs/source/markdown/podman-image.1.md b/docs/source/markdown/podman-image.1.md index bbf5f6d84..1b0dc395d 100644 --- a/docs/source/markdown/podman-image.1.md +++ b/docs/source/markdown/podman-image.1.md @@ -18,7 +18,7 @@ The image command allows you to manage images | 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. | +| inspect | [podman-inspect(1)](podman-inspect.1.md) | Display an 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. | | mount | [podman-image-mount(1)](podman-image-mount.1.md) | Mount an image's root filesystem. | diff --git a/docs/source/markdown/podman-login.1.md b/docs/source/markdown/podman-login.1.md index 88d025c70..3e23600fa 100644 --- a/docs/source/markdown/podman-login.1.md +++ b/docs/source/markdown/podman-login.1.md @@ -28,18 +28,6 @@ For more details about format and configurations of the auth.json file, please r ## OPTIONS -#### **--password**, **-p**=*password* - -Password for registry - -#### **--password-stdin** - -Take the password from stdin - -#### **--username**, **-u**=*username* - -Username for registry - #### **--authfile**=*path* Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json. @@ -47,14 +35,26 @@ Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE environment variable. `export REGISTRY_AUTH_FILE=path` +#### **--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. +Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client) + #### **--get-login** Return the logged-in user for the registry. Return error if no login is found. -#### **--cert-dir**=*path* +#### **--help**, **-h** -Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. -Please refer to containers-certs.d(5) for details. (This option is not available with the remote Podman client) +Print usage statement + +#### **--password**, **-p**=*password* + +Password for registry + +#### **--password-stdin** + +Take the password from stdin #### **--tls-verify**=*true|false* @@ -62,9 +62,13 @@ Require HTTPS and verify certificates when contacting registries (default: true) then TLS verification will be used. If set to false, then TLS verification will not be used. If not specified, TLS verification will be used unless the target registry is listed as an insecure registry in registries.conf. -#### **--help**, **-h** +#### **--username**, **-u**=*username* -Print usage statement +Username for registry + +#### **--verbose**, **-v** + +print detailed information about credential store ## EXAMPLES @@ -107,6 +111,14 @@ $ echo $testpassword | podman login -u testuser --password-stdin docker.io Login Succeeded! ``` +``` +$ podman login quay.io --verbose +Username: myusername +Password: +Used: /run/user/1000/containers/auth.json +Login Succeeded! +``` + ## SEE ALSO podman(1), podman-logout(1), containers-auth.json(5), containers-certs.d(5), containers-registries.conf(5) diff --git a/docs/source/markdown/podman-manifest-rm.1.md b/docs/source/markdown/podman-manifest-rm.1.md index 396dd49c7..a65f32936 100644 --- a/docs/source/markdown/podman-manifest-rm.1.md +++ b/docs/source/markdown/podman-manifest-rm.1.md @@ -11,7 +11,7 @@ Removes one or more locally stored manifest lists. ## EXAMPLE -podman manifest rm <list> +podman manifest rm `<list>` podman manifest rm listid1 listid2 diff --git a/docs/source/markdown/podman-network-create.1.md b/docs/source/markdown/podman-network-create.1.md index 3d5d98055..d110c4ceb 100644 --- a/docs/source/markdown/podman-network-create.1.md +++ b/docs/source/markdown/podman-network-create.1.md @@ -9,7 +9,7 @@ podman\-network-create - Create a Podman CNI network ## DESCRIPTION Create a CNI-network configuration for use with Podman. By default, Podman creates a bridge connection. A *Macvlan* connection can be created with the *-d macvlan* option. A parent device for macvlan can -be designated with the *-o parent=\<device>* option. In the case of *Macvlan* connections, the +be designated with the *-o parent=`<device>`* option. In the case of *Macvlan* connections, the CNI *dhcp* plugin needs to be activated or the container image must have a DHCP client to interact with the host network's DHCP server. diff --git a/docs/source/markdown/podman-pod-create.1.md b/docs/source/markdown/podman-pod-create.1.md index 37eb098d1..4b890a7af 100644 --- a/docs/source/markdown/podman-pod-create.1.md +++ b/docs/source/markdown/podman-pod-create.1.md @@ -10,8 +10,8 @@ podman\-pod\-create - Create a new pod Creates an empty pod, or unit of multiple containers, and prepares it to have containers added to it. The pod id is printed to STDOUT. You can then use -**podman create --pod \<pod_id|pod_name\> ...** to add containers to the pod, and -**podman pod start \<pod_id|pod_name\>** to start the pod. +**podman create --pod `<pod_id|pod_name>` ...** to add containers to the pod, and +**podman pod start `<pod_id|pod_name>`** to start the pod. ## OPTIONS diff --git a/docs/source/markdown/podman-pull.1.md b/docs/source/markdown/podman-pull.1.md index 54f990601..084327efd 100644 --- a/docs/source/markdown/podman-pull.1.md +++ b/docs/source/markdown/podman-pull.1.md @@ -21,42 +21,30 @@ Images are stored in local image storage. ## SOURCE - The SOURCE is the location from which the container images are pulled. - The Image "SOURCE" uses a "transport":"details" format. Only the `docker` (container registry) - transport is allowed for remote access. + SOURCE is the location from the container image is pulled from. It supports all transports from `containers-transports(5)`. If no transport is specified, the input is subject to short-name resolution and the `docker` (i.e., container registry) transport is used. For remote clients, `docker` is the only supported transport. - Multiple transports are supported: - - **dir:**_path_ - An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This - is a non-standardized format, primarily useful for debugging or noninvasive container inspection. - - $ podman pull dir:/tmp/myimage - - **docker://**_docker-reference_ (Default) - An image reference stored in a remote container image registry. The reference can include a path to a - specific registry; if it does not, the registries listed in registries.conf will be queried to find a matching - image. By default, credentials from podman login (stored at $XDG_RUNTIME_DIR/containers/auth.json by default) - will be used to authenticate; if these cannot be found, we will fall back to using credentials in - $HOME/.docker/config.json. - - $ podman pull quay.io/username/myimage +``` +# Pull from a container registry +$ podman pull quay.io/username/myimage - **docker-archive:**_path_[**:**_docker-reference_] - An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a - file, and it must not contain a digest. +# Pull from a container registry with short-name resolution +$ podman pull fedora - $ podman pull docker-archive:/tmp/myimage +# Pull from a container registry via the docker transport +$ podman pull docker://quay.io/username/myimage - **docker-daemon:**_docker-reference_ - An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest). +# Pull from a local directory +$ podman pull dir:/tmp/myimage - $ sudo podman pull docker-daemon:docker.io/library/myimage:33 +# Pull from a tarball in the docker-archive format +$ podman pull docker-archive:/tmp/myimage - **oci-archive:**_path_**:**_tag_ - An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. +# Pull from a local docker daemon +$ sudo podman pull docker-daemon:docker.io/library/myimage:33 - $ podman pull oci-archive:/tmp/myimage +# Pull from a tarball in the OCI-archive format +$ podman pull oci-archive:/tmp/myimage +``` ## OPTIONS @@ -217,7 +205,7 @@ registries.conf is the configuration file which specifies which container regist NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`. ## SEE ALSO -podman(1), podman-push(1), podman-login(1), containers-certs.d(5), containers-registries.conf(5) +podman(1), podman-push(1), podman-login(1), containers-certs.d(5), containers-registries.conf(5), containers-transports(5) ## HISTORY July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/markdown/podman-push.1.md b/docs/source/markdown/podman-push.1.md index e26d73891..68478accd 100644 --- a/docs/source/markdown/podman-push.1.md +++ b/docs/source/markdown/podman-push.1.md @@ -20,37 +20,30 @@ Images are pushed from those stored in local image storage. ## DESTINATION - The DESTINATION is a location to store container images - The Image "DESTINATION" uses a "transport":"details" format. - If a transport is not given, podman push will attempt to push - to a registry. + DESTINATION is the location the container image is pushed to. It supports all transports from `containers-transports(5)`. If no transport is specified, the `docker` (i.e., container registry) transport is used. For remote clients, `docker` is the only supported transport. - Multiple transports are supported: - - **dir:**_path_ - An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This is a non-standardized format, primarily useful for debugging or noninvasive container inspection. - - $ podman push myimage dir:/tmp/myimage - - **docker://**_docker-reference_ - An image in a registry implementing the "Docker Registry HTTP API V2". By default, uses the authorization state in `$XDG_RUNTIME_DIR/containers/auth.json`, which is set using `(podman login)`. If the authorization state is not found there, `$HOME/.docker/config.json` is checked, which is set using `(docker login)`. - - $ podman push myimage quay.io/username/myimage +``` +# Push to a container registry +$ podman push quay.io/podman/stable - **docker-archive:**_path_[**:**_docker-reference_] - An image is stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a file, and it must not contain a digest. +# Push to a container registry via the docker transport +$ podman push docker://quay.io/podman/stable - $ podman push myimage docker-archive:/tmp/myimage +# Push to a container registry with another tag +$ podman push myimage quay.io/username/myimage - **docker-daemon:**_docker-reference_ - An image in _docker-reference_ format stored in the docker daemon internal storage. _docker-reference_ must contain a tag. +# Push to a local directory +$ podman push myimage dir:/tmp/myimage - $ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 +# Push to a tarball in the docker-archive format +$ podman push myimage docker-archive:/tmp/myimage - **oci-archive:**_path_**:**_tag_ - An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. +# Push to a local docker daemon +$ sudo podman push myimage docker-daemon:docker.io/library/myimage:33 - $ podman push myimage oci-archive:/tmp/myimage +# Push to a tarball in the OCI format +$ podman push myimage oci-archive:/tmp/myimage +``` ## OPTIONS @@ -161,4 +154,4 @@ Storing signatures ``` ## SEE ALSO -podman(1), podman-pull(1), podman-login(1), containers-certs.d(5) +podman(1), podman-pull(1), podman-login(1), containers-certs.d(5), containers-transports(5) diff --git a/docs/source/markdown/podman-rmi.1.md b/docs/source/markdown/podman-rmi.1.md index 765c1bd6d..1f62d6133 100644 --- a/docs/source/markdown/podman-rmi.1.md +++ b/docs/source/markdown/podman-rmi.1.md @@ -10,6 +10,7 @@ podman\-rmi - Removes one or more locally stored images ## DESCRIPTION Removes one or more locally stored images. +Passing an argument _image_ deletes it, along with any of its dangling (untagged) parent images. ## OPTIONS diff --git a/docs/source/markdown/podman-run.1.md b/docs/source/markdown/podman-run.1.md index 46e15d62f..6027a14a5 100644 --- a/docs/source/markdown/podman-run.1.md +++ b/docs/source/markdown/podman-run.1.md @@ -281,12 +281,10 @@ it in the **containers.conf** file: see **containers.conf(5)** for more informat #### **--detach-keys**=*sequence* -Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will disable this feature. The default is *ctrl-p,ctrl-q*. +Specify the key sequence for detaching a container. Format is a single character `[a-Z]` or one or more `ctrl-<value>` characters where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. Specifying "" will set the sequence to the default value of *ctrl-p,ctrl-q*. This option can also be set in **containers.conf**(5) file. -Specifying "" will disable this feature. The default is **ctrl-p,ctrl-q**. - #### **--device**=_host-device_[**:**_container-device_][**:**_permissions_] Add a host device to the container. Optional *permissions* parameter diff --git a/docs/source/markdown/podman.1.md b/docs/source/markdown/podman.1.md index 734d00971..2510eaa81 100644 --- a/docs/source/markdown/podman.1.md +++ b/docs/source/markdown/podman.1.md @@ -336,9 +336,11 @@ Images are pulled under `XDG_DATA_HOME` when specified, otherwise in the home di Currently the slirp4netns package is required to be installed to create a network device, otherwise rootless containers need to run in the network namespace of the host. +In certain environments like HPC (High Performance Computing), users cannot take advantage of the additional UIDs and GIDs from the /etc/subuid and /etc/subgid systems. However, in this environment, rootless Podman can operate with a single UID. To make this work, set the `ignore_chown_errors` option in the /etc/containers/storage.conf or in ~/.config/containers/storage.conf files. This option tells Podman when pulling an image to ignore chown errors when attempting to change a file in a container image to match the non-root UID in the image. This means all files get saved as the user's UID. Note this could cause issues when running the container. + ### **NOTE:** Unsupported file systems in rootless mode -The Overlay file system (OverlayFS) is not supported in rootless mode. The fuse-overlayfs package is a tool that provides the functionality of OverlayFS in user namespace that allows mounting file systems in rootless environments. It is recommended to install the fuse-overlayfs package. In rootless mode Podman will automatically use the fuse-overlafs program as the mount_program if installed, as long as the $HOME/.config/containers/storage.conf file was not previously created. If storage.conf exists in the homedir, add `mount_program = "/usr/bin/fuse-overlayfs"` under `[storage.options.overlay]` to enable this feature. +The Overlay file system (OverlayFS) is not supported with kernels prior to 5.12.9 in rootless mode. The fuse-overlayfs package is a tool that provides the functionality of OverlayFS in user namespace that allows mounting file systems in rootless environments. It is recommended to install the fuse-overlayfs package. In rootless mode, Podman will automatically use the fuse-overlayfs program as the mount_program if installed, as long as the $HOME/.config/containers/storage.conf file was not previously created. If storage.conf exists in the homedir, add `mount_program = "/usr/bin/fuse-overlayfs"` under `[storage.options.overlay]` to enable this feature. 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. |