1.\" $NetBSD: mtree.8,v 1.34 2002/12/27 06:31:51 grant 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 22, 2002 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 cCdDelLPruUWx 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 p Ar path 53.Ek 54.Bk -words 55.Op Fl k Ar keywords 56.Ek 57.Bk -words 58.Op Fl K Ar keywords 59.Ek 60.Bk -words 61.Op Fl R Ar keywords 62.Ek 63.Bk -words 64.Op Fl E Ar tags 65.Ek 66.Bk -words 67.Op Fl I Ar tags 68.Ek 69.Bk -words 70.Op Fl N Ar dbdir 71.Ek 72.Bk -words 73.Op Fl s Ar seed 74.Ek 75.Bk -words 76.Op Fl X Ar exclude-file 77.Ek 78.Sh DESCRIPTION 79The utility 80.Nm 81compares the file hierarchy rooted in the current directory against a 82specification read from the standard input. 83Messages are written to the standard output for any files whose 84characteristics do not match the specification, or which are 85missing from either the file hierarchy or the specification. 86.Pp 87The options are as follows: 88.Bl -tag -width flag 89.It Fl c 90Print a specification for the file hierarchy to the standard output. 91.It Fl d 92Ignore everything except directory type files. 93.It Fl C 94Print 95.Pq Sq dump 96the specification as provided by 97.Fl f Ar spec 98in a format that's easier to parse with various tools. 99The full path name is always printed as the first field, and 100.Fl k , 101.Fl K , 102and 103.Fl R 104can be used to control which other keywords are printed, 105and 106.Fl E 107and 108.Fl I 109can be used to control which files are printed. 110.It Fl D 111As per 112.Fl C , 113except that the path name is always printed as the last field instead of 114the first. 115.It Fl E Ar tags 116Add the comma separated tags to the 117.Dq exclusion 118list. 119Non-directories with tags which are in the exclusion list are not printed with 120.Fl D . 121.It Fl e 122Don't complain about files that are in the file hierarchy, but not in the 123specification. 124.It Fl f Ar spec 125Read the specification from 126.Ar file , 127instead of from the standard input. 128.It Fl I Ar tags 129Add the comma separated tags to the 130.Dq inclusion 131list. 132Non-directories with tags which are in the inclusion list are printed with 133.Fl D . 134If no inclusion list is provided, the default is to display all files. 135.It Fl i 136If specified, set the schg and/or sappnd flags. 137.It Fl K Ar keywords 138Add the specified (whitespace or comma separated) keywords to the current 139set of keywords. 140If 141.Ql all 142is specified, add all of the other keywords. 143.It Fl k Ar keywords 144Use the 145.Sy type 146keyword plus the specified (whitespace or comma separated) 147keywords instead of the current set of keywords. 148If 149.Ql all 150is specified, use all of the other keywords. 151.It Fl l 152Do 153.Dq loose 154permissions checks, in which more stringent permissions 155will match less stringent ones. For example, a file marked mode 0444 156will pass a check for mode 0644. 157.Dq Loose 158checks apply only to read, write and execute permissions -- in 159particular, if other bits like the sticky bit or suid/sgid bits are 160set either in the specification or the file, exact checking will be 161performed. This flag may not be set at the same time as the 162.Fl u 163or 164.Fl U 165flags. 166.It Fl L 167Follow all symbolic links in the file hierarchy. 168.It Fl m 169If the schg and/or sappnd flags are specified, reset these flags. Note that 170this is only possible with securelevel less than 1 (i. e. in single user mode 171or while the system is running in insecure mode). See 172.Xr init 8 173for information on security levels. 174.It Fl N Ar dbdir 175Use the user database text file 176.Pa master.passwd 177and group database text file 178.Pa group 179from 180.Ar dbdir , 181rather than using the results from the system's 182.Xr getpwnam 3 183and 184.Xr getgrnam 3 185(and related) library calls. 186.It Fl p Ar path 187Use the file hierarchy rooted in 188.Ar path , 189instead of the current directory. 190.It Fl P 191Don't follow symbolic links in the file hierarchy, instead consider 192the symbolic link itself in any comparisons. 193This is the default. 194.It Fl r 195Remove any files in the file hierarchy that are not described in the 196specification. 197.It Fl R Ar keywords 198Remove the specified (whitespace or comma separated) keywords from the current 199set of keywords. 200If 201.Ql all 202is specified, remove all of the other keywords. 203.It Fl s Ar seed 204Display a single checksum to the standard error output that represents all 205of the files for which the keyword 206.Sy cksum 207was specified. 208The checksum is seeded with the specified value. 209.It Fl u 210Modify the owner, group, permissions, and flags of existing files, 211the device type of devices, and symbolic link targets, 212to match the specification. 213Create any missing directories, devices or symbolic links. 214User, group, and permissions must all be specified for missing directories 215to be created. 216Note that unless the 217.Fl i 218option is given, the schg and sappnd flags will not be set, even if 219specified. If 220.Fl m 221is given, these flags will be reset. 222Exit with a status of 0 on success, 2232 if the file hierarchy did not match the specification, and 2241 if any other error occurred. 225.It Fl U 226Same as 227.Fl u 228except that a mismatch is not considered to be an error if it was corrected. 229.It Fl W 230Don't attempt to set various file attributes such as the 231ownership, mode, flags, or time 232when creating new directories or changing existing entries. 233This option will be most useful when used in conjunction with 234.Fl u 235or 236.Fl U . 237.It Fl x 238Don't descend below mount points in the file hierarchy. 239.It Fl X Ar exclude-file 240The specified file contains 241.Xr fnmatch 3 242patterns matching files to be excluded from 243the specification, one to a line. 244If the pattern contains a 245.Ql \&/ 246character, it will be matched against entire pathnames (relative to 247the starting directory); otherwise, 248it will be matched against basenames only. 249Comments are permitted in 250the 251.Ar exclude-list 252file. 253.El 254.Pp 255Specifications are mostly composed of 256.Dq keywords , 257i.e. strings that 258that specify values relating to files. 259No keywords have default values, and if a keyword has no value set, no 260checks based on it are performed. 261.Pp 262Currently supported keywords are as follows: 263.Bl -tag -width Sy 264.It Sy cksum 265The checksum of the file using the default algorithm specified by 266the 267.Xr cksum 1 268utility. 269.It Sy device 270The device number to use for 271.Sy block 272or 273.Sy char 274file types. 275The argument must be one of the following forms: 276.Pp 277.Bl -tag -width 4n 278.It Xo 279.Sm off 280.Ar format , 281.Ar major , 282.Ar minor 283.Sm on 284.Xc 285A device with 286.Ar major 287and 288.Ar minor 289fields, for an operating system specified with 290.Ar format . 291See below for valid formats. 292.It Xo 293.Sm off 294.Ar format , 295.Ar major , 296.Ar unit , 297.Ar subunit 298.Sm on 299.Xc 300A device with 301.Ar major , 302.Ar unit , 303and 304.Ar subunit 305fields, for an operating system specified with 306.Ar format . 307(Currently this is only supported by the 308.Sy bsdos 309format.) 310.It Ar number 311Opaque number (as stored on the file system). 312.El 313.Pp 314The following values for 315.Ar format 316are recognized: 317.Sy native , 318.Sy 386bsd , 319.Sy 4bsd , 320.Sy bsdos , 321.Sy freebsd , 322.Sy hpux , 323.Sy isc , 324.Sy linux , 325.Sy netbsd , 326.Sy osf1 , 327.Sy sco , 328.Sy solaris , 329.Sy sunos , 330.Sy svr3 , 331.Sy svr4 , 332and 333.Sy ultrix . 334.Pp 335See 336.Xr mknod 8 337for more details. 338.It Sy flags 339The file flags as a symbolic name. See 340.Xr chflags 1 341for information on these names. If no flags are to be set the string 342.Ql none 343may be used to override the current default. 344Note that the schg and sappnd flags are treated specially (see the 345.Fl i 346and 347.Fl m 348options). 349.It Sy ignore 350Ignore any file hierarchy below this file. 351.It Sy gid 352The file group as a numeric value. 353.It Sy gname 354The file group as a symbolic name. 355.It Sy link 356The file the symbolic link is expected to reference. 357.It Sy md5 358The 359.Tn MD5 360cryptographic message digest of the file. 361.It Sy md5digest 362Synonym for 363.Sy md5 . 364.It Sy mode 365The current file's permissions as a numeric (octal) or symbolic 366value. 367.It Sy nlink 368The number of hard links the file is expected to have. 369.It Sy optional 370The file is optional; don't complain about the file if it's 371not in the file hierarchy. 372.It Sy rmd160 373The 374.Tn RMD-160 375cryptographic message digest of the file. 376.It Sy rmd160digest 377Synonym for 378.Sy rmd160 . 379.It Sy sha1 380The 381.Tn SHA-1 382cryptographic message digest of the file. 383.It Sy sha1digest 384Synonym for 385.Sy sha1 . 386.It Sy size 387The size, in bytes, of the file. 388.It Sy tags 389Comma delimited tags to be matched with 390.Fl E 391and 392.Fl I . 393These may be specified without leading or trailing commas, but will be 394stored internally with them. 395.It Sy time 396The last modification time of the file. 397.It Sy type 398The type of the file; may be set to any one of the following: 399.Pp 400.Bl -tag -width Sy -compact 401.It Sy block 402block special device 403.It Sy char 404character special device 405.It Sy dir 406directory 407.It Sy fifo 408fifo 409.It Sy file 410regular file 411.It Sy link 412symbolic link 413.It Sy socket 414socket 415.El 416.It Sy uid 417The file owner as a numeric value. 418.It Sy uname 419The file owner as a symbolic name. 420.El 421.Pp 422The default set of keywords are 423.Sy flags , 424.Sy gid , 425.Sy link , 426.Sy mode , 427.Sy nlink , 428.Sy size , 429.Sy time , 430.Sy type , 431and 432.Sy uid . 433.Pp 434There are four types of lines in a specification: 435.Pp 436.Bl -enum 437.It 438Set global values for a keyword. 439This consists of the string 440.Ql /set 441followed by whitespace, followed by sets of keyword/value 442pairs, separated by whitespace. 443Keyword/value pairs consist of a keyword, followed by an equals sign 444.Pq Ql = , 445followed by a value, without whitespace characters. 446Once a keyword has been set, its value remains unchanged until either 447reset or unset. 448.It 449Unset global values for a keyword. 450This consists of the string 451.Ql /unset , 452followed by whitespace, followed by one or more keywords, 453separated by whitespace. 454If 455.Ql all 456is specified, unset all of the keywords. 457.It 458A file specification, consisting of a path name, followed by whitespace, 459followed by zero or more whitespace separated keyword/value pairs. 460.Pp 461The path name may be preceded by whitespace characters. 462The path name may contain any of the standard path name matching 463characters 464.Po 465.Ql [ , 466.Ql \] , 467.Ql ? 468or 469.Ql * 470.Pc , 471in which case files 472in the hierarchy will be associated with the first pattern that 473they match. 474.Nm 475uses 476.Xr strsvis 3 477(in VIS_CSTYLE format) to encode path names containing 478non-printable characters. Whitespace characters are encoded as 479.Ql \es 480(space), 481.Ql \et 482(tab), and 483.Ql \en 484(new line). 485.Ql # 486characters in path names are escaped by a preceding backslash 487.Ql \e 488to distinguish them from comments. 489.Pp 490Each of the keyword/value pairs consist of a keyword, followed by an 491equals sign 492.Pq Ql = , 493followed by the keyword's value, without 494whitespace characters. 495These values override, without changing, the global value of the 496corresponding keyword. 497.Pp 498The first path name entry listed must be a directory named 499.Ql \&. , 500as this ensures that intermixing full and relative path names will 501work consistently and correctly. 502Multiple entries for a directory named 503.Ql \&. 504are permitted; the settings for the last such entry override those 505of the existing entry. 506.Pp 507A path name that contains a slash 508.Pq Ql / 509that is not the first character will be treated as a full path 510(relative to the root of the tree). 511All parent directories referenced in the path name must exist. 512The current directory path used by relative path names will be updated 513appropriately. 514Multiple entries for the same full path are permitted if the types 515are the same; 516in this case the settings for the last entry take precedence. 517.Pp 518A path name that does not contain a slash will be treated as a relative path. 519Specifying a directory will cause subsequent files to be searched 520for in that directory hierarchy. 521.It 522A line containing only the string 523.Ql \&.. 524which causes the current directory path (used by relative paths) 525to ascend one level. 526.El 527.Pp 528Empty lines and lines whose first non-whitespace character is a hash 529mark 530.Pq Ql # 531are ignored. 532.Pp 533The 534.Nm 535utility exits with a status of 0 on success, 1 if any error occurred, 536and 2 if the file hierarchy did not match the specification. 537.Sh FILES 538.Bl -tag -width /etc/mtree -compact 539.It Pa /etc/mtree 540system specification directory 541.El 542.Sh EXAMPLES 543To detect system binaries that have been 544.Dq trojan horsed , 545it is recommended that 546.Nm 547be run on the file systems, and a copy of the results stored on a different 548machine, or, at least, in encrypted form. 549The seed for the 550.Fl s 551option should not be an obvious value and the final checksum should not be 552stored on-line under any circumstances! 553Then, periodically, 554.Nm 555should be run against the on-line specifications and the final checksum 556compared with the previous value. 557While it is possible for the bad guys to change the on-line specifications 558to conform to their modified binaries, it shouldn't be possible for them 559to make it produce the same final checksum value. 560If the final checksum value changes, the off-line copies of the specification 561can be used to detect which of the binaries have actually been modified. 562.Pp 563The 564.Fl d 565and 566.Fl u 567options can be used in combination to create directory hierarchies 568for distributions and other such things. 569.Sh SEE ALSO 570.Xr chflags 1 , 571.Xr chgrp 1 , 572.Xr chmod 1 , 573.Xr cksum 1 , 574.Xr md5 1 , 575.Xr stat 2 , 576.Xr fnmatch 3 , 577.Xr fts 3 , 578.Xr strsvis 3 , 579.Xr chown 8 , 580.Xr mknod 8 581.Sh HISTORY 582The 583.Nm 584utility appeared in 585.Bx 4.3 Reno . 586The 587.Sy optional 588keyword appeared in 589.Nx 1.2 . 590The 591.Fl U 592flag appeared in 593.Nx 1.3 . 594The 595.Sy flags 596and 597.Sy md5 598keywords, and 599.Fl i 600and 601.Fl m 602flags 603appeared in 604.Nx 1.4 . 605The 606.Sy device , 607.Sy rmd160 , 608.Sy sha1 , 609.Sy tags , 610and 611.Sy all 612keywords, 613.Fl D , 614.Fl E , 615.Fl I , 616.Fl l , 617.Fl L , 618.Fl N , 619.Fl P , 620.Fl R , 621.Fl W , 622and 623.Fl X 624flags, and support for full paths appeared in 625.Nx 1.6 . 626