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    Don't 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    Don't 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    Don't 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.

     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.

     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.

EXAMPLES
     To  detect  system  binaries that have been ``trojan horsed'', it is recom-
     mended that mtree -K sha1digest 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 md5(1) utility.  Then,
     periodically, mtree and md5(1) should be run against the on-line specifica-
     tions.  While it is possible for the bad guys to change the on-line  speci-
     fications	to  conform to their modified binaries, it is believed to be im-
     practical for them to create a modified specification which  has  the  same
     MD5 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.

FILES
     /etc/mtree  system specification directory

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

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.  Support
     for file flags was added in FreeBSD 4.0, and mostly comes from NetBSD.

FreeBSD 5.5			January 11, 2004			MTREE(8)
home | help