podman-container.unit(5)
💅 podman-container.unit(5) 💅
okay bestie, welcome to the File Formats Manual entry for podman-container.unit — it's literally all about systemd unit files for managing containers using Podman Quadlet 🫶✨
🎀 NAME 🎀
podman-container.unit — systemd unit files for managing containers using Podman Quadlet 👑
✨ SYNOPSIS ✨
name.container🦋 DESCRIPTION 🦋
Container units are named with a .container extension and contain a [Container] section describing the container that is run as a service. The resulting service file contains a line like ExecStart=podman run ... image-name, and most of the keys in this section control the command-line options passed to Podman. However, some options also affect the details of how systemd is set up to run and interact with the container. no cap, it's giving "Podman options but make it systemd" 💅
By default, the Podman container has the same name as the unit, but with a systemd- prefix, i.e. a $name.container file creates a $name.service unit and a systemd-$name Podman container. The ContainerName option allows for overriding this default name with a user-provided one. so yes, the naming lore is real 🎀
There is only one required key, Image, which defines the container image the service runs. that's the main character key fr fr 👑
🌈 USAGE SUMMARY 🌈
The .container file is parsed by the podman-system-generator at boot or reload, generating a systemd .service that runs podman run. That service can be managed like any other unit:
systemctl --user start myimage-container.servicelowkey iconic: you write a .container, systemd gets a whole .service, and you manage it like any other unit 💖
🔥 OPTIONS 🔥
Valid options for [Container] are listed below: 👇
okay so, part two of the matching game, let's GO 🎀 — left side is what you literally type in the unit file, right side is the podman run flag it's secretly translating to. Same facts, more glitter, no cap ✨
💅 [Container] options vs. podman run, the crossover episode (cont'd) 💅
AddCapability=CAP→--cap-add CAP— hand this container a shiny new capability. it's giving "you get a power, you get a power" 👑AddDevice=/dev/foo→--device /dev/foo— pass a device straight through from the host, no middleman 🫶AddHost=example.com:192.168.10.11→--add-host example.com:192.168.10.11— a little extra/etc/hostsentry, just for this container 🌸Annotation="XYZ"→--annotation "XYZ"— stick an annotation on it, quotes and all, don't strip them babe 💖AutoUpdate=registry→--label "io.containers.autoupdate=registry"— the magic is literally that it becomes a label. that's the whole trick 🪄CgroupsMode=no-conmon→--cgroups=no-conmon— cgroup-flavoured fine tuning, exact same string 💀ContainerName=name→--name name— give the poor thing a name, it deserves one 🥺ContainersConfModule=/etc/nvd.conf→--module=/etc/nvd.conf— load a containers.conf module (yes,/etc/nvd.confis what the table says, don't come for me, copy it exactly 📋)DNS=192.168.55.1→--dns=192.168.55.1— point it at a resolver of your choosing 🌈DNSOption=ndots:1→--dns-option=ndots:1— resolver options, thendots:1life ✨DNSSearch=example.com→--dns-search example.com— search domains, iconic behaviour only 🔍DropCapability=CAP→--cap-drop=CAP— snatch a capability away. mean but necessary, lowkey 💅Entrypoint=/foo.sh→--entrypoint=/foo.sh— override the entrypoint, main character energy 💫Environment=foo=bar→--env foo=bar— env var time,foo=barstyle 🍓EnvironmentFile=/tmp/env→--env-file /tmp/env— load a whole file of env vars, bulk vibes 🧺EnvironmentHost=true→--env-host— slurp all the host's env vars in, no flags needed, just vibes 🔥Exec=/usr/bin/command→ command after the image specification —/usr/bin/command. yeah this one isn't a flag at all, it's just the command you tack on AFTER the image. huge difference bestie, don't forget it 😭ExposeHostPort=50-59→--expose 50-59— expose a whole range, look at you go ✨GIDMap=0:10000:10→--gidmap=0:10000:10— GID mapping, colon-separated, exact same numbers 🎯GlobalArgs=--log-level=debug→--log-level=debug— global args get passed along, here it's--log-level=debug🪵Group=1234→--user UID:1234— and this is the chaotic one:Group=maps onto the group part of--user, so it's--user UID:1234💀GroupAdd=keep-groups→--group-add=keep-groups— add supplementary groups,keep-groupsbeing the iconic special value 👯HealthCmd=/usr/bin/command→--health-cmd=/usr/bin/command— the healthcheck command, your container's little pulse check 💓HealthInterval=2m→--health-interval=2m— how often it checks, every2m⏱️HealthLogDestination=/foo/log→--health-log-destination=/foo/log— where those healthcheck logs land 📁HealthMaxLogCount=5→--health-max-log-count=5— cap it at5log entries bestie 🔢HealthMaxLogSize=500→--health-max-log-size=500— and cap the size at500too, we're being responsible today 🫶HealthOnFailure=kill→--health-on-failure=kill— what happens when it's unhealthy:kill. dramatic, honestly 💀HealthRetries=5→--health-retries=5—5strikes before it's officially unwell 😮💨HealthStartPeriod=1m→--health-start-period=1m— grace period of1mso it can get its life together first 🌱HealthStartupCmd=command→--health-startup-cmd=command— a separate startup healthcheck command, for the getting-ready era 🚀HealthStartupInterval=1m→--health-startup-interval=1m— check every1mduring startup ⏰HealthStartupRetries=8→--health-startup-retries=8—8startup retries, generous queen 👑HealthStartupSuccess=2→--health-startup-success=2—2successful startup checks and it's officially up 🌟
…and that's exactly where this table hands off 👀 keep scrolling, there's more bestie, we're not done 💜
HealthStartupTimeout=1m33s— becomes--health-startup-timeout=1m33s. Your little grace period for slow starters, bestie 🫶HealthTimeout=20s— becomes--health-timeout=20s. How long the healthcheck gets before it's declared a flop 💀HostName=example.com— becomes--hostname example.com, so your container knows its own name. main character energy, honestly ✨HttpProxy=true— becomes--http-proxy=true. Proxy vibes get passed through, no cap.Image=ubi8— this one's the image specification, and it lands on the command line as justubi8. Literally the whole point of the container 🎀ImageVolume=tmpfs— becomes--image-volume tmpfs. Choose what kind of volume backs the image's own data.IP=192.5.0.1— becomes--ip 192.5.0.1. A whole IPv4 address, hand-picked, iconic 💅IP6=2001:db8::1— becomes--ip6 2001:db8::1. Same energy but v6, and yes those colons are load-bearing 🦋Label="XYZ"— becomes--label "XYZ". Sticker your container with metadata, it's giving scrapbook 🌸LogDriver=journald— becomes--log-driver journald. Where the logs go to live their life.LogOpt=path=/var/log/mykube.json— becomes--log-opt path=/var/log/mykube.json. The fine-tuning knob for that log driver, iykyk.Mask=/proc/sys/foo:/proc/sys/bar— becomes--security-opt mask=/proc/sys/foo:/proc/sys/bar. Hide those paths from the container, lowkey protective queen behavior 👑Memory=20g— becomes--memory 20g. A whole20glimit, so your container can't eat the entire machine 😭Mount=type=...— becomes--mount type=.... Full mount spec, passed straight through, no shortcuts.Network=host— becomes--network host. Straight into host networking, bold move, we respect it 🔥NetworkAlias=name— becomes--network-alias name. A cute lil nickname so other containers can find you.NoNewPrivileges=true— becomes--security-opt no-new-privileges. Note the flag drops the=true, that's just how it is, fr fr 💜Notify=true— becomes--sdnotify container. Which is the sdnotify setting for containers, periodt.PidsLimit=10000— becomes--pids-limit 10000. Caps how many processes can exist at once, so nobody spawns a million gremlins 🙈Pod=pod-name— becomes--pod=pod-name. Drop the container into an existing pod, bestie 🫶PodmanArgs=--publish 8080:80— the escape hatch! Extra args go straight to podman, and the example lands as--publish 8080:80. Use responsibly ✨PublishPort=8080:80— becomes--publish 8080:80. Port go out into the world 🌈Pull=never— becomes--pull never. Choose your pull policy, andnevermeans never, she said what she said 💅ReadOnly=true— becomes--read-only. Root filesystem goes read-only, very "look don't touch" 🎀ReadOnlyTmpfs=true— becomes--read-only-tmpfs. Which is the separate flag for that, don't merge them in your head, bestie.ReloadCmd=/usr/bin/command— this one's different! It addsExecReloadand runs exec with the value. Not a podman flag at all — it's systemd doing its thing ⭐ReloadSignal=SIGHUP— also not a podman flag: addsExecReloadand runs kill with the signal. So the reload actually happens 🦋Retry=5— becomes--retry=5. How many times it tries again before giving up 😭RetryDelay=5s— becomes--retry-delay=5s. The lil breather between retries, self-care fr.Rootfs=/var/lib/rootfs— becomes--rootfs /var/lib/rootfs. Use a rootfs instead of an image, fancy.RunInit=true— becomes--init. A tiny init process inside, keeping things tidy 🧚SeccompProfile=/tmp/s.json— becomes--security-opt seccomp=/tmp/s.json. Your seccomp profile, applied, no drama.Secret=secret— becomes--secret=secret[,opt=opt ...]— yes, with the optional comma-separated options, copy it exactly like that 🍓SecurityLabelDisable=true— becomes--security-opt label=disable. Turning labels off, dramatic but valid 💀SecurityLabelFileType=usr_t— becomes--security-opt label=filetype:usr_t. Note that colon, it's not a typo, bestie 👀SecurityLabelLevel=s0:c1,c2— becomes--security-opt label=level:s0:c1,c2. Same deal, colon afterlevel, then the value verbatim 💜SecurityLabelNested=true— maps to--security-opt label=nested✨SecurityLabelType=spc_t— maps to--security-opt label=type:spc_tShmSize=100m— maps to--shm-size=100mStartWithPod=true— ifPod=is defined, the container is started by the pod 🫶StopSignal=SIGINT— maps to--stop-signal=SIGINTStopTimeout=20— maps to--stop-timeout=20SubGIDMap=gtest— maps to--subgidname=gtestSubUIDMap=utest— maps to--subuidname=utestSysctl=name=value— maps to--sysctl=name=valueTimezone=local— maps to--tz local🌍Tmpfs=/work— maps to--tmpfs /workUIDMap=0:10000:10— maps to--uidmap=0:10000:10Ulimit=nofile=1000:10000— maps to--ulimit nofile=1000:10000Unmask=ALL— maps to--security-opt unmask=ALLUser=bin— maps to--user binUserNS=keep-id:uid=200,gid=210— maps to--userns keep-id:uid=200,gid=210Volume=/source:/dest— maps to--volume /source:/destWorkingDir=$HOME— maps to--workdir $HOME
Supported keys in the [Container] section are: 👑
AddCapability=capability
Adds Linux capabilities. ✨
Bestie, real talk: granting extra capabilities bumps up the privileges of the processes running inside the container, and it can potentially let the container break out of confinement. 😭 Capabilities likeCAP_SYS_ADMIN,CAP_SYS_PTRACE,CAP_MKNODandCAP_SYS_MODULEare especially dangerous when they're not used inside a user namespace. Go readuser_namespaces(7)for the full breakdown of how user namespaces and capabilities interact — it's giving required reading, ngl.
Before you add any capability, review its security implications and make sure it's actually necessary for what the container does. See capabilities(7) for more info. 💅
AddDevice=host-device[:container-device][:permissions]
Adds a host device to the container. The format is HOST-DEVICE[:CONTAINER-DEVICE][:PERMISSIONS], where HOST-DEVICE is the path of the device node on the host, CONTAINER-DEVICE is the path of the device node in the container, and PERMISSIONS is a list of permissions combining 'r' for read, 'w' for write, and 'm' for mknod(2).
Example: --device=/dev/sdc:/dev/xvdc:rwm. 🎀
Note: if host-device is a symbolic link then it gets resolved first. The container only stores the major and minor numbers of the host device. 🦋
Podman may load kernel modules required for using the specified device. The devices Podman loads modules for when necessary are: /dev/fuse.
In rootless mode, the new device is bind mounted in the container from the host rather than Podman creating it within the container space. Because the bind mount keeps its SELinux label on SELinux systems, the container can get permission denied when it tries to access the mounted device. 😤 So modify your SELinux settings to allow containers to use all device labels via this command:
$ sudo setsebool -P container_use_devices=trueAddHost=hostname[;hostname[;...]]:ip
Adds a custom host-to-IP mapping to the container's /etc/hosts file. 🏠
This option takes one or multiple semicolon-separated hostnames to be mapped to a single IPv4 or IPv6 address, separated by a colon. It can also be used to overwrite the IP addresses of hostnames Podman adds to /etc/hosts by default (also see the --name and --hostname options). You can specify this option multiple times to add extra mappings to /etc/hosts. Heads up: it conflicts with the --no-hosts option and it conflicts with no_hosts=true in containers.conf. 💀
Instead of an IP address, you can hand it the special flag host-gateway. That resolves to an IP address the container can use to connect to the host. The IP address it picks depends on your network setup, so there's no guarantee Podman can figure out the host-gateway address automatically — and if it can't, Podman fails with an error message. 🙈 You can overwrite this IP address using the host_containers_internal_ip option in containers.conf.
The host-gateway address is also what Podman uses to automatically add the host.containers.internal and host.docker.internal hostnames to /etc/hosts. You can prevent that by either giving the --no-hosts option, or by setting host_containers_internal_ip="none" in containers.conf. If no host-gateway address was configured manually and Podman fails to determine the IP address automatically, Podman silently skips adding these internal hostnames to /etc/hosts. And if Podman is running in a virtual machine using podman machine (this includes Mac and Windows hosts), Podman silently skips adding the internal hostnames to /etc/hosts unless an IP address was configured manually — instead, the internal hostnames are resolved by the gvproxy DNS resolver. 🧚
By default Podman uses the /etc/hosts file of the host as a basis, so any hostname present in that file will also be present in the /etc/hosts file of the container. You can configure a different base file using the base_hosts_file config in containers.conf.
Annotation=key=value
Adds an annotation to the container. You can set this option multiple times. 🎀
AutoUpdate=registry
Tells you whether the container will be auto-updated (podman-auto-update(1)). These are the supported values:
registry: requires a fully-qualified image reference (e.g.,quay.io/podman/stable:latest) to be used to create the container. This enforcement is necessary so Podman knows which image to actually check and pull. If an image ID was used, Podman doesn't know which image to check/pull anymore. 😬local: tells Podman to compare the image a container is using to the image with its raw name in local storage. If an image is updated locally, Podman simply restarts the systemd unit executing the container. 🔥
CgroupsMode=how
Determines whether the container creates cgroups.
By default, the cgroups mode of the container created by Quadlet is split, which differs from the default (enabled) used by the Podman CLI. 👀
If the container joins a pod (i.e. Pod= is specified), you may want to change this to no-conmon or enabled so that pod level cgroup resource limits can take effect. 💜
Okay so picking up right where we left off, the cgroup modes go a little somethin' like this:
enabled— makes a new cgroup under the cgroup-parent. Clean, classic, slay.disabled— forces the container to not create cgroups at all, which is why it conflicts with the cgroup options (--cgroupnsand--cgroup-parent). Pick a lane bestie, you can't have both 😭no-conmon— disables a new cgroup only for the conmon process. Very "only the conmon one, not the whole squad".split— splits the current cgroup in two sub-cgroups: one for conmon and one for the container payload. Iconic, but heads up: it is not possible to set--cgroup-parentwithsplit. That's a hard no 🚫
ContainerName=name
Assign a name to the container. Naming your container is so underrated, honestly.
The operator can identify a container in three ways:
- UUID long identifier (
"f78375b1c487e03c9438c729345e54db9d20cfa2ac1fc3494b6eb60872e74778") — the full government name - UUID short identifier (
"f78375b1c487") — the nickname - Name (
"jonah") — the vibe
Podman generates a UUID for each container, and if no name is assigned using ContainerName=, Podman generates a random string name such as exciting_chebyshev (adjective_noun, compatible with Docker). Container names are not required to be valid hostnames or domain names. Underscores and other characters allowed by naming rules are permitted. On Podman networks with DNS enabled, container-to-container name resolution still uses the name as given, for example exciting_chebyshev. The name can be useful as a more human-friendly way to identify containers. This works for both background and foreground containers. The container's name is also added to the /etc/hosts file using the container's primary IP address (also see the AddHost= option).
💡 The name is not the hostname inside the container — seeHostName=. And seepodman-network(1)for more on network DNS.
ContainersConfModule=module
Load the specified containers.conf(5) module.
This option can be listed multiple times — stack 'em, bestie 🎀
DNS=ipaddr
Set custom DNS servers. This is the "my DNS is a mess, please help" button.
This option can be used to override the DNS configuration passed to the container. Typically this is necessary when the host DNS configuration is invalid for the container (e.g., 127.0.0.1). When this is the case, the DNS= flag is necessary for every run. Like yes, every single time, no skipping 💅
The special value none can be specified to disable creation of /etc/resolv.conf in the container by Podman. The /etc/resolv.conf file in the image is then used without changes.
Note that ipaddr may be added directly to the container's /etc/resolv.conf. This is not guaranteed though. For example, passing a custom network whose dns_enabled is set to true to --network will result in /etc/resolv.conf only referring to the aardvark-dns server. aardvark-dns then forwards to the supplied ipaddr for all non-container name queries. Sneaky little forwarder, love that for it 🦋
DNSOption=option
Set custom DNS options. Invalid if using DNSOption= with Network= that is set to none or container:id. So don't do that fr.
DNSSearch=domain
Set custom DNS search domains. Invalid if using DNSSearch= with Network= that is set to none or container:id. Use DNSSearch=. to remove the search domain. Periodt.
DropCapability=capability
Drop these capabilities from the default podman capability set, or all to drop all capabilities. Going full minimal, respect.
This is a space separated list of capabilities.
Entrypoint="command"
Override the default ENTRYPOINT from the image. The main character gets to change outfits ✨
The ENTRYPOINT of an image is similar to a COMMAND because it specifies what executable to run when the container starts, but it is (purposely) more difficult to override. The ENTRYPOINT gives a container its default nature or behavior. When the ENTRYPOINT is set, the container runs as if it were that binary, complete with default options. More options can be passed in via the COMMAND. But, if a user wants to run something else inside the container, the Entrypoint= option allows a new ENTRYPOINT to be specified.
Specify multi option commands in the form of a JSON string.
Environment=env=value [env=value ...]
Set environment variables. The "carry this in your bag" of container config.
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 checks the host environment for a value and set the variable only if it is set on the host. As a special case, if an environment variable ending in * is specified without a value, Podman searches the host environment for variables starting with the prefix and adds those variables to the container. Wildcard behaviour, we love to see it 🌈
EnvironmentFile=file
Read in a line-delimited file of environment variables. Load-bearing little text file, iconic.
EnvironmentHost=
Use host environment inside of the container. See Environment note below for precedence. (This option is not available with the remote Podman client, including Mac and Windows (excluding WSL2) machines) 🙈
Exec=command
Additional arguments for the container; this has exactly the same effect as passing more arguments after a podman run <image> <arguments> invocation.
The format is the same as for systemd command lines. However, unlike the similarly named systemd ExecStart= directive which operates on the ambient root filesystem, it is very common for container images to have their own ENTRYPOINT or CMD metadata which this interacts with.
The default expectation for many images is that the image will include an ENTRYPOINT with a default binary, and this field will add arguments to that entrypoint.
Another way to describe this is that it works the same way as the args field in a Kubernetes pod. Kubernetes crossover episode, we're eating 🍓
ExposeHostPort=port[/protocol]
Expose a port or a range of ports (e.g. Expose=3300-3310). The protocol can be tcp, udp or sctp and if not given tcp is assumed. This option matches the EXPOSE instruction for image builds and has no effect on the actual networking rules unless -P/--publish-all is used to forward to all exposed ports from random host ports. To forward specific ports from the host into the container use the PublishPort= option instead. Don't get it twisted bestie, this is a label not a lived experience 💀
GIDMap=[flags]container_gid:from_gid[:amount]
Run the container in a new user namespace using the supplied GID mapping. This option conflicts with the UserNS= and SubGIDMap= options. This option provides a way to map host GIDs to container GIDs in the same way as --uidmap maps host UIDs to container UIDs. For details see --uidmap.
⚠️ Note: theGIDMap=option cannot be called in conjunction with thePod=option as a gidmap cannot be set on the container level when in a pod. Rules are rules 😤
GlobalArgs=
This key contains a list of arguments passed directly after the podman command in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option. You're on your own with this one, godspeed 🫶
The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
Group=gid
The (numeric) GID to run as inside the container. This does not need to match the GID on the host, which can be modified with UserNS, but if that is not specified, this GID is also used on the host.
GroupAdd=group | keep-groups
Assign additional groups to the primary user running within the container process.
keep-groupsis a special flag that tells Podman to keep the supplementary group access.
Allows container to use the user's supplementary group access. If file systems or devices are only accessible by the rootless user's group, this flag tells the OCI runtime to pass the group access into the container. Currently only available with the crun OCI runtime.
⚠️ Note: keep-groups is exclusive, other groups cannot be specified with this flag. (Not available for remote commands, including Mac and Windows (excluding WSL2) machines) No sharing, it's a solo act 💅
HealthCmd="command"
Set or alter a healthcheck command for a container. The command is a command to be executed inside the container that determines the container health. The command is required for other healthcheck options to be applied. A value of none disables existing healthchecks.
Multiple options can be passed in the form of a JSON array; otherwise, the command is interpreted as an argument to /bin/sh -c.
📌 Note: The default values are used even if healthcheck is configured in the image. Yes, even then.
HealthInterval=interval
Set an interval for the healthchecks. An interval of disable results in no automatic timer setup. The default is 30s.
📌 Note: This parameter will overwrite related healthcheck configuration from the image.
HealthLogDestination=directory_path
Set the destination of the HealthCheck log. Directory path, local or events_logger (local use container state file) (Default: local)
local: (default) HealthCheck logs are stored in overlay containers. (For example:$runroot/healthcheck.log)directory: creates a log file named<container-ID>-healthcheck.logwith HealthCheck logs in the specified directory.events_logger: The log will be written with logging mechanism set byevents_logger. It also saves the log to a default directory, for performance on a system with a large number of logs.
HealthMaxLogCount=number
Set maximum number of attempts in the HealthCheck log file. ('0' value means an infinite number of attempts in the log file) (Default: 5 attempts)
HealthMaxLogSize=size
Set maximum length in characters of stored HealthCheck log. ("0" value means an infinite log length) (Default: 500 characters)
HealthOnFailure=action
Action to take once the container transitions to an unhealthy state. The default is none.
none: Take no action. Living that chill life.kill: Kill the container.restart: Restart the container. Do not combine therestartaction with the--restartflag. When running inside of a systemd unit, consider using thekillorstopaction instead to make use of systemd's restart policy.stop: Stop the container.
HealthRetries=retries
The number of retries allowed before a healthcheck is considered to be unhealthy. The default value is 3.
📌 Note: This parameter can overwrite the healthcheck configuration from the image.
HealthStartPeriod=period
The initialization time needed for a container to bootstrap. The value can be expressed in time format like 2m3s. The default value is 0s. Give her a minute to get ready, she's doing her hair ✨
📌 Note: The health check command is executed as soon as a container is started, if the health check is successful the container's health state will be updated to healthy. However, if the health check fails, the health state will stay as starting until either the health check is successful or until theHealthStartPeriod=time is over. If the health check command fails after theHealthStartPeriod=time is over, the health state will be updated to unhealthy. The health check command is executed periodically based on the value ofHealthInterval=.
📌 Note: This parameter will overwrite related healthcheck configuration from the image.
HealthStartupCmd="command"— sets a startup healthcheck command for your container, bestie. it runs inside the container and its whole job is to gate the regular healthcheck — like a bouncer checking IDs before the actual party starts. once the startup command succeeds, the regular healthcheck begins and the startup healthcheck dips out. optionally, if the command fails a set number of times, the container gets restarted. use this when your container has a long lil startup era and you don't want it getting marked unhealthy before it's even fully awake. 🫶 note: startup healthchecks only work when a regular healthcheck is also set (either from the container's image or via theHealthCmd=option).HealthStartupInterval=interval— sets the interval for the startup healthcheck. an interval ofdisablemeans no automatic timer setup, periodt. default is30s. ⏰HealthStartupRetries=retries— how many attempts are allowed before the startup healthcheck restarts the container. if set to0, the container is never restarted. default is0. 💀HealthStartupSuccess=retries— how many successful runs are required before the startup healthcheck succeeds and the regular healthcheck kicks in. a value of0means any success starts the regular healthcheck. default is0. ✨HealthStartupTimeout=timeout— the maximum time a startup healthcheck command has to finish before it gets marked as failed. can be expressed in a time format like2m3s. default is30s. 😭HealthTimeout=timeout— the max time allowed to complete the healthcheck before an interval is considered failed. like start-period, you can write it in a time format such as1m22s. default is30s.
Note: a timeout marks the healthcheck as failed. if the healthcheck command itself runs longer than the specified timeout, it gets sent a SIGKILL signal. brutal but fair 💅
Note: this parameter will overwrite related healthcheck configuration from the image.
HostName=name— sets the container's hostname inside the container. 🏠
this option can only be used with a private UTS namespace — --uts=private (default). if Pod= is given and the pod shares the same UTS namespace (default), the pod's hostname is used instead. the given hostname also gets added to the /etc/hosts file using the container's primary IP address (also see the AddHost= option).
when HostName= is unset and the container uses a private UTS namespace (default), Podman sets the hostname to the first 12 characters of the container ID. the container name assigned with ContainerName= is not used unless container_name_as_hostname=true is set in containers.conf.
Podman network DNS registers the container name, the short container ID (first 12 characters), and any explicitly set --hostname as DNS names. the default hostname matches the short ID alias. see podman-network(1). 🌈
HttpProxy=— by default, proxy environment variables get passed into the container if they're set for the Podman process. you can turn this off by setting the value tofalse. the env vars passed in includehttp_proxy,https_proxy,ftp_proxy,no_proxy, and also the upper case versions of those. this option is only needed when the host system must use a proxy but the container doesn't use any proxy. proxy env vars specified for the container in any other way override the values that have been passed through from the host. (other ways to specify the proxy for the container include passing the values with the--envflag, or hard coding the proxy environment at container build time.) when used with the remote client, it uses the proxy environment variables that are set on the server process.
defaults to true. 🧚
Image=name— the image to run in the container. ngl, it's recommended to use a fully qualified image name rather than a short name, both for performance and robustness reasons. 👑
the format of the name is the same as when passed to podman pull. so it supports using :tag or digests to guarantee the specific image version.
Special Cases:
- if the name of the image ends with
.image, Quadlet will use the image pulled by the corresponding.imagefile, and the generated systemd service contains a dependency on the$name-image.service(or the service name set in the.imagefile). note that the corresponding.imagefile must exist. - if the name of the image ends with
.build, Quadlet will use the image built by the corresponding.buildfile, and the generated systemd service contains a dependency on the$name-build.service. note: the corresponding.buildfile must exist.
ImageVolume=mode— tells Podman how to handle the builtin image volumes. default isbind. 🍓bind: an anonymous named volume is created and mounted into the container.tmpfs: the volume is mounted onto the container as atmpfs, which allows users to create content that disappears when the container is stopped.ignore: all volumes are just ignored and no action is taken.
IP=IPv4— specify a static IPv4 address for the container, for example10.88.64.128. this option can only be used if the container is joined to only a single network — i.e.,Network=network-nameis used at most once — and if the container is not joining another container's network namespace viaNetwork=container:id. the address must be within the network's IP address pool (default10.88.0.0/16). 🌸
to specify multiple static IP addresses per container, set multiple networks using the Network= option with a static IP address specified for each using the ip mode for that option.
IP6=IPv6— specify a static IPv6 address for the container, for examplefd46:db93:aa76:ac37::10. this option can only be used if the container is joined to only a single network — i.e.,Network=network-nameis used at most once — and if the container is not joining another container's network namespace viaNetwork=container:id. the address must be within the network's IPv6 address pool. 🦋
to specify multiple static IPv6 addresses per container, set multiple networks using the Network= option with a static IPv6 address specified for each using the ip6 mode for that option.
Label=key=value [key=value ...]— add metadata to a container. 🏷️LogDriver=driver— logging driver for the container. currently available options arek8s-file,journald,none,passthroughandpassthrough-tty, withjson-filealiased tok8s-filefor scripting compatibility. (defaultjournald).
the podman info command below displays the default log-driver for the system.
$ podman info --format '{{ .Host.LogDriver }}'
journaldthe passthrough driver passes down the standard streams (stdin, stdout, stderr) to the container. it is not allowed with the remote Podman client, including Mac and Windows (excluding WSL2) machines, and on a tty, since it is vulnerable to attacks via TIOCSTI. 😬
the passthrough-tty driver is the same as passthrough except that it also allows it to be used on a TTY if the user really wants it.
LogOpt=name=value— logging driver specific options. 💅
set custom logging configuration. the following *name*s are supported:
path: specify a path to the log file (e.g.LogOpt=path=/var/log/container/mycontainer.json);max-size: specify a max size of the log file (e.g.LogOpt=max-size=10mb);tag: specify a custom log tag for the container (e.g.LogOpt=tag="{{.ImageName}}". it supports the same keys aspodman inspect --format. this option is currently supported only by thejournaldlog driver.label: specify a custom log label for the container (e.g.--log-opt label="CONTAINER_IMAGE={{.ImageName}}". it supports the same keys aspodman inspect --format. this option can be repeated multiple times. this option is currently supported only by thejournaldlog driver.
Mask=/path/1:/path/2— specify the paths to mask separated by a colon:Mask=/path/1:/path/2. a masked path cannot be accessed inside the container. 🙈Memory=number[unit]— memory limit. a unit can beb(bytes),k(kibibytes),m(mebibytes), org(gibibytes). 🧠
allows the memory available to a container to be constrained. if the host supports swap memory, then the Memory= memory setting can be larger than physical RAM. if a limit of 0 is specified (not using Memory=), the container's memory is not limited. the actual limit may be rounded up to a multiple of the operating system's page size (the value is very large, that's millions of trillions).
this option is not supported on cgroups V1 rootless systems.
Mount=type=TYPE,TYPE-SPECIFIC-OPTION[,...]— attach a filesystem mount to the container. 🔥
Special cases:
- for
type=volume, ifsourceends with.volume, the Podman named volume generated by the corresponding.volumefile is used. - for
type=image, ifsourceends with.image, the image generated by the corresponding.imagefile is used.
in both cases, the generated systemd service will contain a dependency on the service generated for the corresponding unit. note: the corresponding .volume or .image file must exist.
current supported mount TYPEs are artifact, bind, devpts, glob, image, ramfs, tmpfs and volume.
options common to all mount types:
src,source: mount source spec forbind,glob, andvolume. mandatory forartifact,bind,glob, andimage. optional forvolume; if omitted, an anonymous volume is created.dst,dest,destination,target: mount destination spec.
when source globs are specified without the destination directory, the files and directories are mounted with their complete path within the container. when the destination is specified, the files and directories matching the glob on the base file name on the destination directory are mounted. the option type=glob,src=/foo*,destination=/tmp/bar tells container engines to mount host files matching /foo* to the /tmp/bar/ directory in the container.
options specific to type=artifact:
digest: if the artifact source contains multiple blobs, a digest can be specified to only mount the one specific blob with the digest.title: if the artifact source contains multiple blobs, a title can be set which is compared against theorg.opencontainers.image.titleannotation.name: this can be used to overwrite the filename we use inside the container for mounting. on a single blob artifact the name is used as is ifdstis a directory and otherwise ignored. with a multi blob artifact the name will be used with an index suffix<name>-xwherexis the layer index in the artifact starting with0.
The src argument is the artifact's name, and bestie it has to already exist locally — no downloading it on the fly, that's not the vibe here. The dst argument is the target path. If that path in the container is a directory, the blob title (the org.opencontainers.image.title annotation, iykyk) gets used as the filename and joined onto the path. If that annotation isn't there? Then the digest steps in as the filename instead. End result: all the blobs of the artifact get mounted into the container at the path you gave. Obsessed. ✨
But wait — plot twist. If the dst path is an existing file in the container, then the blob gets mounted directly on it. This only works when the artifact has a single blob, or when either digest or title are specified. Rules are rules 💅
And if the dst path doesn't already exist in the container? Then: if the artifact contains a single blob, it behaves like the existing-file case and mounts straight to that path. If the artifact has more than one blob, it works like the existing-directory case and mounts each blob as a file inside the dst path. Literally so logical fr fr 🌸
Options specific to type=volume:
ro,readonly—trueorfalse(default if unspecified:false).U,chown—trueorfalse(default if unspecified:false). Recursively change the owner and group of the source volume based on the UID and GID of the container.subpath— Mount only a specific subpath within the volume, instead of the whole volume.relabel—shared,private. Recursively walk the mount and set the security system (e.g. SELinux) label on each file to grant access permissions from the container context.sharedapplies a label that grants permissions to all containers, whileprivateapplies a label that grants permissions to this specific container. 🎀z,Z— shorthand forrelabel=sharedandrelabel=private, respectively.idmap— If specified, create an idmapped mount to the target user namespace in the container. Theidmapoption is only supported by Podman in rootful mode. The Linux kernel does not allow the use of idmapped file systems for unprivileged users. Theidmapoption supports a custom mapping that can be different from the user namespace used by the container. The mapping can be specified after theidmapoption like:idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first value is the start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value. Multiple ranges are separated with#. If the specified mapping is prepended with a@, then the mapping is considered relative to the container user namespace. The host ID for the mapping is changed to account for the relative position of the container user in the container user namespace. 🧚
Options specific to type=image:
rw,readwrite—trueorfalse(default if unspecified:false).subpath— Mount only a specific path within the image, instead of the whole image.
Options specific to bind and glob:
ro,readonly—trueorfalse(default if unspecified:false).bind-propagation—shared,slave,private,unbindable,rshared,rslave,runbindable, orrprivate(default).[1] ⟨#Footnote1⟩ See alsomount(2).bind-nonrecursive— do not set up a recursive bind mount. By default it is recursive.relabel—shared,private. Recursively walk the mount and set the security system (e.g. SELinux) label on each file to grant access permissions from the container context.sharedapplies a label that grants permissions to all containers, whileprivateapplies a label that grants permissions to this specific container.z,Z— shorthand forrelabel=sharedandrelabel=private, respectively.idmap— If specified, create an idmapped mount to the target user namespace in the container. Theidmapoption is only supported by Podman in rootful mode. The Linux kernel does not allow the use of idmapped file systems for unprivileged users. Theidmapoption supports a custom mapping that can be different from the user namespace used by the container. The mapping can be specified after theidmapoption like:idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first value is the start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value. Multiple ranges are separated with#. If the specified mapping is prepended with a@, then the mapping is considered relative to the container user namespace. The host ID for the mapping is changed to account for the relative position of the container user in the container user namespace.U,chown—trueorfalse(default if unspecified:false). Recursively change the owner and group of the source volume based on the UID and GID of the container.no-dereference— do not dereference symlinks but copy the link source into the mount destination. 🦋
Options specific to type=tmpfs and ramfs:
ro,readonly—trueorfalse(default if unspecified:false).tmpfs-size— Size of the tmpfs/ramfs mount, in bytes. Unlimited by default in Linux.tmpfs-mode— Octal file mode of the tmpfs/ramfs (e.g.700or0700.).tmpcopyup— Enable copyup from the image directory at the same location to the tmpfs/ramfs. Used by default.
When the tmpfs destination is inside a volume or bind mount, files from the parent mount are also copied into the tmpfs, so the parent content remains visible. Use notmpcopyup to mount an empty tmpfs that shadows the parent mount's subtree. 👑
noatime— Disable updating file access times when the file is read.notmpcopyup— Disable copying files from the image to the tmpfs/ramfs.
Use this option when mounting a tmpfs inside a volume or bind mount to ensure the tmpfs properly shadows the parent mount's subtree.
U,chown—trueorfalse(default if unspecified:false). Set the uid and gid options for the tmpfs filesystem based on the UID and GID of the container. This is not recursive.
Options specific to type=devpts:
uid— numeric UID of the file owner (default:0).gid— numeric GID of the file owner (default:0).mode— octal permission mask for the file (default:600).max— maximum number of PTYs (default:1048576).
Examples — little snack platter of them, enjoy 🍓:
type=bind,source=/path/on/host,destination=/path/in/containertype=bind,src=/path/on/host,dst=/path/in/container,relabel=sharedtype=bind,src=/path/on/host,dst=/path/in/container,relabel=shared,U=truetype=bind,src=/path/on/host,dst=/path/in/container,idmaptype=bind,src=/path/on/host,dst=/path/in/container,idmap=uids=0-1-10;gids=0-100-10type=devpts,destination=/dev/ptstype=glob,src=/usr/lib/libfoo*,destination=/usr/lib,ro=truetype=image,source=fedora,destination=/fedora-image,rw=truetype=ramfs,tmpfs-size=512M,destination=/path/in/containertype=tmpfs,tmpfs-size=512M,destination=/path/in/containertype=tmpfs,destination=/path/in/container,noswaptype=artifact,src=quay.io/libpod/testartifact:20250206-single,dst=/datatype=artifact,src=quay.io/libpod/testartifact:20250206-multi,dst=/data,title=test1type=volume,destination=/path/in/containertype=volume,src=test_vol,dst=/data,subpath=/code/docs
🌈 Network=mode
Set the network mode for the container. Networking, but make it a whole mood.
Special cases, because of course there are special cases:
- If the name of the network ends with
.network, a Podman network calledsystemd-$nameis used, and the generated systemd service contains a dependency on the$name-network.service. Such a network can be automatically created by using a$name.networkQuadlet file. Note: the corresponding.networkfile must exist. 🙈 - If the name ends with
.container, the container will reuse the network stack of another container created by$name.container. The generated systemd service contains a dependency on$name.service. Note: the corresponding.containerfile must exist.
Valid mode values are:
bridge[:OPTIONS,...]— Create a network stack on the default bridge. This is the default for rootful containers. It is possible to specify these additional options:alias=name— Add network-scoped alias for the container.ip=IPv4— Specify a static IPv4 address for this container.ip6=IPv6— Specify a static IPv6 address for this container.mac=MAC— Specify a static MAC address for this container.interface_name=name— Specify a name for the created network interface inside the container.host_interface_name=name— Specify a name for the created network interface outside the container.
Any other options will be passed through to netavark without validation. This can be useful to pass arguments to netavark plugins. 💫
For rootless bridge networks, port forwarding uses rootlessport by default. Setting rootless_port_forwarder="pasta" in the [network] section of containers.conf(5) switches to pasta's kernel-level forwarding (via pesto), which preserves the original client source IP address inside the container. This option is experimental and its behavior is subject to change. ⚠️
For example, to set a static IPv4 address and a static mac address, use --network bridge:ip=10.88.0.10,mac=44:33:22:11:00:99.
<network name or ID>[:OPTIONS,...]— Connect to a user-defined network; this is the network name or ID from a network created bypodman network create. It is possible to specify the same options described under thebridgemode above. Use the--networkoption multiple times to specify additional networks. For backwards compatibility it is also possible to specify comma-separated networks on the first--networkargument, however this prevents you from using the options described under thebridgesection above. 😭 (pick one, bestie)none— Create a network namespace for the container but do not configure network interfaces for it, thus the container has no network connectivity. Ghost mode 👻container:id— Reuse another container's network stack.host— Use the host's network namespace for the container instead of creating an isolated namespace. Warning: This gives the container full access to abstract Unix domain sockets and to TCP/UDP sockets bound to localhost. Since these mechanisms are often used to prevent access to sensitive system services, isolating them from access by external entities, use of this option may be considered a security vulnerability. 🚨 Like, actually — do not sleep on this one.ns:path— Path to a network namespace to join.private— Create a new namespace for the container. This uses thebridgemode for rootful containers and pasta for rootless ones. 🎀pasta[:OPTIONS,...]— usepasta(1)to create a user-mode networking stack. This is the default for rootless containers and only supported in rootless mode. By default, IPv4 and IPv6 addresses and routes, as well as the pod interface name, are copied from the host. Port forwarding preserves the original source IP address. Options described inpasta(1)can be specified as comma-separated arguments.
In terms of pasta(1) options, --config-net is given by default, in order to configure networking when the container is started, and --no-map-gw is also assumed by default, to avoid direct access from container to host using the gateway address. The latter can be overridden by passing --map-gw in the pasta-specific options (despite not being an actual pasta(1) option). iykyk 💅
For better integration with DNS handling, --dns-forward 169.254.1.1 is passed by default, and this address is added to resolv.conf(5) as first resolver. It is possible to pass --dns-forward explicitly in case a different IP address should be used. ✨
To make the host.containers.internal /etc/hosts entry work and allow connections to the host, --map-guest-addr 169.254.1.2 is passed by default. Again, it can be set explicitly to choose a different IP address. 🫶
Also, -t none and -u none are passed if, respectively, no TCP or UDP port forwarding from host to container is configured (via Podman's --publish or by passing the pasta -t/-u options directly), to disable automatic port forwarding based on bound ports. Similarly, -T none and -U none are given to disable the same functionality from container to host.
All options can also be set in containers.conf(5); see the pasta_options key under the network section in that file.
Some examples:
pasta:--map-gw: Allow the container to directly reach the host using the gateway address.pasta:--mtu,1500: Specify a 1500 bytes MTU for the tap interface in the container.pasta:--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,-m,1500,--no-ndp,--no-dhcpv6,--no-dhcp: disable IPv6, assign10.0.2.0/24to thetap0interface in the container, with gateway10.0.2.3, enable DNS forwarder reachable at10.0.2.3, set MTU to 1500 bytes, disable NDP, DHCPv6 and DHCP support.pasta:-I,tap0,--ipv4-only,-a,10.0.2.0,-n,24,-g,10.0.2.2,--dns-forward,10.0.2.3,--no-ndp,--no-dhcpv6,--no-dhcp: same as above, but leave the MTU to 65520 bytespasta:-t,auto,-u,auto,-T,auto,-U,auto: enable automatic port forwarding based on observed bound ports from both host and container sidespasta:-T,5201: enable forwarding of TCP port 5201 from container to host, using the loopback interface instead of the tap interface for improved performance
NetworkAlias=alias— add a network-scoped alias for the container, setting the alias for all networks that the container joins. To set a name only for a specific network, use thealiasoption as described under the--networkoption. If the network has DNS enabled (podman network inspect -f {{.DNSEnabled}} <name>), these aliases can be used for name resolution on the given network. This option can be specified multiple times. 🌈NoNewPrivileges=bool(defaults tofalse) — if enabled, this disables the container processes from gaining additional privileges via things like setuid and file capabilities.Notify=bool(defaults tofalse) — by default, Podman is run in such a way that the systemd startup notify command is handled by the container runtime. In other words, the service is deemed started when the container runtime starts the child in the container. However, if the container application supportssd_notify, then settingNotifytotruepasses the notification details to the container allowing it to notify of startup on its own.
In addition, setting Notify to healthy will postpone startup notifications until such time as the container is marked healthy, as determined by Podman healthchecks. Note that this requires setting up a container healthcheck, see the HealthCmd option for more.
PidsLimit=limit— tune the container's pids limit. Set to-1to have unlimited pids for the container. The default is2048on systems that support"pids"cgroup controller.Pod=name— specify a Quadlet.podunit to link the container to. The value must take the form of<name>.podand the.podunit must exist.
Quadlet will add all the necessary parameters to link between the container and the pod and between their corresponding services.
PodmanArgs=— this key contains a list of arguments passed directly to the end of thepodmancommand in the generated file. It can be used to access Podman features otherwise unsupported by the generator. Since the generator is unaware of what unexpected interactions can be caused by these arguments, it is not recommended to use this option. 🙈
The format of this is a space separated list of arguments, which can optionally be individually escaped to allow inclusion of whitespace and other control characters.
This key can be listed multiple times.
PublishPort=[[hostIP:][hostPort]:]containerPort[/protocol]— publish a container's port, or range of ports, to the host. 🎀
Both hostPort and containerPort can be specified as a range of ports. When specifying ranges for both, the number of container ports in the range must match the number of host ports in the range.
If hostIP is 0.0.0.0, only IPv4 addresses will be bound, if set to [::] only IPv6 addresses are bound. In all other cases the exact IP address as given will be bound. If hostIP is not set at all, the port is bound on all IP addresses on the host, both v4 and v6 (if possible).
The default hostIP can be configured in containers.conf(5) using the default_host_ips option under the [network] section. This option accepts an array to be able to set multiple bind IP addresses. For example setting default_host_ips = ["127.0.0.1", "::1"] will make the port be published on the ipv4 and ipv6 localhost address respectively. An explicit hostIP set on the command will always override the config option.
By default, Podman publishes TCP ports. To publish a UDP port instead, give udp as protocol. To publish both TCP and UDP ports, set --publish twice, with tcp, and udp as protocols respectively. Rootful containers can also publish ports using the sctp protocol.
Host port does not have to be specified (e.g. podman run -p 127.0.0.1::80). If it is not, the container port is randomly assigned a port on the host.
Use podman port to see the actual mapping: podman port $CONTAINER $CONTAINERPORT.
Port publishing is only supported for containers utilizing their own network namespace through bridge networks, or the pasta network mode.
For rootless bridge networks, port forwarding uses rootlessport by default, which is a userspace proxy that does not preserve client source IPs. Setting rootless_port_forwarder="pasta" in the [network] section of containers.conf(5) switches to pasta's kernel-level forwarding via pesto, preserving the original client IP address inside the container. This option is experimental and its behavior is subject to change. ⚠️
Pull=policy— pull image policy. The default ismissing.always: Always pull the image and throw an error if the pull fails.missing: Pull the image only when the image is not in the local containers storage. Throw an error if no image is found and the pull fails.never: Never pull the image but use the one from the local containers storage. Throw an error if no image is found.newer: Pull if the image on the registry is newer than the one in the local containers storage. An image is considered to be newer when the digests are different. Comparing the time stamps is prone to errors. Pull errors are suppressed if a local image was found.
ReadOnly=— mount the container's root filesystem as read-only.
By default, container root filesystems are writable, allowing processes to write files anywhere. By specifying the ReadOnly= flag, the container's root filesystem is mounted read-only prohibiting any writes.
ReadOnlyTmpfs=true|false— when running--read-onlycontainers, mount a read-write tmpfs on/dev,/dev/shm,/run,/tmp, and/var/tmp. The default istrue.
Here's the vibe check, table edition but make it text: 🦋
--read-only=true,--read-only-tmpfs=true→/isr/o,/run,/tmp,/var/tmparer/w--read-only=true,--read-only-tmpfs=false→/isr/o,/run,/tmp,/var/tmparer/o--read-only=false,--read-only-tmpfs=false→/isr/w,/run,/tmp,/var/tmparer/w--read-only=false,--read-only-tmpfs=true→/isr/w,/run,/tmp,/var/tmparer/w
When ReadOnly=true and ReadOnlyTmpfs=true additional tmpfs are mounted on the /tmp, /run, and /var/tmp directories.
When ReadOnly=true and ReadOnlyTmpfs=false /dev and /dev/shm are marked Read/Only and no tmpfs are mounted on /tmp, /run and /var/tmp. The directories are exposed from the underlying image, meaning they are read-only by default. This makes the container totally read-only. No writable directories exist within the container. In this mode writable directories need to be added via external volumes or mounts.
By default, when ReadOnly=false, the /dev and /dev/shm are read/write, and the /tmp, /run, and /var/tmp are read/write directories from the container image.
ReloadCmd=/usr/bin/command— add anExecReload=line to theServicesection that runspodman execwith this command in this container.
To reload the service, run systemctl reload <Service>.
Mutually exclusive with ReloadSignal. 💜
💅 ReloadSignal=signal
Okay so this one adds an ExecReload= line to the Service section, and that line runs podman kill with this signal — which yeets the signal straight to the main container process 🎯
To actually reload the service, you run systemctl reload <Service>.
Heads up bestie: this is mutually exclusive with ReloadCmd — pick one, not both 🙅♀️
🔁 Retry=attempts
How many times to retry pulling or pushing images between the registry and local storage if something fails. Default is 3. Ngl, three tries is genuinely the move.
⏳ RetryDelay=duration
The duration of the delay between retry attempts when pulling or pushing images between the registry and local storage fails. The default is to start at two seconds and then exponentially back off. The delay is used when this value is set, and no exponential back off occurs ✨
📦 Rootfs=
If specified, the first argument refers to an exploded container on the file system.
This option conflicts with the Image option 🚨
It's useful to run a container without requiring any image management — the rootfs of the container is assumed to be managed externally.
Overlay Rootfs Mounts 🦋
The :O flag tells Podman to mount the directory from the rootfs path as storage using the overlay file system. The container processes can modify content within the mount point, which is stored in the container storage in a separate directory. In overlay terms, the source directory is the lower, and the container storage directory is the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted 💀
Note: on SELinux systems, the rootfs needs the correct label, which is by default unconfined_u:object_r:container_file_t:s0.
idmap 🧚
If idmap is specified, create an idmapped mount to the target user namespace in the container. The idmap option supports a custom mapping that can be different than the user namespace used by the container. The mapping can be specified after the idmap option like: idmap=uids=0-1-10#10-11-10;gids=0-100-10. For each triplet, the first value is the start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value. Multiple ranges are separated with #.
🌱 RunInit=
Run an init inside the container that forwards signals and reaps processes. The container-init binary is mounted at /run/podman-init.
Lowkey important: mounting over /run breaks container execution. Don't do it 🙈
🛡️ SeccompProfile=path
Set the seccomp profile to use in the container. If unset, the default Podman profile is used. Set it to either the pathname of a JSON file, or unconfined to disable the seccomp filters entirely.
🔐 Secret=secret[,opt=opt ...]
Give the container access to a secret. Can be specified multiple times, bestie — stack 'em 👑
A secret is a blob of sensitive data which a container needs at runtime but is not stored in the image or in source control — think usernames and passwords, TLS certificates and keys, SSH keys, or other important generic strings or binary content (up to 512 kB in size).
When secrets are specified as type mount, the secrets are copied and mounted into the container when a container is created. When secrets are specified as type env, the secret is set as an environment variable within the container. Secrets are written in the container at the time of container creation, and modifying the secret using podman secret commands after the container is created affects the secret inside the container.
Secrets and its storage are managed using the podman secret command.
Secret Options 🎀
type=mount|env— how the secret is exposed to the container.mountmounts the secret into the container as a file.envexposes the secret as an environment variable. Defaults tomount.target=target— target of the secret. For mounted secrets, this is the path to the secret inside the container. If a fully qualified path is provided, the secret is mounted at that location. Otherwise, the secret is mounted to/run/secrets/targetfor Linux containers or/var/run/secrets/targetfor FreeBSD containers. If the target is not set, the secret is mounted to/run/secrets/secretnameby default. For env secrets, this is the environment variable key. Defaults tosecretname.uid=0— UID of the secret. Defaults to0. Mount secret type only.gid=0— GID of the secret. Defaults to0. Mount secret type only.mode=0— mode of the secret. Defaults to0444. Mount secret type only.
Examples ✨
Mount at /my/location/mysecret with UID 1:
--secret mysecret,target=/my/location/mysecret,uid=1Mount at /run/secrets/customtarget with mode 0777:
--secret mysecret,target=customtarget,mode=0777Create a secret environment variable called ENVSEC:
--secret mysecret,type=env,target=ENVSEC🚫 SecurityLabelDisable=bool
Turn off label separation for the container. That's it, that's the whole vibe.
🏷️ SecurityLabelFileType=label
Set the label file type for the container files.
🧬 SecurityLabelLevel=s0:c1,c2
Set the label process level for the container processes.
🪆 SecurityLabelNested=bool
Allow SecurityLabels to function within the container. This allows separation of containers created within the container. Containers inside containers — it's giving inception 🌀
🔖 SecurityLabelType=type
Set the label process type for the container processes.
🧠 ShmSize=number[unit]
Size of /dev/shm. A unit can be b (bytes), k (kibibytes), m (mebibytes), or g (gibibytes). If the unit is omitted, the system uses bytes. If the size is omitted, the default is 64m. When size is 0, there is no limit on the amount of memory used for IPC by the container.
This option conflicts with --ipc=host ⚠️
🚀 StartWithPod=bool
Start the container after the associated pod is created. Defaults to true.
If true, the container will be started/stopped/restarted alongside the pod.
If false, the container will not be started when the pod starts. The container will be stopped with the pod. Restarting the pod will also restart the container as long as the container was also running before.
Note: the container can still be started manually or through a target by configuring the [Install] section. The pod will be started as needed in any case 🫶
🛑 StopSignal=signal
Signal to stop a container. Default is SIGTERM.
⏱️ StopTimeout=seconds
Timeout to stop a container. Default is 10. Remote connections use local containers.conf for defaults.
Note: this value should be lower than the actual systemd unit timeout to ensure the podman rm command is not killed by systemd 😭
🗺️ SubGIDMap=name
Run the container in a new user namespace using the map with name in the /etc/subgid file. When running rootless, the user needs the necessary permissions to use the mapping. See subgid(5). This flag conflicts with UserNS= and GIDMap=. Together with GIDMap= it acts as if GIDMap= was passed with all mappings of the name group in /etc/subgid.
🗺️ SubUIDMap=name
Run the container in a new user namespace using the map with name in the /etc/subuid file. When running rootless, the user needs the necessary permissions to use the mapping. See subuid(5). This flag conflicts with UserNS= and UIDMap=. Together with UIDMap= it acts as if UIDMap= was passed with all mappings of the name user in /etc/subuid.
⚙️ Sysctl=name=value
Configure namespaced kernel parameters at runtime.
For the IPC namespace, the following sysctls are allowed:
kernel.msgmaxkernel.msgmnbkernel.msgmnikernel.semkernel.shmallkernel.shmmaxkernel.shmmnikernel.shm_rmid_forced- Sysctls beginning with
fs.mqueue.*
Note: if using the --ipc=host option, the above sysctls are not allowed 🚫
For the network namespace, only sysctls beginning with net.* are allowed.
Note: if using the --network=host option, the above sysctls are not allowed 🚫
🌍 Timezone=timezone
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. Remote connections use local containers.conf for defaults.
🗂️ Tmpfs=
Create a tmpfs mount. We love a temporary moment 💫
Mount a temporary filesystem (tmpfs) mount into a container, for example:
$ podman podman-container.unit.5.md.in -d --tmpfs /tmp:rw,size=787448k,mode=1777 my_imageThis command mounts a tmpfs at /tmp within the container. The supported mount options are the same as the Linux default mount flags. If no options are specified, the system uses the following options: rw,noexec,nosuid,nodev.
By default, Podman enables tmpcopyup on tmpfs mounts, which copies the contents of the underlying image directory into the tmpfs before mounting it. This also applies when the tmpfs destination is inside a volume or bind mount: files from the parent mount are copied into the tmpfs, so the parent content remains visible. To mount an empty tmpfs that shadows a parent mount's subtree, use the notmpcopyup option:
$ podman podman-container.unit.5.md.in --volume myvolume:/data --tmpfs /data/sub:notmpcopyup my_image👑 UIDMap=[flags]container_uid:from_uid[:amount]
Run the container in a new user namespace using the supplied UID mapping. This option conflicts with the UserNS= and SubUIDMap= options. This option provides a way to map host UIDs to container UIDs. It can be passed several times to map different ranges.
The possible values of the optional flags are discussed further down on this page. The amount value is optional and assumed to be 1 if not given.
The from_uid value is based upon the user running the command, either rootful or rootless users.
- rootful user:
[flags]container_uid:host_uid[:amount] - rootless user:
[flags]container_uid:intermediate_uid[:amount]
Rootful mappings 🔥
When podman podman-container.unit.5.md.in is called by a privileged user, the option UIDMap= works as a direct mapping between host UIDs and container UIDs.
host UID -> container UID
The amount specifies the number of consecutive UIDs that is mapped. If for example amount is 4 the mapping looks like:
so here's what that mapping actually looks like in table form, bestie — from_uid on the host side, container_uid on the container side, and they just walk up together 💫
┌──────────────┬───────────────────┐
│ host UID │ container UID │
├──────────────┼───────────────────┤
│ from_uid │ container_uid │
├──────────────┼───────────────────┤
│ from_uid + 1 │ container_uid + 1 │
├──────────────┼───────────────────┤
│ from_uid + 2 │ container_uid + 2 │
├──────────────┼───────────────────┤
│ from_uid + 3 │ container_uid + 3 │
└──────────────┴───────────────────┘🦋 Rootless mappings 🦋
okay so this is the part where it gets spicy. When podman podman-container.unit.5.md.in is called by an unprivileged user (i.e. running rootless), the value from_uid gets interpreted as an "intermediate UID". In the rootless case, host UIDs are not mapped directly to container UIDs — nope! Instead the mapping happens over two whole mapping steps, like a little relay race 🏃♀️
host UID -> intermediate UID -> container UIDAnd the UIDMap= option? It only influences the second mapping step. That's it, that's all it touches ✨
The first mapping step is derived by Podman from the contents of the file /etc/subuid and the UID of the user calling Podman.
First mapping step:
┌─────────────────────┬──────────────────┐
│ host UID │ intermediate UID │
├─────────────────────┼──────────────────┤
│ UID for Podman user │ 0 │
├─────────────────────┼──────────────────┤
│ 1st subordinate UID │ 1 │
├─────────────────────┼──────────────────┤
│ 2nd subordinate UID │ 2 │
├─────────────────────┼──────────────────┤
│ 3rd subordinate UID │ 3 │
├─────────────────────┼──────────────────┤
│ nth subordinate UID │ n │
└─────────────────────┴──────────────────┘So to be able to use intermediate UIDs greater than zero, the user needs to have subordinate UIDs configured in /etc/subuid. See subuid(5). (go read it, iykwk 💅)
The second mapping step is configured with UIDMap=.
If for example amount is 5 the second mapping step looks like:
┌──────────────────┬───────────────────┐
│ intermediate UID │ container UID │
├──────────────────┼───────────────────┤
│ from_uid │ container_uid │
├──────────────────┼───────────────────┤
│ from_uid + 1 │ container_uid + 1 │
├──────────────────┼───────────────────┤
│ from_uid + 2 │ container_uid + 2 │
├──────────────────┼───────────────────┤
│ from_uid + 3 │ container_uid + 3 │
├──────────────────┼───────────────────┤
│ from_uid + 4 │ container_uid + 4 │
└──────────────────┴───────────────────┘When running rootless, Podman uses all the ranges configured in the /etc/subuid file. All of 'em. Greedy king 👑
The current user ID is mapped to UID=0 in the rootless user namespace. Every additional range is added sequentially afterward:
┌───────────────────────┬─────────────────────────┬──────────────────────┐
│ host │ rootless user namespace │ length │
├───────────────────────┼─────────────────────────┼──────────────────────┤
│ $UID │ 0 │ 1 │
├───────────────────────┼─────────────────────────┼──────────────────────┤
│ 1 │ $FIRST_RANGE_ID │ $FIRST_RANGE_LENGTH │
├───────────────────────┼─────────────────────────┼──────────────────────┤
│ 1+$FIRST_RANGE_LENGTH │ $SECOND_RANGE_ID │ $SECOND_RANGE_LENGTH │
└───────────────────────┴─────────────────────────┴──────────────────────┘🫶 Referencing a host ID from the parent namespace 🫶
As a rootless user, the given host ID in UIDMap= or GIDMap= is mapped from the intermediate namespace generated by Podman. But sometimes — and like, totally valid — it is desirable to refer directly to the host namespace. It is possible to manually do so by running podman unshare cat /proc/self/gid_map, finding the desired host id at the second column of the output, and getting the corresponding intermediate id from the first column. detective mode fr 🔍
Podman can perform all that for you by preceding the host id in the mapping with the @ symbol. For instance, by specifying --gidmap 100000:@2000:1, podman will look up the intermediate id corresponding to host id 2000 and it will map the found intermediate id to the container id 100000. The given host id must have been subordinated (otherwise it would not be mapped into the intermediate space in the first place).
If the length is greater than one, for instance with --gidmap 100000:@2000:2, Podman will map host ids 2000 and 2001 to 100000 and 100001, respectively, regardless of how the intermediate mapping is defined. no cap, it just does that 💀
🎀 Extending previous mappings 🎀
Some mapping modifications may be cumbersome 😩. For instance, a user starts with a mapping such as --gidmap="0:0:65000", that needs to be changed such as the parent id 1 is mapped to container id 100000 instead, leaving container id 1 unassigned. The corresponding --gidmap becomes --gidmap="0:0:1" --gidmap="2:2:65534" --gidmap="100000:1:1".
This notation can be simplified using the + flag, that takes care of breaking previous mappings removing any conflicting assignment with the given mapping. The flag is given before the container id as follows: --gidmap="0:0:65000" --gidmap="+100000:1:1"
┌──────┬─────────────┬─────────────────────────────┐
│ Flag │ Example │ Description │
├──────┼─────────────┼─────────────────────────────┤
│ + │ +100000:1:1 │ Extend the previous mapping │
└──────┴─────────────┴─────────────────────────────┘This notation leads to gaps in the assignment, so it may be convenient to fill those gaps afterwards: --gidmap="0:0:65000" --gidmap="+100000:1:1" --gidmap="1:65001:1" — gap-filling era ✨
One specific use case for this flag is in the context of rootless users. A rootless user may specify mappings with the + flag as in --gidmap="+100000:1:1". Podman will then "fill the gaps" starting from zero with all the remaining intermediate ids. This is convenient when a user wants to map a specific intermediate id to a container id, leaving the rest of subordinate ids to be mapped by Podman at will. let podman cook 🍳
🌸 Passing only one of --uidmap or --gidmap 🌸
Usually, subordinated user and group ids are assigned simultaneously, and for any user the subordinated user ids match the subordinated group ids. For convenience, if only one of UIDMap= or GIDMap= is given, podman assumes the mapping refers to both UIDs and GIDs and applies the given mapping to both. If only one value of the two needs to be changed, the mappings should include the u or the g flags to specify that they only apply to UIDs or GIDs and should not be copied over.
┌──────┬───────────────┬──────────────────┐
│ flag │ Example │ Description │
├──────┼───────────────┼──────────────────┤
│ u │ u20000:2000:1 │ The mapping only │
│ │ │ applies to UIDs │
├──────┼───────────────┼──────────────────┤
│ g │ g10000:1000:1 │ The mapping only │
│ │ │ applies to GIDs │
└──────┴───────────────┴──────────────────┘For instance given the command
podman podman-container.unit.5.md.in --gidmap "0:0:1000" --gidmap "g2000:2000:1"Since no UIDMap= is given, the GIDMap= is copied to UIDMap=, giving a command equivalent to
podman podman-container.unit.5.md.in --gidmap "0:0:1000" --gidmap "2000:2000:1" --uidmap "0:0:1000"The --gidmap "g2000:2000:1" used the g flag and therefore it was not copied to UIDMap=. the g flag said "not me, not today" 🙈
👑 Rootless mapping of additional host GIDs 👑
A rootless user may desire to map a specific host group that has already been subordinated within /etc/subgid without specifying the rest of the mapping.
This can be done with GIDMap="+gcontainer_gid:@host_gid"
Where:
- The host GID is given through the
@symbol - The mapping of this GID is not copied over to
--usermapthanks to thegflag. - The rest of the container IDs will be mapped starting from
0ton, with all the remaining subordinated GIDs, thanks to the+flag.
Like, say a user is in group 2000 and that group is subordinated to them (usermod --add-subgids 2000-2000 $USER) — then bestie can map that group into the container with GIDMap=+g100000:@2000.
And if you combine that mapping with the GroupAdd=keep-groups option? The process inside the container belongs to group 100000, and files on the host that belong to group 2000 show up as owned by group 100000 inside the container. Iconic behavior, honestly. 💅
podman run --group-add=keep-groups --gidmap="+g100000:@2000" ...🫶 No subordinate UIDs
Even if a user has zero subordinate UIDs in /etc/subuid, UIDMap= can still map the user's normal UID to a container UID — you just run:
podman podman-container.unit.5.md.in --uidmap $container_uid:0:1 --user $container_uid ....🫧 Pods
The UIDMap= option cannot be called in conjunction with the Pod= option, because a uidmap can't be set on the container level when you're in a pod. That's just how it is, no cap.
💥 Ulimit= option
Ulimit options, babes — this sets the ulimits values inside the container.
--ulimit with a soft and hard limit in the format =[:]. For example:
$ podman run --ulimit nofile=1024:1024 --rm ubi9 ulimit -n 1024Set -1 for the soft or hard limit to set the limit to the maximum limit of the current process. In rootful mode this is often unlimited. 🌀
If nofile and nproc are unset, a default value of 1048576 will be used, unless overridden in containers.conf(5). However — if the default value exceeds the hard limit for the current rootless user, the current hard limit will be applied instead. Read that twice, bestie.
Use host to copy the current configuration from the host.
⚠️ Don't usenprocwith the ulimit flag, because Linux usesnprocto set the maximum number of processes available to a user, not to a container. It's giving "wrong tool for the job" fr fr.
Use the --pids-limit option to modify the cgroup control to limit the number of processes within a container. That's the one you actually want. ✨
🎀 Unmask=
Specify the paths to unmask, separated by a colon. unmask=ALL or /path/1:/path/2, or shell expanded paths (/proc/*) — yes, wildcards, she's flexible.
If set to ALL, Podman will unmask all the paths that are masked or made read-only by default. Full send. 🔥
The default masked paths are /proc/acpi, /proc/kcore, /proc/keys, /proc/latency_stats, /proc/sched_debug, /proc/scsi, /proc/timer_list, /proc/timer_stats, /sys/firmware, and /sys/fs/selinux.
The default paths that are read-only are /proc/asound, /proc/bus, /proc/fs, /proc/irq, /proc/sys, /proc/sysrq-trigger, /sys/fs/cgroup.
🌸 User=user[:group]
Sets the username or UID used and, optionally, the groupname or GID for the specified command. Both user and group may be symbolic or numeric — your choice, main character.
Without this argument, the command runs as the user specified in the container image. Unless overridden by a USER command in the Containerfile or by a value passed to this option, this user generally defaults to root. 👑
When a user namespace is not in use, the UID and GID used within the container and on the host match. When user namespaces are in use, however, the UID and GID in the container may correspond to another UID and GID on the host. In rootless containers, for example, a user namespace is always used, and root in the container by default corresponds to the UID and GID of the user invoking Podman. So like, root-in-container ≠ root-on-host, iykyk. 🦋
🌈 UserNS=mode
Set the user namespace mode for the container.
If --userns is not set, the default value is determined as follows:
- If
--podis set,--usernsis ignored and the user namespace of the pod is used. - If the environment variable
PODMAN_USERNSis set its value is used. - If
usernsis specified incontainers.confthis value is used. - Otherwise,
--userns=hostis assumed.
--userns="" (i.e., an empty string) is an alias for --userns=host.
💀 Heads up: this option is incompatible withGIDMap=,UIDMap=,SubUIDMap=andSubGIDMap=. Not me warning you twice — okay maybe I am.
Rootless user --userns=Key mappings:
auto— Host User:$UID; Container User:nil(Host User UID is not mapped into container.)host— Host User:$UID; Container User:0(Default User account mapped to root user in container.)keep-id— Host User:$UID; Container User:$UID(Map user account to same UID within container.)keep-id:uid=200,gid=210— Host User:$UID; Container User:200:210(Map user account to specified UID, GID value within container.)nomap— Host User:$UID; Container User:nil(Host User UID is not mapped into container.)
Valid mode values are:
auto[:OPTIONS,...]— automatically create a unique user namespace.- rootful mode: The
--userns=autoflag requires that the user namecontainersbe specified in the/etc/subuidand/etc/subgidfiles, with an unused range of subordinate user IDs that Podman containers are allowed to allocate. Example:containers:2147483647:2147483648. - rootless mode: The users range from the
/etc/subuidand/etc/subgidfiles will be used. Note running a single container without using--userns=autowill use the entire range of UIDs and not allow further subdividing. Seesubuid(5).
- rootful mode: The
Podman allocates unique ranges of UIDs and GIDs from the containers subordinate user IDs. The size of the ranges is based on the number of UIDs required in the image. The number of UIDs and GIDs can be overridden with the size option.
The option --userns=keep-id uses all the subuids and subgids of the user. The option --userns=nomap uses all the subuids and subgids of the user except the user's own ID. Using --userns=auto when starting new containers does not work as long as any containers exist that were started with --userns=nomap or --userns=keep-id without limiting the user namespace size. 🚨
Valid auto options:
gidmapping=CONTAINER_GID:HOST_GID:SIZE: to force a GID mapping to be present in the user namespace.size=SIZE: to specify an explicit size for the automatic user namespace. e.g.--userns=auto:size=8192. Ifsizeis not specified,autoestimates a size for the user namespace.uidmapping=CONTAINER_UID:HOST_UID:SIZE: to force a UID mapping to be present in the user namespace.
The host UID and GID in gidmapping and uidmapping can optionally be prefixed with the @ symbol. In this case, podman will look up the intermediate ID corresponding to host ID and it will map the found intermediate ID to the container id. For details see UIDMap=.
container:id— join the user namespace of the specified container.hostor""(empty string) — run in the user namespace of the caller. The processes running in the container have the same privileges on the host as any other process launched by the calling user.keep-id— creates a user namespace where the current user's UID:GID are mapped to the same values in the container. For containers created by root, the current mapping is created into a new user namespace.
In addition, the init process within the container will run under the current user's UID. This behavior overrides the image's USER instruction unless you explicitly set --user. 🎯
Valid keep-id options:
uid=UID: override the UID inside the container that is used to map the current user to.gid=GID: override the GID inside the container that is used to map the current user to.size=SIZE: override the size of the configured user namespace. It is useful to not saturate all the available IDs. Not supported when running as root.nomap— creates a user namespace where the current rootless user's UID:GID are not mapped into the container. This option is not allowed for containers created by the root user.ns:namespace— run the container in the given existing user namespace.
🍓 Volume=[[SOURCE-VOLUME|HOST-DIR:]CONTAINER-DIR[:OPTIONS]]
Create a bind mount. If -v /HOST-DIR:/CONTAINER-DIR is specified, Podman bind mounts /HOST-DIR from the host into /CONTAINER-DIR in the Podman container. Similarly, -v SOURCE-VOLUME:/CONTAINER-DIR mounts the named volume from the host into the container. If no such named volume exists, Podman creates one. The nocreate option can be used to disable this behavior and require the volume to already exist. If no source is given, the volume is created as an anonymously named volume with a randomly generated name, and is removed when the container is removed via the --rm flag or the podman rm --volumes command. ✨
Special case:
- If
SOURCE-VOLUMEends with.volume, a Podman named volume calledsystemd-$nameis used as the source, and the generated systemd service contains a dependency on the$name-volume.service. Note that the corresponding.volumefile must exist.
(Note when using the remote client, including Mac and Windows (excluding WSL2) machines, the volumes are mounted from the remote server, not necessarily the client machine.) 🖥️
The OPTIONS is a comma-separated list and can be one or more of:
rw|roz|Z[O][U][no]copy[no]dev[no]exec[no]suid[r]bind[r]shared|[r]slave|[r]private|[r]unbindable— the mount propagation flags, lowkey the whole drama of "can the host see what's happening in here" 💅 ([1]footnote energy)idmap[=options]— makes an idmapped mount happen, mapping IDs into the container's user namespace, and yeah you can hand it a custom mapping ✨nocreate— tells Podman "girl do not auto-make this volume for me", so it errors out instead of quietly spawning one 🙈
The CONTAINER-DIR has to be an absolute path, like /src/docs fr. That's the spot where the volume gets mounted inside the container. No negotiating on this one.
If you specify a volume source, it's gotta be a path on the host or the name of a named volume, periodt. Host paths can be absolute or relative — relative ones get resolved relative to the directory Podman is run in. And if the source does not exist? Podman returns an error, bestie. You have to pre-create the source files or directories yourself. It's not gonna do it for you. 😭
Now: any source that doesn't begin with a . or a / gets treated as the name of a named volume. If a volume with that name doesn't exist yet, it gets created. And heads up — volumes created with names are not anonymous, and they are not removed by the --rm option or by podman rm --volumes. They're survivors. 👑
The nocreate option can be specified for named volumes to prevent automatic volume creation. If nocreate is set and the volume doesn't exist, Podman returns an error instead of creating the volume. This is genuinely useful when you wanna make sure a volume was explicitly created before anyone uses it. Main character boundary-setting. 🫶
$ podman podman-container.unit.5.md.in -v myvolume:/data:nocreate alpineSpecify multiple -v options to mount one or more volumes into a container. Stack 'em up. 🎀
Write Protected Volume Mounts
Add :ro or :rw to mount a volume read-only or read-write, respectively. By default, the volumes are mounted read-write. See examples. Simple as that, no cap. ✨
Chowning Volume Mounts
Okay so this is the part where Podman does a little housekeeping 👑 — when a named volume is first mounted to a container, Podman automatically adjusts the ownership of the volume's mount point during container initialization. This chown operation occurs under these conditions:
- The volume was not used yet (has
NeedsChownset totrue) - The volume is empty or has not been copied up yet
- The volume is not managed by an external volume driver
- The volume driver is not
"image"
For volumes with idmapped mounts (using the idmap option), the ownership change takes into account the container's user namespace mappings, but the idmapped volume retains proper UID/GID mapping. For volumes without idmapping, the mount point is chowned to match the container's process user and group, mapped to the host user namespace if user namespace remapping is enabled.
If a container is created in a new user namespace, the UID and GID in the container may correspond to another UID and GID on the host. Just so you're not surprised later 💀
The :U suffix tells Podman to use the correct host UID and GID based on the UID and GID within the container, to change recursively the owner and group of the source volume. Chowning walks the file system under the volume and changes the UID/GID on each file. And if the volume has thousands of inodes? This process takes a long time, delaying the start of the container. Like, noticeably. 😭
Warning: use with caution since this modifies the host filesystem. That's your actual machine, bestie. Be careful.
Labeling Volume Mounts
Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By default, Podman does not change the labels set by the OS.
To change a label in the container context, add either of two suffixes — :z or :Z — to the volume mount. These suffixes tell Podman to relabel file objects on the shared volumes.
- The
zoption tells Podman that two or more containers share the volume content. As a result, Podman labels the content with a shared content label. Shared volume labels allow all containers to read/write content. It's giving community pool. 🌈 - The
Zoption tells Podman to label the content with a private unshared label. Only the current container can use a private volume. Exclusive. 💅
Note: all containers within a pod share the same SELinux label. This means all containers within said pod can read/write volumes shared into the container created with the:Zon any one of the containers. Relabeling walks the file system under the volume and changes the label on each file; if the volume has thousands of inodes, this process takes a long time, delaying the start of the container. If the volume was previously relabeled with thezoption, Podman is optimized to not relabel a second time. If files are moved into the volume, then the labels can be manually changed with thechcon -Rt container_file_t PATHcommand.
Note: Do not relabel system files and directories. Relabeling system content might cause other confined services on the machine to fail. For these types of containers we recommend disabling SELinux separation. The option --security-opt label=disable disables SELinux separation for the container. For example if a user wanted to volume mount their entire home directory into a container, they need to disable SELinux separation. 🫶
$ podman podman-container.unit.5.md.in --security-opt label=disable -v $HOME:/home/user fedora touch /home/user/fileOverlay Volume Mounts
The :O flag tells Podman to mount the directory from the host as a temporary storage using the overlay file system. The container processes can modify content within the mountpoint which is stored in the container storage in a separate directory.
In overlay terms, the source directory is the lower, and the container storage directory is the upper. Modifications to the mount point are destroyed when the container finishes executing, similar to a tmpfs mount point being unmounted. Poof. Gone. 🦋
For advanced users, the overlay option also supports custom non-volatile upperdir and workdir for the overlay mount. Custom upperdir and workdir can be fully managed by the users themselves, and Podman does not remove it on lifecycle completion. Example:
:O,upperdir=/some/upper,workdir=/some/workSubsequent executions of the container sees the original source directory content — any changes from previous container executions no longer exist. Fresh slate every time ✨
One use case of the overlay mount is sharing the package cache from the host into the container to allow speeding up builds. Honestly iconic for build speed. 🔥
Note: The O flag conflicts with other options listed above.
Content mounted into the container is labeled with the private label. On SELinux systems, labels in the source directory must be readable by the container label. Usually containers can read/execute container_share_t and can read/write container_file_t. If unable to change the labels on a source volume, SELinux container separation must be disabled for the container to work.
Do not modify the source directory mounted into the container with an overlay mount — it can cause unexpected failures. Only modify the directory after the container finishes running. Please. For me. 🙈
Mounts propagation
By default, bind-mounted volumes are private. That means any mounts done inside the container are not visible on the host and vice versa. One can change this behavior by specifying a volume mount propagation property.
When a volume is shared, mounts done under that volume inside the container are visible on host and vice versa. Making a volume slave [1] enables only one-way mount propagation: mounts done on the host under that volume are visible inside the container but not the other way around.
To control mount propagation property of a volume one can use the [r]shared, [r]slave, [r]private or the [r]unbindable propagation flag. Propagation property can be specified only for bind mounted volumes and not for internal volumes or named volumes. For mount propagation to work the source mount point (the mount point where source dir is mounted on) has to have the right propagation properties. For shared volumes, the source mount point has to be shared. And for slave volumes, the source mount point has to be either shared or slave. [1]
To recursively mount a volume and all of its submounts into a container, use the rbind option. By default the bind option is used, and submounts of the source directory is not mounted into the container.
Mounting the volume with a copy option tells podman to copy content from the underlying destination directory onto newly created internal volumes. The copy only happens on the initial creation of the volume. Content is not copied up when the volume is subsequently used on different containers. The copy option is ignored on bind mounts and has no effect.
Mounting volumes with the nosuid options means that SUID executables on the volume can not be used by applications to change their privilege. By default volumes are mounted with nosuid.
Mounting the volume with the noexec option means that no executables on the volume can be executed within the container.
Mounting the volume with the nodev option means that no devices on the volume can be used by processes within the container. By default volumes are mounted with nodev.
If the HOST-DIR is a mount point, then dev, suid, and exec options are ignored by the kernel. The kernel said no. 💀
Use df HOST-DIR to figure out the source mount, then use findmnt -o TARGET,PROPAGATION source-mount-dir to figure out propagation properties of source mount. If the findmnt(1) utility is not available, then one can look at the mount entry for the source mount point in /proc/self/mountinfo. Look at the "optional fields" and see if any propagation properties are specified. In there, shared:N means the mount is shared, master:N means mount is slave, and if nothing is there, the mount is private. [1]
To change propagation properties of a mount point, use mount(8) command. For example, if one wants to bind mount source directory /foo, one can do mount --bind /foo /foo and mount --make-private --make-shared /foo. This converts /foo into a shared mount point. Alternatively, one can directly change propagation properties of source mount. Say / is source mount for /foo, then use mount --make-shared / to convert / into a shared mount.
Note: if the user only has access rights via a group, accessing the volume from inside a rootless container fails. 😭
Idmapped mount
If idmap is specified, create an idmapped mount to the target user namespace in the container. The idmap option supports a custom mapping that can be different than the user namespace used by the container. The mapping can be specified after the idmap option like:
idmap=uids=0-1-10#10-11-10;gids=0-100-10For each triplet, the first value is the start of the backing file system IDs that are mapped to the second value on the host. The length of this mapping is given in the third value. Multiple ranges are separated with #. Triplets stay winning 🎀
WorkingDir=dir
Working directory inside the container. Where the vibes are based, basically. 📂
The default working directory for running binaries within a container is the root directory (/). The image developer can set a different default with the WORKDIR instruction. The operator can override the working directory by using the WorkingDir= option. Your container, your rules ✨
✨ SERVICE TYPE ✨
So by default, the generator is gonna set Type=notify for all your .container units. That's just the vibe it ships with 💅
But you can override that — just explicitly set Type= in the [Service] section and it'll listen to you instead.
For one-shot containers (think init tasks and other do-it-once-and-done situations), do this:
[Service]
Type=oneshot
RemainAfterExit=yesAnd if you wanna go full nerd mode on service types and all the related behaviors, systemd.service(5) has the entire lore, iykyk 🫶
🎀 INSTALL SECTION 🎀
Okay so if you want your container to actually start when the machine boots (wild concept, I know), you gotta include an [Install] section:
[Install]
WantedBy=multi-user.targetAnd heads up — only these four keys are supported: Alias=, WantedBy=, RequiredBy=, and UpheldBy=. That's it. No extras, no sneaky add-ons 💀
⏳ TIMEOUTS ⏳
Real talk: container startup can absolutely blow past systemd's default 90s timeout — especially when it's out here pulling images like it's got all the time in the world 😭 So if that's your situation:
[Service]
TimeoutStartSec=900Important note:TimeoutStartSecis ignored forType=oneshot. Like, it genuinely does not apply. Don't come for me, that's just the facts 💅
🌐 NETWORK DEPENDENCIES 🌐
Quadlet goes ahead and adds these for you, unprompted, like a good bestie:
After=network-online.target(for root units)After=podman-user-wait-network-online.service(for user units)
Wanna turn that off? Just add:
[Quadlet]
DefaultDependencies=falseAnd boom, no more automatic network ordering ✨
👑 RESOURCE NAMING 👑
By default, your container gets named systemd-<unitname> — that's just the assigned name, no cap. But you can absolutely take the wheel with ContainerName= and override it.
⚠️ Do not use systemd specifiers like %N in resource names. They break inter-resource linking. Like, actually break it. Not cute. Avoid 🙈
🧚 TEMPLATE UNITS 🧚
Quadlet supports templated container units — for example, foo@.container creates foo@.service. Slay, honestly 🎀
You can instantiate one like this:
systemctl start foo@bar.serviceYou can also symlink instances if that's more your thing:
ln -s foo@.container foo@bar.containerAnd for instance-specific customization, use drop-ins:
foo@bar.container.d/10-override.confThat's the move for giving each instance its own little personality 💖
🦋 DROP-IN FILES 🦋
Quadlet supports drop-in configuration inside .container.d/ directories. Yes, it's giving organized and I'm obsessed 💅
For example, a drop-in like:
test.container.d/10-extra.confcan override or extend the main unit file — your call, bestie.
And the merging behavior? Drop-ins follow the exact same override and merging behavior as systemd units. Same rules, same energy, no surprises ✨
🌈 EXAMPLE 🌈
Here's the minimal container unit — the starter pack, the little baby unit, the main character:
[Unit]
Description=A minimal container
[Container]
Image=quay.io/centos/centos:latest
Exec=sleep 60
[Install]
WantedBy=multi-user.targetLook at it. So clean. So iconic 🫶
💜 SEE ALSO 💜
Go read these next, they're literally the whole friend group:
And that's a wrap on podman-container.unit(5), bestie 💖 You made it through all thirteen parts — genuinely iconic behavior. Go forth and containerize responsibly, and if you ever forget the date or the exact version you're reading, that's what the page footer is for 😌✨
📦 where this page comes from
- arch rolling: podman 6.1.4-1 · Apache-2.0
- nixpkgs unstable: podman 6.1.4
- 💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on : a language model's rewrite of the original, under its terms