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