mtree/mtree.8

   1 .\"     $NetBSD: mtree.8,v 1.7 1997/10/17 11:46:46 lukem 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. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)mtree.8     8.2 (Berkeley) 12/11/93
  35 .\"
  36 .Dd December 11, 1993
  37 .Dt MTREE 8
  38 .Os
  39 .Sh NAME
  40 .Nm mtree
  41 .Nd map a directory hierarchy
  42 .Sh SYNOPSIS
  43 .Nm
  44 .Op Fl cderux
  45 .Op Fl f Ar spec
  46 .Op Fl K Ar keywords
  47 .Op Fl k Ar keywords
  48 .Op Fl p Ar path
  49 .Op Fl s Ar seed
  50 .Sh DESCRIPTION
  51 The utility
  52 .Nm
  53 compares the file hierarchy rooted in the current directory against a
  54 specification read from the standard input.
  55 Messages are written to the standard output for any files whose
  56 characteristics do not match the specification, or which are
  57 missing from either the file hierarchy or the specification.
  58 .Pp
  59 The options are as follows:
  60 .Bl -tag -width flag
  61 .It Fl c
  62 Print a specification for the file hierarchy to the standard output.
  63 .It Fl d
  64 Ignore everything except directory type files.
  65 .It Fl e
  66 Don't complain about files that are in the file hierarchy, but not in the
  67 specification.
  68 .It Fl f
  69 Read the specification from
  70 .Ar file  ,
  71 instead of from the standard input.
  72 .It Fl K
  73 Add the specified (whitespace or comma separated) keywords to the current
  74 set of keywords.
  75 .It Fl k
  76 Use the ``type'' keyword plus the specified (whitespace or comma separated)
  77 keywords instead of the current set of keywords.
  78 .It Fl p
  79 Use the file hierarchy rooted in
  80 .Ar path  ,
  81 instead of the current directory.
  82 .It Fl r
  83 Remove any files in the file hierarchy that are not described in the
  84 specification.
  85 .It Fl s
  86 Display a single checksum to the standard error output that represents all
  87 of the files for which the keyword
  88 .Cm cksum
  89 was specified.
  90 The checksum is seeded with the specified value.
  91 .It Fl U
  92 Modify the owner, group, and permissions of existing files to match
  93 the specification and create any missing directories.
  94 User, group, and permissions must all be specified for missing directories
  95 to be created.
  96 Exit with a status of 0 on success, 1 if any error occurred;
  97 a mismatch is not considered to be an error if it was corrected.
  98 .It Fl u
  99 Same as
 100 .Fl U
 101 except a status of 2 is returned if the file hierarchy did not match
 102 the specification.
 103 .It Fl x
 104 Don't descend below mount points in the file hierarchy.
 105 .El
 106 .Pp
 107 Specifications are mostly composed of ``keywords'', i.e. strings that
 108 that specify values relating to files.
 109 No keywords have default values, and if a keyword has no value set, no
 110 checks based on it are performed.
 111 .Pp
 112 Currently supported keywords are as follows:
 113 .Bl -tag -width Cm
 114 .It Cm cksum
 115 The checksum of the file using the default algorithm specified by
 116 the
 117 .Xr cksum 1
 118 utility.
 119 .It Cm ignore
 120 Ignore any file hierarchy below this file.
 121 .It Cm gid
 122 The file group as a numeric value.
 123 .It Cm gname
 124 The file group as a symbolic name.
 125 .It Cm link
 126 The file the symbolic link is expected to reference.
 127 .It Cm mode
 128 The current file's permissions as a numeric (octal) or symbolic
 129 value.
 130 .It Cm nlink
 131 The number of hard links the file is expected to have.
 132 .It Cm optional
 133 The file is optional; don't complain about the file if it's
 134 not in the file hierarchy.
 135 .It Cm uid
 136 The file owner as a numeric value.
 137 .It Cm uname
 138 The file owner as a symbolic name.
 139 .It Cm size
 140 The size, in bytes, of the file.
 141 .It Cm time
 142 The last modification time of the file.
 143 .It Cm type
 144 The type of the file; may be set to any one of the following:
 145 .sp
 146 .Bl -tag -width Cm -compact
 147 .It Cm block
 148 block special device
 149 .It Cm char
 150 character special device
 151 .It Cm dir
 152 directory
 153 .It Cm fifo
 154 fifo
 155 .It Cm file
 156 regular file
 157 .It Cm link
 158 symbolic link
 159 .It Cm socket
 160 socket
 161 .El
 162 .El
 163 .Pp
 164 The default set of keywords are
 165 .Cm gid ,
 166 .Cm link ,
 167 .Cm mode ,
 168 .Cm nlink ,
 169 .Cm size ,
 170 .Cm time ,
 171 and
 172 .Cm uid .
 173 .Pp
 174 There are four types of lines in a specification.
 175 .Pp
 176 The first type of line sets a global value for a keyword, and consists of
 177 the string ``/set'' followed by whitespace, followed by sets of keyword/value
 178 pairs, separated by whitespace.
 179 Keyword/value pairs consist of a keyword, followed by an equals sign
 180 (``=''), followed by a value, without whitespace characters.
 181 Once a keyword has been set, its value remains unchanged until either
 182 reset or unset.
 183 .Pp
 184 The second type of line unsets keywords and consists of the string
 185 ``/unset'', followed by whitespace, followed by one or more keywords,
 186 separated by whitespace.
 187 .Pp
 188 The third type of line is a file specification and consists of a file
 189 name, followed by whitespace, followed by zero or more whitespace
 190 separated keyword/value pairs.
 191 The file name may be preceded by whitespace characters.
 192 The file name may contain any of the standard file name matching
 193 characters (``['', ``]'', ``?'' or ``*''), in which case files
 194 in the hierarchy will be associated with the first pattern that
 195 they match.
 196 .Pp
 197 Each of the keyword/value pairs consist of a keyword, followed by an
 198 equals sign (``=''), followed by the keyword's value, without
 199 whitespace characters.
 200 These values override, without changing, the global value of the
 201 corresponding keyword.
 202 .Pp
 203 All paths are relative.
 204 Specifying a directory will cause subsequent files to be searched
 205 for in that directory hierarchy.
 206 Which brings us to the last type of line in a specification: a line
 207 containing only the string
 208 .Dq Nm \&..
 209 causes the current directory
 210 path to ascend one level.
 211 .Pp
 212 Empty lines and lines whose first non-whitespace character is a hash
 213 mark (``#'') are ignored.
 214 .Pp
 215 The
 216 .Nm
 217 utility exits with a status of 0 on success, 1 if any error occurred,
 218 and 2 if the file hierarchy did not match the specification.
 219 .Sh EXAMPLES
 220 To detect system binaries that have been ``trojan horsed'', it is recommended
 221 that
 222 .Nm
 223 be run on the file systems, and a copy of the results stored on a different
 224 machine, or, at least, in encrypted form.
 225 The seed for the
 226 .Fl s
 227 option should not be an obvious value and the final checksum should not be
 228 stored on-line under any circumstances!
 229 Then, periodically,
 230 .Nm
 231 should be run against the on-line specifications and the final checksum
 232 compared with the previous value.
 233 While it is possible for the bad guys to change the on-line specifications
 234 to conform to their modified binaries, it shouldn't be possible for them
 235 to make it produce the same final checksum value.
 236 If the final checksum value changes, the off-line copies of the specification
 237 can be used to detect which of the binaries have actually been modified.
 238 .Pp
 239 The
 240 .Fl d
 241 and
 242 .Fl u
 243 options can be used in combination to create directory hierarchies
 244 for distributions and other such things.
 245 .Sh FILES
 246 .Bl -tag -width /etc/mtree -compact
 247 .It Pa /etc/mtree
 248 system specification directory
 249 .El
 250 .Sh SEE ALSO
 251 .Xr chmod 1 ,
 252 .Xr chgrp 1 ,
 253 .Xr cksum 1 ,
 254 .Xr stat 2 ,
 255 .Xr fts 3 ,
 256 .Xr chown 8
 257 .Sh HISTORY
 258 The
 259 .Nm
 260 utility appeared in
 261 .Bx 4.3 Reno .