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