| blob | 22eb829bf94e1985d945c853a4bfe155ce21255b |
1 '\" te
2 .\" Copyright (c) 2006, 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 8 "Oct 26, 2005"
7 .SH NAME
8 bart \- basic audit reporting tool
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fB/usr/bin/bart\fR create [ \fB-n\fR] [\fB-R\fR \fIroot_directory\fR]
13 [\fB-r\fR \fIrules_file\fR | -]
14 .fi
16 .LP
17 .nf
18 \fB/usr/bin/bart\fR create [\fB-n\fR] [\fB-R\fR \fIroot_directory\fR] \fB-I\fR
19 [\fIfile_name\fR]...
20 .fi
22 .LP
23 .nf
24 \fB/usr/bin/bart\fR compare [\fB-i\fR \fIattribute\fR ] [\fB-p\fR]
25 [\fB-r\fR \fIrules_file\fR | -] \fIcontrol-manifest\fR \fItest-manifest\fR
26 .fi
28 .SH DESCRIPTION
29 .sp
30 .LP
31 \fBbart\fR(8) is a tool that performs a file-level check of the software
32 contents of a system.
33 .sp
34 .LP
35 You can also specify the files to track and the types of discrepancies to flag
36 by means of a rules file, \fBbart_rules\fR. See \fBbart_rules\fR(4).
37 .sp
38 .LP
39 The \fBbart\fR utility performs two basic functions:
40 .sp
41 .ne 2
42 .na
43 \fB\fBbart create\fR\fR
44 .ad
45 .RS 16n
46 The manifest generator tool takes a file-level \fBsnapshot\fR of a system. The
47 output is a catalog of file attributes referred to as a \fBmanifest\fR. See
48 \fBbart_manifest\fR(4).
49 .sp
50 You can specify that the list of files be cataloged in three ways. Use \fBbart
51 create\fR with no options, specify the files by name on the command line, or
52 create a rules file with directives that specify which the files to monitor.
53 See \fBbart_rules\fR(4).
54 .sp
55 By default, the manifest generator catalogs all attributes of all files in the
56 root (\fB/\fR) file system. File systems mounted on the root file system are
57 cataloged only if they are of the same type as the root file system.
58 .sp
59 For example, \fB/\fR, \fB/usr\fR, and \fB/opt\fR are separate UFS file systems.
60 \fB/usr\fR and \fB/opt\fR are mounted on \fB/\fR. Therefore, all three file
61 systems are cataloged. However, \fB/tmp\fR, also mounted on \fB/\fR, is not
62 cataloged because it is a TMPFS file system. Mounted CD-ROMs are not cataloged
63 since they are HSFS file systems.
64 .RE
66 .sp
67 .ne 2
68 .na
69 \fB\fBbart compare\fR\fR
70 .ad
71 .RS 16n
72 The report tool compares two manifests. The output is a list of per-file
73 attribute discrepancies. These discrepancies are the differences between two
74 manifests: a control manifest and a test manifest.
75 .sp
76 A discrepancy is a change to any attribute for a given file cataloged by both
77 manifests. A new file or a deleted file in a manifest is reported as a
78 discrepancy.
79 .sp
80 The reporting mechanism provides two types of output: verbose and programmatic.
81 Verbose output is localized and presented on multiple lines, while programmatic
82 output is more easily parsable by other programs. See \fBOUTPUT\fR.
83 .sp
84 By default, the report tool generates verbose output where all discrepancies
85 are reported except for modified directory timestamps (\fBdirmtime\fR
86 attribute).
87 .sp
88 To ensure consistent and accurate comparison results, \fIcontrol-manifest\fR
89 and \fItest-manifest\fR must be built with the same rules file.
90 .RE
92 .sp
93 .LP
94 Use the rules file to ignore specified files or subtrees when you generate a
95 manifest or compare two manifests. Users can compare manifests from different
96 perspectives by re-running the \fBbart compare\fR command with different rules
97 files.
98 .SH OPTIONS
99 .sp
100 .LP
101 The following options are supported:
102 .sp
103 .ne 2
104 .na
105 \fB\fB-i\fR \fIattribute\fR ...\fR
106 .ad
107 .RS 21n
108 Specify the file attributes to be ignored globally. Specify attributes as a
109 comma separated list.
110 .sp
111 This option produces the same behavior as supplying the file attributes to a
112 global \fBIGNORE\fR keyword in the rules file. See \fBbart_rules\fR(4).
113 .RE
115 .sp
116 .ne 2
117 .na
118 \fB\fB-I\fR [\fIfile_name\fR...]\fR
119 .ad
120 .RS 21n
121 Specify the input list of files. The file list can be specified at the command
122 line or read from standard input.
123 .RE
125 .sp
126 .ne 2
127 .na
128 \fB\fB-n\fR\fR
129 .ad
130 .RS 21n
131 Prevent computation of content signatures for all regular files in the file
132 list.
133 .RE
135 .sp
136 .ne 2
137 .na
138 \fB\fB-p\fR\fR
139 .ad
140 .RS 21n
141 Display manifest comparison output in ``programmatic mode,'' which is suitable
142 for programmatic parsing. The output is not localized.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fB-r\fR \fIrules_file\fR\fR
149 .ad
150 .RS 21n
151 Use \fIrules_file\fR to specify which files and directories to catalog, and to
152 define which file attribute discrepancies to flag. If \fIrules_file\fR is
153 \fB-\fR, then the rules are read from standard input. See \fBbart_rules\fR(4)
154 for the definition of the syntax.
155 .RE
157 .sp
158 .ne 2
159 .na
160 \fB\fB-R\fR \fIroot_directory\fR\fR
161 .ad
162 .RS 21n
163 Specify the root directory for the manifest. All paths specified by the rules,
164 and all paths reported in the manifest, are relative to \fIroot_directory\fR.
165 .LP
166 Note -
167 .sp
168 .RS 2
169 The root file system of any non-global zones must not be referenced with the
170 \fB-R\fR option. Doing so might damage the global zone's file system, might
171 compromise the security of the global zone, and might damage the non-global
172 zone's file system. See \fBzones\fR(5).
173 .RE
174 .RE
176 .SH OPERANDS
177 .sp
178 .LP
179 bart allows quoting of operands. This is particularly important for white-space
180 appearing in subtree and subtree modifier specifications.
181 .sp
182 .LP
183 The following operands are supported:
184 .sp
185 .ne 2
186 .na
187 \fB\fIcontrol-manifest\fR\fR
188 .ad
189 .RS 20n
190 Specify the manifest created by \fBbart create\fR on the control system.
191 .RE
193 .sp
194 .ne 2
195 .na
196 \fB\fItest-manifest\fR\fR
197 .ad
198 .RS 20n
199 Specify the manifest created by \fBbart create\fR on the test system.
200 .RE
202 .SH OUTPUT
203 .sp
204 .LP
205 The \fBbart create\fR and \fBbart compare\fR commands write output to standard
206 output, and write error messages to standard error.
207 .sp
208 .LP
209 The \fBbart create\fR command generates a system manifest. See
210 \fBbart_manifest\fR(4).
211 .sp
212 .LP
213 When the \fBbart compare\fR command compares two system manifests, it generates
214 a list of file differences. By default, the comparison output is localized.
215 However, if the \fB-p\fR option is specified, the output is generated in a form
216 that is suitable for programmatic manipulation.
217 .SS "Default Format"
218 .sp
219 .in +2
220 .nf
221 \fIfilename\fR
222 \fIattribute\fR control:\fIxxxx\fR test:\fIyyyy\fR
223 .fi
224 .in -2
225 .sp
227 .sp
228 .ne 2
229 .na
230 \fB\fIfilename\fR\fR
231 .ad
232 .RS 13n
233 Name of the file that differs between \fIcontrol-manifest\fR and
234 \fItest-manifest\fR. For file names that contain embedded whitespace or newline
235 characters, see \fBbart_manifest\fR(4).
236 .RE
238 .sp
239 .ne 2
240 .na
241 \fB\fIattribute\fR\fR
242 .ad
243 .RS 13n
244 The name of the file attribute that differs between the manifests that are
245 compared. \fIxxxx\fR is the attribute value from \fIcontrol-manifest\fR, and
246 \fIyyyy\fR is the attribute value from \fItest-manifest\fR. When discrepancies
247 for multiple attributes occur for the same file, each difference is noted on a
248 separate line.
249 .sp
250 The following attributes are supported:
251 .sp
252 .ne 2
253 .na
254 \fBacl\fR
255 .ad
256 .RS 12n
257 ACL attributes for the file. For a file with ACL attributes, this field
258 contains the output from \fBacltotext()\fR.
259 .RE
261 .sp
262 .ne 2
263 .na
264 \fBall\fR
265 .ad
266 .RS 12n
267 All attributes.
268 .RE
270 .sp
271 .ne 2
272 .na
273 \fBcontents\fR
274 .ad
275 .RS 12n
276 Checksum value of the file. This attribute is only specified for regular files.
277 If you turn off context checking or if checksums cannot be computed, the value
278 of this field is \fB-\fR.
279 .RE
281 .sp
282 .ne 2
283 .na
284 \fBdest\fR
285 .ad
286 .RS 12n
287 Destination of a symbolic link.
288 .RE
290 .sp
291 .ne 2
292 .na
293 \fBdevnode\fR
294 .ad
295 .RS 12n
296 Value of the device node. This attribute is for character device files and
297 block device files only.
298 .RE
300 .sp
301 .ne 2
302 .na
303 \fBdirmtime\fR
304 .ad
305 .RS 12n
306 Modification time in seconds since 00:00:00 UTC, January 1, 1970 for
307 directories.
308 .RE
310 .sp
311 .ne 2
312 .na
313 \fBgid\fR
314 .ad
315 .RS 12n
316 Numerical group ID of the owner of this entry.
317 .RE
319 .sp
320 .ne 2
321 .na
322 \fBlnmtime\fR
323 .ad
324 .RS 12n
325 Creation time for links.
326 .RE
328 .sp
329 .ne 2
330 .na
331 \fBmode\fR
332 .ad
333 .RS 12n
334 Octal number that represents the permissions of the file.
335 .RE
337 .sp
338 .ne 2
339 .na
340 \fBmtime\fR
341 .ad
342 .RS 12n
343 Modification time in seconds since 00:00:00 UTC, January 1, 1970 for files.
344 .RE
346 .sp
347 .ne 2
348 .na
349 \fBsize\fR
350 .ad
351 .RS 12n
352 File size in bytes.
353 .RE
355 .sp
356 .ne 2
357 .na
358 \fBtype\fR
359 .ad
360 .RS 12n
361 Type of file.
362 .RE
364 .sp
365 .ne 2
366 .na
367 \fBuid\fR
368 .ad
369 .RS 12n
370 Numerical user ID of the owner of this entry.
371 .RE
373 .RE
375 .sp
376 .LP
377 The following default output shows the attribute differences for the
378 \fB/etc/passwd\fR file. The output indicates that the \fBsize\fR, \fBmtime\fR,
379 and \fBcontents\fR attributes have changed.
380 .sp
381 .in +2
382 .nf
383 /etc/passwd:
384 size control:74 test:81
385 mtime control:3c165879 test:3c165979
386 contents control:daca28ae0de97afd7a6b91fde8d57afa
387 test:84b2b32c4165887355317207b48a6ec7
388 .fi
389 .in -2
390 .sp
392 .SS "Programmatic Format"
393 .sp
394 .in +2
395 .nf
396 \fIfilename\fR \fIattribute\fR \fIcontrol-val\fR \fItest-val\fR [\fIattribute\fR \fIcontrol-val\fR \fItest-val\fR]*
397 .fi
398 .in -2
399 .sp
401 .sp
402 .ne 2
403 .na
404 \fB\fIfilename\fR\fR
405 .ad
406 .sp .6
407 .RS 4n
408 Same as \fIfilename\fR in the default format.
409 .RE
411 .sp
412 .ne 2
413 .na
414 \fB\fIattribute\fR \fIcontrol-val\fR \fItest-val\fR\fR
415 .ad
416 .sp .6
417 .RS 4n
418 A description of the file attributes that differ between the control and test
419 manifests for each file. Each entry includes the attribute value from each
420 manifest. See \fBbart_manifest\fR(4) for the definition of the attributes.
421 .RE
423 .sp
424 .LP
425 Each line of the programmatic output describes all attribute differences for a
426 single file.
427 .sp
428 .LP
429 The following programmatic output shows the attribute differences for the
430 \fB/etc/passwd\fR file. The output indicates that the \fBsize\fR, \fBmtime\fR,
431 and \fBcontents\fR attributes have changed.
432 .sp
433 .in +2
434 .nf
435 /etc/passwd size 74 81 mtime 3c165879 3c165979
436 contents daca28ae0de97afd7a6b91fde8d57afa 84b2b32c4165887355317207b48a6ec7
437 .fi
438 .in -2
439 .sp
441 .SH EXIT STATUS
442 .SS "Manifest Generator"
443 .sp
444 .LP
445 The manifest generator returns the following exit values:
446 .sp
447 .ne 2
448 .na
449 \fB\fB0\fR\fR
450 .ad
451 .RS 6n
452 Success
453 .RE
455 .sp
456 .ne 2
457 .na
458 \fB\fB1\fR\fR
459 .ad
460 .RS 6n
461 Non-fatal error when processing files; for example, permission problems
462 .RE
464 .sp
465 .ne 2
466 .na
467 \fB\fB>1\fR\fR
468 .ad
469 .RS 6n
470 Fatal error; for example, invalid command-line options
471 .RE
473 .SS "Report Tool"
474 .sp
475 .LP
476 The report tool returns the following exit values:
477 .sp
478 .ne 2
479 .na
480 \fB\fB0\fR\fR
481 .ad
482 .RS 6n
483 No discrepancies reported
484 .RE
486 .sp
487 .ne 2
488 .na
489 \fB\fB1\fR\fR
490 .ad
491 .RS 6n
492 Discrepancies found
493 .RE
495 .sp
496 .ne 2
497 .na
498 \fB\fB>1\fR\fR
499 .ad
500 .RS 6n
501 Fatal error executing comparison
502 .RE
504 .SH EXAMPLES
505 .LP
506 \fBExample 1 \fRCreating a Default Manifest Without Computing Checksums
507 .sp
508 .LP
509 The following command line creates a default manifest, which consists of all
510 files in the \fB/\fR file system. The \fB-n\fR option prevents computation of
511 checksums, which causes the manifest to be generated more quickly.
513 .sp
514 .in +2
515 .nf
516 bart create -n
517 .fi
518 .in -2
519 .sp
521 .LP
522 \fBExample 2 \fRCreating a Manifest for a Specified Subtree
523 .sp
524 .LP
525 The following command line creates a manifest that contains all files in the
526 \fB/home/nickiso\fR subtree.
528 .sp
529 .in +2
530 .nf
531 bart create -R /home/nickiso
532 .fi
533 .in -2
534 .sp
536 .LP
537 \fBExample 3 \fRCreating a Manifest by Using Standard Input
538 .sp
539 .LP
540 The following command line uses output from the \fBfind\fR(1) command to
541 generate the list of files to be cataloged. The \fBfind\fR output is used as
542 input to the \fBbart create\fR command that specifies the \fB-I\fR option.
544 .sp
545 .in +2
546 .nf
547 find /home/nickiso -print | bart create -I
548 .fi
549 .in -2
550 .sp
552 .LP
553 \fBExample 4 \fRCreating a Manifest by Using a Rules File
554 .sp
555 .LP
556 The following command line uses a rules file, \fBrules\fR, to specify the files
557 to be cataloged.
559 .sp
560 .in +2
561 .nf
562 bart create -r rules
563 .fi
564 .in -2
565 .sp
567 .LP
568 \fBExample 5 \fRComparing Two Manifests and Generating Programmatic Output
569 .sp
570 .LP
571 The following command line compares two manifests and produces output suitable
572 for parsing by a program.
574 .sp
575 .in +2
576 .nf
577 bart compare -p manifest1 manifest2
578 .fi
579 .in -2
580 .sp
582 .LP
583 \fBExample 6 \fRComparing Two Manifests and Specifying Attributes to Ignore
584 .sp
585 .LP
586 The following command line compares two manifests. The \fBdirmtime\fR,
587 \fBlnmtime\fR, and \fBmtime\fR attributes are not compared.
589 .sp
590 .in +2
591 .nf
592 bart compare -i dirmtime,lnmtime,mtime manifest1 manifest2
593 .fi
594 .in -2
595 .sp
597 .LP
598 \fBExample 7 \fRComparing Two Manifests by Using a Rules File
599 .sp
600 .LP
601 The following command line uses a rules file, \fBrules\fR, to compare two
602 manifests.
604 .sp
605 .in +2
606 .nf
607 bart compare -r rules manifest1 manifest2
608 .fi
609 .in -2
610 .sp
612 .SH ATTRIBUTES
613 .sp
614 .LP
615 See \fBattributes\fR(5) for descriptions of the following attributes:
616 .sp
618 .sp
619 .TS
620 box;
621 c | c
622 l | l .
623 ATTRIBUTE TYPE ATTRIBUTE VALUE
624 _
625 Interface Stability Evolving
626 .TE
628 .SH SEE ALSO
629 .sp
630 .LP
631 \fBcksum\fR(1), \fBdigest\fR(1), \fBfind\fR(1), \fBbart_manifest\fR(4),
632 \fBbart_rules\fR(4), \fBattributes\fR(5)
633 .SH NOTES
634 .sp
635 .LP
636 The file attributes of certain system libraries can be temporarily altered by
637 the system as it boots. To avoid triggering false warnings, you should compare
638 manifests only if they were both created with the system in the same state;
639 that is, if both were created in single-user or both in multi-user.