1.\" $NetBSD: mtree.8,v 1.12 1999/11/07 20:23:01 wennmach Exp $ 2.\" 3.\" Copyright (c) 1989, 1990, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgement: 16.\" This product includes software developed by the University of 17.\" California, Berkeley and its contributors. 18.\" 4. Neither the name of the University nor the names of its contributors 19.\" may be used to endorse or promote products derived from this software 20.\" without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.\" @(#)mtree.8 8.2 (Berkeley) 12/11/93 35.\" 36.Dd December 11, 1993 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 cderUux 45.Bk -words 46.Op Fl i | Fl m 47.Ek 48.Bk -words 49.Op Fl f Ar spec 50.Ek 51.Bk -words 52.Op Fl K Ar keywords 53.Ek 54.Bk -words 55.Op Fl k Ar keywords 56.Ek 57.Bk -words 58.Op Fl p Ar path 59.Ek 60.Bk -words 61.Op Fl s Ar seed 62.Ek 63.Sh DESCRIPTION 64The utility 65.Nm 66compares 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 specification, 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 c 75Print a specification for the file hierarchy to the standard output. 76.It Fl d 77Ignore everything except directory type files. 78.It Fl e 79Don't complain about files that are in the file hierarchy, but not in the 80specification. 81.It Fl f 82Read the specification from 83.Ar file , 84instead of from the standard input. 85.It Fl i 86If specified, set the schg and/or sappnd flags. 87.It Fl K 88Add the specified (whitespace or comma separated) keywords to the current 89set of keywords. 90.It Fl k 91Use the ``type'' keyword plus the specified (whitespace or comma separated) 92keywords instead of the current set of keywords. 93.It Fl m 94If the schg and/or sappnd flags are specified, reset these flags. Note that 95this is only possible with securelevel less than 1 (i. e. in single user mode 96or while the system is running in insecure mode). See 97.Xr init 8 98for information on security levels. 99.It Fl p 100Use the file hierarchy rooted in 101.Ar path , 102instead of the current directory. 103.It Fl r 104Remove any files in the file hierarchy that are not described in the 105specification. 106.It Fl s 107Display a single checksum to the standard error output that represents all 108of the files for which the keyword 109.Cm cksum 110was specified. 111The checksum is seeded with the specified value. 112.It Fl U 113Modify the owner, group, permissions, and flags of existing files to match 114the specification and create any missing directories. 115User, group, and permissions must all be specified for missing directories 116to be created. 117Note that unless the 118.Fl i 119option is given, the schg and sappnd flags will not be set, even if 120specified. If 121.Fl m 122is given, these flags will be reset. 123Exit with a status of 0 on success, 1 if any error occurred; 124a mismatch is not considered to be an error if it was corrected. 125.It Fl u 126Same as 127.Fl U 128except a status of 2 is returned if the file hierarchy did not match 129the specification. 130.It Fl x 131Don't descend below mount points in the file hierarchy. 132.El 133.Pp 134Specifications are mostly composed of ``keywords'', i.e. strings that 135that specify values relating to files. 136No keywords have default values, and if a keyword has no value set, no 137checks based on it are performed. 138.Pp 139Currently supported keywords are as follows: 140.Bl -tag -width Cm 141.It Cm cksum 142The checksum of the file using the default algorithm specified by 143the 144.Xr cksum 1 145utility. 146.It Cm flags 147The file flags as a symbolic name. See 148.Xr chflags 1 149for information on these names. If no flags are to be set the string 150.Dq none 151may be used to override the current default. 152Note that the schg and sappnd flags are treated specially (see the 153.Fl i 154and 155.Fl m 156options). 157.It Cm ignore 158Ignore any file hierarchy below this file. 159.It Cm gid 160The file group as a numeric value. 161.It Cm gname 162The file group as a symbolic name. 163.It Cm link 164The file the symbolic link is expected to reference. 165.It Cm md5 166The MD5 cryptographic checksum of the file. 167.It Cm mode 168The current file's permissions as a numeric (octal) or symbolic 169value. 170.It Cm nlink 171The number of hard links the file is expected to have. 172.It Cm optional 173The file is optional; don't complain about the file if it's 174not in the file hierarchy. 175.It Cm uid 176The file owner as a numeric value. 177.It Cm uname 178The file owner as a symbolic name. 179.It Cm size 180The size, in bytes, of the file. 181.It Cm time 182The last modification time of the file. 183.It Cm type 184The type of the file; may be set to any one of the following: 185.sp 186.Bl -tag -width Cm -compact 187.It Cm block 188block special device 189.It Cm char 190character special device 191.It Cm dir 192directory 193.It Cm fifo 194fifo 195.It Cm file 196regular file 197.It Cm link 198symbolic link 199.It Cm socket 200socket 201.El 202.El 203.Pp 204The default set of keywords are 205.Cm flags , 206.Cm gid , 207.Cm link , 208.Cm mode , 209.Cm nlink , 210.Cm size , 211.Cm time , 212and 213.Cm uid . 214.Pp 215There are four types of lines in a specification. 216.Pp 217The first type of line sets a global value for a keyword, and consists of 218the string ``/set'' followed by whitespace, followed by sets of keyword/value 219pairs, separated by whitespace. 220Keyword/value pairs consist of a keyword, followed by an equals sign 221(``=''), followed by a value, without whitespace characters. 222Once a keyword has been set, its value remains unchanged until either 223reset or unset. 224.Pp 225The second type of line unsets keywords and consists of the string 226``/unset'', followed by whitespace, followed by one or more keywords, 227separated by whitespace. 228.Pp 229The third type of line is a file specification and consists of a file 230name, followed by whitespace, followed by zero or more whitespace 231separated keyword/value pairs. 232The file name may be preceded by whitespace characters. 233The file name may contain any of the standard file name matching 234characters (``['', ``]'', ``?'' or ``*''), in which case files 235in the hierarchy will be associated with the first pattern that 236they match. 237.Nm 238uses strvis(3) (in VIS_CSTYLE format) to encode file names containing 239non-printable characters. Whitespace characters are encoded as 240``\es'' (space), ``\et'' (tab), and ``\en'' (new line). 241``#'' characters in file names are escaped by a preceding backslash (``\e'') 242to distinguish them from comments. 243.Pp 244Each of the keyword/value pairs consist of a keyword, followed by an 245equals sign (``=''), followed by the keyword's value, without 246whitespace characters. 247These values override, without changing, the global value of the 248corresponding keyword. 249.Pp 250All paths are relative. 251Specifying a directory will cause subsequent files to be searched 252for in that directory hierarchy. 253Which brings us to the last type of line in a specification: a line 254containing only the string 255.Dq Nm \&.. 256causes the current directory 257path to ascend one level. 258.Pp 259Empty lines and lines whose first non-whitespace character is a hash 260mark (``#'') are ignored. 261.Pp 262The 263.Nm 264utility exits with a status of 0 on success, 1 if any error occurred, 265and 2 if the file hierarchy did not match the specification. 266.Sh EXAMPLES 267To detect system binaries that have been ``trojan horsed'', it is recommended 268that 269.Nm 270be run on the file systems, and a copy of the results stored on a different 271machine, or, at least, in encrypted form. 272The seed for the 273.Fl s 274option should not be an obvious value and the final checksum should not be 275stored on-line under any circumstances! 276Then, periodically, 277.Nm 278should be run against the on-line specifications and the final checksum 279compared with the previous value. 280While it is possible for the bad guys to change the on-line specifications 281to conform to their modified binaries, it shouldn't be possible for them 282to make it produce the same final checksum value. 283If the final checksum value changes, the off-line copies of the specification 284can be used to detect which of the binaries have actually been modified. 285.Pp 286The 287.Fl d 288and 289.Fl u 290options can be used in combination to create directory hierarchies 291for distributions and other such things. 292.Sh FILES 293.Bl -tag -width /etc/mtree -compact 294.It Pa /etc/mtree 295system specification directory 296.El 297.Sh SEE ALSO 298.Xr chflags 1 , 299.Xr chgrp 1 , 300.Xr chmod 1 , 301.Xr cksum 1 , 302.Xr md5 1 , 303.Xr stat 2 , 304.Xr strvis 3 , 305.Xr fts 3 , 306.Xr chown 8 307.Sh HISTORY 308The 309.Nm 310utility appeared in 311.Bx 4.3 Reno . 312