1.\" $NetBSD: mtree.8,v 1.67 2012/12/20 20:31:01 wiz 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.\" 45.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 46.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 47.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 48.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 49.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 50.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 51.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 52.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 53.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 54.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 55.\" POSSIBILITY OF SUCH DAMAGE. 56.\" 57.\" @(#)mtree.8 8.2 (Berkeley) 12/11/93 58.\" 59.Dd December 20, 2012 60.Dt MTREE 8 61.Os 62.Sh NAME 63.Nm mtree 64.Nd map a directory hierarchy 65.Sh SYNOPSIS 66.Nm 67.Op Fl bCcDdejLlMnPqrStUuWx 68.Op Fl i | Fl m 69.Op Fl E Ar tags 70.Op Fl F Ar flavor 71.Op Fl f Ar spec 72.Op Fl I Ar tags 73.Op Fl K Ar keywords 74.Op Fl k Ar keywords 75.Op Fl N Ar dbdir 76.Op Fl p Ar path 77.Op Fl R Ar keywords 78.Op Fl s Ar seed 79.Op Fl X Ar exclude-file 80.Sh DESCRIPTION 81The 82.Nm 83utility compares a file hierarchy against a specification, 84creates a specification for a file hierarchy, or modifies 85a specification. 86.Pp 87The default action, if not overridden by command line options, 88is to compare the file hierarchy rooted in the current directory 89against a specification read from the standard input. 90Messages are written to the standard output for any files whose 91characteristics do not match the specification, or which are 92missing from either the file hierarchy or the specification. 93.Pp 94The options are as follows: 95.Bl -tag -width Xxxexcludexfilexx 96.It Fl b 97Suppress blank lines before entering and after exiting directories. 98.It Fl C 99Convert a specification into 100a format that's easier to parse with various tools. 101The input specification is read from standard input or 102from the file given by 103.Fl f Ar spec . 104In the output, each file or directory is represented using a single line 105(which might be very long). 106The full path name 107(beginning with 108.Dq \&./ ) 109is always printed as the first field; 110.Fl K , 111.Fl k , 112and 113.Fl R 114can be used to control which other keywords are printed; 115.Fl E 116and 117.Fl I 118can be used to control which files are printed; 119and the 120.Fl S 121option can be used to sort the output. 122.It Fl c 123Print a specification for the file hierarchy originating at 124the current working directory (or the directory provided by 125.Fl p Ar path ) 126to the standard output. 127The output is in a style using relative path names. 128.It Fl D 129As per 130.Fl C , 131except that the path name is always printed as the last field instead of 132the first. 133.It Fl d 134Ignore everything except directory type files. 135.It Fl E Ar tags 136Add the comma separated tags to the 137.Dq exclusion 138list. 139Non-directories with tags which are in the exclusion list are not printed with 140.Fl C 141and 142.Fl D . 143.It Fl e 144Don't complain about files that are in the file hierarchy, but not in the 145specification. 146.It Fl F Ar flavor 147Set the compatibility flavor of the 148.Nm 149utility. 150The 151.Ar flavor 152can be one of 153.Sy mtree , 154.Sy freebsd9 , 155or 156.Sy netbsd6 . 157The default is 158.Sy mtree . 159The 160.Sy freebsd9 161and 162.Sy netbsd6 163flavors attempt to preserve output compatiblity and command line option 164backward compatibility with 165.Fx 9.0 166and 167.Nx 6.0 168respectively. 169.It Fl f Ar spec 170Read the specification from 171.Ar file , 172instead of from the standard input. 173.Pp 174If this option is specified twice, the two specifications are compared 175to each other rather than to the file hierarchy. 176The specifications will be sorted like output generated using 177.Fl c . 178The output format in this case is somewhat reminiscent of 179.Xr comm 1 , 180having "in first spec only", "in second spec only", and "different" 181columns, prefixed by zero, one and two TAB characters respectively. 182Each entry in the "different" column occupies two lines, one from each 183specification. 184.It Fl I Ar tags 185Add the comma separated tags to the 186.Dq inclusion 187list. 188Non-directories with tags which are in the inclusion list are printed with 189.Fl C 190and 191.Fl D . 192If no inclusion list is provided, the default is to display all files. 193.It Fl i 194If specified, set the schg and/or sappnd flags. 195.It Fl j 196Indent the output 4 spaces each time a directory level is descended when 197creating a specification with the 198.Fl c 199option. 200This does not affect either the /set statements or the comment before each 201directory. 202It does however affect the comment before the close of each directory. 203This is the equivalent of the 204.Fl i 205option in the 206.Fx 207version of 208.Nm . 209.It Fl K Ar keywords 210Add the specified (whitespace or comma separated) keywords to the current 211set of keywords. 212If 213.Ql all 214is specified, add all of the other keywords. 215.It Fl k Ar keywords 216Use the 217.Sy type 218keyword plus the specified (whitespace or comma separated) 219keywords instead of the current set of keywords. 220If 221.Ql all 222is specified, use all of the other keywords. 223If the 224.Sy type 225keyword is not desired, suppress it with 226.Fl R Ar type . 227.It Fl L 228Follow all symbolic links in the file hierarchy. 229.It Fl l 230Do 231.Dq loose 232permissions checks, in which more stringent permissions 233will match less stringent ones. 234For example, a file marked mode 0444 235will pass a check for mode 0644. 236.Dq Loose 237checks apply only to read, write and execute permissions -- in 238particular, if other bits like the sticky bit or suid/sgid bits are 239set either in the specification or the file, exact checking will be 240performed. 241This option may not be set at the same time as the 242.Fl U 243or 244.Fl u 245option. 246.It Fl M 247Permit merging of specification entries with different types, 248with the last entry taking precedence. 249.It Fl m 250If the schg and/or sappnd flags are specified, reset these flags. 251Note that this is only possible with securelevel less than 1 (i.e., 252in single user mode or while the system is running in insecure 253mode). 254See 255.Xr init 8 256for information on security levels. 257.It Fl n 258Do not emit pathname comments when creating a specification. 259Normally 260a comment is emitted before each directory and before the close of that 261directory when using the 262.Fl c 263option. 264.It Fl N Ar dbdir 265Use the user database text file 266.Pa master.passwd 267and group database text file 268.Pa group 269from 270.Ar dbdir , 271rather than using the results from the system's 272.Xr getpwnam 3 273and 274.Xr getgrnam 3 275(and related) library calls. 276.It Fl P 277Don't follow symbolic links in the file hierarchy, instead consider 278the symbolic link itself in any comparisons. 279This is the default. 280.It Fl p Ar path 281Use the file hierarchy rooted in 282.Ar path , 283instead of the current directory. 284.It Fl q 285Quiet mode. 286Do not complain when a 287.Dq missing 288directory cannot be created because it already exists. 289This occurs when the directory is a symbolic link. 290.It Fl R Ar keywords 291Remove the specified (whitespace or comma separated) keywords from the current 292set of keywords. 293If 294.Ql all 295is specified, remove all of the other keywords. 296.It Fl r 297Remove any files in the file hierarchy that are not described in the 298specification. 299.It Fl S 300When reading a specification into an internal data structure, 301sort the entries. 302Sorting will affect the order of the output produced by the 303.Fl C 304or 305.Fl D 306options, and will also affect the order in which 307missing entries are created or reported when a directory tree is checked 308against a specification. 309.Pp 310The sort order is the same as that used by the 311.Fl c 312option, which is that entries within the same directory are 313sorted in the order used by 314.Xr strcmp 3 , 315except that entries for subdirectories sort after other entries. 316By default, if the 317.Fl S 318option is not used, entries within the same directory are collected 319together (separated from entries for other directories), but not sorted. 320.It Fl s Ar seed 321Display a single checksum to the standard error output that represents all 322of the files for which the keyword 323.Sy cksum 324was specified. 325The checksum is seeded with the specified value. 326.It Fl t 327Modify the modified time of existing files, the device type of devices, and 328symbolic link targets, to match the specification. 329.It Fl U 330Same as 331.Fl u 332except that a mismatch is not considered to be an error if it was corrected. 333.It Fl u 334Modify the owner, group, permissions, and flags of existing files, 335the device type of devices, and symbolic link targets, 336to match the specification. 337Create any missing directories, devices or symbolic links. 338User, group, and permissions must all be specified for missing directories 339to be created. 340Note that unless the 341.Fl i 342option is given, the schg and sappnd flags will not be set, even if 343specified. 344If 345.Fl m 346is given, these flags will be reset. 347Exit with a status of 0 on success, 3482 if the file hierarchy did not match the specification, and 3491 if any other error occurred. 350.It Fl W 351Don't attempt to set various file attributes such as the 352ownership, mode, flags, or time 353when creating new directories or changing existing entries. 354This option will be most useful when used in conjunction with 355.Fl U 356or 357.Fl u . 358.It Fl X Ar exclude-file 359The specified file contains 360.Xr fnmatch 3 361patterns matching files to be excluded from 362the specification, one to a line. 363If the pattern contains a 364.Ql \&/ 365character, it will be matched against entire pathnames (relative to 366the starting directory); otherwise, 367it will be matched against basenames only. 368Comments are permitted in 369the 370.Ar exclude-list 371file. 372.It Fl x 373Don't descend below mount points in the file hierarchy. 374.El 375.Pp 376Specifications are mostly composed of 377.Dq keywords , 378i.e. strings that 379that specify values relating to files. 380No keywords have default values, and if a keyword has no value set, no 381checks based on it are performed. 382.Pp 383Currently supported keywords are as follows: 384.Bl -tag -width sha384digestxx 385.It Sy cksum 386The checksum of the file using the default algorithm specified by 387the 388.Xr cksum 1 389utility. 390.It Sy device 391The device number to use for 392.Sy block 393or 394.Sy char 395file types. 396The argument must be one of the following forms: 397.Bl -tag -width 4n 398.It Ar format , Ns Ar major , Ns Ar minor 399A device with 400.Ar major 401and 402.Ar minor 403fields, for an operating system specified with 404.Ar format . 405See below for valid formats. 406.It Ar format , Ns Ar major , Ns Ar unit , Ns Ar subunit 407A device with 408.Ar major , 409.Ar unit , 410and 411.Ar subunit 412fields, for an operating system specified with 413.Ar format . 414(Currently this is only supported by the 415.Sy bsdos 416format.) 417.It Ar number 418Opaque number (as stored on the file system). 419.El 420.Pp 421The following values for 422.Ar format 423are recognized: 424.Sy native , 425.Sy 386bsd , 426.Sy 4bsd , 427.Sy bsdos , 428.Sy freebsd , 429.Sy hpux , 430.Sy isc , 431.Sy linux , 432.Sy netbsd , 433.Sy osf1 , 434.Sy sco , 435.Sy solaris , 436.Sy sunos , 437.Sy svr3 , 438.Sy svr4 , 439and 440.Sy ultrix . 441.Pp 442See 443.Xr mknod 8 444for more details. 445.It Sy flags 446The file flags as a symbolic name. 447See 448.Xr chflags 1 449for information on these names. 450If no flags are to be set the string 451.Ql none 452may be used to override the current default. 453Note that the schg and sappnd flags are treated specially (see the 454.Fl i 455and 456.Fl m 457options). 458.It Sy ignore 459Ignore any file hierarchy below this file. 460.It Sy gid 461The file group as a numeric value. 462.It Sy gname 463The file group as a symbolic name. 464.It Sy link 465The file the symbolic link is expected to reference. 466.It Sy md5 467The 468.Tn MD5 469cryptographic message digest of the file. 470.It Sy md5digest 471Synonym for 472.Sy md5 . 473.It Sy mode 474The current file's permissions as a numeric (octal) or symbolic 475value. 476.It Sy nlink 477The number of hard links the file is expected to have. 478.It Sy nochange 479Make sure this file or directory exists but otherwise ignore all attributes. 480.It Sy optional 481The file is optional; don't complain about the file if it's 482not in the file hierarchy. 483.It Sy ripemd160digest 484Synonym for 485.Sy rmd160 . 486.It Sy rmd160 487The 488.Tn RMD-160 489cryptographic message digest of the file. 490.It Sy rmd160digest 491Synonym for 492.Sy rmd160 . 493.It Sy sha1 494The 495.Tn SHA-1 496cryptographic message digest of the file. 497.It Sy sha1digest 498Synonym for 499.Sy sha1 . 500.It Sy sha256 501The 256-bits 502.Tn SHA-2 503cryptographic message digest of the file. 504.It Sy sha256digest 505Synonym for 506.Sy sha256 . 507.It Sy sha384 508The 384-bits 509.Tn SHA-2 510cryptographic message digest of the file. 511.It Sy sha384digest 512Synonym for 513.Sy sha384 . 514.It Sy sha512 515The 512-bits 516.Tn SHA-2 517cryptographic message digest of the file. 518.It Sy sha512digest 519Synonym for 520.Sy sha512 . 521.It Sy size 522The size, in bytes, of the file. 523.It Sy tags 524Comma delimited tags to be matched with 525.Fl E 526and 527.Fl I . 528These may be specified without leading or trailing commas, but will be 529stored internally with them. 530.It Sy time 531The last modification time of the file, 532in second and nanoseconds. 533The value should include a period character and exactly nine digits after 534the period. 535.It Sy type 536The type of the file; may be set to any one of the following: 537.Pp 538.Bl -tag -width Sy -compact 539.It Sy block 540block special device 541.It Sy char 542character special device 543.It Sy dir 544directory 545.It Sy fifo 546fifo 547.It Sy file 548regular file 549.It Sy link 550symbolic link 551.It Sy socket 552socket 553.El 554.It Sy uid 555The file owner as a numeric value. 556.It Sy uname 557The file owner as a symbolic name. 558.El 559.Pp 560The default set of keywords are 561.Sy flags , 562.Sy gid , 563.Sy link , 564.Sy mode , 565.Sy nlink , 566.Sy size , 567.Sy time , 568.Sy type , 569and 570.Sy uid . 571.Pp 572There are four types of lines in a specification: 573.Bl -enum 574.It 575Set global values for a keyword. 576This consists of the string 577.Ql /set 578followed by whitespace, followed by sets of keyword/value 579pairs, separated by whitespace. 580Keyword/value pairs consist of a keyword, followed by an equals sign 581.Pq Ql = , 582followed by a value, without whitespace characters. 583Once a keyword has been set, its value remains unchanged until either 584reset or unset. 585.It 586Unset global values for a keyword. 587This consists of the string 588.Ql /unset , 589followed by whitespace, followed by one or more keywords, 590separated by whitespace. 591If 592.Ql all 593is specified, unset all of the keywords. 594.It 595A file specification, consisting of a path name, followed by whitespace, 596followed by zero or more whitespace separated keyword/value pairs. 597.Pp 598The path name may be preceded by whitespace characters. 599The path name may contain any of the standard path name matching 600characters 601.Po 602.Ql \&[ , 603.Ql \&] , 604.Ql \&? 605or 606.Ql * 607.Pc , 608in which case files 609in the hierarchy will be associated with the first pattern that 610they match. 611.Nm 612uses 613.Xr strsvis 3 614(in VIS_CSTYLE format) to encode path names containing 615non-printable characters. 616Whitespace characters are encoded as 617.Ql \es 618(space), 619.Ql \et 620(tab), and 621.Ql \en 622(new line). 623.Ql # 624characters in path names are escaped by a preceding backslash 625.Ql \e 626to distinguish them from comments. 627.Pp 628Each of the keyword/value pairs consist of a keyword, followed by an 629equals sign 630.Pq Ql = , 631followed by the keyword's value, without 632whitespace characters. 633These values override, without changing, the global value of the 634corresponding keyword. 635.Pp 636The first path name entry listed must be a directory named 637.Ql \&. , 638as this ensures that intermixing full and relative path names will 639work consistently and correctly. 640Multiple entries for a directory named 641.Ql \&. 642are permitted; the settings for the last such entry override those 643of the existing entry. 644.Pp 645A path name that contains a slash 646.Pq Ql / 647that is not the first character will be treated as a full path 648(relative to the root of the tree). 649All parent directories referenced in the path name must exist. 650The current directory path used by relative path names will be updated 651appropriately. 652Multiple entries for the same full path are permitted if the types 653are the same (unless 654.Fl M 655is given, in which case the types may differ); 656in this case the settings for the last entry take precedence. 657.Pp 658A path name that does not contain a slash will be treated as a relative path. 659Specifying a directory will cause subsequent files to be searched 660for in that directory hierarchy. 661.It 662A line containing only the string 663.Ql \&.. 664which causes the current directory path (used by relative paths) 665to ascend one level. 666.El 667.Pp 668Empty lines and lines whose first non-whitespace character is a hash 669mark 670.Pq Ql # 671are ignored. 672.Pp 673The 674.Nm 675utility exits with a status of 0 on success, 1 if any error occurred, 676and 2 if the file hierarchy did not match the specification. 677.Sh FILES 678.Bl -tag -width /etc/mtree -compact 679.It Pa /etc/mtree 680system specification directory 681.El 682.Sh EXAMPLES 683To detect system binaries that have been 684.Dq trojan horsed , 685it is recommended that 686.Nm 687be run on the file systems, and a copy of the results stored on a different 688machine, or, at least, in encrypted form. 689The seed for the 690.Fl s 691option should not be an obvious value and the final checksum should not be 692stored on-line under any circumstances! 693Then, periodically, 694.Nm 695should be run against the on-line specifications and the final checksum 696compared with the previous value. 697While it is possible for the bad guys to change the on-line specifications 698to conform to their modified binaries, it shouldn't be possible for them 699to make it produce the same final checksum value. 700If the final checksum value changes, the off-line copies of the specification 701can be used to detect which of the binaries have actually been modified. 702.Pp 703The 704.Fl d 705option can be used in combination with 706.Fl U 707or 708.Fl u 709to create directory hierarchies for, for example, distributions. 710.Sh COMPATIBILITY 711The compatibility shims provided by the 712.Fl F 713option are incomplete by design. 714Known limitations are described below. 715.Pp 716The 717.Sy freebsd9 718flavor retains the default handling of lookup failures for the 719.Sy uname 720and 721.Sy group 722keywords by replacing them with appropriate 723.Sy uid 724and 725.Sy gid 726keywords rather than failing and reporting an error. 727The related 728.Fl w 729flag is a no-op rather than causing a warning to be printed and no 730keyword to be emitted. 731The latter behavior is not emulated as it is potentially dangerous in 732the face of /set statements. 733.Pp 734The 735.Sy netbsd6 736flavor does not replicate the historical bug that reported time as 737seconds.nanoseconds without zero padding nanosecond values less than 738100000000. 739.Sh SEE ALSO 740.Xr chflags 1 , 741.Xr chgrp 1 , 742.Xr chmod 1 , 743.Xr cksum 1 , 744.Xr stat 2 , 745.Xr fnmatch 3 , 746.Xr fts 3 , 747.Xr strsvis 3 , 748.Xr chown 8 , 749.Xr mknod 8 750.Sh HISTORY 751The 752.Nm 753utility appeared in 754.Bx 4.3 Reno . 755The 756.Sy optional 757keyword appeared in 758.Nx 1.2 . 759The 760.Fl U 761option appeared in 762.Nx 1.3 . 763The 764.Sy flags 765and 766.Sy md5 767keywords, and 768.Fl i 769and 770.Fl m 771options 772appeared in 773.Nx 1.4 . 774The 775.Sy device , 776.Sy rmd160 , 777.Sy sha1 , 778.Sy tags , 779and 780.Sy all 781keywords, 782.Fl D , 783.Fl E , 784.Fl I , 785.Fl L , 786.Fl l , 787.Fl N , 788.Fl P , 789.Fl R , 790.Fl W , 791and 792.Fl X 793options, and support for full paths appeared in 794.Nx 1.6 . 795The 796.Sy sha256 , 797.Sy sha384 , 798and 799.Sy sha512 800keywords appeared in 801.Nx 3.0 . 802The 803.Fl S 804option appeared in 805.Nx 6.0 . 806