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