| blob | 15068021a9b05c3c7c8d80b623979d76770d9098 |
1 .\" $NetBSD: mtree.8,v 1.50 2009/04/08 19:39:23 wiz Exp $
2 .\"
3 .\" Copyright (c) 1989, 1990, 1993
4 .\" The Regents of the University of California. All rights reserved.
5 .\"
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
8 .\" are met:
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.
17 .\"
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
28 .\" SUCH DAMAGE.
29 .\"
30 .\" Copyright (c) 2001-2004 The NetBSD Foundation, Inc.
31 .\" All rights reserved.
32 .\"
33 .\" This code is derived from software contributed to The NetBSD Foundation
34 .\" by Luke Mewburn of Wasabi Systems.
35 .\"
36 .\" Redistribution and use in source and binary forms, with or without
37 .\" modification, are permitted provided that the following conditions
38 .\" are met:
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.
44 .\"
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.
56 .\"
57 .\" @(#)mtree.8 8.2 (Berkeley) 12/11/93
58 .\"
59 .Dd April 9, 2009
60 .Dt MTREE 8
61 .Os
62 .Sh NAME
63 .Nm mtree
64 .Nd map a directory hierarchy
65 .Sh SYNOPSIS
66 .Nm
67 .Op Fl CcDdeLlMPrSUuWx
68 .Op Fl i | Fl m
69 .Op Fl E Ar tags
70 .Op Fl f Ar spec
71 .Op Fl I Ar tags
72 .Op Fl K Ar keywords
73 .Op Fl k Ar keywords
74 .Op Fl N Ar dbdir
75 .Op Fl p Ar path
76 .Op Fl R Ar keywords
77 .Op Fl s Ar seed
78 .Op Fl X Ar exclude-file
79 .Sh DESCRIPTION
80 The
81 .Nm
82 utility compares a file hierarchy against a specification,
83 creates a specification for a file hierarchy, or modifies
84 a specification.
85 .Pp
86 The default action, if not overridden by command line options,
87 is to compare the file hierarchy rooted in the current directory
88 against a specification read from the standard input.
89 Messages are written to the standard output for any files whose
90 characteristics do not match the specification, or which are
91 missing from either the file hierarchy or the specification.
92 .Pp
93 The options are as follows:
94 .Bl -tag -width Xxxexcludexfilexx
95 .It Fl C
96 Convert a specification into
97 a format that's easier to parse with various tools.
98 The input specification is read from standard input or
99 from the file given by
100 .Fl f Ar spec .
101 In the output, each file or directory is represented using a single line
102 (which might be very long).
103 The full path name
104 (beginning with
105 .Dq \&./ )
106 is always printed as the first field;
107 .Fl k ,
108 .Fl K ,
109 and
110 .Fl R
111 can be used to control which other keywords are printed;
112 .Fl E
113 and
114 .Fl I
115 can be used to control which files are printed;
116 .Fl S
117 option can be used to sort the output.
118 .It Fl c
119 Print a specification for the file hierarchy originating at
120 the current working directory (or the directory provided by
121 .Fl p Ar path )
122 to the standard output.
123 The output is in a style using relative path names.
124 .It Fl D
125 As per
126 .Fl C ,
127 except that the path name is always printed as the last field instead of
128 the first.
129 .It Fl d
130 Ignore everything except directory type files.
131 .It Fl E Ar tags
132 Add the comma separated tags to the
133 .Dq exclusion
134 list.
135 Non-directories with tags which are in the exclusion list are not printed with
136 .Fl C
137 and
138 .Fl D .
139 .It Fl e
140 Don't complain about files that are in the file hierarchy, but not in the
141 specification.
142 .It Fl f Ar spec
143 Read the specification from
144 .Ar file ,
145 instead of from the standard input.
146 .It Fl I Ar tags
147 Add the comma separated tags to the
148 .Dq inclusion
149 list.
150 Non-directories with tags which are in the inclusion list are printed with
151 .Fl C
152 and
153 .Fl D .
154 If no inclusion list is provided, the default is to display all files.
155 .It Fl i
156 If specified, set the schg and/or sappnd flags.
157 .It Fl K Ar keywords
158 Add the specified (whitespace or comma separated) keywords to the current
159 set of keywords.
160 If
161 .Ql all
162 is specified, add all of the other keywords.
163 .It Fl k Ar keywords
164 Use the
165 .Sy type
166 keyword plus the specified (whitespace or comma separated)
167 keywords instead of the current set of keywords.
168 If
169 .Ql all
170 is specified, use all of the other keywords.
171 If the
172 .Sy type
173 keyword is not desired, suppress it with
174 .Fl R Ar type .
175 .It Fl L
176 Follow all symbolic links in the file hierarchy.
177 .It Fl l
178 Do
179 .Dq loose
180 permissions checks, in which more stringent permissions
181 will match less stringent ones.
182 For example, a file marked mode 0444
183 will pass a check for mode 0644.
184 .Dq Loose
185 checks apply only to read, write and execute permissions -- in
186 particular, if other bits like the sticky bit or suid/sgid bits are
187 set either in the specification or the file, exact checking will be
188 performed.
189 This option may not be set at the same time as the
190 .Fl u
191 or
192 .Fl U
193 option.
194 .It Fl M
195 Permit merging of specification entries with different types,
196 with the last entry take precedence.
197 .It Fl m
198 If the schg and/or sappnd flags are specified, reset these flags.
199 Note that this is only possible with securelevel less than 1 (i.e.,
200 in single user mode or while the system is running in insecure
201 mode).
202 See
203 .Xr init 8
204 for information on security levels.
205 .It Fl N Ar dbdir
206 Use the user database text file
207 .Pa master.passwd
208 and group database text file
209 .Pa group
210 from
211 .Ar dbdir ,
212 rather than using the results from the system's
213 .Xr getpwnam 3
214 and
215 .Xr getgrnam 3
216 (and related) library calls.
217 .It Fl P
218 Don't follow symbolic links in the file hierarchy, instead consider
219 the symbolic link itself in any comparisons.
220 This is the default.
221 .It Fl p Ar path
222 Use the file hierarchy rooted in
223 .Ar path ,
224 instead of the current directory.
225 .It Fl R Ar keywords
226 Remove the specified (whitespace or comma separated) keywords from the current
227 set of keywords.
228 If
229 .Ql all
230 is specified, remove all of the other keywords.
231 .It Fl r
232 Remove any files in the file hierarchy that are not described in the
233 specification.
234 .It Fl S
235 When reading a specification into an internal data structure,
236 sort the entries.
237 Sorting will affect the order of the output produced by the
238 .Fl C
239 or
240 .Fl D
241 options, and will also affect the order in which
242 missing entries are created or reported when a directory tree is checked
243 against a specification.
244 .Pp
245 The sort order is the same as that used by the
246 .Fl c
247 option, which is that entries within the same directory are
248 sorted in the order used by
249 .Xr strcmp 3 ,
250 except that entries for subdirectories sort after other entries.
251 By default, if the
252 .Fl S
253 option is not used, entries within the same directory are collected
254 together (separated from entries for other directories), but not sorted.
255 .It Fl s Ar seed
256 Display a single checksum to the standard error output that represents all
257 of the files for which the keyword
258 .Sy cksum
259 was specified.
260 The checksum is seeded with the specified value.
261 .It Fl U
262 Same as
263 .Fl u
264 except that a mismatch is not considered to be an error if it was corrected.
265 .It Fl u
266 Modify the owner, group, permissions, and flags of existing files,
267 the device type of devices, and symbolic link targets,
268 to match the specification.
269 Create any missing directories, devices or symbolic links.
270 User, group, and permissions must all be specified for missing directories
271 to be created.
272 Note that unless the
273 .Fl i
274 option is given, the schg and sappnd flags will not be set, even if
275 specified.
276 If
277 .Fl m
278 is given, these flags will be reset.
279 Exit with a status of 0 on success,
280 2 if the file hierarchy did not match the specification, and
281 1 if any other error occurred.
282 .It Fl W
283 Don't attempt to set various file attributes such as the
284 ownership, mode, flags, or time
285 when creating new directories or changing existing entries.
286 This option will be most useful when used in conjunction with
287 .Fl u
288 or
289 .Fl U .
290 .It Fl X Ar exclude-file
291 The specified file contains
292 .Xr fnmatch 3
293 patterns matching files to be excluded from
294 the specification, one to a line.
295 If the pattern contains a
296 .Ql \&/
297 character, it will be matched against entire pathnames (relative to
298 the starting directory); otherwise,
299 it will be matched against basenames only.
300 Comments are permitted in
301 the
302 .Ar exclude-list
303 file.
304 .It Fl x
305 Don't descend below mount points in the file hierarchy.
306 .El
307 .Pp
308 Specifications are mostly composed of
309 .Dq keywords ,
310 i.e. strings that
311 that specify values relating to files.
312 No keywords have default values, and if a keyword has no value set, no
313 checks based on it are performed.
314 .Pp
315 Currently supported keywords are as follows:
316 .Bl -tag -width sha384digestxx
317 .It Sy cksum
318 The checksum of the file using the default algorithm specified by
319 the
320 .Xr cksum 1
321 utility.
322 .It Sy device
323 The device number to use for
324 .Sy block
325 or
326 .Sy char
327 file types.
328 The argument must be one of the following forms:
329 .Pp
330 .Bl -tag -width 4n
331 .It Ar format , Ns Ar major , Ns Ar minor
332 A device with
333 .Ar major
334 and
335 .Ar minor
336 fields, for an operating system specified with
337 .Ar format .
338 See below for valid formats.
339 .It Ar format , Ns Ar major , Ns Ar unit , Ns Ar subunit
340 A device with
341 .Ar major ,
342 .Ar unit ,
343 and
344 .Ar subunit
345 fields, for an operating system specified with
346 .Ar format .
347 (Currently this is only supported by the
348 .Sy bsdos
349 format.)
350 .It Ar number
351 Opaque number (as stored on the file system).
352 .El
353 .Pp
354 The following values for
355 .Ar format
356 are recognized:
357 .Sy native ,
358 .Sy 386bsd ,
359 .Sy 4bsd ,
360 .Sy bsdos ,
361 .Sy freebsd ,
362 .Sy hpux ,
363 .Sy isc ,
364 .Sy linux ,
365 .Sy netbsd ,
366 .Sy osf1 ,
367 .Sy sco ,
368 .Sy solaris ,
369 .Sy sunos ,
370 .Sy svr3 ,
371 .Sy svr4 ,
372 and
373 .Sy ultrix .
374 .Pp
375 See
376 .Xr mknod 8
377 for more details.
378 .It Sy flags
379 The file flags as a symbolic name.
380 See
381 .Xr chflags 1
382 for information on these names.
383 If no flags are to be set the string
384 .Ql none
385 may be used to override the current default.
386 Note that the schg and sappnd flags are treated specially (see the
387 .Fl i
388 and
389 .Fl m
390 options).
391 .It Sy ignore
392 Ignore any file hierarchy below this file.
393 .It Sy gid
394 The file group as a numeric value.
395 .It Sy gname
396 The file group as a symbolic name.
397 .It Sy link
398 The file the symbolic link is expected to reference.
399 .It Sy md5
400 The
401 .Tn MD5
402 cryptographic message digest of the file.
403 .It Sy md5digest
404 Synonym for
405 .Sy md5 .
406 .It Sy mode
407 The current file's permissions as a numeric (octal) or symbolic
408 value.
409 .It Sy nlink
410 The number of hard links the file is expected to have.
411 .It Sy optional
412 The file is optional; don't complain about the file if it's
413 not in the file hierarchy.
414 .It Sy rmd160
415 The
416 .Tn RMD-160
417 cryptographic message digest of the file.
418 .It Sy rmd160digest
419 Synonym for
420 .Sy rmd160 .
421 .It Sy sha1
422 The
423 .Tn SHA-1
424 cryptographic message digest of the file.
425 .It Sy sha1digest
426 Synonym for
427 .Sy sha1 .
428 .It Sy sha256
429 The 256-bits
430 .Tn SHA-2
431 cryptographic message digest of the file.
432 .It Sy sha256digest
433 Synonym for
434 .Sy sha256 .
435 .It Sy sha384
436 The 384-bits
437 .Tn SHA-2
438 cryptographic message digest of the file.
439 .It Sy sha384digest
440 Synonym for
441 .Sy sha384 .
442 .It Sy sha512
443 The 512-bits
444 .Tn SHA-2
445 cryptographic message digest of the file.
446 .It Sy sha512digest
447 Synonym for
448 .Sy sha512 .
449 .It Sy size
450 The size, in bytes, of the file.
451 .It Sy tags
452 Comma delimited tags to be matched with
453 .Fl E
454 and
455 .Fl I .
456 These may be specified without leading or trailing commas, but will be
457 stored internally with them.
458 .It Sy time
459 The last modification time of the file.
460 .It Sy type
461 The type of the file; may be set to any one of the following:
462 .Pp
463 .Bl -tag -width Sy -compact
464 .It Sy block
465 block special device
466 .It Sy char
467 character special device
468 .It Sy dir
469 directory
470 .It Sy fifo
471 fifo
472 .It Sy file
473 regular file
474 .It Sy link
475 symbolic link
476 .It Sy socket
477 socket
478 .El
479 .It Sy uid
480 The file owner as a numeric value.
481 .It Sy uname
482 The file owner as a symbolic name.
483 .El
484 .Pp
485 The default set of keywords are
486 .Sy flags ,
487 .Sy gid ,
488 .Sy link ,
489 .Sy mode ,
490 .Sy nlink ,
491 .Sy size ,
492 .Sy time ,
493 .Sy type ,
494 and
495 .Sy uid .
496 .Pp
497 There are four types of lines in a specification:
498 .Pp
499 .Bl -enum
500 .It
501 Set global values for a keyword.
502 This consists of the string
503 .Ql /set
504 followed by whitespace, followed by sets of keyword/value
505 pairs, separated by whitespace.
506 Keyword/value pairs consist of a keyword, followed by an equals sign
507 .Pq Ql = ,
508 followed by a value, without whitespace characters.
509 Once a keyword has been set, its value remains unchanged until either
510 reset or unset.
511 .It
512 Unset global values for a keyword.
513 This consists of the string
514 .Ql /unset ,
515 followed by whitespace, followed by one or more keywords,
516 separated by whitespace.
517 If
518 .Ql all
519 is specified, unset all of the keywords.
520 .It
521 A file specification, consisting of a path name, followed by whitespace,
522 followed by zero or more whitespace separated keyword/value pairs.
523 .Pp
524 The path name may be preceded by whitespace characters.
525 The path name may contain any of the standard path name matching
526 characters
527 .Po
528 .Ql \&[ ,
529 .Ql \&] ,
530 .Ql \&?
531 or
532 .Ql *
533 .Pc ,
534 in which case files
535 in the hierarchy will be associated with the first pattern that
536 they match.
537 .Nm
538 uses
539 .Xr strsvis 3
540 (in VIS_CSTYLE format) to encode path names containing
541 non-printable characters.
542 Whitespace characters are encoded as
543 .Ql \es
544 (space),
545 .Ql \et
546 (tab), and
547 .Ql \en
548 (new line).
549 .Ql #
550 characters in path names are escaped by a preceding backslash
551 .Ql \e
552 to distinguish them from comments.
553 .Pp
554 Each of the keyword/value pairs consist of a keyword, followed by an
555 equals sign
556 .Pq Ql = ,
557 followed by the keyword's value, without
558 whitespace characters.
559 These values override, without changing, the global value of the
560 corresponding keyword.
561 .Pp
562 The first path name entry listed must be a directory named
563 .Ql \&. ,
564 as this ensures that intermixing full and relative path names will
565 work consistently and correctly.
566 Multiple entries for a directory named
567 .Ql \&.
568 are permitted; the settings for the last such entry override those
569 of the existing entry.
570 .Pp
571 A path name that contains a slash
572 .Pq Ql /
573 that is not the first character will be treated as a full path
574 (relative to the root of the tree).
575 All parent directories referenced in the path name must exist.
576 The current directory path used by relative path names will be updated
577 appropriately.
578 Multiple entries for the same full path are permitted if the types
579 are the same (unless
580 .Fl M
581 is given, and then the types may differ);
582 in this case the settings for the last entry take precedence.
583 .Pp
584 A path name that does not contain a slash will be treated as a relative path.
585 Specifying a directory will cause subsequent files to be searched
586 for in that directory hierarchy.
587 .It
588 A line containing only the string
589 .Ql \&..
590 which causes the current directory path (used by relative paths)
591 to ascend one level.
592 .El
593 .Pp
594 Empty lines and lines whose first non-whitespace character is a hash
595 mark
596 .Pq Ql #
597 are ignored.
598 .Pp
599 The
600 .Nm
601 utility exits with a status of 0 on success, 1 if any error occurred,
602 and 2 if the file hierarchy did not match the specification.
603 .Sh FILES
604 .Bl -tag -width /etc/mtree -compact
605 .It Pa /etc/mtree
606 system specification directory
607 .El
608 .Sh EXAMPLES
609 To detect system binaries that have been
610 .Dq trojan horsed ,
611 it is recommended that
612 .Nm
613 be run on the file systems, and a copy of the results stored on a different
614 machine, or, at least, in encrypted form.
615 The seed for the
616 .Fl s
617 option should not be an obvious value and the final checksum should not be
618 stored on-line under any circumstances!
619 Then, periodically,
620 .Nm
621 should be run against the on-line specifications and the final checksum
622 compared with the previous value.
623 While it is possible for the bad guys to change the on-line specifications
624 to conform to their modified binaries, it shouldn't be possible for them
625 to make it produce the same final checksum value.
626 If the final checksum value changes, the off-line copies of the specification
627 can be used to detect which of the binaries have actually been modified.
628 .Pp
629 The
630 .Fl d
631 and
632 .Fl u
633 options can be used in combination to create directory hierarchies
634 for distributions and other such things.
635 .Sh SEE ALSO
636 .Xr chflags 1 ,
637 .Xr chgrp 1 ,
638 .Xr chmod 1 ,
639 .Xr cksum 1 ,
640 .Xr stat 2 ,
641 .Xr fnmatch 3 ,
642 .Xr fts 3 ,
643 .Xr strsvis 3 ,
644 .Xr chown 8 ,
645 .Xr mknod 8
646 .Sh HISTORY
647 The
648 .Nm
649 utility appeared in
650 .Bx 4.3 Reno .
651 The
652 .Sy optional
653 keyword appeared in
654 .Nx 1.2 .
655 The
656 .Fl U
657 option appeared in
658 .Nx 1.3 .
659 The
660 .Sy flags
661 and
662 .Sy md5
663 keywords, and
664 .Fl i
665 and
666 .Fl m
667 options
668 appeared in
669 .Nx 1.4 .
670 The
671 .Sy device ,
672 .Sy rmd160 ,
673 .Sy sha1 ,
674 .Sy tags ,
675 and
676 .Sy all
677 keywords,
678 .Fl D ,
679 .Fl E ,
680 .Fl I ,
681 .Fl l ,
682 .Fl L ,
683 .Fl N ,
684 .Fl P ,
685 .Fl R ,
686 .Fl W ,
687 and
688 .Fl X
689 options, and support for full paths appeared in
690 .Nx 1.6 .
691 The
692 .Sy sha256 ,
693 .Sy sha384 ,
694 and
695 .Sy sha512
696 keywords appeared in
697 .Nx 3.0 .
698 The
699 .Fl S
700 option appeared in
701 .Nx 6.0 .