.\"  $HeadURL$ $LastChangedRevision$
.pso fad-config --format=man
.TH FADSCAN 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.ne 5
.SH NAME
fadscan \- Filesystem scanner
.br
.ne 5
.SH SYNOPSIS
.B fadscan
[
.B \-V
|
.B \-\-version
] [
.B \-v
|
.B \-\-verbose
|
.B \-d
.I level
|
.B \-\-debug=\fIlevel
] [
.B \-h
|
.B \-\-help
] [
.B \-p
|
.B \-\-list\-paths
] 
[
.B \-\-no\-crcs
]
{
.B \-i
|
.B \-\-mode\-init
|
.B \-c
|
.B \-\-mode\-check
|
.B \-r
|
.B \-\-mode\-refresh
|
.B \-s
|
.B \-\-mode\-schedule
} [ 
.B \-\-config\-dir=\fIcfgdir
] [ 
.B \-\-log\-dir=\fIlogdir
] [ 
.B \-\-state\-dir=\fIsttdir
] [
.B \-\-gzip
|
.B \-\-compress
|
.B \-\-no\-compress
] [
.B \-m 
.I addr
|
.B \-\-mail=\fIaddr
[ \fR\.\.\.  ] ]
.I scanid
.br
.ne 5
.SH DESCRIPTION
.B Fadscan
is designed to be run on a day by day basis,
reporting differences between the state of a specified
set of files on a previous occasion and their state at runtime.
.PP
.B Fadscan
is useful as a security tool, and as a tool to remind the
forgetful sysadmin to log system configuration changes,
and for those who are simply curious what is happening
on their system.
.PP
.B Fadscan
operates in four modes:
initialize, check, refresh and schedule which correspond to the options
.B \-i\fR, 
.B \-c\fR, 
.B \-r\fR 
and 
.B \-s\fR. 
In all modes, 
.B fadscan
operates on a fileset defined by a configuration file, which is
in turn defined by the command line parameter
.I scanid\fR.
.PP
In initialize mode, 
.B fadscan
scans the fileset recording various attributes of each candidate file.
The information is written in FAD format
(see 
.B fad\fR(5)).
The resulting FAD file is preserved to facilitate subsequent checks
and refreshes. This FAD file is called the base snapshot. The base
snapshot will be overwritten by subsequent initializes, refreshes
or post-schedule checks.
.PP
In refresh mode,
.B fadscan
scans the fileset reporting important differences in the state of
any of the files. Additionally it refreshes the base snapshot.
Subsequent checks and refreshes will then compare the fileset with the
refreshed base snapshot file.
.PP
In schedule mode,
.B fadscan
schedules a refresh to be made at the next invocation in check mode. It
does this by creating a schedule file, which is detected the next time
.B fadscan
is run in check mode. This
is intended to facilitate refreshing when fadscan is invoked by 
.B cron\fR(8)
in check mode. See 
.B EXAMPLES 
below for further explanation of operating 
.B fadscan
with
.B cron\fR(8).
.PP
In check mode,
.B fadscan
scans the fileset reporting differences in the state of any of the files. 
If the check is a post-scheduled check, then the temporary base snapshot,
created during the scan, is preserved to become the new base snapshot, and
the schedule file is deleted.
.PP 
.ne 5
.SH CONFIGURATION
.B Fadscan
reads the definition of a fileset 
.I scanid
from the file
.B \*[fad_etc_prefix]/fadscan/\fIscanid\fR.
.PP
This file must be an executable, which when run writes the list of files
to monitor to standard output; this is based on the assumption that
.B find\fR(1)
is a better tool for generating file lists than 
.B fadscan
itself.
.ne 5
.SH OPTIONS
.TP 25
.B \-c\fR,\fB\-\-mode\-check
Operate in check mode.
.TP
.B \-\-compress
With the exception of the small configuration file, all files
written are compressed with 
.B compress\fR(1). 
.TP
.B \-d \fIlevel\fR, \fB\-\-debug \fIlevel\fR
Determines how verbose
.B fadscan
will be. The message types displayed for the different values of 
.I level
are as follows:
.RS 25
.TP 5
.B 0
internal errors only
.TP
.B 1
internal errors and normal errors 
.TP
.B 2
internal errors, normal errors and warnings
.TP 
.B 3
internal errors, normal errors, warnings and informational messages
.TP 
.B >3
all the above plus application-specific debug messages.
.RE
.TP
.B \-\-config\-dir=\fIcfgdir\fB
This option is used to specify an alternative location 
for 
.I scanid
directories. The
default is 
.B \*[fad_etc_prefix]/fadscan\fR.
.TP 
.B \-\-log\-dir=\fIlogdir\fB
This option is used to specify an alternative location
for reports generated by
.B fadscan\fR.
The default is
.B \*[fad_log_prefix]/fadscan\fR.
.TP
.B \-\-state\-dir=\fIsttdir\fB
This option is used to specify an alternative location
for state information which must be preserved between invocations of
.B fadscan\fR.
The default is
.B \*[fad_state_prefix]/fadscan\fR.
.TP
.B \-\-gzip
With the exception of the small configuration file, all files 
written are compressed with 
.B gzip\fR(1). 
.TP
.B \-h\fR, \fB\-\-help
Displays a brief usage message.
.TP
.B \-i\fR,\fB\-\-mode\-init
Operate in initialize mode.
.TP
.B \-m\fR,\fB\-\-mail=\fIaddr\fB
The resulting log file will be mailed to
.I addr\fR.
This option only makes sense when used in conjunction with 
.B \-c
or 
.B \-r\fR.
Multiple email addresses require multiple
.B \-m
options.
.TP
.B \-\-no\-crcs
Suppress the writing of CRCs; this will considerably speed up the process of
collecting the data about each filesystem item, but will make it impossible 
to distinguish files whose contents have changed.
.TP
.B \-\-no\-compress
All files written are not compressed. 
.TP
.B \-p\fR, \fB\-\-list\-paths
List the compiled-in paths of various files and directories that
.B fadscan
uses.
.TP
.B \-r\fR,\fB\-\-mode\-refresh
Operate in refresh mode.
.TP
.B \-s\fR,\fB\-\-mode\-schedule
Operate in schedule mode.
.TP 
.B \-v\fR, \fB\-\-verbose
Equivalent to
.B \-d 3\fR.
.TP
.B \-V\fR, \fB\-\-version
Print the program's version number and exit.
.br
.ne 5
.SH EXIT STATUS
On success
.B fadscan
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP 25
.B \*[fad_etc_prefix]/fadscan/\fIscanid
Default location of configuration file for 
.I scanid\fR.
.TP
.B \*[fad_state_prefix]/fadscan/\fIscanid\fB-basesnap.*
Default location of base snapshot for
.I scanid\fR,
generated by the
.B \-i
option.
.TP
.B \*[fad_state_prefix]/fadscan/\fIscanid\fB-scheduled
Default location for schedule request files for 
.I scanid\fR,
generated by the
.B \-s
option.
.TP
.B \*[fad_state_prefix]/fadscan/\fIscanid\fB-tempsnap.*
Default location of temporary snapshot for
.I scanid\fR, 
generated by the
.B \-c
option.
If option
.B \-r
is used, or 
.B \-c
following a schedule request made with 
.B \-s\fR,
then this file is moved to
.B \*[fad_state_prefix]/fadscan/\fIscanid\fB-scheduled\fR
after the report has been generated.
.TP
.B \*[fad_log_prefix]/fadscan/\fIscanid\fB-\fIday\fB.*
Default location of log files.
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.ne 5
.SH EXAMPLES
Supposing 
.B \*[fad_etc_prefix]/fadscan/wholesystem
contains:
.IP
.nf
.fam C
#!/bin/sh
find / \\( \\
           -path /var/tmp -o \\
           -path /tmp     -o \\
           -path /home    -o \\
           -path /proc    -o \\
           -path /sys        \\
       \\) -prune -o -print
