1 .\" $NetBSD: mtree.8,v 1.72 2017/02/22 14:15:15 abhinav 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
80 .Op Fl X Ar exclude-file
84 utility compares a file hierarchy against a specification,
85 creates a specification for a file hierarchy, or modifies
88 The default action, if not overridden by command line options,
89 is to compare the file hierarchy rooted in the current directory
90 against a specification read from the standard input.
91 Messages are written to the standard output for any files whose
92 characteristics do not match the specification, or which are
93 missing from either the file hierarchy or the specification.
95 The options are as follows:
96 .Bl -tag -width Xxxexcludexfilexx
98 Suppress blank lines before entering and after exiting directories.
100 Convert a specification into
101 a format that's easier to parse with various tools.
102 The input specification is read from standard input or
103 from the file given by
105 In the output, each file or directory is represented using a single line
106 (which might be very long).
110 is always printed as the first field;
115 can be used to control which other keywords are printed;
119 can be used to control which files are printed;
122 option can be used to sort the output.
124 Print a specification for the file hierarchy originating at
125 the current working directory (or the directory provided by
127 to the standard output.
128 The output is in a style using relative path names.
132 except that the path name is always printed as the last field instead of
135 Ignore everything except directory type files.
137 Add the comma separated tags to the
140 Non-directories with tags which are in the exclusion list are not printed with
145 Don't complain about files that are in the file hierarchy, but not in the
148 Set the compatibility flavor of the
164 flavors attempt to preserve output compatibility and command line option
165 backward compatibility with
171 Read the specification from
173 instead of from the standard input.
175 If this option is specified twice, the two specifications are compared
176 to each other rather than to the file hierarchy.
177 The specifications will be sorted like output generated using
179 The output format in this case is somewhat reminiscent of
181 having "in first spec only", "in second spec only", and "different"
182 columns, prefixed by zero, one and two TAB characters respectively.
183 Each entry in the "different" column occupies two lines, one from each
186 Add the comma separated tags to the
189 Non-directories with tags which are in the inclusion list are printed with
193 If no inclusion list is provided, the default is to display all files.
195 If specified, set the schg and/or sappnd flags.
197 Indent the output 4 spaces each time a directory level is descended when
198 creating a specification with the
201 This does not affect either the /set statements or the comment before each
203 It does however affect the comment before the close of each directory.
204 This is the equivalent of the
211 Add the specified (whitespace or comma separated) keywords to the current
215 is specified, add all of the other keywords.
219 keyword plus the specified (whitespace or comma separated)
220 keywords instead of the current set of keywords.
223 is specified, use all of the other keywords.
226 keyword is not desired, suppress it with
229 Follow all symbolic links in the file hierarchy.
233 permissions checks, in which more stringent permissions
234 will match less stringent ones.
235 For example, a file marked mode 0444
236 will pass a check for mode 0644.
238 checks apply only to read, write and execute permissions -- in
239 particular, if other bits like the sticky bit or suid/sgid bits are
240 set either in the specification or the file, exact checking will be
242 This option may not be set at the same time as the
248 Permit merging of specification entries with different types,
249 with the last entry taking precedence.
251 If the schg and/or sappnd flags are specified, reset these flags.
252 Note that this is only possible with securelevel less than 1 (i.e.,
253 in single user mode or while the system is running in insecure
257 for information on security levels.
259 Do not emit pathname comments when creating a specification.
261 a comment is emitted before each directory and before the close of that
262 directory when using the
266 Use the user database text file
268 and group database text file
272 rather than using the results from the system's
276 (and related) library calls.
277 .It Fl O Ar onlypaths
278 Only include files included in this list of pathnames.
280 Don't follow symbolic links in the file hierarchy, instead consider
281 the symbolic link itself in any comparisons.
284 Use the file hierarchy rooted in
286 instead of the current directory.
289 Do not complain when a
291 directory cannot be created because it already exists.
292 This occurs when the directory is a symbolic link.
294 Remove the specified (whitespace or comma separated) keywords from the current
298 is specified, remove all of the other keywords.
300 Remove any files in the file hierarchy that are not described in the
302 Repeating the flag more than once will attempt to reset all the
305 before attempting to remove the file in case the file was immutable.
307 When reading a specification into an internal data structure,
309 Sorting will affect the order of the output produced by the
313 options, and will also affect the order in which
314 missing entries are created or reported when a directory tree is checked
315 against a specification.
317 The sort order is the same as that used by the
319 option, which is that entries within the same directory are
320 sorted in the order used by
322 except that entries for subdirectories sort after other entries.
325 option is not used, entries within the same directory are collected
326 together (separated from entries for other directories), but not sorted.
328 Display a single checksum to the standard error output that represents all
329 of the files for which the keyword
332 The checksum is seeded with the specified value.
334 Modify the modified time of existing files, the device type of devices, and
335 symbolic link targets, to match the specification.
339 except that a mismatch is not considered to be an error if it was corrected.
341 Modify the owner, group, permissions, and flags of existing files,
342 the device type of devices, and symbolic link targets,
343 to match the specification.
344 Create any missing directories, devices or symbolic links.
345 User, group, and permissions must all be specified for missing directories
349 option is given, the schg and sappnd flags will not be set, even if
353 is given, these flags will be reset.
354 Exit with a status of 0 on success,
355 2 if the file hierarchy did not match the specification, and
356 1 if any other error occurred.
358 Don't attempt to set various file attributes such as the
359 ownership, mode, flags, or time
360 when creating new directories or changing existing entries.
361 This option will be most useful when used in conjunction with
365 .It Fl X Ar exclude-file
366 The specified file contains
368 patterns matching files to be excluded from
369 the specification, one to a line.
370 If the pattern contains a
372 character, it will be matched against entire pathnames (relative to
373 the starting directory); otherwise,
374 it will be matched against basenames only.
375 Comments are permitted in
380 Don't descend below mount points in the file hierarchy.
383 Specifications are mostly composed of
385 i.e. strings that specify values relating to files.
386 No keywords have default values, and if a keyword has no value set, no
387 checks based on it are performed.
389 Currently supported keywords are as follows:
390 .Bl -tag -width sha384digestxx
392 The checksum of the file using the default algorithm specified by
397 The device number to use for
402 The argument must be one of the following forms:
404 .It Ar format , Ns Ar major , Ns Ar minor
409 fields, for an operating system specified with
411 See below for valid formats.
412 .It Ar format , Ns Ar major , Ns Ar unit , Ns Ar subunit
418 fields, for an operating system specified with
420 (Currently this is only supported by the
424 Opaque number (as stored on the file system).
427 The following values for
448 The file flags as a symbolic name.
451 for information on these names.
452 If no flags are to be set the string
454 may be used to override the current default.
455 Note that the schg and sappnd flags are treated specially (see the
461 Ignore any file hierarchy below this file.
463 The file group as a numeric value.
465 The file group as a symbolic name.
467 The file the symbolic link is expected to reference.
471 cryptographic message digest of the file.
476 The current file's permissions as a numeric (octal) or symbolic
479 The number of hard links the file is expected to have.
481 Make sure this file or directory exists but otherwise ignore all attributes.
483 The file is optional; don't complain about the file if it's
484 not in the file hierarchy.
485 .It Sy ripemd160digest
491 cryptographic message digest of the file.
498 cryptographic message digest of the file.
505 cryptographic message digest of the file.
512 cryptographic message digest of the file.
519 cryptographic message digest of the file.
524 The size, in bytes, of the file.
526 Comma delimited tags to be matched with
530 These may be specified without leading or trailing commas, but will be
531 stored internally with them.
533 The last modification time of the file,
534 in second and nanoseconds.
535 The value should include a period character and exactly nine digits after
538 The type of the file; may be set to any one of the following:
540 .Bl -tag -width Sy -compact
544 character special device
557 The file owner as a numeric value.
559 The file owner as a symbolic name.
562 The default set of keywords are
574 There are four types of lines in a specification:
577 Set global values for a keyword.
578 This consists of the string
580 followed by whitespace, followed by sets of keyword/value
581 pairs, separated by whitespace.
582 Keyword/value pairs consist of a keyword, followed by an equals sign
584 followed by a value, without whitespace characters.
585 Once a keyword has been set, its value remains unchanged until either
588 Unset global values for a keyword.
589 This consists of the string
591 followed by whitespace, followed by one or more keywords,
592 separated by whitespace.
595 is specified, unset all of the keywords.
597 A file specification, consisting of a path name, followed by whitespace,
598 followed by zero or more whitespace separated keyword/value pairs.
600 The path name may be preceded by whitespace characters.
601 The path name may contain any of the standard path name matching
611 in the hierarchy will be associated with the first pattern that
616 (in VIS_CSTYLE format) to encode path names containing
617 non-printable characters.
618 Whitespace characters are encoded as
626 characters in path names are escaped by a preceding backslash
628 to distinguish them from comments.
630 Each of the keyword/value pairs consist of a keyword, followed by an
633 followed by the keyword's value, without
634 whitespace characters.
635 These values override, without changing, the global value of the
636 corresponding keyword.
638 The first path name entry listed must be a directory named
640 as this ensures that intermixing full and relative path names will
641 work consistently and correctly.
642 Multiple entries for a directory named
644 are permitted; the settings for the last such entry override those
645 of the existing entry.
647 A path name that contains a slash
649 that is not the first character will be treated as a full path
650 (relative to the root of the tree).
651 All parent directories referenced in the path name must exist.
652 The current directory path used by relative path names will be updated
654 Multiple entries for the same full path are permitted if the types
657 is given, in which case the types may differ);
658 in this case the settings for the last entry take precedence.
660 A path name that does not contain a slash will be treated as a relative path.
661 Specifying a directory will cause subsequent files to be searched
662 for in that directory hierarchy.
664 A line containing only the string
666 which causes the current directory path (used by relative paths)
670 Empty lines and lines whose first non-whitespace character is a hash
677 utility exits with a status of 0 on success, 1 if any error occurred,
678 and 2 if the file hierarchy did not match the specification.
680 .Bl -tag -width /etc/mtree -compact
682 system specification directory
687 To detect system binaries that have been
689 it is recommended that
691 be run on the file systems, and a copy of the results stored on a different
692 machine, or, at least, in encrypted form.
695 option should not be an obvious value and the final checksum should not be
696 stored on-line under any circumstances!
699 should be run against the on-line specifications and the final checksum
700 compared with the previous value.
701 While it is possible for the bad guys to change the on-line specifications
702 to conform to their modified binaries, it shouldn't be possible for them
703 to make it produce the same final checksum value.
704 If the final checksum value changes, the off-line copies of the specification
705 can be used to detect which of the binaries have actually been modified.
709 option can be used in combination with
713 to create directory hierarchies for distributions.
716 .Dl mtree -deiU -f /etc/mtree/BSD.var.dist -p /var
720 directory hierarchies at
723 .Dl mtree -deiU -f /etc/mtree/BSD.include.dist -p /usr/include
727 directory hierarchies at
730 The compatibility shims provided by the
732 option are incomplete by design.
733 Known limitations are described below.
737 flavor retains the default handling of lookup failures for the
741 keywords by replacing them with appropriate
745 keywords rather than failing and reporting an error.
748 flag is a no-op rather than causing a warning to be printed and no
749 keyword to be emitted.
750 The latter behavior is not emulated as it is potentially dangerous in
757 flavor does not replicate the historical bug that reported time as
758 seconds.nanoseconds without zero padding nanosecond values less than
813 options, and support for full paths appeared in
projects / dragonfly.git / blob