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