Package: mount Version: 2.38.1-4 Dear Maintainer,
[Some new text for the manual page is suggested below.]
'man 8 mount' says under "Mount options for overlay":
A read-only overlay of two read-only filesystems may use any filesystem type.
The options lowerdir and upperdir are combined into a merged directory
When trying to set this up, the kernel logged this error:
overlayfs: upper fs is r/o, try multi-lower layers mount
The manual doesn't mention any such possibility, and seems to contradict
it (unless the following text is read very carefully, using a definition
of "upper" differing from that used in the source code):
An overlay filesystem combines two filesystems - an upper filesystem
and a lower filesystem.
…
The options lowerdir and upperdir are combined…
I tried using 'lowerdir' multiple times, but that doesn't work. Looking
at the source code revealed 'lowerdir' is treated as a list separated by
colons, with backslash as an escape character. 'upperdir' and 'workdir'
are single items and don't require or support escaping.
It's also unclear about whether the 'workdir' is mandatory. If upperdir
is specified, it is; otherwise, it's useless and ignored, and the kernel
will log a message saying that.
The statement that "workdir needs to be an empty directory" is false; it
can contain a "work" subdirectory, at least, but I see no enforcement at
all in the code. (The kernel will create a "work" subdirectory. If the
workdir had to be empty, a user would have to delete that before reusing
the same workdir later.)
A kernel comment says "Workdir should not be subdir of upperdir and vice
versa"--and "should" is misleading because the mount will fail if either
is true. The manual doesn't say this (as a suggestion or requirement).
The code implements an optional "exclusive upperdir protection" feature,
also used for the workdir, not mentioned in the manual. If either is in
use for another overlay mount, it's an error--except that if "index=off"
was used, it's only a warning.
I suggest the text from "An overlay filesystem combines" to "userxattr"
be replaced with the following:
An overlay filesystem combines two or more directory trees:
one or more read-only lower trees, and an optional upper tree.
Directories are merged, with any non-directory path in a
higher tree hiding any such path that exists in a lower tree.
A read-only overlay mount would normally be created using
multiple lower trees; for example,
mount -t overlay overlay -o ro,lowerdir=/top:/bottom /merged
A read/write mount requires upper and work trees; for example,
mount -t overlay overlay -o lowerdir=/lower,upperdir=/upper,workdir=/work
/merged
lowerdir=directory[:directory]
One or more directory paths separated by colons, with each tree to
be mounted below any that precede it. Any filesystem supported by
Linux is acceptable, even if it's read-only or is itself an overlay.
Each colon or backslash in a path must be escaped by preceding it
with a backslash.
upperdir=directory
One (un-escaped) directory path to be mounted above everything
in the lowerdir list. It should not be in use as the upperdir or
workdir of any other overlay. A read/write overlay requires an
upperdir and workdir on the same writable filesystem, with neither
being inside the other; this filesystem must support the creation
of trusted.* extended attributes, and must provide a valid d_type
in readdir response (so, NFS is not suitable).
workdir=directory
One (un-escaped) directory path to be used internally by overlayfs.
It must be on the same filesystem as upperdir, without being inside
upperdir. It should be empty, and should not be in use as the
upperdir or workdir of any other overlay.
I waive any copyright in this text (per public-domain.txt, attached).
- Michael
-- System Information:
Debian Release: bookworm/sid
APT prefers unstable
APT policy: (500, 'unstable')
Architecture: amd64 (x86_64)
Kernel: Linux 6.1.0-4-amd64 (SMP w/32 CPU threads; PREEMPT)
Locale: LANG=en_CA.UTF-8, LC_CTYPE=en_CA.UTF-8 (charmap=UTF-8),
LANGUAGE=en_CA:en
Shell: /bin/sh linked to /usr/bin/dash
Init: systemd (via /run/systemd/system)
LSM: AppArmor: enabled
Versions of packages mount depends on:
ii libblkid1 2.38.1-4
ii libc6 2.36-8
ii libmount1 2.38.1-4
ii libselinux1 3.4-1+b5
ii libsmartcols1 2.38.1-4
mount recommends no packages.
Versions of packages mount suggests:
pn nfs-common <none>
-- no debconf information
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. In addition to the above license, the author(s) have dedicated all copyright and related and neighboring rights to this work to the public domain worldwide, to the extent possible under law. For details: https://creativecommons.org/publicdomain/zero/1.0/legalcode
signature.asc
Description: PGP signature
