github.com/containers/podman/v2@v2.2.2-0.20210501105131-c1e07d070c4c/docs/source/markdown/podman-create.1.md (about)

     1  % podman-create(1)
     2  
     3  ## NAME
     4  podman\-create - Create a new container
     5  
     6  ## SYNOPSIS
     7  **podman create** [*options*] *image* [*command* [*arg* ...]]
     8  
     9  **podman container create** [*options*] *image* [*command* [*arg* ...]]
    10  
    11  ## DESCRIPTION
    12  
    13  Creates a writable container layer over the specified image and prepares it for
    14  running the specified command. The container ID is then printed to STDOUT. This
    15  is similar to **podman run -d** except the container is never started. You can
    16  then use the **podman start** *container* command to start the container at
    17  any point.
    18  
    19  The initial status of the container created with **podman create** is 'created'.
    20  
    21  Default settings for flags are defined in `containers.conf`. Most settings for
    22  remote connections use the server's containers.conf, except when documented in
    23  man pages.
    24  
    25  ## IMAGE
    26  
    27    The image is specified using transport:path format. If no transport is specified, the `docker` (container registry)
    28  transport will be used by default. For remote Podman, `docker` is the only allowed transport.
    29  
    30    **dir:**_path_
    31    An existing local directory _path_ storing the manifest, layer tarballs and signatures as individual files. This
    32  is a non-standardized format, primarily useful for debugging or noninvasive container inspection.
    33  
    34      $ podman save --format docker-dir fedora -o /tmp/fedora
    35      $ podman create dir:/tmp/fedora echo hello
    36  
    37    **docker://**_docker-reference_ (Default)
    38    An image reference stored in  a remote container image registry. Example: "quay.io/podman/stable:latest".
    39  The reference can include a path to a specific registry; if it does not, the
    40  registries listed in registries.conf will be queried to find a matching image.
    41  By default, credentials from `podman login` (stored at
    42  $XDG_RUNTIME_DIR/containers/auth.json by default) will be used to authenticate;
    43  otherwise it falls back to using credentials in $HOME/.docker/config.json.
    44  
    45      $ podman create registry.fedoraproject.org/fedora:latest echo hello
    46  
    47    **docker-archive:**_path_[**:**_docker-reference_]
    48  An image stored in the `docker save` formatted file. _docker-reference_ is only used when creating such a
    49  file, and it must not contain a digest.
    50  
    51      $ podman save --format docker-archive fedora -o /tmp/fedora
    52      $ podman create docker-archive:/tmp/fedora echo hello
    53  
    54    **docker-daemon:**_docker-reference_
    55    An image in _docker-reference_ format stored in the docker daemon internal storage. The _docker-reference_ can also be an image ID (docker-daemon:algo:digest).
    56  
    57      $ sudo docker pull fedora
    58      $ sudo podman create docker-daemon:docker.io/library/fedora echo hello
    59  
    60    **oci-archive:**_path_**:**_tag_
    61    An image in a directory compliant with the "Open Container Image Layout Specification" at the specified _path_
    62  and specified with a _tag_.
    63  
    64      $ podman save --format oci-archive fedora -o /tmp/fedora
    65      $ podman create oci-archive:/tmp/fedora echo hello
    66  
    67  ## OPTIONS
    68  #### **--add-host**=*host*
    69  
    70  Add a custom host-to-IP mapping (host:ip)
    71  
    72  Add a line to /etc/hosts. The format is hostname:ip. The **--add-host**
    73  option can be set multiple times.
    74  
    75  #### **--annotation**=*key=value*
    76  
    77  Add an annotation to the container. The format is key=value.
    78  The **--annotation** option can be set multiple times.
    79  
    80  #### **--attach**, **-a**=*location*
    81  
    82  Attach to STDIN, STDOUT or STDERR.
    83  
    84  In foreground mode (the default when **-d**
    85  is not specified), **podman run** can start the process in the container
    86  and attach the console to the process's standard input, output, and standard
    87  error. It can even pretend to be a TTY (this is what most commandline
    88  executables expect) and pass along signals. The **-a** option can be set for
    89  each of stdin, stdout, and stderr.
    90  
    91  #### **--authfile**=*path*
    92  
    93  Path of the authentication file. Default is ${XDG\_RUNTIME\_DIR}/containers/auth.json
    94  
    95  Note: You can also override the default path of the authentication file by setting the REGISTRY\_AUTH\_FILE
    96  environment variable. `export REGISTRY_AUTH_FILE=path`
    97  
    98  #### **--blkio-weight**=*weight*
    99  
   100  Block IO weight (relative weight) accepts a weight value between 10 and 1000.
   101  
   102  #### **--blkio-weight-device**=*weight*
   103  
   104  Block IO weight (relative device weight, format: `DEVICE_NAME:WEIGHT`).
   105  
   106  #### **--cap-add**=*capability*
   107  
   108  Add Linux capabilities
   109  
   110  #### **--cap-drop**=*capability*
   111  
   112  Drop Linux capabilities
   113  
   114  #### **--cgroupns**=*mode*
   115  
   116  Set the cgroup namespace mode for the container.
   117      **host**: use the host's cgroup namespace inside the container.
   118      **container:<NAME|ID>**: join the namespace of the specified container.
   119      **ns:<PATH>**: join the namespace at the specified path.
   120      **private**: create a new cgroup namespace.
   121  
   122  If the host uses cgroups v1, the default is set to **host**. On cgroups v2 the default is **private**.
   123  
   124  #### **--cgroups**=*mode*
   125  
   126  Determines whether the container will create CGroups.
   127  Valid values are *enabled*, *disabled*, *no-conmon*, *split*, which the default being *enabled*.
   128  
   129  The *enabled* option will create a new cgroup under the cgroup-parent.
   130  The *disabled* option will force the container to not create CGroups, and thus conflicts with CGroup options (**--cgroupns** and **--cgroup-parent**).
   131  The *no-conmon* option disables a new CGroup only for the conmon process.
   132  The *split* option splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. It is not possible to set *--cgroup-parent* with *split*.
   133  
   134  #### **--cgroup-parent**=*path*
   135  
   136  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.
   137  
   138  #### **--cgroup-conf**=*KEY=VALUE*
   139  
   140  When running on cgroup v2, specify the cgroup file to write to and its value. For example **--cgroup-conf=memory.high=1073741824** sets the memory.high limit to 1GB.
   141  
   142  #### **--cidfile**=*id*
   143  
   144  Write the container ID to the file
   145  
   146  #### **--conmon-pidfile**=*path*
   147  
   148  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.
   149  
   150  #### **--cpu-period**=*limit*
   151  
   152  Set the CPU period for the Completely Fair Scheduler (CFS), which is a
   153  duration in microseconds. Once the container's CPU quota is used up, it will
   154  not be scheduled to run until the current period ends. Defaults to 100000
   155  microseconds.
   156  
   157  On some systems, changing the CPU limits may not be allowed for non-root
   158  users. For more details, see
   159  https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
   160  
   161  #### **--cpu-quota**=*limit*
   162  
   163  Limit the CPU Completely Fair Scheduler (CFS) quota.
   164  
   165  Limit the container's CPU usage. By default, containers run with the full
   166  CPU resource. The limit is a number in microseconds. If you provide a number,
   167  the container will be allowed to use that much CPU time until the CPU period
   168  ends (controllable via **--cpu-period**).
   169  
   170  On some systems, changing the CPU limits may not be allowed for non-root
   171  users. For more details, see
   172  https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
   173  
   174  #### **--cpu-rt-period**=*microseconds*
   175  
   176  Limit the CPU real-time period in microseconds
   177  
   178  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.
   179  
   180  #### **--cpu-rt-runtime**=*microseconds*
   181  
   182  Limit the CPU real-time runtime in microseconds
   183  
   184  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:
   185  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.
   186  
   187  The sum of all runtimes across containers cannot exceed the amount allotted to the parent cgroup.
   188  
   189  #### **--cpu-shares**=*shares*
   190  
   191  CPU shares (relative weight)
   192  
   193  By default, all containers get the same proportion of CPU cycles. This proportion
   194  can be modified by changing the container's CPU share weighting relative
   195  to the weighting of all other running containers.
   196  
   197  To modify the proportion from the default of 1024, use the **--cpu-shares**
   198  flag to set the weighting to 2 or higher.
   199  
   200  The proportion will only apply when CPU-intensive processes are running.
   201  When tasks in one container are idle, other containers can use the
   202  left-over CPU time. The actual amount of CPU time will vary depending on
   203  the number of containers running on the system.
   204  
   205  For example, consider three containers, one has a cpu-share of 1024 and
   206  two others have a cpu-share setting of 512. When processes in all three
   207  containers attempt to use 100% of CPU, the first container would receive
   208  50% of the total CPU time. If you add a fourth container with a cpu-share
   209  of 1024, the first container only gets 33% of the CPU. The remaining containers
   210  receive 16.5%, 16.5% and 33% of the CPU.
   211  
   212  On a multi-core system, the shares of CPU time are distributed over all CPU
   213  cores. Even if a container is limited to less than 100% of CPU time, it can
   214  use 100% of each individual CPU core.
   215  
   216  For example, consider a system with more than three cores. If you start one
   217  container **{C0}** with **-c=512** running one process, and another container
   218  **{C1}** with **-c=1024** running two processes, this can result in the following
   219  division of CPU shares:
   220  
   221  PID    container	CPU	CPU share
   222  100    {C0}		0	100% of CPU0
   223  101    {C1}		1	100% of CPU1
   224  102    {C1}		2	100% of CPU2
   225  
   226  #### **--cpus**=*number*
   227  
   228  Number of CPUs. The default is *0.0* which means no limit. This is shorthand
   229  for **--cpu-period** and **--cpu-quota**, so you may only set either
   230  #### **--cpus** or **--cpu-period** and **--cpu-quota**.
   231  
   232  On some systems, changing the CPU limits may not be allowed for non-root
   233  users. For more details, see
   234  https://github.com/containers/podman/blob/master/troubleshooting.md#26-running-containers-with-cpu-limits-fails-with-a-permissions-error
   235  
   236  #### **--cpuset-cpus**=*cpus*
   237  
   238  CPUs in which to allow execution (0-3, 0,1)
   239  
   240  #### **--cpuset-mems**=*nodes*
   241  
   242  Memory nodes (MEMs) in which to allow execution (0-3, 0,1). Only effective on NUMA systems.
   243  
   244  If you have four memory nodes on your system (0-3), use `--cpuset-mems=0,1`
   245  then processes in your container will only use memory from the first
   246  two memory nodes.
   247  
   248  #### **--device**=_host-device_[**:**_container-device_][**:**_permissions_]
   249  
   250  Add a host device to the container. Optional *permissions* parameter
   251  can be used to specify device permissions, it is combination of
   252  **r** for read, **w** for write, and **m** for **mknod**(2).
   253  
   254  Example: **--device=/dev/sdc:/dev/xvdc:rwm**.
   255  
   256  Note: if _host_device_ is a symbolic link then it will be resolved first.
   257  The container will only store the major and minor numbers of the host device.
   258  
   259  Note: if the user only has access rights via a group, accessing the device
   260  from inside a rootless container will fail. The **crun**(1) runtime offers a
   261  workaround for this by adding the option **--annotation run.oci.keep_original_groups=1**.
   262  
   263  Podman may load kernel modules required for using the specified
   264  device. The devices that podman will load modules when necessary are:
   265  /dev/fuse.
   266  
   267  #### **--device-cgroup-rule**="type major:minor mode"
   268  
   269  Add a rule to the cgroup allowed devices list. The rule is expected to be in the format specified in the Linux kernel documentation (Documentation/cgroup-v1/devices.txt):
   270         - type: a (all), c (char), or b (block);
   271         - major and minor: either a number, or * for all;
   272         - mode: a composition of r (read), w (write), and m (mknod(2)).
   273  
   274  #### **--device-read-bps**=*path*
   275  
   276  Limit read rate (bytes per second) from a device (e.g. --device-read-bps=/dev/sda:1mb)
   277  
   278  #### **--device-read-iops**=*path*
   279  
   280  Limit read rate (IO per second) from a device (e.g. --device-read-iops=/dev/sda:1000)
   281  
   282  #### **--device-write-bps**=*path*
   283  
   284  Limit write rate (bytes per second) to a device (e.g. --device-write-bps=/dev/sda:1mb)
   285  
   286  #### **--device-write-iops**=*path*
   287  
   288  Limit write rate (IO per second) to a device (e.g. --device-write-iops=/dev/sda:1000)
   289  
   290  #### **--disable-content-trust**
   291  
   292  This is a Docker specific option to disable image verification to a Docker
   293  registry and is not supported by Podman. This flag is a NOOP and provided
   294  solely for scripting compatibility.
   295  
   296  #### **--dns**=*dns*
   297  
   298  Set custom DNS servers. Invalid if using **--dns** and **--network** that is set to 'none' or 'container:<name|id>'.
   299  
   300  This option can be used to override the DNS
   301  configuration passed to the container. Typically this is necessary when the
   302  host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this
   303  is the case the **--dns** flags is necessary for every run.
   304  
   305  The special value **none** can be specified to disable creation of **/etc/resolv.conf** in the container by Podman.
   306  The **/etc/resolv.conf** file in the image will be used without changes.
   307  
   308  #### **--dns-opt**=*option*
   309  
   310  Set custom DNS options. Invalid if using **--dns-opt** and **--network** that is set to 'none' or 'container:<name|id>'.
   311  
   312  #### **--dns-search**=*domain*
   313  
   314  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)
   315  
   316  #### **--entrypoint**=*"command"* | *'["command", "arg1", ...]'*
   317  
   318  Overwrite the default ENTRYPOINT of the image
   319  
   320  This option allows you to overwrite the default entrypoint of the image.
   321  The ENTRYPOINT of an image is similar to a COMMAND
   322  because it specifies what executable to run when the container starts, but it is
   323  (purposely) more difficult to override. The ENTRYPOINT gives a container its
   324  default nature or behavior, so that when you set an ENTRYPOINT you can run the
   325  container as if it were that binary, complete with default options, and you can
   326  pass in more options via the COMMAND. But, sometimes an operator may want to run
   327  something else inside the container, so you can override the default ENTRYPOINT
   328  at runtime by using a **--entrypoint** and a string to specify the new
   329  ENTRYPOINT.
   330  
   331  You need to specify multi option commands in the form of a json string.
   332  
   333  #### **--env**, **-e**=*env*
   334  
   335  Set environment variables
   336  
   337  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.
   338  
   339  See [**Environment**](#environment) note below for precedence and examples.
   340  
   341  #### **--env-host**=*true|false*
   342  
   343  Use host environment inside of the container. See **Environment** note below for precedence. (Not available for remote commands)
   344  
   345  #### **--env-file**=*file*
   346  
   347  Read in a line delimited file of environment variables. See **Environment** note below for precedence.
   348  
   349  #### **--expose**=*port*
   350  
   351  Expose a port, or a range of ports (e.g. --expose=3300-3310) to set up port redirection
   352  on the host system.
   353  
   354  #### **--gidmap**=*container_gid:host_gid:amount*
   355  
   356  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.
   357  
   358  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`
   359  
   360  #### **--group-add**=*group*
   361  
   362  Add additional groups to run as
   363  
   364  #### **--health-cmd**=*"command"* | *'["command", "arg1", ...]'*
   365  
   366  Set or alter a healthcheck command for a container. The command is a command to be executed inside your
   367  container that determines your container health. The command is required for other healthcheck options
   368  to be applied. A value of `none` disables existing healthchecks.
   369  
   370  Multiple options can be passed in the form of a JSON array; otherwise, the command will be interpreted
   371  as an argument to `/bin/sh -c`.
   372  
   373  #### **--health-interval**=*interval*
   374  
   375  Set an interval for the healthchecks (a value of `disable` results in no automatic timer setup) (default "30s")
   376  
   377  #### **--health-retries**=*retries*
   378  
   379  The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is `3`.
   380  
   381  #### **--health-start-period**=*period*
   382  
   383  The initialization time needed for a container to bootstrap. The value can be expressed in time format like
   384  `2m3s`. The default value is `0s`
   385  
   386  #### **--health-timeout**=*timeout*
   387  
   388  The maximum time allowed to complete the healthcheck before an interval is considered failed. Like start-period, the
   389  value can be expressed in a time format such as `1m22s`. The default value is `30s`.
   390  
   391  #### **--hostname**=*name*, **-h**
   392  
   393  Container host name
   394  
   395  Sets the container host name that is available inside the container. Can only be used with a private UTS namespace `--uts=private` (default). If `--pod` is specified and the pod shares the UTS namespace (default) the pod's hostname will be used.
   396  
   397  #### **--help**
   398  
   399  Print usage statement
   400  
   401  #### **--http-proxy**=*true|false*
   402  
   403  By default proxy environment variables are passed into the container if set
   404  for the Podman process. This can be disabled by setting the `--http-proxy`
   405  option to `false`. The environment variables passed in include `http_proxy`,
   406  `https_proxy`, `ftp_proxy`, `no_proxy`, and also the upper case versions of
   407  those. This option is only needed when the host system must use a proxy but
   408  the container should not use any proxy. Proxy environment variables specified
   409  for the container in any other way will override the values that would have
   410  been passed through from the host. (Other ways to specify the proxy for the
   411  container include passing the values with the `--env` flag, or hard coding the
   412  proxy environment at container build time.)  (Not available for remote commands)
   413  
   414  For example, to disable passing these environment variables from host to
   415  container:
   416  
   417  `--http-proxy=false`
   418  
   419  Defaults to `true`
   420  
   421  #### **--image-volume**, **builtin-volume**=*bind|tmpfs|ignore*
   422  
   423  Tells Podman how to handle the builtin image volumes. Default is **bind**.
   424  
   425  - **bind**: An anonymous named volume will be created and mounted into the container.
   426  - **tmpfs**: The volume is mounted onto the container as a tmpfs, which allows the users to create
   427  content that disappears when the container is stopped.
   428  - **ignore**: All volumes are just ignored and no action is taken.
   429  
   430  #### **--init**
   431  
   432  Run an init inside the container that forwards signals and reaps processes.
   433  
   434  #### **--init-path**=*path*
   435  
   436  Path to the container-init binary.
   437  
   438  #### **--interactive**, **-i**=*true|false*
   439  
   440  Keep STDIN open even if not attached. The default is *false*.
   441  
   442  #### **--ip6**=*ip*
   443  
   444  Not implemented
   445  
   446  #### **--ip**=*ip*
   447  
   448  Specify a static IP address for the container, for example **10.88.64.128**.
   449  This option can only be used if the container is joined to only a single network - i.e., `--network=_network-name_` is used at most once -
   450  and if the container is not joining another container's network namespace via `--network=container:_id_`.
   451  The address must be within the CNI network's IP address pool (default **10.88.0.0/16**).
   452  
   453  #### **--ipc**=*ipc*
   454  
   455  Default is to create a private IPC namespace (POSIX SysV IPC) for the container
   456  		'container:<name|id>': reuses another container shared memory, semaphores and message queues
   457  		'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.
   458  		'ns:<path>' path to an IPC namespace to join.
   459  
   460  #### **--kernel-memory**=*number[unit]*
   461  
   462  Kernel memory limit (format: `<number>[<unit>]`, where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
   463  
   464  Constrains the kernel memory available to a container. If a limit of 0
   465  is specified (not using `--kernel-memory`), the container's kernel memory
   466  is not limited. If you specify a limit, it may be rounded up to a multiple
   467  of the operating system's page size and the value can be very large,
   468  millions of trillions.
   469  
   470  #### **--label**, **-l**=*label*
   471  
   472  Add metadata to a container (e.g., --label com.example.key=value)
   473  
   474  #### **--label-file**=*file*
   475  
   476  Read in a line delimited file of labels
   477  
   478  #### **--link-local-ip**=*ip*
   479  
   480  Not implemented
   481  
   482  #### **--log-driver**="*k8s-file*"
   483  
   484  Logging driver for the container. Currently available options are *k8s-file*, *journald*, and *none*, with *json-file* aliased to *k8s-file* for scripting compatibility.
   485  
   486  #### **--log-opt**=*name*=*value*
   487  
   488  Set custom logging configuration. The following *name*s are supported:
   489  
   490  - **path**: specify a path to the log file
   491  (e.g. **--log-opt path=/var/log/container/mycontainer.json**);
   492  
   493  - **max-size**: specify a max size of the log file
   494  (e.g. **--log-opt max-size=10mb**);
   495  
   496  - **tag**: specify a custom log tag for the container
   497  (e.g. **--log-opt tag="{{.ImageName}}"**.
   498  
   499  It supports the same keys as **podman inspect --format**.
   500  
   501  This option is currently supported only by the **journald** log driver.
   502  
   503  `--log-opt tag="{{.ImageName}}"`
   504  
   505  It supports the same keys as `podman inspect --format`.
   506  
   507  It is currently supported only by the journald log driver.
   508  
   509  #### **--mac-address**=*address*
   510  
   511  Container MAC address (e.g. 92:d0:c6:0a:29:33)
   512  
   513  Remember that the MAC address in an Ethernet network must be unique.
   514  The IPv6 link-local address will be based on the device's MAC address
   515  according to RFC4862.
   516  
   517  #### **--memory**, **-m**=*limit*
   518  
   519  Memory limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
   520  
   521  Allows you to constrain the memory available to a container. If the host
   522  supports swap memory, then the **-m** memory setting can be larger than physical
   523  RAM. If a limit of 0 is specified (not using **-m**), the container's memory is
   524  not limited. The actual limit may be rounded up to a multiple of the operating
   525  system's page size (the value would be very large, that's millions of trillions).
   526  
   527  #### **--memory-reservation**=*limit*
   528  
   529  Memory soft limit (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
   530  
   531  After setting memory reservation, when the system detects memory contention
   532  or low memory, containers are forced to restrict their consumption to their
   533  reservation. So you should always set the value below **--memory**, otherwise the
   534  hard limit will take precedence. By default, memory reservation will be the same
   535  as memory limit.
   536  
   537  #### **--memory-swap**=*limit*
   538  
   539  A limit value equal to memory plus swap. Must be used with the  **-m**
   540  (**--memory**) flag. The swap `LIMIT` should always be larger than **-m**
   541  (**--memory**) value. By default, the swap `LIMIT` will be set to double
   542  the value of --memory.
   543  
   544  The format of `LIMIT` is `<number>[<unit>]`. Unit can be `b` (bytes),
   545  `k` (kilobytes), `m` (megabytes), or `g` (gigabytes). If you don't specify a
   546  unit, `b` is used. Set LIMIT to `-1` to enable unlimited swap.
   547  
   548  #### **--memory-swappiness**=*number*
   549  
   550  Tune a container's memory swappiness behavior. Accepts an integer between 0 and 100.
   551  
   552  #### **--mount**=*type=TYPE,TYPE-SPECIFIC-OPTION[,...]*
   553  
   554  Attach a filesystem mount to the container
   555  
   556  Current supported mount TYPEs are **bind**, **volume**, **image**, **tmpfs** and **devpts**. <sup>[[1]](#Footnote1)</sup>
   557  
   558         e.g.
   559  
   560         type=bind,source=/path/on/host,destination=/path/in/container
   561  
   562         type=bind,src=/path/on/host,dst=/path/in/container,relabel=shared
   563  
   564         type=volume,source=vol1,destination=/path/in/container,ro=true
   565  
   566         type=tmpfs,tmpfs-size=512M,destination=/path/in/container
   567  
   568         type=image,source=fedora,destination=/fedora-image,rw=true
   569  
   570         type=devpts,destination=/dev/pts
   571  
   572         Common Options:
   573  
   574  	      · src, source: mount source spec for bind and volume. Mandatory for bind.
   575  
   576  	      · dst, destination, target: mount destination spec.
   577  
   578         Options specific to volume:
   579  
   580  	      · ro, readonly: true or false (default).
   581  
   582         Options specific to image:
   583  
   584  	      · rw, readwrite: true or false (default).
   585  
   586         Options specific to bind:
   587  
   588  	      · ro, readonly: true or false (default).
   589  
   590  	      · bind-propagation: shared, slave, private, unbindable, rshared, rslave, runbindable, or rprivate(default). See also mount(2).
   591  
   592  	      . bind-nonrecursive: do not setup a recursive bind mount. By default it is recursive.
   593  
   594  	      . relabel: shared, private.
   595  
   596         Options specific to tmpfs:
   597  
   598  	      · ro, readonly: true or false (default).
   599  
   600  	      · tmpfs-size: Size of the tmpfs mount in bytes. Unlimited by default in Linux.
   601  
   602  	      · tmpfs-mode: File mode of the tmpfs in octal. (e.g. 700 or 0700.) Defaults to 1777 in Linux.
   603  
   604  	      · tmpcopyup: Enable copyup from the image directory at the same location to the tmpfs. Used by default.
   605  
   606  	      · notmpcopyup: Disable copying files from the image to the tmpfs.
   607  
   608  
   609  #### **--name**=*name*
   610  
   611  Assign a name to the container
   612  
   613  The operator can identify a container in three ways:
   614  UUID long identifier (“f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778”)
   615  UUID short identifier (“f78375b1c487”)
   616  Name (“jonah”)
   617  
   618  podman generates a UUID for each container, and if a name is not assigned
   619  to the container with **--name** then it will generate a random
   620  string name. The name is useful any place you need to identify a container.
   621  This works for both background and foreground containers.
   622  
   623  #### **--network**=*mode*, **--net**
   624  
   625  Set the network mode for the container. Invalid if using **--dns**, **--dns-opt**, or **--dns-search** with **--network** that is set to **none** or **container:**_id_. If used together with **--pod**, the container will not join the pod's network namespace.
   626  
   627  Valid _mode_ values are:
   628  
   629  - **bridge**: create a network stack on the default bridge;
   630  - **none**: no networking;
   631  - **container:**_id_: reuse another container's network stack;
   632  - **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;
   633  - _network-id_: connect to a user-defined network, multiple networks should be comma separated;
   634  - **ns:**_path_: path to a network namespace to join;
   635  - **private**: create a new namespace for the container (default)
   636  - **slirp4netns[:OPTIONS,...]**: use **slirp4netns**(1) to create a user network stack. This is the default for rootless containers. It is possible to specify these additional options:
   637    - **allow_host_loopback=true|false**: Allow the slirp4netns to reach the host loopback IP (`10.0.2.2`). Default is false.
   638    - **cidr=CIDR**: Specify ip range to use for this network. (Default is `10.0.2.0/24`).
   639    - **enable_ipv6=true|false**: Enable IPv6. Default is false. (Required for `outbound_addr6`).
   640    - **outbound_addr=INTERFACE**: Specify the outbound interface slirp should bind to (ipv4 traffic only).
   641    - **outbound_addr=IPv4**: Specify the outbound ipv4 address slirp should bind to.
   642    - **outbound_addr6=INTERFACE**: Specify the outbound interface slirp should bind to (ipv6 traffic only).
   643    - **outbound_addr6=IPv6**: Specify the outbound ipv6 address slirp should bind to.
   644    - **port_handler=rootlesskit**: Use rootlesskit for port forwarding. Default.
   645    - **port_handler=slirp4netns**: Use the slirp4netns port forwarding.
   646  
   647  #### **--network-alias**=*alias*
   648  
   649  Add network-scoped alias for the container
   650  
   651  #### **--no-healthcheck**=*true|false*
   652  
   653  Disable any defined healthchecks for container.
   654  
   655  #### **--no-hosts**=*true|false*
   656  
   657  Do not create /etc/hosts for the container.
   658  By default, Podman will manage /etc/hosts, adding the container's own IP address and any hosts from **--add-host**.
   659  #### **--no-hosts** disables this, and the image's **/etc/host** will be preserved unmodified.
   660  This option conflicts with **--add-host**.
   661  
   662  #### **--oom-kill-disable**=*true|false*
   663  
   664  Whether to disable OOM Killer for the container or not.
   665  
   666  #### **--oom-score-adj**=*num*
   667  
   668  Tune the host's OOM preferences for containers (accepts -1000 to 1000)
   669  
   670  #### **--override-arch**=*ARCH*
   671  Override the architecture, defaults to hosts, of the image to be pulled. For example, `arm`.
   672  
   673  #### **--override-os**=*OS*
   674  Override the OS, defaults to hosts, of the image to be pulled. For example, `windows`.
   675  
   676  #### **--override-variant**=*VARIANT*
   677  Use _VARIANT_ instead of the default architecture variant of the container image. Some images can use multiple variants of the arm architectures, such as arm/v5 and arm/v7.
   678  
   679  #### **--pid**=*pid*
   680  
   681  Set the PID mode for the container
   682  Default is to create a private PID namespace for the container
   683  - `container:<name|id>`: join another container's PID namespace
   684  - `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.
   685  - `ns`: join the specified PID namespace
   686  - `private`: create a new namespace for the container (default)
   687  
   688  #### **--pids-limit**=*limit*
   689  
   690  Tune the container's pids limit. Set `0` to have unlimited pids for the container. (default "4096" on systems that support PIDS cgroups).
   691  
   692  #### **--pod**=*name*
   693  
   694  Run container in an existing pod. If you want Podman to make the pod for you, preference the pod name with `new:`.
   695  To make a pod with more granular options, use the `podman pod create` command before creating a container.
   696  
   697  #### **--pod-id-file**=*path*
   698  
   699  Run container in an existing pod and read the pod's ID from the specified file. If a container is run within a pod, and the pod has an infra-container, the infra-container will be started before the container is.
   700  
   701  #### **--privileged**=*true|false*
   702  
   703  Give extended privileges to this container. The default is *false*.
   704  
   705  By default, Podman containers are
   706  “unprivileged” (=false) and cannot, for example, modify parts of the operating system.
   707  This is because by default a container is not allowed to access any devices.
   708  A “privileged” container is given access to all devices.
   709  
   710  When the operator executes a privileged container, Podman enables access
   711  to all devices on the host, turns off graphdriver mount options, as well as
   712  turning off most of the security measures protecting the host from the
   713  container.
   714  
   715  Rootless containers cannot have more privileges than the account that launched them.
   716  
   717  #### **--publish**, **-p**=*port*
   718  
   719  Publish a container's port, or range of ports, to the host
   720  
   721  Format: `ip:hostPort:containerPort | ip::containerPort | hostPort:containerPort | containerPort`
   722  Both hostPort and containerPort can be specified as a range of ports.
   723  When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range.
   724  (e.g., `podman run -p 1234-1236:1222-1224 --name thisWorks -t busybox`
   725  but not `podman run -p 1230-1236:1230-1240 --name RangeContainerPortsBiggerThanRangeHostPorts -t busybox`)
   726  With host IP: `podman run -p 127.0.0.1:$HOSTPORT:$CONTAINERPORT --name CONTAINER -t someimage`
   727  If host IP is set to 0.0.0.0 or not set at all, the port will be bound on all IPs on the host.
   728  Host port does not have to be specified (e.g. `podman run -p 127.0.0.1::80`).
   729  If it is not, the container port will be randomly assigned a port on the host.
   730  Use `podman port` to see the actual mapping: `podman port CONTAINER $CONTAINERPORT`
   731  
   732  **Note:** if a container will be run within a pod, it is not necessary to publish the port for
   733  the containers in the pod. The port must only be published by the pod itself. Pod network
   734  stacks act like the network stack on the host - you have a variety of containers in the pod,
   735  and programs in the container, all sharing a single interface and IP address, and
   736  associated ports. If one container binds to a port, no other container can use that port
   737  within the pod while it is in use. Containers in the pod can also communicate over localhost
   738  by having one container bind to localhost in the pod, and another connect to that port.
   739  
   740  #### **--publish-all**, **-P**=*true|false*
   741  
   742  Publish all exposed ports to random ports on the host interfaces. The default is *false*.
   743  
   744  When set to true publish all exposed ports to the host interfaces. The
   745  default is false. If the operator uses -P (or -p) then Podman will make the
   746  exposed port accessible on the host and the ports will be available to any
   747  client that can reach the host. When using -P, Podman will bind any exposed
   748  port to a random port on the host within an *ephemeral port range* defined by
   749  `/proc/sys/net/ipv4/ip_local_port_range`. To find the mapping between the host
   750  ports and the exposed ports, use `podman port`.
   751  
   752  #### **--pull**=*missing*
   753  
   754  Pull image before creating ("always"|"missing"|"never") (default "missing").
   755         '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.
   756         '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.
   757         'never': do not pull the image from the registry, use only the local version. Raise an error if the image is not present locally.
   758  
   759  Defaults to *missing*.
   760  
   761  #### **--quiet**, **-q**
   762  
   763  Suppress output information when pulling images
   764  
   765  #### **--read-only**=*true|false*
   766  
   767  Mount the container's root filesystem as read only.
   768  
   769  By default a container will have its root filesystem writable allowing processes
   770  to write files anywhere. By specifying the `--read-only` flag the container will have
   771  its root filesystem mounted as read only prohibiting any writes.
   772  
   773  #### **--read-only-tmpfs**=*true|false*
   774  
   775  If container is running in --read-only mode, then mount a read-write tmpfs on /run, /tmp, and /var/tmp. The default is *true*
   776  
   777  #### **--replace**=**true**|**false**
   778  
   779  If another container with the same name already exists, replace and remove it. The default is **false**.
   780  
   781  #### **--restart**=*policy*
   782  
   783  Restart policy to follow when containers exit.
   784  Restart policy will not take effect if a container is stopped via the `podman kill` or `podman stop` commands.
   785  
   786  Valid values are:
   787  
   788  - `no`                       : Do not restart containers on exit
   789  - `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
   790  - `always`                   : Restart containers when they exit, regardless of status, retrying indefinitely
   791  - `unless-stopped`           : Identical to **always**
   792  
   793  Please note that restart will not restart containers after a system reboot.
   794  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.
   795  To generate systemd unit files, please see *podman generate systemd*
   796  
   797  #### **--rm**=*true|false*
   798  
   799  Automatically remove the container when it exits. The default is *false*.
   800  
   801  Note that the container will not be removed when it could not be created or
   802  started successfully. This allows the user to inspect the container after
   803  failure.
   804  
   805  #### **--rootfs**
   806  
   807  If specified, the first argument refers to an exploded container on the file system.
   808  
   809  This is useful to run a container without requiring any image management, the rootfs
   810  of the container is assumed to be managed externally.
   811  
   812  #### **--sdnotify**=**container**|**conmon**|**ignore**
   813  
   814  Determines how to use the NOTIFY_SOCKET, as passed with systemd and Type=notify.
   815  
   816  Default is **container**, which means allow the OCI runtime to proxy the socket into the
   817  container to receive ready notification. Podman will set the MAINPID to conmon's pid.
   818  The **conmon** option sets MAINPID to conmon's pid, and sends READY when the container
   819  has started. The socket is never passed to the runtime or the container.
   820  The **ignore** option removes NOTIFY_SOCKET from the environment for itself and child processes,
   821  for the case where some other process above Podman uses NOTIFY_SOCKET and Podman should not use it.
   822  
   823  #### **--seccomp-policy**=*policy*
   824  
   825  Specify the policy to select the seccomp profile. If set to *image*, Podman will look for a "io.podman.seccomp.profile" label in the container-image config and use its value as a seccomp profile. Otherwise, Podman will follow the *default* policy by applying the default profile unless specified otherwise via *--security-opt seccomp* as described below.
   826  
   827  Note that this feature is experimental and may change in the future.
   828  
   829  #### **--security-opt**=*option*
   830  
   831  Security Options
   832  
   833  - `apparmor=unconfined` : Turn off apparmor confinement for the container
   834  - `apparmor=your-profile` : Set the apparmor confinement profile for the container
   835  
   836  - `label=user:USER`     : Set the label user for the container processes
   837  - `label=role:ROLE`     : Set the label role for the container processes
   838  - `label=type:TYPE`     : Set the label process type for the container processes
   839  - `label=level:LEVEL`   : Set the label level for the container processes
   840  - `label=filetype:TYPE` : Set the label file type for the container files
   841  - `label=disable`       : Turn off label separation for the container
   842  
   843  - `no-new-privileges` : Disable container processes from gaining additional privileges
   844  
   845  - `seccomp=unconfined` : Turn off seccomp confinement for the container
   846  - `seccomp=profile.json` :  White listed syscalls seccomp Json file to be used as a seccomp filter
   847  
   848  - `proc-opts=OPTIONS` : Comma separated list of options to use for the /proc mount. More details for the
   849    possible mount options are specified at **proc(5)** man page.
   850  
   851  Note: Labeling can be disabled for all containers by setting label=false in the **containers.conf** (`/etc/containers/containers.conf` or `$HOME/.config/containers/containers.conf`) file.
   852  
   853  #### **--shm-size**=*size*
   854  
   855  Size of `/dev/shm` (format: <number>[<unit>], where unit = b (bytes), k (kilobytes), m (megabytes), or g (gigabytes))
   856  If you omit the unit, the system uses bytes. If you omit the size entirely, the system uses `64m`.
   857  When size is `0`, there is no limit on the amount of memory used for IPC by the container.
   858  
   859  #### **--stop-signal**=*SIGTERM*
   860  
   861  Signal to stop a container. Default is SIGTERM.
   862  
   863  #### **--stop-timeout**=*seconds*
   864  
   865  Timeout (in seconds) to stop a container. Default is 10.
   866  Remote connections use local containers.conf for defaults
   867  
   868  #### **--subgidname**=*name*
   869  
   870  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`.
   871  
   872  #### **--subuidname**=*name*
   873  
   874  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`.
   875  
   876  #### **--sysctl**=*SYSCTL*
   877  
   878  Configure namespaced kernel parameters at runtime
   879  
   880  IPC Namespace - current sysctls allowed:
   881  
   882  kernel.msgmax, kernel.msgmnb, kernel.msgmni, kernel.sem, kernel.shmall, kernel.shmmax, kernel.shmmni, kernel.shm_rmid_forced
   883  Sysctls beginning with fs.mqueue.*
   884  
   885  Note: if you use the --ipc=host option these sysctls will not be allowed.
   886  
   887  Network Namespace - current sysctls allowed:
   888      Sysctls beginning with net.*
   889  
   890  Note: if you use the --network=host option these sysctls will not be allowed.
   891  
   892  #### **--systemd**=*true|false|always*
   893  
   894  Run container in systemd mode. The default is *true*.
   895  
   896  The value *always* enforces the systemd mode is enforced without
   897  looking at the executable name. Otherwise, if set to true and the
   898  command you are running inside the container is systemd, /usr/sbin/init,
   899  /sbin/init or /usr/local/sbin/init.
   900  
   901  If the command you are running inside of the container is systemd,
   902  Podman will setup tmpfs mount points in the following directories:
   903  
   904  /run, /run/lock, /tmp, /sys/fs/cgroup/systemd, /var/lib/journal
   905  
   906  It will also set the default stop signal to SIGRTMIN+3.
   907  
   908  This allow systemd to run in a confined container without any modifications.
   909  
   910  Note: On `SELinux` systems, systemd attempts to write to the cgroup
   911  file system. Containers writing to the cgroup file system are denied by default.
   912  The `container_manage_cgroup` boolean must be enabled for this to be allowed on an SELinux separated system.
   913  
   914  `setsebool -P container_manage_cgroup true`
   915  
   916  #### **--tmpfs**=*fs*
   917  
   918  Create a tmpfs mount
   919  
   920  Mount a temporary filesystem (`tmpfs`) mount into a container, for example:
   921  
   922  $ podman create -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_image
   923  
   924  This command mounts a `tmpfs` at `/tmp` within the container. The supported mount
   925  options are the same as the Linux default `mount` flags. If you do not specify
   926  any options, the systems uses the following options:
   927  `rw,noexec,nosuid,nodev`.
   928  
   929  #### **--tty**, **-t**=*true|false*
   930  
   931  Allocate a pseudo-TTY. The default is *false*.
   932  
   933  When set to true Podman will allocate a pseudo-tty and attach to the standard
   934  input of the container. This can be used, for example, to run a throwaway
   935  interactive shell. The default is false.
   936  
   937  Note: The **-t** option is incompatible with a redirection of the Podman client
   938  standard input.
   939  
   940  #### **--tz**=*timezone*
   941  
   942  Set timezone in container. This flag takes area-based timezones, GMT time, as well as `local`, which sets the timezone in the container to match the host machine. See `/usr/share/zoneinfo/` for valid timezones.
   943  Remote connections use local containers.conf for defaults
   944  
   945  #### **--umask**=*umask*
   946  
   947  Set the umask inside the container. Defaults to `0022`.
   948  Remote connections use local containers.conf for defaults
   949  
   950  #### **--uidmap**=*container_uid:host_uid:amount*
   951  
   952  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.
   953  
   954  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`
   955  
   956  #### **--ulimit**=*option*
   957  
   958  Ulimit options
   959  
   960  You can pass `host` to copy the current configuration from the host.
   961  
   962  #### **--user**, **-u**=*user*
   963  
   964  Sets the username or UID used and optionally the groupname or GID for the specified command.
   965  
   966  The following examples are all valid:
   967  --user [user | user:group | uid | uid:gid | user:gid | uid:group ]
   968  
   969  Without this argument the command will be run as root in the container.
   970  
   971  #### **--userns**=*auto*[:OPTIONS]
   972  #### **--userns**=*host*
   973  #### **--userns**=*keep-id*
   974  #### **--userns**=container:container
   975  #### **--userns**=private
   976  #### **--userns**=*ns:my_namespace*
   977  
   978  Set the user namespace mode for the container. It defaults to the **PODMAN_USERNS** environment variable. An empty value means user namespaces are disabled.
   979  
   980  
   981  - `auto`: automatically create a namespace. It is possible to specify other options to `auto`. The supported options are
   982    **size=SIZE** to specify an explicit size for the automatic user namespace. e.g. `--userns=auto:size=8192`. If `size` is not specified, `auto` will guess a size for the user namespace.
   983    **uidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a UID mapping to be present in the user namespace.
   984    **gidmapping=HOST_UID:CONTAINER_UID:SIZE** to force a GID mapping to be present in the user namespace.
   985  - `container`: join the user namespace of the specified container.
   986  - `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.
   987  - `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.
   988  - `ns`: run the container in the given existing user namespace.
   989  - `private`: create a new namespace for the container (default)
   990  
   991  This option is incompatible with **--gidmap**, **--uidmap**, **--subuidname** and **--subgidname**.
   992  
   993  #### **--uts**=*mode*
   994  
   995  Set the UTS namespace mode for the container. The following values are supported:
   996  
   997  - **host**: use the host's UTS namespace inside the container.
   998  - **private**: create a new namespace for the container (default).
   999  - **ns:[path]**: run the container in the given existing UTS namespace.
  1000  - **container:[container]**: join the UTS namespace of the specified container.
  1001  
  1002  #### **--volume**, **-v**[=*[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]*]
  1003  
  1004  Create a bind mount. If you specify, ` -v /HOST-DIR:/CONTAINER-DIR`, Podman
  1005  bind mounts `/HOST-DIR` in the host to `/CONTAINER-DIR` in the Podman
  1006  container. Similarly, `-v SOURCE-VOLUME:/CONTAINER-DIR` will mount the volume
  1007  in the host to the container. If no such named volume exists, Podman will
  1008  create one. The `OPTIONS` are a comma delimited list and can be: <sup>[[1]](#Footnote1)</sup>
  1009  
  1010  The _options_ is a comma delimited list and can be:
  1011  
  1012  * **rw**|**ro**
  1013  * **z**|**Z**
  1014  * [**r**]**shared**|[**r**]**slave**|[**r**]**private**[**r**]**unbindable**
  1015  * [**r**]**bind**
  1016  * [**no**]**exec**
  1017  * [**no**]**dev**
  1018  * [**no**]**suid**
  1019  * [**O**]
  1020  
  1021  The `CONTAINER-DIR` must be an absolute path such as `/src/docs`. The volume
  1022  will be mounted into the container at this directory.
  1023  
  1024  Volumes may specify a source as well, as either a directory on the host or the
  1025  name of a named volume. If no source is given, the volume will be created as an
  1026  anonymous named volume with a randomly generated name, and will be removed when
  1027  the container is removed via the `--rm` flag or `podman rm --volumes`.
  1028  
  1029  If a volume source is specified, it must be a path on the host or the name of a
  1030  named volume. Host paths are allowed to be absolute or relative; relative paths
  1031  are resolved relative to the directory Podman is run in. Any source that does
  1032  not begin with a `.` or `/` will be treated as the name of a named volume.
  1033  If a volume with that name does not exist, it will be created. Volumes created
  1034  with names are not anonymous. They are not removed by the `--rm` option and the
  1035  `podman rm --volumes` command.
  1036  
  1037  You can specify multiple  **-v** options to mount one or more volumes into a
  1038  container.
  1039  
  1040    `Write Protected Volume Mounts`
  1041  
  1042  You can add `:ro` or `:rw` suffix to a volume to mount it read-only or
  1043  read-write mode, respectively. By default, the volumes are mounted read-write.
  1044  See examples.
  1045  
  1046    `Labeling Volume Mounts`
  1047  
  1048  Labeling systems like SELinux require that proper labels are placed on volume
  1049  content mounted into a container. Without a label, the security system might
  1050  prevent the processes running inside the container from using the content. By
  1051  default, Podman does not change the labels set by the OS.
  1052  
  1053  To change a label in the container context, you can add either of two suffixes
  1054  `:z` or `:Z` to the volume mount. These suffixes tell Podman to relabel file
  1055  objects on the shared volumes. The `z` option tells Podman that two containers
  1056  share the volume content. As a result, Podman labels the content with a shared
  1057  content label. Shared volume labels allow all containers to read/write content.
  1058  The `Z` option tells Podman to label the content with a private unshared label.
  1059  Only the current container can use a private volume.
  1060  
  1061    `Overlay Volume Mounts`
  1062  
  1063     The `:O` flag tells Podman to mount the directory from the host as a
  1064  temporary storage using the `overlay file system`. The container processes
  1065  can modify content within the mountpoint which is stored in the
  1066  container storage in a separate directory. In overlay terms, the source
  1067  directory will be the lower, and the container storage directory will be the
  1068  upper. Modifications to the mount point are destroyed when the container
  1069  finishes executing, similar to a tmpfs mount point being unmounted.
  1070  
  1071    Subsequent executions of the container will see the original source directory
  1072  content, any changes from previous container executions no longer exists.
  1073  
  1074    One use case of the overlay mount is sharing the package cache from the
  1075  host into the container to allow speeding up builds.
  1076  
  1077    Note:
  1078  
  1079       - The `O` flag conflicts with other options listed above.
  1080  Content mounted into the container is labeled with the private label.
  1081         On SELinux systems, labels in the source directory must be readable
  1082  by the container label. Usually containers can read/execute `container_share_t`
  1083  and can read/write `container_file_t`. If you can not change the labels on a
  1084  source volume, SELinux container separation must be disabled for the container
  1085  to work.
  1086       - The source directory mounted into the container with an overlay mount
  1087  should not be modified, it can cause unexpected failures. It is recommended
  1088  that you do not modify the directory until the container finishes running.
  1089  
  1090    `Mounts propagation`
  1091  
  1092  By default bind mounted volumes are `private`. That means any mounts done
  1093  inside container will not be visible on host and vice versa. One can change
  1094  this behavior by specifying a volume mount propagation property. Making a
  1095  volume `shared` mounts done under that volume inside container will be
  1096  visible on host and vice versa. Making a volume `slave` enables only one
  1097  way mount propagation and that is mounts done on host under that volume
  1098  will be visible inside container but not the other way around. <sup>[[1]](#Footnote1)</sup>
  1099  
  1100  To control mount propagation property of a volume one can use the [**r**]**shared**,
  1101  [**r**]**slave**, [**r**]**private** or the [**r**]**unbindable** propagation flag.
  1102  Propagation property can be specified only for bind mounted volumes and not for
  1103  internal volumes or named volumes. For mount propagation to work the source mount
  1104  point (the mount point where source dir is mounted on) has to have the right propagation
  1105  properties. For shared volumes, the source mount point has to be shared. And for
  1106  slave volumes, the source mount point has to be either shared or slave.
  1107  <sup>[[1]](#Footnote1)</sup>
  1108  
  1109  If you want to recursively mount a volume and all of its submounts into a
  1110  container, then you can use the `rbind` option. By default the bind option is
  1111  used, and submounts of the source directory will not be mounted into the
  1112  container.
  1113  
  1114  Mounting the volume with the `nosuid` options means that SUID applications on
  1115  the volume will not be able to change their privilege. By default volumes
  1116  are mounted with `nosuid`.
  1117  
  1118  Mounting the volume with the noexec option means that no executables on the
  1119  volume will be able to executed within the container.
  1120  
  1121  Mounting the volume with the nodev option means that no devices on the volume
  1122  will be able to be used by processes within the container. By default volumes
  1123  are mounted with `nodev`.
  1124  
  1125  If the <source-dir> is a mount point, then "dev", "suid", and "exec" options are
  1126  ignored by the kernel.
  1127  
  1128  Use `df <source-dir>` to figure out the source mount and then use
  1129  `findmnt -o TARGET,PROPAGATION <source-mount-dir>` to figure out propagation
  1130  properties of source mount. If `findmnt` utility is not available, then one
  1131  can look at mount entry for source mount point in `/proc/self/mountinfo`. Look
  1132  at `optional fields` and see if any propagation properties are specified.
  1133  `shared:X` means mount is `shared`, `master:X` means mount is `slave` and if
  1134  nothing is there that means mount is `private`. <sup>[[1]](#Footnote1)</sup>
  1135  
  1136  To change propagation properties of a mount point use `mount` command. For
  1137  example, if one wants to bind mount source directory `/foo` one can do
  1138  `mount --bind /foo /foo` and `mount --make-private --make-shared /foo`. This
  1139  will convert /foo into a `shared` mount point. Alternatively one can directly
  1140  change propagation properties of source mount. Say `/` is source mount for
  1141  `/foo`, then use `mount --make-shared /` to convert `/` into a `shared` mount.
  1142  
  1143  #### **--volumes-from**[=*CONTAINER*[:*OPTIONS*]]
  1144  
  1145  Mount volumes from the specified container(s). Used to share volumes between
  1146  containers. The *options* is a comma delimited list with the following available elements:
  1147  
  1148  * **rw**|**ro**
  1149  * **z**
  1150  
  1151  Mounts already mounted volumes from a source container onto another
  1152  container. You must supply the source's container-id or container-name.
  1153  To share a volume, use the --volumes-from option when running
  1154  the target container. You can share volumes even if the source container
  1155  is not running.
  1156  
  1157  By default, Podman mounts the volumes in the same mode (read-write or
  1158  read-only) as it is mounted in the source container.
  1159  You can change this by adding a `ro` or `rw` _option_.
  1160  
  1161  Labeling systems like SELinux require that proper labels are placed on volume
  1162  content mounted into a container. Without a label, the security system might
  1163  prevent the processes running inside the container from using the content. By
  1164  default, Podman does not change the labels set by the OS.
  1165  
  1166  To change a label in the container context, you can add `z` to the volume mount.
  1167  This suffix tells Podman to relabel file objects on the shared volumes. The `z`
  1168  option tells Podman that two containers share the volume content. As a result,
  1169  Podman labels the content with a shared content label. Shared volume labels allow
  1170  all containers to read/write content.
  1171  
  1172  If the location of the volume from the source container overlaps with
  1173  data residing on a target container, then the volume hides
  1174  that data on the target.
  1175  
  1176  #### **--workdir**, **-w**=*dir*
  1177  
  1178  Working directory inside the container
  1179  
  1180  The default working directory for running binaries within a container is the root directory (/).
  1181  The image developer can set a different default with the WORKDIR instruction. The operator
  1182  can override the working directory by using the **-w** option.
  1183  
  1184  ## EXAMPLES
  1185  
  1186  ### Create a container using a local image
  1187  
  1188  ```
  1189  $ podman create alpine ls
  1190  ```
  1191  
  1192  ### Create a container using a local image and annotate it
  1193  
  1194  ```
  1195  $ podman create --annotation HELLO=WORLD alpine ls
  1196  ```
  1197  
  1198  ### Create a container using a local image, allocating a pseudo-TTY, keeping stdin open and name it myctr
  1199  
  1200  ```
  1201    podman create -t -i --name myctr alpine ls
  1202  ```
  1203  
  1204  ### Set UID/GID mapping in a new user namespace
  1205  
  1206  Running a container in a new user namespace requires a mapping of
  1207  the uids and gids from the host.
  1208  
  1209  ```
  1210  $ podman create --uidmap 0:30000:7000 --gidmap 0:30000:7000 fedora echo hello
  1211  ```
  1212  
  1213  ### Configure timezone in a container
  1214  
  1215  ```
  1216  $ podman create --tz=local alpine date
  1217  $ podman create --tz=Asia/Shanghai alpine date
  1218  $ podman create --tz=US/Eastern alpine date
  1219  ```
  1220  
  1221  ### Rootless Containers
  1222  
  1223  Podman runs as a non root user on most systems. This feature requires that a new enough version of shadow-utils
  1224  be installed. The shadow-utils package must include the newuidmap and newgidmap executables.
  1225  
  1226  Note: RHEL7 and Centos 7 will not have this feature until RHEL7.7 is released.
  1227  
  1228  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.
  1229  
  1230  Rootless Podman works better if the fuse-overlayfs and slirp4netns packages are installed.
  1231  The fuse-overlay package provides a userspace overlay storage driver, otherwise users need to use
  1232  the vfs storage driver, which is diskspace expensive and does not perform well. slirp4netns is
  1233  required for VPN, without it containers need to be run with the --network=host flag.
  1234  
  1235  ## ENVIRONMENT
  1236  
  1237  Environment variables within containers can be set using multiple different options:  This section describes the precedence.
  1238  
  1239  Precedence order (later entries override earlier entries):
  1240  
  1241  - **--env-host** : Host environment of the process executing Podman is added.
  1242  - **--http-proxy**: By default, several environment variables will be passed in from the host, such as **http_proxy** and **no_proxy**. See **--http-proxy** for details.
  1243  - Container image : Any environment variables specified in the container image.
  1244  - **--env-file** : Any environment variables specified via env-files. If multiple files specified, then they override each other in order of entry.
  1245  - **--env** : Any environment variables specified will override previous settings.
  1246  
  1247  Create containers and set the environment ending with a __*__ and a *****
  1248  
  1249  ```
  1250  $ export ENV1=a
  1251  $ podman create --name ctr --env ENV* alpine printenv ENV1
  1252  $ podman start --attach ctr
  1253  a
  1254  
  1255  $ podman create --name ctr --env ENV*****=b alpine printenv ENV*****
  1256  $ podman start --attach ctr
  1257  b
  1258  ```
  1259  
  1260  ## FILES
  1261  
  1262  **/etc/subuid**
  1263  **/etc/subgid**
  1264  
  1265  NOTE: Use the environment variable `TMPDIR` to change the temporary storage location of downloaded container images. Podman defaults to use `/var/tmp`.
  1266  
  1267  ## SEE ALSO
  1268  **podman**(1), **podman-save**(1), **podman-ps**(1), **podman-attach**(1), **podman-pod-create**(1), **podman-port**(1), **podman-kill**(1), **podman-stop**(1),
  1269  **podman-generate-systemd**(1) **podman-rm**(1), **subgid**(5), **subuid**(5), **containers.conf**(5), **systemd.unit**(5), **setsebool**(8), **slirp4netns**(1), **fuse-overlayfs**(1), **proc**(5)**.
  1270  
  1271  ## HISTORY
  1272  October 2017, converted from Docker documentation to Podman by Dan Walsh for Podman <dwalsh@redhat.com>
  1273  
  1274  November 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
  1275  
  1276  September 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
  1277  
  1278  August 2014, updated by Sven Dowideit <SvenDowideit@home.org.au>
  1279  
  1280  ## FOOTNOTES
  1281  <a name="Footnote1">1</a>: The Podman project is committed to inclusivity, a core value of open source. The `master` and `slave` mount propagation terminology used here is problematic and divisive, and should be changed. However, these terms are currently used within the Linux kernel and must be used as-is at this time. When the kernel maintainers rectify this usage, Podman will follow suit immediately.