| blob | 8254270456f257421abc2d6353f2280489b5dc16 |
1 .\" Copyright (c) 1989, 1990, 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 .\" 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.
19 .\"
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
30 .\" SUCH DAMAGE.
31 .\"
32 .\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93
33 .\" $FreeBSD: src/usr.sbin/mtree/mtree.8,v 1.16.2.11 2003/03/11 22:31:29 trhodes Exp $
34 .\" $DragonFly: src/usr.sbin/mtree/mtree.8,v 1.6 2007/10/20 13:43:00 swildner Exp $
35 .\"
36 .Dd February 26, 1999
37 .Dt MTREE 8
38 .Os
39 .Sh NAME
40 .Nm mtree
41 .Nd map a directory hierarchy
42 .Sh SYNOPSIS
43 .Nm
44 .Op Fl LPUcdeinqrux
45 .Bk -words
46 .Op Fl f Ar spec
47 .Ek
48 .Bk -words
49 .Op Fl K Ar keywords
50 .Ek
51 .Bk -words
52 .Op Fl k Ar keywords
53 .Ek
54 .Bk -words
55 .Op Fl p Ar path
56 .Ek
57 .Bk -words
58 .Op Fl s Ar seed
59 .Ek
60 .Bk -words
61 .Op Fl X Ar exclude-list
62 .Ek
63 .Sh DESCRIPTION
64 The
65 .Nm
66 utility compares the file hierarchy rooted in the current directory against a
67 specification read from the standard input.
68 Messages are written to the standard output for any files whose
69 characteristics do not match the specifications, or which are
70 missing from either the file hierarchy or the specification.
71 .Pp
72 The options are as follows:
73 .Bl -tag -width flag
74 .It Fl L
75 Follow all symbolic links in the file hierarchy.
76 .It Fl P
77 Don't follow symbolic links in the file hierarchy, instead consider
78 the symbolic link itself in any comparisons. This is the default.
79 .It Fl U
80 Modify the owner, group and permissions of existing files to match
81 the specification and create any missing directories or symbolic links.
82 User, group and permissions must all be specified for missing directories
83 to be created.
84 Corrected mismatches are not considered errors.
85 .It Fl c
86 Print a specification for the file hierarchy to the standard output.
87 .It Fl d
88 Ignore everything except directory type files.
89 .It Fl e
90 Don't complain about files that are in the file hierarchy, but not in the
91 specification.
92 .It Fl i
93 Indent the output 4 spaces each time a directory level is descended when
94 create a specification with the
95 .Fl c
96 option.
97 This does not affect either the /set statements or the comment before each
98 directory.
99 It does however affect the comment before the close of each directory.
100 .It Fl n
101 Do not emit pathname comments when creating a specification. Normally
102 a comment is emitted before each directory and before the close of that
103 directory when using the
104 .Fl c
105 option.
106 .It Fl q
107 Quiet mode. Do not complain when a
108 .Dq missing
109 directory cannot be created because it already exists.
110 This occurs when the directory is a symbolic link.
111 .It Fl r
112 Remove any files in the file hierarchy that are not described in the
113 specification.
114 .It Fl u
115 Same as
116 .Fl U
117 except a status of 2 is returned if the file hierarchy did not match
118 the specification.
119 .It Fl x
120 Don't descend below mount points in the file hierarchy.
121 .It Fl f Ar file
122 Read the specification from
123 .Ar file ,
124 instead of from the standard input.
125 .It Fl K Ar keywords
126 Add the specified (whitespace or comma separated)
127 .Ar keywords
128 to the current set of keywords.
129 .It Fl k Ar keywords
130 Use the ``type'' keyword plus the specified (whitespace or comma separated)
131 .Ar keywords
132 instead of the current set of keywords.
133 .It Fl p Ar path
134 Use the file hierarchy rooted in
135 .Ar path ,
136 instead of the current directory.
137 .It Fl s Ar seed
138 Display a single checksum to the standard error output that represents all
139 of the files for which the keyword
140 .Cm cksum
141 was specified.
142 The checksum is seeded with the specified value.
143 .It Fl X Ar exclude-list
144 The specified file contains
145 .Xr fnmatch 3
146 patterns matching files to be excluded from
147 the specification, one to a line.
148 If the pattern contains a
149 .Ql \&/
150 character, it will be matched against entire pathnames (relative to
151 the starting directory); otherwise,
152 it will be matched against basenames only. No comments are allowed in
153 the
154 .Ar exclude-list
155 file.
156 .El
157 .Pp
158 Specifications are mostly composed of ``keywords'', i.e. strings
159 that specify values relating to files.
160 No keywords have default values, and if a keyword has no value set, no
161 checks based on it are performed.
162 .Pp
163 Currently supported keywords are as follows:
164 .Bl -tag -width Cm
165 .It Cm cksum
166 The checksum of the file using the default algorithm specified by
167 the
168 .Xr cksum 1
169 utility.
170 .It Cm flags
171 The file flags as a symbolic name. See
172 .Xr chflags 1
173 for information on these names. If no flags are to be set the string
174 .Dq none
175 may be used to override the current default.
176 .It Cm ignore
177 Ignore any file hierarchy below this file.
178 .It Cm gid
179 The file group as a numeric value.
180 .It Cm gname
181 The file group as a symbolic name.
182 .It Cm md5digest
183 The MD5 message digest of the file.
184 .It Cm sha1digest
185 The
186 .Tn FIPS
187 160-1
188 .Pq Dq Tn SHA-1
189 message digest of the file.
190 .It Cm ripemd160digest
191 The
192 .Tn RIPEMD160
193 message digest of the file.
194 .It Cm mode
195 The current file's permissions as a numeric (octal) or symbolic
196 value.
197 .It Cm nlink
198 The number of hard links the file is expected to have.
199 .It Cm nochange
200 Make sure this file or directory exists but otherwise ignore all attributes.
201 .It Cm uid
202 The file owner as a numeric value.
203 .It Cm uname
204 The file owner as a symbolic name.
205 .It Cm size
206 The size, in bytes, of the file.
207 .It Cm link
208 The file the symbolic link is expected to reference.
209 .It Cm time
210 The last modification time of the file.
211 .It Cm type
212 The type of the file; may be set to any one of the following:
213 .Pp
214 .Bl -tag -width Cm -compact
215 .It Cm block
216 block special device
217 .It Cm char
218 character special device
219 .It Cm dir
220 directory
221 .It Cm fifo
222 fifo
223 .It Cm file
224 regular file
225 .It Cm link
226 symbolic link
227 .It Cm socket
228 socket
229 .El
230 .El
231 .Pp
232 The default set of keywords are
233 .Cm flags ,
234 .Cm gid ,
235 .Cm mode ,
236 .Cm nlink ,
237 .Cm size ,
238 .Cm link ,
239 .Cm time ,
240 and
241 .Cm uid .
242 .Pp
243 There are four types of lines in a specification.
244 .Pp
245 The first type of line sets a global value for a keyword, and consists of
246 the string ``/set'' followed by whitespace, followed by sets of keyword/value
247 pairs, separated by whitespace.
248 Keyword/value pairs consist of a keyword, followed by an equals sign
249 (``=''), followed by a value, without whitespace characters.
250 Once a keyword has been set, its value remains unchanged until either
251 reset or unset.
252 .Pp
253 The second type of line unsets keywords and consists of the string
254 ``/unset'', followed by whitespace, followed by one or more keywords,
255 separated by whitespace.
256 .Pp
257 The third type of line is a file specification and consists of a file
258 name, followed by whitespace, followed by zero or more whitespace
259 separated keyword/value pairs.
260 The file name may be preceded by whitespace characters.
261 The file name may contain any of the standard file name matching
262 characters (``['', ``]'', ``?'' or ``*''), in which case files
263 in the hierarchy will be associated with the first pattern that
264 they match.
265 .Pp
266 Each of the keyword/value pairs consist of a keyword, followed by an
267 equals sign (``=''), followed by the keyword's value, without
268 whitespace characters.
269 These values override, without changing, the global value of the
270 corresponding keyword.
271 .Pp
272 All paths are relative.
273 Specifying a directory will cause subsequent files to be searched
274 for in that directory hierarchy.
275 Which brings us to the last type of line in a specification: a line
276 containing only the string
277 .Dq Pa ..\&
278 causes the current directory
279 path to ascend one level.
280 .Pp
281 Empty lines and lines whose first non-whitespace character is a hash
282 mark (``#'') are ignored.
283 .Pp
284 The
285 .Nm
286 utility exits with a status of 0 on success, 1 if any error occurred,
287 and 2 if the file hierarchy did not match the specification.
288 A status of 2 is converted to a status of 0 if the
289 .Fl U
290 option is used.
291 .Sh FILES
292 .Bl -tag -width /etc/mtree -compact
293 .It Pa /etc/mtree
294 system specification directory
295 .El
296 .Sh EXAMPLES
297 To detect system binaries that have been ``trojan horsed'', it is recommended
298 that
299 .Nm
300 .Fl K
301 .Cm sha1digest
302 be run on the file systems, and a copy of the results stored on a different
303 machine, or, at least, in encrypted form.
304 The output file itself should be digested using the
305 .Xr md5 1
306 utility.
307 Then, periodically,
308 .Nm
309 and
310 .Xr md5 1
311 should be run against the on-line specifications.
312 While it is possible for the bad guys to change the on-line specifications
313 to conform to their modified binaries, it is believed to be
314 impractical for them to create a modified specification which has
315 the same MD5 digest as the original.
316 .Pp
317 The
318 .Fl d
319 and
320 .Fl u
321 options can be used in combination to create directory hierarchies
322 for distributions and other such things; the files in
323 .Pa /etc/mtree
324 were used to create almost all directories in this
325 .Dx
326 distribution.
327 .Pp
328 To create an
329 .Pa /etc/mtree
330 style BSD.*.dist file, use
331 .Nm
332 .Fl c
333 .Fl d
334 .Fl i
335 .Fl n
336 .Fl k
337 .Cm uname,gname,mode,nochange .
338 .Sh DIAGNOSTICS
339 .Ex -std
340 .Sh SEE ALSO
341 .Xr chflags 1 ,
342 .Xr chgrp 1 ,
343 .Xr chmod 1 ,
344 .Xr cksum 1 ,
345 .Xr md5 1 ,
346 .Xr stat 2 ,
347 .Xr fts 3 ,
348 .Xr md5 3 ,
349 .Xr chown 8
350 .Sh HISTORY
351 The
352 .Nm
353 utility appeared in
354 .Bx 4.3 Reno .
355 The
356 .Tn MD5
357 digest capability was added in
358 .Fx 2.1 ,
359 in response to the widespread use of programs which can spoof
360 .Xr cksum 1 .
361 The
362 .Tn SHA-1
363 and
364 .Tn RIPEMD160
365 digests were added in
366 .Fx 4.0 ,
367 as new attacks have demonstrated weaknesses in
368 .Tn MD5 .
369 Support for file flags was added in
370 .Fx 4.0 ,
371 and mostly comes from
372 .Nx .