1fuse-overlayfs(1)           General Commands Manual          fuse-overlayfs(1)
2
3
4

NAME

6       fuse-overlayfs - overlayfs FUSE implementation
7
8
9

SYNOPSIS

11       mounting
12           fuse-overlayfs [-f] [--debug] [-o OPTS] MOUNT_TARGET
13
14
15       unmounting
16           fusermount -u mountpoint
17
18
19

DESCRIPTION

21       fuse-overlayfs provides an overlayfs FUSE implementation so that it can
22       be used since Linux 4.18 by unprivileged users in an user namespace.
23
24
25

OPTIONS

27       --debug Enable debugging mode, can be very noisy.
28
29
30       -o lowerdir=low1[:low2...]  A  list  of  directories  separated  by  :.
31       Their content is merged.
32
33
34       -o  upperdir=upperdir  A  directory  merged on top of all the lowerdirs
35       where all the changes done to the file system will be written.
36
37
38       -o workdir=workdir A directory used internally by  fuse-overlays,  must
39       be on the same file system as the upper dir.
40
41
42       -o  workdir=workdir  A directory used internally by fuse-overlays, must
43       be on the same file system as the upper dir.
44
45
46       -o  uidmapping=UID:MAPPED-UID:LEN[,UID2:MAPPED-UID2:LEN2]  -o   gidmap‐
47       ping=GID:MAPPED-GID:LEN[,GID2:MAPPED-GID2:LEN2]  Specifies  the dynamic
48       UID/GID mapping used by fuse-overlayfs when  reading/writing  files  to
49       the system.
50
51
52       The fuse-overlayfs dynamic mapping is an alternative and cheaper way to
53       chown'ing the files on the host to accomodate the user  namespace  set‐
54       tings.
55
56
57       It  is useful to share the same storage among different user namespaces
58       and counter effect the mapping done by the user namespace  itself,  and
59       without requiring to chown the files.
60
61
62       For example, given on the host two files like:
63
64
65       $ stat -c %u:%g lower/a lower/b 0:0 1:1
66
67
68       When we run in a user namespace with the following configuration: $ cat
69       /proc/self/uid_map
70                0       1000          1
71                1     110000      65536
72
73
74       We would see:
75
76
77       $ stat -c %u:%g merged/a merged/b 65534:65534 65534:65534
78
79
80       65534 is the overflow id used when the UID/GID is not known inside  the
81       user  namespace.   This  happens because both users 0:0 and 1:1 are not
82       mapped.
83
84
85       In the above example, if we mount the fuse-overlayfs file system using:
86       -ouidmapping=0:1000:1:1:110000:65536,gidmap‐
87       ping=0:1000:1:1:110000:65536,  which  is  the  namespace  configuration
88       specified on a single line, we'd see from the same user namespace:
89
90
91       $ stat -c %u:%g merged/a merged/b 0:0 1:1
92
93
94       Those are the same IDs visible from outside the user namespace.
95
96
97

SEE ALSO

99       fuse(8), mount(8), user_namespaces(7)
100
101
102

AVAILABILITY

104       The  slirp4netns command is available from ⟨https://github.com/contain‐
105       ers/fuse-overlayfs⟩ under GNU  GENERAL  PUBLIC  LICENSE  Version  3  or
106       later.
107
108
109
110                                 User Commands               fuse-overlayfs(1)