.\" $HeadURL$ $LastChangedRevision$
.\"
.pso ade-config --format=man
.so \*[ade_include_prefix]/ade.man
.pso srf-config --format=man
.TH SRF 1 "ADE_APP_TOKEN_RELEASE_DATE_MAN"
.SH NAME
srf \- System Report Facility
.br
.ne 5
.SH SYNOPSIS
.B srf
\*[ade_standard_synopsis_component]
[
.B \-\-op\-mode=\fImode\fR
]
[
.B \-\-config\-file=\fIfile\fR
]
[
.B \-\-package\-mode=\fImode\fR
]
[
.B \-\-package\-addr=\fIaddr\fR
]
[
.B \-\-apply=\fR{\fBtrue\fR|\fBfalse\fR}
]
[
.B \-\-archive=\fR{\fBtrue\fR|\fBfalse\fR}
]
[
.B \-\-alert=\fR{\fBtrue\fR|\fBfalse\fR}
]
[
.B \-\-archive\-days=\fIdays\fR
]
[
.B \-\-archive\-dir=\fIdir\fR
]
[
.B \-\-log\-file=\fIfile\fR
]
[
.B \-\-alert\-mode=\fImode\fR
]
[
.B \-\-alert\-addr=\fIaddr\fR
]
[
.B \-\-diff\-cmd=\fIcmd\fR
]
[
.B \-\-diff\-opts=\fIopts\fR
]
[
.B \-\-diff\-text=\fItext\fR
]
.br
.ne 5
.SH DESCRIPTION
.B Srf
runs user-specified commands and can archive their output. These commands
are referred to as the \[oq]monitored commands'.
.B Srf
examines the output of the monitored commands and can provide alerts
if they change. 
.PP
.B Srf 
is intended to monitor system changes and thereby aid in system debugging, but 
could also be used to monitor websites, or be put to many other uses.
.PP
.B Srf 
is called twice by the user; once in
.B pack
mode and once
.B unpack\fR, 
with the output of the first call being the input to the second.
Internally, these modes spawn further calls in 
.B sub\-pack
mode and
.B sub\-unpack
mode, respectively.
When called in 
.B unpack
mode, the 
.B srf
process is referred to as the \[oq]unpacker'.
.TP 
.B pack
In pack mode, which is the default,
.B srf
runs monitored commands specified in a configuration file, packs their individual 
outputs into a single stream and dispatches this according to a user-specified method 
(e.g. to standard output or via email to an offsite address).
.TP 
.B sub\-pack
The configuration file, which must be a program (typically a shell script), should not 
call the monitored commands directly, but should call 
.B srf
in 
.B sub\-pack 
mode specifying the monitored command as a parameter; this provides a finer granularity
for archive and alert control. There is no need to explicitly request this mode;
.B srf
will do the right thing when it is called from in the configuration file.
.TP 
.B unpack
In this mode, 
.B srf
reads standard input and unpacks it into the individual monitored commands'
outputs, processes them, generates a report and dispatches this according to
a user-specified method (e.g. via email to a human).
.TP 
.B sub\-unpack
.B Srf 
invoked in 
.B unpack 
mode does not generate the report's components itself,
but spawns slave processes in 
.B sub\-pack 
mode to do this. This is handled internally
and, as such, is of little interest to the user.
.br
.ne 5
.SH CONFIGURATION
See 
.B EXAMPLES
below.
.br
.ne 5
.SH OPTIONS
\*[ade_standard_options_component]
.TP 
.B \-\-op\-mode=\fImode\fR
Set the operating mode to one of 
.B pack\fR,
.B sub\-pack\fR,
.B unpack\fR
or 
.B sub\-unpack\fR.
The default is
.B pack\fR.
.B sub\-pack 
and
.B sub\-unpack
modes are set automatically according to context. Therefore the
only one that the user ever need specify is 
.B unpack\fR.
.TP
.B \-\-config\-file=\fIfile\fR
This option is only valid in
.B pack
mode.
Specify the configuration file to load. 
The default is \*[srf_etc_prefix]/srf.conf.
.TP
.B \-\-diff\-cmd=\fIcmd\fR
This option is only valid in 
.B sub\-pack
mode (i.e. inside the configuration file).
Specify the command that is used to diff previous and current
command outputs when determining if an alert should be send.
The default is 
.B diff\fR(1).
.TP
.B \-\-diff\-opts=\fIopts\fR
This option is only valid in
.B sub\-pack
mode (i.e. inside the configuration file).
Specify the options that are passed to the the diff command
(see the
.B \-\-diff\-cmd
option above). 
The default is that no options are passed.
.TP
.B \-\-diff\-text=\fItext\fR
This option is only valid in
.B sub\-pack
mode (i.e. inside the configuration file).
Instead of comparing the output of the command's current output
with its previous output, compare the command's current output
against
.I text\fR. 
The point of this option is to facilitate repeated reminders of
a difference between expected output and actual output. If 
.I text
is suitably quoted then it may span several lines.
.TP
.B \-\-package\-mode=\fImode\fR
This option is only valid in
.B pack
mode.
Specify the mechanism by which the stream is to be transmitted
to the unpacker. Mode
.B cat
will send the stream to standard output, mode
.B mail
will send the stream via email to the address specified with 
.B \-\-package\-addr
option, mode
.B dir
will immediately archive the stream without dispatching it to
the unpacker. 
The default mode is
.B cat\fR.
.TP
.B \-\-package\-addr=\fIaddr\fR
This option is only valid in
.B pack
mode.
Set the email address to which the stream is sent when the 
stream delivery mode is
.B mail\fR.
The default address is 
.B srf\fR.
.TP
.B \-\-apply=\fR{\fBtrue\fR|\fBfalse\fR}
This option is only valid in 
.B sub\-pack
mode (i.e. inside the configuration file).
Skip execution of a monitored command. This option is intended to
ease conditional execution.
There is no default.
E.g. The following commands in the configuration file would only be executed on 
Solaris systems:
.IP
.nf
.fam C
.B rc2truth()
.B { 
.B \ \ \ \ { eval \[dq]$1\[dq] && echo true; } || echo false
.B }
.B \ 
.B I_AM_SOLARIS=$(rc2truth '[ $(uname) = SunOS ]')
.B \ 
.B srf --id=dfstab --apply=$I_AM_SOLARIS --archive=true \[rs]
.B \ \ \ \ --alert=true \[dq]cat /etc/dfstab\[dq]
.fam T
.fi
.br
.TP
.B \-\-archive=\fR{\fBtrue\fR|\fBfalse\fR}
This option is only valid in 
.B sub\-pack
mode (i.e. inside the configuration file).
Archive the output of the command.
There is no default.
.TP
.B \-\-alert=\fR{\fBtrue\fR|\fBfalse\fR}
This option is only valid in 
.B sub\-pack
mode (i.e. inside the configuration file).
Alert on changes in the output of the command.
There is no default.
.TP
.B \-\-archive\-days=\fIdays\fR
Archive a maximum of 
.I days
days of output from the monitored commands. The default is 180.
.TP
.B \-\-archive\-dir=\fIdir\fR
This option is only valid in 
.B unpack
mode.
Set the directory in which the output from monitored commands will be
archived, if that was requested for this monitored command in the config file.
The default is \*[srf_state_prefix].
.TP
.B \-\-log\-file=\fIfile\fR
This option is only valid in
.B pack
and
.B unpack
modes.
Set the file to which actions will be logged.
.TP
.B \-\-alert\-mode=\fImode\fR
This option is only valid in
.B unpack
mode.
Specify the mechanism by which alerts are to be transmitted
to the user. Mode
.B cat
will send the alert to standard output (this generally makes little sense), mode
.B mail
will send the alert via email to the address specified with
.B \-\-alert\-addr
option, mode
.B file
will save the alert in the user's home directory with a timestamped prefix.
The default mode is
.B cat\fR.
.TP
.B \-\-alert\-addr=\fIaddr\fR
This option is only valid in
.B unpack
mode.
Set the email address to which the alert is sent when the
alert delivery mode is
.B mail\fR.
The default address is
.B root\fR.
.br
.ne 5
.SH EXIT STATUS
On success
.B srf
returns zero. On failure it returns non-zero and displays a diagnostic
message.
.br
.ne 5
.SH FILES
.TP
.B \*[srf_etc_prefix]/srf.conf
This is the default configuration file.
.br
.ne 5
.SH ENVIRONMENT VARIABLES
None.
.br
.ne 5
.SH EXAMPLES
.B Srf 
needs to be called (normally this is done in a cronjob) specifying the name of 
the configuration file and how the resulting stream is to be dispatched to the
unpacker. 
.PP
The following example of how that might be done specifies that the configuration file
is \*[srf_etc_prefix]/system.conf and that the resulting stream is to be dispatched
by email to the user srf@example.com:
.IP
.nf
.fam C
.B 0 0 * * * srf --config-file=\*[srf_etc_prefix]/system.conf --package-mode=mail \[rs]
.B \ \ \ \ --package-addr=srf@example.com
.fam T
.fi
.br
.PP
That configuration file \*[srf_etc_prefix]/system.conf needs to make calls to
.B srf\fR,
each of which specifies the command to run, whether to archive its results,
whether changes should trigger an alert and any special diff options.
.PP
The first example of an entry in such a configuration file below specifies to run 
.B dmesg\fR(1),
to archive its output but not to alert the user to changes in that output;
the second example entry specifies to run
.B wget\fR(1) 
to monitor for new versions of Ekiga on the Debian website, not to archive
the results, but to alert the user if there are any changes; 
the third example entry specifies to run 
.B mkfad\fR(1) 
to monitor root's home and to use 
.B faddiff\fR(1)
to report changes:
.B 
.IP
.nf
.fam C
.B srf --id=dmesg\ \ \ \ --apply=true --archive=true\ \ --alert=false \[dq]dmesg\[dq]
.B srf --id=debekiga --apply=true --archive=false --alert=true\ \ \[dq]w3m \[rs]
.B \ \ \ \ -cols 1000 -no-cookie -dump \[rs]
.B \ \ \ \ http://ftp.de.debian.org/debian/pool/main/e/ekiga/?C=M;O=A\[dq]
.B srf --id=rootfad\ \ --apply=true --archive=true\ \ --alert=true \[rs]
.B \ \ \ \ --diff-cmd=faddiff \[dq]cd /root && find . | mkfad\[dq]
.fam T
.fi
.br
.PP
At the receiving end, 
.B srf
needs to be called to unpack the incoming stream (normally from /etc/aliases 
or ~srf/.forward), specifying where the monitored commands' outputs are to be
archived and to whom to send alerts.
.PP
The following example of an entry in /etc/aliases would archive the
outputs in \*[srf_state_prefix] and send alerts to root:
.IP
.nf
.fam C
.B srf: |\[dq]srf --op-mode=unpack --archive-dir=\*[srf_state_prefix] \[rs]
.B \ \ \ \ --alert-mode=cat | mailx-if-not-empty -s \[rs]\[dq]srf report\[rs]\[dq] root\[dq]
.fam T
.fi
.br
.ne 5
.SH CAVEATS
The list of commands provided in the \*[srf_doc_prefix]/examples/system.conf file is short; users
are invited to submit other commands to the author.
.br
.ne 5
.SH STANDARDS
This manual page documents version ADE_APP_TOKEN_RELEASE_ID of
.B srf\fR.
.br
.ne 5
.SH SEE ALSO
cron(1), diff(1), dmesg(1), faddiff(1), mailx\-if\-not\-empty(1), wget(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) 2009-ADE_APP_TOKEN_RELEASE_YEAR ADE_APP_TOKEN_AUTHOR_NAME
\*[ade_standard_copyright_component]