eels_config(4eels)

eels_config -- configuration file for EELS

Synopsis

/etc/default/eels

Description

The configuration file for the Enhanced Event Logging System (EELS) is /etc/default/eels. It contains multiple Configuration Parameter blocks that describe the configuration of EELS.

Currently, there are nine types of parameter blocks that specify various aspects of the EELS environment. Two of these parameter blocks are themselves referenced by the other blocks in some way. These two parameter blocks are, log-destination and filter; they are used to specify the database and table name and filter criteria respectively. The table below shows which parameter blocks reference log-destination and filter.

log-destination filter

real-time-import Yes Yes

dynamic-import No No

log-destination N/A N/A

filter N/A N/A

accept-remote Yes No

auto-archive Yes No

database-info No No

execute-script No Yes

send-trap No Yes

Each of these configuration blocks are described below:

	log-destination	filter
real-time-import	Yes	Yes
dynamic-import	No	No
log-destination	N/A	N/A
filter	N/A	N/A
accept-remote	Yes	No
auto-archive	Yes	No
database-info	No	No
execute-script	No	Yes
send-trap	No	Yes

real-time-import

The syntax of the real-time-import parameter block is:

   real-time-import tag {
   	syslog sink;
   	audit sink;
   	EELSUser sink;
   	EELSKernel sink;
   	XDAS sink;
   	filter filter_tag;
   }

This parameter block specifies the log sources that can be imported in real-time. Multiple real-time-import parameter blocks are allowed, but each parameter block can only have one type of log import source, that is, syslog, audit, XDAS and so on.

tag

An arbitrary string that uniquely identifies this parameter block.

syslog sink

Import log entries in real-time from syslogd(1M) and messages from cmn_err(D3) into the destination specified by the log-destination parameter block called sink.

audit sink

Import log entries in real-time from the audit subsystem into the destination specified by the log-destination parameter block called sink. For more information on audit, see auditon(1M).

NOTE: Before you can use auditing with EELS you must first configure auditing so that it sends its messages to the EELS driver. You can do this by adding the following line to /etc/default/audit:

AUDIT_DEFPATH=/dev/elsa

EELSUser sink

Import records in real-time from eels_log_import(1Meels) and the EELS generic logging APIs into the destination specified by the log-destination parameter block called sink. For more information on EELS generic logging APIs, see Intro(3eels).

EELSKernel sink

Import records in real-time from the EELS kernel logging APIs into the destination specified by the log-destination parameter block called sink. For more information on EELS kernel logging APIs, see Intro(D3eels).

XDAS sink

Import records in real-time from the XDAS generic and kernel logging APIs into the destination specified by the log-destination parameter block called sink. For more information on these APIs, see Intro(D3xdas) and Intro(3xdas).

filter filter_tag

Specify that the filter called filter_tag is applied to the log source being imported in real-time.

NOTE: You must specify a filter if the log source is syslog. If the log source is audit the filter tag is ignored. Filters are optional for all other log sources.

dynamic-import

The syntax of the dynamic-import parameter block is:

   dynamic-import tag {
   	filename log_file;
   	filter file_name;
   	growth size;
   }

This parameter block specifies when records from an external log file should be automatically imported into an EELS database.

tag

An arbitrary string that uniquely identifies this parameter block.

filename log_file

The filename of the log to monitor.

filter file_name

The name of the script or program that translates the contents of the log file into a format that can be accepted by eels_log_import(1Meels).

NOTE: As well as translating the contents of the log file, the script or program must also call eels_log_import to insert the resulting records into a specified database.

growth size

The size the specified log file is allowed to grow to before records are automatically imported by filter.

Sizes can be specified in bytes, kilobytes or megabytes by appending a ``B'', ``K'' or ``M'' to a numeric value. For example, ``16K''

log-destination

The syntax of the log-destination parameter block is:

   log-destination tag {
   	database database_name;
   	table table_name;
   	hostname remote_host;
   	port remote_port;
   }

This parameter block specifies the destination (also known as a sink) for log messages. If the messages are to be logged locally on the same machine, this block identifies the destination database and table names. If the messages are to be logged on a remote EELS server, this block identifies the remote machine name (or IP address) and the destination TCP port number.

Log messages are directed to a sink by specifying the sink parameter in real-time-import and accept-remote parameter blocks.

The parameters that can be used in this block are:

tag

A string that uniquely identifies this log-destination parameter block. This name is the sink name used in the real-time-import and accept-remote parameter blocks.

database database_name

