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