1.\" $NetBSD: mtree.8,v 1.76 2020/06/16 14:26:39 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 June 16, 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 \(em 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-file 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 622.Dv VIS_OCTAL 623format) to encode path names containing 624non-printable characters. 625Whitespace characters are encoded as 626.Ql \e040 627(space), 628.Ql \e011 629(tab), and 630.Ql \e012 631(new line). 632When flavor 633.Sy netbsd6 634is selected, 635.Xr strsvis 3 636(in 637.Dv VIS_CSTYLE 638format) is used and whitespace characters are encoded as 639.Ql \es 640(space), 641.Ql \et 642(tab), and 643.Ql \en 644(new line). 645.Ql # 646characters in path names are escaped by a preceding backslash 647.Ql \e 648to distinguish them from comments. 649.Pp 650Each of the keyword/value pairs consist of a keyword, followed by an 651equals sign 652.Pq Ql = , 653followed by the keyword's value, without 654whitespace characters. 655These values override, without changing, the global value of the 656corresponding keyword. 657.Pp 658The first path name entry listed must be a directory named 659.Ql \&. , 660as this ensures that intermixing full and relative path names will 661work consistently and correctly. 662Multiple entries for a directory named 663.Ql \&. 664are permitted; the settings for the last such entry override those 665of the existing entry. 666.Pp 667A path name that contains a slash 668.Pq Ql / 669that is not the first character will be treated as a full path 670(relative to the root of the tree). 671All parent directories referenced in the path name must exist. 672The current directory path used by relative path names will be updated 673appropriately. 674Multiple entries for the same full path are permitted if the types 675are the same (unless 676.Fl M 677is given, in which case the types may differ); 678in this case the settings for the last entry take precedence. 679.Pp 680A path name that does not contain a slash will be treated as a relative path. 681Specifying a directory will cause subsequent files to be searched 682for in that directory hierarchy. 683.It 684A line containing only the string 685.Ql \&.. 686which causes the current directory path (used by relative paths) 687to ascend one level. 688.El 689.Pp 690Empty lines and lines whose first non-whitespace character is a hash 691mark 692.Pq Ql # 693are ignored. 694.Pp 695The 696.Nm 697utility exits with a status of 0 on success, 1 if any error occurred, 698and 2 if the file hierarchy did not match the specification. 699.Sh FILES 700.Bl -tag -width /etc/mtree -compact 701.It Pa /etc/mtree 702system specification directory 703.El 704.Sh EXAMPLES 705To detect system binaries that have been 706.Dq trojan horsed , 707it is recommended that 708.Nm 709be run on the file systems, and a copy of the results stored on a different 710machine, or, at least, in encrypted form. 711The seed for the 712.Fl s 713option should not be an obvious value and the final checksum should not be 714stored on-line under any circumstances! 715Then, periodically, 716.Nm 717should be run against the on-line specifications and the final checksum 718compared with the previous value. 719While it is possible for the bad guys to change the on-line specifications 720to conform to their modified binaries, it shouldn't be possible for them 721to make it produce the same final checksum value. 722If the final checksum value changes, the off-line copies of the specification 723can be used to detect which of the binaries have actually been modified. 724.Pp 725The 726.Fl d 727option can be used in combination with 728.Fl U 729or 730.Fl u 731to create directory hierarchies for, for example, distributions. 732.Sh COMPATIBILITY 733The compatibility shims provided by the 734.Fl F 735option are incomplete by design. 736Known limitations are described below. 737.Pp 738The 739.Sy freebsd9 740flavor retains the default handling of lookup failures for the 741.Sy uname 742and 743.Sy group 744keywords by replacing them with appropriate 745.Sy uid 746and 747.Sy gid 748keywords rather than failing and reporting an error. 749The related 750.Fl w 751flag is a no-op rather than causing a warning to be printed and no 752keyword to be emitted. 753The latter behavior is not emulated as it is potentially dangerous in 754the face of /set statements. 755.Pp 756The 757.Sy netbsd6 758flavor does not replicate the historical bug that reported time as 759seconds.nanoseconds without zero padding nanosecond values less than 760100000000. 761.Sh SEE ALSO 762.Xr chflags 1 , 763.Xr chgrp 1 , 764.Xr chmod 1 , 765.Xr cksum 1 , 766.Xr stat 2 , 767.Xr fnmatch 3 , 768.Xr fts 3 , 769.Xr strsvis 3 , 770.Xr chown 8 , 771.Xr mknod 8 772.Sh HISTORY 773The 774.Nm 775utility appeared in 776.Bx 4.3 Reno . 777The 778.Sy optional 779keyword appeared in 780.Nx 1.2 . 781The 782.Fl U 783option appeared in 784.Nx 1.3 . 785The 786.Sy flags 787and 788.Sy md5 789keywords, and 790.Fl i 791and 792.Fl m 793options 794appeared in 795.Nx 1.4 . 796The 797.Sy device , 798.Sy rmd160 , 799.Sy sha1 , 800.Sy tags , 801and 802.Sy all 803keywords, 804.Fl D , 805.Fl E , 806.Fl I , 807.Fl L , 808.Fl l , 809.Fl N , 810.Fl P , 811.Fl R , 812.Fl W , 813and 814.Fl X 815options, and support for full paths appeared in 816.Nx 1.6 . 817The 818.Sy sha256 , 819.Sy sha384 , 820and 821.Sy sha512 822keywords appeared in 823.Nx 3.0 . 824The 825.Fl S 826option appeared in 827.Nx 6.0 . 828