/share/doc/smm/03.fsck/3.t

  1.\" Copyright (c) 1982, 1993
  2.\"	The Regents of the University of California.  All rights reserved.
  3.\"
  4.\" Redistribution and use in source and binary forms, with or without
  5.\" modification, are permitted provided that the following conditions
  6.\" are met:
  7.\" 1. Redistributions of source code must retain the above copyright
  8.\"    notice, this list of conditions and the following disclaimer.
  9.\" 2. Redistributions in binary form must reproduce the above copyright
 10.\"    notice, this list of conditions and the following disclaimer in the
 11.\"    documentation and/or other materials provided with the distribution.
 12.\" 4. Neither the name of the University nor the names of its contributors
 13.\"    may be used to endorse or promote products derived from this software
 14.\"    without specific prior written permission.
 15.\"
 16.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 17.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 19.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 20.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 21.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 22.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 23.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 24.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 25.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 26.\" SUCH DAMAGE.
 27.\"
 28.\"	$FreeBSD$
 29.\"	@(#)3.t	8.1 (Berkeley) 6/5/93
 30.\"
 31.ds RH Fixing corrupted file systems
 32.NH
 33Fixing corrupted file systems
 34.PP
 35A file system
 36can become corrupted in several ways.
 37The most common of these ways are
 38improper shutdown procedures
 39and hardware failures.
 40.PP
 41File systems may become corrupted during an
 42.I "unclean halt" .
 43This happens when proper shutdown
 44procedures are not observed,
 45physically write-protecting a mounted file system,
 46or a mounted file system is taken off-line.
 47The most common operator procedural failure is forgetting to
 48.I sync
 49the system before halting the CPU.
 50.PP
 51File systems may become further corrupted if proper startup
 52procedures are not observed, e.g.,
 53not checking a file system for inconsistencies,
 54and not repairing inconsistencies.
 55Allowing a corrupted file system to be used (and, thus, to be modified
 56further) can be disastrous.
 57.PP
 58Any piece of hardware can fail at any time.
 59Failures
 60can be as subtle as a bad block
 61on a disk pack, or as blatant as a non-functional disk-controller.
 62.NH 2
 63Detecting and correcting corruption
 64.PP
 65Normally
 66.I fsck_ffs
 67is run non-interactively.
 68In this mode it will only fix
 69corruptions that are expected to occur from an unclean halt.
 70These actions are a proper subset of the actions that 
 71.I fsck_ffs
 72will take when it is running interactively.
 73Throughout this paper we assume that 
 74.I fsck_ffs 
 75is being run interactively,
 76and all possible errors can be encountered.
 77When an inconsistency is discovered in this mode,
 78.I fsck_ffs
 79reports the inconsistency for the operator to
 80chose a corrective action.
 81.PP
 82A quiescent\(dd
 83.FS
 84\(dd I.e., unmounted and not being written on.
 85.FE
 86file system may be checked for structural integrity
 87by performing consistency checks on the
 88redundant data intrinsic to a file system.
 89The redundant data is either read from
 90the file system,
 91or computed from other known values.
 92The file system
 93.B must
 94be in a quiescent state when
 95.I fsck_ffs
 96is run,
 97since
 98.I fsck_ffs
 99is a multi-pass program.
100.PP
101In the following sections,
102we discuss methods to discover inconsistencies
103and possible corrective actions
104for the cylinder group blocks, the inodes, the indirect blocks, and
105the data blocks containing directory entries.
106.NH 2
107Super-block checking
108.PP
109The most commonly corrupted item in a file system
110is the summary information
111associated with the super-block.
112The summary information is prone to corruption
113because it is modified with every change to the file
114system's blocks or inodes,
115and is usually corrupted
116after an unclean halt.
117.PP
118The super-block is checked for inconsistencies
119involving file-system size, number of inodes,
120free-block count, and the free-inode count.
121The file-system size must be larger than the
122number of blocks used by the super-block
123and the number of blocks used by the list of inodes.
124The file-system size and layout information
125are the most critical pieces of information for
126.I fsck_ffs .
127While there is no way to actually check these sizes,
128since they are statically determined by
129.I newfs ,
130.I fsck_ffs
131can check that these sizes are within reasonable bounds.
132All other file system checks require that these sizes be correct.
133If
134.I fsck_ffs 
135detects corruption in the static parameters of the default super-block,
136.I fsck_ffs
137requests the operator to specify the location of an alternate super-block.
138.NH 2
139Free block checking
140.PP
141.I Fsck_ffs
142checks that all the blocks
143marked as free in the cylinder group block maps
144are not claimed by any files.
145When all the blocks have been initially accounted for,
146.I fsck_ffs
147checks that
148the number of free blocks
149plus the number of blocks claimed by the inodes
150equals the total number of blocks in the file system.
151.PP
152If anything is wrong with the block allocation maps,
153.I fsck_ffs
154will rebuild them,
155based on the list it has computed of allocated blocks.
156.PP
157The summary information associated with the super-block
158counts the total number of free blocks within the file system.
159.I Fsck_ffs
160compares this count to the
161number of free blocks it found within the file system.
162If the two counts do not agree, then
163.I fsck_ffs
164replaces the incorrect count in the summary information
165by the actual free-block count.
166.PP
167The summary information
168counts the total number of free inodes within the file system.
169.I Fsck_ffs
170compares this count to the number
171of free inodes it found within the file system.
172If the two counts do not agree, then
173.I fsck_ffs
174replaces the incorrect count in the
175summary information by the actual free-inode count.
176.NH 2
177Checking the inode state
178.PP
179An individual inode is not as likely to be corrupted as
180the allocation information.
181However, because of the great number of active inodes,
182a few of the inodes are usually corrupted.
183.PP
184The list of inodes in the file system
185is checked sequentially starting with inode 2
186(inode 0 marks unused inodes;
187inode 1 is saved for future generations)
188and progressing through the last inode in the file system.
189The state of each inode is checked for
190inconsistencies involving format and type,
191link count,
192duplicate blocks,
193bad blocks,
194and inode size.
195.PP
196Each inode contains a mode word.
197This mode word describes the type and state of the inode.
198Inodes must be one of six types:
199regular inode, directory inode, symbolic link inode,
200special block inode, special character inode, or socket inode.
201Inodes may be found in one of three allocation states:
202unallocated, allocated, and neither unallocated nor allocated.
203This last state suggests an incorrectly formated inode.
204An inode can get in this state if
205bad data is written into the inode list.
206The only possible corrective action is for
207.I fsck_ffs
208is to clear the inode.
209.NH 2
210Inode links
211.PP
212Each inode counts the
213total number of directory entries
214linked to the inode.
215.I Fsck_ffs
216verifies the link count of each inode
217by starting at the root of the file system,
218and descending through the directory structure.
219The actual link count for each inode
220is calculated during the descent.
221.PP
222If the stored link count is non-zero and the actual
223link count is zero,
224then no directory entry appears for the inode.
225If this happens,
226.I fsck_ffs
227will place the disconnected file in the
228.I lost+found
229directory.
230If the stored and actual link counts are non-zero and unequal,
231a directory entry may have been added or removed without the inode being
232updated.
233If this happens,
234.I fsck_ffs
235replaces the incorrect stored link count by the actual link count.
236.PP
237Each inode contains a list,
238or pointers to
239lists (indirect blocks),
240of all the blocks claimed by the inode.
241Since indirect blocks are owned by an inode,
242inconsistencies in indirect blocks directly
243affect the inode that owns it.
244.PP
245.I Fsck_ffs
246compares each block number claimed by an inode
247against a list of already allocated blocks.
248If another inode already claims a block number,
249then the block number is added to a list of
250.I "duplicate blocks" .
251Otherwise, the list of allocated blocks
252is updated to include the block number.
253.PP
254If there are any duplicate blocks,
255.I fsck_ffs
256will perform a partial second
257pass over the inode list
258to find the inode of the duplicated block.
259The second pass is needed,
260since without examining the files associated with
261these inodes for correct content,
262not enough information is available
263to determine which inode is corrupted and should be cleared.
264If this condition does arise
265(only hardware failure will cause it),
266then the inode with the earliest
267modify time is usually incorrect,
268and should be cleared.
269If this happens,
270.I fsck_ffs
271prompts the operator to clear both inodes.
272The operator must decide which one should be kept
273and which one should be cleared.
274.PP
275.I Fsck_ffs
276checks the range of each block number claimed by an inode.
277If the block number is
278lower than the first data block in the file system,
279or greater than the last data block,
280then the block number is a
281.I "bad block number" .
282Many bad blocks in an inode are usually caused by
283an indirect block that was not written to the file system,
284a condition which can only occur if there has been a hardware failure.
285If an inode contains bad block numbers,
286.I fsck_ffs
287prompts the operator to clear it.
288.NH 2
289Inode data size
290.PP
291Each inode contains a count of the number of data blocks
292that it contains.
293The number of actual data blocks
294is the sum of the allocated data blocks
295and the indirect blocks.
296.I Fsck_ffs
297computes the actual number of data blocks
298and compares that block count against
299the actual number of blocks the inode claims.
300If an inode contains an incorrect count
301.I fsck_ffs
302prompts the operator to fix it.
303.PP
304Each inode contains a thirty-two bit size field.
305The size is the number of data bytes
306in the file associated with the inode.
307The consistency of the byte size field is roughly checked
308by computing from the size field the maximum number of blocks
309that should be associated with the inode,
310and comparing that expected block count against
311the actual number of blocks the inode claims.
312.NH 2
313Checking the data associated with an inode
314.PP
315An inode can directly or indirectly
316reference three kinds of data blocks.
317All referenced blocks must be the same kind.
318The three types of data blocks are:
319plain data blocks, symbolic link data blocks, and directory data blocks.
320Plain data blocks
321contain the information stored in a file;
322symbolic link data blocks
323contain the path name stored in a link.
324Directory data blocks contain directory entries.
325.I Fsck_ffs
326can only check the validity of directory data blocks.
327.PP
328Each directory data block is checked for
329several types of inconsistencies.
330These inconsistencies include
331directory inode numbers pointing to unallocated inodes,
332directory inode numbers that are greater than
333the number of inodes in the file system,
334incorrect directory inode numbers for ``\fB.\fP'' and ``\fB..\fP'',
335and directories that are not attached to the file system.
336If the inode number in a directory data block
337references an unallocated inode,
338then
339.I fsck_ffs
340will remove that directory entry.
341Again,
342this condition can only arise when there has been a hardware failure.
343.PP
344.I Fsck_ffs
345also checks for directories with unallocated blocks (holes).
346Such directories should never be created.
347When found,
348.I fsck_ffs
349will prompt the user to adjust the length of the offending directory
350which is done by shortening the size of the directory to the end of the
351last allocated block preceding the hole.
352Unfortunately, this means that another Phase 1 run has to be done. 
353.I Fsck_ffs
354will remind the user to rerun fsck_ffs after repairing a
355directory containing an unallocated block.
356.PP
357If a directory entry inode number references
358outside the inode list, then
359.I fsck_ffs
360will remove that directory entry.
361This condition occurs if bad data is written into a directory data block.
362.PP
363The directory inode number entry for ``\fB.\fP''
364must be the first entry in the directory data block.
365The inode number for ``\fB.\fP''
366must reference itself;
367e.g., it must equal the inode number
368for the directory data block.
369The directory inode number entry
370for ``\fB..\fP'' must be
371the second entry in the directory data block.
372Its value must equal the inode number for the
373parent of the directory entry
374(or the inode number of the directory
375data block if the directory is the
376root directory).
377If the directory inode numbers are
378incorrect,
379.I fsck_ffs
380will replace them with the correct values.
381If there are multiple hard links to a directory,
382the first one encountered is considered the real parent
383to which ``\fB..\fP'' should point;
384\fIfsck_ffs\fP recommends deletion for the subsequently discovered names.
385.NH 2
386File system connectivity
387.PP
388.I Fsck_ffs
389checks the general connectivity of the file system.
390If directories are not linked into the file system, then
391.I fsck_ffs
392links the directory back into the file system in the
393.I lost+found
394directory.
395This condition only occurs when there has been a hardware failure.
396.ds RH "References"
397.SH
398\s+2Acknowledgements\s0
399.PP
400I thank Bill Joy, Sam Leffler, Robert Elz and Dennis Ritchie 
401for their suggestions and help in implementing the new file system.
402Thanks also to Robert Henry for his editorial input to
403get this document together.
404Finally we thank our sponsors,
405the National Science Foundation under grant MCS80-05144,
406and the Defense Advance Research Projects Agency (DoD) under
407Arpa Order No. 4031 monitored by Naval Electronic System Command under
408Contract No. N00039-82-C-0235. (Kirk McKusick, July 1983)
409.PP
410I would like to thank Larry A. Wehr for advice that lead
411to the first version of
412.I fsck_ffs
413and Rick B. Brandt for adapting
414.I fsck_ffs
415to
416UNIX/TS. (T. Kowalski, July 1979)
417.sp 2
418.SH
419\s+2References\s0
420.LP
421.IP [Dolotta78] 20
422Dolotta, T. A., and Olsson, S. B. eds.,
423.I "UNIX User's Manual, Edition 1.1\^" ,
424January 1978.
425.IP [Joy83] 20
426Joy, W., Cooper, E., Fabry, R., Leffler, S., McKusick, M., and Mosher, D.
4274.2BSD System Manual,
428.I "University of California at Berkeley" ,
429.I "Computer Systems Research Group Technical Report"
430#4, 1982.
431.IP [McKusick84] 20
432McKusick, M., Joy, W., Leffler, S., and Fabry, R.
433A Fast File System for UNIX,
434\fIACM Transactions on Computer Systems 2\fP, 3.
435pp. 181-197, August 1984.
436.IP [Ritchie78] 20
437Ritchie, D. M., and Thompson, K.,
438The UNIX Time-Sharing System,
439.I "The Bell System Technical Journal"
440.B 57 ,
4416 (July-August 1978, Part 2), pp. 1905-29.
442.IP [Thompson78] 20
443Thompson, K.,
444UNIX Implementation,
445.I "The Bell System Technical Journal\^"
446.B 57 ,
4476 (July-August 1978, Part 2), pp. 1931-46.
448.ds RH Appendix A \- Fsck_ffs Error Conditions
449.bp