1 .\" Copyright (c) 1989, 1990, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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 .\" 3. All advertising materials mentioning features or use of this software
13 .\" must display the following acknowledgement:
14 .\" This product includes software developed by the University of
15 .\" California, Berkeley and its contributors.
16 .\" 4. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93
40 .Nd map a directory hierarchy
60 .Op Fl X Ar exclude-list
65 compares the file hierarchy rooted in the current directory against a
66 specification read from the standard input.
67 Messages are written to the standard output for any files whose
68 characteristics do not match the specifications, or which are
69 missing from either the file hierarchy or the specification.
71 The options are as follows:
74 Follow all symbolic links in the file hierarchy.
76 Don't follow symbolic links in the file hierarchy, instead consider
77 the symbolic link itself in any comparisons. This is the default.
79 Modify the owner, group and permissions of existing files to match
80 the specification and create any missing directories or symbolic links.
81 User, group and permissions must all be specified for missing directories
83 Corrected mismatches are not considered errors.
85 Print a specification for the file hierarchy to the standard output.
87 Ignore everything except directory type files.
89 Don't complain about files that are in the file hierarchy, but not in the
92 Indent the output 4 spaces each time a directory level is descended when
93 create a specification with the
96 This does not affect either the /set statements or the comment before each
98 It does however affect the comment before the close of each directory.
100 Do not emit pathname comments when creating a specification. Normally
101 a comment is emitted before each directory and before the close of that
102 directory when using the
106 Quiet mode. Do not complain when a
108 directory cannot be created because it already exists.
109 This occurs when the directory is a symbolic link.
111 Remove any files in the file hierarchy that are not described in the
116 except a status of 2 is returned if the file hierarchy did not match
119 Don't descend below mount points in the file hierarchy.
121 Read the specification from
123 instead of from the standard input.
125 Add the specified (whitespace or comma separated)
127 to the current set of keywords.
129 Use the ``type'' keyword plus the specified (whitespace or comma separated)
131 instead of the current set of keywords.
133 Use the file hierarchy rooted in
135 instead of the current directory.
137 Display a single checksum to the standard error output that represents all
138 of the files for which the keyword
141 The checksum is seeded with the specified value.
142 .It Fl X Ar exclude-list
143 The specified file contains
145 patterns matching files to be excluded from
146 the specification, one to a line.
147 If the pattern contains a
149 character, it will be matched against entire pathnames (relative to
150 the starting directory); otherwise,
151 it will be matched against basenames only. No comments are allowed in
157 Specifications are mostly composed of ``keywords'', i.e. strings that
158 that specify values relating to files.
159 No keywords have default values, and if a keyword has no value set, no
160 checks based on it are performed.
162 Currently supported keywords are as follows:
165 The checksum of the file using the default algorithm specified by
170 The file flags as a symbolic name. See
172 for information on these names. If no flags are to be set the string
174 may be used to override the current default.
176 Ignore any file hierarchy below this file.
178 The file group as a numeric value.
180 The file group as a symbolic name.
182 The MD5 message digest of the file.
188 message digest of the file.
189 .It Cm ripemd160digest
192 message digest of the file.
194 The current file's permissions as a numeric (octal) or symbolic
197 The number of hard links the file is expected to have.
199 Make sure this file or directory exists but otherwise ignore all attributes.
201 The file owner as a numeric value.
203 The file owner as a symbolic name.
205 The size, in bytes, of the file.
207 The file the symbolic link is expected to reference.
209 The last modification time of the file.
211 The type of the file; may be set to any one of the following:
213 .Bl -tag -width Cm -compact
217 character special device
231 The default set of keywords are
242 There are four types of lines in a specification.
244 The first type of line sets a global value for a keyword, and consists of
245 the string ``/set'' followed by whitespace, followed by sets of keyword/value
246 pairs, separated by whitespace.
247 Keyword/value pairs consist of a keyword, followed by an equals sign
248 (``=''), followed by a value, without whitespace characters.
249 Once a keyword has been set, its value remains unchanged until either
252 The second type of line unsets keywords and consists of the string
253 ``/unset'', followed by whitespace, followed by one or more keywords,
254 separated by whitespace.
256 The third type of line is a file specification and consists of a file
257 name, followed by whitespace, followed by zero or more whitespace
258 separated keyword/value pairs.
259 The file name may be preceded by whitespace characters.
260 The file name may contain any of the standard file name matching
261 characters (``['', ``]'', ``?'' or ``*''), in which case files
262 in the hierarchy will be associated with the first pattern that
265 Each of the keyword/value pairs consist of a keyword, followed by an
266 equals sign (``=''), followed by the keyword's value, without
267 whitespace characters.
268 These values override, without changing, the global value of the
269 corresponding keyword.
271 All paths are relative.
272 Specifying a directory will cause subsequent files to be searched
273 for in that directory hierarchy.
274 Which brings us to the last type of line in a specification: a line
275 containing only the string
277 causes the current directory
278 path to ascend one level.
280 Empty lines and lines whose first non-whitespace character is a hash
281 mark (``#'') are ignored.
285 utility exits with a status of 0 on success, 1 if any error occurred,
286 and 2 if the file hierarchy did not match the specification.
287 A status of 2 is converted to a status of 0 if the
291 To detect system binaries that have been ``trojan horsed'', it is recommended
296 be run on the filesystems, and a copy of the results stored on a different
297 machine, or, at least, in encrypted form.
298 The output file itself should be digested using the
305 should be run against the on-line specifications.
306 While it is possible for the bad guys to change the on-line specifications
307 to conform to their modified binaries, it is believed to be
308 impractical for them to create a modified specification which has
309 the same MD5 digest as the original.
315 options can be used in combination to create directory hierarchies
316 for distributions and other such things; the files in
318 were used to create almost all directories in this
322 .Bl -tag -width /etc/mtree -compact
324 system specification directory
345 digest capability was added in
347 in response to the widespread use of programs which can spoof
353 digests were added in
355 as new attacks have demonstrated weaknesses in
357 Support for file flags was added in
359 and mostly comes from