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