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