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