| blob | 8a150b6a92cc30496104704e802dd411b399b51e |
1 .\" $NetBSD: mtree.8,v 1.53 2010/01/20 14:00:48 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 January 20, 2010
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 t
262 Modify the modified time of existing files, the device type of devices, and
263 symbolic link targets, to match the specification.
264 .It Fl U
265 Same as
266 .Fl u
267 except that a mismatch is not considered to be an error if it was corrected.
268 .It Fl u
269 Modify the owner, group, permissions, and flags of existing files,
270 the device type of devices, and symbolic link targets,
271 to match the specification.
272 Create any missing directories, devices or symbolic links.
273 User, group, and permissions must all be specified for missing directories
274 to be created.
275 Note that unless the
276 .Fl i
277 option is given, the schg and sappnd flags will not be set, even if
278 specified.
279 If
280 .Fl m
281 is given, these flags will be reset.
282 Exit with a status of 0 on success,
283 2 if the file hierarchy did not match the specification, and
284 1 if any other error occurred.
285 .It Fl W
286 Don't attempt to set various file attributes such as the
287 ownership, mode, flags, or time
288 when creating new directories or changing existing entries.
289 This option will be most useful when used in conjunction with
290 .Fl u
291 or
292 .Fl U .
293 .It Fl X Ar exclude-file
294 The specified file contains
295 .Xr fnmatch 3
296 patterns matching files to be excluded from
297 the specification, one to a line.
298 If the pattern contains a
299 .Ql \&/
300 character, it will be matched against entire pathnames (relative to
301 the starting directory); otherwise,
302 it will be matched against basenames only.
303 Comments are permitted in
304 the
305 .Ar exclude-list
306 file.
307 .It Fl x
308 Don't descend below mount points in the file hierarchy.
309 .El
310 .Pp
311 Specifications are mostly composed of
312 .Dq keywords ,
313 i.e. strings that
314 that specify values relating to files.
315 No keywords have default values, and if a keyword has no value set, no
316 checks based on it are performed.
317 .Pp
318 Currently supported keywords are as follows:
319 .Bl -tag -width sha384digestxx
320 .It Sy cksum
321 The checksum of the file using the default algorithm specified by
322 the
323 .Xr cksum 1
324 utility.
325 .It Sy device
326 The device number to use for
327 .Sy block
328 or
329 .Sy char
330 file types.
331 The argument must be one of the following forms:
332 .Pp
333 .Bl -tag -width 4n
334 .It Ar format , Ns Ar major , Ns Ar minor
335 A device with
336 .Ar major
337 and
338 .Ar minor
339 fields, for an operating system specified with
340 .Ar format .
341 See below for valid formats.
342 .It Ar format , Ns Ar major , Ns Ar unit , Ns Ar subunit
343 A device with
344 .Ar major ,
345 .Ar unit ,
346 and
347 .Ar subunit
348 fields, for an operating system specified with
349 .Ar format .
350 (Currently this is only supported by the
351 .Sy bsdos
352 format.)
353 .It Ar number
354 Opaque number (as stored on the file system).
355 .El
356 .Pp
357 The following values for
358 .Ar format
359 are recognized:
360 .Sy native ,
361 .Sy 386bsd ,
362 .Sy 4bsd ,
363 .Sy bsdos ,
364 .Sy freebsd ,
365 .Sy hpux ,
366 .Sy isc ,
367 .Sy linux ,
368 .Sy netbsd ,
369 .Sy osf1 ,
370 .Sy sco ,
371 .Sy solaris ,
372 .Sy sunos ,
373 .Sy svr3 ,
374 .Sy svr4 ,
375 and
376 .Sy ultrix .
377 .Pp
378 See
379 .Xr mknod 8
380 for more details.
381 .It Sy flags
382 The file flags as a symbolic name.
383 See
384 .Xr chflags 1
385 for information on these names.
386 If no flags are to be set the string
387 .Ql none
388 may be used to override the current default.
389 Note that the schg and sappnd flags are treated specially (see the
390 .Fl i
391 and
392 .Fl m
393 options).
394 .It Sy ignore
395 Ignore any file hierarchy below this file.
396 .It Sy gid
397 The file group as a numeric value.
398 .It Sy gname
399 The file group as a symbolic name.
400 .It Sy link
401 The file the symbolic link is expected to reference.
402 .It Sy md5
403 The
404 .Tn MD5
405 cryptographic message digest of the file.
406 .It Sy md5digest
407 Synonym for
408 .Sy md5 .
409 .It Sy mode
410 The current file's permissions as a numeric (octal) or symbolic
411 value.
412 .It Sy nlink
413 The number of hard links the file is expected to have.
414 .It Sy optional
415 The file is optional; don't complain about the file if it's
416 not in the file hierarchy.
417 .It Sy rmd160
418 The
419 .Tn RMD-160
420 cryptographic message digest of the file.
421 .It Sy rmd160digest
422 Synonym for
423 .Sy rmd160 .
424 .It Sy sha1
425 The
426 .Tn SHA-1
427 cryptographic message digest of the file.
428 .It Sy sha1digest
429 Synonym for
430 .Sy sha1 .
431 .It Sy sha256
432 The 256-bits
433 .Tn SHA-2
434 cryptographic message digest of the file.
435 .It Sy sha256digest
436 Synonym for
437 .Sy sha256 .
438 .It Sy sha384
439 The 384-bits
440 .Tn SHA-2
441 cryptographic message digest of the file.
442 .It Sy sha384digest
443 Synonym for
444 .Sy sha384 .
445 .It Sy sha512
446 The 512-bits
447 .Tn SHA-2
448 cryptographic message digest of the file.
449 .It Sy sha512digest
450 Synonym for
451 .Sy sha512 .
452 .It Sy size
453 The size, in bytes, of the file.
454 .It Sy tags
455 Comma delimited tags to be matched with
456 .Fl E
457 and
458 .Fl I .
459 These may be specified without leading or trailing commas, but will be
460 stored internally with them.
461 .It Sy time
462 The last modification time of the file.
463 .It Sy type
464 The type of the file; may be set to any one of the following:
465 .Pp
466 .Bl -tag -width Sy -compact
467 .It Sy block
468 block special device
469 .It Sy char
470 character special device
471 .It Sy dir
472 directory
473 .It Sy fifo
474 fifo
475 .It Sy file
476 regular file
477 .It Sy link
478 symbolic link
479 .It Sy socket
480 socket
481 .El
482 .It Sy uid
483 The file owner as a numeric value.
484 .It Sy uname
485 The file owner as a symbolic name.
486 .El
487 .Pp
488 The default set of keywords are
489 .Sy flags ,
490 .Sy gid ,
491 .Sy link ,
492 .Sy mode ,
493 .Sy nlink ,
494 .Sy size ,
495 .Sy time ,
496 .Sy type ,
497 and
498 .Sy uid .
499 .Pp
500 There are four types of lines in a specification:
501 .Pp
502 .Bl -enum
503 .It
504 Set global values for a keyword.
505 This consists of the string
506 .Ql /set
507 followed by whitespace, followed by sets of keyword/value
508 pairs, separated by whitespace.
509 Keyword/value pairs consist of a keyword, followed by an equals sign
510 .Pq Ql = ,
511 followed by a value, without whitespace characters.
512 Once a keyword has been set, its value remains unchanged until either
513 reset or unset.
514 .It
515 Unset global values for a keyword.
516 This consists of the string
517 .Ql /unset ,
518 followed by whitespace, followed by one or more keywords,
519 separated by whitespace.
520 If
521 .Ql all
522 is specified, unset all of the keywords.
523 .It
524 A file specification, consisting of a path name, followed by whitespace,
525 followed by zero or more whitespace separated keyword/value pairs.
526 .Pp
527 The path name may be preceded by whitespace characters.
528 The path name may contain any of the standard path name matching
529 characters
530 .Po
531 .Ql \&[ ,
532 .Ql \&] ,
533 .Ql \&?
534 or
535 .Ql *
536 .Pc ,
537 in which case files
538 in the hierarchy will be associated with the first pattern that
539 they match.
540 .Nm
541 uses
542 .Xr strsvis 3
543 (in VIS_CSTYLE format) to encode path names containing
544 non-printable characters.
545 Whitespace characters are encoded as
546 .Ql \es
547 (space),
548 .Ql \et
549 (tab), and
550 .Ql \en
551 (new line).
552 .Ql #
553 characters in path names are escaped by a preceding backslash
554 .Ql \e
555 to distinguish them from comments.
556 .Pp
557 Each of the keyword/value pairs consist of a keyword, followed by an
558 equals sign
559 .Pq Ql = ,
560 followed by the keyword's value, without
561 whitespace characters.
562 These values override, without changing, the global value of the
563 corresponding keyword.
564 .Pp
565 The first path name entry listed must be a directory named
566 .Ql \&. ,
567 as this ensures that intermixing full and relative path names will
568 work consistently and correctly.
569 Multiple entries for a directory named
570 .Ql \&.
571 are permitted; the settings for the last such entry override those
572 of the existing entry.
573 .Pp
574 A path name that contains a slash
575 .Pq Ql /
576 that is not the first character will be treated as a full path
577 (relative to the root of the tree).
578 All parent directories referenced in the path name must exist.
579 The current directory path used by relative path names will be updated
580 appropriately.
581 Multiple entries for the same full path are permitted if the types
582 are the same (unless
583 .Fl M
584 is given, and then the types may differ);
585 in this case the settings for the last entry take precedence.
586 .Pp
587 A path name that does not contain a slash will be treated as a relative path.
588 Specifying a directory will cause subsequent files to be searched
589 for in that directory hierarchy.
590 .It
591 A line containing only the string
592 .Ql \&..
593 which causes the current directory path (used by relative paths)
594 to ascend one level.
595 .El
596 .Pp
597 Empty lines and lines whose first non-whitespace character is a hash
598 mark
599 .Pq Ql #
600 are ignored.
601 .Pp
602 The
603 .Nm
604 utility exits with a status of 0 on success, 1 if any error occurred,
605 and 2 if the file hierarchy did not match the specification.
606 .Sh FILES
607 .Bl -tag -width /etc/mtree -compact
608 .It Pa /etc/mtree
609 system specification directory
610 .El
611 .Sh EXAMPLES
612 To detect system binaries that have been
613 .Dq trojan horsed ,
614 it is recommended that
615 .Nm
616 be run on the file systems, and a copy of the results stored on a different
617 machine, or, at least, in encrypted form.
618 The seed for the
619 .Fl s
620 option should not be an obvious value and the final checksum should not be
621 stored on-line under any circumstances!
622 Then, periodically,
623 .Nm
624 should be run against the on-line specifications and the final checksum
625 compared with the previous value.
626 While it is possible for the bad guys to change the on-line specifications
627 to conform to their modified binaries, it shouldn't be possible for them
628 to make it produce the same final checksum value.
629 If the final checksum value changes, the off-line copies of the specification
630 can be used to detect which of the binaries have actually been modified.
631 .Pp
632 The
633 .Fl d
634 and
635 .Fl u
636 options can be used in combination to create directory hierarchies
637 for distributions and other such things.
638 .Sh SEE ALSO
639 .Xr chflags 1 ,
640 .Xr chgrp 1 ,
641 .Xr chmod 1 ,
642 .Xr cksum 1 ,
643 .Xr stat 2 ,
644 .Xr fnmatch 3 ,
645 .Xr fts 3 ,
646 .Xr strsvis 3 ,
647 .Xr chown 8 ,
648 .Xr mknod 8
649 .Sh HISTORY
650 The
651 .Nm
652 utility appeared in
653 .Bx 4.3 Reno .
654 The
655 .Sy optional
656 keyword appeared in
657 .Nx 1.2 .
658 The
659 .Fl U
660 option appeared in
661 .Nx 1.3 .
662 The
663 .Sy flags
664 and
665 .Sy md5
666 keywords, and
667 .Fl i
668 and
669 .Fl m
670 options
671 appeared in
672 .Nx 1.4 .
673 The
674 .Sy device ,
675 .Sy rmd160 ,
676 .Sy sha1 ,
677 .Sy tags ,
678 and
679 .Sy all
680 keywords,
681 .Fl D ,
682 .Fl E ,
683 .Fl I ,
684 .Fl l ,
685 .Fl L ,
686 .Fl N ,
687 .Fl P ,
688 .Fl R ,
689 .Fl W ,
690 and
691 .Fl X
692 options, and support for full paths appeared in
693 .Nx 1.6 .
694 The
695 .Sy sha256 ,
696 .Sy sha384 ,
697 and
698 .Sy sha512
699 keywords appeared in
700 .Nx 3.0 .
701 The
702 .Fl S
703 option appeared in
704 .Nx 6.0 .