If the log messages are to be logged locally, use this parameter to specify the name of an existing database into which they can be written.

NOTE: The database must have been created using eels_db_admin(1Meels).

table table_name

If the log messages are to be logged locally, use this parameter to specify the name of an existing database table into which they can be written.

NOTE: The database table must have been created using eels_db_admin(1Meels).

hostname remote_host

If the log messages are to be logged remotely, use this parameter to specify the name of the remote EELS log server. The name can be specified either as an IP address or a fully qualified domain name.

port Remote_port

If the log messages are to be logged remotely, use this parameter to specify the port number the remote EELS server listens on for incoming log messages. This parameter is optional, if you do not use it, the default of ``2020'' is used.

filter

The syntax of the filter parameter block is:

   filter filter_tag {
   	include rule;
   	.
   	.
   	.
   	exclude rule;
   	.
   	.
   	.
   }

This parameter block specifies filtering rules to apply to log messages. It can be referenced by a filter parameter in any of the real-time-import, send-trap or execute-script parameter blocks.

The parameters that can be used in the filter parameter block are:

filter_tag: A string that uniquely identifies this filter parameter block. This name is the filter_tag name used in the real-time-import, send-trap or execute-script parameter blocks.
include rule: Include log messages that match rule. To include all log messages, use the reserved word ``all'' in place of the rule.
exclude rule: Exclude log messages that match rule. To exclude all log messages, use the reserved word ``all'' in place of the rule.

The filter parameter block consists of one or more rules. The individual rules are applied to the log messages one at a time. If a message matches the rules selection criteria, it is dropped if the rule is an ``exclude'' rule, or logged if it is an ``include'' rule. Once a rule is matched, no other rules are used. If a message does not match any of the rules, it is dropped. To include all messages by default, append an ``include all'' rule to the end of the filter specification.

The syntax of a filter rule is shown below:

   include | exclude "field_name operation value '[bool_op field_name operation value]'"

Where:

field_name

The name of the column within the log message on which to apply the rule. Use eels_db_query(1Meels) to list all the columns within the EELS database.

operation

The type of operation to apply to field_name. Possible operations are:

==: Equals
!=: Not equals
~: Contains

value

The value to use in conjunction with the operation in determining the rule.

bool_op

A boolean operator for joining together two or more sets of field_name operation value. Possible operators are:

&&: And
||: Or

For example, to exclude all messages that contain the word ``mount'' in their EventSpecificInformation column, use the following rule:

"exclude EventSpecificInformation ~ 'mount'"

accept-remote

The syntax of the accept-remote parameter block is:

   accept-remote tag {
   	hostname remote_host;
   	destination sink;
   }

This parameter block specifies which client machines are allowed to send their log records to this machine. Multiple accept-remote parameter blocks can be specified.

The parameters that can be used in this parameter block are:

tag: An arbitrary string that uniquely identifies this parameter block.
hostname remote_host: Use this parameter to specify the name of a remote machine that is allowed to send log messages to this host for logging. The name can be specified either as an IP address or a fully qualified domain name.
destination sink: Import records from the remote host into the destination database table specified by the log-destination parameter block identified by sink.

auto-archive

The syntax of the auto-archive parameter block is:

   auto-archive tag(
   	source sink;
   	query SQL_query;
   	filename archive_name;
   	trigger size;
   	frequency time;
   );

This parameter block specifies when records should be automatically archived, and then deleted from the database. The archiving is performed whenever the database reaches a pre-defined size.

tag

An arbitrary string that uniquely identifies this parameter block.

source sink

The name of the sink to use as source for records to archive. The sink name must correspond to a valid log-destination parameter block.

query SQL_query

The SQL query that selects the records from the source database to be archived. A typical example might be:

query "select UniqEventID,LogSystemsSource,EventSpecificInformation from events"

filename archive_name

The name of the file where the archived records are written. A timestamp is appended to the filename so that archive files are not over-written if multiple auto archives are triggered.

Archives can be restored using eels_log_restore(1Meels).

trigger size

The size the source database is allowed to grow to before records are automatically archived to filename.

Sizes can be specified in bytes, kilobytes or megabytes by appending a ``B'', ``K'' or ``M'' to a numeric value. For example, ``20M''

frequency time

How often to check the database size to see if it has exceeded the size specified by trigger.

Times can be specified in hours, minutes or seconds by appending an ``H'', ``M'' or ``S'' to a numeric value. For example, ``4H''.

