a014988113
A rootless user can bind-mount a directory whose parent is mode 700 when that parent is owned by a UID inside their /etc/subuid range, and gets "statfs ...: permission denied" when the same parent is owned by root. The user has no access to the parent in either case, and nothing in the docs explains the difference. The reason is the user namespace. CAP_DAC_OVERRIDE bypasses a file's mode only when that file's UID and GID are both mapped in the namespace, which is "Operation of file-related capabilities" in user_namespaces(7). A parent whose owner is not mapped is reported with the overflow ID 65534, so root gets no DAC override and the parent's mode is enforced. An owner inside the subordinate range is mapped, the override applies, and mode 700 is bypassed. --userns=keep-id changes none of the outcomes. The report that prompted this was a rootless bind mount of a directory under /etc/letsencrypt, owned by certbot:certbot with mode 750, by a user who is not in that group, and a question about whether that is intentional. The "Using volumes" section explains the ID shift for files created inside the container and says nothing about whether the mount source can be traversed, which is the part the reporter hit. Add a short subsection there that opens with the capability rule and shows three cases as one rule: mode 755 owned by root mounts fine because world permissions already allow it, mode 700 owned by root fails, and mode 700 owned by an ID inside the range succeeds. It also gives the podman unshare check for whether a UID is mapped, and the consequence for subordinate ranges that overlap real accounts. Behavior checked on Debian with podman 5.4.2 and a 100000:65536 range. Discussion: https://github.com/podman-container-tools/podman/discussions/29443 Signed-off-by: José M. Requena Plens <jmrplens@gmail.com> |
||
|---|---|---|
| .. | ||
| cncf | ||
| source | ||
| tutorials | ||
| CODE_STRUCTURE.md | ||
| Containerfile | ||
| dckrman.sh | ||
| kubernetes_support.md | ||
| links-to-html.lua | ||
| make.ps1 | ||
| Makefile | ||
| MANPAGE_SYNTAX.md | ||
| play.png | ||
| podman-derivative-api | ||
| README.md | ||
| remote-docs.sh | ||
| requirements.txt | ||
| standalone-styling.css | ||
| use-pagetitle.lua | ||
Podman Documentation
The online man pages and other documents regarding Podman can be found at Read The Docs. The man pages can be found under the Commands link on that page.
Build the Docs
Directory Structure
| Directory | |
|---|---|
| Markdown source for man pages | docs/source/markdown/ |
| man pages aliases as .so files | docs/source/markdown/links/ |
| target for output | docs/build |
| man pages | docs/build/man |
| remote linux man pages | docs/build/remote/linux |
| remote darwin man pages | docs/build/remote/darwin |
| remote windows html pages | docs/build/remote/windows |
Support files
| docs/remote-docs.sh | Read the docs/source/markdown files and format for each platform |
| docs/links-to-html.lua | pandoc filter to do aliases for html files |
| docs/use-pagetitle.lua | pandoc filter to set html document title |
Manpage Syntax
The syntax for the formatting of all man pages can be found here.
API Reference
The latest online documentation is
automatically generated by the readthedocs build process. It uses redoc to render the
swagger.yml file, the swagger is build and injected as static resource in the readthedocs
build process, see the .readthedocs.yaml file.
The swagger file can be downloaded from https://docs.podman.io/en/latest/_static/swagger.yaml.
Note the latest link always contains the latest yaml from the main branch, if you like a specific
version replace latest with the version, i.e. for v6.0.0 https://docs.podman.io/en/v6.0.0/_static/swagger.yaml.
Also this new process is only done since v5.8.4. Earlier swagger.yml files where
uploaded here.
Local Testing
To build standard man pages, run make docs. Results will be in docs/build/man.
To build HTMLized man pages: Assuming that you have the dependencies installed, then also install (showing Fedora in the example):
$ sudo dnf install python3-sphinx python3-recommonmark
$ pip install sphinx-markdown-tables myst_parser
(The above dependencies are current as of 2022-09-15. If you experience problems, please see requirements.txt in this directory, it will almost certainly be more up-to-date than this README.)
After that completes, cd to the docs directory in your Podman sandbox and then do make html.
You can then preview the html files in docs/build/html with:
python -m http.server 8000 --directory build/html
...and point your web browser at http://localhost:8000/