Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (NetBSD-2.0)
Apropos / Subsearch:
optional field

MTREE(8)                  BSD System Manager's Manual                 MTREE(8)

     mtree -- map a directory hierarchy

     mtree [-cCdDelLPruUWx] [-i | -m] [-f spec] [-p path] [-k keywords]
           [-K keywords] [-R keywords] [-E tags] [-I tags] [-N dbdir]
           [-s seed] [-X exclude-file]

     The mtree utility compares the file hierarchy rooted in the current
     directory against a specification read from the standard input.  Messages
     are written to the standard output for any files whose characteristics do
     not match the specification, or which are missing from either the file
     hierarchy or the specification.

     The options are as follows:

     -c    Print a specification for the file hierarchy to the standard out-

     -d    Ignore everything except directory type files.

     -C    Print ('dump') the specification as provided by -f spec in a format
           that's easier to parse with various tools.  The full path name is
           always printed as the first field, and -k, -K, and -R can be used
           to control which other keywords are printed, and -E and -I can be
           used to control which files are printed.

     -D    As per -C, except that the path name is always printed as the last
           field instead of the first.

     -E tags
           Add the comma separated tags to the ``exclusion'' list.  Non-direc-
           tories with tags which are in the exclusion list are not printed
           with -D.

     -e    Don't complain about files that are in the file hierarchy, but not
           in the specification.

     -f spec
           Read the specification from file, instead of from the standard

     -I tags
           Add the comma separated tags to the ``inclusion'' list.  Non-direc-
           tories with tags which are in the inclusion list are printed with
           -D.  If no inclusion list is provided, the default is to display
           all files.

     -i    If specified, set the schg and/or sappnd flags.

     -K keywords
           Add the specified (whitespace or comma separated) keywords to the
           current set of keywords.  If 'all' is specified, add all of the
           other keywords.

     -k keywords
           Use the type keyword plus the specified (whitespace or comma sepa-
           rated) keywords instead of the current set of keywords.  If 'all'
           is specified, use all of the other keywords.

     -l    Do ``loose'' permissions checks, in which more stringent permis-
           sions will match less stringent ones. For example, a file marked
           mode 0444 will pass a check for mode 0644.  ``Loose'' checks apply
           only to read, write and execute permissions -- in particular, if
           other bits like the sticky bit or suid/sgid bits are set either in
           the specification or the file, exact checking will be performed.
           This flag may not be set at the same time as the -u or -U flags.

     -L    Follow all symbolic links in the file hierarchy.

     -m    If the schg and/or sappnd flags are specified, reset these flags.
           Note that this is only possible with securelevel less than 1 (i. e.
           in single user mode or while the system is running in insecure
           mode). See init(8) for information on security levels.

     -N dbdir
           Use the user database text file master.passwd and group database
           text file group from dbdir, rather than using the results from the
           system's getpwnam(3) and getgrnam(3) (and related) library calls.

     -p path
           Use the file hierarchy rooted in path, instead of the current

     -P    Don't follow symbolic links in the file hierarchy, instead consider
           the symbolic link itself in any comparisons.  This is the default.

     -r    Remove any files in the file hierarchy that are not described in
           the specification.

     -R keywords
           Remove the specified (whitespace or comma separated) keywords from
           the current set of keywords.  If 'all' is specified, remove all of
           the other keywords.

     -s seed
           Display a single checksum to the standard error output that repre-
           sents all of the files for which the keyword cksum was specified.
           The checksum is seeded with the specified value.

     -u    Modify the owner, group, permissions, and flags of existing files,
           the device type of devices, and symbolic link targets, to match the
           specification.  Create any missing directories, devices or symbolic
           links.  User, group, and permissions must all be specified for
           missing directories to be created.  Note that unless the -i option
           is given, the schg and sappnd flags will not be set, even if speci-
           fied. If -m is given, these flags will be reset.  Exit with a sta-
           tus of 0 on success, 2 if the file hierarchy did not match the
           specification, and 1 if any other error occurred.

     -U    Same as -u except that a mismatch is not considered to be an error
           if it was corrected.

     -W    Don't attempt to set various file attributes such as the ownership,
           mode, flags, or time when creating new directories or changing
           existing entries.  This option will be most useful when used in
           conjunction with -u or -U.

     -x    Don't descend below mount points in the file hierarchy.

     -X exclude-file
           The specified file contains fnmatch(3) patterns matching files to
           be excluded from the specification, one to a line.  If the pattern
           contains a '/' character, it will be matched against entire path-
           names (relative to the starting directory); otherwise, it will be
           matched against basenames only.  Comments are permitted in the
           exclude-list file.

     Specifications are mostly composed of ``keywords'', i.e. strings that
     that specify values relating to files.  No keywords have default values,
     and if a keyword has no value set, no checks based on it are performed.

     Currently supported keywords are as follows:

     cksum   The checksum of the file using the default algorithm specified by
             the cksum(1) utility.

     device  The device number to use for block or char file types.  The argu-
             ment must be one of the following forms:

                   A device with major and minor fields, for an operating sys-
                   tem specified with format.  See below for valid formats.

                   A device with major, unit, and subunit fields, for an oper-
                   ating system specified with format.  (Currently this is
                   only supported by the bsdos format.)

                   Opaque number (as stored on the file system).

             The following values for format are recognized: native, 386bsd,
             4bsd, bsdos, freebsd, hpux, isc, linux, netbsd, osf1, sco,
             solaris, sunos, svr3, svr4, and ultrix.

             See mknod(8) for more details.

     flags   The file flags as a symbolic name.  See chflags(1) for informa-
             tion on these names.  If no flags are to be set the string 'none'
             may be used to override the current default.  Note that the schg
             and sappnd flags are treated specially (see the -i and -m

     ignore  Ignore any file hierarchy below this file.

     gid     The file group as a numeric value.

     gname   The file group as a symbolic name.

     link    The file the symbolic link is expected to reference.

     md5     The MD5 cryptographic message digest of the file.

             Synonym for md5.

     mode    The current file's permissions as a numeric (octal) or symbolic

     nlink   The number of hard links the file is expected to have.

             The file is optional; don't complain about the file if it's not
             in the file hierarchy.

     rmd160  The RMD-160 cryptographic message digest of the file.

             Synonym for rmd160.

     sha1    The SHA-1 cryptographic message digest of the file.

             Synonym for sha1.

     size    The size, in bytes, of the file.

     tags    Comma delimited tags to be matched with -E and -I.  These may be
             specified without leading or trailing commas, but will be stored
             internally with them.

     time    The last modification time of the file.

     type    The type of the file; may be set to any one of the following:

             block   block special device
             char    character special device
             dir     directory
             fifo    fifo
             file    regular file
             link    symbolic link
             socket  socket

     uid     The file owner as a numeric value.

     uname   The file owner as a symbolic name.

     The default set of keywords are flags, gid, link, mode, nlink, size,
     time, type, and uid.

     There are four types of lines in a specification:

     1.   Set global values for a keyword.  This consists of the string '/set'
          followed by whitespace, followed by sets of keyword/value pairs,
          separated by whitespace.  Keyword/value pairs consist of a keyword,
          followed by an equals sign ('='), followed by a value, without
          whitespace characters.  Once a keyword has been set, its value
          remains unchanged until either reset or unset.

     2.   Unset global values for a keyword.  This consists of the string
          '/unset', followed by whitespace, followed by one or more keywords,
          separated by whitespace.  If 'all' is specified, unset all of the

     3.   A file specification, consisting of a path name, followed by white-
          space, followed by zero or more whitespace separated keyword/value

          The path name may be preceded by whitespace characters.  The path
          name may contain any of the standard path name matching characters
          ('[', ']', '?' or '*'), in which case files in the hierarchy will be
          associated with the first pattern that they match.  mtree uses
          strsvis(3) (in VIS_CSTYLE format) to encode path names containing
          non-printable characters. Whitespace characters are encoded as '\s'
          (space), '\t' (tab), and '\n' (new line).  '#' characters in path
          names are escaped by a preceding backslash '\' to distinguish them
          from comments.

          Each of the keyword/value pairs consist of a keyword, followed by an
          equals sign ('='), followed by the keyword's value, without white-
          space characters.  These values override, without changing, the
          global value of the corresponding keyword.

          The first path name entry listed must be a directory named '.', as
          this ensures that intermixing full and relative path names will work
          consistently and correctly.  Multiple entries for a directory named
          '.' are permitted; the settings for the last such entry override
          those of the existing entry.

          A path name that contains a slash ('/') that is not the first char-
          acter will be treated as a full path (relative to the root of the
          tree).  All parent directories referenced in the path name must
          exist.  The current directory path used by relative path names will
          be updated appropriately.  Multiple entries for the same full path
          are permitted if the types are the same; in this case the settings
          for the last entry take precedence.

          A path name that does not contain a slash will be treated as a rela-
          tive path.  Specifying a directory will cause subsequent files to be
          searched for in that directory hierarchy.

     4.   A line containing only the string '..' which causes the current
          directory path (used by relative paths) to ascend one level.

     Empty lines and lines whose first non-whitespace character is a hash mark
     ('#') are ignored.

     The mtree utility exits with a status of 0 on success, 1 if any error
     occurred, and 2 if the file hierarchy did not match the specification.

     /etc/mtree  system specification directory

     To detect system binaries that have been ``trojan horsed'', it is recom-
     mended that mtree be run on the file systems, and a copy of the results
     stored on a different machine, or, at least, in encrypted form.  The seed
     for the -s option should not be an obvious value and the final checksum
     should not be stored on-line under any circumstances!  Then, periodi-
     cally, mtree should be run against the on-line specifications and the
     final checksum compared with the previous value.  While it is possible
     for the bad guys to change the on-line specifications to conform to their
     modified binaries, it shouldn't be possible for them to make it produce
     the same final checksum value.  If the final checksum value changes, the
     off-line copies of the specification can be used to detect which of the
     binaries have actually been modified.

     The -d and -u options can be used in combination to create directory
     hierarchies for distributions and other such things.

     chflags(1), chgrp(1), chmod(1), cksum(1), md5(1), stat(2), fnmatch(3),
     fts(3), strsvis(3), chown(8), mknod(8)

     The mtree utility appeared in 4.3BSD-Reno.  The optional keyword appeared
     in NetBSD 1.2.  The -U flag appeared in NetBSD 1.3.  The flags and md5
     keywords, and -i and -m flags appeared in NetBSD 1.4.  The device,
     rmd160, sha1, tags, and all keywords, -D, -E, -I, -l, -L, -N, -P, -R, -W,
     and -X flags, and support for full paths appeared in NetBSD 1.6.

BSD                            December 22, 2002                           BSD