diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/podman-build.1.md | 2 | ||||
| -rw-r--r-- | docs/podman-container.1.md | 1 | ||||
| -rw-r--r-- | docs/podman-create.1.md | 12 | ||||
| -rw-r--r-- | docs/podman-kill.1.md | 2 | ||||
| -rw-r--r-- | docs/podman-pause.1.md | 19 | ||||
| -rw-r--r-- | docs/podman-restart.1.md | 26 | ||||
| -rw-r--r-- | docs/podman-rm.1.md | 19 | ||||
| -rw-r--r-- | docs/podman-run.1.md | 13 | ||||
| -rw-r--r-- | docs/podman-unpause.1.md | 20 | ||||
| -rw-r--r-- | docs/podman.1.md | 11 | ||||
| -rw-r--r-- | docs/tutorials/podman_tutorial.md | 99 |
11 files changed, 145 insertions, 79 deletions
diff --git a/docs/podman-build.1.md b/docs/podman-build.1.md index 0cbce15c0..f887d68cd 100644 --- a/docs/podman-build.1.md +++ b/docs/podman-build.1.md @@ -171,7 +171,7 @@ value can be entered. The password is entered without echo. **--disable-content-trust** This is a Docker specific option to disable image verification to a Docker -registry and is not supported by Buildah. This flag is a NOOP and provided +registry and is not supported by Podman. This flag is a NOOP and provided soley for scripting compatibility. **--file, -f** *Dockerfile* diff --git a/docs/podman-container.1.md b/docs/podman-container.1.md index eac3343d5..67d42bfef 100644 --- a/docs/podman-container.1.md +++ b/docs/podman-container.1.md @@ -38,7 +38,6 @@ The container command allows you to manage containers | stop | [podman-stop(1)](podman-stop.1.md) | Stop one or more running containers. | | top | [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | | umount | [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem. | -| unmount | [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem. | | unpause | [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. | | wait | [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. | diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md index 5a4d7fb5a..68c00685b 100644 --- a/docs/podman-create.1.md +++ b/docs/podman-create.1.md @@ -66,7 +66,7 @@ Write the container ID to the file **--conmon-pidfile**="" -Write the pid of the `conmon` process to a file. `conmon` daemonizes separate from Podman, so this is necessary when using systemd to restart Podman containers. +Write the pid of the `conmon` process to a file. `conmon` runs in a separate process than Podman, so this is necessary when using systemd to restart Podman containers. **--cpu-count**=*0* @@ -321,13 +321,13 @@ Not implemented **--log-driver**="*json-file*" -Logging driver for the container. Default is defined by daemon `--log-driver` flag. -**Warning**: the `podman logs` command works only for the `json-file` and -`journald` logging drivers. +Logging driver for the container. Currently not supported. This flag is a NOOP provided soley for scripting compatibility. **--log-opt**=[] -Logging driver specific options. +Logging driver specific options. Used to set the path to the container log file. For example: + +`--log-opt path=/var/log/container/mycontainer.json` **--mac-address**="" @@ -414,7 +414,7 @@ UUID short identifier (“f78375b1c487”) Name (“jonah”) podman generates a UUID for each container, and if a name is not assigned -to the container with **--name** then the daemon will also generate a random +to the container with **--name** then it will generate a random string name. The name is useful any place you need to identify a container. This works for both background and foreground containers. diff --git a/docs/podman-kill.1.md b/docs/podman-kill.1.md index 14066d151..85f68a73d 100644 --- a/docs/podman-kill.1.md +++ b/docs/podman-kill.1.md @@ -4,7 +4,7 @@ podman\-kill - Kills one or more containers with a signal ## SYNOPSIS -**podman kill** [*options*] *container* ... +**podman kill** [*options*] [*container* ...] ## DESCRIPTION The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal. diff --git a/docs/podman-pause.1.md b/docs/podman-pause.1.md index b4930de8d..f19fa5d6a 100644 --- a/docs/podman-pause.1.md +++ b/docs/podman-pause.1.md @@ -4,16 +4,33 @@ podman\-pause - Pause one or more containers ## SYNOPSIS -**podman pause** [*options*] *container* ... +**podman pause** [*options*] [*container*...] ## DESCRIPTION Pauses all the processes in one or more containers. You may use container IDs or names as input. +## OPTIONS + +**--all, -a** + +Pause all running containers. + ## EXAMPLE +Pause a container named 'mywebserver' +``` podman pause mywebserver +``` +Pause a container by partial container ID. +``` podman pause 860a4b23 +``` + +Pause all **running** containers. +``` +podman stop -a +``` ## SEE ALSO podman(1), podman-unpause(1) diff --git a/docs/podman-restart.1.md b/docs/podman-restart.1.md index caacaf31d..875afa385 100644 --- a/docs/podman-restart.1.md +++ b/docs/podman-restart.1.md @@ -12,33 +12,51 @@ Containers will be stopped if they are running and then restarted. Stopped containers will not be stopped and will only be started. ## OPTIONS -**--timeout** - -Timeout to wait before forcibly stopping the container +**--all, -a** +Restart all containers regardless of their current state. **--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. +**--running** +Restart all containers that are already in the *running* state. + +**--timeout** +Timeout to wait before forcibly stopping the container. + + ## EXAMPLES ## +Restart the latest container ``` $ podman restart -l ec588fc80b05e19d3006bf2e8aa325f0a2e2ff1f609b7afb39176ca8e3e13467 ``` +Restart a specific container by partial container ID ``` $ podman restart ff6cf1 ff6cf1e5e77e6dba1efc7f3fcdb20e8b89ad8947bc0518be1fcb2c78681f226f ``` +Restart two containers by name with a timeout of 4 seconds ``` $ podman restart --timeout 4 test1 test2 c3bb026838c30e5097f079fa365c9a4769d52e1017588278fa00d5c68ebc1502 17e13a63081a995136f907024bcfe50ff532917988a152da229db9d894c5a9ec ``` +Restart all running containers +``` +$ podman restart --running +``` + +Restart all containers +``` +$ podman restart --all +``` + ## SEE ALSO podman(1), podman-run(1), podman-start(1), podman-create(1) diff --git a/docs/podman-rm.1.md b/docs/podman-rm.1.md index 7474a0d1f..56664a8c1 100644 --- a/docs/podman-rm.1.md +++ b/docs/podman-rm.1.md @@ -13,7 +13,7 @@ podman\-rm - Remove one or more containers **--force, f** -Force the removal of a running container +Force the removal of a running and paused containers **--all, a** @@ -29,16 +29,29 @@ to run containers such as CRI-O, the last started container could be from either Remove the volumes associated with the container. (Not yet implemented) ## EXAMPLE - +Remove a container by its name *mywebserver* +``` podman rm mywebserver - +``` +Remove several containers by name and container id. +``` podman rm mywebserver myflaskserver 860a4b23 +``` +Forcibly remove a container by container ID. +``` podman rm -f 860a4b23 +``` +Remove all containers regardless of its run state. +``` podman rm -f -a +``` +Forcibly remove the latest container created. +``` podman rm -f --latest +``` ## SEE ALSO podman(1), podman-rmi(1) diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md index b708e3407..912026a55 100644 --- a/docs/podman-run.1.md +++ b/docs/podman-run.1.md @@ -78,7 +78,7 @@ Write the container ID to the file **--conmon-pidfile**="" -Write the pid of the `conmon` process to a file. `conmon` daemonizes separate from Podman, so this is necessary when using systemd to restart Podman containers. +Write the pid of the `conmon` process to a file. `conmon` runs in a separate process than Podman, so this is necessary when using systemd to restart Podman containers. **--cpu-period**=*0* @@ -333,16 +333,13 @@ Not implemented **--log-driver**="*json-file*" -Logging driver for the container. Default is defined by daemon `--log-driver` flag. - -**Warning**: the `podman logs` command works only for the `json-file` and -`journald` logging drivers. +Logging driver for the container. Currently not supported. This flag is a NOOP provided soley for scripting compatibility. **--log-opt**=[] -Logging driver specific options. +Logging driver specific options. Used to set the path to the container log file. For example: -`path=/var/log/container/mycontainer.json`: Set the path to the container log file. +`--log-opt path=/var/log/container/mycontainer.json` **--mac-address**="" @@ -399,7 +396,7 @@ The operator can identify a container in three ways: - Name (“jonah”) podman generates a UUID for each container, and if a name is not assigned -to the container with **--name** then the daemon will also generate a random +to the container with **--name** then it will generate a random string name. The name is useful any place you need to identify a container. This works for both background and foreground containers. diff --git a/docs/podman-unpause.1.md b/docs/podman-unpause.1.md index 9404e7648..acfab0930 100644 --- a/docs/podman-unpause.1.md +++ b/docs/podman-unpause.1.md @@ -4,16 +4,34 @@ podman\-unpause - Unpause one or more containers ## SYNOPSIS -**podman unpause** [*options*] *container* ... +**podman unpause** [*options*] [*container*...] ## DESCRIPTION Unpauses the processes in one or more containers. You may use container IDs or names as input. +## OPTIONS + +**--all, -a** + +Unpause all paused containers. + ## EXAMPLE +Unpause a container called 'mywebserver' +``` podman unpause mywebserver +``` +Unpause a container by a partial container ID. + +``` podman unpause 860a4b23 +``` + +Unpause all **paused** containers. +``` +podman unpause -a +``` ## SEE ALSO podman(1), podman-pause(1) diff --git a/docs/podman.1.md b/docs/podman.1.md index 085af97ff..b7433d850 100644 --- a/docs/podman.1.md +++ b/docs/podman.1.md @@ -56,7 +56,7 @@ Path to the OCI compatible binary used to run containers **--storage-driver, -s**=**value** -Storage driver. The default storage driver for UID 0 is configured in /etc/containers/storage.conf (`$HOME/.config/containers/storage.conf` in rootless mode), and is *vfs* for other users. The `STORAGE_DRIVER` environment variable overrides the default. The --storage-driver specified driver overrides all. +Storage driver. The default storage driver for UID 0 is configured in /etc/containers/storage.conf (`$HOME/.config/containers/storage.conf` in rootless mode), and is *vfs* for non-root users when *fuse-overlayfs* is not available. The `STORAGE_DRIVER` environment variable overrides the default. The --storage-driver specified driver overrides all. Overriding this option will cause the *storage-opt* settings in /etc/containers/storage.conf to be ignored. The user must specify additional options via the `--storage-opt` flag. @@ -192,7 +192,7 @@ the exit codes follow the `chroot` standard, see below: When Podman runs in rootless mode, the file `$HOME/.config/containers/storage.conf` is also loaded. ## Rootless mode -Podman can also be used as non-root user. When podman runs in rootless mode, an user namespace is automatically created. +Podman can also be used as non-root user. When podman runs in rootless mode, a user namespace is automatically created for the user, defined in /etc/subuid and /etc/subgid. Containers created by a non-root user are not visible to other users and are not seen or managed by podman running as root. @@ -209,13 +209,14 @@ Or just add the content manually. $ echo USERNAME:10000:65536 >> /etc/subuid $ echo USERNAME:10000:65536 >> /etc/subgid +See the `subuid(5)` and `subgid(5)` man pages for more information. + Images are pulled under `XDG_DATA_HOME` when specified, otherwise in the home directory of the user under `.local/share/containers/storage`. -Currently it is not possible to create a network device, so rootless containers need to run in the host network namespace. If a rootless container creates a network namespace, -then only the loopback device will be available. +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. ## SEE ALSO -`containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `crio(8)`, `libpod.conf(5)`, `oci-hooks(5)`, `policy.json(5)` +`containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `crio(8)`, `libpod.conf(5)`, `oci-hooks(5)`, `policy.json(5)`, `subuid(5)`, `subgid(5)`, `slirp4netns(1)` ## HISTORY Dec 2016, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/tutorials/podman_tutorial.md b/docs/tutorials/podman_tutorial.md index 152d65a59..5a8f997b8 100644 --- a/docs/tutorials/podman_tutorial.md +++ b/docs/tutorials/podman_tutorial.md @@ -5,10 +5,13 @@ Podman is a utility provided as part of the libpod library. It can be used to c containers. The following tutorial will teach you how to set up Podman and perform some basic commands with Podman. +**NOTE**: the code samples are intended to be run as a non-root user, and use `sudo` where +root escalation is required. + ## Install Podman on Fedora from RPM Repositories Fedora 27 and later provide Podman via the package manager. ```console -$ sudo dnf install -y podman +sudo dnf install -y podman ``` ## Install Podman on Fedora from Source @@ -18,10 +21,10 @@ acquire the source, and build it. ### Installing build and runtime dependencies ```console -$ sudo dnf install -y git runc libassuan-devel golang golang-github-cpuguy83-go-md2man glibc-static \ - gpgme-devel glib2-devel device-mapper-devel libseccomp-devel \ - atomic-registries iptables skopeo-containers containernetworking-cni \ - conmon +sudo dnf install -y git runc libassuan-devel golang golang-github-cpuguy83-go-md2man glibc-static \ + gpgme-devel glib2-devel device-mapper-devel libseccomp-devel \ + atomic-registries iptables skopeo-containers containernetworking-cni \ + conmon ``` ### Building and installing podman @@ -29,12 +32,12 @@ First, configure a `GOPATH` (if you are using go1.8 or later, this defaults to ` and make libpod. ```console -$ export GOPATH=~/go -$ mkdir -p $GOPATH -$ git clone https://github.com/containers/libpod/ $GOPATH/src/github.com/containers/libpod -$ cd $GOPATH/src/github.com/containers/libpod -$ make -$ sudo make install PREFIX=/usr +export GOPATH=~/go +mkdir -p $GOPATH +git clone https://github.com/containers/libpod/ $GOPATH/src/github.com/containers/libpod +cd $GOPATH/src/github.com/containers/libpod +make +sudo make install PREFIX=/usr ``` You now have a working podman environment. Jump to [Familiarizing yourself with Podman](#familiarizing-yourself-with-podman) @@ -50,8 +53,8 @@ tutorial. For this tutorial, the Ubuntu **artful-server-cloudimg** image was use #### Installing base packages ```console -$ sudo apt-get update -$ sudo apt-get install libdevmapper-dev libglib2.0-dev libgpgme11-dev golang libseccomp-dev \ +sudo apt-get update +sudo apt-get install libdevmapper-dev libglib2.0-dev libgpgme11-dev golang libseccomp-dev \ go-md2man libprotobuf-dev libprotobuf-c0-dev libseccomp-dev python3-setuptools ``` #### Building and installing conmon @@ -59,42 +62,42 @@ First, configure a `GOPATH` (if you are using go1.8 or later, this defaults to ` and make libpod. ```console -$ export GOPATH=~/go -$ mkdir -p $GOPATH -$ git clone https://github.com/kubernetes-sigs/cri-o $GOPATH/src/github.com/kubernetes-sigs/cri-o -$ cd $GOPATH/src/github.com/kubernetes-sigs/cri-o -$ mkdir bin -$ make bin/conmon -$ sudo install -D -m 755 bin/conmon /usr/libexec/podman/conmon +export GOPATH=~/go +mkdir -p $GOPATH +git clone https://github.com/kubernetes-sigs/cri-o $GOPATH/src/github.com/kubernetes-sigs/cri-o +cd $GOPATH/src/github.com/kubernetes-sigs/cri-o +mkdir bin +make bin/conmon +sudo install -D -m 755 bin/conmon /usr/libexec/podman/conmon ``` #### Adding required configuration files ```console -$ sudo mkdir -p /etc/containers -$ sudo curl https://raw.githubusercontent.com/projectatomic/registries/master/registries.fedora -o /etc/containers/registries.conf -$ sudo curl https://raw.githubusercontent.com/containers/skopeo/master/default-policy.json -o /etc/containers/policy.json +sudo mkdir -p /etc/containers +sudo curl https://raw.githubusercontent.com/projectatomic/registries/master/registries.fedora -o /etc/containers/registries.conf +sudo curl https://raw.githubusercontent.com/containers/skopeo/master/default-policy.json -o /etc/containers/policy.json ``` #### Installing CNI plugins ```console -$ git clone https://github.com/containernetworking/plugins.git $GOPATH/src/github.com/containernetworking/plugins -$ cd $GOPATH/src/github.com/containernetworking/plugins -$ ./build.sh -$ sudo mkdir -p /usr/libexec/cni -$ sudo cp bin/* /usr/libexec/cni +git clone https://github.com/containernetworking/plugins.git $GOPATH/src/github.com/containernetworking/plugins +cd $GOPATH/src/github.com/containernetworking/plugins +./build_linux.sh +sudo mkdir -p /usr/libexec/cni +sudo cp bin/* /usr/libexec/cni ``` #### Installing runc ```console -$ git clone https://github.com/opencontainers/runc.git $GOPATH/src/github.com/opencontainers/runc -$ cd $GOPATH/src/github.com/opencontainers/runc -$ make BUILDTAGS="seccomp" -$ sudo cp runc /usr/bin/runc +git clone https://github.com/opencontainers/runc.git $GOPATH/src/github.com/opencontainers/runc +cd $GOPATH/src/github.com/opencontainers/runc +make BUILDTAGS="seccomp" +sudo cp runc /usr/bin/runc ``` ### Building and installing Podman ```console -$ git clone https://github.com/containers/libpod/ $GOPATH/src/github.com/containers/libpod -$ cd $GOPATH/src/github.com/containers/libpod -$ make -$ sudo make install PREFIX=/usr +git clone https://github.com/containers/libpod/ $GOPATH/src/github.com/containers/libpod +cd $GOPATH/src/github.com/containers/libpod +make +sudo make install PREFIX=/usr ``` ## Familiarizing yourself with Podman @@ -103,10 +106,10 @@ $ sudo make install PREFIX=/usr This sample container will run a very basic httpd server that serves only its index page. ```console -$ sudo podman run -dt -e HTTPD_VAR_RUN=/var/run/httpd -e HTTPD_MAIN_CONF_D_PATH=/etc/httpd/conf.d \ - -e HTTPD_MAIN_CONF_PATH=/etc/httpd/conf \ - -e HTTPD_CONTAINER_SCRIPTS_PATH=/usr/share/container-scripts/httpd/ \ - registry.fedoraproject.org/f27/httpd /usr/bin/run-httpd +sudo podman run -dt -e HTTPD_VAR_RUN=/var/run/httpd -e HTTPD_MAIN_CONF_D_PATH=/etc/httpd/conf.d \ + -e HTTPD_MAIN_CONF_PATH=/etc/httpd/conf \ + -e HTTPD_CONTAINER_SCRIPTS_PATH=/usr/share/container-scripts/httpd/ \ + registry.fedoraproject.org/f27/httpd /usr/bin/run-httpd ``` Because the container is being run in detached mode, represented by the *-d* in the podman run command, podman will print the container ID after it has run. @@ -114,7 +117,7 @@ will print the container ID after it has run. ### Listing running containers The Podman *ps* command is used to list creating and running containers. ```console -$ sudo podman ps +sudo podman ps ``` Note: If you add *-a* to the *ps* command, Podman will show all containers. @@ -134,7 +137,7 @@ Now that we have the IP address of the container, we can test the network commun operating system and the container using curl. The following command should display the index page of our containerized httpd server. ```console -# curl http://<IP_address>:8080 +curl http://<IP_address>:8080 ``` ### Viewing the container's logs @@ -163,7 +166,7 @@ With this a container can later be restored and continue running at exactly the checkpoint. This capability requires CRIU 3.11 or later installed on the system. To checkpoint the container use: ```console -$ sudo podman container checkpoint <container_id> +sudo podman container checkpoint <container_id> ``` ### Restoring the container @@ -171,29 +174,29 @@ Restoring a container is only possible for a previously checkpointed container. continue to run at exactly the same point in time it was checkpointed. To restore the container use: ```console -$ sudo podman container restore <container_id> +sudo podman container restore <container_id> ``` After being restored, the container will answer requests again as it did before checkpointing. ```console -# curl http://<IP_address>:8080 +curl http://<IP_address>:8080 ``` ### Stopping the container To stop the httpd container: ```console -$ sudo podman stop --latest +sudo podman stop --latest ``` You can also check the status of one or more containers using the *ps* subcommand. In this case, we should use the *-a* argument to list all containers. ```console -$ sudo podman ps -a +sudo podman ps -a ``` ### Removing the container To remove the httpd container: ```console -$ sudo podman rm --latest +sudo podman rm --latest ``` You can verify the deletion of the container by running *podman ps -a*. |