usr.sbin/mtree/mtree.8

   1 .\" Copyright (c) 1989, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)mtree.8       8.2 (Berkeley) 12/11/93
  29 .\" $FreeBSD: src/usr.sbin/mtree/mtree.8,v 1.16.2.11 2003/03/11 22:31:29 trhodes Exp $
  30 .\"
  31 .Dd February 26, 1999
  32 .Dt MTREE 8
  33 .Os
  34 .Sh NAME
  35 .Nm mtree
  36 .Nd map a directory hierarchy
  37 .Sh SYNOPSIS
  38 .Nm
  39 .Op Fl LPUcdeinqrux
  40 .Bk -words
  41 .Op Fl f Ar spec
  42 .Ek
  43 .Bk -words
  44 .Op Fl K Ar keywords
  45 .Ek
  46 .Bk -words
  47 .Op Fl k Ar keywords
  48 .Ek
  49 .Bk -words
  50 .Op Fl p Ar path
  51 .Ek
  52 .Bk -words
  53 .Op Fl s Ar seed
  54 .Ek
  55 .Bk -words
  56 .Op Fl X Ar exclude-list
  57 .Ek
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 utility compares the file hierarchy rooted in the current directory against a
  62 specification read from the standard input.
  63 Messages are written to the standard output for any files whose
  64 characteristics do not match the specifications, or which are
  65 missing from either the file hierarchy or the specification.
  66 .Pp
  67 The options are as follows:
  68 .Bl -tag -width flag
  69 .It Fl L
  70 Follow all symbolic links in the file hierarchy.
  71 .It Fl P
  72 Don't follow symbolic links in the file hierarchy, instead consider
  73 the symbolic link itself in any comparisons. This is the default.
  74 .It Fl U
  75 Modify the owner, group and permissions of existing files to match
  76 the specification and create any missing directories or symbolic links.
  77 User, group and permissions must all be specified for missing directories
  78 to be created.
  79 Corrected mismatches are not considered errors.
  80 .It Fl c
  81 Print a specification for the file hierarchy to the standard output.
  82 .It Fl d
  83 Ignore everything except directory type files.
  84 .It Fl e
  85 Don't complain about files that are in the file hierarchy, but not in the
  86 specification.
  87 .It Fl i
  88 Indent the output 4 spaces each time a directory level is descended when
  89 create a specification with the
  90 .Fl c
  91 option.
  92 This does not affect either the /set statements or the comment before each
  93 directory.
  94 It does however affect the comment before the close of each directory.
  95 .It Fl n
  96 Do not emit pathname comments when creating a specification.  Normally
  97 a comment is emitted before each directory and before the close of that
  98 directory when using the
  99 .Fl c
 100 option.
 101 .It Fl q
 102 Quiet mode.  Do not complain when a
 103 .Dq missing
 104 directory cannot be created because it already exists.
 105 This occurs when the directory is a symbolic link.
 106 .It Fl r
 107 Remove any files in the file hierarchy that are not described in the
 108 specification.
 109 .It Fl u
 110 Same as
 111 .Fl U
 112 except a status of 2 is returned if the file hierarchy did not match
 113 the specification.
 114 .It Fl x
 115 Don't descend below mount points in the file hierarchy.
 116 .It Fl f Ar file
 117 Read the specification from
 118 .Ar file ,
 119 instead of from the standard input.
 120 .It Fl K Ar keywords
 121 Add the specified (whitespace or comma separated)
 122 .Ar keywords
 123 to the current set of keywords.
 124 .It Fl k Ar keywords
 125 Use the ``type'' keyword plus the specified (whitespace or comma separated)
 126 .Ar keywords
 127 instead of the current set of keywords.
 128 .It Fl p Ar path
 129 Use the file hierarchy rooted in
 130 .Ar path ,
 131 instead of the current directory.
 132 .It Fl s Ar seed
 133 Display a single checksum to the standard error output that represents all
 134 of the files for which the keyword
 135 .Cm cksum
 136 was specified.
 137 The checksum is seeded with the specified value.
 138 .It Fl X Ar exclude-list
 139 The specified file contains
 140 .Xr fnmatch 3
 141 patterns matching files to be excluded from
 142 the specification, one to a line.
 143 If the pattern contains a
 144 .Ql \&/
 145 character, it will be matched against entire pathnames (relative to
 146 the starting directory); otherwise,
 147 it will be matched against basenames only.  No comments are allowed in
 148 the
 149 .Ar exclude-list
 150 file.
 151 .El
 152 .Pp
 153 Specifications are mostly composed of ``keywords'', i.e. strings
 154 that specify values relating to files.
 155 No keywords have default values, and if a keyword has no value set, no
 156 checks based on it are performed.
 157 .Pp
 158 Currently supported keywords are as follows:
 159 .Bl -tag -width Cm
 160 .It Cm cksum
 161 The checksum of the file using the default algorithm specified by
 162 the
 163 .Xr cksum 1
 164 utility.
 165 .It Cm flags
 166 The file flags as a symbolic name.  See
 167 .Xr chflags 1
 168 for information on these names.  If no flags are to be set the string
 169 .Dq none
 170 may be used to override the current default.
 171 .It Cm ignore
 172 Ignore any file hierarchy below this file.
 173 .It Cm gid
 174 The file group as a numeric value.
 175 .It Cm gname
 176 The file group as a symbolic name.
 177 .It Cm md5digest
 178 The MD5 message digest of the file.
 179 .It Cm sha1digest
 180 The
 181 .Tn FIPS
 182 160-1
 183 .Pq Dq Tn SHA-1
 184 message digest of the file.
 185 .It Cm ripemd160digest
 186 The
 187 .Tn RIPEMD160
 188 message digest of the file.
 189 .It Cm mode
 190 The current file's permissions as a numeric (octal) or symbolic
 191 value.
 192 .It Cm nlink
 193 The number of hard links the file is expected to have.
 194 .It Cm nochange
 195 Make sure this file or directory exists but otherwise ignore all attributes.
 196 .It Cm uid
 197 The file owner as a numeric value.
 198 .It Cm uname
 199 The file owner as a symbolic name.
 200 .It Cm size
 201 The size, in bytes, of the file.
 202 .It Cm link
 203 The file the symbolic link is expected to reference.
 204 .It Cm time
 205 The last modification time of the file.
 206 .It Cm type
 207 The type of the file; may be set to any one of the following:
 208 .Pp
 209 .Bl -tag -width Cm -compact
 210 .It Cm block
 211 block special device
 212 .It Cm char
 213 character special device
 214 .It Cm dir
 215 directory
 216 .It Cm fifo
 217 fifo
 218 .It Cm file
 219 regular file
 220 .It Cm link
 221 symbolic link
 222 .It Cm socket
 223 socket
 224 .El
 225 .El
 226 .Pp
 227 The default set of keywords are
 228 .Cm flags ,
 229 .Cm gid ,
 230 .Cm mode ,
 231 .Cm nlink ,
 232 .Cm size ,
 233 .Cm link ,
 234 .Cm time ,
 235 and
 236 .Cm uid .
 237 .Pp
 238 There are four types of lines in a specification.
 239 .Pp
 240 The first type of line sets a global value for a keyword, and consists of
 241 the string ``/set'' followed by whitespace, followed by sets of keyword/value
 242 pairs, separated by whitespace.
 243 Keyword/value pairs consist of a keyword, followed by an equals sign
 244 (``=''), followed by a value, without whitespace characters.
 245 Once a keyword has been set, its value remains unchanged until either
 246 reset or unset.
 247 .Pp
 248 The second type of line unsets keywords and consists of the string
 249 ``/unset'', followed by whitespace, followed by one or more keywords,
 250 separated by whitespace.
 251 .Pp
 252 The third type of line is a file specification and consists of a file
 253 name, followed by whitespace, followed by zero or more whitespace
 254 separated keyword/value pairs.
 255 The file name may be preceded by whitespace characters.
 256 The file name may contain any of the standard file name matching
 257 characters (``['', ``]'', ``?'' or ``*''), in which case files
 258 in the hierarchy will be associated with the first pattern that
 259 they match.
 260 .Pp
 261 Each of the keyword/value pairs consist of a keyword, followed by an
 262 equals sign (``=''), followed by the keyword's value, without
 263 whitespace characters.
 264 These values override, without changing, the global value of the
 265 corresponding keyword.
 266 .Pp
 267 All paths are relative.
 268 Specifying a directory will cause subsequent files to be searched
 269 for in that directory hierarchy.
 270 Which brings us to the last type of line in a specification: a line
 271 containing only the string
 272 .Dq Pa ..\&
 273 causes the current directory
 274 path to ascend one level.
 275 .Pp
 276 Empty lines and lines whose first non-whitespace character is a hash
 277 mark (``#'') are ignored.
 278 .Pp
 279 The
 280 .Nm
 281 utility exits with a status of 0 on success, 1 if any error occurred,
 282 and 2 if the file hierarchy did not match the specification.
 283 A status of 2 is converted to a status of 0 if the
 284 .Fl U
 285 option is used.
 286 .Sh FILES
 287 .Bl -tag -width /etc/mtree -compact
 288 .It Pa /etc/mtree
 289 system specification directory
 290 .El
 291 .Sh EXIT STATUS
 292 .Ex -std
 293 .Sh EXAMPLES
 294 To detect system binaries that have been ``trojan horsed'', it is recommended
 295 that
 296 .Nm
 297 .Fl K
 298 .Cm sha1digest
 299 be run on the file systems, and a copy of the results stored on a different
 300 machine, or, at least, in encrypted form.
 301 The output file itself should be digested using the
 302 .Xr md5 1
 303 utility.
 304 Then, periodically,
 305 .Nm
 306 and
 307 .Xr md5 1
 308 should be run against the on-line specifications.
 309 While it is possible for the bad guys to change the on-line specifications
 310 to conform to their modified binaries, it is believed to be
 311 impractical for them to create a modified specification which has
 312 the same MD5 digest as the original.
 313 .Pp
 314 The
 315 .Fl d
 316 and
 317 .Fl u
 318 options can be used in combination to create directory hierarchies
 319 for distributions and other such things; the files in
 320 .Pa /etc/mtree
 321 were used to create almost all directories in this
 322 .Dx
 323 distribution.
 324 .Pp
 325 To create an
 326 .Pa /etc/mtree
 327 style BSD.*.dist file, use
 328 .Nm
 329 .Fl c
 330 .Fl d
 331 .Fl i
 332 .Fl n
 333 .Fl k
 334 .Cm uname,gname,mode,nochange .
 335 .Sh SEE ALSO
 336 .Xr chflags 1 ,
 337 .Xr chgrp 1 ,
 338 .Xr chmod 1 ,
 339 .Xr cksum 1 ,
 340 .Xr md5 1 ,
 341 .Xr stat 2 ,
 342 .Xr fts 3 ,
 343 .Xr md5 3 ,
 344 .Xr chown 8
 345 .Sh HISTORY
 346 The
 347 .Nm
 348 utility appeared in
 349 .Bx 4.3 Reno .
 350 The
 351 .Tn MD5
 352 digest capability was added in
 353 .Fx 2.1 ,
 354 in response to the widespread use of programs which can spoof
 355 .Xr cksum 1 .
 356 The
 357 .Tn SHA-1
 358 and
 359 .Tn RIPEMD160
 360 digests were added in
 361 .Fx 4.0 ,
 362 as new attacks have demonstrated weaknesses in
 363 .Tn MD5 .
 364 Support for file flags was added in
 365 .Fx 4.0 ,
 366 and mostly comes from
 367 .Nx .