diff options
Diffstat (limited to 'docs/source/man')
96 files changed, 9729 insertions, 0 deletions
diff --git a/docs/source/man/podman-attach.1.md b/docs/source/man/podman-attach.1.md new file mode 100644 index 000000000..cef01f0f6 --- /dev/null +++ b/docs/source/man/podman-attach.1.md @@ -0,0 +1,60 @@ +% podman-attach(1) + +## NAME +podman\-attach - Attach to a running container + +## SYNOPSIS +**podman attach** [*options*] *container* + +**podman container attach** [*options*] *container* + +## DESCRIPTION +The attach command allows you to attach to a running container using the container's ID +or name, either to view its ongoing output or to control it interactively. + +You can detach from the container (and leave it running) using a configurable key sequence. The default +sequence is `ctrl-p,ctrl-q`. +Configure the keys sequence using the **--detach-keys** option, or specifying +it in the **libpod.conf** file: see **libpod.conf(5)** for more information. + +## OPTIONS +**--detach-keys**=*sequence* + +Override the key sequence for detaching a container. Format is a single character `[a-Z]` or +a comma separated sequence of `ctrl-<value>`, where `<value>` is one of: +`a-z`, `@`, `^`, `[`, `\\`, `]`, `^` or `_`. + +**--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 latest option is not supported on the remote client. + +**--no-stdin** + +Do not attach STDIN. The default is false. + +**--sig-proxy**=*true*|*false* + +Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true*. + +## EXAMPLES + +``` +$ podman attach foobar +[root@localhost /]# +``` +``` +$ podman attach --latest +[root@localhost /]# +``` +``` +$ podman attach 1234 +[root@localhost /]# +``` +``` +$ podman attach --no-stdin foobar +``` +## SEE ALSO +podman(1), podman-exec(1), podman-run(1) diff --git a/docs/source/man/podman-build.1.md b/docs/source/man/podman-build.1.md new file mode 100644 index 000000000..567d0ead3 --- /dev/null +++ b/docs/source/man/podman-build.1.md @@ -0,0 +1,712 @@ +% podman-build(1) + +## NAME +podman\-build - Build a container image using a Containerfile + +## SYNOPSIS +**podman build** [*options*] [*context*] + +**podman image build** [*options*] [*context*] + +## DESCRIPTION +**podman build** Builds an image using instructions from one or more Containerfiles or Dockerfiles and a specified build context directory. A Containerfile uses the same syntax as a Dockerfile internally. For this document, a file referred to as a Containerfile can be a file named either 'Containerfile' or 'Dockerfile'. + +The build context directory can be specified as the http(s) URL of an archive, git repository or Containerfile. + +If no context directory is specified, then Podman will assume the current working directory as the build context, which should contain the Containerfile. + +Containerfiles ending with a ".in" suffix will be preprocessed via CPP(1). This can be useful to decompose Containerfiles into several reusable parts that can be used via CPP's **#include** directive. Notice, a Containerfile.in file can still be used by other tools when manually preprocessing them via `cpp -E`. + +When the URL is an archive, the contents of the URL is downloaded to a temporary location and extracted before execution. + +When the URL is an Containerfile, the Containerfile is downloaded to a temporary location. + +When a Git repository is set as the URL, the repository is cloned locally and then set as the context. + +## OPTIONS + +**--add-host**=*host* + +Add a custom host-to-IP mapping (host:ip) + +Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** option can be set multiple times. + +**--annotation**=*annotation* + +Add an image *annotation* (e.g. annotation=*value*) to the image metadata. Can be used multiple times. + +Note: this information is not present in Docker image formats, so it is discarded when writing images in Docker formats. + +**--authfile**=*path* + +Path of the authentication file. Default is ${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`. (Not available for remote commands) + +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` + +**--build-arg**=*arg=value* + +Specifies a build argument and its value, which will be interpolated in +instructions read from the Containerfiles in the same way that environment +variables are, but which will not be added to environment variable list in the +resulting image's configuration. + +**--cache-from** + +Images to utilize as potential cache sources. Podman does not currently support caching so this is a NOOP. + +**--cap-add**=*CAP\_xxx* + +When executing RUN instructions, run the command specified in the instruction +with the specified capability added to its capability set. +Certain capabilities are granted by default; this option can be used to add +more. + +**--cap-drop**=*CAP\_xxx* + +When executing RUN instructions, run the command specified in the instruction +with the specified capability removed from its capability set. +The CAP\_AUDIT\_WRITE, CAP\_CHOWN, CAP\_DAC\_OVERRIDE, CAP\_FOWNER, +CAP\_FSETID, CAP\_KILL, CAP\_MKNOD, CAP\_NET\_BIND\_SERVICE, CAP\_SETFCAP, +CAP\_SETGID, CAP\_SETPCAP, CAP\_SETUID, and CAP\_SYS\_CHROOT capabilities are +granted by default; this option can be used to remove them. + +If a capability is specified to both the **--cap-add** and **--cap-drop** +options, it will be dropped, regardless of the order in which the options were +given. + +**--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--cgroup-parent**=*path* + +Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. + +**--compress** + +This option is added to be aligned with other containers CLIs. +Podman doesn't communicate with a daemon or a remote server. +Thus, compressing the data before sending it is irrelevant to Podman. + +**--cni-config-dir**=*directory* + +Location of CNI configuration files which will dictate which plugins will be +used to configure network interfaces and routing for containers created for +handling `RUN` instructions, if those containers will be run in their own +network namespaces, and networking is not disabled. + +**--cni-plugin-path**=*directory[:directory[:directory[...]]]* + +List of directories in which the CNI plugins which will be used for configuring +network namespaces can be found. + +**--cpu-period**=*limit* + +Limit the CPU CFS (Completely Fair Scheduler) period + +Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. + +**--cpu-quota**=*limit* + +Limit the CPU CFS (Completely Fair Scheduler) quota + +Limit the container's CPU usage. By default, containers run with the full +CPU resource. This flag tell the kernel to restrict the container's CPU usage +to the quota you specify. + +**--cpu-shares**, **-c**=*shares* + +CPU shares (relative weight) + +By default, all containers get the same proportion of CPU cycles. This proportion +can be modified by changing the container's CPU share weighting relative +to the weighting of all other running containers. + +To modify the proportion from the default of 1024, use the **--cpu-shares** +flag to set the weighting to 2 or higher. + +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. + +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fourth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container **{C0}** with **-c=512** running one process, and another container +**{C1}** with **-c=1024** running two processes, this can result in the following +division of CPU shares: + + PID container CPU CPU share + 100 {C0} 0 100% of CPU0 + 101 {C1} 1 100% of CPU1 + 102 {C1} 2 100% of CPU2 + +**--cpuset-cpus**=*num* + + CPUs in which to allow execution (0-3, 0,1) + +**--cpuset-mems**=*nodes* + +Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + +If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` +then processes in your container will only use memory from the first +two memory nodes. + +**--creds**=*creds* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +**--device**=*device* + +Add a host device to the container. The format is `<device-on-host>[:<device-on-container>][:<permissions>]` (e.g. --device=/dev/sdc:/dev/xvdc:rwm) + +**--disable-compression, -D** + +Don't compress filesystem layers when building the image unless it is required +by the location where the image is being written. This is the default setting, +because image layers are compressed automatically when they are pushed to +registries, and images being written to local storage would only need to be +decompressed again to be stored. Compression can be forced in all cases by +specifying **--disable-compression=false**. + +**--disable-content-trust** + +This is a Docker specific option to disable image verification to a Docker +registry and is not supported by Podman. This flag is a NOOP and provided +solely for scripting compatibility. + +**--dns**=*dns* + +Set custom DNS servers + +This option can be used to override the DNS configuration passed to the container. Typically this is necessary when the host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this is the case the `--dns` flag is necessary for every run. + +The special value **none** can be specified to disable creation of /etc/resolv.conf in the container by Podman. The /etc/resolv.conf file in the image will be used without changes. + +**--dns-option**=*option* + +Set custom DNS options + +**--dns-search**=*domain* + +Set custom DNS search domains + +**--file**, **-f**=*Containerfile* + +Specifies a Containerfile which contains instructions for building the image, +either a local file or an **http** or **https** URL. If more than one +Containerfile is specified, *FROM* instructions will only be accepted from the +first specified file. + +If a build context is not specified, and at least one Containerfile is a +local file, the directory in which it resides will be used as the build +context. + +If you specify `-f -`, the Containerfile contents will be read from stdin. + +**--force-rm**=*true|false* + +Always remove intermediate containers after a build, even if the build fails (default false). + +**--format** + +Control the format for the built image's manifest and configuration data. +Recognized formats include *oci* (OCI image-spec v1.0, the default) and +*docker* (version 2, using schema format 2 for the manifest). + +Note: You can also override the default format by setting the BUILDAH\_FORMAT +environment variable. `export BUILDAH_FORMAT=docker` + +**-h**, **--help** + +Print usage statement + +**--iidfile**=*ImageIDfile* + +Write the image ID to the file. + +**--ipc**=*how* + +Sets the configuration for IPC namespaces when handling `RUN` instructions. +The configured value can be "" (the empty string) or "container" to indicate +that a new IPC namespace should be created, or it can be "host" to indicate +that the IPC namespace in which `podman` itself is being run should be reused, +or it can be the path to an IPC namespace which is already in use by +another process. + +**--isolation**=*type* + +Controls what type of isolation is used for running processes as part of `RUN` +instructions. Recognized types include *oci* (OCI-compatible runtime, the +default), *rootless* (OCI-compatible runtime invoked using a modified +configuration and its --rootless flag enabled, with *--no-new-keyring +--no-pivot* added to its *create* invocation, with network and UTS namespaces +disabled, and IPC, PID, and user namespaces enabled; the default for +unprivileged users), and *chroot* (an internal wrapper that leans more toward +chroot(1) than container technology). + +Note: You can also override the default isolation type by setting the +BUILDAH\_ISOLATION environment variable. `export BUILDAH_ISOLATION=oci` + +**--label**=*label* + +Add an image *label* (e.g. label=*value*) to the image metadata. Can be used multiple times. + +**--layers** + +Cache intermediate images during the build process (Default is `true`). + +Note: You can also override the default value of layers by setting the BUILDAH\_LAYERS +environment variable. `export BUILDAH_LAYERS=true` + +**--logfile**=*filename* + +Log output which would be sent to standard output and standard error to the +specified file instead of to standard output and standard error. + +**--loglevel** *number* + +Adjust the logging level up or down. Valid option values range from -2 to 3, +with 3 being roughly equivalent to using the global *--debug* option, and +values below 0 omitting even error messages which accompany fatal errors. + +**--memory**, **-m**=*LIMIT* +Memory limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +Allows you to constrain the memory available to a container. If the host +supports swap memory, then the **-m** memory setting can be larger than physical +RAM. If a limit of 0 is specified (not using **-m**), the container's memory is +not limited. The actual limit may be rounded up to a multiple of the operating +system's page size (the value would be very large, that's millions of trillions). + +**--memory-swap**=*LIMIT* + +A limit value equal to memory plus swap. Must be used with the **-m** +(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** +(**--memory**) value. By default, the swap `LIMIT` will be set to double +the value of --memory. + +The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), +`k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a +unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. + +**--net**, **--network**=*string* + +Sets the configuration for network namespaces when handling `RUN` instructions. +The configured value can be "" (the empty string) or "container" to indicate +that a new network namespace should be created, or it can be "host" to indicate +that the network namespace in which `podman` itself is being run should be +reused, or it can be the path to a network namespace which is already in use by +another process. + +**--no-cache** + +Do not use existing cached images for the container build. Build from the start with a new set of cached layers. + +**--pid**=*pid* + +Sets the configuration for PID namespaces when handling `RUN` instructions. +The configured value can be "" (the empty string) or "container" to indicate +that a new PID namespace should be created, or it can be "host" to indicate +that the PID namespace in which `podman` itself is being run should be reused, +or it can be the path to a PID namespace which is already in use by another +process. + +**--platform**="Linux" + +This option has no effect on the build. Other container engines use this option +to control the execution platform for the build (e.g., Windows, Linux) which is +not required for Buildah as it supports only Linux. + +**--pull** + +When the flag is enabled, attempt to pull the latest image from the registries +listed in registries.conf if a local image does not exist or the image is newer +than the one in storage. Raise an error if the image is not in any listed +registry and is not present locally. + +If the flag is disabled (with *--pull=false*), do not pull the image from the +registry, use only the local version. Raise an error if the image is not +present locally. + +Defaults to *true*. + +**--pull-always** + +Pull the image from the first registry it is found in as listed in registries.conf. +Raise an error if not found in the registries, even if the image is present locally. + +**--quiet**, **-q** + +Suppress output messages which indicate which instruction is being processed, +and of progress when pulling images from a registry, and when writing the +output image. + +**--rm**=*true|false* + +Remove intermediate containers after a successful build (default true). + +**--runtime**=*path* + +The *path* to an alternate OCI-compatible runtime, which will be used to run +commands specified by the **RUN** instruction. + +Note: You can also override the default runtime by setting the BUILDAH\_RUNTIME +environment variable. `export BUILDAH_RUNTIME=/usr/local/bin/runc` + +**--runtime-flag**=*flag* + +Adds global flags for the container runtime. To list the supported flags, please +consult the manpages of the selected container runtime (`runc` is the default +runtime, the manpage to consult is `runc(8)`. When the machine is configured +for cgroup V2, the default runtime is `crun`, the manpage to consult is `crun(8)`.). + +Note: Do not pass the leading `--` to the flag. To pass the runc flag `--log-format json` +to podman build, the option given would be `--runtime-flag log-format=json`. + +**--security-opt**=*option* + +Security Options + +- `apparmor=unconfined` : Turn off apparmor confinement for the container +- `apparmor=your-profile` : Set the apparmor confinement profile for the container + +- `label=user:USER` : Set the label user for the container processes +- `label=role:ROLE` : Set the label role for the container processes +- `label=type:TYPE` : Set the label process type for the container processes +- `label=level:LEVEL` : Set the label level for the container processes +- `label=filetype:TYPE` : Set the label file type for the container files +- `label=disable` : Turn off label separation for the container + +- `seccomp=unconfined` : Turn off seccomp confinement for the container +- `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter + +**--shm-size**=*size* + +Size of `/dev/shm`. The format is `<number><unit>`. `number` must be greater than `0`. +Unit is optional and can be `b` (bytes), `k` (kilobytes), `m`(megabytes), or `g` (gigabytes). +If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. + +**--squash** + +Squash all of the image's new layers into a single new layer; any preexisting layers +are not squashed. + +**--squash-all** + +Squash all of the new image's layers (including those inherited from a base image) into a single new layer. + +**--tag**, **-t**=*imageName* + +Specifies the name which will be assigned to the resulting image if the build +process completes successfully. +If _imageName_ does not include a registry name, the registry name *localhost* will be prepended to the image name. + +**--target**=*stageName* + +Set the target build stage to build. When building a Containerfile with multiple build stages, --target +can be used to specify an intermediate build stage by name as the final stage for the resulting image. +Commands after the target stage will be skipped. + +**--tls-verify**=*true|false* + +Require HTTPS and verify certificates when talking to container registries (defaults to true). (Not available for remote commands) + +**--ulimit**=*type*=*soft-limit*[:*hard-limit*] + +Specifies resource limits to apply to processes launched when processing `RUN` instructions. +This option can be specified multiple times. Recognized resource types +include: + "core": maximum core dump size (ulimit -c) + "cpu": maximum CPU time (ulimit -t) + "data": maximum size of a process's data segment (ulimit -d) + "fsize": maximum size of new files (ulimit -f) + "locks": maximum number of file locks (ulimit -x) + "memlock": maximum amount of locked memory (ulimit -l) + "msgqueue": maximum amount of data in message queues (ulimit -q) + "nice": niceness adjustment (nice -n, ulimit -e) + "nofile": maximum number of open files (ulimit -n) + "nproc": maximum number of processes (ulimit -u) + "rss": maximum size of a process's (ulimit -m) + "rtprio": maximum real-time scheduling priority (ulimit -r) + "rttime": maximum amount of real-time execution between blocking syscalls + "sigpending": maximum number of pending signals (ulimit -i) + "stack": maximum stack size (ulimit -s) + +**--userns**=*how* + +Sets the configuration for user namespaces when handling `RUN` instructions. +The configured value can be "" (the empty string) or "container" to indicate +that a new user namespace should be created, it can be "host" to indicate that +the user namespace in which `podman` itself is being run should be reused, or +it can be the path to an user namespace which is already in use by another +process. + +**--userns-uid-map**=*mapping* + +Directly specifies a UID mapping which should be used to set ownership, at the +filesystem level, on the working container's contents. +Commands run when handling `RUN` instructions will default to being run in +their own user namespaces, configured using the UID and GID maps. + +Entries in this map take the form of one or more triples of a starting +in-container UID, a corresponding starting host-level UID, and the number of +consecutive IDs which the map entry represents. + +This option overrides the *remap-uids* setting in the *options* section of +/etc/containers/storage.conf. + +If this option is not specified, but a global --userns-uid-map setting is +supplied, settings from the global option will be used. + +If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-uid-map +are specified, but --userns-gid-map is specified, the UID map will be set to +use the same numeric values as the GID map. + +**--userns-gid-map**=*mapping* + +Directly specifies a GID mapping which should be used to set ownership, at the +filesystem level, on the working container's contents. +Commands run when handling `RUN` instructions will default to being run in +their own user namespaces, configured using the UID and GID maps. + +Entries in this map take the form of one or more triples of a starting +in-container GID, a corresponding starting host-level GID, and the number of +consecutive IDs which the map entry represents. + +This option overrides the *remap-gids* setting in the *options* section of +/etc/containers/storage.conf. + +If this option is not specified, but a global --userns-gid-map setting is +supplied, settings from the global option will be used. + +If none of --userns-uid-map-user, --userns-gid-map-group, or --userns-gid-map +are specified, but --userns-uid-map is specified, the GID map will be set to +use the same numeric values as the UID map. + +**--userns-uid-map-user**=*user* + +Specifies that a UID mapping which should be used to set ownership, at the +filesystem level, on the working container's contents, can be found in entries +in the `/etc/subuid` file which correspond to the specified user. +Commands run when handling `RUN` instructions will default to being run in +their own user namespaces, configured using the UID and GID maps. +If --userns-gid-map-group is specified, but --userns-uid-map-user is not +specified, `podman` will assume that the specified group name is also a +suitable user name to use as the default setting for this option. + +**--userns-gid-map-group**=*group* + +Specifies that a GID mapping which should be used to set ownership, at the +filesystem level, on the working container's contents, can be found in entries +in the `/etc/subgid` file which correspond to the specified group. +Commands run when handling `RUN` instructions will default to being run in +their own user namespaces, configured using the UID and GID maps. +If --userns-uid-map-user is specified, but --userns-gid-map-group is not +specified, `podman` will assume that the specified user name is also a +suitable group name to use as the default setting for this option. + +**--uts**=*how* + +Sets the configuration for UTS namespaces when the handling `RUN` instructions. +The configured value can be "" (the empty string) or "container" to indicate +that a new UTS namespace should be created, or it can be "host" to indicate +that the UTS namespace in which `podman` itself is being run should be reused, +or it can be the path to a UTS namespace which is already in use by another +process. + +**--volume**, **-v**[=*[HOST-DIR:CONTAINER-DIR[:OPTIONS]]*] + + Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman + bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman + container. The `OPTIONS` are a comma delimited list and can be: + + * [rw|ro] + * [z|Z|O] + * [`[r]shared`|`[r]slave`|`[r]private`] + +The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The `HOST-DIR` +must be an absolute path as well. Podman bind-mounts the `HOST-DIR` to the +path you specify. For example, if you supply `/foo` as the host path, +Podman copies the contents of `/foo` to the container filesystem on the host +and bind mounts that into the container. + +You can specify multiple **-v** options to mount one or more mounts to a +container. + +You can add the `:ro` or `:rw` suffix to a volume to mount it read-only or +read-write mode, respectively. By default, the volumes are mounted read-write. +See examples. + + `Labeling Volume Mounts` + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a container. Without a label, the security system might +prevent the processes running inside the container from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the container context, you can add either of two suffixes +`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file +objects on the shared volumes. The `z` option tells Podman that two containers +share the volume content. As a result, Podman labels the content with a shared +content label. Shared volume labels allow all containers to read/write content. +The `Z` option tells Podman to label the content with a private unshared label. +Only the current container can use a private volume. + + `Overlay Volume Mounts` + + The `:O` flag tells Podman to mount the directory from the host as a temporary storage using the Overlay file system. The `RUN` command containers are allowed to modify contents within the mountpoint and are stored in the container storage in a separate directory. In Overlay FS terms the source directory will be the lower, and the container storage directory will be the upper. Modifications to the mount point are destroyed when the `RUN` command finishes executing, similar to a tmpfs mount point. + + Any subsequent execution of `RUN` commands sees the original source directory content, any changes from previous RUN commands no longer exists. + + One use case of the `overlay` mount is sharing the package cache from the host into the container to allow speeding up builds. + + Note: + + - Overlay mounts are not currently supported in rootless mode. + - The `O` flag is not allowed to be specified with the `Z` or `z` flags. Content mounted into the container is labeled with the private label. + On SELinux systems, labels in the source directory needs to be readable by the container label. If not, SELinux container separation must be disabled for the container to work. + - Modification of the directory volume mounted into the container with an overlay mount can cause unexpected failures. It is recommended that you do not modify the directory until the container finishes running. + +By default bind mounted volumes are `private`. That means any mounts done +inside container will not be visible on the host and vice versa. This behavior can +be changed by specifying a volume mount propagation property. + +When the mount propagation policy is set to `shared`, any mounts completed inside +the container on that volume will be visible to both the host and container. When +the mount propagation policy is set to `slave`, one way mount propagation is enabled +and any mounts completed on the host for that volume will be visible only inside of the container. +To control the mount propagation property of volume use the `:[r]shared`, +`:[r]slave` or `:[r]private` propagation flag. The propagation property can +be specified only for bind mounted volumes and not for internal volumes or +named volumes. For mount propagation to work on the source mount point (mount point +where source dir is mounted on) has to have the right propagation properties. For +shared volumes, the source mount point has to be shared. And for slave volumes, +the source mount has to be either shared or slave. + +Use `df <source-dir>` to determine the source mount and then use +`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to determine propagation +properties of source mount, if `findmnt` utility is not available, the source mount point +can be determined by looking at the mount entry in `/proc/self/mountinfo`. Look +at `optional fields` and see if any propagation properties are specified. +`shared:X` means the mount is `shared`, `master:X` means the mount is `slave` and if +nothing is there that means the mount is `private`. + +To change propagation properties of a mount point use the `mount` command. For +example, to bind mount the source directory `/foo` do +`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This +will convert /foo into a `shared` mount point. The propagation properties of the source +mount can be changed directly. For instance if `/` is the source mount for +`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. + +## EXAMPLES + +### Build an image using local Containerfiles + +``` +$ podman build . + +$ podman build -f Containerfile.simple . + +$ cat ~/Dockerfile | podman build -f - . + +$ podman build -f Dockerfile.simple -f Containerfile.notsosimple . + +$ podman build -f Dockerfile.in ~ + +$ podman build -t imageName . + +$ podman build --tls-verify=true -t imageName -f Dockerfile.simple . + +$ podman build --tls-verify=false -t imageName . + +$ podman build --runtime-flag log-format=json . + +$ podman build --runtime-flag debug . + +$ podman build --authfile /tmp/auths/myauths.json --cert-dir ~/auth --tls-verify=true --creds=username:password -t imageName -f Dockerfile.simple . + +$ podman build --memory 40m --cpu-period 10000 --cpu-quota 50000 --ulimit nofile=1024:1028 -t imageName . + +$ podman build --security-opt label=level:s0:c100,c200 --cgroup-parent /path/to/cgroup/parent -t imageName . + +$ podman build --volume /home/test:/myvol:ro,Z -t imageName . + +$ podman build -v /var/lib/yum:/var/lib/yum:O -t imageName . + +$ podman build --layers -t imageName . + +$ podman build --no-cache -t imageName . + +$ podman build --layers --force-rm -t imageName . + +$ podman build --no-cache --rm=false -t imageName . +``` + +### Building an image using a URL, Git repo, or archive + + The build context directory can be specified as a URL to a Containerfile, a Git repository, or URL to an archive. If the URL is a Containerfile, it is downloaded to a temporary location and used as the context. When a Git repository is set as the URL, the repository is cloned locally to a temporary location and then used as the context. Lastly, if the URL is an archive, it is downloaded to a temporary location and extracted before being used as the context. + +#### Building an image using a URL to a Containerfile + + Podman will download the Containerfile to a temporary location and then use it as the build context. + +``` +$ podman build https://10.10.10.1/podman/Containerfile +``` + +#### Building an image using a Git repository + + Podman will clone the specified GitHub repository to a temporary location and use it as the context. The Containerfile at the root of the repository will be used and it only works if the GitHub repository is a dedicated repository. + +``` +$ podman build git://github.com/scollier/purpletest +``` + +#### Building an image using a URL to an archive + + Podman will fetch the archive file, decompress it, and use its contents as the build context. The Containerfile at the root of the archive and the rest of the archive will get used as the context of the build. If you pass `-f PATH/Containerfile` option as well, the system will look for that file inside the contents of the archive. + +``` +$ podman build -f dev/Containerfile https://10.10.10.1/podman/context.tar.gz +``` + + Note: supported compression formats are 'xz', 'bzip2', 'gzip' and 'identity' (no compression). + +## Files + +**registries.conf** (`/etc/containers/registries.conf`) + +registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. + +## Troubleshooting + +If you are using a useradd command within a Containerfile with a large UID/GID, it will create a large sparse file `/var/log/lastlog`. This can cause the build to hang forever. Go language does not support sparse files correctly, which can lead to some huge files being created in your container image. + +### Solution + +If you are using `useradd` within your build script, you should pass the `--no-log-init or -l` option to the `useradd` command. This option tells useradd to stop creating the lastlog file. + +## SEE ALSO +podman(1), buildah(1), containers-registries.conf(5), crun(8), runc(8), useradd(8) + +## HISTORY +May 2018, Minor revisions added by Joe Doss <joe@solidadmin.com> + +December 2017, Originally compiled by Tom Sweeney <tsweeney@redhat.com> diff --git a/docs/source/man/podman-commit.1.md b/docs/source/man/podman-commit.1.md new file mode 100644 index 000000000..07a885ae2 --- /dev/null +++ b/docs/source/man/podman-commit.1.md @@ -0,0 +1,93 @@ +% podman-commit(1) + +## NAME +podman\-commit - Create new image based on the changed container + +## SYNOPSIS +**podman commit** [*options*] *container* *image* + +**podman container commit** [*options*] *container* *image* + +## DESCRIPTION +**podman commit** creates an image based on a changed container. The author of the +image can be set using the `--author` flag. Various image instructions can be +configured with the `--change` flag and a commit message can be set using the +`--message` flag. The container and its processes are paused while the image is +committed. This minimizes the likelihood of data corruption when creating the new +image. If this is not desired, the `--pause` flag can be set to false. When the commit +is complete, Podman will print out the ID of the new image. + +If *image* does not begin with a registry name component, `localhost` will be added to the name. + +## OPTIONS + +**--author**, **-a**=*author* + +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** + +Can be set multiple times + +**--format**, **-f**=*format* + +Set the format of the image manifest and metadata. The currently supported formats are _oci_ and _docker_. If +not specifically set, the default format used is _oci_. + +**--iidfile**=*ImageIDfile* + +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` and `podman run` commands. + +**--message**, **-m**=*message* + +Set commit message for committed image. The message field is not supported in _oci_ format. + +**--pause**, **-p** + +Pause the container when creating an image + +**--quiet**, **-q** + +Suppress output + +## EXAMPLES + +``` +$ podman commit --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change LABEL=blue=image reverent_golick image-committed +Getting image source signatures +Copying blob sha256:b41deda5a2feb1f03a5c1bb38c598cbc12c9ccd675f438edc6acd815f7585b86 + 25.80 MB / 25.80 MB [======================================================] 0s +Copying config sha256:c16a6d30f3782288ec4e7521c754acc29d37155629cb39149756f486dae2d4cd + 448 B / 448 B [============================================================] 0s +Writing manifest to image destination +Storing signatures +e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8 +``` + +``` +$ podman commit -q --message "committing container to image" reverent_golick image-committed +e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8 +``` + +``` +$ podman commit -q --author "firstName lastName" reverent_golick image-committed +e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8 +``` + +``` +$ podman commit -q --pause=false containerID image-committed +e3ce4d93051ceea088d1c242624d659be32cf1667ef62f1d16d6b60193e2c7a8 +``` + +## SEE ALSO +podman(1), podman-run(1), podman-create(1) + +## HISTORY +December 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-container-checkpoint.1.md b/docs/source/man/podman-container-checkpoint.1.md new file mode 100644 index 000000000..034d338bb --- /dev/null +++ b/docs/source/man/podman-container-checkpoint.1.md @@ -0,0 +1,65 @@ +% podman-container-checkpoint(1) + +## NAME +podman\-container\-checkpoint - Checkpoints one or more running containers + +## SYNOPSIS +**podman container checkpoint** [*options*] *container* ... + +## DESCRIPTION +Checkpoints all the processes in one or more containers. You may use container IDs or names as input. + +## OPTIONS +**--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. + +**--all**, **-a** + +Checkpoint all running containers. + +**--latest**, **-l** + +Instead of providing the container name or ID, checkpoint the last created container. + +The latest option is not supported on the remote client. + +**--leave-running**, **-R** + +Leave the container running after checkpointing instead of stopping it. + +**--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. + +**--export, -e** + +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** + +**--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. + +## EXAMPLE + +podman container checkpoint mywebserver + +podman container checkpoint 860a4b23 + +## SEE ALSO +podman(1), podman-container-restore(1) + +## HISTORY +September 2018, Originally compiled by Adrian Reber <areber@redhat.com> diff --git a/docs/source/man/podman-container-cleanup.1.md b/docs/source/man/podman-container-cleanup.1.md new file mode 100644 index 000000000..69e21ce9f --- /dev/null +++ b/docs/source/man/podman-container-cleanup.1.md @@ -0,0 +1,41 @@ +% podman-container-cleanup(1) + +## NAME +podman\-container\-cleanup - Cleanup the container's network and mountpoints + +## SYNOPSIS +**podman container cleanup** [*options*] *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. + +## OPTIONS + +**--all**, **a** + +Cleanup all containers. + +**--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 latest option is not supported on the remote client. + +## EXAMPLE + +`podman container cleanup mywebserver` + +`podman container cleanup mywebserver myflaskserver 860a4b23` + +`podman container cleanup 860a4b23` + +`podman container cleanup -a` + +`podman container cleanup --latest` + +## SEE ALSO +podman(1), podman-container(1) + +## HISTORY +Jun 2018, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-container-exists.1.md b/docs/source/man/podman-container-exists.1.md new file mode 100644 index 000000000..4d988132b --- /dev/null +++ b/docs/source/man/podman-container-exists.1.md @@ -0,0 +1,42 @@ +% podman-container-exists(1) + +## NAME +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. + +## OPTIONS + +**-h**, **--help** +Print usage statement + +## Examples + +Check if an container called `webclient` exists in local storage (the container does actually exist). +``` +$ sudo podman container exists webclient +$ echo $? +0 +$ +``` + +Check if an container called `webbackend` exists in local storage (the container does not actually exist). +``` +$ sudo podman container exists webbackend +$ echo $? +1 +$ +``` + +## SEE ALSO +podman(1) + +## HISTORY +November 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-container-prune.1.md b/docs/source/man/podman-container-prune.1.md new file mode 100644 index 000000000..d8a4b7f4e --- /dev/null +++ b/docs/source/man/podman-container-prune.1.md @@ -0,0 +1,35 @@ +% podman-container-prune(1) + +## NAME +podman-container-prune - Remove all stopped containers from local storage + +## SYNOPSIS +**podman container prune** [*options*] + +## DESCRIPTION +**podman container prune** removes all stopped containers from local storage. + +## OPTIONS + +**-h**, **--help** + +Print usage statement + +## Examples + +Remove all stopped containers from local storage +``` +$ sudo podman container prune +878392adf2e6c5c9bb1fc19b69d37d2e98c8abf9d539c0bce4b15b46bbcce471 +37664467fbe3618bf9479c34393ac29c02696675addf1750f9e346581636cde7 +ed0c6468b8e1cb641b4621d1fe30cb477e1fefc5c0bceb66feaf2f7cb50e5962 +6ac6c8f0067b7a4682e6b8e18902665b57d1a0e07e885d9abcd382232a543ccd +fff1c5b6c3631746055ec40598ce8ecaa4b82aef122f9e3a85b03b55c0d06c23 +602d343cd47e7cb3dfc808282a9900a3e4555747787ec6723bb68cedab8384d5 +``` + +## SEE ALSO +podman(1), podman-ps + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-container-restore.1.md b/docs/source/man/podman-container-restore.1.md new file mode 100644 index 000000000..1d2cf0b3e --- /dev/null +++ b/docs/source/man/podman-container-restore.1.md @@ -0,0 +1,89 @@ +% podman-container-restore(1) + +## NAME +podman\-container\-restore - Restores one or more containers from a checkpoint + +## SYNOPSIS +**podman container restore** [*options*] *container* ... + +## DESCRIPTION +Restores a container from a checkpoint. You may use container IDs or names as input. + +## OPTIONS +**--keep**, **-k** + +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. + +**--latest**, **-l** + +Instead of providing the container name or ID, restore the last created container. + +The latest option is not supported on the remote 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. + +**--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**. + +**--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. + +**--ignore-static-ip** + +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**. + +Using **--ignore-static-ip** tells Podman to ignore the IP address if it was configured +with **--ip** during container creation. + +## EXAMPLE + +podman container restore mywebserver + +podman container restore 860a4b23 + +## SEE ALSO +podman(1), podman-container-checkpoint(1) + +## HISTORY +September 2018, Originally compiled by Adrian Reber <areber@redhat.com> diff --git a/docs/source/man/podman-container-runlabel.1.md b/docs/source/man/podman-container-runlabel.1.md new file mode 100644 index 000000000..8511dd5cd --- /dev/null +++ b/docs/source/man/podman-container-runlabel.1.md @@ -0,0 +1,122 @@ +% podman-container-runlabel(1) + +## NAME +podman-container-runlabel - Executes a command as described by a container image label + +## SYNOPSIS +**podman container runlabel** [*options*] *label* *image* [*arg...*] + +## DESCRIPTION +**podman container runlabel** reads the provided `LABEL` field in the container +IMAGE and executes the provided value for the label as a command. If this field does not +exist, `podman container runlabel` will just exit. + +If the container image has a LABEL INSTALL instruction like the following: + +`LABEL INSTALL /usr/bin/podman run -t -i --rm \${OPT1} --privileged -v /:/host --net=host --ipc=host --pid=host -e HOST=/host -e NAME=\${NAME} -e IMAGE=\${IMAGE} -e CONFDIR=\/etc/${NAME} -e LOGDIR=/var/log/\${NAME} -e DATADIR=/var/lib/\${NAME} \${IMAGE} \${OPT2} /bin/install.sh \${OPT3}` + +`podman container runlabel` will set the following environment variables for use in the command: + +If the container image does not have the desired label, an error message will be displayed along with a non-zero +return code. If the image is not found in local storage, Podman will attempt to pull it first. + +**LABEL** +The label name specified via the command. + +**IMAGE** +Image name specified via the command. + +**SUDO_UID** +The `SUDO_UID` environment variable. This is useful with the podman +`-u` option for user space tools. If the environment variable is +not available, the value of `/proc/self/loginuid` is used. + +**SUDO_GID** +The `SUDO_GID` environment variable. This is useful with the podman +`-u` option for user space tools. If the environment variable is +not available, the default GID of the value for `SUDO_UID` is used. +If this value is not available, the value of `/proc/self/loginuid` +is used. + +Any additional arguments will be appended to the command. + +## OPTIONS: +**--authfile**=*path* + +Path of the authentication file. Default is ${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`. (Not available for remote commands) + +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` + +**--display** + +Display the label's value of the image having populated its environment variables. +The runlabel command will not execute if --display is specified. + +**--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--creds**=*[username[:password]]* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +**--help**, **-h** +Print usage statement + +**--name**, **-n**=*name* + +Use this name for creating content for the container. NAME will default to the IMAGENAME if it is not specified. + +**--quiet**, **-q** + +Suppress output information when pulling images + +**--replace** + +If a container exists of the default or given name, as needed it will be stopped, deleted and a new container will be +created from this image. + +**--rootfs**=*ROOTFS* + +Set rootfs + +**--set**=*NAME*=*VALUE* + +Set name & value + +**--storage** +Use storage + +**--tls-verify** + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to 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 (Not available for remote commands) + +## Examples + +Execute the run label of an image called foobar. +``` +$ sudo podman container runlabel run foobar +``` + +Execute the install label of an image called foobar with additional arguments. +``` +$ sudo podman container runlabel install foobar apples oranges +``` + +Display the command that would be executed by runlabel. +``` +$ sudo podman container runlabel --display run foobar +``` + +## SEE ALSO +podman(1) + +## HISTORY +September 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-container.1.md b/docs/source/man/podman-container.1.md new file mode 100644 index 000000000..4ea7c7acc --- /dev/null +++ b/docs/source/man/podman-container.1.md @@ -0,0 +1,49 @@ +% podman-container(1) + +## NAME +podman\-container - Manage containers + +## SYNOPSIS +**podman container** *subcommand* + +## DESCRIPTION +The container command allows you to manage containers + +## COMMANDS + +| Command | Man Page | Description | +| --------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | +| attach | [podman-attach(1)](podman-attach.1.md) | Attach to a running container. | +| checkpoint | [podman-container-checkpoint(1)](podman-container-checkpoint.1.md) | Checkpoints one or more running containers. | +| cleanup | [podman-container-cleanup(1)](podman-container-cleanup.1.md) | Cleanup the container's network and mountpoints. | +| commit | [podman-commit(1)](podman-commit.1.md) | Create new image based on the changed container. | +| cp | [podman-cp(1)](podman-cp.1.md) | Copy files/folders between a container and the local filesystem. | +| create | [podman-create(1)](podman-create.1.md) | Create a new container. | +| diff | [podman-diff(1)](podman-diff.1.md) | Inspect changes on a container or image's filesystem. | +| exec | [podman-exec(1)](podman-exec.1.md) | Execute a command in a running container. | +| exists | [podman-container-exists(1)](podman-container-exists.1.md) | Check if a container exists in local storage | +| export | [podman-export(1)](podman-export.1.md) | Export a container's filesystem contents as a tar archive. | +| init | [podman-init(1)](podman-init.1.md) | Initialize a container | +| inspect | [podman-inspect(1)](podman-inspect.1.md) | Display a container or image's configuration. | +| kill | [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. | +| list | [podman-ps(1)](podman-ps.1.md) | List the containers on the system.(alias ls) | +| logs | [podman-logs(1)](podman-logs.1.md) | Display the logs of a container. | +| mount | [podman-mount(1)](podman-mount.1.md) | Mount a working container's root filesystem. | +| pause | [podman-pause(1)](podman-pause.1.md) | Pause one or more containers. | +| port | [podman-port(1)](podman-port.1.md) | List port mappings for the container. | +| prune | [podman-container-prune(1)](podman-container-prune.1.md)| Remove all stopped containers from local storage. | +| restart | [podman-restart(1)](podman-restart.1.md) | Restart one or more containers. | +| restore | [podman-container-restore(1)](podman-container-restore.1.md) | Restores one or more containers from a checkpoint. | +| rm | [podman-rm(1)](podman-rm.1.md) | Remove one or more containers. | +| run | [podman-run(1)](podman-run.1.md) | Run a command in a container. | +| runlabel | [podman-container-runlabel(1)](podman-container-runlabel.1.md) | Executes a command as described by a container image label. | +| start | [podman-start(1)](podman-start.1.md) | Starts one or more containers. | +| stats | [podman-stats(1)](podman-stats.1.md) | Display a live stream of one or more container's resource usage statistics. | +| stop | [podman-stop(1)](podman-stop.1.md) | Stop one or more running containers. | +| top | [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | +| umount | [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem.(Alias unmount) | +| 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. | + +## SEE ALSO +podman, podman-exec, podman-run diff --git a/docs/source/man/podman-cp.1.md b/docs/source/man/podman-cp.1.md new file mode 100644 index 000000000..0f54b2e8b --- /dev/null +++ b/docs/source/man/podman-cp.1.md @@ -0,0 +1,120 @@ +% podman-cp(1) + +## NAME +podman\-cp - Copy files/folders between a container and the local filesystem + +## SYNOPSIS +**podman cp** [*options*] [*container*:]*src_path* [*container*:]*dest_path* + +**podman container cp** [*options*] [*container*:]*src_path* [*container*:]*dest_path* + +## DESCRIPTION +Copies the contents of **src_path** to the **dest_path**. You can copy from the container's filesystem to the local machine or the reverse, from the local filesystem to the container. +If - is specified for either the SRC_PATH or DEST_PATH, you can also stream a tar archive from STDIN or to STDOUT. + +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 / + - Error condition: the destination directory must exist. + - **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` + +## OPTIONS + +**--extract** + +Extract the tar file into the destination directory. If the destination directory is not provided, extract the tar file into the root directory. + +**--pause** + +Pause the container while copying into it to avoid potential security issues around symlinks. Defaults to *true*. On rootless containers with cgroups V1, defaults to false. + +## 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. + +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: + + mnt=$(podman mount CONTAINERID) + cp -R ${mnt}/etc/foobar /tmp + podman umount CONTAINERID + +If you want to untar a tar ball into a container, you can execute these commands: + + mnt=$(podman mount CONTAINERID) + tar xf content.tgz -C ${mnt} + podman umount CONTAINERID + +One last example, if you want to install a package into a container that +does not have dnf installed, you could execute something like: + + mnt=$(podman mount CONTAINERID) + dnf install --installroot=${mnt} httpd + chroot ${mnt} rm -rf /var/log/dnf /var/cache/dnf + podman umount CONTAINERID + +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/ + +podman cp --extract /home/myuser/myfiles.tar.gz containerID:/myfiles + +podman cp - containerID:/myfiles.tar.gz < myfiles.tar.gz + +## SEE ALSO +podman(1), podman-mount(1), podman-umount(1) diff --git a/docs/source/man/podman-create.1.md b/docs/source/man/podman-create.1.md new file mode 100644 index 000000000..6617850fd --- /dev/null +++ b/docs/source/man/podman-create.1.md @@ -0,0 +1,1010 @@ +% podman-create(1) + +## NAME +podman\-create - Create a new container + +## SYNOPSIS +**podman create** [*options*] *image* [*command* [*arg* ...]] + +**podman container create** [*options*] *image* [*command* [*arg* ...]] + +## DESCRIPTION + +Creates a writable container layer over the specified image and prepares it for +running the specified command. The container ID is then printed to STDOUT. This +is similar to **podman run -d** except the container is never started. You can +then use the **podman start** *container* command to start the container at +any point. + +The initial status of the container created with **podman create** is 'created'. + +## OPTIONS +**--add-host**=*host* + +Add a custom host-to-IP mapping (host:ip) + +Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** +option can be set multiple times. + +**--annotation**=*key=value* + +Add an annotation to the container. The format is key=value. +The **--annotation** option can be set multiple times. + +**--attach**, **-a**=*location* + +Attach to STDIN, STDOUT or STDERR. + +In foreground mode (the default when **-d** +is not specified), **podman run** can start the process in the container +and attach the console to the process's standard input, output, and standard +error. It can even pretend to be a TTY (this is what most commandline +executables expect) and pass along signals. The **-a** option can be set for +each of stdin, stdout, and stderr. + +**--authfile**=*path* + +Path of the authentication file. Default is ${XDG_\RUNTIME\_DIR}/containers/auth.json + +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` (Not available for remote commands) + +**--blkio-weight**=*weight* + +Block IO weight (relative weight) accepts a weight value between 10 and 1000. + +**--blkio-weight-device**=*weight* + +Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). + +**--cap-add**=*capability* + +Add Linux capabilities + +**--cap-drop**=*capability* + +Drop Linux capabilities + +**--cgroupns**=*mode* + +Set the cgroup namespace mode for the container, by default **host** is used. + **host**: use the host's cgroup namespace inside the container. + **container:<NAME|ID>**: join the namespace of the specified container. + **private**: create a new cgroup namespace. + **ns:<PATH>**: join the namespace at the specified path. + +**--cgroups**=*mode* + +Determines whether the container will create CGroups. +Valid values are *enabled* and *disabled*, which the default being *enabled*. +The *disabled* option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). + +**--cgroup-parent**=*path* + +Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. + +**--cidfile**=*id* + +Write the container ID to the file + +**--conmon-pidfile**=*path* + +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**=*limit* + +Limit the number of CPUs available for execution by the container. + +On Windows Server containers, this is approximated as a percentage of total CPU usage. + +On Windows Server containers, the processor resource controls are mutually exclusive, the order of precedence is CPUCount first, then CPUShares, and CPUPercent last. + +**--cpu-period**=*limit* + +Limit the CPU CFS (Completely Fair Scheduler) period + +Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. + +**--cpu-quota**=*limit* + +Limit the CPU CFS (Completely Fair Scheduler) quota + +Limit the container's CPU usage. By default, containers run with the full +CPU resource. This flag tell the kernel to restrict the container's CPU usage +to the quota you specify. + +**--cpu-rt-period**=*microseconds* + +Limit the CPU real-time period in microseconds + +Limit the container's Real Time CPU usage. This flag tell the kernel to restrict the container's Real Time CPU usage to the period you specify. + +**--cpu-rt-runtime**=*microseconds* + +Limit the CPU real-time runtime in microseconds + +Limit the containers Real Time CPU usage. This flag tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: +Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. + +The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. + +**--cpu-shares**=*shares* + +CPU shares (relative weight) + +By default, all containers get the same proportion of CPU cycles. This proportion +can be modified by changing the container's CPU share weighting relative +to the weighting of all other running containers. + +To modify the proportion from the default of 1024, use the **--cpu-shares** +flag to set the weighting to 2 or higher. + +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. + +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fourth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container **{C0}** with **-c=512** running one process, and another container +**{C1}** with **-c=1024** running two processes, this can result in the following +division of CPU shares: + +PID container CPU CPU share +100 {C0} 0 100% of CPU0 +101 {C1} 1 100% of CPU1 +102 {C1} 2 100% of CPU2 + +**--cpus**=*number* + +Number of CPUs. The default is *0.0* which means no limit. + +**--cpuset-cpus**=*cpus* + +CPUs in which to allow execution (0-3, 0,1) + +**--cpuset-mems**=*nodes* + +Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + +If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` +then processes in your container will only use memory from the first +two memory nodes. + +**--detach**, **-d**=*true|false* + +Detached mode: run the container in the background and print the new container ID. The default is *false*. + +At any time you can run **podman ps** in +the other shell to view a list of the running containers. You can reattach to a +detached container with **podman attach**. + +When attached in the tty mode, you can detach from the container (and leave it +running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. +Configure the keys sequence using the **--detach-keys** option, or specifying +it in the **libpod.conf** file: see **libpod.conf(5)** for more information. + +**--detach-keys**=*sequence* + +Override the key sequence for detaching a container. Format is a single character `[a-Z]` or +a comma separated sequence of `ctrl-<value>`, where `<value>` is one of: +`a-z`, `@`, `^`, `[`, `\\`, `]`, `^` or `_`. + +**--device**=*device* + +Add a host device to the container. The format is `<device-on-host>[:<device-on-container>][:<permissions>]` (e.g. --device=/dev/sdc:/dev/xvdc:rwm) + +**--device-read-bps**=*path* + +Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) + +**--device-read-iops**=*path* + +Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000) + +**--device-write-bps**=*path* + +Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) + +**--device-write-iops**=*path* + +Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000) + +**--dns**=*dns* + +Set custom DNS servers. Invalid if using **--dns** and **--network** that is set to 'none' or 'container:<name|id>'. + +This option can be used to override the DNS +configuration passed to the container. Typically this is necessary when the +host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this +is the case the **--dns** flags is necessary for every run. + +The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman. +The **/etc/resolv.conf** file in the image will be used without changes. + +**--dns-option**=*option* + +Set custom DNS options. Invalid if using **--dns-option** and **--network** that is set to 'none' or 'container:<name|id>'. + +**--dns-search**=*domain* + +Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to 'none' or 'container:<name|id>'. (Use --dns-search=. if you don't wish to set the search domain) + +**--entrypoint**=*"command"* | *'["command", "arg1", ...]'* + +Overwrite the default ENTRYPOINT of the image + +This option allows you to overwrite the default entrypoint of the image. +The ENTRYPOINT of an image is similar to a COMMAND +because it specifies what executable to run when the container starts, but it is +(purposely) more difficult to override. The ENTRYPOINT gives a container its +default nature or behavior, so that when you set an ENTRYPOINT you can run the +container as if it were that binary, complete with default options, and you can +pass in more options via the COMMAND. But, sometimes an operator may want to run +something else inside the container, so you can override the default ENTRYPOINT +at runtime by using a **--entrypoint** and a string to specify the new +ENTRYPOINT. + +You need to specify multi option commands in the form of a json string. + +**--env**, **-e**=*env* + +Set environment variables + +This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. If an environment variable ending in __*__ is specified, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. If an environment variable with a trailing ***** is specified, then a value must be supplied. + +See [**Environment**](#environment) note below for precedence and examples. + +**--env-host**=*true|false* + +Use host environment inside of the container. See **Environment** note below for precedence. + +**--env-file**=*file* + +Read in a line delimited file of environment variables. See **Environment** note below for precedence. + +**--expose**=*port* + +Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection +on the host system. + +**--gidmap**=*container_gid:host_gid:amount* + +GID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subgidname` flags. + +The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host. `--gidmap=0:30000:2000` + +**--group-add**=*group* + +Add additional groups to run as + +**--health-cmd**=*"command"* | *'["command", "arg1", ...]'* + +Set or alter a healthcheck command for a container. The command is a command to be executed inside your +container that determines your container health. The command is required for other healthcheck options +to be applied. A value of `none` disables existing healthchecks. + +Multiple options can be passed in the form of a JSON array; otherwise, the command will be interpreted +as an argument to `/bin/sh -c`. + +**--health-interval**=*interval* + +Set an interval for the healthchecks (a value of `disable` results in no automatic timer setup) (default "30s") + +**--health-retries**=*retries* + +The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is `3`. + +**--health-start-period**=*period* + +The initialization time needed for a container to bootstrap. The value can be expressed in time format like +`2m3s`. The default value is `0s` + +**--health-timeout**=*timeout* + +The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the +value can be expressed in a time format such as `1m22s`. The default value is `30s`. + +**--hostname**=*name* + +Container host name + +Sets the container host name that is available inside the container. + +**--help** + +Print usage statement + +**--http-proxy**=*true|false* + +By default proxy environment variables are passed into the container if set +for the Podman process. This can be disabled by setting the `--http-proxy` +option to `false`. The environment variables passed in include `http_proxy`, +`https_proxy`, `ftp_proxy`, `no_proxy`, and also the upper case versions of +those. This option is only needed when the host system must use a proxy but +the container should not use any proxy. Proxy environment variables specified +for the container in any other way will override the values that would have +been passed thru from the host. (Other ways to specify the proxy for the +container include passing the values with the `--env` flag, or hard coding the +proxy environment at container build time.) + +For example, to disable passing these environment variables from host to +container: + +`--http-proxy=false` + +Defaults to `true` + +**--image-volume**, **builtin-volume**=*bind|tmpfs|ignore* + +Tells Podman how to handle the builtin image volumes. The options are: 'bind', 'tmpfs', or 'ignore' (default 'bind'). +bind: A directory is created inside the container state directory and bind mounted into +the container for the volumes. +tmpfs: The volume is mounted onto the container as a tmpfs, which allows the users to create +content that disappears when the container is stopped. +ignore: All volumes are just ignored and no action is taken. + +**--init** + +Run an init inside the container that forwards signals and reaps processes. + +**--init-path**=*path* + +Path to the container-init binary. + +**--interactive**, **i**=*true|false* + +Keep STDIN open even if not attached. The default is *false*. + +**--ip6**=*ip* + +Not implemented + +**--ip**=*ip* + +Specify a static IP address for the container, for example '10.88.64.128'. +Can only be used if no additional CNI networks to join were specified via '--network=<network-name>', and if the container is not joining another container's network namespace via '--network=container:<name|id>'. +The address must be within the default CNI network's pool (default 10.88.0.0/16). + +**--ipc**=*ipc* + +Default is to create a private IPC namespace (POSIX SysV IPC) for the container + 'container:<name|id>': reuses another container shared memory, semaphores and message queues + 'host': use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. + 'ns:<path>' path to an IPC namespace to join. + +**--kernel-memory**=*number[unit]* + +Kernel memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +Constrains the kernel memory available to a container. If a limit of 0 +is specified (not using `--kernel-memory`), the container's kernel memory +is not limited. If you specify a limit, it may be rounded up to a multiple +of the operating system's page size and the value can be very large, +millions of trillions. + +**--label**, **-l**=*label* + +Add metadata to a container (e.g., --label com.example.key=value) + +**--label-file**=*file* + +Read in a line delimited file of labels + +**--link-local-ip**=*ip* + +Not implemented + +**--log-driver**="*k8s-file*" + +Logging driver for the container. Currently available options are *k8s-file* and *journald*, with *json-file* aliased to *k8s-file* for scripting compatibility. + +**--log-opt**=*path* + +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**=*address* + +Container MAC address (e.g. 92:d0:c6:0a:29:33) + +Remember that the MAC address in an Ethernet network must be unique. +The IPv6 link-local address will be based on the device's MAC address +according to RFC4862. + +Not currently supported + +**--memory**, **-m**=*limit* + +Memory limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +Allows you to constrain the memory available to a container. If the host +supports swap memory, then the **-m** memory setting can be larger than physical +RAM. If a limit of 0 is specified (not using **-m**), the container's memory is +not limited. The actual limit may be rounded up to a multiple of the operating +system's page size (the value would be very large, that's millions of trillions). + +**--memory-reservation**=*limit* + +Memory soft limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +After setting memory reservation, when the system detects memory contention +or low memory, containers are forced to restrict their consumption to their +reservation. So you should always set the value below **--memory**, otherwise the +hard limit will take precedence. By default, memory reservation will be the same +as memory limit. + +**--memory-swap**=*limit* + +A limit value equal to memory plus swap. Must be used with the **-m** +(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** +(**--memory**) value. By default, the swap `LIMIT` will be set to double +the value of --memory. + +The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), +`k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a +unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. + +**--memory-swappiness**=*number* + +Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + +**--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* + +Attach a filesystem mount to the container + +Current supported mount TYPES are `bind`, `volume`, and `tmpfs`. + + e.g. + + type=bind,source=/path/on/host,destination=/path/in/container + + type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared + + type=volume,source=vol1,destination=/path/in/container,ro=true + + type=tmpfs,tmpfs-size=512M,destination=/path/in/container + + Common Options: + + · src, source: mount source spec for bind and volume. Mandatory for bind. + + · dst, destination, target: mount destination spec. + + · ro, read-only: true or false (default). + + Options specific to bind: + + · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2). + + . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. + + . relabel: shared, private. + + Options specific to tmpfs: + + · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. + + · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. + +**--name**=*name* + +Assign a name to the container + +The operator can identify a container in three ways: +UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) +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 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. + +**--network**, **--net**="*bridge*" + +Set the Network mode for the container. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** that is set to 'none' or 'container:<name|id>'. + +Valid values are: + +- `bridge`: create a network stack on the default bridge +- `none`: no networking +- `container:<name|id>`: reuse another container's network stack +- `host`: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. +- `<network-name>|<network-id>`: connect to a user-defined network, multiple networks should be comma separated +- `ns:<path>`: path to a network namespace to join +- `slirp4netns`: use slirp4netns to create a user network stack. This is the default for rootless containers + +**--network-alias**=*alias* + +Not implemented + +**--no-hosts**=*true|false* + +Do not create /etc/hosts for the container. +By default, Podman will manage /etc/hosts, adding the container's own IP address and any hosts from **--add-host**. +**--no-hosts** disables this, and the image's **/etc/host** will be preserved unmodified. +This option conflicts with **--add-host**. + +**--oom-kill-disable**=*true|false* + +Whether to disable OOM Killer for the container or not. + +**--oom-score-adj**=*num* + +Tune the host's OOM preferences for containers (accepts -1000 to 1000) + +**--pid**=*pid* + +Set the PID mode for the container +Default is to create a private PID namespace for the container + 'container:<name|id>': join another container's PID namespace + 'host': use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure. + 'ns': join the specified PID namespace + +**--pids-limit**=*limit* + +Tune the container's pids limit. Set `0` to have unlimited pids for the container. (default "4096" on systems that support PIDS cgroups). + +**--pod**=*name* + +Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`. +To make a pod with more granular options, use the `podman pod create` command before creating a container. + +**--privileged**=*true|false* + +Give extended privileges to this container. The default is *false*. + +By default, Podman containers are +“unprivileged” (=false) and cannot, for example, modify parts of the kernel. +This is because by default a container is not allowed to access any devices. +A “privileged” container is given access to all devices. + +When the operator executes a privileged container, Podman enables access +to all devices on the host, turns off graphdriver mount options, as well as +turning off most of the security measures protecting the host from the +container. + +**--publish**, **-p**=*port* + +Publish a container's port, or range of ports, to the host + +Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort` +Both hostPort and containerPort can be specified as a range of ports. +When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. +(e.g., `podman run -p 1234-1236:1222-1224 --name thisWorks -t busybox` +but not `podman run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox`) +With ip: `podman run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage` +Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT` + +**--publish-all**, **-P**=*true|false* + +Publish all exposed ports to random ports on the host interfaces. The default is *false*. + +When set to true publish all exposed ports to the host interfaces. The +default is false. If the operator uses -P (or -p) then Podman will make the +exposed port accessible on the host and the ports will be available to any +client that can reach the host. When using -P, Podman will bind any exposed +port to a random port on the host within an *ephemeral port range* defined by +`/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host +ports and the exposed ports, use `podman port`. + +**--pull**=*missing* + +Pull image before creating ("always"|"missing"|"never") (default "missing"). + 'missing': default value, attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally. + 'always': Pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally. + 'never': do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally. + +Defaults to *missing*. + +**--quiet**, **-q** + +Suppress output information when pulling images + +**--read-only**=*true|false* + +Mount the container's root filesystem as read only. + +By default a container will have its root filesystem writable allowing processes +to write files anywhere. By specifying the `--read-only` flag the container will have +its root filesystem mounted as read only prohibiting any writes. + +**--read-only-tmpfs**=*true|false* + +If container is running in --read-only mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The default is *true* + +**--restart**=*policy* + +Restart policy to follow when containers exit. +Restart policy will not take effect if a container is stopped via the `podman kill` or `podman stop` commands. + +Valid values are: + +- `no` : Do not restart containers on exit +- `on-failure[:max_retries]` : Restart containers when they exit with a non-0 exit code, retrying indefinitely or until the optional max_retries count is hit +- `always` : Restart containers when they exit, regardless of status, retrying indefinitely + +Please note that restart will not restart containers after a system reboot. +If this functionality is required in your environment, you can invoke Podman from a systemd unit file, or create an init script for whichever init system is in use. +To generate systemd unit files, please see *podman generate systemd* + +**--rm**=*true|false* + +Automatically remove the container when it exits. The default is *false*. + +Note that the container will not be removed when it could not be created or +started successfully. This allows the user to inspect the container after +failure. + +**--rootfs** + +If specified, the first argument refers to an exploded container on the file system. + +This is useful to run a container without requiring any image management, the rootfs +of the container is assumed to be managed externally. + +**--security-opt**=*option* + +Security Options + +- `apparmor=unconfined` : Turn off apparmor confinement for the container +- `apparmor=your-profile` : Set the apparmor confinement profile for the container + +- `label=user:USER` : Set the label user for the container processes +- `label=role:ROLE` : Set the label role for the container processes +- `label=type:TYPE` : Set the label process type for the container processes +- `label=level:LEVEL` : Set the label level for the container processes +- `label=filetype:TYPE` : Set the label file type for the container files +- `label=disable` : Turn off label separation for the container + +- `no-new-privileges` : Disable container processes from gaining additional privileges + +- `seccomp=unconfined` : Turn off seccomp confinement for the container +- `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter + +Note: Labeling can be disabled for all containers by setting label=false in the **libpod.conf** (`/etc/containers/libpod.conf`) file. + +**--shm-size**=*size* + +Size of `/dev/shm` (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) +If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. +When size is `0`, there is no limit on the amount of memory used for IPC by the container. + +**--stop-signal**=*SIGTERM* + +Signal to stop a container. Default is SIGTERM. + +**--stop-timeout**=*seconds* + +Timeout (in seconds) to stop a container. Default is 10. + +**--subgidname**=*name* + +Name for GID map from the `/etc/subgid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--gidmap`. + +**--subuidname**=*name* + +Name for UID map from the `/etc/subuid` file. Using this flag will run the container with user namespace enabled. This flag conflicts with `--userns` and `--uidmap`. + +**--sysctl**=*SYSCTL* + +Configure namespaced kernel parameters at runtime + +IPC Namespace - current sysctls allowed: + +kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced +Sysctls beginning with fs.mqueue.* + +Note: if you use the --ipc=host option these sysctls will not be allowed. + +Network Namespace - current sysctls allowed: + Sysctls beginning with net.* + +Note: if you use the --network=host option these sysctls will not be allowed. + +**--systemd**=*true|false|always* + +Run container in systemd mode. The default is *true*. + +The value *always* enforces the systemd mode is enforced without +looking at the executable name. Otherwise, if set to true and the +command you are running inside the container is systemd, /usr/sbin/init +or /sbin/init. + +If the command you are running inside of the container is systemd, +Podman will setup tmpfs mount points in the following directories: + +/run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal + +It will also set the default stop signal to SIGRTMIN+3. + +This allow systemd to run in a confined container without any modifications. + +Note: On `SELinux` systems, systemd attempts to write to the cgroup +file system. Containers writing to the cgroup file system are denied by default. +The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system. + +`setsebool -P container_manage_cgroup true` + +**--tmpfs**=*fs* + +Create a tmpfs mount + +Mount a temporary filesystem (`tmpfs`) mount into a container, for example: + +$ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image + +This command mounts a `tmpfs` at `/tmp` within the container. The supported mount +options are the same as the Linux default `mount` flags. If you do not specify +any options, the systems uses the following options: +`rw,noexec,nosuid,nodev`. + +**--tty**, **-t**=*true|false* + +Allocate a pseudo-TTY. The default is *false*. + +When set to true Podman will allocate a pseudo-tty and attach to the standard +input of the container. This can be used, for example, to run a throwaway +interactive shell. The default is false. + +Note: The **-t** option is incompatible with a redirection of the Podman client +standard input. + +**--uidmap**=*container_uid:host_uid:amount* + +UID map for the user namespace. Using this flag will run the container with user namespace enabled. It conflicts with the `--userns` and `--subuidname` flags. + +The following example maps uids 0-2000 in the container to the uids 30000-31999 on the host and gids 0-2000 in the container to the gids 30000-31999 on the host. `--uidmap=0:30000:2000` + +**--ulimit**=*option* + +Ulimit options + +You can pass `host` to copy the current configuration from the host. + +**--user**, **-u**=*user* + +Sets the username or UID used and optionally the groupname or GID for the specified command. + +The followings examples are all valid: +--user [user | user:group | uid | uid:gid | user:gid | uid:group ] + +Without this argument the command will be run as root in the container. + +**--userns**=*host* +**--userns**=*keep-id* +**--userns**=container:container +**--userns**=*ns:my_namespace* + +Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled. + +- `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. +- `keep-id`: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user. +- `ns`: run the container in the given existing user namespace. +- `container`: join the user namespace of the specified container. + +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 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**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] + +Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the podman +container. The `OPTIONS` are a comma delimited list and can be: + +* [rw|ro] +* [z|Z] +* [`[r]shared`|`[r]slave`|`[r]private`] + +The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume +will be mounted into the container at this directory. + +Volumes may specify a source as well, as either a directory on the host or the +name of a named volume. If no source is given, the volume will be created as an +anonymous named volume with a randomly generated name, and will be removed when +the container is removed via the `--rm` flag or `podman rm --volumes`. + +If a volume source is specified, it must be a path on the host or the name of a +named volume. Host paths are allowed to be absolute or relative; relative paths +are resolved relative to the directory Podman is run in. Any source that does +not begin with a `.` or `/` it will be treated as the name of a named volume. +If a volume with that name does not exist, it will be created. Volumes created +with names are not anonymous and are not removed by `--rm` and +`podman rm --volumes`. + +You can specify multiple **-v** options to mount one or more volumes into a +container. + +You can add `:ro` or `:rw` suffix to a volume to mount it read-only or +read-write mode, respectively. By default, the volumes are mounted read-write. +See examples. + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a container. Without a label, the security system might +prevent the processes running inside the container from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the container context, you can add either of two suffixes +`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file +objects on the shared volumes. The `z` option tells Podman that two containers +share the volume content. As a result, Podman labels the content with a shared +content label. Shared volume labels allow all containers to read/write content. +The `Z` option tells Podman to label the content with a private unshared label. +Only the current container can use a private volume. + +By default bind mounted volumes are `private`. That means any mounts done +inside container will not be visible on host and vice versa. One can change +this behavior by specifying a volume mount propagation property. Making a +volume `shared` mounts done under that volume inside container will be +visible on host and vice versa. Making a volume `slave` enables only one +way mount propagation and that is mounts done on host under that volume +will be visible inside container but not the other way around. + +To control mount propagation property of volume one can use `:[r]shared`, +`:[r]slave` or `:[r]private` propagation flag. Propagation property can +be specified only for bind mounted volumes and not for internal volumes or +named volumes. For mount propagation to work source mount point (mount point +where source dir is mounted on) has to have right propagation properties. For +shared volumes, source mount point has to be shared. And for slave volumes, +source mount has to be either shared or slave. + +Use `df <source-dir>` to figure out the source mount and then use +`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation +properties of source mount. If `findmnt` utility is not available, then one +can look at mount entry for source mount point in `/proc/self/mountinfo`. Look +at `optional fields` and see if any propagation properties are specified. +`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if +nothing is there that means mount is `private`. + +To change propagation properties of a mount point use `mount` command. For +example, if one wants to bind mount source directory `/foo` one can do +`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This +will convert /foo into a `shared` mount point. Alternatively one can directly +change propagation properties of source mount. Say `/` is source mount for +`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. + +**--volumes-from**[=*CONTAINER*[:*OPTIONS*]] + +Mount volumes from the specified container(s). +*OPTIONS* is a comma delimited list with the following available elements: + +* [rw|ro] +* z + +Mounts already mounted volumes from a source container onto another +container. You must supply the source's container-id or container-name. +To share a volume, use the --volumes-from option when running +the target container. You can share volumes even if the source container +is not running. + +By default, Podman mounts the volumes in the same mode (read-write or +read-only) as it is mounted in the source container. Optionally, you +can change this by suffixing the container-id with either the `ro` or +`rw` keyword. + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a container. Without a label, the security system might +prevent the processes running inside the container from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the container context, you can add `z` to the volume mount. +This suffix tells Podman to relabel file objects on the shared volumes. The `z` +option tells Podman that two containers share the volume content. As a result, +podman labels the content with a shared content label. Shared volume labels allow +all containers to read/write content. + +If the location of the volume from the source container overlaps with +data residing on a target container, then the volume hides +that data on the target. + +**--workdir**, **-w**=*dir* + +Working directory inside the container + +The default working directory for running binaries within a container is the root directory (/). +The image developer can set a different default with the WORKDIR instruction. The operator +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 + +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 +``` + +### 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. + +## ENVIRONMENT + +Environment variables within containers can be set using multiple different options: This section describes the precedence. + +Precedence Order: + **--env-host** : Host environment of the process executing Podman is added. + + Container image : Any environment variables specified in the container image. + + **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. + + **--env** : Any environment variables specified will override previous settings. + +Create containers and set the environment ending with a __*__ and a ***** + +``` +$ export ENV1=a +$ podman create --name ctr --env ENV* alpine printenv ENV1 +$ podman start --attach ctr +a + +$ podman create --name ctr --env ENV*****=b alpine printenv ENV***** +$ podman start --attach ctr +b +``` + +## FILES + +**/etc/subuid** +**/etc/subgid** + +## SEE ALSO +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> + +November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> + +September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> + +August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> diff --git a/docs/source/man/podman-diff.1.md b/docs/source/man/podman-diff.1.md new file mode 100644 index 000000000..5b0434a07 --- /dev/null +++ b/docs/source/man/podman-diff.1.md @@ -0,0 +1,55 @@ +% podman-diff(1) + +## NAME +podman\-diff - Inspect changes on a container or image's filesystem + +## SYNOPSIS +**podman diff** [*options*] *name* + +**podman container diff** [*options*] *name* + +## DESCRIPTION +Displays changes on a container or image's filesystem. The container or image will be compared to its parent layer + +## OPTIONS + +**--format** + +Alter the output into a different format. The only valid format for diff is `json`. + +**--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 latest option is not supported on the remote client. + +## EXAMPLE + +``` +# podman diff redis:alpine +C /usr +C /usr/local +C /usr/local/bin +A /usr/local/bin/docker-entrypoint.sh +``` + +``` +# podman diff --format json redis:alpine +{ + "changed": [ + "/usr", + "/usr/local", + "/usr/local/bin" + ], + "added": [ + "/usr/local/bin/docker-entrypoint.sh" + ] +} +``` + +## SEE ALSO +podman(1) + +## HISTORY +August 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/man/podman-events.1.md b/docs/source/man/podman-events.1.md new file mode 100644 index 000000000..bb1923574 --- /dev/null +++ b/docs/source/man/podman-events.1.md @@ -0,0 +1,154 @@ +% podman-events(1) + +## NAME +podman\-events - Monitor Podman events + +## SYNOPSIS +**podman events** [*options*] + +## DESCRIPTION + +Monitor and print events that occur in Podman. Each event will include a timestamp, +a type, a status, name (if applicable), and image (if applicable). The default logging +mechanism is *journald*. This can be changed in libpod.conf by changing the `events_logger` +value to `file`. Only `file` and `journald` are accepted. A `none` logger is also +available but this logging mechanism completely disables events; nothing will be reported by +`podman events`. + +The *container* event type will report the follow statuses: + * attach + * checkpoint + * cleanup + * commit + * create + * exec + * export + * import + * init + * kill + * mount + * pause + * prune + * remove + * restart + * restore + * start + * stop + * sync + * unmount + * unpause + +The *pod* event type will report the follow statuses: + * create + * kill + * pause + * remove + * start + * stop + * unpause + +The *image* event type will report the following statuses: + * prune + * pull + * push + * remove + * save + * tag + * untag + +The *system* type will report the following statuses: + * refresh + * renumber + +The *volume* type will report the following statuses: + * create + * prune + * remove + + +## OPTIONS + +**--help** + +Print usage statement. + +**--format** + +Format the output to JSON Lines or using the given Go template. + + +**--filter**=*filter* + +Filter events that are displayed. They must be in the format of "filter=value". The following +filters are supported: + * container=name_or_id + * event=event_status (described above) + * image=name_or_id + * pod=name_or_id + * volume=name_or_id + * type=event_type (described above) + +In the case where an ID is used, the ID may be in its full or shortened form. + +**--since**=*timestamp* + +Show all events created since the given timestamp + + +**--until**=*timestamp* + +Show all events created until the given timestamp + +The *since* and *until* values can be RFC3339Nano time stamps or a Go duration string such as 10m, 5h. If no +*since* or *until* values are provided, only new events will be shown. + +## EXAMPLES + +Showing Podman events +``` +$ podman events +2019-03-02 10:33:42.312377447 -0600 CST container create 34503c192940 (image=docker.io/library/alpine:latest, name=friendly_allen) +2019-03-02 10:33:46.958768077 -0600 CST container init 34503c192940 (image=docker.io/library/alpine:latest, name=friendly_allen) +2019-03-02 10:33:46.973661968 -0600 CST container start 34503c192940 (image=docker.io/library/alpine:latest, name=friendly_allen) +2019-03-02 10:33:50.833761479 -0600 CST container stop 34503c192940 (image=docker.io/library/alpine:latest, name=friendly_allen) +2019-03-02 10:33:51.047104966 -0600 CST container cleanup 34503c192940 (image=docker.io/library/alpine:latest, name=friendly_allen) +``` + +Show only Podman create events +``` +$ podman events --filter event=create +2019-03-02 10:36:01.375685062 -0600 CST container create 20dc581f6fbf (image=docker.io/library/alpine:latest, name=sharp_morse) +2019-03-02 10:36:08.561188337 -0600 CST container create 58e7e002344c (image=k8s.gcr.io/pause:3.1, name=3e701f270d54-infra) +2019-03-02 10:36:13.146899437 -0600 CST volume create cad6dc50e087 (image=, name=cad6dc50e0879568e7d656bd004bd343d6035e7fc4024e1711506fe2fd459e6f) +2019-03-02 10:36:29.978806894 -0600 CST container create d81e30f1310f (image=docker.io/library/busybox:latest, name=musing_newton) +``` + +Show only Podman pod create events +``` +$ podman events --filter event=create --filter type=pod +2019-03-02 10:44:29.601746633 -0600 CST pod create 1df5ebca7b44 (image=, name=confident_hawking) +2019-03-02 10:44:42.374637304 -0600 CST pod create ca731231718e (image=, name=webapp) +2019-03-02 10:44:47.486759133 -0600 CST pod create 71e807fc3a8e (image=, name=reverent_swanson) +``` + +Show only Podman events created in the last five minutes: +``` +$ sudo podman events --since 5m +2019-03-02 10:44:29.598835409 -0600 CST container create b629d10d3831 (image=k8s.gcr.io/pause:3.1, name=1df5ebca7b44-infra) +2019-03-02 10:44:29.601746633 -0600 CST pod create 1df5ebca7b44 (image=, name=confident_hawking) +2019-03-02 10:44:42.371100253 -0600 CST container create 170a0f457d00 (image=k8s.gcr.io/pause:3.1, name=ca731231718e-infra) +2019-03-02 10:44:42.374637304 -0600 CST pod create ca731231718e (image=, name=webapp) +``` + +Show Podman events in JSON Lines format +``` +events --format json +{"ID":"683b0909d556a9c02fa8cd2b61c3531a965db42158627622d1a67b391964d519","Image":"localhost/myshdemo:latest","Name":"agitated_diffie","Status":"cleanup","Time":"2019-04-27T22:47:00.849932843-04:00","Type":"container"} +{"ID":"a0f8ab051bfd43f9c5141a8a2502139707e4b38d98ac0872e57c5315381e88ad","Image":"docker.io/library/alpine:latest","Name":"friendly_tereshkova","Status":"unmount","Time":"2019-04-28T13:43:38.063017276-04:00","Type":"container"} +``` + +## SEE ALSO +podman(1) + +## HISTORY +March 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-exec.1.md b/docs/source/man/podman-exec.1.md new file mode 100644 index 000000000..4c17c056a --- /dev/null +++ b/docs/source/man/podman-exec.1.md @@ -0,0 +1,100 @@ +% podman-exec(1) + +## NAME +podman\-exec - Execute a command in a running container + +## SYNOPSIS +**podman exec** [*options*] *container* [*command* [*arg* ...]] + +**podman container exec** [*options*] *container* [*command* [*arg* ...]] + +## DESCRIPTION +**podman exec** executes a command in a running container. + +## OPTIONS + +**--detach-keys**=*sequence* + +Override the key sequence for detaching a container. Format is a single character `[a-Z]` or `ctrl-<value>` where `<value>` is one of: `a-z`, `@`, `^`, `[`, `,` or `_`. + +**--env**, **-e** + +You may specify arbitrary environment variables that are available for the +command to be executed. + +**--interactive**, **-i**=*true|false* + +When set to true, keep stdin open even if not attached. The default is *false*. + +**--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 latest option is not supported on the remote client. + +**--preserve-fds**=*N* + +Pass down to the process N additional file descriptors (in addition to 0, 1, 2). The total FDs will be 3+N. + +**--privileged** + +Give the process extended Linux capabilities when running the command in container. + +**--tty**, **-t** + +Allocate a pseudo-TTY. + +**--user**, **-u** + +Sets the username or UID used and optionally the groupname or GID for the specified command. +The following examples are all valid: +--user [user | user:group | uid | uid:gid | user:gid | uid:group ] + +**--workdir**, **-w**=*path* + +Working directory inside the container + +The default working directory for running binaries within a container is the root directory (/). +The image developer can set a different default with the WORKDIR instruction, which can be overridden +when creating the container. + +## Exit Status + +The exit code from `podman exec` gives information about why the command within the container failed to run or why it exited. When `podman exec` exits with a +non-zero code, the exit codes follow the `chroot` standard, see below: + +**_125_** if the error is with Podman **_itself_** + + $ podman exec --foo ctrID /bin/sh; echo $? + Error: unknown flag: --foo + 125 + +**_126_** if the **_contained command_** cannot be invoked + + $ podman exec ctrID /etc; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error + 126 + +**_127_** if the **_contained command_** cannot be found + + $ podman exec ctrID foo; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error + 127 + +**_Exit code_** of **_contained command_** otherwise + + $ podman exec ctrID /bin/sh -c 'exit 3' + # 3 + +## EXAMPLES + +$ podman exec -it ctrID ls +$ podman exec -it -w /tmp myCtr pwd +$ podman exec --user root ctrID ls + +## SEE ALSO +podman(1), podman-run(1) + +## HISTORY +December 2017, Originally compiled by Brent Baude<bbaude@redhat.com> diff --git a/docs/source/man/podman-export.1.md b/docs/source/man/podman-export.1.md new file mode 100644 index 000000000..4286d0e2f --- /dev/null +++ b/docs/source/man/podman-export.1.md @@ -0,0 +1,45 @@ +% podman-export(1) + +## NAME +podman\-export - Export a container's filesystem contents as a tar archive + +## SYNOPSIS +**podman export** [*options*] *container* + +**podman container export** [*options*] *container* + +## DESCRIPTION +**podman export** exports the filesystem of a container and saves it as a tarball +on the local machine. **podman export** writes to STDOUT by default and can be +redirected to a file using the `--output` flag. +Note: `:` is a restricted character and cannot be part of the file name. + +**podman [GLOBAL OPTIONS]** + +**podman export [GLOBAL OPTIONS]** + +**podman export [OPTIONS] CONTAINER** + +## OPTIONS + +**--output**, **-o** + +Write to a file, default is STDOUT + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman export -o redis-container.tar 883504668ec465463bc0fe7e63d53154ac3b696ea8d7b233748918664ea90e57 + +$ podman export 883504668ec465463bc0fe7e63d53154ac3b696ea8d7b233748918664ea90e57 > redis-container.tar +``` + +## SEE ALSO +podman(1), podman-import(1) + +## HISTORY +August 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-generate-kube.1.md b/docs/source/man/podman-generate-kube.1.md new file mode 100644 index 000000000..f4b4cd482 --- /dev/null +++ b/docs/source/man/podman-generate-kube.1.md @@ -0,0 +1,150 @@ +% podman-generate-kube(1) +## NAME +podman-generate-kube - Generate Kubernetes YAML based on a pod or container + +## SYNOPSIS +**podman generate kube** [*options*] *container* | *pod* + +## DESCRIPTION +**podman generate kube** will generate Kubernetes Pod YAML (v1 specification) from a Podman container or pod. Whether +the input is for a container or pod, Podman will always generate the specification as a Pod. The input may be in the form +of a pod or container name or ID. + +Note that the generated Kubernetes YAML file can be used to re-run the deployment via podman-play-kube(1). + +## OPTIONS: + +**--filename**, **-f**=**filename** + +Output to the given file, instead of STDOUT. If the file already exists, `generate kube` will refuse to replace it and return an error. + +**--service**, **-s** + +Generate a Kubernetes service object in addition to the Pods. Used to generate a Service specification for the corresponding Pod output. In particular, if the object has portmap bindings, the service specification will include a NodePort declaration to expose the service. A +random port is assigned by Podman in the specification. + +## Examples + +Create Kubernetes Pod YAML for a container called `some-mariadb` . +``` +$ sudo podman generate kube some-mariadb +# Generation of Kubenetes YAML is still under development! +# +# Save the output of this file and use kubectl create -f to import +# it into Kubernetes. +# +# Created with podman-0.11.2-dev +apiVersion: v1 +kind: Pod +metadata: + creationTimestamp: 2018-12-03T19:07:59Z + labels: + app: some-mariadb + name: some-mariadb-libpod +spec: + containers: + - command: + - docker-entrypoint.sh + - mysqld + env: + - name: PATH + value: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + - name: TERM + value: xterm + - name: HOSTNAME + - name: container + value: podman + - name: GOSU_VERSION + value: "1.10" + - name: GPG_KEYS + value: "199369E5404BD5FC7D2FE43BCBCB082A1BB943DB \t177F4010FE56CA3336300305F1656F24C74CD1D8 + \t430BDF5C56E7C94E848EE60C1C4CBDCDCD2EFD2A \t4D1BB29D63D98E422B2113B19334A25F8507EFA5" + - name: MARIADB_MAJOR + value: "10.3" + - name: MARIADB_VERSION + value: 1:10.3.10+maria~bionic + - name: MYSQL_ROOT_PASSWORD + value: x + image: quay.io/baude/demodb:latest + name: some-mariadb + ports: + - containerPort: 3306 + hostPort: 36533 + protocol: TCP + resources: {} + securityContext: + allowPrivilegeEscalation: true + privileged: false + readOnlyRootFilesystem: false + tty: true + workingDir: / +status: {} +``` + +Create Kubernetes Pod YAML for a pod called `demoweb` and include a service. +``` +$ sudo podman generate kube -s demoweb +# Generation of Kubernetes YAML is still under development! +# +# Save the output of this file and use kubectl create -f to import +# it into Kubernetes. +# +# Created with podman-0.12.2-dev +apiVersion: v1 +kind: Pod +metadata: + creationTimestamp: 2018-12-18T15:16:06Z + labels: + app: demoweb + name: demoweb-libpod +spec: + containers: + - command: + - python3 + - /root/code/graph.py + env: + - name: PATH + value: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin + - name: TERM + value: xterm + - name: HOSTNAME + - name: container + value: podman + image: quay.io/baude/demoweb:latest + name: practicalarchimedes + resources: {} + securityContext: + allowPrivilegeEscalation: true + capabilities: {} + privileged: false + readOnlyRootFilesystem: false + tty: true + workingDir: /root/code +status: {} +--- +apiVersion: v1 +kind: Service +metadata: + creationTimestamp: 2018-12-18T15:16:06Z + labels: + app: demoweb + name: demoweb-libpod +spec: + ports: + - name: "8050" + nodePort: 31269 + port: 8050 + protocol: TCP + targetPort: 0 + selector: + app: demoweb + type: NodePort +status: + loadBalancer: {} +``` + +## SEE ALSO +podman(1), podman-container(1), podman-pod(1), podman-play-kube(1) + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-generate-systemd.1.md b/docs/source/man/podman-generate-systemd.1.md new file mode 100644 index 000000000..b81e68a46 --- /dev/null +++ b/docs/source/man/podman-generate-systemd.1.md @@ -0,0 +1,96 @@ +% podman-generate-systemd(1) + +## NAME +podman\-generate\-systemd - Generate systemd unit file(s) for a container. Not supported for the remote client + +## SYNOPSIS +**podman generate systemd** [*options*] *container|pod* + +## DESCRIPTION +**podman generate systemd** will create a systemd unit file that can be used to control a container or pod. +By default, the command will print the content of the unit files to stdout. + +Note that this command is not supported for the remote client. + +## OPTIONS: + +**--files**, **-f** + +Generate files instead of printing to stdout. The generated files are named {container,pod}-{ID,name}.service and will be placed in the current working directory. + +**--name**, **-n** + +Use the name of the container for the start, stop, and description in the unit file + +**--timeout**, **-t**=*value* + +Override the default stop timeout for the container with the given value. + +**--restart-policy**=*policy* +Set the systemd restart policy. The restart-policy must be one of: "no", "on-success", "on-failure", "on-abnormal", +"on-watchdog", "on-abort", or "always". The default policy is *on-failure*. + +## Examples + +Create and print a systemd unit file for a container running nginx with an *always* restart policy and 1-second timeout to stdout. +``` +$ podman create --name nginx nginx:latest +$ podman generate systemd --restart-policy=always -t 1 nginx +# container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service +# autogenerated by Podman 1.5.2 +# Wed Aug 21 09:46:45 CEST 2019 + +[Unit] +Description=Podman container-de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6.service +Documentation=man:podman-generate-systemd(1) + +[Service] +Restart=always +ExecStart=/usr/bin/podman start de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 +ExecStop=/usr/bin/podman stop -t 1 de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6 +KillMode=none +Type=forking +PIDFile=/run/user/1000/overlay-containers/de1e3223b1b888bc02d0962dd6cb5855eb00734061013ffdd3479d225abacdc6/userdata/conmon.pid + +[Install] +WantedBy=multi-user.target +``` + +Create systemd unit files for a pod with two simple alpine containers. Note that these container services cannot be started or stopped individually via `systemctl`; they are managed by the pod service. You can still use `systemctl status` or journalctl to examine them. +``` +$ podman pod create --name systemd-pod +$ podman create --pod systemd-pod alpine top +$ podman create --pod systemd-pod alpine top +$ podman generate systemd --files --name systemd-pod +/home/user/pod-systemd-pod.service +/home/user/container-amazing_chandrasekhar.service +/home/user/container-jolly_shtern.service +$ cat pod-systemd-pod.service +# pod-systemd-pod.service +# autogenerated by Podman 1.5.2 +# Wed Aug 21 09:52:37 CEST 2019 + +[Unit] +Description=Podman pod-systemd-pod.service +Documentation=man:podman-generate-systemd(1) +Requires=container-amazing_chandrasekhar.service container-jolly_shtern.service +Before=container-amazing_chandrasekhar.service container-jolly_shtern.service + +[Service] +Restart=on-failure +ExecStart=/usr/bin/podman start 77a818221650-infra +ExecStop=/usr/bin/podman stop -t 10 77a818221650-infra +KillMode=none +Type=forking +PIDFile=/run/user/1000/overlay-containers/ccfd5c71a088768774ca7bd05888d55cc287698dde06f475c8b02f696a25adcd/userdata/conmon.pid + +[Install] +WantedBy=multi-user.target +``` + +## SEE ALSO +podman(1), podman-container(1), systemctl(1), systemd.unit(5), systemd.service(5) + +## HISTORY +August 2019, Updated with pod support by Valentin Rothberg (rothberg at redhat dot com) +April 2019, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-generate.1.md b/docs/source/man/podman-generate.1.md new file mode 100644 index 000000000..50050f2c1 --- /dev/null +++ b/docs/source/man/podman-generate.1.md @@ -0,0 +1,21 @@ +% podman-generate(1) + +## NAME +podman\-generate - Generate structured data based for a containers and pods + +## SYNOPSIS +**podman generate** *subcommand* + +## DESCRIPTION +The generate command will create structured output (like YAML) based on a container or pod. + +## COMMANDS + +| Command | Man Page | Description | +|---------|------------------------------------------------------------|-------------------------------------------------------------------------------------| +| kube | [podman-generate-kube(1)](podman-generate-kube.1.md) | Generate Kubernetes YAML based on a pod or container. | +| systemd | [podman-generate-systemd(1)](podman-generate-systemd.1.md) | Generate systemd unit file(s) for a container. Not supported for the remote client. | + + +## SEE ALSO +podman, podman-pod, podman-container diff --git a/docs/source/man/podman-healthcheck-run.1.md b/docs/source/man/podman-healthcheck-run.1.md new file mode 100644 index 000000000..21f2d9b20 --- /dev/null +++ b/docs/source/man/podman-healthcheck-run.1.md @@ -0,0 +1,39 @@ +% podman-healthcheck-run(1) + +## NAME +podman\-healthcheck\-run - Run a container healthcheck + +## SYNOPSIS +**podman healthcheck run** [*options*] *container* + +## DESCRIPTION + +Runs the healthcheck command defined in a running container manually. The resulting error codes are defined +as follows: + +* 0 = healthcheck command succeeded +* 1 = healthcheck command failed +* 125 = an error has occurred + +Possible errors that can occur during the healthcheck are: +* unable to find the container +* container has no defined healthcheck +* container is not running + +## OPTIONS +**--help** + +Print usage statement + + +## EXAMPLES + +``` +$ podman healthcheck run mywebapp +``` + +## SEE ALSO +podman-healthcheck(1) + +## HISTORY +Feb 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-healthcheck.1.md b/docs/source/man/podman-healthcheck.1.md new file mode 100644 index 000000000..91c3e4345 --- /dev/null +++ b/docs/source/man/podman-healthcheck.1.md @@ -0,0 +1,22 @@ +% podman-healthcheck(1) + +## NAME +podman\-healthcheck - Manage healthchecks for containers + +## SYNOPSIS +**podman healthcheck** *subcommand* + +## DESCRIPTION +podman healthcheck is a set of subcommands that manage container healthchecks + +## SUBCOMMANDS + +| Command | Man Page | Description | +| ------- | ------------------------------------------------- | ------------------------------------------------------------------------------ | +| run | [podman-healthcheck-run(1)](podman-healthcheck-run.1.md) | Run a container healthcheck | + +## SEE ALSO +podman(1) + +## HISTORY +Feb 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-history.1.md b/docs/source/man/podman-history.1.md new file mode 100644 index 000000000..a67cb0286 --- /dev/null +++ b/docs/source/man/podman-history.1.md @@ -0,0 +1,98 @@ +% podman-history(1) + +## NAME +podman\-history - Show the history of an image + +## SYNOPSIS +**podman history** [*options*] *image*[:*tag*|@*digest*] + +**podman image history** [*options*] *image*[:*tag*|@*digest*] + +## DESCRIPTION +**podman history** displays the history of an image by printing out information +about each layer used in the image. The information printed out for each layer +include Created (time and date), Created By, Size, and Comment. The output can +be truncated or not using the **--no-trunc** flag. If the **--human** flag is +set, the time of creation and size are printed out in a human readable format. +The **--quiet** flag displays the ID of the image only when set and the **--format** +flag is used to print the information using the Go template provided by the user. + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | ----------------------------------------------------------------------------- | +| .ID | Image ID | +| .Created | if **--human**, time elapsed since creation, otherwise time stamp of creation | +| .CreatedBy | Command used to create the layer | +| .Size | Size of layer on disk | +| .Comment | Comment for the layer | + +## OPTIONS + +**--human**, **-H** + +Display sizes and dates in human readable format + +**--no-trunc** + +Do not truncate the output + +**--quiet**, **-q** + +Print the numeric IDs only + +**--format**=*format* + +Alter the output for a format like 'json' or a Go template. + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman history debian +ID CREATED CREATED BY SIZE COMMENT +b676ca55e4f2c 9 weeks ago /bin/sh -c #(nop) CMD ["bash"] 0 B +<missing> 9 weeks ago /bin/sh -c #(nop) ADD file:ebba725fb97cea4... 45.14 MB +``` + +``` +$ podman history --no-trunc=true --human=false debian +ID CREATED CREATED BY SIZE COMMENT +b676ca55e4f2c 2017-07-24T16:52:55Z /bin/sh -c #(nop) CMD ["bash"] 0 +<missing> 2017-07-24T16:52:54Z /bin/sh -c #(nop) ADD file:ebba725fb97cea4... 45142935 +``` + +``` +$ podman history --format "{{.ID}} {{.Created}}" debian +b676ca55e4f2c 9 weeks ago +<missing> 9 weeks ago +``` + +``` +$ podman history --format json debian +[ + { + "id": "b676ca55e4f2c0ce53d0636438c5372d3efeb5ae99b676fa5a5d1581bad46060", + "created": "2017-07-24T16:52:55.195062314Z", + "createdBy": "/bin/sh -c #(nop) CMD [\"bash\"]", + "size": 0, + "comment": "" + }, + { + "id": "b676ca55e4f2c0ce53d0636438c5372d3efeb5ae99b676fa5a5d1581bad46060", + "created": "2017-07-24T16:52:54.898893387Z", + "createdBy": "/bin/sh -c #(nop) ADD file:ebba725fb97cea45d0b1b35ccc8144e766fcfc9a78530465c23b0c4674b14042 in / ", + "size": 45142935, + "comment": "" + } +] +``` + +## SEE ALSO +podman(1) + +## HISTORY +July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-image-exists.1.md b/docs/source/man/podman-image-exists.1.md new file mode 100644 index 000000000..f6a89e2aa --- /dev/null +++ b/docs/source/man/podman-image-exists.1.md @@ -0,0 +1,43 @@ +% podman-image-exists(1) + +## NAME +podman-image-exists - Check if an image exists in local storage + +## SYNOPSIS +**podman image exists** [*options*] *image* + +## DESCRIPTION +**podman image exists** checks if an image exists in local storage. The **ID** or **Name** +of the image may be used as input. Podman will return an exit code +of `0` when the image is found. A `1` will be returned otherwise. An exit code of `125` indicates there +was an issue accessing the local storage. + +## OPTIONS + +**--help**, **-h** + +Print usage statement + +## Examples + +Check if an image called `webclient` exists in local storage (the image does actually exist). +``` +$ sudo podman image exists webclient +$ echo $? +0 +$ +``` + +Check if an image called `webbackend` exists in local storage (the image does not actually exist). +``` +$ sudo podman image exists webbackend +$ echo $? +1 +$ +``` + +## SEE ALSO +podman(1) + +## HISTORY +November 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-image-prune.1.md b/docs/source/man/podman-image-prune.1.md new file mode 100644 index 000000000..b844a9f63 --- /dev/null +++ b/docs/source/man/podman-image-prune.1.md @@ -0,0 +1,48 @@ +% podman-image-prune(1) + +## NAME +podman-image-prune - Remove all unused images from the local store + +## SYNOPSIS +**podman image prune** [*options*] + +## DESCRIPTION +**podman image prune** removes all dangling images from local storage. With the `all` option, +you can delete all unused images. Unused images are dangling images as well as any image that +does not have any containers based on it. + +## OPTIONS +**--all**, **-a** + +Remove dangling images and images that have no associated containers. + +**--help**, **-h** + +Print usage statement + +## Examples ## + +Remove all dangling images from local storage +``` +$ sudo podman image prune +f3e20dc537fb04cb51672a5cb6fdf2292e61d411315549391a0d1f64e4e3097e +324a7a3b2e0135f4226ffdd473e4099fd9e477a74230cdc35de69e84c0f9d907 +``` + +Remove all unused images from local storage +``` +$ sudo podman image prune -a +f3e20dc537fb04cb51672a5cb6fdf2292e61d411315549391a0d1f64e4e3097e +324a7a3b2e0135f4226ffdd473e4099fd9e477a74230cdc35de69e84c0f9d907 +6125002719feb1ddf3030acab1df6156da7ce0e78e571e9b6e9c250424d6220c +91e732da5657264c6f4641b8d0c4001c218ae6c1adb9dcef33ad00cafd37d8b6 +e4e5109420323221f170627c138817770fb64832da7d8fe2babd863148287fca +77a57fa8285e9656dbb7b23d9efa837a106957409ddd702f995605af27a45ebe + +``` + +## SEE ALSO +podman(1), podman-images + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-image-sign.1.md b/docs/source/man/podman-image-sign.1.md new file mode 100644 index 000000000..62845e715 --- /dev/null +++ b/docs/source/man/podman-image-sign.1.md @@ -0,0 +1,57 @@ +% podman-image-sign(1) + +## NAME +podman-image-sign - Create a signature for an image + +## SYNOPSIS +**podman image sign** [*options*] *image* [*image* ...] + +## DESCRIPTION +**podman image sign** will create a local signature for one or more local images that have +been pulled from a registry. The signature will be written to a directory +derived from the registry configuration files in /etc/containers/registries.d. By default, the signature will be written into /var/lib/containers/sigstore directory. + +## OPTIONS + +**--help**, **-h** + +Print usage statement. + +**--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--directory**, **-d**=*dir* + +Store the signatures in the specified directory. Default: /var/lib/containers/sigstore + +**--sign-by**=*identity* + +Override the default identity of the signature. + +## EXAMPLES +Sign the busybox image with the identify of foo@bar.com with a user's keyring and save the signature in /tmp/signatures/. + + sudo podman image sign --sign-by foo@bar.com --directory /tmp/signatures docker://privateregistry.example.com/foobar + +## RELATED CONFIGURATION + +The write (and read) location for signatures is defined in YAML-based +configuration files in /etc/containers/registries.d/. When you sign +an image, Podman will use those configuration files to determine +where to write the signature based on the the name of the originating +registry or a default storage value unless overriden with the --directory +option. For example, consider the following configuration file. + +docker: + privateregistry.example.com: + sigstore: file:///var/lib/containers/sigstore + +When signing an image preceded with the registry name 'privateregistry.example.com', +the signature will be written into sub-directories of +/var/lib/containers/sigstore/privateregistry.example.com. The use of 'sigstore' also means +the signature will be 'read' from that same location on a pull-related function. + +## HISTORY +November 2018, Originally compiled by Qi Wang (qiwan at redhat dot com) diff --git a/docs/source/man/podman-image-tree.1.md b/docs/source/man/podman-image-tree.1.md new file mode 100644 index 000000000..c4624e05c --- /dev/null +++ b/docs/source/man/podman-image-tree.1.md @@ -0,0 +1,88 @@ +% podman-image-tree(1) + +## NAME +podman\-image\-tree - Prints layer hierarchy of an image in a tree format + +## SYNOPSIS +**podman image tree** [*options*] *image:tag*|*image-id* + + +## DESCRIPTION +Prints layer hierarchy of an image in a tree format. +If you do not provide a *tag*, Podman will default to `latest` for the *image*. +Layers are indicated with image tags as `Top Layer of`, when the tag is known locally. +## OPTIONS + +**--help**, **-h** + +Print usage statement + +**--whatrequires** + +Show all child images and layers of the specified image + +## EXAMPLES + +``` +$ podman pull docker.io/library/wordpress +$ podman pull docker.io/library/php:7.2-apache + +$ podman image tree docker.io/library/wordpress +Image ID: 6e880d17852f +Tags: [docker.io/library/wordpress:latest] +Size: 429.9MB +Image Layers +├── ID: 3c816b4ead84 Size: 58.47MB +├── ID: e39dad2af72e Size: 3.584kB +├── ID: b2d6a702383c Size: 213.6MB +├── ID: 94609408badd Size: 3.584kB +├── ID: f4dddbf86725 Size: 43.04MB +├── ID: 8f695df43a4c Size: 11.78kB +├── ID: c29d67bf8461 Size: 9.728kB +├── ID: 23f4315918f8 Size: 7.68kB +├── ID: d082f93a18b3 Size: 13.51MB +├── ID: 7ea8bedcac69 Size: 4.096kB +├── ID: dc3bbf7b3dc0 Size: 57.53MB +├── ID: fdbbc6404531 Size: 11.78kB +├── ID: 8d24785437c6 Size: 4.608kB +├── ID: 80715f9e8880 Size: 4.608kB Top Layer of: [docker.io/library/php:7.2-apache] +├── ID: c93cbcd6437e Size: 3.573MB +├── ID: dece674f3cd1 Size: 4.608kB +├── ID: 834f4497afda Size: 7.168kB +├── ID: bfe2ce1263f8 Size: 40.06MB +└── ID: 748e99b214cf Size: 11.78kB Top Layer of: [docker.io/library/wordpress:latest] + +$ podman pull docker.io/circleci/ruby:latest +$ podman pull docker.io/library/ruby:latest + +$ podman image tree ae96a4ad4f3f --whatrequires +Image ID: ae96a4ad4f3f +Tags: [docker.io/library/ruby:latest] +Size: 894.2MB +Image Layers +└── ID: 9c92106221c7 Size: 2.56kB Top Layer of: [docker.io/library/ruby:latest] + ├── ID: 1b90f2b80ba0 Size: 3.584kB + │ ├── ID: 42b7d43ae61c Size: 169.5MB + │ ├── ID: 26dc8ba99ec3 Size: 2.048kB + │ ├── ID: b4f822db8d95 Size: 3.957MB + │ ├── ID: 044e9616ef8a Size: 164.7MB + │ ├── ID: bf94b940200d Size: 11.75MB + │ ├── ID: 4938e71bfb3b Size: 8.532MB + │ └── ID: f513034bf553 Size: 1.141MB + ├── ID: 1e55901c3ea9 Size: 3.584kB + ├── ID: b62835a63f51 Size: 169.5MB + ├── ID: 9f4e8857f3fd Size: 2.048kB + ├── ID: c3b392020e8f Size: 3.957MB + ├── ID: 880163026a0a Size: 164.8MB + ├── ID: 8c78b2b14643 Size: 11.75MB + ├── ID: 830370cfa182 Size: 8.532MB + └── ID: 567fd7b7bd38 Size: 1.141MB Top Layer of: [docker.io/circleci/ruby:latest] + +``` + + +## SEE ALSO +podman(1) + +## HISTORY +Feb 2019, Originally compiled by Kunal Kushwaha <kushwaha_kunal_v7@lab.ntt.co.jp> diff --git a/docs/source/man/podman-image-trust.1.md b/docs/source/man/podman-image-trust.1.md new file mode 100644 index 000000000..3fe4f7f52 --- /dev/null +++ b/docs/source/man/podman-image-trust.1.md @@ -0,0 +1,93 @@ +% podman-image-trust(1) + +## NAME +podman\-image\-trust - Manage container registry image trust policy + + +## SYNOPSIS +**podman image trust** set|show [*options*] *registry[/repository]* + +## DESCRIPTION +Manages which registries you trust as a source of container images based on its location. (Not available for remote commands) + +The location is determined +by the transport and the registry host of the image. Using this container image `docker://docker.io/library/busybox` +as an example, `docker` is the transport and `docker.io` is the registry host. + +Trust is defined in **/etc/containers/policy.json** and is enforced when a user attempts to pull +a remote image from a registry. The trust policy in policy.json describes a registry scope (registry and/or repository) for the trust. This trust can use public keys for signed images. + +The scope of the trust is evaluated from most specific to the least specific. In other words, a policy may be defined for an entire registry. Or it could be defined for a particular repository in that registry. Or it could be defined down to a specific signed image inside of the registry. + +For example, the following list includes valid scope values that could be used in policy.json from most specific to the least specific: + +docker.io/library/busybox:notlatest +docker.io/library/busybox +docker.io/library +docker.io + +If no configuration is found for any of these scopes, the default value (specified by using "default" instead of REGISTRY[/REPOSITORY]) is used. + +Trust **type** provides a way to: + +Whitelist ("accept") or +Blacklist ("reject") registries or +Require signature (“signedBy”). + +Trust may be updated using the command **podman image trust set** for an existing trust scope. + +## OPTIONS +**-h**, **--help** + Print usage statement. + +**-f**, **--pubkeysfile**=*KEY1* + A path to an exported public key on the local system. Key paths + will be referenced in policy.json. Any path to a file may be used but locating the file in **/etc/pki/containers** is recommended. Options may be used multiple times to + require an image be signed by multiple keys. The **--pubkeysfile** option is required for the **signedBy** type. + +**-t**, **--type**=*value* + The trust type for this policy entry. + Accepted values: + **signedBy** (default): Require signatures with corresponding list of + public keys + **accept**: do not require any signatures for this + registry scope + **reject**: do not accept images for this registry scope + +## show OPTIONS + +**--raw** + Output trust policy file as raw JSON + +**-j**, **--json** + Output trust as JSON for machine parsing + +## EXAMPLES + +Accept all unsigned images from a registry + + sudo podman image trust set --type accept docker.io + +Modify default trust policy + + sudo podman image trust set -t reject default + +Display system trust policy + + sudo podman image trust show + +Display trust policy file + + sudo podman image trust show --raw + +Display trust as JSON + + sudo podman image trust show --json + +## SEE ALSO + +policy-json(5) + +## HISTORY +January 2019, updated by Tom Sweeney (tsweeney at redhat dot com) +December 2018, originally compiled by Qi Wang (qiwan at redhat dot com) diff --git a/docs/source/man/podman-image.1.md b/docs/source/man/podman-image.1.md new file mode 100644 index 000000000..339a531dd --- /dev/null +++ b/docs/source/man/podman-image.1.md @@ -0,0 +1,34 @@ +% podman-image(1) + +## NAME +podman\-image - Manage images + +## SYNOPSIS +**podman image** *subcommand* + +## DESCRIPTION +The image command allows you to manage images + +## COMMANDS + +| Command | Man Page | Description | +| -------- | ----------------------------------------------- | --------------------------------------------------------------------------- | +| build | [podman-build(1)](podman-build.1.md) | Build a container using a Dockerfile. | +| exists | [podman-image-exists(1)](podman-image-exists.1.md) | Check if an image exists in local storage. | +| history | [podman-history(1)](podman-history.1.md) | Show the history of an image. | +| import | [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | +| inspect | [podman-inspect(1)](podman-inspect.1.md) | Display a image or image's configuration. | +| list | [podman-images(1)](podman-images.1.md) | List the container images on the system.(alias ls) | +| load | [podman-load(1)](podman-load.1.md) | Load an image from the docker archive. | +| prune | [podman-image-prune(1)](podman-image-prune.1.md)| Remove all unused images from the local store. | +| pull | [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. | +| push | [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. | +| rm | [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. | +| save | [podman-save(1)](podman-save.1.md) | Save an image to docker-archive or oci. | +| sign | [podman-image-sign(1)](podman-image-sign.1.md) | Create a signature for an image. | +| tag | [podman-tag(1)](podman-tag.1.md) | Add an additional name to a local image. | +| tree | [podman-image-tree(1)](podman-image-tree.1.md) | Prints layer hierarchy of an image in a tree format. | +| trust | [podman-image-trust(1)](podman-image-trust.1.md)| Manage container registry image trust policy. | + +## SEE ALSO +podman diff --git a/docs/source/man/podman-images.1.md b/docs/source/man/podman-images.1.md new file mode 100644 index 000000000..3ac07fc43 --- /dev/null +++ b/docs/source/man/podman-images.1.md @@ -0,0 +1,178 @@ +% podman-images(1) + +## NAME +podman\-images - List images in local storage + +## SYNOPSIS +**podman images** [*options*] + +**podman image list** [*options*] + +**podman image ls** [*options*] + +## DESCRIPTION +Displays locally stored images, their names, and their IDs. + +## OPTIONS + +**-a**, **--all** + +Show all images (by default filter out the intermediate image layers). The default is false. + +**--digests** + +Show image digests + +**-f**, **--filter**=*filter* + +Filter output based on conditions provided + + Filters: + + **after==TIMESTRING** + Filter on images created after the given time.Time. + + **before==TIMESTRING** + Filter on images created before the given time.Time. + + **dangling=true|false** + Show dangling images. Dangling images are a file system layer that was used in a previous build of an image and is no longer referenced by any active images. They are denoted with the <none> tag, consume disk space and serve no active purpose. + + **label** + Filter by images labels key and/or value. + + **readonly=true|false** + Show only read only images or Read/Write images. The default is to show both. Read/Only images can be configured by modifying the "additionalimagestores" in the /etc/containers/storage.conf file. + + **reference=** + Filter by image name, specified as regular expressions. + +**--format**=*format* + +Change the default output format. This can be of a supported type like 'json' +or a Go template. + +**--noheading**, **-n** + +Omit the table headings from the listing of images. + +**--no-trunc**, **--notruncate** + +Do not truncate output. + +**--quiet**, **-q** + +Lists only the image IDs. + +**--sort**=*sort* + +Sort by created, id, repository, size or tag (default: created) + +## EXAMPLE + +``` +# podman images +REPOSITORY TAG IMAGE ID CREATED SIZE +docker.io/kubernetes/pause latest e3d42bcaf643 3 years ago 251 kB +<none> <none> ebb91b73692b 4 weeks ago 27.2 MB +docker.io/library/ubuntu latest 4526339ae51c 6 weeks ago 126 MB +``` + +``` +# podman images --quiet +e3d42bcaf643 +ebb91b73692b +4526339ae51c +``` + +``` +# podman images --noheading +docker.io/kubernetes/pause latest e3d42bcaf643 3 years ago 251 kB +<none> <none> ebb91b73692b 4 weeks ago 27.2 MB +docker.io/library/ubuntu latest 4526339ae51c 6 weeks ago 126 MB +``` + +``` +# podman images --no-trunc +REPOSITORY TAG IMAGE ID CREATED SIZE +docker.io/kubernetes/pause latest sha256:e3d42bcaf643097dd1bb0385658ae8cbe100a80f773555c44690d22c25d16b27 3 years ago 251 kB +<none> <none> sha256:ebb91b73692bd27890685846412ae338d13552165eacf7fcd5f139bfa9c2d6d9 4 weeks ago 27.2 MB +docker.io/library/ubuntu latest sha256:4526339ae51c3cdc97956a7a961c193c39dfc6bd9733b0d762a36c6881b5583a 6 weeks ago 126 MB +``` + +``` +# podman images --format "table {{.ID}} {{.Repository}} {{.Tag}}" +IMAGE ID REPOSITORY TAG +e3d42bcaf643 docker.io/kubernetes/pause latest +ebb91b73692b <none> <none> +4526339ae51c docker.io/library/ubuntu latest +``` + +``` +# podman images --filter dangling=true +REPOSITORY TAG IMAGE ID CREATED SIZE +<none> <none> ebb91b73692b 4 weeks ago 27.2 MB +``` + +``` +# podman images --format json +[ + { + "id": "e3d42bcaf643097dd1bb0385658ae8cbe100a80f773555c44690d22c25d16b27", + "names": [ + "docker.io/kubernetes/pause:latest" + ], + "digest": "sha256:0aecf73ff86844324847883f2e916d3f6984c5fae3c2f23e91d66f549fe7d423", + "created": "2014-07-19T07:02:32.267701596Z", + "size": 250665 + }, + { + "id": "ebb91b73692bd27890685846412ae338d13552165eacf7fcd5f139bfa9c2d6d9", + "names": [ + "\u003cnone\u003e" + ], + "digest": "sha256:ba7e4091d27e8114a205003ca6a768905c3395d961624a2c78873d9526461032", + "created": "2017-10-26T03:07:22.796184288Z", + "size": 27170520 + }, + { + "id": "4526339ae51c3cdc97956a7a961c193c39dfc6bd9733b0d762a36c6881b5583a", + "names": [ + "docker.io/library/ubuntu:latest" + ], + "digest": "sha256:193f7734ddd68e0fb24ba9af8c2b673aecb0227b026871f8e932dab45add7753", + "created": "2017-10-10T20:59:05.10196344Z", + "size": 126085200 + } +] +``` + +``` +# podman images --sort repository +REPOSITORY TAG IMAGE ID CREATED SIZE +<none> <none> 2460217d76fc About a minute ago 4.41 MB +docker.io/library/alpine latest 3fd9065eaf02 5 months ago 4.41 MB +localhost/myapp latest b2e0ad03474a About a minute ago 4.41 MB +registry.access.redhat.com/rhel7 latest 7a840db7f020 2 weeks ago 211 MB +registry.fedoraproject.org/fedora 27 801894bc0e43 6 weeks ago 246 MB +``` + +``` +# podman images +REPOSITORY TAG IMAGE ID CREATED SIZE +localhost/test latest 18f0c080cd72 4 seconds ago 4.42 MB +docker.io/library/alpine latest 3fd9065eaf02 5 months ago 4.41 MB +# podman images -a +REPOSITORY TAG IMAGE ID CREATED SIZE +localhost/test latest 18f0c080cd72 6 seconds ago 4.42 MB +<none> <none> 270e70dc54c0 7 seconds ago 4.42 MB +<none> <none> 4ed6fbe43414 8 seconds ago 4.41 MB +<none> <none> 6b0df8e71508 8 seconds ago 4.41 MB +docker.io/library/alpine latest 3fd9065eaf02 5 months ago 4.41 MB +``` + +## SEE ALSO +podman(1), containers-storage.conf(5) + +## HISTORY +March 2017, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-import.1.md b/docs/source/man/podman-import.1.md new file mode 100644 index 000000000..946b680dd --- /dev/null +++ b/docs/source/man/podman-import.1.md @@ -0,0 +1,111 @@ +% podman-import(1) + +## NAME +podman\-import - Import a tarball and save it as a filesystem image + +## SYNOPSIS +**podman import** [*options*] *path* [*reference*] + +**podman image import** [*options*] *path* [*reference*] + +## DESCRIPTION +**podman import** imports a tarball (.tar, .tar.gz, .tgz, .bzip, .tar.xz, .txz) +and saves it as a filesystem image. Remote tarballs can be specified using a URL. +Various image instructions can be configured with the **--change** flag and +a commit message can be set using the **--message** flag. +**reference**, if present, is a tag to assign to the image. +Note: `:` is a restricted character and cannot be part of the file name. + +## OPTIONS + +**-c**, **--change**=*instruction* + +Apply the following possible instructions to the created image: +**CMD** | **ENTRYPOINT** | **ENV** | **EXPOSE** | **LABEL** | **STOPSIGNAL** | **USER** | **VOLUME** | **WORKDIR** +Can be set multiple times + +**--message**, **-m**=*message* + +Set commit message for imported image + +**--quiet**, **-q** + +Shows progress on the import + +**-verbose** + +Print additional debugging information + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman import --change CMD=/bin/bash --change ENTRYPOINT=/bin/sh --change LABEL=blue=image ctr.tar image-imported +Getting image source signatures +Copying blob sha256:b41deda5a2feb1f03a5c1bb38c598cbc12c9ccd675f438edc6acd815f7585b86 + 25.80 MB / 25.80 MB [======================================================] 0s +Copying config sha256:c16a6d30f3782288ec4e7521c754acc29d37155629cb39149756f486dae2d4cd + 448 B / 448 B [============================================================] 0s +Writing manifest to image destination +Storing signatures +db65d991f3bbf7f31ed1064db9a6ced7652e3f8166c4736aa9133dadd3c7acb3 +``` + +``` +$ podman import --change "ENTRYPOINT ["/bin/sh","-c","test-image"]" --change LABEL=blue=image test-image.tar image-imported +Getting image source signatures +Copying blob e3b0c44298fc skipped: already exists +Copying config 1105523502 done +Writing manifest to image destination +Storing signatures +110552350206337183ceadc0bdd646dc356e06514c548b69a8917b4182414b +``` +``` +$ podman import --change "CMD /bin/sh" --change LABEL=blue=image test-image.tar image-imported +Getting image source signatures +Copying blob e3b0c44298fc skipped: already exists +Copying config ae9a27e249 done +Writing manifest to image destination +Storing signatures +ae9a27e249f801aff11a4ba54a81751ea9fbc9db45a6df3f1bfd63fc2437bb9c +``` + + +``` +$ cat ctr.tar | podman -q import --message "importing the ctr.tar tarball" - image-imported +db65d991f3bbf7f31ed1064db9a6ced7652e3f8166c4736aa9133dadd3c7acb3 +``` + +``` +$ cat ctr.tar | podman import - +Getting image source signatures +Copying blob sha256:b41deda5a2feb1f03a5c1bb38c598cbc12c9ccd675f438edc6acd815f7585b86 + 25.80 MB / 25.80 MB [======================================================] 0s +Copying config sha256:d61387b4d5edf65edee5353e2340783703074ffeaaac529cde97a8357eea7645 + 378 B / 378 B [============================================================] 0s +Writing manifest to image destination +Storing signatures +db65d991f3bbf7f31ed1064db9a6ced7652e3f8166c4736aa9133dadd3c7acb3 +``` + +``` +$ podman import http://example.com/ctr.tar url-image +Downloading from "http://example.com/ctr.tar" +Getting image source signatures +Copying blob sha256:b41deda5a2feb1f03a5c1bb38c598cbc12c9ccd675f438edc6acd815f7585b86 + 25.80 MB / 25.80 MB [======================================================] 0s +Copying config sha256:5813fe8a3b18696089fd09957a12e88bda43dc1745b5240879ffffe93240d29a + 419 B / 419 B [============================================================] 0s +Writing manifest to image destination +Storing signatures +db65d991f3bbf7f31ed1064db9a6ced7652e3f8166c4736aa9133dadd3c7acb3 +``` + +## SEE ALSO +podman(1), podman-export(1) + +## HISTORY +November 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-info.1.md b/docs/source/man/podman-info.1.md new file mode 100644 index 000000000..9721755ef --- /dev/null +++ b/docs/source/man/podman-info.1.md @@ -0,0 +1,151 @@ +% podman-info(1) + +## NAME +podman\-info - Displays Podman related system information + +## SYNOPSIS +**podman info** [*options*] + +**podman system info** [*options*] + +## DESCRIPTION + +Displays information pertinent to the host, current storage stats, configured container registries, and build of podman. + + +## OPTIONS + +**-D**, **--debug** + +Show additional information + +**-f**, **--format**=*format* + +Change output format to "json" or a Go template. + + +## EXAMPLE + +Run podman info with plain text response: +``` +$ podman info +host: + BuildahVersion: 1.4-dev + Conmon: + package: Unknown + path: /usr/libexec/podman/conmon + version: 'conmon version 1.12.0-dev, commit: d724f3d54ad2d95b6de741085d4990190ebfd7ff' + Distribution: + distribution: fedora + version: "28" + MemFree: 1271083008 + MemTotal: 33074233344 + OCIRuntime: + package: runc-1.0.0-51.dev.gitfdd8055.fc28.x86_64 + path: /usr/bin/runc + version: 'runc version spec: 1.0.0' + SwapFree: 34309664768 + SwapTotal: 34359734272 + arch: amd64 + cpus: 8 + hostname: localhost.localdomain + kernel: 4.18.7-200.fc28.x86_64 + os: linux + uptime: 218h 49m 33.66s (Approximately 9.08 days) +registries: + blocked: null + insecure: null + search: + - quay.io + - registry.fedoraproject.org + - docker.io + - registry.redhat.io +store: + ConfigFile: /etc/containers/storage.conf + ContainerStore: + number: 37 + GraphDriverName: overlay + GraphOptions: + - overlay.mountopt=nodev + - overlay.override_kernel_check=true + GraphRoot: /var/lib/containers/storage + GraphStatus: + Backing Filesystem: extfs + Native Overlay Diff: "true" + Supports d_type: "true" + ImageStore: + number: 17 + RunRoot: /var/run/containers/storage + +``` +Run podman info with JSON formatted response: +``` +{ + "host": { + "BuildahVersion": "1.4-dev", + "Conmon": { + "package": "Unknown", + "path": "/usr/libexec/podman/conmon", + "version": "conmon version 1.12.0-dev, commit: d724f3d54ad2d95b6de741085d4990190ebfd7ff" + }, + "Distribution": { + "distribution": "fedora", + "version": "28" + }, + "MemFree": 1204109312, + "MemTotal": 33074233344, + "OCIRuntime": { + "package": "runc-1.0.0-51.dev.gitfdd8055.fc28.x86_64", + "path": "/usr/bin/runc", + "version": "runc version spec: 1.0.0" + }, + "SwapFree": 34309664768, + "SwapTotal": 34359734272, + "arch": "amd64", + "cpus": 8, + "hostname": "localhost.localdomain", + "kernel": "4.18.7-200.fc28.x86_64", + "os": "linux", + "uptime": "218h 50m 35.02s (Approximately 9.08 days)" + }, + "insecure registries": { + "registries": [] + }, + "registries": { + "registries": [ + "quay.io", + "registry.fedoraproject.org", + "docker.io", + "registry.access.redhat.com" + ] + }, + "store": { + "ContainerStore": { + "number": 37 + }, + "GraphDriverName": "overlay", + "GraphOptions": [ + "overlay.mountopt=nodev", + "overlay.override_kernel_check=true" + ], + "GraphRoot": "/var/lib/containers/storage", + "GraphStatus": { + "Backing Filesystem": "extfs", + "Native Overlay Diff": "true", + "Supports d_type": "true" + }, + "ImageStore": { + "number": 17 + }, + "RunRoot": "/var/run/containers/storage" + } +} +``` +Run podman info and only get the registries information. +``` +$ podman info --format={{".registries"}} +map[registries:[docker.io quay.io registry.fedoraproject.org registry.access.redhat.com]] +``` + +## SEE ALSO +podman(1), containers-registries.conf(5), containers-storage.conf(5) diff --git a/docs/source/man/podman-init.1.md b/docs/source/man/podman-init.1.md new file mode 100644 index 000000000..3b49cfb99 --- /dev/null +++ b/docs/source/man/podman-init.1.md @@ -0,0 +1,44 @@ +% podman-init(1) + +## NAME +podman\-init - Initialize one or more containers + +## SYNOPSIS +**podman init** [*options*] *container* [*container*...] + +**podman container init** [*options*] *container* [*container*...] + +## DESCRIPTION +Initialize one or more containers. +You may use container IDs or names as input. +Initializing a container performs all tasks necessary for starting the container (mounting filesystems, creating an OCI spec, initializing the container network) but does not start the container. +If a container is not initialized, the `podman start` and `podman run` commands will do so automatically prior to starting it. +This command is intended to be used for inspecting or modifying the container's filesystem or OCI spec prior to starting it. +This can be used to inspect the container before it runs, or debug why a container is failing to run. + +## OPTIONS + +**--all**, **-a** + +Initialize all containers. Containers that have already initialized (including containers that have been started and are running) are ignored. + +**--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 latest option is not supported on the remote client. + +## EXAMPLE + +podman init 35480fc9d568 + +podman init test1 + +podman init --latest + +## SEE ALSO +podman(1), podman-start(1) + +## HISTORY +April 2019, Originally compiled by Matthew Heon <mheon@redhat.com> diff --git a/docs/source/man/podman-inspect.1.md b/docs/source/man/podman-inspect.1.md new file mode 100644 index 000000000..f1630c713 --- /dev/null +++ b/docs/source/man/podman-inspect.1.md @@ -0,0 +1,115 @@ +% podman-inspect(1) + +## NAME +podman\-inspect - Display a container or image's configuration + +## SYNOPSIS +**podman inspect** [*options*] *name* [...] + +**podman image inspect** [*options*] *image* + +**podman container inspect** [*options*] *container* + +## DESCRIPTION +This displays the low-level information on containers and images identified by name or ID. By default, this will render +all results in a JSON array. If the container and image have the same name, this will return container JSON for +unspecified type. If a format is specified, the given template will be executed for each result. + +## OPTIONS + +**--type**, **-t**=*type* + +Return JSON for the specified type. Type can be 'container', 'image' or 'all' (default: all) +(Only meaningful when invoked as *podman inspect*) + +**--format**, **-f**=*format* + +Format the output using the given Go template. +The keys of the returned JSON can be used as the values for the --format flag (see examples below). + +**--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 latest option is not supported on the remote client or when invoked as *podman image inspect*. + +**--size**, **-s** + +Display the total file size if the type is a container + + +## EXAMPLE + +``` +# podman inspect fedora +{ + "Id": "422dc563ca3260ad9ef5c47a1c246f5065d7f177ce51f4dd208efd82967ff182", + "Digest": "sha256:1b9bfb4e634dc1e5c19d0fa1eb2e5a28a5c2b498e3d3e4ac742bd7f5dae08611", + "RepoTags": [ + "docker.io/library/fedora:latest" + ], + "RepoDigests": [ + "docker.io/library/fedora@sha256:1b9bfb4e634dc1e5c19d0fa1eb2e5a28a5c2b498e3d3e4ac742bd7f5dae08611" + ], + "Parent": "", + "Comment": "", + "Created": "2017-11-14T21:07:08.475840838Z", + "Config": { + "Env": [ + "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", + "DISTTAG=f27container", + "FGC=f27", + "FBR=f27" + ] + }, + "Version": "17.06.2-ce", + "Author": "[Adam Miller \u003cmaxamillion@fedoraproject.org\u003e] [Patrick Uiterwijk \u003cpatrick@puiterwijk.org\u003e]", + "Architecture": "amd64", + "Os": "linux", + "Size": 251722732, + "VirtualSize": 514895140, + "GraphDriver": { + "Name": "overlay", + "Data": { + "MergedDir": "/var/lib/containers/storage/overlay/d32459d9ce237564fb93573b85cbc707600d43fbe5e46e8eeef22cad914bb516/merged", + "UpperDir": "/var/lib/containers/storage/overlay/d32459d9ce237564fb93573b85cbc707600d43fbe5e46e8eeef22cad914bb516/diff", + "WorkDir": "/var/lib/containers/storage/overlay/d32459d9ce237564fb93573b85cbc707600d43fbe5e46e8eeef22cad914bb516/work" + } + }, + "RootFS": { + "Type": "layers", + "Layers": [ + "sha256:d32459d9ce237564fb93573b85cbc707600d43fbe5e46e8eeef22cad914bb516" + ] + }, + "Labels": null, + "Annotations": {} +} +``` + +``` +# podman inspect a04 --format "{{.ImageName}}" +fedora +``` + +``` +# podman inspect a04 --format "{{.GraphDriver.Name}}" +overlay +``` + +``` +# podman image inspect --format "size: {{.Size}}" alpine +size: 4405240 +``` + +``` +podman container inspect --latest --format {{.EffectiveCaps}} +[CAP_CHOWN CAP_DAC_OVERRIDE CAP_FSETID CAP_FOWNER CAP_MKNOD CAP_NET_RAW CAP_SETGID CAP_SETUID CAP_SETFCAP CAP_SETPCAP CAP_NET_BIND_SERVICE CAP_SYS_CHROOT CAP_KILL CAP_AUDIT_WRITE] +``` + +## SEE ALSO +podman(1) + +## HISTORY +July 2017, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-kill.1.md b/docs/source/man/podman-kill.1.md new file mode 100644 index 000000000..617d25b85 --- /dev/null +++ b/docs/source/man/podman-kill.1.md @@ -0,0 +1,47 @@ +% podman-kill(1) + +## NAME +podman\-kill - Kill the main process in one or more containers + +## SYNOPSIS +**podman kill** [*options*] [*container* ...] + +**podman container kill** [*options*] [*container* ...] + +## DESCRIPTION +The main process inside each container specified will be sent SIGKILL, or any signal specified with option --signal. + +## OPTIONS +**--all**, **-a** + +Signal all running containers. This does not include paused containers. + +**--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 latest option is not supported on the remote client. + +**--signal**, **s** + +Signal to send to the container. For more information on Linux signals, refer to *man signal(7)*. + + +## EXAMPLE + +podman kill mywebserver + +podman kill 860a4b23 + +podman kill --signal TERM 860a4b23 + +podman kill --latest + +podman kill --signal KILL -a + +## SEE ALSO +podman(1), podman-stop(1) + +## HISTORY +September 2017, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-load.1.md b/docs/source/man/podman-load.1.md new file mode 100644 index 000000000..deb4fb5ec --- /dev/null +++ b/docs/source/man/podman-load.1.md @@ -0,0 +1,79 @@ +% podman-load(1) + +## NAME +podman\-load - Load an image from a container image archive into container storage + +## SYNOPSIS +**podman load** [*options*] [*name*[:*tag*]] + +**podman image load** [*options*] [*name*[:*tag*]] + +## DESCRIPTION +**podman load** loads an image from either an **oci-archive** or **docker-archive** stored on the local machine into container storage. **podman load** reads from stdin by default or a file if the **input** option is set. +You can also specify a name for the image if the archive does not contain a named reference, of if you want an additional name for the local image. + +The **quiet** option suppresses the progress output when set. +Note: `:` is a restricted character and cannot be part of the file name. + + +**podman [GLOBAL OPTIONS]** + +**podman load [GLOBAL OPTIONS]** + +**podman load [OPTIONS] NAME[:TAG]** + +## OPTIONS + +**--input**, **-i**=*input* + +Read from archive file, default is STDIN. + +The remote client requires the use of this option. + +**--quiet**, **-q** + +Suppress the progress output + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman load --quiet -i fedora.tar +``` + +``` +$ podman load -q -i fedora.tar +``` + +``` +$ podman load < fedora.tar +Getting image source signatures +Copying blob sha256:5bef08742407efd622d243692b79ba0055383bbce12900324f75e56f589aedb0 + 0 B / 4.03 MB [---------------------------------------------------------------] +Copying config sha256:7328f6f8b41890597575cbaadc884e7386ae0acc53b747401ebce5cf0d624560 + 0 B / 1.48 KB [---------------------------------------------------------------] +Writing manifest to image destination +Storing signatures +Loaded image: registry.fedoraproject.org/fedora:latest +``` + +``` +$ cat fedora.tar | podman load +Getting image source signatures +Copying blob sha256:5bef08742407efd622d243692b79ba0055383bbce12900324f75e56f589aedb0 + 0 B / 4.03 MB [---------------------------------------------------------------] +Copying config sha256:7328f6f8b41890597575cbaadc884e7386ae0acc53b747401ebce5cf0d624560 + 0 B / 1.48 KB [---------------------------------------------------------------] +Writing manifest to image destination +Storing signatures +Loaded image: registry.fedoraproject.org/fedora:latest +``` + +## SEE ALSO +podman(1), podman-save(1), podman-tag(1) + +## HISTORY +July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-login.1.md b/docs/source/man/podman-login.1.md new file mode 100644 index 000000000..9d368e9f2 --- /dev/null +++ b/docs/source/man/podman-login.1.md @@ -0,0 +1,107 @@ +% podman-login(1) + +## NAME +podman\-login - Login to a container registry + +## SYNOPSIS +**podman login** [*options*] *registry* + +## DESCRIPTION +**podman login** logs into a specified registry server with the correct username +and password. **podman login** reads in the username and password from STDIN. +The username and password can also be set using the **username** and **password** flags. +The path of the authentication file can be specified by the user by setting the **authfile** +flag. The default path used is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. + +**podman [GLOBAL OPTIONS]** + +**podman login [GLOBAL OPTIONS]** + +**podman login [OPTIONS] REGISTRY [GLOBAL OPTIONS]** + +## 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 (Not available for remote commands) + +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` + +**--get-login** + +Return the logged-in user for the registry. Return error if no login is found. + +**--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--tls-verify**=*true|false* + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to 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. (Not available for remote commands) + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman login docker.io +Username: umohnani +Password: +Login Succeeded! +``` + +``` +$ podman login -u testuser -p testpassword localhost:5000 +Login Succeeded! +``` + +``` +$ podman login --authfile authdir/myauths.json docker.io +Username: umohnani +Password: +Login Succeeded! +``` + +``` +$ podman login --tls-verify=false -u test -p test localhost:5000 +Login Succeeded! +``` + +``` +$ 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) + +## HISTORY +August 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-logout.1.md b/docs/source/man/podman-logout.1.md new file mode 100644 index 000000000..01dc52ecd --- /dev/null +++ b/docs/source/man/podman-logout.1.md @@ -0,0 +1,59 @@ +% podman-logout(1) + +## NAME +podman\-logout - Logout of a container registry + +## SYNOPSIS +**podman logout** [*options*] *registry* + +## DESCRIPTION +**podman logout** logs out of a specified registry server by deleting the cached credentials +stored in the **auth.json** file. The path of the authentication file can be overridden by the user by setting the **authfile** flag. +The default path used is **${XDG\_RUNTIME\_DIR}/containers/auth.json**. +All the cached credentials can be removed by setting the **all** flag. + +**podman [GLOBAL OPTIONS]** + +**podman logout [GLOBAL OPTIONS]** + +**podman logout [OPTIONS] REGISTRY [GLOBAL OPTIONS]** + +## OPTIONS + +**--authfile**=*path* + +Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json (Not available for remote commands) + +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` + +**--all**, **-a** + +Remove the cached credentials for all registries in the auth file + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman logout docker.io +Remove login credentials for https://registry-1.docker.io/v2/ +``` + +``` +$ podman logout --authfile authdir/myauths.json docker.io +Remove login credentials for https://registry-1.docker.io/v2/ +``` + +``` +$ podman logout --all +Remove login credentials for all registries +``` + +## SEE ALSO +podman(1), podman-login(1) + +## HISTORY +August 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-logs.1.md b/docs/source/man/podman-logs.1.md new file mode 100644 index 000000000..405f180d9 --- /dev/null +++ b/docs/source/man/podman-logs.1.md @@ -0,0 +1,100 @@ +% podman-logs(1) + +## NAME +podman\-logs - Display the logs of one or more containers + +## SYNOPSIS +**podman logs** [*options*] *container* [*container...*] + +**podman container logs** [*options*] *container* [*container...*] + +## DESCRIPTION +The podman logs command batch-retrieves whatever logs are present for one or more containers at the time of execution. +This does not guarantee execution order when combined with podman run (i.e. your run may not have generated +any logs at the time you execute podman logs + +## OPTIONS + +**--follow**, **-f** + +Follow log output. Default is false. + +Note: If you are following a container which is removed `podman container rm` +or removed on exit `podman run --rm ...`, then there is a chance the the log +file will be removed before `podman logs` reads the final content. + +**--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 latest option is not supported on the remote client. + +**--since**=*TIMESTAMP* + +Show logs since TIMESTAMP. The --since option can be Unix timestamps, date formatted timestamps, or Go duration +strings (e.g. 10m, 1h30m) computed relative to the client machine's time. Supported formats for date formatted +time stamps include RFC3339Nano, RFC3339, 2006-01-02T15:04:05, 2006-01-02T15:04:05.999999999, 2006-01-02Z07:00, +and 2006-01-02. + +**--tail**=*LINES* + +Output the specified number of LINES at the end of the logs. LINES must be a positive integer. Defaults to 0, +which prints all lines + +**--timestamps**, **-t** + +Show timestamps in the log outputs. The default is false + +## EXAMPLE + +To view a container's logs: +``` +podman logs -t b3f2436bdb978c1d33b1387afb5d7ba7e3243ed2ce908db431ac0069da86cb45 + +2017/08/07 10:16:21 Seeked /var/log/crio/pods/eb296bd56fab164d4d3cc46e5776b54414af3bf543d138746b25832c816b933b/c49f49788da14f776b7aa93fb97a2a71f9912f4e5a3e30397fca7dfe0ee0367b.log - &{Offset:0 Whence:0} +1:C 07 Aug 14:10:09.055 # oO0OoO0OoO0Oo Redis is starting oO0OoO0OoO0Oo +1:C 07 Aug 14:10:09.055 # Redis version=4.0.1, bits=64, commit=00000000, modified=0, pid=1, just started +1:C 07 Aug 14:10:09.055 # Warning: no config file specified, using the default config. In order to specify a config file use redis-server /path/to/redis.conf +1:M 07 Aug 14:10:09.055 # You requested maxclients of 10000 requiring at least 10032 max file descriptors. +1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. +1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 07 Aug 14:10:09.056 # Server initialized +``` + +To view only the last two lines in container's log: +``` +podman logs --tail 2 b3f2436bdb97 + +# WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +# Server initialized +``` + +To view a containers logs since a certain time: +``` +podman logs -t --since 2017-08-07T10:10:09.055837383-04:00 myserver + +1:M 07 Aug 14:10:09.055 # Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +1:M 07 Aug 14:10:09.055 # Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +1:M 07 Aug 14:10:09.056 * Running mode=standalone, port=6379. +1:M 07 Aug 14:10:09.056 # WARNING: The TCP backlog setting of 511 cannot be enforced because /proc/sys/net/core/somaxconn is set to the lower value of 128. +1:M 07 Aug 14:10:09.056 # Server initialized +``` + +To view a container's logs generated in the last 10 minutes: +``` +podman logs --since 10m myserver + +# Server can't set maximum open files to 10032 because of OS error: Operation not permitted. +# Current maximum open files is 4096. maxclients has been reduced to 4064 to compensate for low ulimit. If you need higher maxclients increase 'ulimit -n'. +``` + +## SEE ALSO +podman(1), podman-run(1), podman-container-rm(1) + +## HISTORY +February 2018, Updated by Brent Baude <bbaude@redhat.com> + +August 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/man/podman-mount.1.md b/docs/source/man/podman-mount.1.md new file mode 100644 index 000000000..8f4deeca6 --- /dev/null +++ b/docs/source/man/podman-mount.1.md @@ -0,0 +1,73 @@ +% podman-mount(1) + +## NAME +podman\-mount - Mount a working container's root filesystem + +## SYNOPSIS +**podman mount** [*container* ...] + +**podman container mount** [*container* ...] + +## DESCRIPTION +Mounts the specified containers' root file system in a location which can be +accessed from the host, and returns its location. + +If you execute the command without any arguments, the tool will list all of the +currently mounted containers. + +## RETURN VALUE +The location of the mounted file system. On error an empty string and errno is +returned. + +## OPTIONS + +**--all**, **a** + +Mount all containers. + +**--format**=*format* + +Print the mounted containers in specified format (json) + +**--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 latest option is not supported on the remote client. + +**--notruncate** + +Do not truncate IDs in output. + +## EXAMPLE + +``` +podman mount c831414b10a3 + +/var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged +``` + +``` +podman mount + +c831414b10a3 /var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged +a7060253093b /var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged +``` +``` +podman mount c831414b10a3 a7060253093b + +/var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged +/var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged +``` + +``` +podman mount + +c831414b10a3 /var/lib/containers/storage/overlay/f3ac502d97b5681989dff84dfedc8354239bcecbdc2692f9a639f4e080a02364/merged +a7060253093b /var/lib/containers/storage/overlay/0ff7d7ca68bed1ace424f9df154d2dd7b5a125c19d887f17653cbcd5b6e30ba1/merged +``` + +## SEE ALSO +podman(1), podman-umount(1), mount(8) diff --git a/docs/source/man/podman-network-create.1.md b/docs/source/man/podman-network-create.1.md new file mode 100644 index 000000000..c281d50d9 --- /dev/null +++ b/docs/source/man/podman-network-create.1.md @@ -0,0 +1,75 @@ +% podman-network-create(1) + +## NAME +podman\-network-create - Create a Podman CNI network + +## SYNOPSIS +**podman network create** [*options*] name + +## DESCRIPTION +Create a CNI-network configuration for use with Podman. At the time of this writing, the only network +type that can be created is a *bridge* network. + +If no options are provided, Podman will assign a free subnet and name for your network. + +Upon completion of creating the network, Podman will display the path to the newly added network file. + +## OPTIONS +**--disable-dns** + +Disables the DNS plugin for this network which if enabled, can perform container to container name +resolution. + +**-d**, , **--driver** + +Driver to manage the network (default "bridge"). Currently on `bridge` is supported. + +**--gateway** + +Define a gateway for the subnet. If you want to provide a gateway address, you must also provide a +*subnet* option. + +**--internal** + +Restrict external access of this network + +**--ip-range** + +Allocate container IP from a range. The range must be a complete subnet and in CIDR notation. The *ip-range* option +must be used with a *subnet* option. + +**--subnet** + +The subnet in CIDR notation. + +## EXAMPLE + +Create a network with no options +``` +# podman network create +/etc/cni/net.d/cni-podman-4.conflist +``` + +Create a network named *newnet* that uses *192.5.0.0/16* for its subnet. +``` +# podman network create --subnet 192.5.0.0/16 newnet +/etc/cni/net.d/newnet.conflist +``` + +Create a network named *newnet* that uses *192.168.33.0/24* and defines a gateway as *192.168.133.3* +``` +# podman network create --subnet 192.168.33.0/24 --gateway 192.168.33.3 newnet +/etc/cni/net.d/newnet.conflist +``` + +Create a network that uses a *192.168.55.0/24** subnet and has an IP address range of *192.168.55.129 - 192.168.55.254*. +``` +# podman network create --subnet 192.168.55.0/24 --ip-range 192.168.55.128/25 +/etc/cni/net.d/cni-podman-5.conflist +``` + +## SEE ALSO +podman(1), podman-network(1), podman-network-inspect(1) + +## HISTORY +August 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-network-inspect.1.md b/docs/source/man/podman-network-inspect.1.md new file mode 100644 index 000000000..dfa7e4b0c --- /dev/null +++ b/docs/source/man/podman-network-inspect.1.md @@ -0,0 +1,50 @@ +% podman-network-inspect(1) + +## NAME +podman\-network\-inspect - Displays the raw CNI network configuration for one or more networks + +## SYNOPSIS +**podman network inspect** [*network* ...] + +## DESCRIPTION +Display the raw (JSON format) network configuration. This command is not available for rootless users. + +## EXAMPLE + +Inspect the default podman network + +``` +# podman network inspect podman +[{ + "cniVersion": "0.3.0", + "name": "podman", + "plugins": [ + { + "type": "bridge", + "bridge": "cni0", + "isGateway": true, + "ipMasq": true, + "ipam": { + "type": "host-local", + "subnet": "10.88.1.0/24", + "routes": [ + { "dst": "0.0.0.0/0" } + ] + } + }, + { + "type": "portmap", + "capabilities": { + "portMappings": true + } + } + ] +} +] +``` + +## SEE ALSO +podman(1), podman-network(1), podman-network-ls(1) + +## HISTORY +August 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-network-ls.1.md b/docs/source/man/podman-network-ls.1.md new file mode 100644 index 000000000..46e424593 --- /dev/null +++ b/docs/source/man/podman-network-ls.1.md @@ -0,0 +1,43 @@ +% podman-network-ls(1) + +## NAME +podman\-network\-ls - Display a summary of CNI networks + +## SYNOPSIS +**podman network ls** [*options*] + +## DESCRIPTION +Displays a list of existing podman networks. This command is not available for rootless users. + +## OPTIONS +**--quiet**, **-q** + +The `quiet` option will restrict the output to only the network names + +## EXAMPLE + +Display networks + +``` +# podman network ls +NAME VERSION PLUGINS +podman 0.3.0 bridge,portmap +podman2 0.3.0 bridge,portmap +outside 0.3.0 bridge +podman9 0.3.0 bridge,portmap +``` + +Display only network names +``` +# podman network ls -q +podman +podman2 +outside +podman9 +``` + +## SEE ALSO +podman(1), podman-network(1), podman-network-inspect(1) + +## HISTORY +August 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-network-rm.1.md b/docs/source/man/podman-network-rm.1.md new file mode 100644 index 000000000..c71f0d8fd --- /dev/null +++ b/docs/source/man/podman-network-rm.1.md @@ -0,0 +1,38 @@ +% podman-network-rm(1) + +## NAME +podman\-network\-rm - Remove one or more CNI networks + +## SYNOPSIS +**podman network rm** [*network...*] + +## DESCRIPTION +Delete one or more Podman networks. + +## OPTIONS +**--force**, **-f** + +The `force` option will remove all containers that use the named network. If the container is +running, the container will be stopped and removed. + +## EXAMPLE + +Delete the `cni-podman9` network + +``` +# podman network rm cni-podman9 +Deleted: cni-podman9 +``` + +Delete the `fred` network and all containers associated with the network. + +``` +# podman network rm -f fred +Deleted: fred +``` + +## SEE ALSO +podman(1), podman-network(1), podman-network-inspect(1) + +## HISTORY +August 2019, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-network.1.md b/docs/source/man/podman-network.1.md new file mode 100644 index 000000000..f05b2b78f --- /dev/null +++ b/docs/source/man/podman-network.1.md @@ -0,0 +1,22 @@ +% podman-network(1) + +## NAME +podman\-network - Manage Podman CNI networks + +## SYNOPSIS +**podman network** *subcommand* + +## DESCRIPTION +The network command manages CNI networks for Podman. It is not supported for rootless users. + +## COMMANDS + +| Command | Man Page | Description | +| ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | +| create | [podman-network-create(1)](podman-network-create.1.md)| Create a Podman CNI network| +| inspect | [podman-network-inspect(1)](podman-network-inspect.1.md)| Displays the raw CNI network configuration for one or more networks| +| ls | [podman-network-ls(1)](podman-network-ls.1.md)| Display a summary of CNI networks | +| rm | [podman-network-rm(1)](podman-network-rm.1.md)| Remove one or more CNI networks | + +## SEE ALSO +podman(1) diff --git a/docs/source/man/podman-pause.1.md b/docs/source/man/podman-pause.1.md new file mode 100644 index 000000000..dfd4da416 --- /dev/null +++ b/docs/source/man/podman-pause.1.md @@ -0,0 +1,41 @@ +% podman-pause(1) + +## NAME +podman\-pause - Pause one or more containers + +## SYNOPSIS +**podman pause** [*options*] [*container*...] + +**podman container 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) + +## HISTORY +September 2017, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-play-kube.1.md b/docs/source/man/podman-play-kube.1.md new file mode 100644 index 000000000..2ac860a32 --- /dev/null +++ b/docs/source/man/podman-play-kube.1.md @@ -0,0 +1,65 @@ +% podman-play-kube(1) + +## NAME +podman-play-kube - Create pods and containers based on Kubernetes YAML + +## SYNOPSIS +**podman play kube** [*options*] *file*__.yml__ + +## DESCRIPTION +**podman play kube** will read in a structured file of Kubernetes YAML. It will then recreate +the pod and containers described in the YAML. The containers within the pod are then started and +the ID of the new Pod is output. + +Ideally the input file would be one created by Podman (see podman-generate-kube(1)). This would guarantee a smooth import and expected results. + +Note: HostPath volume types created by play kube will be given an SELinux private label (Z) + +## OPTIONS: + +**--authfile**=*path* + +Path of the authentication file. Default is ${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`. (Not available for remote commands) + +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. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--creds** + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +**--quiet**, **-q** + +Suppress output information when pulling images + +**--tls-verify**=*true|false* + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to 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. (Not available for remote commands) + +**--help**, **-h** + +Print usage statement + +## Examples + +Recreate the pod and containers as described in a file called `demo.yml` +``` +$ podman play kube demo.yml +52182811df2b1e73f36476003a66ec872101ea59034ac0d4d3a7b40903b955a6 +``` + +## SEE ALSO +podman(1), podman-container(1), podman-pod(1), podman-generate-kube(1), podman-play(1) + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-play.1.md b/docs/source/man/podman-play.1.md new file mode 100644 index 000000000..364baad60 --- /dev/null +++ b/docs/source/man/podman-play.1.md @@ -0,0 +1,20 @@ +% podman-play(1) + +## NAME +podman\-play - Play pods and containers based on a structured input file + +## SYNOPSIS +**podman play** *subcommand* + +## DESCRIPTION +The play command will recreate pods and containers based on the input from a structured (like YAML) +file input. Containers will be automatically started. + +## COMMANDS + +| Command | Man Page | Description | +| ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | +| kube | [podman-play-kube(1)](podman-play-kube.1.md) | Create pods and containers based on Kubernetes YAML. | + +## SEE ALSO +podman, podman-pod(1), podman-container(1), podman-generate(1), podman-play(1), podman-play-kube(1) diff --git a/docs/source/man/podman-pod-create.1.md b/docs/source/man/podman-pod-create.1.md new file mode 100644 index 000000000..cd1de6401 --- /dev/null +++ b/docs/source/man/podman-pod-create.1.md @@ -0,0 +1,94 @@ +% podman-pod-create(1) + +## NAME +podman\-pod\-create - Create a new pod + +## SYNOPSIS +**podman pod create** [*options*] + +## DESCRIPTION + +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. + +## OPTIONS + +**--cgroup-parent**=*path* + +Path to cgroups under which the cgroup for the pod will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. + +**--help** + +Print usage statement + +**--infra** + +Create an infra container and associate it with the pod. An infra container is a lightweight container used to coordinate the shared kernel namespace of a pod. Default: true + +**--infra-command**=*command* + +The command that will be run to start the infra container. Default: "/pause" + +**--infra-image**=*image* + +The image that will be created for the infra container. Default: "k8s.gcr.io/pause:3.1" + +**-l**, **--label**=*label* + +Add metadata to a pod (e.g., --label com.example.key=value) + +**--label-file**=*label* + +Read in a line delimited file of labels + +**-n**, **--name**=*name* + +Assign a name to the pod + +**--podidfile**=*podid* + +Write the pod ID to the file + +**-p**, **--publish**=*port* + +Publish a port or range of ports from the pod to the host + +Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort` +Both hostPort and containerPort can be specified as a range of ports. +When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. +Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT` + +NOTE: This cannot be modified once the pod is created. + +**--share**=*namespace* + +A comma delimited list of kernel namespaces to share. If none or "" is specified, no namespaces will be shared. The namespaces to choose from are ipc, net, pid, user, uts. + +The operator can identify a pod in three ways: +UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) +UUID short identifier (“f78375b1c487”) +Name (“jonah”) + +podman generates a UUID for each pod, and if a name is not assigned +to the container with **--name** then a random string name will be generated +for it. The name is useful any place you need to identify a pod. + +## EXAMPLES + +``` +$ podman pod create --name test + +$ podman pod create --infra=false + +$ podman pod create --infra-command /top + +$ podman pod create --publish 8443:443 +``` + +## SEE ALSO +podman-pod(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-exists.1.md b/docs/source/man/podman-pod-exists.1.md new file mode 100644 index 000000000..cf2852934 --- /dev/null +++ b/docs/source/man/podman-pod-exists.1.md @@ -0,0 +1,37 @@ +% podman-pod-exists(1) + +## NAME +podman-pod-exists - Check if a pod exists in local storage + +## SYNOPSIS +**podman pod exists** *pod* + +## DESCRIPTION +**podman pod exists** checks if a pod exists in local storage. The **ID** or **Name** +of the pod may be used as input. Podman will return an exit code +of `0` when the pod is found. A `1` will be returned otherwise. An exit code of `125` indicates there +was an issue accessing the local storage. + +## Examples ## + +Check if a pod called `web` exists in local storage (the pod does actually exist). +``` +$ sudo podman pod exists web +$ echo $? +0 +$ +``` + +Check if a pod called `backend` exists in local storage (the pod does not actually exist). +``` +$ sudo podman pod exists backend +$ echo $? +1 +$ +``` + +## SEE ALSO +podman-pod(1), podman(1) + +## HISTORY +December 2018, Originally compiled by Brent Baude (bbaude at redhat dot com) diff --git a/docs/source/man/podman-pod-inspect.1.md b/docs/source/man/podman-pod-inspect.1.md new file mode 100644 index 000000000..831d28259 --- /dev/null +++ b/docs/source/man/podman-pod-inspect.1.md @@ -0,0 +1,49 @@ +% podman-pod-inspect(1) + +## NAME +podman\-pod\-inspect - Displays information describing a pod + +## SYNOPSIS +**podman pod inspect** [*options*] *pod* ... + +## DESCRIPTION +Displays configuration and state information about a given pod. It also displays information about containers +that belong to the pod. + +## OPTIONS +**--latest**, **-l** + +Instead of providing the pod name or ID, use the last created pod. If you use methods other than Podman +to run pods such as CRI-O, the last started pod could be from either of those methods. + +The latest option is not supported on the remote client. + +## EXAMPLE +``` +# podman pod inspect foobar +{ + "Config": { + "id": "3513ca70583dd7ef2bac83331350f6b6c47d7b4e526c908e49d89ebf720e4693", + "name": "foobar", + "labels": {}, + "cgroupParent": "/libpod_parent", + "UsePodCgroup": true, + "created": "2018-08-08T11:15:18.823115347-05:00" + }, + "State": { + "CgroupPath": "" + }, + "Containers": [ + { + "id": "d53f8bf1e9730281264aac6e6586e327429f62c704abea4b6afb5d8a2b2c9f2c", + "state": "configured" + } + ] +} +``` + +## SEE ALSO +podman-pod(1), podman-pod-ps(1) + +## HISTORY +August 2018, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-pod-kill.1.md b/docs/source/man/podman-pod-kill.1.md new file mode 100644 index 000000000..596e15cea --- /dev/null +++ b/docs/source/man/podman-pod-kill.1.md @@ -0,0 +1,45 @@ +% podman-pod-kill(1) + +## NAME +podman\-pod\-kill - Kill the main process of each container in one or more pods + +## SYNOPSIS +**podman pod kill** [*options*] *pod* ... + +## DESCRIPTION +The main process of each container inside the pods specified will be sent SIGKILL, or any signal specified with option --signal. + +## OPTIONS +**--all**, **-a** + +Sends signal to all containers associated with a pod. + +**--latest**, **-l** + +Instead of providing the pod name or ID, use the last created pod. If you use methods other than Podman +to run pods such as CRI-O, the last started pod could be from either of those methods. + +The latest option is not supported on the remote client. + +**--signal**, **-s** + +Signal to send to the containers in the pod. For more information on Linux signals, refer to *man signal(7)*. + + +## EXAMPLE + +podman pod kill mywebserver + +podman pod kill 860a4b23 + +podman pod kill --signal TERM 860a4b23 + +podman pod kill --latest + +podman pod kill --all + +## SEE ALSO +podman-pod(1), podman-pod-stop(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-pause.1.md b/docs/source/man/podman-pod-pause.1.md new file mode 100644 index 000000000..9533ed4a1 --- /dev/null +++ b/docs/source/man/podman-pod-pause.1.md @@ -0,0 +1,34 @@ +% podman-pod-pause(1) + +## NAME +podman\-pod\-pause - Pause one or more pods + +## SYNOPSIS +**podman pod pause** [*options*] *pod* ... + +## DESCRIPTION +Pauses all the running processes in the containers of one or more pods. You may use pod IDs or names as input. + +## OPTIONS + +**--all**, **-a** + +Pause all pods. + +**--latest**, **-l** + +Instead of providing the pod name or ID, pause the last created pod. + +The latest option is not supported on the remote client. + +## EXAMPLE + +podman pod pause mywebserverpod + +podman pod pause 860a4b23 + +## SEE ALSO +podman-pod(1), podman-pod-unpause(1), podman-pause(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-prune.1.md b/docs/source/man/podman-pod-prune.1.md new file mode 100644 index 000000000..f79961b2f --- /dev/null +++ b/docs/source/man/podman-pod-prune.1.md @@ -0,0 +1,27 @@ +% podman-pod-prune(1) + +## NAME +podman-pod-prune - Remove all stopped pods + +## SYNOPSIS +**podman pod prune** + +## DESCRIPTION +**podman pod prune** removes all stopped pods from local storage. + +## EXAMPLES +Remove all stopped pods from local storage +``` +$ sudo podman pod prune +22b8813332948064b6566370088c5e0230eeaf15a58b1c5646859fd9fc364fe7 +2afb26869fe5beab979c234afb75c7506063cd4655b1a73557c9d583ff1aebe9 +49161ad2a722cf18722f0e17199a9e840703a17d1158cdeda502b6d54080f674 +5ca429f37fb83a9f54eea89e3a9102b7780a6e6ae5f132db0672da551d862c4a +6bb06573787efb8b0675bc88ebf8361f1a56d3ac7922d1a6436d8f59ffd955f1 +``` + +## SEE ALSO +podman-pod(1), podman-pod-ps(1), podman-pod-rm(1) + +## HISTORY +April 2019, Originally compiled by Peter Hunt (pehunt at redhat dot com) diff --git a/docs/source/man/podman-pod-ps.1.md b/docs/source/man/podman-pod-ps.1.md new file mode 100644 index 000000000..65a7072ab --- /dev/null +++ b/docs/source/man/podman-pod-ps.1.md @@ -0,0 +1,167 @@ +% podman-pod-ps(1) + +## NAME +podman\-pod\-ps - Prints out information about pods + +## SYNOPSIS +**podman pod ps** [*options*] + +## DESCRIPTION +**podman pod ps** lists the pods on the system. +By default it lists: + + * pod id + * pod name + * number of containers attached to pod + * status of pod as defined by the following table + +| **Status** | **Description** | +| ------------ | ------------------------------------------------| +| Created | No containers running nor stopped | +| Running | at least one container is running | +| Stopped | At least one container stopped and none running | +| Exited | All containers stopped in pod | +| Dead | Error retrieving state | + + +## OPTIONS + +**--ctr-names** + +Includes the container names in the container info field + +**--ctr-ids** + +Includes the container IDs in the container info field + +**--ctr-status** + +Includes the container statuses in the container info field + +**--latest**,**-l** + +Show the latest pod created (all states) + +The latest option is not supported on the remote client. + +**--no-trunc** + +Display the extended information + +**--quiet**, **-q** + +Print the numeric IDs of the pods only + +**--format**=*format* + +Pretty-print containers to JSON or using a Go template + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| ------------------- | ----------------------------------------------------------------------------------------------- | +| .ID | Container ID | +| .Name | Name of pod | +| .Status | Status of pod | +| .Labels | All the labels assigned to the pod | +| .ContainerInfo | Show the names, ids and/or statuses of containers (only shows 9 unless no-trunc is specified) | +| .NumberOfContainers | Show the number of containers attached to pod | +| .Cgroup | Cgroup path of pod | +| .UsePodCgroup | Whether containers use the Cgroup of the pod | + +**--sort** + +Sort by created, ID, name, status, or number of containers + +Default: created + +**--filter**, **-f=***filter* + +Filter output based on conditions given + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | ------------------------------------------------------------------- | +| id | [ID] Pod's ID | +| name | [Name] Pod's name | +| label | [Key] or [Key=Value] Label assigned to a container | +| ctr-names | Container name within the pod | +| ctr-ids | Container ID within the pod | +| ctr-status | Container status within the pod | +| ctr-number | Number of containers in the pod | + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman pod ps +POD ID NAME STATUS NUMBER OF CONTAINERS +00dfd6fa02c0 jolly_goldstine Running 1 +f4df8692e116 nifty_torvalds Created 2 +``` + +``` +$ podman pod ps --ctr-names +POD ID NAME STATUS CONTAINER INFO +00dfd6fa02c0 jolly_goldstine Running [ loving_archimedes ] +f4df8692e116 nifty_torvalds Created [ thirsty_hawking ] [ wizardly_golick ] +``` + +``` +$ podman pod ps --ctr-status --ctr-names --ctr-ids +POD ID NAME STATUS CONTAINER INFO +00dfd6fa02c0 jolly_goldstine Running [ ba465ab0a3a4 loving_archimedes Running ] +f4df8692e116 nifty_torvalds Created [ 331693bff40a thirsty_hawking Created ] [ 8e428daeb89e wizardly_golick Created ] +``` + +``` +$ podman pod ps --format "{{.ID}} {{.ContainerInfo}} {{.Cgroup}}" --ctr-names +00dfd6fa02c0 [ loving_archimedes ] /libpod_parent +f4df8692e116 [ thirsty_hawking ] [ wizardly_golick ] /libpod_parent +``` + +``` +$ podman pod ps --cgroup +POD ID NAME STATUS NUMBER OF CONTAINERS CGROUP USE POD CGROUP +00dfd6fa02c0 jolly_goldstine Running 1 /libpod_parent true +f4df8692e116 nifty_torvalds Created 2 /libpod_parent true +``` + +``` +$ podman pod ps --sort id --filter ctr-number=2 +POD ID NAME STATUS NUMBER OF CONTAINERS +f4df8692e116 nifty_torvalds Created 2 +``` + +``` +$ podman pod ps --ctr-ids +POD ID NAME STATUS CONTAINER INFO +00dfd6fa02c0 jolly_goldstine Running [ ba465ab0a3a4 ] +f4df8692e116 nifty_torvalds Created [ 331693bff40a ] [ 8e428daeb89e ] +``` + +``` +$ podman pod ps --no-trunc --ctr-ids +POD ID NAME STATUS CONTAINER INFO +00dfd6fa02c0a2daaedfdf8fcecd06f22ad114d46d167d71777224735f701866 jolly_goldstine Running [ ba465ab0a3a4e15e3539a1e79c32d1213a02b0989371e274f98e0f1ae9de7050 ] +f4df8692e116a3e6d1d62572644ed36ca475d933808cc3c93435c45aa139314b nifty_torvalds Created [ 331693bff40a0ef2f05a3aba73ce49e3243108911927fff04d1f7fc44dda8022 ] [ 8e428daeb89e69b71e7916a13accfb87d122889442b5c05c2d99cf94a3230e9d ] +``` + +``` +$ podman pod ps --ctr-names +POD ID NAME STATUS CONTAINER INFO +314f4da82d74 hi Created [ jovial_jackson ] [ hopeful_archimedes ] [ vibrant_ptolemy ] [ heuristic_jennings ] [ keen_raman ] [ hopeful_newton ] [ mystifying_bose ] [ silly_lalande ] [ serene_lichterman ] ... +``` + +## pod ps +Print a list of pods + +## SEE ALSO +podman-pod(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-restart.1.md b/docs/source/man/podman-pod-restart.1.md new file mode 100644 index 000000000..57f479102 --- /dev/null +++ b/docs/source/man/podman-pod-restart.1.md @@ -0,0 +1,52 @@ +% podman-pod-restart(1) + +## NAME +podman\-pod\-restart - Restart one or more pods + +## SYNOPSIS +**podman pod restart** [*options*] *pod* ... + +## DESCRIPTION +Restart containers in one or more pods. Containers will be stopped if running and then restarted. +Stopped containers will only be started. You may use pod IDs or names as input. +The pod ID will be printed upon successful restart. +When restarting multiple pods, an error from restarting one pod will not effect restarting other pods. + +## OPTIONS + +**--all**, **-a** + +Restarts all pods + +**--latest**, **-l** + +Instead of providing the pod name or ID, restart the last created pod. + +The latest option is not supported on the remote client. + +## EXAMPLE + +``` +podman pod restart mywebserverpod +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 + +podman pod restart 490eb 3557fb +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab + +podman pod restart --latest +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab + +podman pod restart --all +19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +## SEE ALSO +podman-pod(1), podman-pod-start(1), podman-restart(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-rm.1.md b/docs/source/man/podman-pod-rm.1.md new file mode 100644 index 000000000..6659534b4 --- /dev/null +++ b/docs/source/man/podman-pod-rm.1.md @@ -0,0 +1,44 @@ +% podman-pod-rm(1) + +## NAME +podman\-pod\-rm - Remove one or more pods + +## SYNOPSIS +**podman pod rm** [*options*] *pod* + +## DESCRIPTION +**podman pod rm** will remove one or more pods from the host. The pod name or ID can be used. The \-f option stops all containers and then removes them before removing the pod. Without the \-f option, a pod cannot be removed if it has associated containers. + +## OPTIONS + +**--all**, **-a** + +Remove all pods. Can be used in conjunction with \-f as well. + +**--latest**, **-l** + +Instead of providing the pod name or ID, remove the last created pod. + +The latest option is not supported on the remote client. + +**--force**, **-f** + +Stop running containers and delete all stopped containers before removal of pod. + +## EXAMPLE + +podman pod rm mywebserverpod + +podman pod rm mywebserverpod myflaskserverpod 860a4b23 + +podman pod rm -f 860a4b23 + +podman pod rm -f -a + +podman pod rm -fa + +## SEE ALSO +podman-pod(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-start.1.md b/docs/source/man/podman-pod-start.1.md new file mode 100644 index 000000000..29960d6aa --- /dev/null +++ b/docs/source/man/podman-pod-start.1.md @@ -0,0 +1,40 @@ +% podman-pod-start(1) + +## NAME +podman\-pod\-start - Start one or more pods + +## SYNOPSIS +**podman pod start** [*options*] *pod* ... + +## DESCRIPTION +Start containers in one or more pods. You may use pod IDs or names as input. The pod must have a container attached +to be started. + +## OPTIONS + +**--all**, **-a** + +Starts all pods + +**--latest**, **-l** + +Instead of providing the pod name or ID, start the last created pod. + +The latest option is not supported on the remote client. + +## EXAMPLE + +podman pod start mywebserverpod + +podman pod start 860a4b23 5421ab4 + +podman pod start --latest + +podman pod start --all + + +## SEE ALSO +podman-pod(1), podman-pod-stop(1), podman-start(1) + +## HISTORY +July 2018, Adapted from podman start man page by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-stats.1.md b/docs/source/man/podman-pod-stats.1.md new file mode 100644 index 000000000..962edbda0 --- /dev/null +++ b/docs/source/man/podman-pod-stats.1.md @@ -0,0 +1,92 @@ +% podman-pod-stats(1) + +## NAME +podman\-pod\-stats - Display a live stream of resource usage stats for containers in one or more pods + +## SYNOPSIS +**podman pod stats** [*options*] [*pod*] + +## DESCRIPTION +Display a live stream of containers in one or more pods resource usage statistics + +## OPTIONS + +**--all**, **-a** + +Show all containers. Only running containers are shown by default + +**--latest**, **-l** + +Instead of providing the pod name or ID, use the last created pod. + +The latest option is not supported on the remote client. + +**--no-reset** + +Do not clear the terminal/screen in between reporting intervals + +**--no-stream** + +Disable streaming pod stats and only pull the first result, default setting is false + +**--format**=*template* + +Pretty-print container statistics to JSON or using a Go template + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | --------------- | +| .Pod | Pod ID | +| .CID | Container ID | +| .Name | Container Name | +| .CPU | CPU percentage | +| .MemUsage | Memory usage | +| .Mem | Memory percentage | +| .NetIO | Network IO | +| .BlockIO | Block IO | +| .PIDS | Number of PIDs | + +When using a GO template, you may precede the format with `table` to print headers. +## EXAMPLE + +``` +# podman pod stats -a --no-stream +ID NAME CPU % MEM USAGE / LIMIT MEM % NET IO BLOCK IO PIDS +a9f807ffaacd frosty_hodgkin -- 3.092MB / 16.7GB 0.02% -- / -- -- / -- 2 +3b33001239ee sleepy_stallman -- -- / -- -- -- / -- -- / -- -- +``` + +``` +# podman pod stats --no-stream a9f80 +ID NAME CPU % MEM USAGE / LIMIT MEM % NET IO BLOCK IO PIDS +a9f807ffaacd frosty_hodgkin -- 3.092MB / 16.7GB 0.02% -- / -- -- / -- 2 +``` + +``` +# podman pod stats --no-stream --format=json a9f80 +[ + { + "id": "a9f807ffaacd", + "name": "frosty_hodgkin", + "cpu_percent": "--", + "mem_usage": "3.092MB / 16.7GB", + "mem_percent": "0.02%", + "netio": "-- / --", + "blocki": "-- / --", + "pids": "2" + } +] +``` + +``` +# podman pod stats --no-stream --format "table {{.ID}} {{.Name}} {{.MemUsage}}" 6eae +ID NAME MEM USAGE / LIMIT +6eae9e25a564 clever_bassi 3.031MB / 16.7GB +``` + +## SEE ALSO +podman-pod(1), podman(1) + +## HISTORY +February 2019, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-pod-stop.1.md b/docs/source/man/podman-pod-stop.1.md new file mode 100644 index 000000000..b3ce47d72 --- /dev/null +++ b/docs/source/man/podman-pod-stop.1.md @@ -0,0 +1,71 @@ +% podman-pod-stop(1) + +## NAME +podman\-pod\-stop - Stop one or more pods + +## SYNOPSIS +**podman pod stop** [*options*] *pod* ... + +## DESCRIPTION +Stop containers in one or more pods. You may use pod IDs or names as input. + +## OPTIONS + +**--all**, **-a** + +Stops all pods + +**--latest**, **-l** + +Instead of providing the pod name or ID, stop the last created pod. + +The latest option is not supported on the remote client. + +**--timeout**, **--time**, **-t**=*time* + +Timeout to wait before forcibly stopping the containers in the pod. + +## EXAMPLE + +Stop a pod called *mywebserverpod* +``` +$ podman pod stop mywebserverpod +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop two pods by their short IDs. +``` +$ podman pod stop 490eb 3557fb +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` + +Stop the most recent pod +``` +$ podman pod stop --latest +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +``` + +Stop all pods +``` +$ podman pod stop --all +19456b4cd557eaf9629825113a552681a6013f8c8cad258e36ab825ef536e818 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +cc8f0bea67b1a1a11aec1ecd38102a1be4b145577f21fc843c7c83b77fc28907 +``` + +Stop all pods with a timeout of 1 second. +``` +$ podman pod stop -a -t 1 +3557fbea6ad61569de0506fe037479bd9896603c31d3069a6677f23833916fab +490eb241aaf704d4dd2629904410fe4aa31965d9310a735f8755267f4ded1de5 +70c358daecf71ef9be8f62404f926080ca0133277ef7ce4f6aa2d5af6bb2d3e9 +``` + +## SEE ALSO +podman-pod(1), podman-pod-start(1), podman-stop(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-top.1.md b/docs/source/man/podman-pod-top.1.md new file mode 100644 index 000000000..48f10055a --- /dev/null +++ b/docs/source/man/podman-pod-top.1.md @@ -0,0 +1,94 @@ +% podman-pod-top(1) + +## NAME +podman\-pod\-top - Display the running processes of containers in a pod + +## SYNOPSIS +**podman pod top** [*options*] *pod* [*format-descriptors*] + +## DESCRIPTION +Display the running processes of containers in a pod. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container. + +## OPTIONS + +**--help**, **-h** + + Print usage statement + +**--latest**, **-l** + +Instead of providing the pod name or ID, use the last created pod. + +The latest option is not supported on the remote client. + +## FORMAT DESCRIPTORS + +The following descriptors are supported in addition to the AIX format descriptors mentioned in ps (1): + +**args**, **capbnd**, **capeff**, **capinh**, **capprm**, **comm**, **etime**, **group**, **hgroup**, **hpid**, **huser**, **label**, **nice**, **pcpu**, **pgid**, **pid**, **ppid**, **rgroup**, **ruser**, **seccomp**, **state**, **time**, **tty**, **user**, **vsz** + +**capbnd** + + Set of bounding capabilities. See capabilities (7) for more information. + +**capeff** + + Set of effective capabilities. See capabilities (7) for more information. + +**capinh** + + Set of inheritable capabilities. See capabilities (7) for more information. + +**capprm** + + Set of permitted capabilities. See capabilities (7) for more information. + +**hgroup** + + The corresponding effective group of a container process on the host. + +**hpid** + + The corresponding host PID of a container process. + +**huser** + + The corresponding effective user of a container process on the host. + +**label** + + Current security attributes of the process. + +**seccomp** + + Seccomp mode of the process (i.e., disabled, strict or filter). See seccomp (2) for more information. + +**state** + + Process state codes (e.g, **R** for *running*, **S** for *sleeping*). See proc(5) for more information. + +## EXAMPLES + +By default, `podman-top` prints data similar to `ps -ef`: + +``` +$ podman pod top b031293491cc +USER PID PPID %CPU ELAPSED TTY TIME COMMAND +root 1 0 0.000 2h5m38.737137571s ? 0s top +root 8 0 0.000 2h5m15.737228361s ? 0s top +``` + +The output can be controlled by specifying format descriptors as arguments after the pod: + +``` +$ podman pod top -l pid seccomp args %C +PID SECCOMP COMMAND %CPU +1 filter top 0.000 +1 filter /bin/sh 0.000 +``` + +## SEE ALSO +podman-pod(1), ps(1), seccomp(2), proc(5), capabilities(7) + +## HISTORY +August 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod-unpause.1.md b/docs/source/man/podman-pod-unpause.1.md new file mode 100644 index 000000000..e0a88c2e3 --- /dev/null +++ b/docs/source/man/podman-pod-unpause.1.md @@ -0,0 +1,34 @@ +% podman-pod-unpause(1) + +## NAME +podman\-pod\-unpause - Unpause one or more pods + +## SYNOPSIS +**podman pod unpause** [*options*] *pod* ... + +## DESCRIPTION +Unpauses all the paused processes in the containers of one or more pods. You may use pod IDs or names as input. + +## OPTIONS + +**--all**, **-a** + +Unpause all pods. + +**--latest**, **-l** + +Instead of providing the pod name or ID, unpause the last created pod. + +The latest option is not supported on the remote client. + +## EXAMPLE + +podman pod unpause mywebserverpod + +podman pod unpause 860a4b23 + +## SEE ALSO +podman-pod(1), podman-pod-pause(1), podman-unpause(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-pod.1.md b/docs/source/man/podman-pod.1.md new file mode 100644 index 000000000..b3d002a06 --- /dev/null +++ b/docs/source/man/podman-pod.1.md @@ -0,0 +1,35 @@ +% podman-pod(1) + +## NAME +podman\-pod - Management tool for groups of containers, called pods + +## SYNOPSIS +**podman pod** *subcommand* + +## DESCRIPTION +podman pod is a set of subcommands that manage pods, or groups of containers. + +## SUBCOMMANDS + +| Command | Man Page | Description | +| ------- | ------------------------------------------------- | --------------------------------------------------------------------------------- | +| create | [podman-pod-create(1)](podman-pod-create.1.md) | Create a new pod. | +| exists | [podman-pod-exists(1)](podman-pod-exists.1.md) | Check if a pod exists in local storage. | +| inspect | [podman-pod-inspect(1)](podman-pod-inspect.1.md) | Displays information describing a pod. | +| kill | [podman-pod-kill(1)](podman-pod-kill.1.md) | Kill the main process of each container in one or more pods. | +| pause | [podman-pod-pause(1)](podman-pod-pause.1.md) | Pause one or more pods. | +| prune | [podman-pod-prune(1)](podman-pod-prune.1.md) | Remove all stopped pods. | +| ps | [podman-pod-ps(1)](podman-pod-ps.1.md) | Prints out information about pods. | +| restart | [podman-pod-restart(1)](podman-pod-restart.1.md) | Restart one or more pods. | +| rm | [podman-pod-rm(1)](podman-pod-rm.1.md) | Remove one or more pods. | +| start | [podman-pod-start(1)](podman-pod-start.1.md) | Start one or more pods. | +| stats | [podman-pod-stats(1)](podman-pod-stats.1.md) | Display a live stream of resource usage stats for containers in one or more pods. | +| stop | [podman-pod-stop(1)](podman-pod-stop.1.md) | Stop one or more pods. | +| top | [podman-pod-top(1)](podman-pod-top.1.md) | Display the running processes of containers in a pod. | +| unpause | [podman-pod-unpause(1)](podman-pod-unpause.1.md) | Unpause one or more pods. | + +## SEE ALSO +podman(1) + +## HISTORY +July 2018, Originally compiled by Peter Hunt <pehunt@redhat.com> diff --git a/docs/source/man/podman-port.1.md b/docs/source/man/podman-port.1.md new file mode 100644 index 000000000..c9833f447 --- /dev/null +++ b/docs/source/man/podman-port.1.md @@ -0,0 +1,63 @@ +% podman-port(1) + +## NAME +podman\-port - List port mappings for a container + +## SYNOPSIS +**podman port** [*options*] *container* [*private-port*[/*proto*]] + +**podman container port** [*options*] *container* [*private-port*[/*proto*]] + +## DESCRIPTION +List port mappings for the *container* or lookup the public-facing port that is NAT-ed to the *private-port*. + +## OPTIONS + +**--all**, **-a** + +List all known port mappings for running containers. When using this option, you cannot pass any container names +or private ports/protocols as filters. + +**--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 latest option is not supported on the remote client. + +## EXAMPLE + +List all port mappings +``` +# podman port -a +b4d2f05432e482e017b1a4b2eae15fa7b4f6fb7e9f65c1bde46294fdef285906 +80/udp -> 0.0.0.0:44327 +80/tcp -> 0.0.0.0:44327 +# +``` + +List port mappings for a specific container +``` +# podman port b4d2f054 +80/udp -> 0.0.0.0:44327 +80/tcp -> 0.0.0.0:44327 +# +``` +List the port mappings for the latest container and port 80 +``` +# podman port b4d2f054 80 + 0.0.0.0:44327 +# +``` + +List the port mappings for a specific container for port 80 and the tcp protocol. +``` +# podman port b4d2f054 80/tcp +0.0.0.0:44327 +# +``` +## SEE ALSO +podman(1), podman-inspect(1) + +## HISTORY +January 2018, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-ps.1.md b/docs/source/man/podman-ps.1.md new file mode 100644 index 000000000..298de0b2b --- /dev/null +++ b/docs/source/man/podman-ps.1.md @@ -0,0 +1,182 @@ +% podman-ps(1) + +## NAME +podman\-ps - Prints out information about containers + +## SYNOPSIS +**podman ps** [*options*] + +**podman container list** [*options*] + +**podman container ls** [*options*] + +**podman container ps** [*options*] + +**podman list** [*options*] + +**podman ls** [*options*] + +## DESCRIPTION +**podman ps** lists the running containers on the system. Use the **--all** flag to view +all the containers information. By default it lists: + + * container id + * the name of the image the container is using + * the COMMAND the container is executing + * the time the container was created + * the status of the container + * port mappings the container is using + * alternative names for the container + +## OPTIONS + +**--all**, **-a** + +Show all the containers, default is only running containers + +**--pod**, **-p** + +Display the pods the containers are associated with + +**--no-trunc** + +Display the extended information + +**--quiet**, **-q** + +Print the numeric IDs of the containers only + +**--format**=*format* + +Pretty-print containers to JSON or using a Go template + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | ------------------------------------------------ | +| .ID | Container ID | +| .Image | Image ID/Name | +| .Command | Quoted command used | +| .CreatedAt | Creation time for container | +| .RunningFor | Time elapsed since container was started | +| .Status | Status of container | +| .Pod | Pod the container is associated with | +| .Ports | Exposed ports | +| .Size | Size of container | +| .Names | Name of container | +| .Labels | All the labels assigned to the container | +| .Mounts | Volumes mounted in the container | + +**--sort** + +Sort by command, created, id, image, names, runningfor, size, or status", +Note: Choosing size will sort by size of rootFs, not alphabetically like the rest of the options +Default: created + +**--size**, **-s** + +Display the total file size + +**--last**, **-n** + +Print the n last created containers (all states) + +**--latest**, **-l** + +Show the latest container created (all states) + +The latest option is not supported on the remote client. + +**--namespace**, **--ns** + +Display namespace information + +**--filter**, **-f** + +Filter what containers are shown in the output. +Multiple filters can be given with multiple uses of the --filter flag. +If multiple filters are given, only containers which match all of the given filters will be shown. + +Valid filters are listed below: + +| **Filter** | **Description** | +| --------------- | -------------------------------------------------------------------------------- | +| id | [ID] Container's ID | +| name | [Name] Container's name | +| label | [Key] or [Key=Value] Label assigned to a container | +| exited | [Int] Container's exit code | +| status | [Status] Container's status: *created*, *exited*, *paused*, *running*, *unknown* | +| ancestor | [ImageName] Image or descendant used to create container | +| before | [ID] or [Name] Containers created before this container | +| since | [ID] or [Name] Containers created since this container | +| volume | [VolumeName] or [MountpointDestination] Volume mounted in container | +| health | [Status] healthy or unhealthy | + +**--help**, **-h** + +Print usage statement + +**--sync** + +Force a sync of container state with the OCI runtime. +In some cases, a container's state in the runtime can become out of sync with Podman's state. +This will update Podman's state based on what the OCI runtime reports. +Forcibly syncing is much slower, but can resolve inconsistent state issues. + +**--watch**, **-w** + +Refresh the output with current containers on an interval in seconds. + +## EXAMPLES + +``` +$ podman ps -a +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +02f65160e14ca redis:alpine "redis-server" 19 hours ago Exited (-1) 19 hours ago 6379/tcp k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0 +69ed779d8ef9f redis:alpine "redis-server" 25 hours ago Created 6379/tcp k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1 +``` + +``` +$ podman ps -a -s +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES SIZE +02f65160e14ca redis:alpine "redis-server" 20 hours ago Exited (-1) 20 hours ago 6379/tcp k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0 27.49 MB +69ed779d8ef9f redis:alpine "redis-server" 25 hours ago Created 6379/tcp k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1 27.49 MB +``` + +``` +$ podman ps -a --format "{{.ID}} {{.Image}} {{.Labels}} {{.Mounts}}" +02f65160e14ca redis:alpine tier=backend proc,tmpfs,devpts,shm,mqueue,sysfs,cgroup,/var/run/,/var/run/ +69ed779d8ef9f redis:alpine batch=no,type=small proc,tmpfs,devpts,shm,mqueue,sysfs,cgroup,/var/run/,/var/run/ +``` + +``` +$ podman ps --ns -a +CONTAINER ID NAMES PID CGROUP IPC MNT NET PIDNS USER UTS +3557d882a82e3 k8s_container2_podsandbox1_redhat.test.crio_redhat-test-crio_1 29910 4026531835 4026532585 4026532593 4026532508 4026532595 4026531837 4026532594 +09564cdae0bec k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1 29851 4026531835 4026532585 4026532590 4026532508 4026532592 4026531837 4026532591 +a31ebbee9cee7 k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0 29717 4026531835 4026532585 4026532587 4026532508 4026532589 4026531837 4026532588 +``` + +``` +$ podman ps -a --size --sort names +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +69ed779d8ef9f redis:alpine "redis-server" 25 hours ago Created 6379/tcp k8s_container1_podsandbox1_redhat.test.crio_redhat-test-crio_1 +02f65160e14ca redis:alpine "redis-server" 19 hours ago Exited (-1) 19 hours ago 6379/tcp k8s_podsandbox1-redis_podsandbox1_redhat.test.crio_redhat-test-crio_0 +``` + +``` +$ podman ps +CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES +4089df24d4f3 docker.io/library/centos:latest /bin/bash 2 minutes ago Up 2 minutes ago 0.0.0.0:80->8080/tcp, 0.0.0.0:2000-2006->2000-2006/tcp manyports +92f58933c28c docker.io/library/centos:latest /bin/bash 3 minutes ago Up 3 minutes ago 192.168.99.100:1000-1006->1000-1006/tcp zen_sanderson + +``` + +## ps +Print a list of containers + +## SEE ALSO +podman(1) + +## HISTORY +August 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-pull.1.md b/docs/source/man/podman-pull.1.md new file mode 100644 index 000000000..de9688f5e --- /dev/null +++ b/docs/source/man/podman-pull.1.md @@ -0,0 +1,147 @@ +% podman-pull(1) + +## NAME +podman\-pull - Pull an image from a registry + +## SYNOPSIS +**podman pull** [*options*] *name*[:*tag*|@*digest*] + +**podman image pull** [*options*] *name*[:*tag*|@*digest*] + +## DESCRIPTION +Copies an image from a registry onto the local machine. **podman pull** pulls an +image from Docker Hub if a registry is not specified in the command line argument. +If an image tag is not specified, **podman pull** defaults to the image with the +**latest** tag (if it exists) and pulls it. After the image is pulled, podman will +print the full image ID. **podman pull** can also pull an image +using its digest **podman pull** *image*@*digest*. **podman pull** can be used to pull +images from archives and local storage using different transports. + +## imageID +Image stored in local container/storage + +## SOURCE + + The SOURCE is a location to get container images + The Image "SOURCE" uses a "transport":"details" format. + + 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. + + **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)`. + + **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. + + **docker-daemon:**_docker-reference_ + An image _docker-reference_ stored in the docker daemon internal storage. _docker-reference_ must contain either a tag or a digest. Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID). + + **oci-archive:**_path_**:**_tag_ + An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. + +## OPTIONS + +**--all-tags**, **a** + +All tagged images in the repository will be pulled. + +Note: When using the all-tags flag, Podman will not iterate over the search registries in the containers-registries.conf(5) but will always use docker.io for unqualified image names. + +**--authfile**=*path* + +Path of the authentication file. Default is ${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`. (Not available for remote commands) + +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. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--creds**=*[username[:password]]* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +**--quiet**, **-q** + +Suppress output information when pulling images + +**--tls-verify**=*true|false* + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to 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. (Not available for remote commands) + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman pull alpine:latest +Trying to pull registry.access.redhat.com/alpine:latest... Failed +Trying to pull registry.fedoraproject.org/alpine:latest... Failed +Trying to pull docker.io/library/alpine:latest...Getting image source signatures +Copying blob sha256:88286f41530e93dffd4b964e1db22ce4939fffa4a4c665dab8591fbab03d4926 + 1.90 MB / 1.90 MB [========================================================] 0s +Copying config sha256:76da55c8019d7a47c347c0dceb7a6591144d232a7dd616242a367b8bed18ecbc + 1.48 KB / 1.48 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +04660052281190168dbb2362eb15bf7067a8dc642d2498055e0e72efa961a4b6 +``` + +``` +$ podman pull --authfile temp-auths/myauths.json docker://docker.io/umohnani/finaltest +Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures +Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913 + 1.90 MB / 1.90 MB [========================================================] 0s +Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156 + 1.41 KB / 1.41 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438 +``` + +``` +$ podman pull --creds testuser:testpassword docker.io/umohnani/finaltest +Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures +Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913 + 1.90 MB / 1.90 MB [========================================================] 0s +Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156 + 1.41 KB / 1.41 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438 +``` + +``` +$ podman pull --tls-verify=false --cert-dir image/certs docker.io/umohnani/finaltest +Trying to pull docker.io/umohnani/finaltest:latest...Getting image source signatures +Copying blob sha256:6d987f6f42797d81a318c40d442369ba3dc124883a0964d40b0c8f4f7561d913 + 1.90 MB / 1.90 MB [========================================================] 0s +Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156 + 1.41 KB / 1.41 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +03290064078cb797f3e0a530e78c20c13dd22a3dd3adf84a5da2127b48df0438 +``` +## FILES + +**registries.conf** (`/etc/containers/registries.conf`) + + registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. + +## SEE ALSO +podman(1), podman-push(1), podman-login(1), containers-registries.conf(5) + +## HISTORY +July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-push.1.md b/docs/source/man/podman-push.1.md new file mode 100644 index 000000000..3f0350bcd --- /dev/null +++ b/docs/source/man/podman-push.1.md @@ -0,0 +1,148 @@ +% podman-push(1) + +## NAME +podman\-push - Push an image from local storage to elsewhere + +## SYNOPSIS +**podman push** [*options*] *image* [*destination*] + +**podman image push** [*options*] *image* [*destination*] + +## DESCRIPTION +Pushes an image from local storage to a specified destination. +Push is mainly used to push images to registries, however **podman push** +can be used to save images to tarballs and directories using the following +transports: **dir:**, **docker-archive:**, **docker-daemon:** and **oci-archive:**. + +## imageID +Image stored in local container/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. + + 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. + + **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)`. + + **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. + + **docker-daemon:**_docker-reference_ + An image _docker-reference_ stored in the docker daemon internal storage. _docker-reference_ must contain either a tag or a digest. Alternatively, when reading images, the format can also be docker-daemon:algo:digest (an image ID). + + **oci-archive:**_path_**:**_tag_ + An image _tag_ in a directory compliant with "Open Container Image Layout Specification" at _path_. + +## OPTIONS + +**--authfile**=*path* + +Path of the authentication file. Default is ${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`. (Not available for remote commands) + +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` + +**--creds**=*[username[:password]]* + +The [username[:password]] to use to authenticate with the registry if required. +If one or both values are not supplied, a command line prompt will appear and the +value can be entered. The password is entered without echo. + +**--cert-dir**=*path* + +Use certificates at *path* (\*.crt, \*.cert, \*.key) to connect to the registry. +Default certificates directory is _/etc/containers/certs.d_. (Not available for remote commands) + +**--compress** + +Compress tarball image layers when pushing to a directory using the 'dir' transport. (default is same compression type, compressed or uncompressed, as source) +Note: This flag can only be set when using the **dir** transport + +**--digestfile** *Digestfile* + +After copying the image, write the digest of the resulting image to the file. (Not available for remote commands) + +**--format**, **-f**=*format* + +Manifest Type (oci, v2s1, or v2s2) to use when pushing an image to a directory using the 'dir:' transport (default is manifest type of source) +Note: This flag can only be set when using the **dir** transport + +**--quiet**, **-q** + +When writing the output image, suppress progress output + +**--remove-signatures** + +Discard any pre-existing signatures in the image + +**--sign-by**=*key* + +Add a signature at the destination using the specified key + +**--tls-verify**=*true|false* + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to 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. (Not available for remote commands) + +## EXAMPLE + +This example pushes the image specified by the imageID to a local directory in docker format. + + `# podman push imageID dir:/path/to/image` + +This example pushes the image specified by the imageID to a local directory in oci format. + + `# podman push imageID oci-archive:/path/to/layout:image:tag` + +This example pushes the image specified by the imageID to a container registry named registry.example.com + + `# podman push imageID docker://registry.example.com/repository:tag` + +This example pushes the image specified by the imageID to a container registry named registry.example.com and saves the digest in the specified digestfile. + + `# podman push --digestfile=/tmp/mydigest imageID docker://registry.example.com/repository:tag` + +This example pushes the image specified by the imageID and puts it into the local docker container store + + `# podman push imageID docker-daemon:image:tag` + +This example pushes the alpine image to umohnani/alpine on dockerhub and reads the creds from +the path given to --authfile + +``` +# podman push --authfile temp-auths/myauths.json alpine docker://docker.io/umohnani/alpine +Getting image source signatures +Copying blob sha256:5bef08742407efd622d243692b79ba0055383bbce12900324f75e56f589aedb0 + 4.03 MB / 4.03 MB [========================================================] 1s +Copying config sha256:ad4686094d8f0186ec8249fc4917b71faa2c1030d7b5a025c29f26e19d95c156 + 1.41 KB / 1.41 KB [========================================================] 1s +Writing manifest to image destination +Storing signatures +``` + +This example pushes the rhel7 image to rhel7-dir with the "oci" manifest type +``` +# podman push --format oci registry.access.redhat.com/rhel7 dir:rhel7-dir +Getting image source signatures +Copying blob sha256:9cadd93b16ff2a0c51ac967ea2abfadfac50cfa3af8b5bf983d89b8f8647f3e4 + 71.41 MB / 71.41 MB [======================================================] 9s +Copying blob sha256:4aa565ad8b7a87248163ce7dba1dd3894821aac97e846b932ff6b8ef9a8a508a + 1.21 KB / 1.21 KB [========================================================] 0s +Copying config sha256:f1b09a81455c351eaa484b61aacd048ab613c08e4c5d1da80c4c46301b03cf3b + 3.01 KB / 3.01 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +``` + +## SEE ALSO +podman(1), podman-pull(1), podman-login(1) diff --git a/docs/source/man/podman-remote.1.md b/docs/source/man/podman-remote.1.md new file mode 100644 index 000000000..04010abaf --- /dev/null +++ b/docs/source/man/podman-remote.1.md @@ -0,0 +1,145 @@ +% podman-remote(1) + +## NAME +podman-remote - A remote CLI for Podman: A Simple management tool for pods, containers and images. + +## SYNOPSIS +**podman-remote** [*options*] *command* + +## DESCRIPTION +Podman (Pod Manager) is a fully featured container engine that is a simple daemonless tool. +Podman provides a Docker-CLI comparable command line that eases the transition from other +container engines and allows the management of pods, containers and images. Simply put: `alias docker=podman`. +Most Podman commands can be run as a regular user, without requiring additional +privileges. + +Podman uses Buildah(1) internally to create container images. Both tools share image +(not container) storage, hence each can use or manipulate images (but not containers) +created by the other. + +Podman-remote provides a local client interacting with a Podman backend node through a varlink ssh connection. In this context, a Podman node is a Linux system with Podman installed on it and the varlink service activated. Credentials for this session can be passed in using flags, enviroment variables, or in `podman-remote.conf` + +**podman [GLOBAL OPTIONS]** + +## GLOBAL OPTIONS + +**--connection**=*name* + +Remote connection name + +**--help**, **-h** + +Print usage statement + +**--log-level**=*level* + +Log messages above specified level: debug, info, warn, error (default), fatal or panic + +**--port**=*integer* + +Use an alternative port for the ssh connections. The default port is 22 + +**--remote-config-path**=*path* + +Alternate path for configuration file + +**--remote-host**=*ip* + +Remote host IP + +**--syslog** + +Output logging information to syslog as well as the console + +**--username**=*string* + +Username on the remote host (defaults to current username) + +**--version** + +Print the version + +## Exit Status + +The exit code from `podman` gives information about why the container +failed to run or why it exited. When `podman` commands exit with a non-zero code, +the exit codes follow the `chroot` standard, see below: + +**_125_** if the error is with podman **_itself_** + + $ podman run --foo busybox; echo $? + Error: unknown flag: --foo + 125 + +**_126_** if executing a **_contained command_** and the **_command_** cannot be invoked + + $ podman run busybox /etc; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error + 126 + +**_127_** if executing a **_contained command_** and the **_command_** cannot be found + $ podman run busybox foo; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error + 127 + +**_Exit code_** of **_contained command_** otherwise + + $ podman run busybox /bin/sh -c 'exit 3' + # 3 + + +## COMMANDS + +| Command | Description | +| ------------------------------------------------ | --------------------------------------------------------------------------- | +| [podman-attach(1)](podman-attach.1.md) | Attach to a running container. | +| [podman-build(1)](podman-build.1.md) | Build a container image using a Dockerfile. | +| [podman-commit(1)](podman-commit.1.md) | Create new image based on the changed container. | +| [podman-container(1)](podman-container.1.md) | Manage containers. | +| [podman-cp(1)](podman-cp.1.md) | Copy files/folders between a container and the local filesystem. | +| [podman-create(1)](podman-create.1.md) | Create a new container. | +| [podman-diff(1)](podman-diff.1.md) | Inspect changes on a container or image's filesystem. | +| [podman-events(1)](podman-events.1.md) | Monitor Podman events | +| [podman-export(1)](podman-export.1.md) | Export a container's filesystem contents as a tar archive. | +| [podman-generate(1)](podman-generate.1.md) | Generate structured data based for a containers and pods. | +| [podman-healthcheck(1)](podman-healthcheck.1.md) | Manage healthchecks for containers | +| [podman-history(1)](podman-history.1.md) | Show the history of an image. | +| [podman-image(1)](podman-image.1.md) | Manage images. | +| [podman-images(1)](podman-images.1.md) | List images in local storage. | +| [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | +| [podman-info(1)](podman-info.1.md) | Displays Podman related system information. | +| [podman-init(1)](podman-init.1.md) | Initialize a container | +| [podman-inspect(1)](podman-inspect.1.md) | Display a container or image's configuration. | +| [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. | +| [podman-load(1)](podman-load.1.md) | Load an image from a container image archive into container storage. | +| [podman-logs(1)](podman-logs.1.md) | Display the logs of a container. | +| [podman-pause(1)](podman-pause.1.md) | Pause one or more containers. | +| [podman-pod(1)](podman-pod.1.md) | Management tool for groups of containers, called pods. | +| [podman-port(1)](podman-port.1.md) | List port mappings for a container. | +| [podman-ps(1)](podman-ps.1.md) | Prints out information about containers. | +| [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. | +| [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. | +| [podman-restart(1)](podman-restart.1.md) | Restart one or more containers. | +| [podman-rm(1)](podman-rm.1.md) | Remove one or more containers. | +| [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. | +| [podman-run(1)](podman-run.1.md) | Run a command in a new container. | +| [podman-save(1)](podman-save.1.md) | Save an image to a container archive. | +| [podman-start(1)](podman-start.1.md) | Start one or more containers. | +| [podman-stop(1)](podman-stop.1.md) | Stop one or more running containers. | +| [podman-system(1)](podman-system.1.md) | Manage podman. | +| [podman-tag(1)](podman-tag.1.md) | Add an additional name to a local image. | +| [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | +| [podman-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. | + +## FILES + +**podman-remote.conf** (`~/.config/containers/podman-remote.conf`) + + The podman-remote.conf file is the default configuration file for the podman + remote client. It is in the TOML format. It is primarily used to keep track + of the user's remote connections. + +## SEE ALSO +`podman-remote.conf(5)` diff --git a/docs/source/man/podman-restart.1.md b/docs/source/man/podman-restart.1.md new file mode 100644 index 000000000..08fa29244 --- /dev/null +++ b/docs/source/man/podman-restart.1.md @@ -0,0 +1,68 @@ +% podman-restart(1) + +## NAME +podman\-restart - Restart one or more containers + +## SYNOPSIS +**podman restart** [*options*] *container* ... + +**podman container restart** [*options*] *container* ... + +## DESCRIPTION +The restart command allows containers to be restarted using their ID or name. +Containers will be stopped if they are running and then restarted. Stopped +containers will not be stopped and will only be started. + +## OPTIONS +**--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. + +The latest option is not supported on the remote client. + +**--running** +Restart all containers that are already in the *running* state. + +**--timeout**=*time* +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) + +## HISTORY +March 2018, Originally compiled by Matt Heon <mheon@redhat.com> diff --git a/docs/source/man/podman-rm.1.md b/docs/source/man/podman-rm.1.md new file mode 100644 index 000000000..207d9d61d --- /dev/null +++ b/docs/source/man/podman-rm.1.md @@ -0,0 +1,82 @@ +% podman-rm(1) + +## NAME +podman\-rm - Remove one or more containers + +## SYNOPSIS +**podman rm** [*options*] *container* + +**podman container rm** [*options*] *container* + +## DESCRIPTION +**podman rm** will remove one or more containers from the host. The container name or ID can be used. This does not remove images. +Running or unusable containers will not be removed without the `-f` option. + +## OPTIONS + +**--all**, **-a** + +Remove all containers. Can be used in conjunction with -f as well. + +**--force**, **-f** + +Force the removal of running and paused containers. Forcing a container 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. +In addition, forcing can be used to remove unusable containers, e.g. containers +whose OCI runtime has become unavailable. + +**--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 latest option is not supported on the remote client. + +**--storage** + +Remove the container from the storage library only. +This is only possible with containers that are not present in libpod (cannot be seen by `podman ps`). +It is used to remove containers from `podman build` and `buildah`, and orphan containers which were only partially removed by `podman rm`. +The storage option conflicts with the **--all**, **--latest**, and **--volumes** options. + +**--volumes**, **-v** + +Remove the volumes associated with the container. + +## 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 +``` + +## Exit Status +**_0_** if all specified containers removed +**_1_** if one of the specified containers did not exist, and no other failures +**_2_** if one of the specified containers is paused or running +**_125_** if the command fails for a reason other than container did not exist or is paused/running + +## SEE ALSO +podman(1), podman-image-rm(1) + +## HISTORY +August 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/man/podman-rmi.1.md b/docs/source/man/podman-rmi.1.md new file mode 100644 index 000000000..d911ee6cb --- /dev/null +++ b/docs/source/man/podman-rmi.1.md @@ -0,0 +1,53 @@ +% podman-rmi(1) + +## NAME +podman\-rmi - Removes one or more locally stored images + +## SYNOPSIS +**podman rmi** *image* [...] + +**podman image rm** *image* [...] + +## DESCRIPTION +Removes one or more locally stored images. + +## OPTIONS + +**-all**, **-a** + +Remove all images in the local storage. + +**--force**, **-f** + +This option will cause podman to remove all containers that are using the image before removing the image from the system. + + +Remove an image by its short ID +``` +podman rmi c0ed59d05ff7 +``` +Remove an image and its associated containers. +``` +podman rmi --force imageID +```` + +Remove multiple images by their shortened IDs. +``` +podman rmi c4dfb1609ee2 93fd78260bd1 c0ed59d05ff7 +``` + +Remove all images and containers. +``` +podman rmi -a -f +``` +## Exit Status +**_0_** if all specified images removed +**_1_** if one of the specified images did not exist, and no other failures +**_2_** if one of the specified images has child images or is being used by a container +**_125_** if the command fails for a reason other than an image did not exist or is in use + +## SEE ALSO +podman(1) + +## HISTORY +March 2017, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-run.1.md b/docs/source/man/podman-run.1.md new file mode 100644 index 000000000..d6d8f4c1e --- /dev/null +++ b/docs/source/man/podman-run.1.md @@ -0,0 +1,1310 @@ +% podman-run(1) + +## NAME +podman\-run - Run a command in a new container + +## SYNOPSIS +**podman run** [*options*] *image* [*command* [*arg* ...]] + +**podman container run** [*options*] *image* [*command* [*arg* ...]] + +## DESCRIPTION + +Run a process in a new container. **podman run** starts a process with its own +file system, its own networking, and its own isolated process tree. The IMAGE +which starts the process may define defaults related to the process that will be +run in the container, the networking to expose, and more, but **podman run** +gives final control to the operator or administrator who starts the container +from the image. For that reason **podman run** has more options than any other +podman command. + +If the IMAGE is not already loaded then **podman run** will pull the IMAGE, and +all image dependencies, from the repository in the same way running **podman +pull** IMAGE, before it starts the container from that image. + +Several files will be automatically created within the container. These include +`/etc/hosts`, `/etc/hostname`, and `/etc/resolv.conf` to manage networking. +These will be based on the host's version of the files, though they can be +customized with options (for example, **--dns** will override the host's DNS +servers in the created `resolv.conf`). Additionally, an empty file is created in +each container to indicate to programs they are running in a container. This file +is located at `/run/.containerenv`. + +When running from a user defined network namespace, the /etc/netns/NSNAME/resolv.conf will be used if it exists, otherwise /etc/resolv.conf will be used. + +## OPTIONS +**--add-host**=*host:ip* + +Add a custom host-to-IP mapping (host:ip) + +Add a line to /etc/hosts. The format is hostname:ip. The **--add-host** +option can be set multiple times. + +**--annotation**=*key=value* + +Add an annotation to the container. The format is key=value. +The **--annotation** option can be set multiple times. + +**--attach**, **-a**=*stdio* + +Attach to STDIN, STDOUT or STDERR. + +In foreground mode (the default when **-d** +is not specified), **podman run** can start the process in the container +and attach the console to the process's standard input, output, and standard +error. It can even pretend to be a TTY (this is what most commandline +executables expect) and pass along signals. The **-a** option can be set for +each of stdin, stdout, and stderr. + +**--authfile**[=*path*] + +Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json (Not available for remote commands) + +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` + +**--blkio-weight**=*weight* + +Block IO weight (relative weight) accepts a weight value between 10 and 1000. + +**--blkio-weight-device**=*DEVICE_NAME:WEIGHT* + +Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`). + +**--cap-add**=*capability* + +Add Linux capabilities + +**--cap-drop**=*capability* + +Drop Linux capabilities + +**--cgroupns**=*mode* + +Set the cgroup namespace mode for the container, by default **host** is used. + **host**: use the host's cgroup namespace inside the container. + **container:<NAME|ID>**: join the namespace of the specified container. + **private**: create a new cgroup namespace. + **ns:<PATH>**: join the namespace at the specified path. + +**--cgroups**=*mode* + +Determines whether the container will create CGroups. +Valid values are *enabled* and *disabled*, which the default being *enabled*. +The *disabled* option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**). + +**--cgroup-parent**=*cgroup* + +Path to cgroups under which the cgroup for the container will be created. If the path is not absolute, the path is considered to be relative to the cgroups path of the init process. Cgroups will be created if they do not already exist. + +**--cidfile**=*file* + +Write the container ID to the file + +**--conmon-pidfile**=*file* + +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**=*limit* + +Limit the CPU CFS (Completely Fair Scheduler) period + +Limit the container's CPU usage. This flag tell the kernel to restrict the container's CPU usage to the period you specify. + +**--cpu-quota**=*limit* + +Limit the CPU CFS (Completely Fair Scheduler) quota + +Limit the container's CPU usage. By default, containers run with the full +CPU resource. This flag tell the kernel to restrict the container's CPU usage +to the quota you specify. + +**--cpu-rt-period**=*microseconds* + +Limit the CPU real-time period in microseconds + +Limit the container's Real Time CPU usage. This flag tell the kernel to restrict the container's Real Time CPU usage to the period you specify. + +**--cpu-rt-runtime**=*microseconds* + +Limit the CPU real-time runtime in microseconds + +Limit the containers Real Time CPU usage. This flag tells the kernel to limit the amount of time in a given CPU period Real Time tasks may consume. Ex: +Period of 1,000,000us and Runtime of 950,000us means that this container could consume 95% of available CPU and leave the remaining 5% to normal priority tasks. + +The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup. + +**--cpu-shares**=*shares* + +CPU shares (relative weight) + +By default, all containers get the same proportion of CPU cycles. This proportion +can be modified by changing the container's CPU share weighting relative +to the weighting of all other running containers. + +To modify the proportion from the default of 1024, use the **--cpu-shares** +flag to set the weighting to 2 or higher. + +The proportion will only apply when CPU-intensive processes are running. +When tasks in one container are idle, other containers can use the +left-over CPU time. The actual amount of CPU time will vary depending on +the number of containers running on the system. + +For example, consider three containers, one has a cpu-share of 1024 and +two others have a cpu-share setting of 512. When processes in all three +containers attempt to use 100% of CPU, the first container would receive +50% of the total CPU time. If you add a fourth container with a cpu-share +of 1024, the first container only gets 33% of the CPU. The remaining containers +receive 16.5%, 16.5% and 33% of the CPU. + +On a multi-core system, the shares of CPU time are distributed over all CPU +cores. Even if a container is limited to less than 100% of CPU time, it can +use 100% of each individual CPU core. + +For example, consider a system with more than three cores. If you start one +container **{C0}** with **-c=512** running one process, and another container +**{C1}** with **-c=1024** running two processes, this can result in the following +division of CPU shares: + +PID container CPU CPU share +100 {C0} 0 100% of CPU0 +101 {C1} 1 100% of CPU1 +102 {C1} 2 100% of CPU2 + +**--cpus**=*number* + +Number of CPUs. The default is *0.0* which means no limit. + +**--cpuset-cpus**=*number* + +CPUs in which to allow execution (0-3, 0,1) + +**--cpuset-mems**=*nodes* + +Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems. + +If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1` +then processes in your container will only use memory from the first +two memory nodes. + +**--detach**, **-d**=*true|false* + +Detached mode: run the container in the background and print the new container ID. The default is *false*. + +At any time you can run **podman ps** in +the other shell to view a list of the running containers. You can reattach to a +detached container with **podman attach**. + +When attached in the tty mode, you can detach from the container (and leave it +running) using a configurable key sequence. The default sequence is `ctrl-p,ctrl-q`. +Configure the keys sequence using the **--detach-keys** option, or specifying +it in the **libpod.conf** file: see **libpod.conf(5)** for more information. + +**--detach-keys**=*sequence* + +Override the key sequence for detaching a container. Format is a single character `[a-Z]` or +a comma separated sequence of `ctrl-<value>`, where `<value>` is one of: +`a-z`, `@`, `^`, `[`, `\\`, `]`, `^` or `_`. + +**--device**=*device* + +Add a host device to the container. The format is `<device-on-host>[:<device-on-container>][:<permissions>]` (e.g. --device=/dev/sdc:/dev/xvdc:rwm) + +**--device-read-bps**=*path* + +Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb) + +**--device-read-iops**=*path* + +Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000) + +**--device-write-bps**=*path* + +Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb) + +**--device-write-iops**=*path* + +Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000) + +**--dns**=*dns* + +Set custom DNS servers. Invalid if using **--dns** with **--network** that is set to 'none' or 'container:<name|id>'. + +This option can be used to override the DNS +configuration passed to the container. Typically this is necessary when the +host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this +is the case the **--dns** flags is necessary for every run. + +The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman. +The **/etc/resolv.conf** file in the image will be used without changes. + +**--dns-option**=*option* + +Set custom DNS options. Invalid if using **--dns-option** with **--network** that is set to 'none' or 'container:<name|id>'. + +**--dns-search**=*domain* + +Set custom DNS search domains. Invalid if using **--dns-search** and **--network** that is set to 'none' or 'container:<name|id>'. (Use --dns-search=. if you don't wish to set the search domain) + +**--entrypoint**=*"command"* | *'["command", "arg1", ...]'* + +Overwrite the default ENTRYPOINT of the image + +This option allows you to overwrite the default entrypoint of the image. + +The ENTRYPOINT of an image is similar to a COMMAND +because it specifies what executable to run when the container starts, but it is +(purposely) more difficult to override. The ENTRYPOINT gives a container its +default nature or behavior, so that when you set an ENTRYPOINT you can run the +container as if it were that binary, complete with default options, and you can +pass in more options via the COMMAND. But, sometimes an operator may want to run +something else inside the container, so you can override the default ENTRYPOINT +at runtime by using a **--entrypoint** and a string to specify the new +ENTRYPOINT. + +You need to specify multi option commands in the form of a json string. + +**--env**, **-e**=*env* + +Set environment variables + +This option allows arbitrary environment variables that are available for the process to be launched inside of the container. If an environment variable is specified without a value, Podman will check the host environment for a value and set the variable only if it is set on the host. If an environment variable ending in __*__ is specified, Podman will search the host environment for variables starting with the prefix and will add those variables to the container. If an environment variable with a trailing ***** is specified, then a value must be supplied. + +See [**Environment**](#environment) note below for precedence and examples. + +**--env-host**=*true|false* + +Use host environment inside of the container. See **Environment** note below for precedence. + +**--env-file**=*file* + +Read in a line delimited file of environment variables. See **Environment** note below for precedence. + +**--expose**=*port* + +Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection +on the host system. + +**--gidmap**=*container_gid:host_gid:amount* + +Run the container in a new user namespace using the supplied mapping. This option conflicts with the --userns and --subgidname flags. +This option can be passed several times to map different ranges. If calling Podman run as an unprivileged user, the user needs to have the right to use the mapping. See `subuid(5)`. +The example maps gids 0-1999 in the container to the gids 30000-31999 on the host. `--gidmap=0:30000:2000` + +**--group-add**=*group* + +Add additional groups to run as + +**--health-cmd**=*"command"* | *'["command", "arg1", ...]'* + +Set or alter a healthcheck command for a container. The command is a command to be executed inside your +container that determines your container health. The command is required for other healthcheck options +to be applied. A value of `none` disables existing healthchecks. + +Multiple options can be passed in the form of a JSON array; otherwise, the command will be interpreted +as an argument to `/bin/sh -c`. + +**--health-interval**=*interval* + +Set an interval for the healthchecks (a value of `disable` results in no automatic timer setup) (default "30s") + +**--health-retries**=*retries* + +The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is `3`. + +**--health-start-period**=*period* + +The initialization time needed for a container to bootstrap. The value can be expressed in time format like +`2m3s`. The default value is `0s` + +**--health-timeout**=*timeout* + +The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the +value can be expressed in a time format such as `1m22s`. The default value is `30s`. + +**--help** + +Print usage statement + +**--hostname**=*name* + +Container host name + +Sets the container host name that is available inside the container. + +**--http-proxy**=*true|false* + +By default proxy environment variables are passed into the container if set +for the Podman process. This can be disabled by setting the `--http-proxy` +option to `false`. The environment variables passed in include `http_proxy`, +`https_proxy`, `ftp_proxy`, `no_proxy`, and also the upper case versions of +those. This option is only needed when the host system must use a proxy but +the container should not use any proxy. Proxy environment variables specified +for the container in any other way will override the values that would have +been passed thru from the host. (Other ways to specify the proxy for the +container include passing the values with the `--env` flag, or hard coding the +proxy environment at container build time.) + +For example, to disable passing these environment variables from host to +container: + +`--http-proxy=false` + +Defaults to `true` + +**--image-volume**, **builtin-volume**=*bind|tmpfs|ignore* + +Tells Podman how to handle the builtin image volumes. + +The options are: `bind`, `tmpfs`, or `ignore` (default `bind`) + +- `bind`: A directory is created inside the container state directory and bind mounted into +the container for the volumes. +- `tmpfs`: The volume is mounted onto the container as a tmpfs, which allows the users to create +content that disappears when the container is stopped. +- `ignore`: All volumes are just ignored and no action is taken. + +**--init** + +Run an init inside the container that forwards signals and reaps processes. + +**--init-path**=*path* + +Path to the container-init binary. + +**--interactive**, **-i**=*true|false* + +When set to true, keep stdin open even if not attached. The default is *false*. + +**--ip6**=*ip* + +Not implemented + +**--ip**=*ip* + +Specify a static IP address for the container, for example '10.88.64.128'. +Can only be used if no additional CNI networks to join were specified via '--network=<network-name>', and if the container is not joining another container's network namespace via '--network=container:<name|id>'. +The address must be within the default CNI network's pool (default 10.88.0.0/16). + +**--ipc**=*ipc* + +Default is to create a private IPC namespace (POSIX SysV IPC) for the container + +- `container:<name|id>`: reuses another container shared memory, semaphores and message queues +- `host`: use the host shared memory,semaphores and message queues inside the container. Note: the host mode gives the container full access to local shared memory and is therefore considered insecure. +- `ns:<path>` path to an IPC namespace to join. + +**--kernel-memory**=*number[unit]* + +Kernel memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +Constrains the kernel memory available to a container. If a limit of 0 +is specified (not using `--kernel-memory`), the container's kernel memory +is not limited. If you specify a limit, it may be rounded up to a multiple +of the operating system's page size and the value can be very large, +millions of trillions. + +**--label**, **-l**=*label* + +Add metadata to a container (e.g., --label com.example.key=value) + +**--label-file**=*file* + +Read in a line delimited file of labels + +**--link-local-ip**=*ip* + +Not implemented + +**--log-driver**="*k8s-file*" + +Logging driver for the container. Currently available options are *k8s-file* and *journald*, with *json-file* aliased to *k8s-file* for scripting compatibility. + +**--log-opt**=*path* + +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**=*address* + +Container MAC address (e.g. `92:d0:c6:0a:29:33`) + +Remember that the MAC address in an Ethernet network must be unique. +The IPv6 link-local address will be based on the device's MAC address +according to RFC4862. + +Not currently supported + +**--memory**, **-m**=*limit* + +Memory limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +Allows you to constrain the memory available to a container. If the host +supports swap memory, then the **-m** memory setting can be larger than physical +RAM. If a limit of 0 is specified (not using **-m**), the container's memory is +not limited. The actual limit may be rounded up to a multiple of the operating +system's page size (the value would be very large, that's millions of trillions). + +**--memory-reservation**=*limit* + +Memory soft limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) + +After setting memory reservation, when the system detects memory contention +or low memory, containers are forced to restrict their consumption to their +reservation. So you should always set the value below **--memory**, otherwise the +hard limit will take precedence. By default, memory reservation will be the same +as memory limit. + +**--memory-swap**=*limit* + +A limit value equal to memory plus swap. Must be used with the **-m** +(**--memory**) flag. The swap `LIMIT` should always be larger than **-m** +(**--memory**) value. By default, the swap `LIMIT` will be set to double +the value of --memory. + +The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes), +`k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a +unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap. + +**--memory-swappiness**=*number* + +Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100. + +**--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]* + +Attach a filesystem mount to the container + +Current supported mount TYPES are `bind`, `volume`, and `tmpfs`. + + e.g. + + type=bind,source=/path/on/host,destination=/path/in/container + + type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared + + type=volume,source=vol1,destination=/path/in/container,ro=true + + type=tmpfs,tmpfs-size=512M,destination=/path/in/container + + Common Options: + + · src, source: mount source spec for bind and volume. Mandatory for bind. + + · dst, destination, target: mount destination spec. + + · ro, read-only: true or false (default). + + Options specific to bind: + + · bind-propagation: shared, slave, private, rshared, rslave, or rprivate(default). See also mount(2). + + . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive. + + . relabel: shared, private. + + Options specific to tmpfs: + + · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux. + + · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux. + +**--name**=*name* + +Assign a name to the container + +The operator can identify a container in three ways: +- UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”) +- 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 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. + +**--network**, **--net**=*node* + +Set the Network mode for the container. Invalid if using **--dns**, **--dns-option**, or **--dns-search** with **--network** that is set to 'none' or 'container:<name|id>'. + +Valid values are: + +- `bridge`: create a network stack on the default bridge +- `none`: no networking +- `container:<name|id>`: reuse another container's network stack +- `host`: use the Podman host network stack. Note: the host mode gives the container full access to local system services such as D-bus and is therefore considered insecure. +- `<network-name>|<network-id>`: connect to a user-defined network, multiple networks should be comma separated +- `ns:<path>`: path to a network namespace to join +- `slirp4netns`: use slirp4netns to create a user network stack. This is the default for rootless containers + +**--network-alias**=*alias* + +Not implemented + +**--no-hosts**=*true|false* + +Do not create /etc/hosts for the container. +By default, Podman will manage /etc/hosts, adding the container's own IP address and any hosts from **--add-host**. +**--no-hosts** disables this, and the image's **/etc/host** will be preserved unmodified. +This option conflicts with **--add-host**. + +**--oom-kill-disable**=*true|false* + +Whether to disable OOM Killer for the container or not. + +**--oom-score-adj**=*num* + +Tune the host's OOM preferences for containers (accepts -1000 to 1000) + +**--pid**=*pid* + +Set the PID mode for the container + +Default is to create a private PID namespace for the container + +- `container:<name|id>`: join another container's PID namespace +- `host`: use the host's PID namespace for the container. Note: the host mode gives the container full access to local PID and is therefore considered insecure. +- `ns`: join the specified PID namespace + +**--pids-limit**=*limit* + +Tune the container's pids limit. Set `0` to have unlimited pids for the container. (default "4096" on systems that support PIDS cgroups). + +**--pod**=*name* + +Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`. +To make a pod with more granular options, use the `podman pod create` command before creating a container. +If a container is run with a pod, and the pod has an infra-container, the infra-container will be started before the container is. + +**--privileged**=*true|false* + +Give extended privileges to this container. The default is *false*. + +By default, Podman containers are “unprivileged” (=false) and cannot, +for example, modify parts of the kernel. This is because by default a +container is not allowed to access any devices. A “privileged” container +is given access to all devices. + +When the operator executes **podman run --privileged**, Podman enables access +to all devices on the host, turns off graphdriver mount options, as well as +turning off most of the security measures protecting the host from the +container. + +**--publish**, **-p**=*port* + +Publish a container's port, or range of ports, to the host + +Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort` + +Both hostPort and containerPort can be specified as a range of ports. + +When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range. +(e.g., `podman run -p 1234-1236:1222-1224 --name thisWorks -t busybox` +but not `podman run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox`) + +With ip: `podman run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage` + +Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT` + +**--publish-all**, **-P**=*true|false* + +Publish all exposed ports to random ports on the host interfaces. The default is *false*. + +When set to true publish all exposed ports to the host interfaces. The +default is false. If the operator uses -P (or -p) then Podman will make the +exposed port accessible on the host and the ports will be available to any +client that can reach the host. + +When using -P, Podman will bind any exposed port to a random port on the host +within an *ephemeral port range* defined by `/proc/sys/net/ipv4/ip_local_port_range`. +To find the mapping between the host ports and the exposed ports, use `podman port`. + +**--pull**=*missing* + +Pull image before running ("always"|"missing"|"never") (default "missing"). + 'missing': default value, attempt to pull the latest image from the registries listed in registries.conf if a local image does not exist.Raise an error if the image is not in any listed registry and is not present locally. + 'always': Pull the image from the first registry it is found in as listed in registries.conf. Raise an error if not found in the registries, even if the image is present locally. + 'never': do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally. + +Defaults to *missing*. + +**--quiet**, **-q** + +Suppress output information when pulling images + +**--read-only**=*true|false* + +Mount the container's root filesystem as read only. + +By default a container will have its root filesystem writable allowing processes +to write files anywhere. By specifying the `--read-only` flag the container will have +its root filesystem mounted as read only prohibiting any writes. + +**--read-only-tmpfs**=*true|false* + +If container is running in --read-only mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The default is *true* + +**--restart**=*policy* + +Restart policy to follow when containers exit. +Restart policy will not take effect if a container is stopped via the `podman kill` or `podman stop` commands. + +Valid values are: + +- `no` : Do not restart containers on exit +- `on-failure[:max_retries]` : Restart containers when they exit with a non-0 exit code, retrying indefinitely or until the optional max_retries count is hit +- `always` : Restart containers when they exit, regardless of status, retrying indefinitely + +Please note that restart will not restart containers after a system reboot. +If this functionality is required in your environment, you can invoke Podman from a systemd unit file, or create an init script for whichever init system is in use. +To generate systemd unit files, please see *podman generate systemd* + +**--rm**=*true|false* + +Automatically remove the container when it exits. The default is *false*. + +Note that the container will not be removed when it could not be created or +started successfully. This allows the user to inspect the container after +failure. + +**--rootfs** + +If specified, the first argument refers to an exploded container on the file system. + +This is useful to run a container without requiring any image management, the rootfs +of the container is assumed to be managed externally. + +Note: On `SELinux` systems, the rootfs needs the correct label, which is by default +`unconfined_u:object_r:container_file_t`. + +**--security-opt**=*option* + +Security Options + +- `apparmor=unconfined` : Turn off apparmor confinement for the container +- `apparmor=your-profile` : Set the apparmor confinement profile for the container + +- `label=user:USER` : Set the label user for the container processes +- `label=role:ROLE` : Set the label role for the container processes +- `label=type:TYPE` : Set the label process type for the container processes +- `label=level:LEVEL` : Set the label level for the container processes +- `label=filetype:TYPE` : Set the label file type for the container files +- `label=disable` : Turn off label separation for the container + +- `no-new-privileges` : Disable container processes from gaining additional privileges + +- `seccomp=unconfined` : Turn off seccomp confinement for the container +- `seccomp=profile.json` : White listed syscalls seccomp Json file to be used as a seccomp filter + +Note: Labeling can be disabled for all containers by setting label=false in the **libpod.conf** (`/etc/containers/libpod.conf`) file. + +**--shm-size**=*size* + +Size of `/dev/shm` (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes)) +If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`. +When size is `0`, there is no limit on the amount of memory used for IPC by the container. + +**--sig-proxy**=*true|false* + +Proxy signals sent to the `podman run` command to the container process. SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true*. + +**--stop-signal**=*SIGTERM* + +Signal to stop a container. Default is SIGTERM. + +**--stop-timeout**=*seconds* + +Timeout (in seconds) to stop a container. Default is 10. + +**--subgidname**=*name* + +Run the container in a new user namespace using the map with 'name' in the `/etc/subgid` file. +If calling Podman run as an unprivileged user, the user needs to have the right to use the mapping. See `subgid(5)`. +This flag conflicts with `--userns` and `--gidmap`. + +**--subuidname**=*name* + +Run the container in a new user namespace using the map with 'name' in the `/etc/subuid` file. +If calling Podman run as an unprivileged user, the user needs to have the right to use the mapping. See `subuid(5)`. +This flag conflicts with `--userns` and `--uidmap`. + +**--sysctl**=SYSCTL + +Configure namespaced kernel parameters at runtime + +IPC Namespace - current sysctls allowed: + +- kernel.msgmax +- kernel.msgmnb +- kernel.msgmni +- kernel.sem +- kernel.shmall +- kernel.shmmax +- kernel.shmmni +- kernel.shm_rmid_forced +- Sysctls beginning with fs.mqueue.* + +Note: if you use the `--ipc=host` option these sysctls will not be allowed. + +Network Namespace - current sysctls allowed: +- Sysctls beginning with net.* + +Note: if you use the `--network=host` option these sysctls will not be allowed. + +**--systemd**=*true|false|always* + +Run container in systemd mode. The default is *true*. + +The value *always* enforces the systemd mode is enforced without +looking at the executable name. Otherwise, if set to true and the +command you are running inside the container is systemd, /usr/sbin/init +or /sbin/init. + +If the command you are running inside of the container is systemd +Podman will setup tmpfs mount points in the following directories: + +/run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal + +It will also set the default stop signal to SIGRTMIN+3. + +This allows systemd to run in a confined container without any modifications. + +Note: On `SELinux` systems, systemd attempts to write to the cgroup +file system. Containers writing to the cgroup file system are denied by default. +The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system. + +`setsebool -P container_manage_cgroup true` + +**--tmpfs**=*fs* + +Create a tmpfs mount + +Mount a temporary filesystem (`tmpfs`) mount into a container, for example: + +$ podman run -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image + +This command mounts a `tmpfs` at `/tmp` within the container. The supported mount +options are the same as the Linux default `mount` flags. If you do not specify +any options, the systems uses the following options: +`rw,noexec,nosuid,nodev`. + +**--tty**, **-t**=*true|false* + +Allocate a pseudo-TTY. The default is *false*. + +When set to true Podman will allocate a pseudo-tty and attach to the standard +input of the container. This can be used, for example, to run a throwaway +interactive shell. The default is false. + +**NOTE**: The **-t** option is incompatible with a redirection of the Podman client +standard input. + +**--uidmap**=*container_uid:host_uid:amount* + +Run the container in a new user namespace using the supplied mapping. This option conflicts with the --userns and --subuidname flags. +This option can be passed several times to map different ranges. If calling Podman run as an unprivileged user, the user needs to have the right to use the mapping. See `subuid(5)`. +The example maps uids 0-1999 in the container to the uids 30000-31999 on the host. `--uidmap=0:30000:2000` + +**--ulimit**=*option* + +Ulimit options + +You can pass `host` to copy the current configuration from the host. + +**--user**, **-u**=*user* + +Sets the username or UID used and optionally the groupname or GID for the specified command. + +The followings examples are all valid: +--user [user | user:group | uid | uid:gid | user:gid | uid:group ] + +Without this argument the command will be run as root in the container. + +**--userns**=host +**--userns**=keep-id +**--userns**=container:container +**--userns**=ns:my_namespace + +Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled. + +- `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. +- `keep-id`: creates a user namespace where the current rootless user's UID:GID are mapped to the same values in the container. This option is ignored for containers created by the root user. +- `ns`: run the container in the given existing user namespace. +- `container`: join the user namespace of the specified container. + +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 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**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*] + +Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman +bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman +container. Similarly, `-v VOLUME-NAME:/CONTAINER-DIR` will mount the volume +in the host to the container. If no such named volume exists, Podman will +create one. + + The `OPTIONS` are a comma delimited list and can be: + +* [`rw`|`ro`] +* [`z`|`Z`] +* [`[r]shared`|`[r]slave`|`[r]private`] + +The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume +will be mounted into the container at this directory. + +Volumes may specify a source as well, as either a directory on the host or the +name of a named volume. If no source is given, the volume will be created as an +anonymous named volume with a randomly generated name, and will be removed when +the container is removed via the `--rm` flag or `podman rm --volumes`. + +If a volume source is specified, it must be a path on the host or the name of a +named volume. Host paths are allowed to be absolute or relative; relative paths +are resolved relative to the directory Podman is run in. Any source that does +not begin with a `.` or `/` it will be treated as the name of a named volume. +If a volume with that name does not exist, it will be created. Volumes created +with names are not anonymous and are not removed by `--rm` and +`podman rm --volumes`. + +You can specify multiple **-v** options to mount one or more volumes into a +container. + +You can add `:ro` or `:rw` suffix to a volume to mount it read-only or +read-write mode, respectively. By default, the volumes are mounted read-write. +See examples. + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a container. Without a label, the security system might +prevent the processes running inside the container from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the container context, you can add either of two suffixes +`:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file +objects on the shared volumes. The `z` option tells Podman that two containers +share the volume content. As a result, Podman labels the content with a shared +content label. Shared volume labels allow all containers to read/write content. +The `Z` option tells Podman to label the content with a private unshared label. +Only the current container can use a private volume. + +By default bind mounted volumes are `private`. That means any mounts done +inside container will not be visible on host and vice versa. One can change +this behavior by specifying a volume mount propagation property. Making a +volume `shared` mounts done under that volume inside container will be +visible on host and vice versa. Making a volume `slave` enables only one +way mount propagation and that is mounts done on host under that volume +will be visible inside container but not the other way around. + +To control mount propagation property of volume one can use `:[r]shared`, +`:[r]slave` or `:[r]private` propagation flag. Propagation property can +be specified only for bind mounted volumes and not for internal volumes or +named volumes. For mount propagation to work source mount point (mount point +where source dir is mounted on) has to have right propagation properties. For +shared volumes, source mount point has to be shared. And for slave volumes, +source mount has to be either shared or slave. + +Use `df <source-dir>` to figure out the source mount and then use +`findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation +properties of source mount. If `findmnt` utility is not available, then one +can look at mount entry for source mount point in `/proc/self/mountinfo`. Look +at `optional fields` and see if any propagation properties are specified. +`shared:X` means mount is `shared`, `master:X` means mount is `slave` and if +nothing is there that means mount is `private`. + +To change propagation properties of a mount point use `mount` command. For +example, if one wants to bind mount source directory `/foo` one can do +`mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This +will convert /foo into a `shared` mount point. Alternatively one can directly +change propagation properties of source mount. Say `/` is source mount for +`/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount. + +**--volumes-from**[=*CONTAINER*[:*OPTIONS*]] + +Mount volumes from the specified container(s). +*OPTIONS* is a comma delimited list with the following available elements: + +* [rw|ro] +* z + +Mounts already mounted volumes from a source container onto another +container. You must supply the source's container-id or container-name. +To share a volume, use the --volumes-from option when running +the target container. You can share volumes even if the source container +is not running. + +By default, Podman mounts the volumes in the same mode (read-write or +read-only) as it is mounted in the source container. Optionally, you +can change this by suffixing the container-id with either the `ro` or +`rw` keyword. + +Labeling systems like SELinux require that proper labels are placed on volume +content mounted into a container. Without a label, the security system might +prevent the processes running inside the container from using the content. By +default, Podman does not change the labels set by the OS. + +To change a label in the container context, you can add `z` to the volume mount. +This suffix tells Podman to relabel file objects on the shared volumes. The `z` +option tells Podman that two containers share the volume content. As a result, +podman labels the content with a shared content label. Shared volume labels allow +all containers to read/write content. + +If the location of the volume from the source container overlaps with +data residing on a target container, then the volume hides +that data on the target. + +**--workdir**, **-w**=*dir* + +Working directory inside the container + +The default working directory for running binaries within a container is the root directory (/). +The image developer can set a different default with the WORKDIR instruction. The operator +can override the working directory by using the **-w** option. + +## Exit Status + +The exit code from `podman run` gives information about why the container +failed to run or why it exited. When `podman run` exits with a non-zero code, +the exit codes follow the `chroot` standard, see below: + +**_125_** if the error is with Podman **_itself_** + + $ podman run --foo busybox; echo $? + Error: unknown flag: --foo + 125 + +**_126_** if the **_contained command_** cannot be invoked + + $ podman run busybox /etc; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error + 126 + +**_127_** if the **_contained command_** cannot be found + + $ podman run busybox foo; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error + 127 + +**_Exit code_** of **_contained command_** otherwise + + $ podman run busybox /bin/sh -c 'exit 3' + 3 + +## EXAMPLES + +### Running container in read-only mode + +During container image development, containers often need to write to the image +content. Installing packages into /usr, for example. In production, +applications seldom need to write to the image. Container applications write +to volumes if they need to write to file systems at all. Applications can be +made more secure by running them in read-only mode using the --read-only switch. +This protects the containers image from modification. Read only containers may +still need to write temporary data. The best way to handle this is to mount +tmpfs directories on /run and /tmp. + +``` +$ podman run --read-only -i -t fedora /bin/bash +``` + +``` +$ podman run --read-only --read-only-tmpfs=false --tmpfs /run -i -t fedora /bin/bash +``` + +### Exposing log messages from the container to the host's log + +If you want messages that are logged in your container to show up in the host's +syslog/journal then you should bind mount the /dev/log directory as follows. + +``` +$ podman run -v /dev/log:/dev/log -i -t fedora /bin/bash +``` + +From inside the container you can test this by sending a message to the log. + +``` +(bash)# logger "Hello from my container" +``` + +Then exit and check the journal. + +``` +(bash)# exit + +$ journalctl -b | grep Hello +``` + +This should list the message sent to logger. + +### Attaching to one or more from STDIN, STDOUT, STDERR + +If you do not specify -a then Podman will attach everything (stdin,stdout,stderr). +You can specify to which of the three standard streams (stdin, stdout, stderr) +you'd like to connect instead, as in: + +``` +$ podman run -a stdin -a stdout -i -t fedora /bin/bash +``` + +## Sharing IPC between containers + +Using shm_server.c available here: https://www.cs.cf.ac.uk/Dave/C/node27.html + +Testing `--ipc=host` mode: + +Host shows a shared memory segment with 7 pids attached, happens to be from httpd: + +``` +$ sudo ipcs -m + +------ Shared Memory Segments -------- +key shmid owner perms bytes nattch status +0x01128e25 0 root 600 1000 7 +``` + +Now run a regular container, and it correctly does NOT see the shared memory segment from the host: + +``` +$ podman run -it shm ipcs -m + +------ Shared Memory Segments -------- +key shmid owner perms bytes nattch status +``` + +Run a container with the new `--ipc=host` option, and it now sees the shared memory segment from the host httpd: + +``` +$ podman run -it --ipc=host shm ipcs -m + +------ Shared Memory Segments -------- +key shmid owner perms bytes nattch status +0x01128e25 0 root 600 1000 7 +``` +Testing `--ipc=container:CONTAINERID` mode: + +Start a container with a program to create a shared memory segment: +``` +$ podman run -it shm bash +$ sudo shm/shm_server & +$ sudo ipcs -m + +------ Shared Memory Segments -------- +key shmid owner perms bytes nattch status +0x0000162e 0 root 666 27 1 +``` +Create a 2nd container correctly shows no shared memory segment from 1st container: +``` +$ podman run shm ipcs -m + +------ Shared Memory Segments -------- +key shmid owner perms bytes nattch status +``` + +Create a 3rd container using the new --ipc=container:CONTAINERID option, now it shows the shared memory segment from the first: + +``` +$ podman run -it --ipc=container:ed735b2264ac shm ipcs -m +$ sudo ipcs -m + +------ Shared Memory Segments -------- +key shmid owner perms bytes nattch status +0x0000162e 0 root 666 27 1 +``` + +### Mapping Ports for External Usage + +The exposed port of an application can be mapped to a host port using the **-p** +flag. For example, an httpd port 80 can be mapped to the host port 8080 using the +following: + +``` +$ podman run -p 8080:80 -d -i -t fedora/httpd +``` + +### Mounting External Volumes + +To mount a host directory as a container volume, specify the absolute path to +the directory and the absolute path for the container directory separated by a +colon. If the source is a named volume maintained by Podman, it's recommended to +use it's name rather than the path to the volume. Otherwise the volume will be +considered as an orphan and wiped if you execute `podman volume prune`: + +``` +$ podman run -v /var/db:/data1 -i -t fedora bash + +$ podman run -v data:/data2 -i -t fedora bash +``` + +Using --mount flags, To mount a host directory as a container folder, specify +the absolute path to the directory or the volume name, and the absolute path +within the container directory: + +```` +$ podman run --mount type=bind,src=/var/db,target=/data1 busybox sh + +$ podman run --mount type=bind,src=volume-name,target=/data1 busybox sh +```` + +When using SELinux, be aware that the host has no knowledge of container SELinux +policy. Therefore, in the above example, if SELinux policy is enforced, the +`/var/db` directory is not writable to the container. A "Permission Denied" +message will occur and an avc: message in the host's syslog. + +To work around this, at time of writing this man page, the following command +needs to be run in order for the proper SELinux policy type label to be attached +to the host directory: + +``` +$ chcon -Rt svirt_sandbox_file_t /var/db +``` + +Now, writing to the /data1 volume in the container will be allowed and the +changes will also be reflected on the host in /var/db. + +### Using alternative security labeling + +You can override the default labeling scheme for each container by specifying +the `--security-opt` flag. For example, you can specify the MCS/MLS level, a +requirement for MLS systems. Specifying the level in the following command +allows you to share the same content between containers. + +``` +podman run --security-opt label=level:s0:c100,c200 -i -t fedora bash +``` + +An MLS example might be: + +``` +$ podman run --security-opt label=level:TopSecret -i -t rhel7 bash +``` + +To disable the security labeling for this container versus running with the +`--permissive` flag, use the following command: + +``` +$ podman run --security-opt label=disable -i -t fedora bash +``` + +If you want a tighter security policy on the processes within a container, +you can specify an alternate type for the container. You could run a container +that is only allowed to listen on Apache ports by executing the following +command: + +``` +$ podman run --security-opt label=type:svirt_apache_t -i -t centos bash +``` + +Note: + +You would have to write policy defining a `svirt_apache_t` type. + +### Setting device weight + +If you want to set `/dev/sda` device weight to `200`, you can specify the device +weight by `--blkio-weight-device` flag. Use the following command: + +``` +$ podman run -it --blkio-weight-device "/dev/sda:200" ubuntu +``` + +### Setting Namespaced Kernel Parameters (Sysctls) + +The `--sysctl` sets namespaced kernel parameters (sysctls) in the +container. For example, to turn on IP forwarding in the containers +network namespace, run this command: + +``` +$ podman run --sysctl net.ipv4.ip_forward=1 someimage +``` + +Note: + +Not all sysctls are namespaced. Podman does not support changing sysctls +inside of a container that also modify the host system. As the kernel +evolves we expect to see more sysctls become namespaced. + +See the definition of the `--sysctl` option above for the current list of +supported sysctls. + +### Set UID/GID mapping in a new user namespace + +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 +``` + +### Configuring Storage Options from the command line + +Podman allows for the configuration of storage by changing the values +in the /etc/container/storage.conf or by using global options. This +shows how to setup and use fuse-overlayfs for a one time run of busybox +using global options. + +podman --log-level=debug --storage-driver overlay --storage-opt "overlay.mount_program=/usr/bin/fuse-overlayfs" run busybox /bin/sh + +### 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. + +## ENVIRONMENT + +Environment variables within containers can be set using multiple different options: This section describes the precedence. + +Precedence Order: + + **--env-host** : Host environment of the process executing Podman is added. + + Container image : Any environment variables specified in the container image. + + **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry. + + **--env** : Any environment variables specified will override previous settings. + +Run containers and set the environment ending with a __*__ and a ***** + +``` +$ export ENV1=a +$ $ podman run --env ENV* alpine printenv ENV1 +a + +$ podman run --env ENV*****=b alpine printenv ENV***** +b +``` + +## FILES + +**/etc/subuid** +**/etc/subgid** + +## SEE ALSO +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> + +October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman <dwalsh@redhat.com> + +November 2015, updated by Sally O'Malley <somalley@redhat.com> + +July 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> + +June 2014, updated by Sven Dowideit <SvenDowideit@home.org.au> + +April 2014, Originally compiled by William Henry <whenry@redhat.com> based on docker.com source material and internal work. diff --git a/docs/source/man/podman-save.1.md b/docs/source/man/podman-save.1.md new file mode 100644 index 000000000..b2b0995d3 --- /dev/null +++ b/docs/source/man/podman-save.1.md @@ -0,0 +1,99 @@ +% podman-save(1) + +## NAME +podman\-save - Save an image to a container archive + +## SYNOPSIS +**podman save** [*options*] *name*[:*tag*] + +**podman image save** [*options*] *name*[:*tag*] + +## DESCRIPTION +**podman save** saves an image to either **docker-archive**, **oci-archive**, **oci-dir** (directory with oci manifest type), or **docker-dir** (directory with v2s2 manifest type) on the local machine, +default is **docker-archive**. **podman save** writes to STDOUT by default and can be redirected to a +file using the **output** flag. The **quiet** flag suppresses the output when set. +Note: `:` is a restricted character and cannot be part of the file name. + +**podman [GLOBAL OPTIONS]** + +**podman save [GLOBAL OPTIONS]** + +**podman save [OPTIONS] NAME[:TAG]** + +## OPTIONS + +**--compress** + +Compress tarball image layers when pushing to a directory using the 'dir' transport. (default is same compression type, compressed or uncompressed, as source) +Note: This flag can only be set when using the **dir** transport i.e --format=oci-dir or --format-docker-dir + +**--output**, **-o**=*file* + +Write to a file, default is STDOUT + +**--format**=*format* + +Save image to **oci-archive, oci-dir** (directory with oci manifest type), or **docker-dir** (directory with v2s2 manifest type) +``` +--format oci-archive +--format oci-dir +--format docker-dir +``` + +**--quiet**, **-q** + +Suppress the output + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman save --quiet -o alpine.tar alpine:2.6 +``` + +``` +$ podman save > alpine-all.tar alpine +``` + +``` +$ podman save -o oci-alpine.tar --format oci-archive alpine +``` + +``` +$ podman save --compress --format oci-dir -o alp-dir alpine +Getting image source signatures +Copying blob sha256:2fdfe1cd78c20d05774f0919be19bc1a3e4729bce219968e4188e7e0f1af679d + 1.97 MB / 1.97 MB [========================================================] 0s +Copying config sha256:501d1a8f0487e93128df34ea349795bc324d5e0c0d5112e08386a9dfaff620be + 584 B / 584 B [============================================================] 0s +Writing manifest to image destination +Storing signatures +``` + +``` +$ podman save --format docker-dir -o ubuntu-dir ubuntu +Getting image source signatures +Copying blob sha256:660c48dd555dcbfdfe19c80a30f557ac57a15f595250e67bfad1e5663c1725bb + 45.55 MB / 45.55 MB [======================================================] 8s +Copying blob sha256:4c7380416e7816a5ab1f840482c9c3ca8de58c6f3ee7f95e55ad299abbfe599f + 846 B / 846 B [============================================================] 0s +Copying blob sha256:421e436b5f80d876128b74139531693be9b4e59e4f1081c9a3c379c95094e375 + 620 B / 620 B [============================================================] 0s +Copying blob sha256:e4ce6c3651b3a090bb43688f512f687ea6e3e533132bcbc4a83fb97e7046cea3 + 849 B / 849 B [============================================================] 0s +Copying blob sha256:be588e74bd348ce48bb7161350f4b9d783c331f37a853a80b0b4abc0a33c569e + 169 B / 169 B [============================================================] 0s +Copying config sha256:20c44cd7596ff4807aef84273c99588d22749e2a7e15a7545ac96347baa65eda + 3.53 KB / 3.53 KB [========================================================] 0s +Writing manifest to image destination +Storing signatures +``` + +## SEE ALSO +podman(1), podman-load(1) + +## HISTORY +July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-search.1.md b/docs/source/man/podman-search.1.md new file mode 100644 index 000000000..31de6f839 --- /dev/null +++ b/docs/source/man/podman-search.1.md @@ -0,0 +1,155 @@ +% podman-search(1) + +## NAME +podman\-search - Search a registry for an image + +## SYNOPSIS +**podman search** [*options*] *term* + +## DESCRIPTION +**podman search** searches a registry or a list of registries for a matching image. +The user can specify which registry to search by prefixing the registry in the search term +(example **registry.fedoraproject.org/fedora**), default is the registries in the +**registries.search** table in the config file - **/etc/containers/registries.conf**. +The default number of results is 25. The number of results can be limited using the **--limit** flag. +If more than one registry is being searched, the limit will be applied to each registry. The output can be filtered +using the **--filter** flag. To get all available images in a registry without a specific +search term, the user can just enter the registry name with a trailing "/" (example **registry.fedoraproject.org/**). +Note, searching without a search term will only work for registries that implement the v2 API. + +**podman [GLOBAL OPTIONS]** + +**podman search [GLOBAL OPTIONS]** + +**podman search [OPTIONS] TERM** + +## OPTIONS + +**--authfile**=*path* + +Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json (Not available for remote commands) + +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` + +**--filter**, **-f**=*filter* + +Filter output based on conditions provided (default []) + +Supported filters are: + +* stars (int - number of stars the image has) +* is-automated (boolean - true | false) - is the image automated or not +* is-official (boolean - true | false) - is the image official or not + +**--format**=*format* + +Change the output format to a Go template + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | ---------------------------- | +| .Index | Registry | +| .Name | Image name | +| .Descriptions | Image description | +| .Stars | Star count of image | +| .Official | "[OK]" if image is official | +| .Automated | "[OK]" if image is automated | + +**--limit**=*limit* + +Limit the number of results +Note: The results from each registry will be limited to this value. +Example if limit is 10 and two registries are being searched, the total +number of results will be 20, 10 from each (if there are at least 10 matches in each). +The order of the search results is the order in which the API endpoint returns the results. + +**--no-trunc** + +Do not truncate the output + +**--tls-verify**=*true|false* + +Require HTTPS and verify certificates when contacting registries (default: true). If explicitly set to true, +then TLS verification will be used. If set to false, then TLS verification will not be used if needed. If not specified, +default registries will be searched through (in /etc/containers/registries.conf), and TLS will be skipped if a default +registry is listed in the insecure registries. (Not available for remote commands) + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman search --limit 3 rhel +INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED +docker.io docker.io/richxsl/rhel7 RHEL 7 image with minimal installation 9 +docker.io docker.io/bluedata/rhel7 RHEL-7.x base container images 1 +docker.io docker.io/gidikern/rhel-oracle-jre RHEL7 with jre8u60 5 [OK] +redhat.com redhat.com/rhel This platform image provides a minimal runti... 0 +redhat.com redhat.com/rhel6 This platform image provides a minimal runti... 0 +redhat.com redhat.com/rhel6.5 This platform image provides a minimal runti... 0 +``` + +``` +$ podman search alpine +INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED +docker.io docker.io/library/alpine A minimal Docker image based on Alpine Linux... 3009 [OK] +docker.io docker.io/mhart/alpine-node Minimal Node.js built on Alpine Linux 332 +docker.io docker.io/anapsix/alpine-java Oracle Java 8 (and 7) with GLIBC 2.23 over A... 272 [OK] +docker.io docker.io/tenstartups/alpine Alpine linux base docker image with useful p... 5 [OK] +``` + +``` +$ podman search registry.fedoraproject.org/fedora +INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED +fedoraproject.org fedoraproject.org/fedora 0 +fedoraproject.org fedoraproject.org/fedora-minimal 0 +``` + +``` +$ podman search --filter=is-official alpine +INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED +docker.io docker.io/library/alpine A minimal Docker image based on Alpine Linux... 3009 [OK] +``` + +``` +$ podman search --format "table {{.Index}} {{.Name}}" registry.fedoraproject.org/fedora +INDEX NAME +fedoraproject.org fedoraproject.org/fedora +fedoraproject.org fedoraproject.org/fedora-minimal +``` + +``` +$ podman search registry.fedoraproject.org/ +INDEX NAME DESCRIPTION STARS OFFICIAL AUTOMATED +fedoraproject.org registry.fedoraproject.org/f25/cockpit 0 +fedoraproject.org registry.fedoraproject.org/f25/container-engine 0 +fedoraproject.org registry.fedoraproject.org/f25/docker 0 +fedoraproject.org registry.fedoraproject.org/f25/etcd 0 +fedoraproject.org registry.fedoraproject.org/f25/flannel 0 +fedoraproject.org registry.fedoraproject.org/f25/httpd 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-apiserver 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-controller-manager 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-kubelet 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-master 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-node 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-proxy 0 +fedoraproject.org registry.fedoraproject.org/f25/kubernetes-scheduler 0 +fedoraproject.org registry.fedoraproject.org/f25/mariadb 0 +``` +Note: This works only with registries that implement the v2 API. If tried with a v1 registry an error will be returned. + +## FILES + +**registries.conf** (`/etc/containers/registries.conf`) + + registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. + +## SEE ALSO +podman(1), containers-registries.conf(5) + +## HISTORY +January 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-start.1.md b/docs/source/man/podman-start.1.md new file mode 100644 index 000000000..4c81d17bd --- /dev/null +++ b/docs/source/man/podman-start.1.md @@ -0,0 +1,59 @@ +% podman-start(1) + +## NAME +podman\-start - Start one or more containers + +## SYNOPSIS +**podman start** [*options*] *container* ... + +**podman container start** [*options*] *container* ... + +## DESCRIPTION +Start one or more containers. You may use container IDs or names as input. The *attach* and *interactive* +options cannot be used to override the *--tty* and *--interactive* options from when the container +was created. If you attempt to start a running container with the *--attach* option, podman will simply +attach to the container. + +## OPTIONS + +**--attach**, **-a** + +Attach container's STDOUT and STDERR. The default is false. This option cannot be used when +starting multiple containers. + +**--detach-keys**=*sequence* + +Override the key sequence for detaching a container. Format is a single character `[a-Z]` or +a comma separated sequence of `ctrl-<value>`, where `<value>` is one of: +`a-z`, `@`, `^`, `[`, `\\`, `]`, `^` or `_`. + +**--interactive**, **-i** + +Attach container's STDIN. The default is false. + +**--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 latest option is not supported on the remote client. + +**--sig-proxy**=*true|false* + +Proxy received signals to the process (non-TTY mode only). SIGCHLD, SIGSTOP, and SIGKILL are not proxied. The default is *true* when attaching, *false* otherwise. + +## EXAMPLE + +podman start mywebserver + +podman start 860a4b231279 5421ab43b45 + +podman start --interactive --attach 860a4b231279 + +podman start -i -l + +## SEE ALSO +podman(1), podman-create(1) + +## HISTORY +November 2018, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-stats.1.md b/docs/source/man/podman-stats.1.md new file mode 100644 index 000000000..741873c3f --- /dev/null +++ b/docs/source/man/podman-stats.1.md @@ -0,0 +1,103 @@ +% podman-stats(1) + +## NAME +podman\-stats - Display a live stream of one or more container's resource usage statistics + +## SYNOPSIS +**podman stats** [*options*] [*container*] + +**podman container stats** [*options*] [*container*] + +## DESCRIPTION +Display a live stream of one or more containers' resource usage statistics + +Note: Podman stats will not work in rootless environments that use CGroups V1. +Podman stats relies on CGroup information for statistics, and CGroup v1 is not +supported for rootless use cases. + +Note: Rootless environments that use CGroups V2 are not able to report statistics +about their networking usage. + +## OPTIONS + +**--all**, **-a** + +Show all containers. Only running containers are shown by default + +**--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 latest option is not supported on the remote client. + +**--no-reset** + +Do not clear the terminal/screen in between reporting intervals + +**--no-stream** + +Disable streaming stats and only pull the first result, default setting is false + +**--format**=*template* + +Pretty-print container statistics to JSON or using a Go template + +Valid placeholders for the Go template are listed below: + +| **Placeholder** | **Description** | +| --------------- | --------------- | +| .Pod | Pod ID | +| .ID | Container ID | +| .Name | Container Name | +| .CPU | CPU percentage | +| .MemUsage | Memory usage | +| .Mem | Memory percentage | +| .NetIO | Network IO | +| .BlockIO | Block IO | +| .PIDS | Number of PIDs | + +When using a GO template, you may precede the format with `table` to print headers. + +## EXAMPLE + +``` +# podman stats -a --no-stream +ID NAME CPU % MEM USAGE / LIMIT MEM % NET IO BLOCK IO PIDS +a9f807ffaacd frosty_hodgkin -- 3.092MB / 16.7GB 0.02% -- / -- -- / -- 2 +3b33001239ee sleepy_stallman -- -- / -- -- -- / -- -- / -- -- +``` + +``` +# podman stats --no-stream a9f80 +ID NAME CPU % MEM USAGE / LIMIT MEM % NET IO BLOCK IO PIDS +a9f807ffaacd frosty_hodgkin -- 3.092MB / 16.7GB 0.02% -- / -- -- / -- 2 +``` + +``` +# podman stats --no-stream --format=json a9f80 +[ + { + "id": "a9f807ffaacd", + "name": "frosty_hodgkin", + "cpu_percent": "--", + "mem_usage": "3.092MB / 16.7GB", + "mem_percent": "0.02%", + "netio": "-- / --", + "blocki": "-- / --", + "pids": "2" + } +] +``` + +``` +# podman stats --no-stream --format "table {{.ID}} {{.Name}} {{.MemUsage}}" 6eae +ID NAME MEM USAGE / LIMIT +6eae9e25a564 clever_bassi 3.031MB / 16.7GB +``` + +## SEE ALSO +podman(1) + +## HISTORY +July 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/man/podman-stop.1.md b/docs/source/man/podman-stop.1.md new file mode 100644 index 000000000..b5ea670b0 --- /dev/null +++ b/docs/source/man/podman-stop.1.md @@ -0,0 +1,53 @@ +% podman-stop(1) + +## NAME +podman\-stop - Stop one or more running containers + +## SYNOPSIS +**podman stop** [*options*] *container* ... + +**podman container stop** [*options*] *container* ... + +## DESCRIPTION +Stops one or more containers. You may use container IDs or names as input. The **--timeout** switch +allows you to specify the number of seconds to wait before forcibly stopping the container after the stop command +is issued to the container. The default is 10 seconds. By default, containers are stopped with SIGTERM +and then SIGKILL after the timeout. The SIGTERM default can be overridden by the image used to create the +container and also via command line when creating the container. + +## OPTIONS + +**--all**, **-a** + +Stop all running containers. This does not include paused containers. + +**--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 latest option is not supported on the remote client. + +**--timeout**, **--time**, **t**=*time* + +Timeout to wait before forcibly stopping the container + +## EXAMPLE + +podman stop mywebserver + +podman stop 860a4b235279 + +podman stop mywebserver 860a4b235279 + +podman stop --timeout 2 860a4b235279 + +podman stop -a + +podman stop --latest + +## SEE ALSO +podman(1), podman-rm(1) + +## HISTORY +September 2018, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-system-df.1.md b/docs/source/man/podman-system-df.1.md new file mode 100644 index 000000000..d0b1755ee --- /dev/null +++ b/docs/source/man/podman-system-df.1.md @@ -0,0 +1,57 @@ +% podman-system-df(1) + +## NAME +podman\-system\-df - Show podman disk usage + +## SYNOPSIS +**podman system df** [*options*] + +## DESCRIPTION +Show podman disk usage + +## OPTIONS +**--format=***format* + +Pretty-print images using a Go template + +**-v**, **--verbose**[=*true|false*] +Show detailed information on space usage + +## EXAMPLE + +$ podman system df +TYPE TOTAL ACTIVE SIZE RECLAIMABLE +Images 6 2 281MB 168MB (59%) +Containers 3 1 0B 0B (0%) +Local Volumes 1 1 22B 0B (0%) + +$ podman system df -v +Images space usage: + +REPOSITORY TAG IMAGE ID CREATED SIZE SHARED SIZE UNIQUE SIZE CONTAINERS +docker.io/library/alpine latest 5cb3aa00f899 2 weeks ago 5.79MB 0B 5.79MB 5 + +Containers space usage: + +CONTAINER ID IMAGE COMMAND LOCAL VOLUMES SIZE CREATED STATUS NAMES +073f7e62812d 5cb3 sleep 100 1 0B 20 hours ago exited zen_joliot +3f19f5bba242 5cb3 sleep 100 0 5.52kB 22 hours ago exited pedantic_archimedes +8cd89bf645cc 5cb3 ls foodir 0 58B 21 hours ago configured agitated_hamilton +a1d948a4b61d 5cb3 ls foodir 0 12B 21 hours ago exited laughing_wing +eafe3e3c5bb3 5cb3 sleep 10000 0 72B 21 hours ago exited priceless_liskov + +Local Volumes space usage: + +VOLUME NAME LINKS SIZE +data 1 0B + +$ podman system df --format "{{.Type}}\t{{.Total}}" +Images 1 +Containers 5 +Local Volumes 1 + +## SEE ALSO +podman-system(1) + +## HISTORY +March 2019, Originally compiled by Qi Wang (qiwan at redhat dot com) diff --git a/docs/source/man/podman-system-migrate.1.md b/docs/source/man/podman-system-migrate.1.md new file mode 100644 index 000000000..d5e3bcb95 --- /dev/null +++ b/docs/source/man/podman-system-migrate.1.md @@ -0,0 +1,42 @@ +% podman-system-migrate(1) + +## NAME +podman\-system\-migrate - Migrate existing containers to a new podman version + +## SYNOPSIS +** podman system migrate** + +## DESCRIPTION +** podman system migrate** migrates containers to the latest podman version. + +**podman system migrate** takes care of migrating existing containers to the latest version of podman if any change is necessary. + +"Rootless Podman uses a pause process to keep the unprivileged +namespaces alive. This prevents any change to the `/etc/subuid` and +`/etc/subgid` files from being propagated to the rootless containers +while the pause process is running. + +For these changes to be propagated, it is necessary to first stop all +running containers associated with the user and to also stop the pause +process and delete its pid file. Instead of doing it manually, `podman +system migrate` can be used to stop both the running containers and the +pause process. The `/etc/subuid` and `/etc/subgid` files can then be +edited or changed with usermod to recreate the user namespace with the +newly configured mappings. + +## OPTIONS + +**--new-runtime**=*runtime* + +Set a new OCI runtime for all containers. +This can be used after a system upgrade which changes the default OCI runtime to move all containers to the new runtime. +There are no guarantees that the containers will continue to work under the new runtime, as some runtimes support differing options and configurations. + +## SYNOPSIS +**podman system migrate** + +## SEE ALSO +`podman(1)`, `libpod.conf(5)`, `usermod(8)` + +## HISTORY +April 2019, Originally compiled by Giuseppe Scrivano (gscrivan at redhat dot com) diff --git a/docs/source/man/podman-system-prune.1.md b/docs/source/man/podman-system-prune.1.md new file mode 100644 index 000000000..e6297dc0b --- /dev/null +++ b/docs/source/man/podman-system-prune.1.md @@ -0,0 +1,37 @@ +% podman-system-prune(1) + +## NAME +podman\-system\-prune - Remove all unused container, image and volume data + +## SYNOPSIS +**podman system prune** [*options*] + +## DESCRIPTION +**podman system prune** removes all unused containers (both dangling and unreferenced), pods and optionally, volumes from local storage. + +With the `all` option, you can delete all unused images. Unused images are dangling images as well as any image that does not have any containers based on it. + +By default, volumes are not removed to prevent important data from being deleted if there is currently no container using the volume. Use the --volumes flag when running the command to prune volumes as well. + +## OPTIONS +**--all**, **-a** + +Remove all unused images not just dangling ones. + +**--force**, **-f** + +Do not prompt for confirmation + +**--help**, **-h** + +Print usage statement + +**--volumes** + +Prune volumes not used by at least one container + +## SEE ALSO +podman(1), podman-image-prune(1), podman-container-prune(1), podman-pod-prune(1), podman-volume-prune(1) + +## HISTORY +February 2019, Originally compiled by Dan Walsh (dwalsh at redhat dot com) diff --git a/docs/source/man/podman-system-renumber.1.md b/docs/source/man/podman-system-renumber.1.md new file mode 100644 index 000000000..071eefe29 --- /dev/null +++ b/docs/source/man/podman-system-renumber.1.md @@ -0,0 +1,26 @@ +% podman-system-renumber(1) + +## NAME +podman\-system\-renumber - Migrate lock numbers to handle a change in maximum number of locks + +## SYNOPSIS +**podman system renumber** + +## DESCRIPTION +**podman system renumber** renumbers locks used by containers and pods. + +Each Podman container and pod is allocated a lock at creation time, up to a maximum number controlled by the **num_locks** parameter in **libpod.conf**. + +When all available locks are exhausted, no further containers and pods can be created until some existing containers and pods are removed. This can be avoided by increasing the number of locks available via modifying **libpod.conf** and subsequently running **podman system renumber** to prepare the new locks (and reallocate lock numbers to fit the new struct). + +**podman system renumber** must be called after any changes to **num_locks** - failure to do so will result in errors starting Podman as the number of locks available conflicts with the configured number of locks. + +**podman system renumber** can also be used to migrate 1.0 and earlier versions of Podman, which used a different locking scheme, to the new locking model. It is not strictly required to do this, but it is highly recommended to do so as deadlocks can occur otherwise. + +If possible, avoid calling **podman system renumber** while there are other Podman processes running. + +## SEE ALSO +`podman(1)`, `libpod.conf(5)` + +## HISTORY +February 2019, Originally compiled by Matt Heon (mheon at redhat dot com) diff --git a/docs/source/man/podman-system.1.md b/docs/source/man/podman-system.1.md new file mode 100644 index 000000000..bbd541066 --- /dev/null +++ b/docs/source/man/podman-system.1.md @@ -0,0 +1,23 @@ +% podman-system(1) + +## NAME +podman\-system - Manage podman + +## SYNOPSIS +**podman system** *subcommand* + +## DESCRIPTION +The system command allows you to manage the podman systems + +## COMMANDS + +| Command | Man Page | Description | +| ------- | --------------------------------------------------- | ---------------------------------------------------------------------------- | +| df | [podman-system-df(1)](podman-system-df.1.md) | Show podman disk usage. | +| info | [podman-system-info(1)](podman-info.1.md) | Displays Podman related system information. | +| prune | [podman-system-prune(1)](podman-system-prune.1.md) | Remove all unused container, image and volume data | +| renumber | [podman-system-renumber(1)](podman-system-renumber.1.md)| Migrate lock numbers to handle a change in maximum number of locks. | +| migrate | [podman-system-migrate(1)](podman-system-migrate.1.md)| Migrate existing containers to a new podman version. | + +## SEE ALSO +podman(1) diff --git a/docs/source/man/podman-tag.1.md b/docs/source/man/podman-tag.1.md new file mode 100644 index 000000000..291d95228 --- /dev/null +++ b/docs/source/man/podman-tag.1.md @@ -0,0 +1,35 @@ +% podman-tag(1) + +## NAME +podman\-tag - Add an additional name to a local image + +## SYNOPSIS +**podman tag** *image*[:*tag*] *target-name*[:*tag*] [*options*] + +**podman image tag** *image*[:*tag*] *target-name*[:*tag*] [*options*] + +## DESCRIPTION +Assigns a new alias to an image. An alias refers to the entire image name, including the optional +*tag* after the `:`. If you do not provide *tag*, podman will default to `latest` for both +the *image* and the *target-name*. + +## OPTIONS + +**--help**, **-h** + +Print usage statement + +## EXAMPLES + +``` +$ podman tag 0e3bbc2 fedora:latest + +$ podman tag httpd myregistryhost:5000/fedora/httpd:v2 +``` + + +## SEE ALSO +podman(1) + +## HISTORY +July 2017, Originally compiled by Ryan Cole <rycole@redhat.com> diff --git a/docs/source/man/podman-top.1.md b/docs/source/man/podman-top.1.md new file mode 100644 index 000000000..1410aa651 --- /dev/null +++ b/docs/source/man/podman-top.1.md @@ -0,0 +1,108 @@ +% podman-top(1) + +## NAME +podman\-top - Display the running processes of a container + +## SYNOPSIS +**podman top** [*options*] *container* [*format-descriptors*] + +**podman container top** [*options*] *container* [*format-descriptors*] + +## DESCRIPTION +Display the running processes of the container. The *format-descriptors* are ps (1) compatible AIX format descriptors but extended to print additional information, such as the seccomp mode or the effective capabilities of a given process. The descriptors can either be passed as separated arguments or as a single comma-separated argument. Note that you can also specify options and or flags of ps(1); in this case, Podman will fallback to executing ps with the specified arguments and flags in the container. + +## OPTIONS + +**--help**, **-h** + +Print usage statement + +**--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 latest option is not supported on the remote client. + +## FORMAT DESCRIPTORS + +The following descriptors are supported in addition to the AIX format descriptors mentioned in ps (1): + +**args, capbnd, capeff, capinh, capprm, comm, etime, group, hgroup, hpid, huser, label, nice, pcpu, pgid, pid, ppid, rgroup, ruser, seccomp, state, time, tty, user, vsz** + +**capbnd** + + Set of bounding capabilities. See capabilities (7) for more information. + +**capeff** + + Set of effective capabilities. See capabilities (7) for more information. + +**capinh** + + Set of inheritable capabilities. See capabilities (7) for more information. + +**capprm** + + Set of permitted capabilities. See capabilities (7) for more information. + +**hgroup** + + The corresponding effective group of a container process on the host. + +**hpid** + + The corresponding host PID of a container process. + +**huser** + + The corresponding effective user of a container process on the host. + +**label** + + Current security attributes of the process. + +**seccomp** + + Seccomp mode of the process (i.e., disabled, strict or filter). See seccomp (2) for more information. + +**state** + + Process state codes (e.g, **R** for *running*, **S** for *sleeping*). See proc(5) for more information. + +## EXAMPLES + +By default, `podman-top` prints data similar to `ps -ef`: + +``` +$ podman top f5a62a71b07 +USER PID PPID %CPU ELAPSED TTY TIME COMMAND +root 1 0 0.000 20.386825206s pts/0 0s sh +root 7 1 0.000 16.386882887s pts/0 0s sleep +root 8 1 0.000 11.386886562s pts/0 0s vi +``` + +The output can be controlled by specifying format descriptors as arguments after the container: + +``` +$ podman top -l pid seccomp args %C +PID SECCOMP COMMAND %CPU +1 filter sh 0.000 +8 filter vi /etc/ 0.000 +``` + +Podman will fallback to executing ps(1) in the container if an unknown descriptor is specified. + +``` +$ podman top -l -- aux +USER PID PPID %CPU ELAPSED TTY TIME COMMAND +root 1 0 0.000 1h2m12.497061672s ? 0s sleep 100000 +``` + +## SEE ALSO +podman(1), ps(1), seccomp(2), proc(5), capabilities(7) + +## HISTORY +July 2018, Introduce format descriptors by Valentin Rothberg <vrothberg@suse.com> + +December 2017, Originally compiled by Brent Baude <bbaude@redhat.com> diff --git a/docs/source/man/podman-umount.1.md b/docs/source/man/podman-umount.1.md new file mode 100644 index 000000000..100c47b32 --- /dev/null +++ b/docs/source/man/podman-umount.1.md @@ -0,0 +1,55 @@ +% podman-umount(1) + +## NAME +podman\-umount - Unmount a working container's root filesystem + +## SYNOPSIS +**podman umount** *container* [...] + +**podman container umount** *container* [...] + +**podman container unmount** *container* [...] + +**podman unmount** *container* [...] + +## DESCRIPTION +Unmounts the specified containers' root file system, if no other processes +are using it. + +Container storage increments a mount counter each time a container is mounted. +When a container is unmounted, the mount counter is decremented and the +container's root filesystem is physically unmounted only when the mount +counter reaches zero indicating no other processes are using the mount. +An unmount can be forced with the --force flag. + +## OPTIONS +**--all**, **-a** + +All of the currently mounted containers will be unmounted. + +**--force**, **-f** + +Force the unmounting of specified containers' root file system, even if other +processes have mounted it. + +Note: This could cause other processes that are using the file system to fail, +as the mount point could be removed without their knowledge. + +**--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 latest option is not supported on the remote client. + +## EXAMPLE + +podman umount containerID + +podman umount containerID1 containerID2 containerID3 + +podman umount --all + +## SEE ALSO +podman(1), podman-mount(1) diff --git a/docs/source/man/podman-unpause.1.md b/docs/source/man/podman-unpause.1.md new file mode 100644 index 000000000..f5538d6d5 --- /dev/null +++ b/docs/source/man/podman-unpause.1.md @@ -0,0 +1,42 @@ +% podman-unpause(1) + +## NAME +podman\-unpause - Unpause one or more containers + +## SYNOPSIS +**podman unpause** [*options*]|[*container* ...] + +**podman container 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) + +## HISTORY +September 2017, Originally compiled by Dan Walsh <dwalsh@redhat.com> diff --git a/docs/source/man/podman-unshare.1.md b/docs/source/man/podman-unshare.1.md new file mode 100644 index 000000000..9052b97ab --- /dev/null +++ b/docs/source/man/podman-unshare.1.md @@ -0,0 +1,42 @@ +% podman-unshare(1) + +## NAME +podman\-unshare - Run a command inside of a modified user namespace + +## SYNOPSIS +**podman unshare** [*options*] [*--*] [*command*] + +## DESCRIPTION +Launches a process (by default, *$SHELL*) in a new user namespace. The user +namespace is configured so that the invoking user's UID and primary GID appear +to be UID 0 and GID 0, respectively. Any ranges which match that user and +group in /etc/subuid and /etc/subgid are also mapped in as themselves with the +help of the *newuidmap(1)* and *newgidmap(1)* helpers. + +podman unshare is useful for troubleshooting unprivileged operations and for +manually clearing storage and other data related to images and containers. + +It is also useful if you want to use the `podman mount` command. If an unprivileged users wants to mount and work with a container, then they need to execute +podman unshare. Executing `podman mount` fails for unprivileged users unless the user is running inside a `podman unshare` session. + +The unshare session defines two environment variables: + +**CONTAINERS_GRAPHROOT** the path to the persistent containers data. +**CONTAINERS_RUNROOT** the path to the volatile containers data. + +## EXAMPLE + +``` +$ podman unshare id +uid=0(root) gid=0(root) groups=0(root),65534(nobody) + +$ podman unshare cat /proc/self/uid_map /proc/self/gid_map + 0 1000 1 + 1 10000 65536 + 0 1000 1 + 1 10000 65536 +``` + + +## SEE ALSO +podman(1), podman-mount(1), namespaces(7), newuidmap(1), newgidmap(1), user\_namespaces(7) diff --git a/docs/source/man/podman-varlink.1.md b/docs/source/man/podman-varlink.1.md new file mode 100644 index 000000000..0d2ab1668 --- /dev/null +++ b/docs/source/man/podman-varlink.1.md @@ -0,0 +1,63 @@ +% podman-varlink(1) + +## NAME +podman\-varlink - Runs the varlink backend interface + +## SYNOPSIS +**podman varlink** [*options*] *uri* + +## DESCRIPTION +Starts the varlink service listening on *uri* that allows varlink clients to interact with podman. If no *uri* is provided, a default +URI will be used depending on the user calling the varlink service. The default for the root user is `unix:/run/podman/io.podman`. Regular +users will have a default *uri* of `$XDG_RUNTIME_DIR/podman/io.podman`. For example, `unix:/run/user/1000/podman/io.podman` +The varlink service should generally be done with systemd. See _Configuration_ below. + + +## OPTIONS + +**--help**, **-h** + + Print usage statement + +**--timeout**, **-t** + +The time until the varlink session expires in _milliseconds_. The default is 1 +second. A value of `0` means no timeout and the session will not expire. + +## EXAMPLES + +Run the podman varlink service accepting all default options. + +``` +$ podman varlink +``` + + +Run the podman varlink service with an alternate URI and accept the default timeout. + +``` +$ podman varlink unix:/tmp/io.podman +``` + +Run the podman varlink service manually with a 5 second timeout. + +``` +$ podman varlink --timeout 5000 +``` + +## CONFIGURATION + +Users of the podman varlink service should enable the _io.podman.socket_ and _io.podman.service_. +This is the preferred method for running the varlink service. + +You can do this via systemctl. + +``` +$ systemctl enable --now io.podman.socket +``` + +## SEE ALSO +podman(1), systemctl(1) + +## HISTORY +April 2018, Originally compiled by Brent Baude<bbaude@redhat.com> diff --git a/docs/source/man/podman-version.1.md b/docs/source/man/podman-version.1.md new file mode 100644 index 000000000..4499f6338 --- /dev/null +++ b/docs/source/man/podman-version.1.md @@ -0,0 +1,46 @@ +% podman-version(1) + +## NAME +podman\-version - Display the Podman version information + +## SYNOPSIS +**podman version** [*options*] + +## DESCRIPTION +Shows the following information: Version, Go Version, Git Commit, Build Time, +OS, and Architecture. + +## OPTIONS + +**--help**, **-h** + +Print usage statement + +**--format**, **-f**=*format* + +Change output format to "json" or a Go template. + +## Example + +A sample output of the `version` command: +``` +$ podman version +Version: 0.11.1 +Go Version: go1.11 +Git Commit: "8967a1d691ed44896b81ad48c863033f23c65eb0-dirty" +Built: Thu Nov 8 22:35:40 2018 +OS/Arch: linux/amd64 +``` + +Filtering out only the version: +``` +$ podman version --format '{{.Version}}' +0.11.2 +``` + +## SEE ALSO +podman(1) + +## HISTORY +November 2018, Added --format flag by Tomas Tomecek <ttomecek@redhat.com> +July 2017, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-volume-create.1.md b/docs/source/man/podman-volume-create.1.md new file mode 100644 index 000000000..b354f396f --- /dev/null +++ b/docs/source/man/podman-volume-create.1.md @@ -0,0 +1,59 @@ +% podman-volume-create(1) + +## NAME +podman\-volume\-create - Create a new volume + +## SYNOPSIS +**podman volume create** [*options*] + +## DESCRIPTION + +Creates an empty volume and prepares it to be used by containers. The volume +can be created with a specific name, if a name is not given a random name is +generated. You can add metadata to the volume by using the **--label** flag and +driver options can be set using the **--opt** flag. + +## OPTIONS + +**--driver**=*driver* + +Specify the volume driver name (default local). + +**--help** + +Print usage statement + +**-l**, **-label**=*label* + +Set metadata for a volume (e.g., --label mykey=value). + +**-o**, **--opt**=*option* + +Set driver specific options. +For the default driver, `local`, this allows a volume to be configured to mount a filesystem on the host. +For the `local` driver the following options are supported: `type`, `device`, and `o`. +The `type` option sets the type of the filesystem to be mounted, and is equivalent to the `-t` flag to **mount(8)**. +The `device` option sets the device to be mounted, and is equivalent to the `device` argument to **mount(8)**. +The `o` option sets options for the mount, and is equivalent to the `-o` flag to **mount(8)** with two exceptions. +The `o` option supports `uid` and `gid` options to set the UID and GID of the created volume that are not normally supported by **mount(8)**. +Using volume options with the `local` driver requires root privileges. + +## EXAMPLES + +``` +$ podman volume create myvol + +$ podman volume create + +$ podman volume create --label foo=bar myvol + +# podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=nodev,noexec myvol + +# podman volume create --opt device=tmpfs --opt type=tmpfs --opt o=uid=1000,gid=1000 testvol +``` + +## SEE ALSO +podman-volume(1), mount(8) + +## HISTORY +November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-volume-inspect.1.md b/docs/source/man/podman-volume-inspect.1.md new file mode 100644 index 000000000..ac5b6c977 --- /dev/null +++ b/docs/source/man/podman-volume-inspect.1.md @@ -0,0 +1,46 @@ +% podman-volume-inspect(1) + +## NAME +podman\-volume\-inspect - Get detailed information on one or more volumes + +## SYNOPSIS +**podman volume inspect** [*options*] *volume* [...] + +## DESCRIPTION + +Display detailed information on one or more volumes. The output can be formatted using +the **--format** flag and a Go template. To get detailed information about all the +existing volumes, use the **--all** flag. +Volumes can be queried individually by providing their full name or a unique partial name. + + +## OPTIONS + +**-a**, **--all** + +Inspect all volumes. + +**--format**=*format* + +Format volume output using Go template + +**--help** + +Print usage statement + + +## EXAMPLES + +``` +$ podman volume inspect myvol + +$ podman volume inspect --all + +$ podman volume inspect --format "{{.Driver}} {{.Scope}}" myvol +``` + +## SEE ALSO +podman-volume(1) + +## HISTORY +November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-volume-ls.1.md b/docs/source/man/podman-volume-ls.1.md new file mode 100644 index 000000000..d431c7c6e --- /dev/null +++ b/docs/source/man/podman-volume-ls.1.md @@ -0,0 +1,49 @@ +% podman-volume-ls(1) + +## NAME +podman\-volume\-ls - List all the available volumes + +## SYNOPSIS +**podman volume ls** [*options*] + +## DESCRIPTION + +Lists all the volumes that exist. The output can be filtered using the **--filter** +flag and can be formatted to either JSON or a Go template using the **--format** +flag. Use the **--quiet** flag to print only the volume names. + +## OPTIONS + +**--filter**=*filter* + +Filter volume output. + +**--format**=*format* + +Format volume output using Go template. + +**--help** + +Print usage statement. + +**-q**, **--quiet** + +Print volume output in quiet mode. Only print the volume names. + +## EXAMPLES + +``` +$ podman volume ls + +$ podman volume ls --format json + +$ podman volume ls --format "{{.Driver}} {{.Scope}}" + +$ podman volume ls --filter name=foo,label=blue +``` + +## SEE ALSO +podman-volume(1) + +## HISTORY +November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-volume-prune.1.md b/docs/source/man/podman-volume-prune.1.md new file mode 100644 index 000000000..25ea701a3 --- /dev/null +++ b/docs/source/man/podman-volume-prune.1.md @@ -0,0 +1,38 @@ +% podman-volume-prune(1) + +## NAME +podman\-volume\-prune - Remove all unused volumes + +## SYNOPSIS +**podman volume prune** [*options*] + +## DESCRIPTION + +Removes all unused volumes. You will be prompted to confirm the removal of all the +unused volumes. To bypass the confirmation, use the **--force** flag. + + +## OPTIONS + +**-f**, **--force** + +Do not prompt for confirmation. + +**--help** + +Print usage statement + + +## EXAMPLES + +``` +$ podman volume prune + +$ podman volume prune --force +``` + +## SEE ALSO +podman-volume(1) + +## HISTORY +November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-volume-rm.1.md b/docs/source/man/podman-volume-rm.1.md new file mode 100644 index 000000000..9a2fe8c99 --- /dev/null +++ b/docs/source/man/podman-volume-rm.1.md @@ -0,0 +1,46 @@ +% podman-volume-rm(1) + +## NAME +podman\-volume\-rm - Remove one or more volumes + +## SYNOPSIS +**podman volume rm** [*options*] *volume* [...] + +## DESCRIPTION + +Removes one or more volumes. Only volumes that are not being used will be removed. +If a volume is being used by a container, an error will be returned unless the **--force** +flag is being used. To remove all volumes, use the **--all** flag. +Volumes can be removed individually by providing their full name or a unique partial name. + +## OPTIONS + +**-a**, **--all** + +Remove all volumes. + +**-f**, **--force** + +Remove a volume by force. +If it is being used by containers, the containers will be removed first. + +**--help** + +Print usage statement + + +## EXAMPLES + +``` +$ podman volume rm myvol1 myvol2 + +$ podman volume rm --all + +$ podman volume rm --force myvol +``` + +## SEE ALSO +podman-volume(1) + +## HISTORY +November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-volume.1.md b/docs/source/man/podman-volume.1.md new file mode 100644 index 000000000..288e57b82 --- /dev/null +++ b/docs/source/man/podman-volume.1.md @@ -0,0 +1,26 @@ +% podman-volume(1) + +## NAME +podman\-volume - Simple management tool for volumes + +## SYNOPSIS +**podman volume** *subcommand* + +## DESCRIPTION +podman volume is a set of subcommands that manage volumes. + +## SUBCOMMANDS + +| Command | Man Page | Description | +| ------- | ------------------------------------------------------ | ------------------------------------------------------------------------------ | +| create | [podman-volume-create(1)](podman-volume-create.1.md) | Create a new volume. | +| inspect | [podman-volume-inspect(1)](podman-volume-inspect.1.md) | Get detailed information on one or more volumes. | +| ls | [podman-volume-ls(1)](podman-volume-ls.1.md) | List all the available volumes. | +| prune | [podman-volume-prune(1)](podman-volume-prune.1.md) | Remove all unused volumes. | +| rm | [podman-volume-rm(1)](podman-volume-rm.1.md) | Remove one or more volumes. | + +## SEE ALSO +podman(1) + +## HISTORY +November 2018, Originally compiled by Urvashi Mohnani <umohnani@redhat.com> diff --git a/docs/source/man/podman-wait.1.md b/docs/source/man/podman-wait.1.md new file mode 100644 index 000000000..ce1c70a5f --- /dev/null +++ b/docs/source/man/podman-wait.1.md @@ -0,0 +1,48 @@ +% podman-wait(1) + +## NAME +podman\-wait - Wait on one or more containers to stop and print their exit codes + +## SYNOPSIS +**podman wait** [*options*] *container* + +**podman container wait** [*options*] *container* + +## DESCRIPTION +Waits on one or more containers to stop. The container can be referred to by its +name or ID. In the case of multiple containers, podman will wait on each consecutively. +After the container stops, the container's return code is printed. + +## OPTIONS + +**--help**, **-h** + + Print usage statement + +**--interval**, **-i**=*microseconds* + Microseconds to wait before polling for completion + +**--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 latest option is not supported on the remote client. + +## EXAMPLES + +``` +$ podman wait mywebserver + +$ podman wait --latest + +$ podman wait 860a4b23 + +$ podman wait mywebserver myftpserver +``` + +## SEE ALSO +podman(1) + +## HISTORY +September 2017, Originally compiled by Brent Baude<bbaude@redhat.com> diff --git a/docs/source/man/podman.1.md b/docs/source/man/podman.1.md new file mode 100644 index 000000000..f6fa1a457 --- /dev/null +++ b/docs/source/man/podman.1.md @@ -0,0 +1,260 @@ +% podman(1) + +## NAME +podman - Simple management tool for pods, containers and images + +## SYNOPSIS +**podman** [*options*] *command* + +## DESCRIPTION +Podman (Pod Manager) is a fully featured container engine that is a simple daemonless tool. +Podman provides a Docker-CLI comparable command line that eases the transition from other +container engines and allows the management of pods, containers and images. Simply put: `alias docker=podman`. +Most Podman commands can be run as a regular user, without requiring additional +privileges. + +Podman uses Buildah(1) internally to create container images. Both tools share image +(not container) storage, hence each can use or manipulate images (but not containers) +created by the other. + +**podman [GLOBAL OPTIONS]** + +## GLOBAL OPTIONS + +**--help**, **-h** + +Print usage statement + +**--cgroup-manager**=*manager* + +CGroup manager to use for container cgroups. Supported values are cgroupfs or systemd. Default is systemd unless overridden in the libpod.conf file. + +Note: Setting this flag can cause certain commands to break when called on containers previously created by the other CGroup manager type. +Note: CGroup manager is not supported in rootless mode when using CGroups Version V1. + +**--cpu-profile**=*path* + +Path to where the cpu performance results should be written + +**--events-backend**=*type* + +Backend to use for storing events. Allowed values are **file**, **journald**, and **none**. + +**--hooks-dir**=*path* + +Each `*.json` file in the path configures a hook for Podman containers. For more details on the syntax of the JSON files and the semantics of hook injection, see `oci-hooks(5)`. Podman and libpod currently support both the 1.0.0 and 0.1.0 hook schemas, although the 0.1.0 schema is deprecated. + +This option may be set multiple times; paths from later options have higher precedence (`oci-hooks(5)` discusses directory precedence). + +For the annotation conditions, libpod uses any annotations set in the generated OCI configuration. + +For the bind-mount conditions, only mounts explicitly requested by the caller via `--volume` are considered. Bind mounts that libpod inserts by default (e.g. `/dev/shm`) are not considered. + +If `--hooks-dir` is unset for root callers, Podman and libpod will currently default to `/usr/share/containers/oci/hooks.d` and `/etc/containers/oci/hooks.d` in order of increasing precedence. Using these defaults is deprecated, and callers should migrate to explicitly setting `--hooks-dir`. + +Podman and libpod currently support an additional `precreate` state which is called before the runtime's `create` operation. Unlike the other stages, which receive the container state on their standard input, `precreate` hooks receive the proposed runtime configuration on their standard input. They may alter that configuration as they see fit, and write the altered form to their standard output. + +**WARNING**: the `precreate` hook lets you do powerful things, such as adding additional mounts to the runtime configuration. That power also makes it easy to break things. Before reporting libpod errors, try running your container with `precreate` hooks disabled to see if the problem is due to one of your hooks. + +**--log-level**=*level* + +Log messages above specified level: debug, info, warn, error (default), fatal or panic + +**--namespace**=*namespace* + +Set libpod namespace. Namespaces are used to separate groups of containers and pods in libpod's state. +When namespace is set, created containers and pods will join the given namespace, and only containers and pods in the given namespace will be visible to Podman. + +**--root=***value* + +Storage root dir in which data, including images, is stored (default: "/var/lib/containers/storage" for UID 0, "$HOME/.local/share/containers/storage" for other users). +Default root dir is configured in /etc/containers/storage.conf. + +**--runroot**=*value* + +Storage state directory where all state information is stored (default: "/var/run/containers/storage" for UID 0, "/var/run/user/$UID/run" for other users). +Default state dir is configured in /etc/containers/storage.conf. + +**--runtime**=*value* + +Name of the OCI runtime as specified in libpod.conf or absolute path to the OCI compatible binary used to run containers. + +**--network-cmd-path**=*path* +Path to the command binary to use for setting up a network. It is currently only used for setting up a slirp4netns network. If "" is used then the binary is looked up using the $PATH environment variable. + +**--storage-driver**=*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 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. + +**--storage-opt**=*value* + +Storage driver option, Default storage driver options are configured in /etc/containers/storage.conf (`$HOME/.config/containers/storage.conf` in rootless mode). The `STORAGE_OPTS` environment variable overrides the default. The --storage-opt specified options overrides all. + +**--syslog** + +output logging information to syslog as well as the console + +On remote clients, logging is directed to the file ~/.config/containers/podman.log + +**--version**, **-v** + +Print the version + +## Exit Status + +The exit code from `podman` gives information about why the container +failed to run or why it exited. When `podman` commands exit with a non-zero code, +the exit codes follow the `chroot` standard, see below: + +**_125_** if the error is with podman **_itself_** + + $ podman run --foo busybox; echo $? + Error: unknown flag: --foo + 125 + +**_126_** if executing a **_contained command_** and the **_command_** cannot be invoked + + $ podman run busybox /etc; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"/etc\": permission denied": OCI runtime error + 126 + +**_127_** if executing a **_contained command_** and the **_command_** cannot be found + $ podman run busybox foo; echo $? + Error: container_linux.go:346: starting container process caused "exec: \"foo\": executable file not found in $PATH": OCI runtime error + 127 + +**_Exit code_** of **_contained command_** otherwise + + $ podman run busybox /bin/sh -c 'exit 3' + # 3 + + +## COMMANDS + +| Command | Description | +| ------------------------------------------------ | --------------------------------------------------------------------------- | +| [podman-attach(1)](podman-attach.1.md) | Attach to a running container. | +| [podman-build(1)](podman-build.1.md) | Build a container image using a Containerfile. | +| [podman-commit(1)](podman-commit.1.md) | Create new image based on the changed container. | +| [podman-container(1)](podman-container.1.md) | Manage containers. | +| [podman-cp(1)](podman-cp.1.md) | Copy files/folders between a container and the local filesystem. | +| [podman-create(1)](podman-create.1.md) | Create a new container. | +| [podman-diff(1)](podman-diff.1.md) | Inspect changes on a container or image's filesystem. | +| [podman-events(1)](podman-events.1.md) | Monitor Podman events | +| [podman-exec(1)](podman-exec.1.md) | Execute a command in a running container. | +| [podman-export(1)](podman-export.1.md) | Export a container's filesystem contents as a tar archive. | +| [podman-generate(1)](podman-generate.1.md) | Generate structured data based for a containers and pods. | +| [podman-healthcheck(1)](podman-healthcheck.1.md) | Manage healthchecks for containers | +| [podman-history(1)](podman-history.1.md) | Show the history of an image. | +| [podman-image(1)](podman-image.1.md) | Manage images. | +| [podman-images(1)](podman-images.1.md) | List images in local storage. | +| [podman-import(1)](podman-import.1.md) | Import a tarball and save it as a filesystem image. | +| [podman-info(1)](podman-info.1.md) | Displays Podman related system information. | +| [podman-init(1)](podman-init.1.md) | Initialize one or more containers | +| [podman-inspect(1)](podman-inspect.1.md) | Display a container or image's configuration. | +| [podman-kill(1)](podman-kill.1.md) | Kill the main process in one or more containers. | +| [podman-load(1)](podman-load.1.md) | Load an image from a container image archive into container storage. | +| [podman-login(1)](podman-login.1.md) | Login to a container registry. | +| [podman-logout(1)](podman-logout.1.md) | Logout of a container registry. | +| [podman-logs(1)](podman-logs.1.md) | Display the logs of one or more containers. | +| [podman-mount(1)](podman-mount.1.md) | Mount a working container's root filesystem. | +| [podman-network(1)](podman-network.1.md) | Manage Podman CNI networks. | +| [podman-pause(1)](podman-pause.1.md) | Pause one or more containers. | +| [podman-play(1)](podman-play.1.md) | Play pods and containers based on a structured input file. | +| [podman-pod(1)](podman-pod.1.md) | Management tool for groups of containers, called pods. | +| [podman-port(1)](podman-port.1.md) | List port mappings for a container. | +| [podman-ps(1)](podman-ps.1.md) | Prints out information about containers. | +| [podman-pull(1)](podman-pull.1.md) | Pull an image from a registry. | +| [podman-push(1)](podman-push.1.md) | Push an image from local storage to elsewhere. | +| [podman-restart(1)](podman-restart.1.md) | Restart one or more containers. | +| [podman-rm(1)](podman-rm.1.md) | Remove one or more containers. | +| [podman-rmi(1)](podman-rmi.1.md) | Removes one or more locally stored images. | +| [podman-run(1)](podman-run.1.md) | Run a command in a new container. | +| [podman-save(1)](podman-save.1.md) | Save an image to a container archive. | +| [podman-search(1)](podman-search.1.md) | Search a registry for an image. | +| [podman-start(1)](podman-start.1.md) | Start one or more containers. | +| [podman-stats(1)](podman-stats.1.md) | Display a live stream of one or more container's resource usage statistics. | +| [podman-stop(1)](podman-stop.1.md) | Stop one or more running containers. | +| [podman-system(1)](podman-system.1.md) | Manage podman. | +| [podman-tag(1)](podman-tag.1.md) | Add an additional name to a local image. | +| [podman-top(1)](podman-top.1.md) | Display the running processes of a container. | +| [podman-umount(1)](podman-umount.1.md) | Unmount a working container's root filesystem. | +| [podman-unpause(1)](podman-unpause.1.md) | Unpause one or more containers. | +| [podman-unshare(1)](podman-unshare.1.md) | Run a command inside of a modified user namespace. | +| [podman-varlink(1)](podman-varlink.1.md) | Runs the varlink backend interface. | +| [podman-version(1)](podman-version.1.md) | Display the Podman version information. | +| [podman-volume(1)](podman-volume.1.md) | Simple management tool for volumes. | +| [podman-wait(1)](podman-wait.1.md) | Wait on one or more containers to stop and print their exit codes. | + +## FILES + +**libpod.conf** (`/usr/share/containers/libpod.conf`) + + libpod.conf is the configuration file for all tools using libpod to manage containers, when run as root. Administrators can override the defaults file by creating `/etc/containers/libpod.conf`. When Podman runs in rootless mode, the file `$HOME/.config/containers/libpod.conf` is created and replaces some fields in the system configuration file. + + Podman uses builtin defaults if no libpod.conf file is found. + +**mounts.conf** (`/usr/share/containers/mounts.conf`) + + The mounts.conf file specifies volume mount directories that are automatically mounted inside containers when executing the `podman run` or `podman start` commands. Administrators can override the defaults file by creating `/etc/containers/mounts.conf`. + +When Podman runs in rootless mode, the file `$HOME/.config/containers/mounts.conf` will override the default if it exists. Please refer to containers-mounts.conf(5) for further details. + +**policy.json** (`/etc/containers/policy.json`) + + Signature verification policy files are used to specify policy, e.g. trusted keys, applicable when deciding whether to accept an image, or individual signatures of that image, as valid. + +**registries.conf** (`/etc/containers/registries.conf`) + + registries.conf is the configuration file which specifies which container registries should be consulted when completing image names which do not include a registry or domain portion. + + Non root users of Podman can create the `$HOME/.config/containers/registries.conf` file to be used instead of the system defaults. + +**storage.conf** (`/etc/containers/storage.conf`) + + storage.conf is the storage configuration file for all tools using containers/storage + + The storage configuration file specifies all of the available container storage options for tools using shared container storage. + + When Podman runs in rootless mode, the file `$HOME/.config/containers/storage.conf` is used instead of the system defaults. + +## Rootless mode +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. + +It is required to have multiple uids/gids set for an user. Be sure the user is present in the files `/etc/subuid` and `/etc/subgid`. + +If you have a recent version of usermod, you can execute the following +commands to add the ranges to the files + + $ sudo usermod --add-subuids 10000-75535 USERNAME + $ sudo usermod --add-subgids 10000-75535 USERNAME + +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 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. + +### **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 and to enable it by adding `mount_program = "/usr/bin/fuse-overlayfs"` under `[storage.options]` in the `~/.config/containers/storage.conf` file. + +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 `~/.config/containers/storage.conf` to have the `graphroot` option point to a directory stored on local (Non NFS) storage. + +For more information, please refer to the [Podman Troubleshooting Page](https://github.com/containers/libpod/blob/master/troubleshooting.md). + +## SEE ALSO +`containers-mounts.conf(5)`, `containers-registries.conf(5)`, `containers-storage.conf(5)`, `buildah(1)`, `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> |