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