NOTE: Checking the size of the database requires a database query, so avoid checking the database too frequently. Try initially setting the frequency to something like ``5M''.

database-info

The syntax of the database-info parameter block is:

   database-info tag {
   	database-name dbname;
   	database-start-cmd db_start_command
   	database-log-file db_log_file
   }

This parameter block specifies some system wide defaults for the EELS database environment. Do not change any of these parameter values unless you have very specific reasons for doing so and know exactly what the results of your actions will be.

tag: An arbitrary string that uniquely identifies this parameter block.
database-name dbname: The name of the EELS administrative database. Do not use this database to store your own records. Instead, create your own database using eels_db_admin(1Meels).
database-start-cmd db_start_command: The command used to start the EELS database.
database-log-file db_log_file: The destination log file to which the output from STDOUT and STDERR is directed from database-start-cmd.

send-trap

The syntax of the send-trap parameter block is:

   send-trap tag {
   	count num;
   	interval num;
   	trap-type trap_type_name;
   	community community_name;
   	hostname host_address;
   	filter filter_tag;
   }

This parameter block uses the EELS filter system (as described in the filter parameter block). Incoming log messages are filtered and on a filter match, one or more SNMP traps are sent to the specified host.

tag: An arbitrary string that uniquely identifies this parameter block.
count num: The number of SNMP traps to send. If count is not specified in the parameter block, a default of 1 is assumed.
interval num: The time in seconds to pause between sending SNMP traps. If interval is not specified in this parameter block, a default of 3 is assumed.
trap-type trap_type_name: The type of SNMP trap to be sent. This parameter is specified in the same way as the trap_type option of trap_send(1Msnmp).
community community_name: The SNMP community name. This parameter is specified in the same way as the community_string option of the trap_send command.
hostname host_address: The name of the host that will receive the SNMP trap. This parameter is specified in the same way as the entity_addr option of the trap_send command.
filter filter_tag: This name of the filter parameter block that will filter the log messages as they pass through. Any matches that are detected by the filter mechanism will trigger the sending of SNMP traps as defined by the other parameters in this block.

NOTE: If EELS is still busy sending a trap when the same event occurs again, EELS will not send a trap for that second event.

For information on SNMP, see ``Traps'' in Configuring and administering SNMP.

execute-script

The syntax of the execute-script parameter block is:

   execute-script tag {
   	script script_name;
   	user user_name;
   	filter value;
   }

This parameter block uses the EELS filter system (as described in the filter parameter block). Incoming log messages are filtered and on a filter match a specified command or script is executed.

tag: An arbitrary string that uniquely identifies this parameter block.
script script_name: The script to execute when a match is detected by the filter parameter block filter.
user user_name: The username that the script should be executed as. Currently all scripts are run as root. To run a script as any other user, use su(1M).
filter value: This name of the filter parameter block that will filter the log messages as they pass through. Any matches that are detected by the filter mechanism will trigger the execution of the script or command named in script.

Examples

An example of a /etc/default/eels file is shown below:

   real-time-import syslog {
   	syslog  syslog_sink;
   	filter  syslog_filter;
   }
   
   filter syslog_filter {
   	exclude "LogSystemsSource == 'in.telnetd'";
   	include all;
   }
   

   log-destination syslog_sink {
   	database defaultdb;
   	table    events;
   }
   

   real-time-import audit {
   	audit  audit_sink;
   }
   

   log-destination audit_sink {
   	database auditdb;
   	table    events;
   }
   

   real-time-import eels_user {
           EELSUser  httpd-80_sink;
           filter  http_filter;
   }
   

   dynamic-import errors_log {
            filename /usr/ns-home/httpd-80/logs/errors;
            filter /etc/eels/bin/process_errors_file;
            growth 20B;
   }
   

   filter http_filter {
           exclude "EventSpecificInformation ~ 'successful server startup'";
           include all;
   }
   

   log-destination httpd-80_sink {
           database httpd_db;
           table    events;
   }
   

   

   database-info dbinfo {
   	database-name EELS_Admin;
   	database-start-cmd /etc/eels/mysql/bin/safe_mysqld;
   	database-log-file  /etc/eels/logs/mysql.log;
   }

References

auditon(1M), cmn_err(D3), eels_db_admin(1Meels), eels_db_query(1Meels), eels_log_import(1Meels), eels_log_restore(1Meels), Intro(1Meels), Intro(D3eels), Intro(D3xdas), Intro(3eels), Intro(3xdas), su(1M), syslogd(1M), trap_send(1Msnmp)