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   uidmapping=UID:MAPPED-UID:LEN[,UID2:MAPPED-UID2:LEN2]  -o  gidmap‐
43       ping=GID:MAPPED-GID:LEN[,GID2:MAPPED-GID2:LEN2] Specifies  the  dynamic
44       UID/GID  mapping  used  by fuse-overlayfs when reading/writing files to
45       the system.
46
47
48       The fuse-overlayfs dynamic mapping is an alternative and cheaper way to
49       chown'ing  the files on the host to accommodate the user namespace set‐
50       tings.
51
52
53       It is useful to share the same storage among different user  namespaces
54       and  counter  effect the mapping done by the user namespace itself, and
55       without requiring to chown the files.
56
57
58       For example, given on the host two files like:
59
60
61       $ stat -c %u:%g lower/a lower/b 0:0 1:1
62
63
64       When we run in a user namespace with the following configuration: $ cat
65       /proc/self/uid_map
66                0       1000          1
67                1     110000      65536
68
69
70       We would see:
71
72
73       $ stat -c %u:%g merged/a merged/b 65534:65534 65534:65534
74
75
76       65534  is the overflow id used when the UID/GID is not known inside the
77       user namespace.  This happens because both users 0:0 and  1:1  are  not
78       mapped.
79
80
81       In the above example, if we mount the fuse-overlayfs file system using:
82       -ouidmapping=0:1000:1:1:110000:65536,gidmap‐
83       ping=0:1000:1:1:110000:65536,  which  is  the  namespace  configuration
84       specified on a single line, we'd see from the same user namespace:
85
86
87       $ stat -c %u:%g merged/a merged/b 0:0 1:1
88
89
90       Those are the same IDs visible from outside the user namespace.
91
92
93       -o squash_to_root Every file and directory is owned by  the  root  user
94       (0:0).
95
96
97       -o  squash_to_uid=uid  -o squash_to_gid=gid Every file and directory is
98       owned by the specified uid or gid.
99
100
101       It has higher precedence over squash_to_root.
102
103
104       -o static_nlink Set st_nlink to the static value 1 for all directories.
105
106
107       This can be useful for higher latency file systems such as  NFS,  where
108       counting  the  number of hard links for a directory with many files can
109       be a slow operation. With this option enabled, the number of hard links
110       reported when running stat for any directory is 1.
111
112
113

SEE ALSO

115       fuse(8), mount(8), user_namespaces(7)
116
117
118

AVAILABILITY

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