1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======
4 NILFS2
5 ======
6
7 NILFS2 is a log-structured file system (LFS) s
8 snapshotting. In addition to versioning capab
9 system, users can even restore files mistakenl
10 destroyed just a few seconds ago. Since NILFS
11 like conventional LFS, it achieves quick recov
12 crashes.
13
14 NILFS2 creates a number of checkpoints every f
15 synchronous write basis (unless there is no ch
16 significant versions among continuously create
17 change them into snapshots which will be prese
18 changed back to checkpoints.
19
20 There is no limit on the number of snapshots u
21 full. Each snapshot is mountable as a read-on
22 concurrently with its writable mount, and this
23 for online backup.
24
25 The userland tools are included in nilfs-utils
26 available from the following download page. A
27 "mount.nilfs2", "umount.nilfs2", and "nilfs_cl
28 cleaner or garbage collector) are required. D
29 described in the man pages included in the pac
30
31 :Project web page: https://nilfs.sourceforg
32 :Download page: https://nilfs.sourceforg
33 :List info: http://vger.kernel.org/v
34
35 Caveats
36 =======
37
38 Features which NILFS2 does not support yet:
39
40 - atime
41 - extended attributes
42 - POSIX ACLs
43 - quotas
44 - fsck
45 - defragmentation
46
47 Mount options
48 =============
49
50 NILFS2 supports the following mount options:
51 (*) == default
52
53 ======================= ======================
54 barrier(*) This enables/disables
55 nobarrier requires an IO stack w
56 if nilfs gets an error
57 disable again with a w
58 errors=continue Keep going on a filesy
59 errors=remount-ro(*) Remount the filesystem
60 errors=panic Panic and halt the mac
61 cp=n Specify the checkpoint
62 mounted. Checkpoints
63 user command. Only th
64 are mountable with thi
65 so a read-only mount o
66 order=relaxed(*) Apply relaxed order se
67 blocks to be written t
68 checkpoint if no metad
69 is equivalent to the o
70 filesystem except for
71 conserve atomicity. T
72 write performance for
73 order=strict Apply strict in-order
74 of all file operations
75 blocks. That means, i
76 overtaking of events o
77 system after a crash.
78 norecovery Disable recovery of th
79 This disables every wr
80 read-only mounts or sn
81 for r/w mounts on an u
82 discard This enables/disables
83 nodiscard(*) The discard/TRIM comma
84 block device when bloc
85 for SSD devices and sp
86 ======================= ======================
87
88 Ioctls
89 ======
90
91 There is some NILFS2 specific functionality wh
92 through the system call interfaces. The list o
93 shown in the table below.
94
95 Table of NILFS2 specific ioctls:
96
97 ============================== ==============
98 Ioctl Description
99 ============================== ==============
100 NILFS_IOCTL_CHANGE_CPMODE Change mode of
101 checkpoint and
102 used in chcp a
103
104 NILFS_IOCTL_DELETE_CHECKPOINT Remove checkpo
105 This ioctl is
106
107 NILFS_IOCTL_GET_CPINFO Return info ab
108 ioctl is used
109 nilfs_cleanerd
110
111 NILFS_IOCTL_GET_CPSTAT Return checkpo
112 used by lscp,
113 nilfs_cleanerd
114
115 NILFS_IOCTL_GET_SUINFO Return segment
116 segments. This
117 nilfs_resize u
118 daemon.
119
120 NILFS_IOCTL_SET_SUINFO Modify segment
121 segments. This
122 nilfs_cleanerd
123 cleaning opera
124 performance pe
125 due to redunda
126
127 NILFS_IOCTL_GET_SUSTAT Return segment
128 is used in lss
129 by nilfs_clean
130
131 NILFS_IOCTL_GET_VINFO Return informa
132 This ioctl is
133
134 NILFS_IOCTL_GET_BDESCS Return informa
135 block numbers.
136 nilfs_cleanerd
137
138 NILFS_IOCTL_CLEAN_SEGMENTS Do garbage col
139 environment of
140 userspace. Thi
141 nilfs_cleanerd
142
143 NILFS_IOCTL_SYNC Make a checkpo
144 mkcp utility.
145
146 NILFS_IOCTL_RESIZE Resize NILFS2
147 by nilfs_resiz
148
149 NILFS_IOCTL_SET_ALLOC_RANGE Define lower l
150 upper limit of
151 is used by nil
152 ============================== ==============
153
154 NILFS2 usage
155 ============
156
157 To use nilfs2 as a local file system, simply::
158
159 # mkfs -t nilfs2 /dev/block_device
160 # mount -t nilfs2 /dev/block_device /dir
161
162 This will also invoke the cleaner through the
163 (mount.nilfs2).
164
165 Checkpoints and snapshots are managed by the f
166 Their manpages are included in the nilfs-utils
167
168 ==== ===================================
169 lscp list checkpoints or snapshots.
170 mkcp make a checkpoint or a snapshot.
171 chcp change an existing checkpoint to a
172 rmcp invalidate specified checkpoint(s).
173 ==== ===================================
174
175 To mount a snapshot::
176
177 # mount -t nilfs2 -r -o cp=<cno> /dev/block_d
178
179 where <cno> is the checkpoint number of the sn
180
181 To unmount the NILFS2 mount point or snapshot,
182
183 # umount /dir
184
185 Then, the cleaner daemon is automatically shut
186 helper program (umount.nilfs2).
187
188 Disk format
189 ===========
190
191 A nilfs2 volume is equally divided into a numb
192 for the super block (SB) and segment #0. A se
193 of logs. Each log is composed of summary info
194 blocks, and an optional super root block (SR):
195
196 ___________________________________________
197 | |SB| | Segment | Segment | Segment | ... |
198 |_|__|_|____0____|____1____|____2____|_____|
199 0 +1K +4K +8M +16M +24M +(
200 . . (Typical off
201 . .
202 .______________________.
203 | log | log |... | log |
204 |__1__|__2__|____|__m__|
205 . .
206 . .
207 . .
208 .______________________________.
209 | Summary | Payload blocks |SR|
210 |_blocks__|_________________|__|
211
212 The payload blocks are organized per file, and
213 data blocks and B-tree node blocks::
214
215 |<--- File-A --->|<---
216 ___________________________________________
217 | Data blocks | B-tree blocks | Data block
218 _|_____________|_______________|___________
219
220
221 Since only the modified blocks are written in
222 files without data blocks or B-tree node block
223
224 The organization of the blocks is recorded in
225 blocks, which contains a header structure (nil
226 file structures (nilfs_finfo), and per block s
227
228 ____________________________________________
229 | Summary | finfo | binfo | ... | binfo | fin
230 |_blocks__|___A___|_(A,1)_|_____|(A,Na)_|___B
231
232
233 The logs include regular files, directory file
234 and several meta data files. The meta data fi
235 to maintain file system meta data. The curren
236 the following meta data files::
237
238 1) Inode file (ifile) -- Stores o
239 2) Checkpoint file (cpfile) -- Stores c
240 3) Segment usage file (sufile) -- Stores a
241 4) Data address translation file -- Maps vir
242 (DAT) block nu
243 make on-
244
245 The following figure shows a typical organizat
246
247 ____________________________________________
248 | Summary | regular file | file | ... | ifil
249 |_blocks__|_or_directory_|_______|_____|_____
250
251
252 To stride over segment boundaries, this sequen
253 into multiple logs. The sequence of logs that
254 logically one log, is delimited with flags mar
255 summary. The recovery code of nilfs2 looks th
256 to ensure atomicity of updates.
257
258 The super root block is inserted for every che
259 three special inodes, inodes for the DAT, cpfi
260 of regular files, directories, symlinks and ot
261 included in the ifile. The inode of ifile its
262 corresponding checkpoint entry in the cpfile.
263 among NILFS2 files can be depicted as follows:
264
265 Super block (SB)
266 |
267 v
268 Super root block (the latest cno=xx)
269 |-- DAT
270 |-- sufile
271 `-- cpfile
272 |-- ifile (cno=c1)
273 |-- ifile (cno=c2) ---- file (in
274 : : |-- file (in
275 `-- ifile (cno=xx) |-- file (in
276 : :
277 `-- file (in
278 ( regular
279
280 For detail on the format of each file, please
281 located at include/uapi/linux directory.
282
283 There are no patents or other intellectual pro
284 with regard to the design of NILFS2. It is al
285 design in hopes that other operating systems c
286 write, etc.) data stored in this format.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.