1.\" $OpenBSD: mtree.8,v 1.42 2022/02/18 23:17:16 jsg 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: February 18 2022 $ 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 sha256digest 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 sha256digest 197The SHA-256 message digest of the file. 198.It Cm size 199The size, in bytes, of the file. 200.It Cm time 201The last modification time of the file. 202.It Cm type 203The type of the file; may be set to any one of the following: 204.Pp 205.Bl -tag -width Cm -compact 206.It Cm block 207block special device 208.It Cm char 209character special device 210.It Cm dir 211directory 212.It Cm fifo 213FIFO 214.It Cm file 215regular file 216.It Cm link 217symbolic link 218.It Cm socket 219socket 220.El 221.It Cm uid 222The file owner as a numeric value. 223.It Cm uname 224The file owner as a symbolic name. 225.El 226.Pp 227The default set of keywords are 228.Cm gid , 229.Cm mode , 230.Cm nlink , 231.Cm size , 232.Cm link , 233.Cm time , 234and 235.Cm uid . 236.Pp 237There are four types of lines in a specification. 238.Pp 239The first type of line sets a global value for a keyword, and consists of 240the string 241.Dq /set 242followed 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.Pq Sq = , 246followed by a value, without whitespace characters. 247Once a keyword has been set, its value remains unchanged until either 248reset or unset. 249.Pp 250The second type of line unsets keywords and consists of the string 251.Dq /unset , 252followed by whitespace, followed by one or more keywords, 253separated by whitespace. 254.Pp 255The third type of line is a file specification and consists of a file 256name, followed by whitespace, followed by zero or more whitespace 257separated keyword/value pairs. 258The file name may be preceded by whitespace characters. 259The file name may contain any of the standard file name matching 260characters 261.Po 262.Dq \&[ , 263.Dq \&] , 264.Dq \&? , 265or 266.Dq \&* 267.Pc , 268in which case files in the hierarchy will be associated with the first 269pattern that they match. 270.Pp 271Each of the keyword/value pairs consist of a keyword, followed by an 272equals sign, followed by the keyword's value, without 273whitespace characters. 274These values override, without changing, the global value of the 275corresponding keyword. 276.Pp 277All paths are relative. 278Specifying a directory will cause subsequent files to be searched 279for in that directory hierarchy. 280Which brings us to the last type of line in a specification: a line 281containing only the string 282.Dq .. 283causes the current directory 284path to ascend one level. 285.Pp 286Empty lines and lines whose first non-whitespace character is a hash 287mark 288.Pq Sq # 289are ignored. 290.Sh FILES 291.Bl -tag -width /etc/mtree -compact 292.It Pa /etc/mtree 293system specification directory 294.El 295.Sh EXIT STATUS 296The 297.Nm mtree 298utility exits with a status of 0 on success, 1 if any error occurred, 299and 2 if the file hierarchy did not match the specification. 300A status of 2 is converted to a status of 0 if the 301.Fl U 302option is used. 303.Sh EXAMPLES 304To detect system binaries that have been 305.Dq trojan horsed , 306it is recommended 307that 308.Nm mtree 309.Fl cK 310.Cm sha256digest 311be run on the file systems, and a copy of the results stored on a different 312machine or, at least, in encrypted form. 313The output file itself should be digested using the 314.Xr sha256 1 315utility. 316Then, periodically, 317.Nm mtree 318and 319.Xr sha256 1 320should be run against the on-line specifications. 321While it is possible for attackers to change the on-line specifications 322to conform to their modified binaries, it is believed to be 323impractical for them to create a modified specification which has 324the same SHA-256 digest as the original. 325.Pp 326The 327.Fl d 328and 329.Fl u 330options can be used in combination to create directory hierarchies 331for distributions and other such things; the files in 332.Pa /etc/mtree 333were used to create almost all directories in a normal binary 334distribution. 335.Sh SEE ALSO 336.Xr chgrp 1 , 337.Xr chmod 1 , 338.Xr cksum 1 , 339.Xr md5 1 , 340.Xr stat 2 , 341.Xr fts_open 3 , 342.Xr MD5Init 3 , 343.Xr RMD160Init 3 , 344.Xr SHA1Init 3 , 345.Xr SHA256Init 3 , 346.Xr hier 7 , 347.Xr chown 8 348.Sh HISTORY 349The 350.Nm mtree 351utility appeared in 352.Bx 4.3 Reno . 353