.\"	$CoreSDI: auditd.8,v 1.16 2001/12/12 20:23:16 claudio Exp $
.\"
.\"   Copyright (c) 2000, 2001, Core SDI S.A., Argentina
.\"   All rights reserved
.\"  
.\"   Redistribution and use in source and binary forms, with or without
.\"   modification, are permitted provided that the following conditions
.\"   are met:
.\"  
.\"   1. Redistributions of source code must retain the above copyright
.\"      notice, this list of conditions and the following disclaimer.
.\"   2. Redistributions in binary form must reproduce the above copyright
.\"      notice, this list of conditions and the following disclaimer in the
.\"      documentation and/or other materials provided with the distribution.
.\"   3. Neither name of the Core SDI S.A. nor the names of its contributors
.\"      may be used to endorse or promote products derived from this software
.\"      without specific prior written permission.
.\"  
.\"   THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
.\"   IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
.\"   OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
.\"   IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
.\"   INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\"   NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
.\"   DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
.\"   THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\"   (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\"   THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"

.Dd Oct 3, 2001
.Dt AUDITD 8 SMM
.Os CoreSDI
.Sh NAME
.Nm Auditd
.Nd
Remote system logs auditing daemon
.Sh SYNOPSIS
.Nm auditd
.Op Fl f Ar file
.Op Fl M Ar path
.Oo Fl p
.Sm off
.Oo Ar address No : Oc
.Ar port
.Sm on
.Oc
.Op Fl t Ar seconds
.Op Fl T Ar seconds
.Op Fl l
.Op Fl d
.Op Fl v
.Op Fl q
.Op Fl h
.Sh DESCRIPTION
.Nm Auditd
daemon and
.Xr audit 1
programs allow together remote system logs auditing.
.Nm
server runs usually on audited hosts and listens on a specified
port waiting for an
.Xr audit 1
client connection that runs, usually, on the auditor workstation. The
options are as follows:
.Bl -tag -width Ds
.It Fl f Ar file
Specifies the configuration file; the default is
.Pa /usr/local/etc/auditd.conf
(see
.Sx CONFIGURATION FILE FORMAT
section below).
.It Fl M Ar path
Specifies the modules pathname; the default is
.Pa /usr/local/lib/alat
(see
.Xr audit 1
for more information about modules).
.It Fl p Ar [address:]port
Specifies the listening address and port; the default address is 0.0.0.0
(all addresses) and port 9015.
.It Fl t Ar sec
Specifies the login timeout: once the connection is established the
authentication process can't exceed
.Ar sec
seconds, otherwise the connection is closed;
the default is 10 seconds. A value of 0 disables this feature.
.It Fl T Ar sec
Specifies the command timeout: once a connection is established and an
auditor is logged in, he has
.Ar sec
seconds to enter a command, otherwise the connection is closed;
the default is 120 seconds. A value of 0 disables this feature.
.It Fl l
Log each auditor session (commands and status).
.It Fl d
Log debug information.
.It Fl v
Verbose mode: it doesn't become a daemon and logs messages on standard
output instead of
.Xr syslog 3 .
It exits after one session.
.It Fl q
Quiet mode.
.It Fl h
Prints a help on standard error and exits.
.El
.Pp
.Nm Auditd
reads its configuration file when starts up and whenever it
receives a hangup (HUP) signal. The configuration values are set
in the following order:
.Bl -enum -offset indent
.It
Default values
.It
Configuration file values
.It
Command line values
.El
.Pp
.Nm Auditd
creates the file
.Pa /var/run/auditd.pid
and stores its process id there. This can be used to terminate or reconfigure
.Nm auditd .
.Sh CONFIGURATION FILE FORMAT
The
.Nm auditd 
configuration file format consists of two column lines; the former
specifies the option name and the other it's value. A line that
begins with a ``#'' character is considered comment line and is
not parsed. Options names are as follows:
.Bl -tag -width Ds
.It ListenAddress
Specifies the listening address; the default is 0.0.0.0 (all addresses).
.It Port
Specifies the listening port; the default is 9015.
.It Timeout
Specifies the login timeout in seconds; the default is 10.
.It CommandTimeout
Specifies the command timeout in seconds; the default is 120.
.It ModulesPath
Specifies the modules (authentication, information accessing, and resources)
path; the default is
.Pa /usr/local/lib/alat .
.It LogSession
Specifies whether
.Xr auditd 8
should log each
.Xr audit 1
session commmands; the default is ``no''.
.It LogDebugInfo
Specifies whether
.Xr auditd 8
should log debugging information; the default is ``no''.
.It QuietMode
Does not print any messages (disables
.Va LogDebugInfo
and
.Va LogSession
options); the default is ``no''.
.It SyslogFacility
Specifies syslog facility to log
.Xr auditd 8
messages via
.Xr syslog 3 ;
allowed values are: AUTH, AUTHPRIV, DAEMON, USER; the default is DAEMON.
The syslog level depends on the message type: LOG_ERROR for fatal and error
messages, LOG_DEBUG for debugging, LOG_WARNING for warnings, and LOG_INFO
for session messages.
.It AuthModule
Allow auditors to use the specified authentication module (more than
one method can be used by adding multiple
.Va AuthModule
lines); see
.Xr audit 1
manual page for more information about AUTHENTICATION MODULES.
.It IaModule
Allow auditors to use the specified Information Accessing module (more
than one module can be used by adding in multiple
.Va IaModule
lines); see
.Sr audit 1
manual page for more information about INFORMATION ACCESSING MODULES.
.It ResModule
Specify de resources module used to hold
.Xr auditd 8
internal data (auditor permissions, download status, etc.);
the default is ``local''. See
.Sx RESOURCES MODULES
section below and
.Xr audit 1
man page for more information about RESOURCES.
.Sh RESOURCES MODULES
.Nm
stores internal and auditors data on a resource database;
the resource module saves all data on a storage that
is independent from
.Nm auditd ,
that means, the place where the resources are located depends only
on the resources module used.
.Ss LOCAL RESOURCES MODULE
This module stores resources on text files located under the
.Pa /var/audit/resources
directory, each file contains the resources for a given auditor. If
auditor manager is logged into the audited host, he is allowed to
create, remove, and change auditors and their resources by hand using
a text editor instead of being using the
.Fl r
.Xr audit 1
option.
.Ss LOCAL RESOURCES MODULE FILE FORMAT
Since resources may contain binary data, all characters whose code belongs
to the 0x00-0x1F or 0x7F-0xFF ranges (non-printable characters) must be
coded as ``\enn'', where ``nn'' is the character code expressed as
two digit hexadecimal number (ie. the 0x07 character must be specified
as ``\e07'' instead of ``\e7''); codes between 0x20 and 0x7E can be
specified both, as printable
.Xr ascii 7
characters or like the formers.
.Pp
The beginning of a resource is indicated by an ``['' (opening bracket),
then follows the resource name (can't contain zero codes) and finally,
a ``]'' (closing bracket). The general schema is as follows:
.Bd -literal -offset indent
[ resource_name_a ]
	resource_a contents

[ resource_name_b ]
	resrouce b contents
.Li .
.Li .
.Ed
.Pp
New lines and blank spaces don't affect the resource contents, except
they are specified as ``\enn'':
.Bd -literal -offset indent
[ my resource ]
	Hi. How are you?

[ pepe ]

[ another_resource ]
.Ed
.Pp
The above text declares three resources whose names are: ``my resource'',
``pepe'', and ``another_resource''.
If we want the text ``[ pepe ]'' belongs to the ``my resource'' contents,
the bracket ``['' character must be escaped with ``\e['':
.Bd -literal -offset indent
[ my resource ]
	Hi. How are you?

\e[ pepe ]

[ another_resource]
.Ed
.Pp
or formatted like this:
.Bd -literal -offset indent
[ my resource ]
	Hi. How are you?
	\e[ pepe ]

[ another_resource]
.Ed
.Pp
With the above, the contents of ``my resource'' will be
``Hi. How are you?[ pepe ]''. As mentioned earlier if we want a
new line character between ``..you?'' and ``[ pepe ]'' it must be
escaped:
.Bd -literal -offset indent
[ my resource ]
	Hi. How are you?\en
	\e[ pepe ]
.Ed
.Pp
Or:
.Bd -literal -offset indent
[ my resource ]
	Hi. How are you?
	\en\e[ pepe ]
.Ed
.Pp
Or:
.Bd -literal -offset indent
[ my resource ]
	Hi. How are you?\en\e[ pepe ]
.Ed
.Pp
With the above examples the contents will be:
.Bd -literal -offset indent
	"Hi. How are you?
	[ pepe ]"
.Ed
.Pp
The escabale characters are:
.Bl -bullet
.It
Newline:
``\en'' or ``\e0A''
.It
Blank space:
``\e20''
.It
Tabulator:
``\et'' or ``\e09''
.It
Opening bracket:
``\e[''
.It
Inverted slash:
``\e\e''
.El
.Pp
Blank spaces between the ``['' and ``]'' delimiters on the
resource name declaration don't have effect on the resource name itself,
except escaping:
.Bd -literal -offset indent
	[ Offset ! ! ]
	[Offset! !]
.Ed
.Pp
Here the name is ``Offset ! !'' in both cases; if we want the
resource name as ``Offset ! ! '', with an ending white space, it must
be escaped as follows:
.Bd -literal -offset indent
	[ Offset ! !\e20 ]
.Ed
.Pp
LOCAL RESOURCES MODULE file supports INCLUDE FILES: one file is
allowed to include other files, the specification is as follows:
.Bd -literal -offset indent
	[ include filename ]
.Ed
.Pp
The ``filename'' specified above should be a valid resources file
and it may contain other include statments. The reference to the
include doen't get lost after loading the resources on the included
file, so, if two users share a file (with common permissions) and
one user modify the contents of a resource previously loaded from
that file then, the value of that resource will be changed for the
other user the next time he logs in. If both users change a resource
that belongs to the common file, both will be using their own values
until the session in finished; after that the value saved on the
file will be the value of the last session.
.Sh EXAMPLES
Example of a configuration file:
.Bd -literal -offset indent
# my auditd configuration file
ListenAddress	192.168.68.100
Port           32768
ModulesPath    /lib/auditd
AuthModule     raw
AuthModule     srp
IaModule       syslog
IaModule       my_own_ia_module
ResModule      my_own_resources_module
.Ed
.Pp
If a given manager wants an auditor on a host and the auditd 
server uses the
.Sx LOCAL RESOURCES MODULE
and he has access to that host, he can create the auditor and his
permissions by creating a file under
.Pa /var/audit/resources ;
the name of this file is the auditor's login name:
.Bd -literal -offset indent
[ IAPerms ]
	IGZ

[ IAPerms_/var/log/messages ]
	GR

[ IAPerms_/var/log/authlog ]
	L

[ ResPerm_SRPPass ]
	F

[ ResAdmin ]
	juan\encarlos\en
.Ed
.Pp
With the avobe the new auditor has the following capabilities:
.Bl -bullet
.It
He has permissions to ``list'' (know the existence of) the
.Pa /var/log/authlog
logfile.
.It
He has permissions to ``list'', ``get'' (download information and logs),
and ``rotate'' the
.Pa /var/log/messages
logfile.
.It
He has permissions to ``list'', ``info'' (download information), ``get'',
and ``zap'' (truncate) all other logfiles.
.It
He can examine the content of ``SRPPass'' resource but can't change its
value (can't change his own SRP password).
.It
He is the chief of both ``juan'' and ``carlos'' (can change their
resources).
.Sh SEE ALSO
.Xr audit 1 ,
.Xr kill 1 ,
.Xr syslog 3 .
.Sh BUGS
.Bl -bullet
.It
To avoid race conditions accessing logfiles,
.Nm auditd
accepts only one connection at a time; this will be fixed in a future
release.
.It
If you found bugs, please report them to audit-bugs@core-sdi.com
.El