.\"  $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 \-n
|
.B \-\-simulate
]
[
.B \-\-suppress\-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\fB.conf\fR.
.PP
This file may contain blank and hash-led comment lines which are ignored,
and lines of the following format:
.TP 15
.B r \fIpath
This indicates that one of the roots of the fileset is
.I path\fR.
At most, the fileset comprises all files under the specified 
.I path\fR,
and
.I path
itself. 
Multiple r-lines are permitted. Their order is not important.
.TP 
.B e \fIsregexp
This indicates that any pathname matching the special regular expression
.I sregexp
will be excluded from consideration. In this context a special regular
expression is a regular expression conforming to a Perl regular expression
(see
.B perlre\fR(1p))
with the exceptions:
.RS 15
.TP 5
(i)
all regular expressions are automatically prefixed with 
.B ^
.TP
(ii)
all regular expressions are automatically suffixed with 
.B $
.RE
.TP 15
.B i \fIsregexp
This indicates that any pathname matching the special regular expression
.I sregexp
will be re-included for consideration. 
.PP
The order of inclusions and exclusions is important. The inclusion or
exclusion that last matches the currently considered file is the one
that determines whether the file will be included or not.
.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 \-n\fR, \fB\-\-simulate
Simulate everything. 
.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 \-\-suppress\-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\fB.conf
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.conf
contains:
.IP
.nf
.fam C
r /
e /home/.*
e /tmp/.*
e /usr/tmp/.*
e \.*/\.sh_history
e /var/spool/news/.*
i /var/spool/news/control
i /var/spool/news/control/.*
.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 
The current processing of the configuration file means that it is the
.I last
matching inclusion or exclusion that is used. This will probably change
in a future release.
.PP
If while gathering information about the filesystem entries in a fileset 
.B fadscan
encounters a directory which is unreadable, then no information about any
items under the unreadable directory will be recorded. The problem will
be indicated by a message (generated by
.B File::Find\fR(3perl)).
When later comparing the current state of the fileset with its state on
an earlier occassion, the entries under the unreadable directory therefore 
appear to have been deleted. There is not much 
.B fadscan
can do about this.
.PP
Simulation, invoked with the 
.B \-n 
flag does currently work; except that it does not mail the report to
any recipients specified with the 
.B \-m
option.
.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)
.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.