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