1 .\" $NetBSD: mtree.8,v 1.67 2012/12/20 20:31:01 wiz Exp $
3 .\" Copyright (c) 1989, 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" Copyright (c) 2001-2004 The NetBSD Foundation, Inc.
31 .\" All rights reserved.
33 .\" This code is derived from software contributed to The NetBSD Foundation
34 .\" by Luke Mewburn of Wasabi Systems.
36 .\" Redistribution and use in source and binary forms, with or without
37 .\" modification, are permitted provided that the following conditions
39 .\" 1. Redistributions of source code must retain the above copyright
40 .\" notice, this list of conditions and the following disclaimer.
41 .\" 2. Redistributions in binary form must reproduce the above copyright
42 .\" notice, this list of conditions and the following disclaimer in the
43 .\" documentation and/or other materials provided with the distribution.
45 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
46 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
47 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
48 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
49 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
50 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
51 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
52 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
53 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
54 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
55 .\" POSSIBILITY OF SUCH DAMAGE.
57 .\" @(#)mtree.8 8.2 (Berkeley) 12/11/93
64 .Nd map a directory hierarchy
67 .Op Fl bCcDdejLlMnPqrStUuWx
79 .Op Fl X Ar exclude-file
83 utility compares a file hierarchy against a specification,
84 creates a specification for a file hierarchy, or modifies
87 The default action, if not overridden by command line options,
88 is to compare the file hierarchy rooted in the current directory
89 against a specification read from the standard input.
90 Messages are written to the standard output for any files whose
91 characteristics do not match the specification, or which are
92 missing from either the file hierarchy or the specification.
94 The options are as follows:
95 .Bl -tag -width Xxxexcludexfilexx
97 Suppress blank lines before entering and after exiting directories.
99 Convert a specification into
100 a format that's easier to parse with various tools.
101 The input specification is read from standard input or
102 from the file given by
104 In the output, each file or directory is represented using a single line
105 (which might be very long).
109 is always printed as the first field;
114 can be used to control which other keywords are printed;
118 can be used to control which files are printed;
121 option can be used to sort the output.
123 Print a specification for the file hierarchy originating at
124 the current working directory (or the directory provided by
126 to the standard output.
127 The output is in a style using relative path names.
131 except that the path name is always printed as the last field instead of
134 Ignore everything except directory type files.
136 Add the comma separated tags to the
139 Non-directories with tags which are in the exclusion list are not printed with
144 Don't complain about files that are in the file hierarchy, but not in the
147 Set the compatibility flavor of the
163 flavors attempt to preserve output compatiblity and command line option
164 backward compatibility with
170 Read the specification from
172 instead of from the standard input.
174 If this option is specified twice, the two specifications are compared
175 to each other rather than to the file hierarchy.
176 The specifications will be sorted like output generated using
178 The output format in this case is somewhat reminiscent of
180 having "in first spec only", "in second spec only", and "different"
181 columns, prefixed by zero, one and two TAB characters respectively.
182 Each entry in the "different" column occupies two lines, one from each
185 Add the comma separated tags to the
188 Non-directories with tags which are in the inclusion list are printed with
192 If no inclusion list is provided, the default is to display all files.
194 If specified, set the schg and/or sappnd flags.
196 Indent the output 4 spaces each time a directory level is descended when
197 creating a specification with the
200 This does not affect either the /set statements or the comment before each
202 It does however affect the comment before the close of each directory.
203 This is the equivalent of the
210 Add the specified (whitespace or comma separated) keywords to the current
214 is specified, add all of the other keywords.
218 keyword plus the specified (whitespace or comma separated)
219 keywords instead of the current set of keywords.
222 is specified, use all of the other keywords.
225 keyword is not desired, suppress it with
228 Follow all symbolic links in the file hierarchy.
232 permissions checks, in which more stringent permissions
233 will match less stringent ones.
234 For example, a file marked mode 0444
235 will pass a check for mode 0644.
237 checks apply only to read, write and execute permissions -- in
238 particular, if other bits like the sticky bit or suid/sgid bits are
239 set either in the specification or the file, exact checking will be
241 This option may not be set at the same time as the
247 Permit merging of specification entries with different types,
248 with the last entry taking precedence.
250 If the schg and/or sappnd flags are specified, reset these flags.
251 Note that this is only possible with securelevel less than 1 (i.e.,
252 in single user mode or while the system is running in insecure
256 for information on security levels.
258 Do not emit pathname comments when creating a specification.
260 a comment is emitted before each directory and before the close of that
261 directory when using the
265 Use the user database text file
267 and group database text file
271 rather than using the results from the system's
275 (and related) library calls.
277 Don't follow symbolic links in the file hierarchy, instead consider
278 the symbolic link itself in any comparisons.
281 Use the file hierarchy rooted in
283 instead of the current directory.
286 Do not complain when a
288 directory cannot be created because it already exists.
289 This occurs when the directory is a symbolic link.
291 Remove the specified (whitespace or comma separated) keywords from the current
295 is specified, remove all of the other keywords.
297 Remove any files in the file hierarchy that are not described in the
300 When reading a specification into an internal data structure,
302 Sorting will affect the order of the output produced by the
306 options, and will also affect the order in which
307 missing entries are created or reported when a directory tree is checked
308 against a specification.
310 The sort order is the same as that used by the
312 option, which is that entries within the same directory are
313 sorted in the order used by
315 except that entries for subdirectories sort after other entries.
318 option is not used, entries within the same directory are collected
319 together (separated from entries for other directories), but not sorted.
321 Display a single checksum to the standard error output that represents all
322 of the files for which the keyword
325 The checksum is seeded with the specified value.
327 Modify the modified time of existing files, the device type of devices, and
328 symbolic link targets, to match the specification.
332 except that a mismatch is not considered to be an error if it was corrected.
334 Modify the owner, group, permissions, and flags of existing files,
335 the device type of devices, and symbolic link targets,
336 to match the specification.
337 Create any missing directories, devices or symbolic links.
338 User, group, and permissions must all be specified for missing directories
342 option is given, the schg and sappnd flags will not be set, even if
346 is given, these flags will be reset.
347 Exit with a status of 0 on success,
348 2 if the file hierarchy did not match the specification, and
349 1 if any other error occurred.
351 Don't attempt to set various file attributes such as the
352 ownership, mode, flags, or time
353 when creating new directories or changing existing entries.
354 This option will be most useful when used in conjunction with
358 .It Fl X Ar exclude-file
359 The specified file contains
361 patterns matching files to be excluded from
362 the specification, one to a line.
363 If the pattern contains a
365 character, it will be matched against entire pathnames (relative to
366 the starting directory); otherwise,
367 it will be matched against basenames only.
368 Comments are permitted in
373 Don't descend below mount points in the file hierarchy.
376 Specifications are mostly composed of
379 that specify values relating to files.
380 No keywords have default values, and if a keyword has no value set, no
381 checks based on it are performed.
383 Currently supported keywords are as follows:
384 .Bl -tag -width sha384digestxx
386 The checksum of the file using the default algorithm specified by
391 The device number to use for
396 The argument must be one of the following forms:
398 .It Ar format , Ns Ar major , Ns Ar minor
403 fields, for an operating system specified with
405 See below for valid formats.
406 .It Ar format , Ns Ar major , Ns Ar unit , Ns Ar subunit
412 fields, for an operating system specified with
414 (Currently this is only supported by the
418 Opaque number (as stored on the file system).
421 The following values for
446 The file flags as a symbolic name.
449 for information on these names.
450 If no flags are to be set the string
452 may be used to override the current default.
453 Note that the schg and sappnd flags are treated specially (see the
459 Ignore any file hierarchy below this file.
461 The file group as a numeric value.
463 The file group as a symbolic name.
465 The file the symbolic link is expected to reference.
469 cryptographic message digest of the file.
474 The current file's permissions as a numeric (octal) or symbolic
477 The number of hard links the file is expected to have.
479 Make sure this file or directory exists but otherwise ignore all attributes.
481 The file is optional; don't complain about the file if it's
482 not in the file hierarchy.
483 .It Sy ripemd160digest
489 cryptographic message digest of the file.
496 cryptographic message digest of the file.
503 cryptographic message digest of the file.
510 cryptographic message digest of the file.
517 cryptographic message digest of the file.
522 The size, in bytes, of the file.
524 Comma delimited tags to be matched with
528 These may be specified without leading or trailing commas, but will be
529 stored internally with them.
531 The last modification time of the file,
532 in second and nanoseconds.
533 The value should include a period character and exactly nine digits after
536 The type of the file; may be set to any one of the following:
538 .Bl -tag -width Sy -compact
542 character special device
555 The file owner as a numeric value.
557 The file owner as a symbolic name.
560 The default set of keywords are
572 There are four types of lines in a specification:
575 Set global values for a keyword.
576 This consists of the string
578 followed by whitespace, followed by sets of keyword/value
579 pairs, separated by whitespace.
580 Keyword/value pairs consist of a keyword, followed by an equals sign
582 followed by a value, without whitespace characters.
583 Once a keyword has been set, its value remains unchanged until either
586 Unset global values for a keyword.
587 This consists of the string
589 followed by whitespace, followed by one or more keywords,
590 separated by whitespace.
593 is specified, unset all of the keywords.
595 A file specification, consisting of a path name, followed by whitespace,
596 followed by zero or more whitespace separated keyword/value pairs.
598 The path name may be preceded by whitespace characters.
599 The path name may contain any of the standard path name matching
609 in the hierarchy will be associated with the first pattern that
614 (in VIS_CSTYLE format) to encode path names containing
615 non-printable characters.
616 Whitespace characters are encoded as
624 characters in path names are escaped by a preceding backslash
626 to distinguish them from comments.
628 Each of the keyword/value pairs consist of a keyword, followed by an
631 followed by the keyword's value, without
632 whitespace characters.
633 These values override, without changing, the global value of the
634 corresponding keyword.
636 The first path name entry listed must be a directory named
638 as this ensures that intermixing full and relative path names will
639 work consistently and correctly.
640 Multiple entries for a directory named
642 are permitted; the settings for the last such entry override those
643 of the existing entry.
645 A path name that contains a slash
647 that is not the first character will be treated as a full path
648 (relative to the root of the tree).
649 All parent directories referenced in the path name must exist.
650 The current directory path used by relative path names will be updated
652 Multiple entries for the same full path are permitted if the types
655 is given, in which case the types may differ);
656 in this case the settings for the last entry take precedence.
658 A path name that does not contain a slash will be treated as a relative path.
659 Specifying a directory will cause subsequent files to be searched
660 for in that directory hierarchy.
662 A line containing only the string
664 which causes the current directory path (used by relative paths)
668 Empty lines and lines whose first non-whitespace character is a hash
675 utility exits with a status of 0 on success, 1 if any error occurred,
676 and 2 if the file hierarchy did not match the specification.
678 .Bl -tag -width /etc/mtree -compact
680 system specification directory
683 To detect system binaries that have been
685 it is recommended that
687 be run on the file systems, and a copy of the results stored on a different
688 machine, or, at least, in encrypted form.
691 option should not be an obvious value and the final checksum should not be
692 stored on-line under any circumstances!
695 should be run against the on-line specifications and the final checksum
696 compared with the previous value.
697 While it is possible for the bad guys to change the on-line specifications
698 to conform to their modified binaries, it shouldn't be possible for them
699 to make it produce the same final checksum value.
700 If the final checksum value changes, the off-line copies of the specification
701 can be used to detect which of the binaries have actually been modified.
705 option can be used in combination with
709 to create directory hierarchies for, for example, distributions.
711 The compatibility shims provided by the
713 option are incomplete by design.
714 Known limitations are described below.
718 flavor retains the default handling of lookup failures for the
722 keywords by replacing them with appropriate
726 keywords rather than failing and reporting an error.
729 flag is a no-op rather than causing a warning to be printed and no
730 keyword to be emitted.
731 The latter behavior is not emulated as it is potentially dangerous in
732 the face of /set statements.
736 flavor does not replicate the historical bug that reported time as
737 seconds.nanoseconds without zero padding nanosecond values less than
793 options, and support for full paths appeared in
projects / FreeBSD / releng / 9.2.git / blob