summaryrefslogtreecommitdiff
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/libpod.conf.5.md7
-rw-r--r--docs/podman-commit.1.md2
-rw-r--r--docs/podman-cp.1.md80
-rw-r--r--docs/podman-create.1.md51
-rw-r--r--docs/podman-login.1.md14
-rw-r--r--docs/podman-rm.1.md4
-rw-r--r--docs/podman-run.1.md38
-rw-r--r--docs/podman-stats.1.md9
-rw-r--r--docs/podman.1.md1
9 files changed, 175 insertions, 31 deletions
diff --git a/docs/libpod.conf.5.md b/docs/libpod.conf.5.md
index 98eb5bece..0c11e2013 100644
--- a/docs/libpod.conf.5.md
+++ b/docs/libpod.conf.5.md
@@ -12,8 +12,11 @@ libpod to manage containers.
**image_default_transport**=""
Default transport method for pulling and pushing images
-**runtime_path**=""
- Paths to search for a valid OCI runtime binary
+**runtime**=""
+ Default OCI runtime to use if nothing is specified
+
+**runtimes**
+ For each OCI runtime, specify a list of paths to look for. The first one found is used.
**conmon_path**=""
Paths to search for the Conmon container manager binary
diff --git a/docs/podman-commit.1.md b/docs/podman-commit.1.md
index 79e14aba6..acde51859 100644
--- a/docs/podman-commit.1.md
+++ b/docs/podman-commit.1.md
@@ -76,7 +76,7 @@ e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8
```
```
-$ podman commit -q --pause=false reverent_golick image-commited
+$ podman commit -q --pause=false containerID image-commited
e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8
```
diff --git a/docs/podman-cp.1.md b/docs/podman-cp.1.md
index 88e50e86b..37426b236 100644
--- a/docs/podman-cp.1.md
+++ b/docs/podman-cp.1.md
@@ -3,20 +3,70 @@
## NAME
podman\-cp - Copy files/folders between a container and the local filesystem
-## Description
-We chose not to implement the `cp` feature in `podman` even though the upstream Docker
-project has it. We have a much stronger capability. Using standard podman-mount
-and podman-umount, we can take advantage of the entire linux tool chain, rather
+## SYNOPSIS
+**podman cp [CONTAINER:]SRC_PATH [CONTAINER:]DEST_PATH**
+
+## DESCRIPTION
+Copies the contents of **SRC_PATH** to the **DEST_PATH**. You can copy from the containers's filesystem to the local machine or the reverse, from the local filesystem to the container.
+
+The CONTAINER can be a running or stopped container. The **SRC_PATH** or **DEST_PATH** can be a file or directory.
+
+The **podman cp** command assumes container paths are relative to the container's / (root) directory.
+
+This means supplying the initial forward slash is optional;
+
+The command sees **compassionate_darwin:/tmp/foo/myfile.txt** and **compassionate_darwin:tmp/foo/myfile.txt** as identical.
+
+Local machine paths can be an absolute or relative value.
+The command interprets a local machine's relative paths as relative to the current working directory where **podman cp** is run.
+
+Assuming a path separator of /, a first argument of **SRC_PATH** and second argument of **DEST_PATH**, the behavior is as follows:
+
+**SRC_PATH** specifies a file
+ - **DEST_PATH** does not exist
+ - the file is saved to a file created at **DEST_PATH**
+ - **DEST_PATH** does not exist and ends with /
+ - **DEST_PATH** is created as a directory and the file is copied into this directory using the basename from **SRC_PATH**
+ - **DEST_PATH** exists and is a file
+ - the destination is overwritten with the source file's contents
+ - **DEST_PATH** exists and is a directory
+ - the file is copied into this directory using the basename from **SRC_PATH**
+
+**SRC_PATH** specifies a directory
+ - **DEST_PATH** does not exist
+ - **DEST_PATH** is created as a directory and the contents of the source directory are copied into this directory
+ - **DEST_PATH** exists and is a file
+ - Error condition: cannot copy a directory to a file
+ - **DEST_PATH** exists and is a directory
+ - **SRC_PATH** ends with /
+ - the source directory is copied into this directory
+ - **SRC_PATH** ends with /. (that is: slash followed by dot)
+ - the content of the source directory is copied into this directory
+
+The command requires **SRC_PATH** and **DEST_PATH** to exist according to the above rules.
+
+If **SRC_PATH** is local and is a symbolic link, the symbolic target, is copied by default.
+
+A colon (:) is used as a delimiter between CONTAINER and its path.
+
+You can also use : when specifying paths to a **SRC_PATH** or **DEST_PATH** on a local machine, for example, `file:name.txt`.
+
+If you use a : in a local machine path, you must be explicit with a relative or absolute path, for example:
+ `/path/to/file:name.txt` or `./file:name.txt`
+
+
+## ALTERNATIVES
+
+Podman has much stronger capabilities than just `podman cp` to achieve copy files between host and container.
+
+Using standard podman-mount and podman-umount takes advantage of the entire linux tool chain, rather
then just cp.
-If a user wants to copy contents out of a container or into a container, they
-can execute a few simple commands.
+If a user wants to copy contents out of a container or into a container, they can execute a few simple commands.
-You can copy from the container's file system to the local machine or the
-reverse, from the local filesystem to the container.
+You can copy from the container's file system to the local machine or the reverse, from the local filesystem to the container.
-If you want to copy the /etc/foobar directory out of a container and onto /tmp
-on the host, you could execute the following commands:
+If you want to copy the /etc/foobar directory out of a container and onto /tmp on the host, you could execute the following commands:
mnt=$(podman mount CONTAINERID)
cp -R ${mnt}/etc/foobar /tmp
@@ -40,5 +90,15 @@ This shows that using `podman mount` and `podman umount` you can use all of the
standard linux tools for moving files into and out of containers, not just
the cp command.
+## EXAMPLE
+
+podman cp /myapp/app.conf containerID:/myapp/app.conf
+
+podman cp /home/myuser/myfiles.tar containerID:/tmp
+
+podman cp containerID:/myapp/ /myapp/
+
+podman cp containerID:/home/myuser/. /home/myuser/
+
## SEE ALSO
podman(1), podman-mount(1), podman-umount(1)
diff --git a/docs/podman-create.1.md b/docs/podman-create.1.md
index 98b1a2a17..342ef59c3 100644
--- a/docs/podman-create.1.md
+++ b/docs/podman-create.1.md
@@ -657,18 +657,21 @@ The followings examples are all valid:
Without this argument the command will be run as root in the container.
-**--userns**=""
+**--userns**=host
+**--userns**=ns:my_namespace
-Set the usernamespace mode for the container. The use of userns is disabled by default.
+Set the user namespace mode for the container. The use of userns is disabled by default.
- **host**: use the host usernamespace and enable all privileged options (e.g., `pid=host` or `--privileged`).
- **ns**: specify the usernamespace to use.
+- `host`: run in the user namespace of the caller. This is the default if no user namespace options are set. The processes running in the container will have the same privileges on the host as any other process launched by the calling user.
+- `ns`: run the container in the given existing user namespace.
+
+This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
**--uts**=*host*
Set the UTS mode for the container
**host**: use the host's UTS namespace inside the container.
- **ns**: specify the usernamespace to use.
+ **ns**: specify the user namespace to use.
Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
**--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*]
@@ -780,10 +783,28 @@ can override the working directory by using the **-w** option.
## EXAMPLES
+### Create a container using a local image
+
+```
+$ podman create alpine ls
+```
+
+### Create a container using a local image and annotate it
+
+```
+$ podman create --annotation HELLO=WORLD alpine ls
+```
+
+### Create a container using a local image, allocating a pseudo-TTY, keeping stdin open and name it myctr
+
+```
+ podman create -t -i --name myctr alpine ls
+```
+
### Set UID/GID mapping in a new user namespace
-If you want to run the container in a new user namespace and define the mapping of
-the uid and gid from the host.
+Running a container in a new user namespace requires a mapping of
+the uids and gids from the host.
```
$ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
@@ -804,13 +825,27 @@ KillMode=process
WantedBy=multi-user.target
```
+### Rootless Containers
+
+Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils
+be installed. The shadow-utils package must include the newuidmap and newgidmap executables.
+
+Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released.
+
+In order for users to run rootless, there must be an entry for their username in /etc/subuid and /etc/subgid which lists the UIDs for their user namespace.
+
+Rootless podman works better if the fuse-overlayfs and slirp4netns packages are installed.
+The fuse-overlay package provides a userspace overlay storage driver, otherwise users need to use
+the vfs storage driver, which is diskspace expensive and does not perform well. slirp4netns is
+required for VPN, without it containers need to be run with the --net=host flag.
+
## FILES
**/etc/subuid**
**/etc/subgid**
## SEE ALSO
-subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8)
+subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1)
## HISTORY
October 2017, converted from Docker documentation to podman by Dan Walsh for podman <dwalsh@redhat.com>
diff --git a/docs/podman-login.1.md b/docs/podman-login.1.md
index e72d1deca..3ac0e30ef 100644
--- a/docs/podman-login.1.md
+++ b/docs/podman-login.1.md
@@ -25,6 +25,10 @@ flag. The default path used is **${XDG\_RUNTIME_DIR}/containers/auth.json**.
Password for registry
+**--password-stdin**
+
+Take the password from stdin
+
**--username, -u**
Username for registry
@@ -86,6 +90,16 @@ $ podman login --cert-dir /etc/containers/certs.d/ -u foo -p bar localhost:5000
Login Succeeded!
```
+```
+$ podman login -u testuser --password-stdin < testpassword.txt docker.io
+Login Succeeded!
+```
+
+```
+$ echo $testpassword | podman login -u testuser --password-stdin docker.io
+Login Succeeded!
+```
+
## SEE ALSO
podman(1), podman-logout(1), crio(8)
diff --git a/docs/podman-rm.1.md b/docs/podman-rm.1.md
index 4fcb0b6c5..f4513c2be 100644
--- a/docs/podman-rm.1.md
+++ b/docs/podman-rm.1.md
@@ -17,7 +17,9 @@ Remove all containers. Can be used in conjunction with -f as well.
**--force, f**
-Force the removal of a running and paused containers
+Force the removal of running and paused containers. Forcing a containers removal also
+removes containers from container storage even if the container is not known to podman.
+Containers could have been created by a different container engine.
**--latest, -l**
diff --git a/docs/podman-run.1.md b/docs/podman-run.1.md
index 828ae96a8..cef9a6e8a 100644
--- a/docs/podman-run.1.md
+++ b/docs/podman-run.1.md
@@ -663,7 +663,7 @@ Without this argument the command will be run as root in the container.
**--userns**=host
**--userns**=ns:my_namespace
-Set the user namespace for the container.
+Set the user namespace mode for the container. The use of userns is disabled by default.
- `host`: run in the user namespace of the caller. This is the default if no user namespace options are set. The processes running in the container will have the same privileges on the host as any other process launched by the calling user.
- `ns`: run the container in the given existing user namespace.
@@ -675,7 +675,7 @@ This option is incompatible with --gidmap, --uidmap, --subuid and --subgid
Set the UTS mode for the container
`host`: use the host's UTS namespace inside the container.
-`ns`: specify the usernamespace to use.
+`ns`: specify the user namespace to use.
**NOTE**: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
@@ -709,6 +709,20 @@ Current supported mount TYPES are bind, and tmpfs.
ยท tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
+**--userns**=""
+
+Set the user namespace mode for the container. The use of userns is disabled by default.
+
+ **host**: use the host user namespace and enable all privileged options (e.g., `pid=host` or `--privileged`).
+ **ns**: specify the user namespace to use.
+
+**--uts**=*host*
+
+Set the UTS mode for the container
+ **host**: use the host's UTS namespace inside the container.
+ **ns**: specify the user namespace to use.
+ Note: the host mode gives the container access to changing the host's hostname and is therefore considered insecure.
+
**--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*]
Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman
@@ -1074,8 +1088,8 @@ supported sysctls.
### Set UID/GID mapping in a new user namespace
-If you want to run the container in a new user namespace and define the mapping of
-the uid and gid from the host.
+Running a container in a new user namespace requires a mapping of
+the uids and gids from the host.
```
$ podman run --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
@@ -1096,13 +1110,27 @@ KillMode=process
WantedBy=multi-user.target
```
+### Rootless Containers
+
+Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils
+be installed. The shadow-utils package must include the newuidmap and newgidmap executables.
+
+Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released.
+
+In order for users to run rootless, there must be an entry for their username in /etc/subuid and /etc/subgid which lists the UIDs for their user namespace.
+
+Rootless podman works better if the fuse-overlayfs and slirp4netns packages are installed.
+The fuse-overlay package provides a userspace overlay storage driver, otherwise users need to use
+the vfs storage driver, which is diskspace expensive and does not perform well. slirp4netns is
+required for VPN, without it containers need to be run with the --net=host flag.
+
## FILES
**/etc/subuid**
**/etc/subgid**
## SEE ALSO
-subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8)
+subgid(5), subuid(5), libpod.conf(5), systemd.unit(5), setsebool(8), slirp4netns(1), fuse-overlayfs(1)
## HISTORY
September 2018, updated by Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp>
diff --git a/docs/podman-stats.1.md b/docs/podman-stats.1.md
index 8fc765326..d0b56b2e6 100644
--- a/docs/podman-stats.1.md
+++ b/docs/podman-stats.1.md
@@ -36,16 +36,17 @@ Valid placeholders for the Go template are listed below:
| **Placeholder** | **Description** |
| --------------- | --------------- |
-| .ID | Container ID |
+| .Pod | Pod ID |
+| .CID | Container ID |
| .Name | Container Name |
-| .CPUPerc | CPU percentage |
+| .CPU | CPU percentage |
| .MemUsage | Memory usage |
-| .MemPerc | Memory percentage |
+| .Mem | Memory percentage |
| .NetIO | Network IO |
| .BlockIO | Block IO |
| .PIDS | Number of PIDs |
-
+When using a GO template, you may preceed the format with `table` to print headers.
## EXAMPLE
```
diff --git a/docs/podman.1.md b/docs/podman.1.md
index 51ef00383..760f27310 100644
--- a/docs/podman.1.md
+++ b/docs/podman.1.md
@@ -168,6 +168,7 @@ the exit codes follow the `chroot` standard, see below:
| [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem. |
| [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. |
| [podman-version(1)](podman-version.1.md) | Display the Podman version information. |
+| [podman-volume(1)](podman-volume.1.md) | Manage Volumes. |
| [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. |
## FILES
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2025-01-01 00:48:18 +0000