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