-
Notifications
You must be signed in to change notification settings - Fork 4
/
README
138 lines (110 loc) · 5.31 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
fsck.overlay
============
fsck.overlay is used to check and optionally repair underlying directories
of overlay-filesystem.
Check the following points:
Basic items
-----------
Kernel do some basic checking for the workdir and upperdir at mount time, fsck
need to do the same things.
1) The workdir should not be subdir of the upperdir and vice versa.
2) The workdir and the upperdir should belong to the same base file system.
3) The upper layer should not be read-only.
4) Any layer of the whole underlying layers should not be mounted.
fsck will refuse to check and repair the file system if one of the above
mismatch. It will also check the lower layers that are real read-only or not,
and switch to "no change" mode when checking the read-only lower layer.
Whiteouts
---------
A whiteout is a character device with 0/0 device number. It is used to record
the removed files or directories, When a whiteout is found in a directory,
there should be at least one directory or file with the same name in any of the
corresponding lower layers. If not exist, the whiteout will be treated as orphan
whiteout and remove.
Redirect directories
--------------------
An redirect directory is a directory with "trusted.overlay.redirect" xattr
valued to the path of the original location from the root of the overlay. It
is only used when renaming a directory and "redirect dir" feature is enabled.
If an redirect directory is found, the following must be met:
1) The directory path pointed by redirect xattr should exist in one of lower
layers.
2) There must be something with the same name to the rename origin in upper
layer covering the lower target, could be a whiteout or a generic file,
could be an opaque directory or another redirect direcotry but not a merge
directory.
3) The origin directory should be redirected by only once, which means this
origin directory should be redirected by an unique directory in all layers.
If not,
1) The redirect xattr is invalid and should remove.
2) If nothing covering the redirect origin target, fix the missing whiteout.
If the redirect origin is covered by a generic directory, it becomes a
subcase of duplicate redirect directory (redirect direcotry duplicate with
an existing merge directory). Not sure the origin is a merge directory or
a redirected directory, so there are two options can fix this inconsistency:
a) remove the redirect xattr fsck found, or b) set opaque to the covering
directory. Ask user by default or warn in auto mode.
3) Record redirect xattrs but not sure which one is invalid, ask user by
default and warn in auto mode.
Impure directories
------------------
An impure directory is a directory with "trusted.overlay.impure" xattr valued
'y', which indicate that this directory may contain copied up targets from lower
layers.
If a target copy-up from lower to upper layer, it's 'd_ino' (see getdents(2))
will change from lower's 'd_ino' to upper's (a new inode will be created in
upper layer). So the impure xattr should be set to the parent directory to
prompt overlay filesystem to get and return the origin 'd_ino', thus ensuring
the consistentcy of 'd_ino'.
There are three situations of setting impure xattr in overlay filesystem:
1) Copy-up lower target in a directory.
2) Link an origin target (already copied up, have origin xattr) into a
directory.
3) Rename an origin target (include merge subdirectories) into a new
directory.
So, the impure xattr should be set if a direcotry contains origin targets or
redirect/merge subdirectories. If not, fix the impure xattr.
Usage
=====
1. Ensure overlay filesystem is not mounted based on directories which need to
check.
2. Run fsck.overlay program:
Usage:
fsck.overlay [-o lowerdir=<lowers>,upperdir=<upper>,workdir=<work>] [-pnyvhV]
Options:
-o, specify underlying directories of overlayfs:
multiple lower directories use ':' as separator
-p, automatic repair (no questions)
-n, make no changes to the filesystem
-y, assume "yes" to all questions
-v, --verbose print more messages of overlayfs
-h, --help display this usage of overlayfs
-V, --version display version information
Example:
fsck.overlay -o lowerdir=lower,upperdir=upper,workdir=work
3. Exit value:
0 No errors
1 Filesystem errors corrected
2 System should be rebooted
4 Filesystem errors left uncorrected
8 Operational error
16 Usage or syntax error
32 Checking canceled by user request
128 Shared-library error
Note
====
1. It is strongly recommend to run this program after modifing underlying
directories while overlay filesystem is offline.
2. Enough file descriptors (more than the number of specified underlying
directories) are required to run this program.
No Support
==========
Current version cannot support overlayfs which was mounted with new
features introduced in Linux kernel >= 4.13, include index, nfs_export
and other upcoming features. Checking overlayfs which has these features
may lead to inconsistency.
Contributions
=============
Like the Linux kernel, contributions to overlayfs-progs are very welcome.
Please send patches to the author and CC linux-unionfs mail list at