home | help
MTREE(8)		     System Manager's Manual			MTREE(8)

NAME
     mtree -- map a directory hierarchy

SYNOPSIS
     mtree [-LPUcdeinqruxw] [-f spec] [-f spec] [-K keywords] [-k keywords]
	   [-p path] [-s seed] [-X exclude-list]

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

     The options are as follows:

     -L    Follow all symbolic links in the file hierarchy.

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

     -U    Modify the owner, group, permissions, and modification time of exist-
	   ing	files to match the specification and create any missing directo-
	   ries or symbolic links.  User, group  and  permissions  must  all  be
	   specified  for  missing  directories  to  be created.  Corrected mis-
	   matches are not considered errors.

     -c    Print a specification for the file hierarchy to the standard output.

     -d    Ignore everything except directory type files.

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

     -i    Indent  the	output 4 spaces each time a directory level is descended
	   when create a specification with the -c option.  This does not affect
	   either the /set statements or the comment before each directory.   It
	   does however affect the comment before the close of each directory.

     -n    Do  not  emit  pathname comments when creating a specification.  Nor-
	   mally a comment is emitted before each directory and before the close
	   of that directory when using the -c option.

     -q    Quiet mode.	Do not complain when a	"missing"  directory  cannot  be
	   created because it already exists.  This occurs when the directory is
	   a symbolic link.

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

     -u    Same as -U except a status of 2 is returned if the file hierarchy did
	   not match the specification.

     -w    Make some errorconditions non-fatal warnings.

     -x    Do not descend below mount points in the file hierarchy.

     -f file
	   Read the specification from file, instead of from the standard input.

	   If this option is specified twice, the two  specifications  are  com-
	   pared  to each other rather than to the file hierarchy.  The specifi-
	   cations be sorted like output generated using -c.  The output  format
	   in this case is somewhat remniscent of comm(1), having "in first spec
	   only",  "in	second	spec only", and "different" columns, prefixed by
	   zero, one and two TAB characters respectively.   Each  entry  in  the
	   "different" column occupies two lines, one from each specification.

     -K keywords
	   Add	the  specified	(whitespace  or comma separated) keywords to the
	   current set of keywords.

     -k keywords
	   Use the ``type'' keyword plus the specified (whitespace or comma sep-
	   arated) keywords instead of the current set of keywords.

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

     -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.

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

     Specifications are mostly composed  of  ``keywords'',  i.e.,  strings  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.

     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.

     ignore	 Ignore any file hierarchy below this file.

     gid	 The file group as a numeric value.

     gname	 The file group as a symbolic name.

     md5digest	 The MD5 message digest of the file.

     sha1digest  The FIPS 160-1 ("SHA-1") message digest of the file.

     sha256digest
		 The FIPS 180-2 ("SHA-256") message digest of the file.

     ripemd160digest
		 The RIPEMD160 message digest of the file.

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

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

     nochange	 Make sure this file or directory exists  but  otherwise  ignore
		 all attributes.

     optional	 The  file  is optional; do not complain about the file if it is
		 not in the file hierarchy.

     uid	 The file owner as a numeric value.

     uname	 The file owner as a symbolic name.

     size	 The size, in bytes, of the file.

     link	 The file the symbolic link is expected to reference.

     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

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

     There are four types of lines in a specification.

     The  first  type of line sets a global value for a keyword, and consists of
     the string ``/set'' followed  by  whitespace,  followed  by  sets	of  key-
     word/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  un-
     changed until either reset or unset.

     The  second  type of line unsets keywords and consists of the string ``/un-
     set'', followed by whitespace, followed by one or more keywords,  separated
     by whitespace.

     The third type of line is a file specification and consists of a file name,
     followed  by whitespace, followed by zero or more whitespace separated key-
     word/value pairs.	The file name may be preceded by whitespace  characters.
     The file name may contain any of the standard file name matching characters
     (``['',  ``]'',  ``?'' or ``*''), in which case files in the hierarchy will
     be associated with the first pattern that they match.

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

     All paths are relative.  Specifying a directory will cause subsequent files
     to be searched for in that directory hierarchy.  Which  brings  us  to  the
     last  type  of  line  in a specification: a line containing only the string
     ".." causes the current directory path 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 oc-
     curred, and 2 if the file hierarchy did not  match  the  specification.   A
     status of 2 is converted to a status of 0 if the -U option is used.

FILES
     /etc/mtree  system specification directory

EXIT STATUS
     The mtree utility exits 0 on success, and >0 if an error occurs.

EXAMPLES
     To  detect  system  binaries that have been ``trojan horsed'', it is recom-
     mended that mtree -K sha256digest be run on the file systems, and a copy of
     the results stored on a different machine, or, at least, in encrypted form.
     The output file itself should be  digested  using	the  sha256(1)	utility.
     Then,  periodically,  mtree and sha256(1) should be run against the on-line
     specifications.  While it is possible for the bad guys to	change	the  on-
     line  specifications  to conform to their modified binaries, it is believed
     to be impractical for them to create a modified specification which has the
     same SHA-256 digest as the original.

     The -d and -u options can be used in combination to create directory  hier-
     archies  for  distributions  and other such things; the files in /etc/mtree
     were used to create almost all directories in this FreeBSD distribution.

     To create an /etc/mtree style BSD.*.dist file, use mtree -c  -d  -i  -n  -k
     uname,gname,mode,nochange.

SEE ALSO
     chflags(1),  chgrp(1), chmod(1), cksum(1), md5(1), stat(2), fts(3), md5(3),
     chown(8)

HISTORY
     The mtree utility appeared in 4.3BSD-Reno.  The MD5 digest  capability  was
     added  in	FreeBSD 2.1, in response to the widespread use of programs which
     can spoof	cksum(1).   The  SHA-1	and  RIPEMD160	digests  were  added  in
     FreeBSD  4.0,  as	new  attacks  have  demonstrated weaknesses in MD5.  The
     SHA-256 digest was added in FreeBSD 6.0.  Support for file flags was  added
     in FreeBSD 4.0, and mostly comes from NetBSD.

FreeBSD 6.3			  June 16, 2007 			MTREE(8)

home | help