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