Based on kernel version 4.9. Page generated on 2016-12-21 14:34 EST.
1 Written by: Neil Brown 2 Please see MAINTAINERS file for where to send questions. 3 4 Overlay Filesystem 5 ================== 6 7 This document describes a prototype for a new approach to providing 8 overlay-filesystem functionality in Linux (sometimes referred to as 9 union-filesystems). An overlay-filesystem tries to present a 10 filesystem which is the result over overlaying one filesystem on top 11 of the other. 12 13 The result will inevitably fail to look exactly like a normal 14 filesystem for various technical reasons. The expectation is that 15 many use cases will be able to ignore these differences. 16 17 This approach is 'hybrid' because the objects that appear in the 18 filesystem do not all appear to belong to that filesystem. In many 19 cases an object accessed in the union will be indistinguishable 20 from accessing the corresponding object from the original filesystem. 21 This is most obvious from the 'st_dev' field returned by stat(2). 22 23 While directories will report an st_dev from the overlay-filesystem, 24 all non-directory objects will report an st_dev from the lower or 25 upper filesystem that is providing the object. Similarly st_ino will 26 only be unique when combined with st_dev, and both of these can change 27 over the lifetime of a non-directory object. Many applications and 28 tools ignore these values and will not be affected. 29 30 Upper and Lower 31 --------------- 32 33 An overlay filesystem combines two filesystems - an 'upper' filesystem 34 and a 'lower' filesystem. When a name exists in both filesystems, the 35 object in the 'upper' filesystem is visible while the object in the 36 'lower' filesystem is either hidden or, in the case of directories, 37 merged with the 'upper' object. 38 39 It would be more correct to refer to an upper and lower 'directory 40 tree' rather than 'filesystem' as it is quite possible for both 41 directory trees to be in the same filesystem and there is no 42 requirement that the root of a filesystem be given for either upper or 43 lower. 44 45 The lower filesystem can be any filesystem supported by Linux and does 46 not need to be writable. The lower filesystem can even be another 47 overlayfs. The upper filesystem will normally be writable and if it 48 is it must support the creation of trusted.* extended attributes, and 49 must provide valid d_type in readdir responses, so NFS is not suitable. 50 51 A read-only overlay of two read-only filesystems may use any 52 filesystem type. 53 54 Directories 55 ----------- 56 57 Overlaying mainly involves directories. If a given name appears in both 58 upper and lower filesystems and refers to a non-directory in either, 59 then the lower object is hidden - the name refers only to the upper 60 object. 61 62 Where both upper and lower objects are directories, a merged directory 63 is formed. 64 65 At mount time, the two directories given as mount options "lowerdir" and 66 "upperdir" are combined into a merged directory: 67 68 mount -t overlay overlay -olowerdir=/lower,upperdir=/upper,\ 69 workdir=/work /merged 70 71 The "workdir" needs to be an empty directory on the same filesystem 72 as upperdir. 73 74 Then whenever a lookup is requested in such a merged directory, the 75 lookup is performed in each actual directory and the combined result 76 is cached in the dentry belonging to the overlay filesystem. If both 77 actual lookups find directories, both are stored and a merged 78 directory is created, otherwise only one is stored: the upper if it 79 exists, else the lower. 80 81 Only the lists of names from directories are merged. Other content 82 such as metadata and extended attributes are reported for the upper 83 directory only. These attributes of the lower directory are hidden. 84 85 whiteouts and opaque directories 86 -------------------------------- 87 88 In order to support rm and rmdir without changing the lower 89 filesystem, an overlay filesystem needs to record in the upper filesystem 90 that files have been removed. This is done using whiteouts and opaque 91 directories (non-directories are always opaque). 92 93 A whiteout is created as a character device with 0/0 device number. 94 When a whiteout is found in the upper level of a merged directory, any 95 matching name in the lower level is ignored, and the whiteout itself 96 is also hidden. 97 98 A directory is made opaque by setting the xattr "trusted.overlay.opaque" 99 to "y". Where the upper filesystem contains an opaque directory, any 100 directory in the lower filesystem with the same name is ignored. 101 102 readdir 103 ------- 104 105 When a 'readdir' request is made on a merged directory, the upper and 106 lower directories are each read and the name lists merged in the 107 obvious way (upper is read first, then lower - entries that already 108 exist are not re-added). This merged name list is cached in the 109 'struct file' and so remains as long as the file is kept open. If the 110 directory is opened and read by two processes at the same time, they 111 will each have separate caches. A seekdir to the start of the 112 directory (offset 0) followed by a readdir will cause the cache to be 113 discarded and rebuilt. 114 115 This means that changes to the merged directory do not appear while a 116 directory is being read. This is unlikely to be noticed by many 117 programs. 118 119 seek offsets are assigned sequentially when the directories are read. 120 Thus if 121 - read part of a directory 122 - remember an offset, and close the directory 123 - re-open the directory some time later 124 - seek to the remembered offset 125 126 there may be little correlation between the old and new locations in 127 the list of filenames, particularly if anything has changed in the 128 directory. 129 130 Readdir on directories that are not merged is simply handled by the 131 underlying directory (upper or lower). 132 133 134 Non-directories 135 --------------- 136 137 Objects that are not directories (files, symlinks, device-special 138 files etc.) are presented either from the upper or lower filesystem as 139 appropriate. When a file in the lower filesystem is accessed in a way 140 the requires write-access, such as opening for write access, changing 141 some metadata etc., the file is first copied from the lower filesystem 142 to the upper filesystem (copy_up). Note that creating a hard-link 143 also requires copy_up, though of course creation of a symlink does 144 not. 145 146 The copy_up may turn out to be unnecessary, for example if the file is 147 opened for read-write but the data is not modified. 148 149 The copy_up process first makes sure that the containing directory 150 exists in the upper filesystem - creating it and any parents as 151 necessary. It then creates the object with the same metadata (owner, 152 mode, mtime, symlink-target etc.) and then if the object is a file, the 153 data is copied from the lower to the upper filesystem. Finally any 154 extended attributes are copied up. 155 156 Once the copy_up is complete, the overlay filesystem simply 157 provides direct access to the newly created file in the upper 158 filesystem - future operations on the file are barely noticed by the 159 overlay filesystem (though an operation on the name of the file such as 160 rename or unlink will of course be noticed and handled). 161 162 163 Multiple lower layers 164 --------------------- 165 166 Multiple lower layers can now be given using the the colon (":") as a 167 separator character between the directory names. For example: 168 169 mount -t overlay overlay -olowerdir=/lower1:/lower2:/lower3 /merged 170 171 As the example shows, "upperdir=" and "workdir=" may be omitted. In 172 that case the overlay will be read-only. 173 174 The specified lower directories will be stacked beginning from the 175 rightmost one and going left. In the above example lower1 will be the 176 top, lower2 the middle and lower3 the bottom layer. 177 178 179 Non-standard behavior 180 --------------------- 181 182 The copy_up operation essentially creates a new, identical file and 183 moves it over to the old name. The new file may be on a different 184 filesystem, so both st_dev and st_ino of the file may change. 185 186 Any open files referring to this inode will access the old data. 187 188 Any file locks (and leases) obtained before copy_up will not apply 189 to the copied up file. 190 191 If a file with multiple hard links is copied up, then this will 192 "break" the link. Changes will not be propagated to other names 193 referring to the same inode. 194 195 Changes to underlying filesystems 196 --------------------------------- 197 198 Offline changes, when the overlay is not mounted, are allowed to either 199 the upper or the lower trees. 200 201 Changes to the underlying filesystems while part of a mounted overlay 202 filesystem are not allowed. If the underlying filesystem is changed, 203 the behavior of the overlay is undefined, though it will not result in 204 a crash or deadlock. 205 206 Testsuite 207 --------- 208 209 There's testsuite developed by David Howells at: 210 211 git://git.infradead.org/users/dhowells/unionmount-testsuite.git 212 213 Run as root: 214 215 # cd unionmount-testsuite 216 # ./run --ov