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