.fam T
.fi
.br
.PP
Then the base snapshot would be created by the command:
.IP
.nf
.fam C
.B fadscan -i wholesystem
.fam T
.fi
.PP 
The following entry could be added to root's
.B crontab\fR(5)\fR:
.IP
.nf
.fam C
00 04 * * 1-5 fadscan -c -m root wholesystem
.fam T
.fi
.PP
The daily reports which arrive by mail should be read and analyzed for
any significant changes. 
After reading the most recent report, root could issue the command:
.IP
.nf
.fam C
.B fadscan -s wholesystem
.fam T
.fi
.PP
This will ensure that the next check refreshes the base snapshot. If root 
does not manage to read the report then the command should not be issued.
.ne 5
.SH CAVEATS
.PP 
None.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B fadscan\fR.
.br
.ne 5
.SH SEE ALSO
crontab(5), perlre(1), mkfad(1), faddiff(1), fad(5), cron(8), compress(1),
gzip(1), fadcat(1), fad-config(1), find(1)
.br
.ne 5
.SH AUTHOR
ADE_APP_TOKEN_AUTHOR_NAME <ADE_APP_TOKEN_AUTHOR_EMAIL>
.br
.ne 5
.SH COPYRIGHT & DISTRIBUTION POLICY
Copyright (C) 1995-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
.PP
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.
.PP
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.
.PP
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.