1.\" $NetBSD: mtree.8,v 1.71 2015/01/23 03:31:58 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 January 22, 2015 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. 302Repeating the flag more than once will attempt to reset all the 303file flags via 304.Xr lchflags 2 305before attempting to remove the file in case the file was immutable. 306.It Fl S 307When reading a specification into an internal data structure, 308sort the entries. 309Sorting will affect the order of the output produced by the 310.Fl C 311or 312.Fl D 313options, and will also affect the order in which 314missing entries are created or reported when a directory tree is checked 315against a specification. 316.Pp 317The sort order is the same as that used by the 318.Fl c 319option, which is that entries within the same directory are 320sorted in the order used by 321.Xr strcmp 3 , 322except that entries for subdirectories sort after other entries. 323By default, if the 324.Fl S 325option is not used, entries within the same directory are collected 326together (separated from entries for other directories), but not sorted. 327.It Fl s Ar seed 328Display a single checksum to the standard error output that represents all 329of the files for which the keyword 330.Sy cksum 331was specified. 332The checksum is seeded with the specified value. 333.It Fl t 334Modify the modified time of existing files, the device type of devices, and 335symbolic link targets, to match the specification. 336.It Fl U 337Same as 338.Fl u 339except that a mismatch is not considered to be an error if it was corrected. 340.It Fl u 341Modify the owner, group, permissions, and flags of existing files, 342the device type of devices, and symbolic link targets, 343to match the specification. 344Create any missing directories, devices or symbolic links. 345User, group, and permissions must all be specified for missing directories 346to be created. 347Note that unless the 348.Fl i 349option is given, the schg and sappnd flags will not be set, even if 350specified. 351If 352.Fl m 353is given, these flags will be reset. 354Exit with a status of 0 on success, 3552 if the file hierarchy did not match the specification, and 3561 if any other error occurred. 357.It Fl W 358Don't attempt to set various file attributes such as the 359ownership, mode, flags, or time 360when creating new directories or changing existing entries. 361This option will be most useful when used in conjunction with 362.Fl U 363or 364.Fl u . 365.It Fl X Ar exclude-file 366The specified file contains 367.Xr fnmatch 3 368patterns matching files to be excluded from 369the specification, one to a line. 370If the pattern contains a 371.Ql \&/ 372character, it will be matched against entire pathnames (relative to 373the starting directory); otherwise, 374it will be matched against basenames only. 375Comments are permitted in 376the 377.Ar exclude-list 378file. 379.It Fl x 380Don't descend below mount points in the file hierarchy. 381.El 382.Pp 383Specifications are mostly composed of 384.Dq keywords , 385i.e. strings that 386that specify values relating to files. 387No keywords have default values, and if a keyword has no value set, no 388checks based on it are performed. 389.Pp 390Currently supported keywords are as follows: 391.Bl -tag -width sha384digestxx 392.It Sy cksum 393The checksum of the file using the default algorithm specified by 394the 395.Xr cksum 1 396utility. 397.It Sy device 398The device number to use for 399.Sy block 400or 401.Sy char 402file types. 403The argument must be one of the following forms: 404.Bl -tag -width 4n 405.It Ar format , Ns Ar major , Ns Ar minor 406A device with 407.Ar major 408and 409.Ar minor 410fields, for an operating system specified with 411.Ar format . 412See below for valid formats. 413.It Ar format , Ns Ar major , Ns Ar unit , Ns Ar subunit 414A device with 415.Ar major , 416.Ar unit , 417and 418.Ar subunit 419fields, for an operating system specified with 420.Ar format . 421(Currently this is only supported by the 422.Sy bsdos 423format.) 424.It Ar number 425Opaque number (as stored on the file system). 426.El 427.Pp 428The following values for 429.Ar format 430are recognized: 431.Sy native , 432.Sy 386bsd , 433.Sy 4bsd , 434.Sy bsdos , 435.Sy freebsd , 436.Sy hpux , 437.Sy isc , 438.Sy linux , 439.Sy netbsd , 440.Sy osf1 , 441.Sy sco , 442.Sy solaris , 443.Sy sunos , 444.Sy svr3 , 445.Sy svr4 , 446and 447.Sy ultrix . 448.Pp 449See 450.Xr mknod 8 451for more details. 452.It Sy flags 453The file flags as a symbolic name. 454See 455.Xr chflags 1 456for information on these names. 457If no flags are to be set the string 458.Ql none 459may be used to override the current default. 460Note that the schg and sappnd flags are treated specially (see the 461.Fl i 462and 463.Fl m 464options). 465.It Sy ignore 466Ignore any file hierarchy below this file. 467.It Sy gid 468The file group as a numeric value. 469.It Sy gname 470The file group as a symbolic name. 471.It Sy link 472The file the symbolic link is expected to reference. 473.It Sy md5 474The 475.Tn MD5 476cryptographic message digest of the file. 477.It Sy md5digest 478Synonym for 479.Sy md5 . 480.It Sy mode 481The current file's permissions as a numeric (octal) or symbolic 482value. 483.It Sy nlink 484The number of hard links the file is expected to have. 485.It Sy nochange 486Make sure this file or directory exists but otherwise ignore all attributes. 487.It Sy optional 488The file is optional; don't complain about the file if it's 489not in the file hierarchy. 490.It Sy ripemd160digest 491Synonym for 492.Sy rmd160 . 493.It Sy rmd160 494The 495.Tn RMD-160 496cryptographic message digest of the file. 497.It Sy rmd160digest 498Synonym for 499.Sy rmd160 . 500.It Sy sha1 501The 502.Tn SHA-1 503cryptographic message digest of the file. 504.It Sy sha1digest 505Synonym for 506.Sy sha1 . 507.It Sy sha256 508The 256-bits 509.Tn SHA-2 510cryptographic message digest of the file. 511.It Sy sha256digest 512Synonym for 513.Sy sha256 . 514.It Sy sha384 515The 384-bits 516.Tn SHA-2 517cryptographic message digest of the file. 518.It Sy sha384digest 519Synonym for 520.Sy sha384 . 521.It Sy sha512 522The 512-bits 523.Tn SHA-2 524cryptographic message digest of the file. 525.It Sy sha512digest 526Synonym for 527.Sy sha512 . 528.It Sy size 529The size, in bytes, of the file. 530.It Sy tags 531Comma delimited tags to be matched with 532.Fl E 533and 534.Fl I . 535These may be specified without leading or trailing commas, but will be 536stored internally with them. 537.It Sy time 538The last modification time of the file, 539in second and nanoseconds. 540The value should include a period character and exactly nine digits after 541the period. 542.It Sy type 543The type of the file; may be set to any one of the following: 544.Pp 545.Bl -tag -width Sy -compact 546.It Sy block 547block special device 548.It Sy char 549character special device 550.It Sy dir 551directory 552.It Sy fifo 553fifo 554.It Sy file 555regular file 556.It Sy link 557symbolic link 558.It Sy socket 559socket 560.El 561.It Sy uid 562The file owner as a numeric value. 563.It Sy uname 564The file owner as a symbolic name. 565.El 566.Pp 567The default set of keywords are 568.Sy flags , 569.Sy gid , 570.Sy link , 571.Sy mode , 572.Sy nlink , 573.Sy size , 574.Sy time , 575.Sy type , 576and 577.Sy uid . 578.Pp 579There are four types of lines in a specification: 580.Bl -enum 581.It 582Set global values for a keyword. 583This consists of the string 584.Ql /set 585followed by whitespace, followed by sets of keyword/value 586pairs, separated by whitespace. 587Keyword/value pairs consist of a keyword, followed by an equals sign 588.Pq Ql = , 589followed by a value, without whitespace characters. 590Once a keyword has been set, its value remains unchanged until either 591reset or unset. 592.It 593Unset global values for a keyword. 594This consists of the string 595.Ql /unset , 596followed by whitespace, followed by one or more keywords, 597separated by whitespace. 598If 599.Ql all 600is specified, unset all of the keywords. 601.It 602A file specification, consisting of a path name, followed by whitespace, 603followed by zero or more whitespace separated keyword/value pairs. 604.Pp 605The path name may be preceded by whitespace characters. 606The path name may contain any of the standard path name matching 607characters 608.Po 609.Ql \&[ , 610.Ql \&] , 611.Ql \&? 612or 613.Ql * 614.Pc , 615in which case files 616in the hierarchy will be associated with the first pattern that 617they match. 618.Nm 619uses 620.Xr strsvis 3 621(in VIS_CSTYLE format) to encode path names containing 622non-printable characters. 623Whitespace characters are encoded as 624.Ql \es 625(space), 626.Ql \et 627(tab), and 628.Ql \en 629(new line). 630.Ql # 631characters in path names are escaped by a preceding backslash 632.Ql \e 633to distinguish them from comments. 634.Pp 635Each of the keyword/value pairs consist of a keyword, followed by an 636equals sign 637.Pq Ql = , 638followed by the keyword's value, without 639whitespace characters. 640These values override, without changing, the global value of the 641corresponding keyword. 642.Pp 643The first path name entry listed must be a directory named 644.Ql \&. , 645as this ensures that intermixing full and relative path names will 646work consistently and correctly. 647Multiple entries for a directory named 648.Ql \&. 649are permitted; the settings for the last such entry override those 650of the existing entry. 651.Pp 652A path name that contains a slash 653.Pq Ql / 654that is not the first character will be treated as a full path 655(relative to the root of the tree). 656All parent directories referenced in the path name must exist. 657The current directory path used by relative path names will be updated 658appropriately. 659Multiple entries for the same full path are permitted if the types 660are the same (unless 661.Fl M 662is given, in which case the types may differ); 663in this case the settings for the last entry take precedence. 664.Pp 665A path name that does not contain a slash will be treated as a relative path. 666Specifying a directory will cause subsequent files to be searched 667for in that directory hierarchy. 668.It 669A line containing only the string 670.Ql \&.. 671which causes the current directory path (used by relative paths) 672to ascend one level. 673.El 674.Pp 675Empty lines and lines whose first non-whitespace character is a hash 676mark 677.Pq Ql # 678are ignored. 679.Pp 680The 681.Nm 682utility exits with a status of 0 on success, 1 if any error occurred, 683and 2 if the file hierarchy did not match the specification. 684.Sh FILES 685.Bl -tag -width /etc/mtree -compact 686.It Pa /etc/mtree 687system specification directory 688.El 689.Sh EXAMPLES 690To detect system binaries that have been 691.Dq trojan horsed , 692it is recommended that 693.Nm 694be run on the file systems, and a copy of the results stored on a different 695machine, or, at least, in encrypted form. 696The seed for the 697.Fl s 698option should not be an obvious value and the final checksum should not be 699stored on-line under any circumstances! 700Then, periodically, 701.Nm 702should be run against the on-line specifications and the final checksum 703compared with the previous value. 704While it is possible for the bad guys to change the on-line specifications 705to conform to their modified binaries, it shouldn't be possible for them 706to make it produce the same final checksum value. 707If the final checksum value changes, the off-line copies of the specification 708can be used to detect which of the binaries have actually been modified. 709.Pp 710The 711.Fl d 712option can be used in combination with 713.Fl U 714or 715.Fl u 716to create directory hierarchies for, for example, distributions. 717.Sh COMPATIBILITY 718The compatibility shims provided by the 719.Fl F 720option are incomplete by design. 721Known limitations are described below. 722.Pp 723The 724.Sy freebsd9 725flavor retains the default handling of lookup failures for the 726.Sy uname 727and 728.Sy group 729keywords by replacing them with appropriate 730.Sy uid 731and 732.Sy gid 733keywords rather than failing and reporting an error. 734The related 735.Fl w 736flag is a no-op rather than causing a warning to be printed and no 737keyword to be emitted. 738The latter behavior is not emulated as it is potentially dangerous in 739the face of /set statements. 740.Pp 741The 742.Sy netbsd6 743flavor does not replicate the historical bug that reported time as 744seconds.nanoseconds without zero padding nanosecond values less than 745100000000. 746.Sh SEE ALSO 747.Xr chflags 1 , 748.Xr chgrp 1 , 749.Xr chmod 1 , 750.Xr cksum 1 , 751.Xr stat 2 , 752.Xr fnmatch 3 , 753.Xr fts 3 , 754.Xr strsvis 3 , 755.Xr chown 8 , 756.Xr mknod 8 757.Sh HISTORY 758The 759.Nm 760utility appeared in 761.Bx 4.3 Reno . 762The 763.Sy optional 764keyword appeared in 765.Nx 1.2 . 766The 767.Fl U 768option appeared in 769.Nx 1.3 . 770The 771.Sy flags 772and 773.Sy md5 774keywords, and 775.Fl i 776and 777.Fl m 778options 779appeared in 780.Nx 1.4 . 781The 782.Sy device , 783.Sy rmd160 , 784.Sy sha1 , 785.Sy tags , 786and 787.Sy all 788keywords, 789.Fl D , 790.Fl E , 791.Fl I , 792.Fl L , 793.Fl l , 794.Fl N , 795.Fl P , 796.Fl R , 797.Fl W , 798and 799.Fl X 800options, and support for full paths appeared in 801.Nx 1.6 . 802The 803.Sy sha256 , 804.Sy sha384 , 805and 806.Sy sha512 807keywords appeared in 808.Nx 3.0 . 809The 810.Fl S 811option appeared in 812.Nx 6.0 . 813