Podman volume mounts: When to use the :z or :Z suffix?

Question

The Podman man pages explains for volume mounts/binds:

Labeling systems like SELinux require that proper labels are placed on volume content mounted into a container. Without a label, the security system might prevent the processes running inside the container from using the content. By default, Podman does not change the labels set by the OS.

To change a label in the container context, you can add either of two suffixes :z or :Z to the volume mount. These suffixes tell Podman to relabel file objects on the shared volumes. The z option tells Podman that two containers share the volume content. As a result, Podman labels the content with a shared content label. Shared volume labels allow all containers to read/write content. The Z option tells Podman to label the content with a private unshared label.

The troubleshooting page explains the same thing with nearly the same words, however.

Now, being rather new to Podman and SELinux, wonder, what I actually should use when? I know, when I get permissions errors that they could be due to SELinux, so one of the two switches may fix that. But what are the differences between these two (lower-case z and upper-case Z) options?

The difference it says is:

• :z creates a shared content label
• :Z creates a private unshared label

This introduces many new words:

• shared and unshared (what does that mean?)
• ??? vs private (again, it’s not clear what this should say to me)
• also it says “content label” for one option, while the other one only says “label” – is there a difference between these two terms or is it the same?

So what do these words mean in this context? And the final question: When I should I use what?

Answer 1

“Shared” means that multiple containers can share the volume; “unshared” says that they can’t. In a little more detail, :z labels the volume inside each container with the appropriate label (container_file_t), and any given volume can be mounted inside multiple containers in parallel, and all running containers with the volume mount will have access to it. Any change made by the host, or any running container, will be visible to all running containers.

“Private” means that in addition, the label used inside the container will be private to that container. There’s no additional layering at the file system level, so this effectively means that the content is labelled privately even from the host’s perspective. Containers with the same mount can’t share their access to it — at least with Podman, the last container wins, and is the only container with access to the volume. The opposite of “private” here would be “shared” in my mind, which would explain why there’s no opposing term in the documentation (“shared shared label”).

I’m not sure there’s any significance in “content label” v. “label”, unless it’s an allusion to the fact that any content created in such containers will be labelled accordingly, including in the host, so you’ll see files with the container_file_t label.

See this post demonstrating the difference in more detail on Podman. Docker has the same distinction.

Answer 2

"I don't care about in depth security, just make it work": lowercase z

Productive environment: Consider capital Z but be aware that only the last container with that volume attached will be able to access it.

Btw: This is a comma separated list, so if you want to combine it for example with ro it becomes :ro,z.