usr/src/man/man4/bart_rules.4

   1 '\" te
   2 .\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH BART_RULES 4 "Sep 9, 2003"
   7 .SH NAME
   8 bart_rules \- bart rules file
   9 .SH DESCRIPTION
  10 .sp
  11 .LP
  12 The \fBbart_rules\fR file is a text file that is used by the \fBbart\fR(1M)
  13 command. The rules file determines which files to validate and which file
  14 attributes of those files to ignore.
  15 .sp
  16 .LP
  17 Some lines are ignored by the manifest comparison tool. Ignored lines include
  18 blank lines, lines that consist only of white space, and comments that begin
  19 with \fB#\fR.
  20 .sp
  21 .LP
  22 The rules file supports three directives: \fBCHECK\fR, \fBIGNORE\fR, and a
  23 \fIsubtree\fR directive, which is an absolute path name and optional pattern
  24 matching modifiers. Each \fBCHECK\fR, \fBIGNORE\fR, and \fIsubtree\fR directive
  25 must be on a separate line. Bart supports continuation of long lines using a
  26 backslash (\fB\e\fR). The rules file uses the directives to create logical
  27 blocks.
  28 .SS "Syntax"
  29 .sp
  30 .LP
  31 The syntax for the rules file is as follows:
  32 .sp
  33 .in +2
  34 .nf
  35 [IGNORE \fIattribute\fR...]*
  36 [CHECK] [\fIattribute\fR...]*
  37
  38 \fIsubtree1\fR [\fIpattern\fR...]*
  39 [IGNORE \fIattribute\fR...]*
  40 [CHECK] [\fIattribute\fR...]*
  41
  42 \fIsubtree2\fR [\fIpattern\fR...]*
  43 \fIsubtree3\fR [\fIpattern\fR...]*
  44 \fIsubtree4\fR [\fIpattern\fR...]*
  45 [IGNORE \fIattribute\fR...]*
  46 [CHECK] [\fIattribute\fR...]*
  47 \&...
  48 .fi
  49 .in -2
  50
  51 .SS "Rule Blocks"
  52 .sp
  53 .LP
  54 Rule blocks are composed of statements that are created by using directives and
  55 arguments.
  56 .sp
  57 .LP
  58 There are three types of blocks:
  59 .sp
  60 .ne 2
  61 .na
  62 \fBGlobal Block\fR
  63 .ad
  64 .RS 16n
  65 The first block in the file. The block is considered ``global'' if it specifies
  66 \fBCHECK\fR and \fBIGNORE\fR statements, but no previous subtree statement. A
  67 global block pertains to all subsequent blocks.
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fBLocal block\fR
  74 .ad
  75 .RS 16n
  76 A block that specifies \fBCHECK\fR and \fBIGNORE\fR statements as well as a
  77 subtree directive. The rules in this block pertain to files and directories
  78 found in the specified subtree.
  79 .RE
  80
  81 .sp
  82 .ne 2
  83 .na
  84 \fBHeir block\fR
  85 .ad
  86 .RS 16n
  87 A block that contains a null \fBCHECK\fR statement, no arguments. This block
  88 inherits the global \fBCHECK\fR statements and \fBIGNORE\fR statements.
  89 .RE
  90
  91 .sp
  92 .LP
  93 The order in which \fBCHECK\fR and \fBIGNORE\fR statements appear in blocks is
  94 important. The \fBbart\fR command processes \fBCHECK\fR and \fBIGNORE\fR
  95 statements in the order in which they are read, with later statements
  96 overriding earlier statements.
  97 .sp
  98 .LP
  99 Subtree specifications must appear one per line. Each specification must begin
 100 with an absolute path name. Optionally, each specification can be followed by
 101 pattern-matching arguments.
 102 .sp
 103 .LP
 104 When a file system being tracked belongs to more than one subtree directive,
 105 \fBbart\fR performs the following resolution steps:
 106 .RS +4
 107 .TP
 108 .ie t \(bu
 109 .el o
 110 Applies the \fBCHECK\fR and \fBIGNORE\fR statements set in the global block.
 111 Note that all \fBCHECK\fR and \fBIGNORE\fR statements are processed in order.
 112 .RE
 113 .RS +4
 114 .TP
 115 .ie t \(bu
 116 .el o
 117 Finds the last subtree directive that matches the file.
 118 .RE
 119 .RS +4
 120 .TP
 121 .ie t \(bu
 122 .el o
 123 Processes the \fBCHECK\fR and \fBIGNORE\fR statements that belong to the last
 124 matching subtree directive. These statements are processed in the order in
 125 which they are read, overriding global settings.
 126 .RE
 127 .SS "Pattern Matching Statements"
 128 .sp
 129 .LP
 130 There are two types of pattern matching statements
 131 .sp
 132 .ne 2
 133 .na
 134 \fBAND\fR
 135 .ad
 136 .RS 7n
 137 For a given subtree directive, all pattern matching statements are logically
 138 ANDed with the subtree. Patterns have the following syntax:
 139 .RS +4
 140 .TP
 141 .ie t \(bu
 142 .el o
 143 Wildcards are permitted for both the subtree and pattern matching statements.
 144 .RE
 145 .RS +4
 146 .TP
 147 .ie t \(bu
 148 .el o
 149 The exclamation point (\fB!\fR) character represents logical NOT.
 150 .RE
 151 .RS +4
 152 .TP
 153 .ie t \(bu
 154 .el o
 155 A pattern that terminates with a slash is a subtree. The absence of a slash
 156 indicates that the pattern is not a directory. The subtree itself does not
 157 require an end slash.
 158 .RE
 159 For example, the following subtree example includes the contents of
 160 \fB/home/nickiso/src\fR except for object files, core files, and all of the
 161 SCCS subtrees. Note that directory names that terminate with \fB\&.o\fR and
 162 directories named \fBcore\fR are \fBnot\fR excluded because the patterns
 163 specified do not terminate with \fB/\fR.
 164 .sp
 165 .in +2
 166 .nf
 167 /home/nickiso/src !*.o !core !SCCS/
 168 CHECK  all
 169 .fi
 170 .in -2
 171
 172 .RE
 173
 174 .sp
 175 .ne 2
 176 .na
 177 \fBOR\fR
 178 .ad
 179 .RS 7n
 180 Group multiple subtree directives together. Such subtree directives are
 181 logically ORed together.
 182 .sp
 183 .in +2
 184 .nf
 185 /home/nickiso/src !*.o !core
 186 /home/nickiso/Mail
 187 /home/nickiso/docs *.sdw
 188 CHECK   all
 189 IGNORE  mtime lnmtime dirmtime
 190 .fi
 191 .in -2
 192
 193 The files included in the previous example are as follows:
 194 .RS +4
 195 .TP
 196 .ie t \(bu
 197 .el o
 198 Everything under \fB/home/nickiso/src\fR except for \fB*.o\fR and \fBcore\fR
 199 files
 200 .RE
 201 .RS +4
 202 .TP
 203 .ie t \(bu
 204 .el o
 205 Everything under \fB/home/nickiso/Mail\fR
 206 .RE
 207 .RS +4
 208 .TP
 209 .ie t \(bu
 210 .el o
 211 All files under \fB/home/nickiso/docs\fR that end in \fB*.sdw\fR
 212 .RE
 213 For these files, all attributes are checked except for modification times.
 214 .RE
 215
 216 .SS "File Attributes"
 217 .sp
 218 .LP
 219 The \fBbart\fR command uses \fBCHECK\fR and \fBIGNORE\fR statements to define
 220 which attributes to track or ignore. Each attribute has an associated keyword.
 221 .sp
 222 .LP
 223 The attribute keywords are as follows:
 224 .sp
 225 .ne 2
 226 .na
 227 \fBacl\fR
 228 .ad
 229 .RS 12n
 230 ACL attributes for the file. For a file with ACL attributes, this field
 231 contains the output from \fBacltotext()\fR.
 232 .RE
 233
 234 .sp
 235 .ne 2
 236 .na
 237 \fBall\fR
 238 .ad
 239 .RS 12n
 240 All attributes.
 241 .RE
 242
 243 .sp
 244 .ne 2
 245 .na
 246 \fBcontents\fR
 247 .ad
 248 .RS 12n
 249 Checksum value of the file. This attribute is only specified for regular files.
 250 If you turn off context checking or if checksums cannot be computed, the value
 251 of this field is \fB-\fR.
 252 .RE
 253
 254 .sp
 255 .ne 2
 256 .na
 257 \fBdest\fR
 258 .ad
 259 .RS 12n
 260 Destination of a symbolic link.
 261 .RE
 262
 263 .sp
 264 .ne 2
 265 .na
 266 \fBdevnode\fR
 267 .ad
 268 .RS 12n
 269 Value of the device node. This attribute is for character device files and
 270 block device files only.
 271 .RE
 272
 273 .sp
 274 .ne 2
 275 .na
 276 \fBdirmtime\fR
 277 .ad
 278 .RS 12n
 279 Modification time in seconds since 00:00:00 UTC, January 1, 1970 for
 280 directories.
 281 .RE
 282
 283 .sp
 284 .ne 2
 285 .na
 286 \fBgid\fR
 287 .ad
 288 .RS 12n
 289 Numerical group ID of the owner of this entry.
 290 .RE
 291
 292 .sp
 293 .ne 2
 294 .na
 295 \fBlnmtime\fR
 296 .ad
 297 .RS 12n
 298 Creation time for links.
 299 .RE
 300
 301 .sp
 302 .ne 2
 303 .na
 304 \fBmode\fR
 305 .ad
 306 .RS 12n
 307 Octal number that represents the permissions of the file.
 308 .RE
 309
 310 .sp
 311 .ne 2
 312 .na
 313 \fBmtime\fR
 314 .ad
 315 .RS 12n
 316 Modification time in seconds since 00:00:00 UTC, January 1, 1970 for files.
 317 .RE
 318
 319 .sp
 320 .ne 2
 321 .na
 322 \fBsize\fR
 323 .ad
 324 .RS 12n
 325 File size in bytes.
 326 .RE
 327
 328 .sp
 329 .ne 2
 330 .na
 331 \fBtype\fR
 332 .ad
 333 .RS 12n
 334 Type of file.
 335 .RE
 336
 337 .sp
 338 .ne 2
 339 .na
 340 \fBuid\fR
 341 .ad
 342 .RS 12n
 343 Numerical user ID of the owner of this entry.
 344 .RE
 345
 346 .SH EXAMPLES
 347 .LP
 348 \fBExample 1 \fRSample Rules File
 349 .sp
 350 .LP
 351 The following is a sample rules file:
 352
 353 .sp
 354 .in +2
 355 .nf
 356 # Global rules, track everything except dirmtime.
 357 CHECK   all
 358 IGNORE  dirmtime
 359
 360 # The files in /data* are expected to change, so don't bother
 361 # tracking the attributes expected to change.
 362 # Furthermore, by specifying ``IGNORE contents,'' you save
 363 # time and resources.
 364 /data*
 365 IGNORE  contents mtime size
 366
 367 /home/nickiso f* bar/
 368 IGNORE  acl
 369
 370 # For /usr, apply the global rules.
 371 /usr
 372 CHECK
 373
 374 # Note: Since /usr/tmp follows the /usr block, the /usr/tmp
 375 # subtree is subjected to the ``IGNORE all.''
 376 /usr/tmp
 377 /home/nickiso *.o
 378 /home/nickiso core
 379 /home/nickiso/proto
 380 IGNORE  all
 381 .fi
 382 .in -2
 383
 384 .sp
 385 .LP
 386 The following files are cataloged based on the sample rules file:
 387
 388 .RS +4
 389 .TP
 390 .ie t \(bu
 391 .el o
 392 All attributes, except for \fBdirmtime\fR, \fBmtime\fR, \fBsize\fR, and
 393 \fBcontents\fR, are tracked for files under the \fB/data*\fR subtrees.
 394 .RE
 395 .RS +4
 396 .TP
 397 .ie t \(bu
 398 .el o
 399 Files under the \fB/usr\fR subtree, except for \fB/usr/tmp\fR, are cataloged by
 400 using the global rules.
 401 .RE
 402 .RS +4
 403 .TP
 404 .ie t \(bu
 405 .el o
 406 If the \fB/home/nickiso/foo.c\fR file exists, its attributes, except for
 407 \fBacl\fR and \fBdirmtime\fR, are cataloged.
 408 .RE
 409 .RS +4
 410 .TP
 411 .ie t \(bu
 412 .el o
 413 All \fB\&.o\fR and \fBcore\fR files under \fB/home/nickiso\fR, as well as the
 414 \fB/home/nickiso/proto\fR and \fB/usr/tmp\fR subtrees, are ignored.
 415 .RE
 416 .RS +4
 417 .TP
 418 .ie t \(bu
 419 .el o
 420 If the \fB/home/nickiso/bar/foo.o\fR file exists, it is ignored because it is
 421 subject to the last block.
 422 .RE
 423 .SH SEE ALSO
 424 .sp
 425 .LP
 426 \fBbart\fR(1M), \fBbart_manifest\fR(4), \fBattributes\fR(5)