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.