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 accommodate 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       -o  squash_to_root  Every  file and directory is owned by the root user
98       (0:0).
99
100
101       -o squash_to_uid=uid -o squash_to_gid=gid Every file and  directory  is
102       owned by the specified uid or gid.
103
104
105       It has higher precedence over squash_to_root.
106
107
108       -o static_nlink Set st_nlink to the static value 1 for all directories.
109
110
111       This  can  be useful for higher latency file systems such as NFS, where
112       counting the number of hard links for a directory with many  files  can
113       be a slow operation. With this option enabled, the number of hard links
114       reported when running stat for any directory is 1.
115
116
117

SEE ALSO

119       fuse(8), mount(8), user_namespaces(7)
120
121
122

AVAILABILITY

124       The fuse-overlayfs command is  available  from  https://github.com/con‐
125       tainers/fuse-overlayfs  under  GNU  GENERAL PUBLIC LICENSE Version 3 or
126       later.
127
128
129
130                                 User Commands               fuse-overlayfs(1)