1.\" $OpenBSD: mtree.8,v 1.32 2007/05/31 19:20:26 jmc Exp $ 2.\" $NetBSD: mtree.8,v 1.4 1995/03/07 21:26:25 cgd Exp $ 3.\" 4.\" Copyright (c) 1989, 1990, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)mtree.8 8.2 (Berkeley) 12/11/93 32.\" 33.Dd $Mdocdate: May 31 2007 $ 34.Dt MTREE 8 35.Os 36.Sh NAME 37.Nm mtree 38.Nd map a directory hierarchy 39.Sh SYNOPSIS 40.Nm mtree 41.Bk -words 42.Op Fl cdeilnqrtUux 43.Op Fl f Ar spec 44.Op Fl K Ar keywords 45.Op Fl k Ar keywords 46.Op Fl p Ar path 47.Op Fl s Ar seed 48.Ek 49.Sh DESCRIPTION 50The utility 51.Nm mtree 52compares the file hierarchy rooted in the current directory against a 53specification read from the standard input. 54Messages are written to the standard output for any files whose 55characteristics do not match the specification, or which are 56missing from either the file hierarchy or the specification. 57For an explanation of the directory hierarchy, 58see 59.Xr hier 7 . 60.Pp 61The options are as follows: 62.Bl -tag -width Ds 63.It Fl c 64Print a specification for the file hierarchy to the standard output. 65.It Fl d 66Ignore everything except directory type files. 67.It Fl e 68Don't complain about files that are in the file hierarchy, but not in the 69specification. 70.It Fl f Ar spec 71Read the specification from file 72.Ar spec , 73instead of from the standard input. 74.It Fl i 75Indents the output 4 spaces each time a directory level is descended when 76creating a specification with the 77.Fl c 78option. 79This does not affect either the /set statements or the comment before each 80directory. 81It does however affect the comment before the close of each directory. 82.It Fl K Ar keywords 83Add the specified (whitespace or comma separated) keywords to the current 84set of keywords. 85.It Fl k Ar keywords 86Use the 87.Dq type 88keyword plus the specified (whitespace or comma separated) 89keywords instead of the current set of keywords. 90.It Fl l 91Do 92.Dq loose 93permissions checks, in which more stringent permissions 94will match less stringent ones. 95For example, a file marked mode 0444 will pass a check for mode 0644. 96.Dq Loose 97checks apply only to read, write and execute permissions -- in 98particular, if other bits like the sticky bit or suid/sgid bits are 99set either in the specification or the file, exact checking will be 100performed. 101This flag may not be set at the same time as the 102.Fl u 103or 104.Fl U 105flags. 106.It Fl n 107Do not emit pathname comments when creating a specification. 108Normally 109a comment is emitted before each directory and before the close of that 110directory when using the 111.Fl c 112option. 113.It Fl p Ar path 114Use the file hierarchy rooted in 115.Ar path , 116instead of the current directory. 117.It Fl q 118Quiet mode. 119Do not complain when a 120.Dq missing 121directory cannot be created because it already exists. 122This occurs when the directory is a symbolic link. 123.It Fl r 124Remove any files in the file hierarchy that are not described in the 125specification. 126.It Fl s Ar seed 127Display a single checksum to the standard error output that represents all 128of the files for which the keyword 129.Cm cksum 130was specified. 131The checksum is seeded with the specified value. 132.It Fl t 133If a file's timestamp is different from the specification, 134.Dq touch 135it to match the specification (and list as modified). 136.It Fl U 137Modify the owner, group, and permissions of existing files to match 138the specification and create any missing directories. 139User, group, and permissions must all be specified for missing directories 140to be created. 141Exit with a status of 0 on success, 1 if any error occurred; 142a mismatch is not considered an error if it was corrected. 143.It Fl u 144Same as the 145.Fl U 146option except a status of 2 is returned if the file hierarchy 147did not match the specification. 148.It Fl x 149Don't descend below mount points in the file hierarchy. 150.El 151.Pp 152Specifications are mostly composed of 153.Dq keywords 154(i.e., strings that 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 current file's flags (whitespace or comma separated) in symbolic form 167as specified by 168.Xr chflags 1 . 169The string 170.Dq none 171may be used to indicate that no flags should be set on the file. 172.It Cm gid 173The file group as a numeric value. 174.It Cm gname 175The file group as a symbolic name. 176.It Cm ignore 177Ignore any file hierarchy below this file. 178.It Cm link 179The file the symbolic link is expected to reference. 180.It Cm md5digest 181The MD5 message digest of the file. 182.It Cm mode 183The current file's permissions as a numeric (octal) or symbolic 184value. 185.It Cm nlink 186The number of hard links the file is expected to have. 187.It Cm nochange 188Do not change the attributes (owner, group, mode, etc) on a file or directory. 189.It Cm optional 190The file is optional; don't complain about the file if it's 191not in the file hierarchy. 192.It Cm rmd160digest 193The RIPEMD-160 message digest of the file. 194.It Cm sha1digest 195The SHA-1 message digest of the file. 196.It Cm size 197The size, in bytes, of the file. 198.It Cm time 199The last modification time of the file. 200.It Cm type 201The type of the file; may be set to any one of the following: 202.Pp 203.Bl -tag -width Cm -compact 204.It Cm block 205block special device 206.It Cm char 207character special device 208.It Cm dir 209directory 210.It Cm fifo 211FIFO 212.It Cm file 213regular file 214.It Cm link 215symbolic link 216.It Cm socket 217socket 218.El 219.It Cm uid 220The file owner as a numeric value. 221.It Cm uname 222The file owner as a symbolic name. 223.El 224.Pp 225The default set of keywords are 226.Cm gid , 227.Cm mode , 228.Cm nlink , 229.Cm size , 230.Cm link , 231.Cm time , 232and 233.Cm uid . 234.Pp 235There are four types of lines in a specification. 236.Pp 237The first type of line sets a global value for a keyword, and consists of 238the string 239.Dq /set 240followed by whitespace, followed by sets of keyword/value 241pairs, separated by whitespace. 242Keyword/value pairs consist of a keyword, followed by an equals sign 243.Pq Sq = , 244followed 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.Dq /unset , 250followed 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 259.Po 260.Dq [ , 261.Dq \&] , 262.Dq \&? , 263or 264.Dq \&* 265.Pc , 266in which case files in the hierarchy will be associated with the first 267pattern that they match. 268.Pp 269Each of the keyword/value pairs consist of a keyword, followed by an 270equals sign, followed by the keyword's value, without 271whitespace characters. 272These values override, without changing, the global value of the 273corresponding keyword. 274.Pp 275All paths are relative. 276Specifying a directory will cause subsequent files to be searched 277for in that directory hierarchy. 278Which brings us to the last type of line in a specification: a line 279containing only the string 280.Dq .. 281causes the current directory 282path to ascend one level. 283.Pp 284Empty lines and lines whose first non-whitespace character is a hash 285mark 286.Pq Sq # 287are ignored. 288.Pp 289The 290.Nm mtree 291utility exits with a status of 0 on success, 1 if any error occurred, 292and 2 if the file hierarchy did not match the specification. 293A status of 2 is converted to a status of 0 if the 294.Fl U 295option is used. 296.Sh FILES 297.Bl -tag -width /etc/mtree -compact 298.It Pa /etc/mtree 299system specification directory 300.El 301.Sh EXAMPLES 302To detect system binaries that have been 303.Dq trojan horsed , 304it is recommended 305that 306.Nm mtree 307.Fl cK 308.Cm sha1digest 309be run on the file systems, and a copy of the results stored on a different 310machine, or, at least, in encrypted form. 311The output file itself should be digested using the 312.Xr sha1 1 313utility. 314Then, periodically, 315.Nm mtree 316and 317.Xr sha1 1 318should be run against the on-line specifications. 319While it is possible for the bad guys to change the on-line specifications 320to conform to their modified binaries, it is believed to be 321impractical for them to create a modified specification which has 322the same SHA1 digest as the original. 323.Pp 324The 325.Fl d 326and 327.Fl u 328options can be used in combination to create directory hierarchies 329for distributions and other such things; the files in 330.Pa /etc/mtree 331were used to create almost all directories in a normal binary 332distribution. 333.Sh SEE ALSO 334.Xr chgrp 1 , 335.Xr chmod 1 , 336.Xr cksum 1 , 337.Xr md5 1 , 338.Xr rmd160 1 , 339.Xr sha1 1 , 340.Xr stat 2 , 341.Xr fts 3 , 342.Xr md5 3 , 343.Xr rmd160 3 , 344.Xr sha1 3 , 345.Xr hier 7 , 346.Xr chown 8 347.Sh HISTORY 348The 349.Nm mtree 350utility appeared in 351.Bx 4.3 Reno . 352