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 .\" 4. 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$
  30 .\"
  31 .Dd June 16, 2007
  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 LPUcdeinqruxw
  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 Do not follow symbolic links in the file hierarchy, instead consider
  73 the symbolic link itself in any comparisons.
  74 This is the default.
  75 .It Fl U
  76 Modify the owner, group, permissions, and modification time of existing
  77 files to match the specification and create any missing directories or
  78 symbolic links.
  79 User, group and permissions must all be specified for missing directories
  80 to be created.
  81 Corrected mismatches are not considered errors.
  82 .It Fl c
  83 Print a specification for the file hierarchy to the standard output.
  84 .It Fl d
  85 Ignore everything except directory type files.
  86 .It Fl e
  87 Do not complain about files that are in the file hierarchy, but not in the
  88 specification.
  89 .It Fl i
  90 Indent the output 4 spaces each time a directory level is descended when
  91 creating a specification with the
  92 .Fl c
  93 option.
  94 This does not affect either the /set statements or the comment before each
  95 directory.
  96 It does however affect the comment before the close of each directory.
  97 .It Fl n
  98 Do not emit pathname comments when creating a specification.
  99 Normally
 100 a comment is emitted before each directory and before the close of that
 101 directory when using the
 102 .Fl c
 103 option.
 104 .It Fl q
 105 Quiet mode.
 106 Do not complain when a
 107 .Dq missing
 108 directory cannot be created because it already exists.
 109 This occurs when the directory is a symbolic link.
 110 .It Fl r
 111 Remove any files in the file hierarchy that are not described in the
 112 specification.
 113 .It Fl u
 114 Same as
 115 .Fl U
 116 except a status of 2 is returned if the file hierarchy did not match
 117 the specification.
 118 .It Fl w
 119 Make some errors non-fatal warnings.
 120 .It Fl x
 121 Do not descend below mount points in the file hierarchy.
 122 .It Fl f Ar file
 123 Read the specification from
 124 .Ar file ,
 125 instead of from the standard input.
 126 .Pp
 127 If this option is specified twice, the two specifications are compared
 128 to each other rather than to the file hierarchy.
 129 The specifications will be sorted like output generated using
 130 .Fl c .
 131 The output format in this case is somewhat remniscent of
 132 .Xr comm 1 ,
 133 having "in first spec only", "in second spec only", and "different"
 134 columns, prefixed by zero, one and two TAB characters respectively.
 135 Each entry in the "different" column occupies two lines, one from each specification.
 136 .It Fl K Ar keywords
 137 Add the specified (whitespace or comma separated)
 138 .Ar keywords
 139 to the current set of keywords.
 140 .It Fl k Ar keywords
 141 Use the ``type'' keyword plus the specified (whitespace or comma separated)
 142 .Ar keywords
 143 instead of the current set of keywords.
 144 .It Fl p Ar path
 145 Use the file hierarchy rooted in
 146 .Ar path ,
 147 instead of the current directory.
 148 .It Fl s Ar seed
 149 Display a single checksum to the standard error output that represents all
 150 of the files for which the keyword
 151 .Cm cksum
 152 was specified.
 153 The checksum is seeded with the specified value.
 154 .It Fl X Ar exclude-list
 155 The specified file contains
 156 .Xr fnmatch 3
 157 patterns matching files to be excluded from
 158 the specification, one to a line.
 159 If the pattern contains a
 160 .Ql \&/
 161 character, it will be matched against entire pathnames (relative to
 162 the starting directory); otherwise,
 163 it will be matched against basenames only.
 164 No comments are allowed in
 165 the
 166 .Ar exclude-list
 167 file.
 168 .El
 169 .Pp
 170 Specifications are mostly composed of ``keywords'', i.e., strings
 171 that specify values relating to files.
 172 No keywords have default values, and if a keyword has no value set, no
 173 checks based on it are performed.
 174 .Pp
 175 Currently supported keywords are as follows:
 176 .Bl -tag -width Cm
 177 .It Cm cksum
 178 The checksum of the file using the default algorithm specified by
 179 the
 180 .Xr cksum 1
 181 utility.
 182 .It Cm flags
 183 The file flags as a symbolic name.
 184 See
 185 .Xr chflags 1
 186 for information on these names.
 187 If no flags are to be set the string
 188 .Dq none
 189 may be used to override the current default.
 190 .It Cm ignore
 191 Ignore any file hierarchy below this file.
 192 .It Cm gid
 193 The file group as a numeric value.
 194 .It Cm gname
 195 The file group as a symbolic name.
 196 .It Cm md5digest
 197 The MD5 message digest of the file.
 198 .It Cm sha1digest
 199 The
 200 .Tn FIPS
 201 160-1
 202 .Pq Dq Tn SHA-1
 203 message digest of the file.
 204 .It Cm sha256digest
 205 The
 206 .Tn FIPS
 207 180-2
 208 .Pq Dq Tn SHA-256
 209 message digest of the file.
 210 .It Cm ripemd160digest
 211 The
 212 .Tn RIPEMD160
 213 message digest of the file.
 214 .It Cm mode
 215 The current file's permissions as a numeric (octal) or symbolic
 216 value.
 217 .It Cm nlink
 218 The number of hard links the file is expected to have.
 219 .It Cm nochange
 220 Make sure this file or directory exists but otherwise ignore all attributes.
 221 .It Cm optional
 222 The file is optional; do not complain about the file if it is
 223 not in the file hierarchy.
 224 .It Cm uid
 225 The file owner as a numeric value.
 226 .It Cm uname
 227 The file owner as a symbolic name.
 228 .It Cm size
 229 The size, in bytes, of the file.
 230 .It Cm link
 231 The file the symbolic link is expected to reference.
 232 .It Cm time
 233 The last modification time of the file, in seconds and nanoseconds.
 234 The value should include a period character and exactly nine digits
 235 after the period.
 236 .It Cm type
 237 The type of the file; may be set to any one of the following:
 238 .Pp
 239 .Bl -tag -width Cm -compact
 240 .It Cm block
 241 block special device
 242 .It Cm char
 243 character special device
 244 .It Cm dir
 245 directory
 246 .It Cm fifo
 247 fifo
 248 .It Cm file
 249 regular file
 250 .It Cm link
 251 symbolic link
 252 .It Cm socket
 253 socket
 254 .El
 255 .El
 256 .Pp
 257 The default set of keywords are
 258 .Cm flags ,
 259 .Cm gid ,
 260 .Cm link ,
 261 .Cm mode ,
 262 .Cm nlink ,
 263 .Cm size ,
 264 .Cm time ,
 265 and
 266 .Cm uid .
 267 .Pp
 268 There are four types of lines in a specification.
 269 .Pp
 270 The first type of line sets a global value for a keyword, and consists of
 271 the string ``/set'' followed by whitespace, followed by sets of keyword/value
 272 pairs, separated by whitespace.
 273 Keyword/value pairs consist of a keyword, followed by an equals sign
 274 (``=''), followed by a value, without whitespace characters.
 275 Once a keyword has been set, its value remains unchanged until either
 276 reset or unset.
 277 .Pp
 278 The second type of line unsets keywords and consists of the string
 279 ``/unset'', followed by whitespace, followed by one or more keywords,
 280 separated by whitespace.
 281 .Pp
 282 The third type of line is a file specification and consists of a file
 283 name, followed by whitespace, followed by zero or more whitespace
 284 separated keyword/value pairs.
 285 The file name may be preceded by whitespace characters.
 286 The file name may contain any of the standard file name matching
 287 characters (``['', ``]'', ``?'' or ``*''), in which case files
 288 in the hierarchy will be associated with the first pattern that
 289 they match.
 290 .Pp
 291 Each of the keyword/value pairs consist of a keyword, followed by an
 292 equals sign (``=''), followed by the keyword's value, without
 293 whitespace characters.
 294 These values override, without changing, the global value of the
 295 corresponding keyword.
 296 .Pp
 297 All paths are relative.
 298 Specifying a directory will cause subsequent files to be searched
 299 for in that directory hierarchy.
 300 Which brings us to the last type of line in a specification: a line
 301 containing only the string
 302 .Dq Pa ..\&
 303 causes the current directory
 304 path to ascend one level.
 305 .Pp
 306 Empty lines and lines whose first non-whitespace character is a hash
 307 mark (``#'') are ignored.
 308 .Pp
 309 The
 310 .Nm
 311 utility exits with a status of 0 on success, 1 if any error occurred,
 312 and 2 if the file hierarchy did not match the specification.
 313 A status of 2 is converted to a status of 0 if the
 314 .Fl U
 315 option is used.
 316 .Sh FILES
 317 .Bl -tag -width /etc/mtree -compact
 318 .It Pa /etc/mtree
 319 system specification directory
 320 .El
 321 .Sh EXIT STATUS
 322 .Ex -std
 323 .Sh EXAMPLES
 324 To detect system binaries that have been ``trojan horsed'', it is recommended
 325 that
 326 .Nm
 327 .Fl K
 328 .Cm sha256digest
 329 be run on the file systems, and a copy of the results stored on a different
 330 machine, or, at least, in encrypted form.
 331 The output file itself should be digested using the
 332 .Xr sha256 1
 333 utility.
 334 Then, periodically,
 335 .Nm
 336 and
 337 .Xr sha256 1
 338 should be run against the on-line specifications.
 339 While it is possible for the bad guys to change the on-line specifications
 340 to conform to their modified binaries, it is believed to be
 341 impractical for them to create a modified specification which has
 342 the same SHA-256 digest as the original.
 343 .Pp
 344 The
 345 .Fl d
 346 and
 347 .Fl u
 348 options can be used in combination to create directory hierarchies
 349 for distributions and other such things; the files in
 350 .Pa /etc/mtree
 351 were used to create almost all directories in this
 352 .Fx
 353 distribution.
 354 .Pp
 355 To create an
 356 .Pa /etc/mtree
 357 style BSD.*.dist file, use
 358 .Nm
 359 .Fl c
 360 .Fl d
 361 .Fl i
 362 .Fl n
 363 .Fl k
 364 .Cm uname,gname,mode,nochange.
 365 .Sh SEE ALSO
 366 .Xr chflags 1 ,
 367 .Xr chgrp 1 ,
 368 .Xr chmod 1 ,
 369 .Xr cksum 1 ,
 370 .Xr md5 1 ,
 371 .Xr stat 2 ,
 372 .Xr fts 3 ,
 373 .Xr md5 3 ,
 374 .Xr chown 8
 375 .Sh HISTORY
 376 The
 377 .Nm
 378 utility appeared in
 379 .Bx 4.3 Reno .
 380 The
 381 .Tn MD5
 382 digest capability was added in
 383 .Fx 2.1 ,
 384 in response to the widespread use of programs which can spoof
 385 .Xr cksum 1 .
 386 The
 387 .Tn SHA-1
 388 and
 389 .Tn RIPEMD160
 390 digests were added in
 391 .Fx 4.0 ,
 392 as new attacks have demonstrated weaknesses in
 393 .Tn MD5 .
 394 The
 395 .Tn SHA-256
 396 digest was added in
 397 .Fx 6.0 .
 398 Support for file flags was added in
 399 .Fx 4.0 ,
 400 and mostly comes from
 401 .Nx .