.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 .\" .\" Standard preamble: .\" ======================================================================== .de Sh \" Subsection heading .br .if t .Sp .ne 5 .PP \fB\\$1\fR .PP .. .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. | will give a .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' .\" expand to `' in nroff, nothing in troff, for use with C<>. .tr \(*W-|\(bv\*(Tr .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .\" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .hy 0 .if n .na .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "LOG_ANALYSIS 1" .TH LOG_ANALYSIS 1 "2008-01-13" "perl v5.8.8" "User Contributed Perl Documentation" .SH "NAME" log_analysis \- Analyze various system logs .SH "SYNOPSIS" .IX Header "SYNOPSIS" \&\fBlog_analysis\fR [\fB\-h\fR] [\fB\-r\fR] [\fB\-g\fR] [\fB\-f\fR config_file] [\fB\-o\fR file] [\fB\-O\fR] [\fB\-n\fR nodename] [\fB\-U\fR] [\fB\-u\fR unknownsdir] [\fB\-D\fR var1,var2=value,...] [\fB\-d\fR days_ago] [\fB\-a\fR] [\fB\-F\fR] [\fB\-i\fR] [\fB\-m\fR mail_address] [\fB\-M\fR mail_prog] [\fB\-s\fR] [\fB\-S\fR] [\fB\-t\fR forced_type] [required_files. . .] \&\fBlog_analysis\fR \fB\-I info_type\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIlog_analysis\fR analyzes and summarizes system logs files. It also runs some other commands (ie. \fIw\fR, \fIdf \-k\fR) to show the system state. It's intended to be run on a daily basis out of cron. .PP \&\fIlog_analysis\fR supports several major modes. The default mode is report mode, which scans through your logs, produces a text report, and exits. There is also real mode, which lets you monitor your logs continuously; gui mode, which is a gui sitting on top of real mode; and daemon mode, which is a daemonized variant of real mode. .SH "OPTIONS" .IX Header "OPTIONS" .IP "\fB\-a\fR all" 4 .IX Item "-a all" Show all logs, not just the ones from yesterday. .IP "\fB\-A\fR daemon mode" 4 .IX Item "-A daemon mode" Start in daemon mode. Daemon mode is like real mode, except that the process daemonizes, and there is no regular output, just actions. daemon mode is useful if you want to start \fIlog_analysis\fR at system boot time to run actions. It's also useful if you have actions configured, and you have multiple copies of log_analysis running in real/gui mode, and you only want the actions to happen once. .Sp See \fI\-r\fR for more info on real mode. In general, anything that applies to real mode applies to daemon mode unless it explicitly says otherwise. .Sp The variables specific to daemon mode are \&\fIdaemon_mode\fR and \fIdaemon_mode_pid_file\fR. One variable that is not specific to daemon mode but is really useful with daemon mode is \&\fIreal_mode_no_actions_unless_is_daemon\fR. .IP "\fB\-b\fR real mode backlogs" 4 .IX Item "-b real mode backlogs" By default, real mode and gui mode ignore all existing log messages and only show new logs. With this option, real mode shows logs as indicated by \fIdays_ago\fR. See \fI\-r\fR for more info. .IP "\fB\-d days_ago\fR" 4 .IX Item "-d days_ago" Show logs from \fIdays_ago\fR days ago. Defaults to 1 (ie. show yesterday's logs.) In \fI\-a\fR mode, this option only affects the heading, and it defaults to 0. .Sp You can also provide an absolute date in the form \s-1YYYY_MM_DD\s0, ie. 2001_03_02. And you can provide the symbolic names \fItoday\fR (equivalent to 0) and \fIyesterday\fR (equivalent to 1). .Sp And you can even provide a date range in the form \s-1YYYY_MM_DD\-YYYY_MM_DD\s0 or ago1\-ago2 to get output for a range of days. Each day is output individually, so if you use the \fI\-o\fR option, you get a separate file for each day, and if you use the \fI\-m\fR option, you get a separate mail for each day. .Sp You can also set this in the config with the \fIdays_ago\fR variable. .Sp See \fI\-r\fR for how days_ago is handled under real mode and gui mode. .IP "\fB\-D var1,var2=value,var3,...\fR" 4 .IX Item "-D var1,var2=value,var3,..." This option lets you define preprocessor constants. Its argument is a comma-separated list of constants to define. To set a constant to a particular value, say \*(L"constant=value\*(R". .IP "\fB\-f config_file\fR" 4 .IX Item "-f config_file" Read \fIconfig_file\fR in addition to the internal config and the internal config files. See \*(L"\s-1CONFIG\s0 \s-1FILE\s0\*(R" for details. .IP "\fB\-F\fR" 4 .IX Item "-F" Instead of loading the whole internal config, just use a minimal subset. .IP "\fB\-g\fR" 4 .IX Item "-g" \&\*(L"gui mode\*(R", ie. monitor log files continuously. Currently conflicts with many other modes and options. Yes, has built-in support for log file rollover. This is basically real mode (see \fI\-r\fR) with a \s-1GUI\s0; variables that apply to real mode also apply to gui mode, but not vice versa. .Sp See variables \&\fIgui_mode\fR, \fIgui_mode_modifier\fR, and \fIwindow_command\fR for gui mode specifics. See \fB\-r\fR for many things that also apply to gui mode. .IP "\fB\-h\fR help" 4 .IX Item "-h help" Show command summary and exit. .IP "\fB\-i\fR includes suppress" 4 .IX Item "-i includes suppress" Don't include the standard include files, ie. /etc/log_analysis.conf, /etc/log_analysis.conf, and the others listed in \*(L"\s-1FILES\s0\*(R". Note that this option does not stop the inclusion of \&\f(CW$HOME\fR/.log_analysis.conf in gui mode. .IP "\fB\-I info\fR" 4 .IX Item "-I info" This option is used for obtaining internal information about \fIlog_analysis\fR. \&\fIlog_analysis\fR exits immediately after outputting the information. .Sp If \fIinfo\fR is \fIhelp\fR, \fIlog_analysis\fR outputs the list of things you can use for \fIinfo\fR. .Sp If \fIinfo\fR is \fIcategories\fR, all categories (those mentioned in the various configs and implicit categories) will be listed. .Sp If \fIinfo\fR is \fIcolors\fR, all colors that work for real_mode and gui_mode will be listed. .Sp If \fIinfo\fR is \fIconfig_versions\fR, all config files will be listed with their config_version and file_version (if defined). .Sp If \fIinfo\fR is \fIevals\fR, the evals built from the config (internal and local) are output. .Sp If \fIinfo\fR is \fIinternal_config\fR, the internal config is output. .Sp If \fIinfo\fR is \fIlog_files\fR, the log files that would have been read are output. .Sp If \fIinfo\fR is \fIlog_types\fR, the known log types are output. .Sp If \fIinfo\fR is \fInothing\fR, \fIlog_analysis\fR just exits. Useful for testing configs. .Sp If \fIinfo\fR is \fIpats\fR, the known subpatterns will be listed. .Sp If \fIinfo\fR is \fIpatterns\fR, the various patterns defined for the log types are output. .IP "\fB\-m mail_address\fR" 4 .IX Item "-m mail_address" Mail output to \fImail_address\fR. This can also be specified in the config; see \fBmail_address\fR in \*(L"\s-1VARIABLES\s0\*(R". .IP "\fB\-M mail_command\fR" 4 .IX Item "-M mail_command" Use \fImail_command\fR to send the mail. This can also be specified in the config; see \fBmail_command\fR in \*(L"\s-1VARIABLES\s0\*(R" for more info, including the default. .IP "\fB\-n nodename\fR" 4 .IX Item "-n nodename" Use \fInodename\fR as the nodename (\s-1AKA\s0 hostname) instead of the default. This is more than just cosmetic: entries in syslogged files will be processed differently if they didn't come from this nodename. This can also be specified in the config file; see \fBnodename\fR in \*(L"\s-1VARIABLES\s0\*(R". .IP "\fB\-N\fR process all nodenames" 4 .IX Item "-N process all nodenames" If the logs contain entries for nodes other than \fInodename\fR, (ie. if the host is a syslog server), analyze them anyway. .IP "\fB\-o file\fR" 4 .IX Item "-o file" Output to \fIfile\fR instead of to standard output. Works with \fI\-m\fR, so you can save to a file and send mail with one command. .IP "\fB\-O\fR" 4 .IX Item "-O" With \fI\-o file\fR, causes the output to go both to the file and to standard output. \s-1NB:\s0 this does not currently work with \fI\-m\fR, so you can't output to a file, standard output, and to email. .IP "\fB\-p pgp_type\fR" 4 .IX Item "-p pgp_type" Encrypts the mail output. Uses pgp_type to determine the encryption command. For use with \fB\-m\fR or \fBmail_address\fR. See \fBpgp_type\fR in the list of global variables for info on encryption types. .IP "\fB\-r\fR" 4 .IX Item "-r" \&\*(L"Real mode\*(R", ie. monitor log files continuously. Currently conflicts with many other modes and options. Yes, has built-in support for log file rollover. See \fI\-g\fR for a \s-1GUI\s0 that can sit on top of this mode, and \fI\-A\fR to run real mode as a daemon. .Sp See variables \&\fIreal_mode\fR, \fIreal_mode_output_format\fR, \&\fIreal_mode_sleep_interval\fR, \&\fIreal_mode_check_interval\fR, \&\fIreal_mode_backlogs\fR (or the \fI\-b\fR option), and \&\fIkeep_all_raw_logs\fR in the list of global variables for more configurables. .Sp \&\fI\s-1WARNING:\s0\fR in real mode and gui mode, only the most recent file per glob in \fIoptional_log_files\fR is monitored. This means that you should set it to something like \fI/var/log/messages*\fR and \fI/var/log/syslog*\fR rather than \fI/var/log/*\fR. .Sp \&\fI\s-1WARNING:\s0\fR in real mode and in gui mode, \fIlog_analysis\fR treats \&\fIdays_ago\fR differently; if it's a simple number, it is treated as the number of days ago to start looking at logs. So, if days_ago is 7, \&\fIlog_analysis\fR looks through the past 7 days' worth of logs. \&\s-1HOWEVER\s0, even if \fB\-d\fR is set, \fIlog_analysis\fR doesn't actually show these logs unless \fI\-b\fR is specified or the corresponding variable real_mode_backlogs is set. .Sp \&\fI\s-1NOTE:\s0\fR The primary feature of \fIlog_analysis\fR is its reporting capability. Using it for continuous monitoring makes sense if you want a single config for reporting and for continuous monitoring. If you just want continuous monitoring then you may be better off with some of the other software out there, such as \fIswatch\fR\|(1). .IP "\fB\-s\fR suppress other commands" 4 .IX Item "-s suppress other commands" Usually, \fIlog_analysis\fR runs assorted commands that show system state (ie. \fIw\fR, \fIdf \-k\fR). This option doesn't run those commands. See \fBcommands_to_run\fR in \*(L"\s-1VARIABLES\s0\*(R" for the list of extra commands. The \fBsuppress_commands\fR variable does the same thing as this option. .IP "\fB\-S\fR suppress output footer" 4 .IX Item "-S suppress output footer" Usually, \fIlog_analysis\fR will include its version number, the time it spent running, and its arguments at the end of the output. This option suppresses that output. The \fBsuppress_footer\fR variable does the same thing as this option. .IP "\fB\-t forced_type\fR" 4 .IX Item "-t forced_type" \&\fIlog_analysis\fR usually determines the type of logfiles by looking at the per-type \fIlog_filenames\fR extension. This option and the \fItype_force\fR variable let you bypass that check. .IP "\fB\-U\fR unknowns-only" 4 .IX Item "-U unknowns-only" Output logfile unknowns to stdout and exit. If \fIunknownsdir\fR exists, also wipe \fIunknownsdir\fR if it exists and then write out raw unknown lines to files in \fIunknownsdir\fR. This exists to make writing custom rules easier. .IP "\fB\-u unknownsdir\fR" 4 .IX Item "-u unknownsdir" Use \fIunknownsdir\fR as the unknownsdir. If \fIunknownsdir\fR already exists, and contains files, its files will be used as the input for \fIlog_analysis\fR regardless of any other command line options. If \fI\-U\fR is also specified, after all processing \fIunknownsdir\fR will be wiped out and its files rewritten with the current unknowns. This is useful for writing your own configs. .IP "\fB\-v\fR version" 4 .IX Item "-v version" Output version and exit. .IP "\fBrequired-files\fR" 4 .IX Item "required-files" If files are specified on the command line, log_analysis ignores its built-in list of optional and required log files, and process the files on the command line. If one of the files doesn't exist, it's a fatal error. .SH "CONFIG FILE" .IX Header "CONFIG FILE" The script has an embedded config file. It will also read various external config files if they exist; see \*(L"\s-1FILES\s0\*(R" for a list. Later directives (from later in the file or from a file read later) override earlier directives. .PP You can make comments with '#' at the beginning of a line. If you want a '#' or '=' at the beginning of a line, you usually need to quote it with backslash. .PP Some directives take a \*(L"block\*(R" as argument. A block is a collection of lines that ends with a line that is empty or only contains whitespace. '#' at the beginning of a line still comments out the line. Leading whitespace on a line is ignored. .PP Before the config is parsed, it is passed through a preprocessor inspired by the \fIaide\fR\|(1) preprocessor. .Sh "Pattern directives" .IX Subsection "Pattern directives" .RS 4 These directives describe your logs, and are the main point of this program. The basic idea here is that you first declare what logtype you are working with, and then you specify a bunch of perl patterns that describe different kinds of log messages, and that save parts of the message. For each perl pattern, you specify one or more destinations that describe what you want done with it. .RE .IP "\fBlogtype:\fR \fItype\fR" 4 .IX Item "logtype: type" Future patterns should be applied to this logtype (ie. sulog, syslog, wtmp.) Example: .Sp \&\fIlogtype: syslog\fR .IP "\fBpattern:\fR \fIpattern\fR" 4 .IX Item "pattern: pattern" \&\fIpattern\fR is a perl regex (see \fIperlre\fR\|(1)) that implictly starts with ^ (beginning of the line) and implicitly ends with \es*$ (optional whitespace and the end of the line.) This should only be issued after a \fBlogtype:\fR has been issued in the same config file. Wildcard parts of the pattern should be surrounded with parentheses, to save these parts for later use in the \fBformat:\fR. Note that there are some tokens with special meanings that can be used here in the format \f(CW$pat\fR{something}, ie. \f(CW$pat\fR{ip}, \f(CW$pat\fR{file}, etc. (see \*(L"pat\*(R" for details, and run \fIlog_analysis \-I pats\fR for the current list). Examples: .Sp \&\fIpattern: popper: Stats: ($pat{mail_user}) (\ed+) (\ed+) (\ed+) (\ed+)\fR .Sp \&\fIpattern: login: \s-1LOGIN\s0 \s-1ON\s0 ($pat{file}) \s-1BY\s0 ($pat{user})\fR .Sp The order of precedence for patterns is undefined, except that user-defined patterns always have precedence over the patterns of the internal config. .IP "\fBformat:\fR \fIformat\fR" 4 .IX Item "format: format" \&\fIformat\fR is treated as a string that contains the useful information from a pattern. Note that it should not actually be quoted. A format is mandatory for category destinations, but should not be used with \&\s-1SKIP\s0 or \s-1LAST\s0 destinations. .Sp For example, if we had a pattern that was \fIlogin: \s-1LOGIN\s0 \s-1ON\s0 ($pat{file}) \s-1BY\s0 ($pat{user})\fR, we would probably just want \f(CW$2\fR, so we might say: .Sp \&\fIformat: \f(CI$2\fI\fR .Sp Similarly, if we had a patterns that was \fIkernel: deny (\ed+) packets from ($pat{ip}) to ($pat{ip})\fR, we might want to say: .Sp \&\fIformat: \f(CI$2\fI => \f(CI$3\fI\fR .IP "\fBuse_sprintf\fR" 4 .IX Item "use_sprintf" \&\fIuse_sprintf\fR is optional. If this directive is present for a given format, than instead of the format being treated as a string, it is treated as the arguments for \fIsprintf\fR\|(3). For example, if you have a source \s-1IP\s0 address in \f(CW$2\fR and a destination \s-1IP\s0 address in \f(CW$3\fR, you could just have dest as \fI$2 => \f(CI$3\fI\fR, but you would have things lining up better if you did this: .Sp \&\fIformat: "%\-15s => \f(CI$3\fI", \f(CI$2\fI\fR .Sp \&\fIuse_sprintf\fR .IP "\fBdelete_if_unique\fR" 4 .IX Item "delete_if_unique" \&\fIdelete_if_unique\fR is optional. This feature can be used when you have multiple \fIdest\fRs for one pattern, one of which is a regular category and one of which is a \&\fI\s-1UNIQUE\s0\fR with a filter. You want the one that is a regular category to be deleted if the \fI\s-1UNIQUE\s0\fR category meets its filter, ie. because it's a scan. See \*(L"\s-1UNIQUE\s0 \s-1DESTINATION\s0\*(R" for more info. .IP "\fBcount:\fR \fIcount\fR" 4 .IX Item "count: count" \&\fIcount\fR is optional. The default is that a log line that matches a pattern causes the category to increment by 1. But sometimes, a single log line corresponds to multiple events, ie. if you have a log message of the form \*(L"5 packets denied by firewall\*(R" or \*(L"last message repeated 3 times\*(R", you can extract the event count to \fIcount\fR. For example, if you're using the pattern \fIkernel: deny (\ed+) packets from ($pat{ip}) to ($pat{ip})\fR, you might say: .Sp \&\fIcount: \f(CI$1\fI\fR .IP "\fBcolor:\fR \fIcolors\fR" 4 .IX Item "color: colors" space-separated list of colors to display this message in when in real-mode or gui\-mode. For a list of colors that will work in both modes, run \fIlog_analysis \-I colors\fR. Note that \*(L"bell\*(R" is among the available colors, because it didn't fit anywhere else. See the \&\fIcolors\fR entry for more info. .Sp \&\s-1NOTE:\s0 if multiple dest configs with conflicting color settings result in delivery to the same line in gui mode, the result is currently undefined. There is only one line to be displayed, after all. .IP "\fBdescription:\fR \fIdescription_text\fR" 4 .IX Item "description: description_text" This is a simple text description of the event, to explain the problem to your operators. It can be accessed via gui mode. The note above by color applies. .IP "\fBdo_action:\fR \fIaction\fR" 4 .IX Item "do_action: action" Run \*(L"action\*(R" (described elsewhere in the config with the \*(L"action:\*(R" keyword) if this event is seen in real mode or gui mode. .IP "\fBpriority:\fR \fIpriority\fR" 4 .IX Item "priority: priority" Assign priority \fIpriority\fR to action. Currently, the only priority that does anything is \*(L"\s-1IGNORE\s0\*(R". It can be used to ignore events. .IP "\fBdest:\fR \fIdest\fR" 4 .IX Item "dest: dest" This describes what you want done with the data in a pattern. If \&\fIdest\fR is the special token \fI\s-1SKIP\s0\fR the data is discarded. If \&\fIdest\fR is the special token \fI\s-1LAST\s0\fR, the data is assumed to be of the form \*(L"last message repeated N times\*(R", and we pretend as though the last message we saw occurred, using \fIcount\fR as a multiplier. If \fIdest\fR starts with the special token \fI\s-1UNIQUE\s0\fR, we do special \*(L"unique\*(R" handling, which is covered in \*(L"\s-1UNIQUE\s0 \s-1DESTINATION\s0\*(R". If \fIdest\fR starts with the special token \fI\s-1CATEGORY\s0\fR or is any other string, it is treated as a category that the pattern data should be saved to. Ie. if \fIpattern\fR was \fIlogin: \s-1LOGIN\s0 \&\s-1ON\s0 ($pat{file}) \s-1BY\s0 ($pat{user})\fR, and \fIformat\fR was \fI$2\fR, then one might set \fIdest\fR to \fIlogin: successful local login\fR. You must have a format defined before the \fIdest\fR. .Sp You can have multiple \fIdest\fR directives for a single \fIpattern\fR, if all of the \fIdest\fRs are category destinations. Each one needs its own \&\fIformat\fR. Similarly, if you set \fIcount\fR or \fIuse_sprintf\fR, they are tied to the particular \fIdest\fR you set them with. .Sp Note that \fIdest\fR \*(L"closes\*(R" the description of a destination, so you need to have any other related directives (ie. \fIformat\fR, \fIcount\fR, \&\fIuse_sprintf\fR, \fIdelete_if_unique\fR) before the \fIdest\fR directive. This ordering is necessary to avoid ambiguity in the multiple-destination case. .Sh "Event directives" .IX Subsection "Event directives" You can configure what happens for incoming events based on certain criteria. Currently, those criteria are a simple string match of one or more of the category, data, or hostname. So, for example, you can ignore all messages from \*(L"roguehost\*(R", or color \*(L"user logged in\*(R" messages for a certain user in bright red. Here are the useful directives: .IP "\fBevent:\fR" 4 .IX Item "event:" Starts a new event config. .IP "\fBmatch\fR \fIcategory:\fR \fIvalue\fR" 4 .IX Item "match category: value" .PD 0 .IP "\fBmatch\fR \fIdata:\fR \fIvalue\fR" 4 .IX Item "match data: value" .IP "\fBmatch\fR \fIhostname:\fR \fIvalue\fR" 4 .IX Item "match hostname: value" .PD This event config applies when the \*(L"category\*(R" is \*(L"value\*(R", or the \&\*(L"data\*(R" is value, or the \*(L"hostname\*(R" is \*(L"value\*(R". If multiple match lines are supplied, they are ANDed together. .IP "\fBcolor:\fR \fIcolor\fR" 4 .IX Item "color: color" .PD 0 .IP "\fBdescription:\fR \fIdescription_text\fR" 4 .IX Item "description: description_text" .IP "\fBdo_action:\fR \fIaction\fR" 4 .IX Item "do_action: action" .IP "\fBpriority:\fR \fIpriority\fR" 4 .IX Item "priority: priority" .PD color, description, do_action, and priority work the same way as they do in a \*(L"dest\*(R" config or in an \*(L"event\*(R" config. .Sp If \*(L"event\*(R", \*(L"dest\*(R", and \*(L"category\*(R" configs all apply to a given event than \&\*(L"event\*(R" has highest precedence, followed by \*(L"dest\*(R", followed by \*(L"category\*(R". .Sh "Category directives" .IX Subsection "Category directives" Several patterns can lead to the same category, so category-specific directives are associated with the category, not with a pattern. Here are the category directives: .IP "\fBcategory:\fR \fIcategory\fR" 4 .IX Item "category: category" Specifies which category subsequent directives will define. .IP "\fBfilter:\fR \fIfilter commands\fR" 4 .IX Item "filter: filter commands" By default, \fIlog_analysis\fR will output all the data it finds in a category. Filters let you specify, say, that only the top 10 items should be output, or that only the items that occurred fewer than 5 times should be output. If a category has data, but none of the data meet the filter rules, then the category will be completely skipped. See \*(L"\s-1FILTERS\s0\*(R" for more info. .IP "\fBsort:\fR \fIsorting keywords\fR" 4 .IX Item "sort: sorting keywords" Specifies how this category should be sorted in the output. Examples are \&\*(L"funky\*(R", \*(L"string\*(R", \*(L"value\*(R", \*(L"reverse value\*(R", etc. The default is \*(L"funky\*(R". See \*(L"\s-1SORTING\s0\*(R" for more info. .IP "\fBderive:\fR \fIderive commands\fR" 4 .IX Item "derive: derive commands" The usual way to populate categories is via the pattern config. But sometimes, you want to combine two or more elemental categories to make a new category. Any categories derived in this manner may not be a destination for simple patterns. .Sp There are currently three subcommands for this (the quotes are literal): .RS 4 .ie n .IP "\fI""category1""\fR \fBadd\fR \fI""category2""\fR" 8 .el .IP "\fI``category1''\fR \fBadd\fR \fI``category2''\fR" 8 .IX Item "category1 add category2" .PD 0 .ie n .IP "\fI""category1""\fR \fBsubtract\fR \fI""category2""\fR" 8 .el .IP "\fI``category1''\fR \fBsubtract\fR \fI``category2''\fR" 8 .IX Item "category1 subtract category2" .PD These do what you expect: take the values for the items in category2 and add or subtract them from the values for the items in category1. Any item defined in either category will be in the new category. Subtract can cause the values in the new category to be negative or 0. .ie n .IP "\fI""category1""\fR \fBremove\fR \fI""category2""\fR" 8 .el .IP "\fI``category1''\fR \fBremove\fR \fI``category2''\fR" 8 .IX Item "category1 remove category2" The new category will contain items in category1 that are not in category2. This is very different from subtract. .Sp Example: if category1 contains A with a value of 2 and B with a value of 2, while category2 contains A with a value of 1 and C with a value of 1, \&'\*(L"category1\*(R" subtract \*(L"category2\*(R"' will contain A with a value of 1, B with a value of 2, and C with a value of \-1, while '\*(L"category1\*(R" remove \*(L"category2\*(R"' will only contain B with a value of 2. .RE .RS 4 .RE .IP "\fBcolor:\fR \fIcolor\fR" 4 .IX Item "color: color" .PD 0 .IP "\fBdescription:\fR \fIdescription_text\fR" 4 .IX Item "description: description_text" .IP "\fBdo_action:\fR \fIaction\fR" 4 .IX Item "do_action: action" .IP "\fBpriority:\fR \fIpriority\fR" 4 .IX Item "priority: priority" .PD color, description, do_action, and priority work the same way as they do in a \*(L"dest\*(R" config or in an \*(L"event\*(R" config. .Sp If \*(L"event\*(R", \*(L"dest\*(R", and \*(L"category\*(R" configs all apply to a given event than \&\*(L"event\*(R" has highest precedence, followed by \*(L"dest\*(R", followed by \*(L"category\*(R". .Sh "Action directives" .IX Subsection "Action directives" In real mode and in gui mode, sometimes you want an \*(L"action\*(R" (like paging someone) to automatically happen when a particular message is seen. And in gui mode, you might want to run a command on a message interactively (ie. to telnet or ssh into the host it came from.) The directives to do that (inspired by \fIswatch\fR\|(1)) are: .IP "\fBaction:\fR \fIaction_name\fR" 4 .IX Item "action: action_name" Starts defining a new action named action_name. .IP "\fBcommand:\fR \fIcommand\fR" 4 .IX Item "command: command" The command to run for the current action. \fIcommand\fR uses the same tags as \fIreal_mode_output_format\fR. .Sp \&\s-1WARNING:\s0 you can potentially shoot yourself in the foot by passing data that has not been sanitized to a command on your system. Be careful! .IP "\fBwindow:\fR \fItitle\fR" 4 .IX Item "window: title" Performing the action will require creating a window using \fItitle\fR as the title. The title will be passed to \fIwindow_command\fR as the \*(L"%t\*(R" tag. \fItitle\fR itself uses the same tags as \&\fIreal_mode_output_format\fR. This only makes sense for gui mode. .Sp \&\s-1WARNING:\s0 you can potentially shoot yourself in the foot by passing data that has not been sanitized to a command on your system. Be careful! .IP "\fBuse_pipe:\fR" 4 .IX Item "use_pipe:" The data in the event will be sent to the command via standard input. The format used will be that specified by the \fIdefault_action_format\fR variable, unless overridden locally by the \fIaction_format:\fR directive. These formats allow the same tags as \fIreal_mode_output_format\fR. .IP "\fBaction_format:\fR \fIformat\fR" 4 .IX Item "action_format: format" See \fIuse_pipe\fR above. .IP "\fBthrottle:\fR \fIthrottle_time\fR" 4 .IX Item "throttle: throttle_time" Automatically-triggered actions can potentially result in a slew of events. The \*(L"throttle\*(R" option lets you specify a minimum amount of time before the action should recur with this event. The time can be specified as seconds, as minutes:seconds, or as hours:minutes:seconds. .Sp Throttles do not apply to actions and logins that are explicitly invoked via the \s-1GUI\s0. .Sp By default, the throttle is triggered on unique category and data. That is, if the event was category \*(L"user logged in\*(R" and the data was \*(L"morty\*(R", then the throttle will keep \*(L"user logged in\*(R", \*(L"morty\*(R" events from causing the action to run again, but won't stop \*(L"user logged in\*(R", \*(L"esther\*(R" or \&\*(L"no such user\*(R", \*(L"morty\*(R" events from triggering the action. This default is set with the \fIdefault_throttle_format\fR variable, which defaults to \&\*(L"%c\en%d\*(R". It can be overriden on a per-action basis with the \&\fIthrottle_format:\fR directive, which takes the same tags as \&\fIreal_mode_output_format\fR. If you want the throttle to be global to the action (say, a pager action), set throttle_format to a simple scalar value (like 1). .IP "\fBthrottle_format:\fR \fIformat\fR" 4 .IX Item "throttle_format: format" See \fIthrottle:\fR above. .Sh "Other directives" .IX Subsection "Other directives" .IP "\fBconfig_version\fR \fIversion-number\fR" 4 .IX Item "config_version version-number" Declare that the config is compatible with version \fIversion-number\fR. This is for version-control purposes. Every config file should have one of these. You can scan your config files' config versions with \&\fI\-I config_versions\fR. .IP "\fBfile_version\fR \fIrevision-information\fR" 4 .IX Item "file_version revision-information" Your own version control information. \fIrevision-information\fR can be arbitrary text. You can scan your config files' config versions with \&\fI\-I config_versions\fR. .IP "\fBinclude\fR \fIfile\fR" 4 .IX Item "include file" Read in configuration from \fIfile\fR. Dies if \fIfile\fR doesn't exist. \&\fIfile\fR is subject to usual tag substitutions; see \*(L"\s-1TAG\s0 \s-1SUBSTITUTION\s0\*(R". .IP "\fBinclude_if_exists\fR \fIfile\fR" 4 .IX Item "include_if_exists file" Just like \fBinclude\fR, but doesn't die if the file doesn't exist. .IP "\fBinclude_dir\fR \fIdir\fR" 4 .IX Item "include_dir dir" Read in all files in \fIdir\fR, and include them. Die if the directory doesn't exist, or if a file in the directory isn't readable. \fIdir\fR is subject to the usual tag substitutions; see \*(L"\s-1TAG\s0 \s-1SUBSTITUTION\s0\*(R". Any filenames that match a pattern in \fIfilename_ignore_patterns\fR will be skipped. .IP "\fBinclude_dir_if_exists\fR \fIdir\fR" 4 .IX Item "include_dir_if_exists dir" Just like \fBinclude_dir\fR, but doesn't die if the directory doesn't exist. \&\fIDoes\fR still die if any of the files in \fIdir\fR isn't readable. .IP "\fBblock_comment\fR" 4 .IX Item "block_comment" Throws out the block immediately after it. .IP "\fBset var\fR \fIvarname\fR =\fIvalue\fR" 4 .IX Item "set var varname =value" Set scalar variable \fIvarname\fR to value \fIvalue\fR. If the variable already exists, this will overwrite it. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBadd var\fR \fIvarname\fR =\fIvalue\fR" 4 .IX Item "add var varname =value" If scalar variable \fBvarname\fR already exists, append \fIvalue\fR to the end of its current value. If it doesn't yet exist, create it and set it to \&\fIvalue\fR. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBprepend var\fR \fIvarname\fR =\fIvalue\fR" 4 .IX Item "prepend var varname =value" If scalar variable \fBvarname\fR already exists, prepend \fIvalue\fR to the current value. If it doesn't yet exist, create it and set it to \&\fIvalue\fR. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBset arr\fR \fIarrname\fR =" 4 .IX Item "set arr arrname =" Read in the block that follows this declaration, make the lines into an array, and set the array variable \fIarrname\fR to that array. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBadd arr\fR \fIarrname\fR =" 4 .IX Item "add arr arrname =" Read in the block that follows this declaration, make the lines into an array, and append that array to the array named \fIarrname\fR. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBprepend arr\fR \fIarrname\fR =" 4 .IX Item "prepend arr arrname =" Read in the block that follows this declaration, make the lines into an array, and prepend that array to the array named \fIarrname\fR. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBremove arr\fR \fIarrname\fR =" 4 .IX Item "remove arr arrname =" Read in the block that follows this declaration, and for each line, look for and delete that line from array \fIarrname\fR. If one of these lines cannot be found, the result is a warning, not death. .Sp See \*(L"\s-1VARIABLES\s0\*(R" for the list of variables you can play with. .IP "\fBlocal\fR \s-1OTHER\s0 \s-1DIRECTIVE\s0" 4 .IX Item "local OTHER DIRECTIVE" Putting \*(L"local\*(R" in front of another directive means that this directive should be saved when gui_mode_config_savelocal is in effect. .IP "\fBnowarn\fR \s-1OTHER\s0 \s-1DIRECTIVE\s0" 4 .IX Item "nowarn OTHER DIRECTIVE" Putting \*(L"nowarn\*(R" in front of another directive means that this directive should not generate a config warning, i.e. for redefining a category filter. .SH "VARIABLES" .IX Header "VARIABLES" Some variables are scalar, which means they are strings or numbers. Some variables are arrays, which are lists of scalars. .PP Some variables are mandatory, which means they must be defined somewhere in one of the config files, while some variables are optional. .PP Some variables are global, while some are per-log-type extensions. Some example of per-log-type extensions are date_pattern and filenames. Extensions should actually appear in the format \*(L"\s-1TYPE_EXTENSION\s0\*(R", ie. date_pattern would actually appear as \fIsyslog_date_pattern\fR for the syslog log-type and \fIsulog_date_pattern\fR for sulog. .PP To see examples of many of the possibilities, as well as the default values, run \fIlog_analysis \-I internal_config\fR. .Sh "PER-LOG-TYPE \s-1VARIABLE\s0 \s-1EXTENSIONS\s0" .IX Subsection "PER-LOG-TYPE VARIABLE EXTENSIONS" .IP "\fBfilenames\fR" 4 .IX Item "filenames" This mandatory extension is an array of file basenames that apply to the log type. For example, if you wanted \fI/var/adm/messages.1\fR to be processed by the syslog rules, you might add \fImessages\fR to \fIsyslog_filenames\fR. .IP "\fBopen_command\fR" 4 .IX Item "open_command" Some log files (ie. wtmp log types) are in a binary format that needs to be interpreted by external commands. This optional scalar extension specifies a command to be run to interpret the file. The command is subject to the usual tag substitutions (see \*(L"\s-1TAG\s0 \s-1SUBSTITUTIONS\s0\*(R"), plus the \f(CW%f\fR tag maps to the file. For example, the wtmp log type defines \fIwtmp_open_command\fR as "\fIlast \-f \f(CI%f\fI\fR". If both \fIdecompression_rules\fR and \fIopen_command\fR apply to a given file, the intermediate data will be stored in a temp file unless \&\fIpipe_decompress_to_open\fR is used. See \*(L"pipe_decompress_to_open\*(R" for more info. .IP "\fBpipe_decompress_to_open\fR" 4 .IX Item "pipe_decompress_to_open" If both \fIdecompression_rules\fR and \fIopen_command\fR apply to a given file, the intermediate data will be stored in a temporary file by default to avoid problems with some commands that can't handle input from a pipe. If this optional scalar extension is set to \fI1\fR (or any \*(L"true\*(R") value, then instead, the output of the decompression rule will be piped to the open command, and the open command's \f(CW%f\fR tag will be mapped to \*(L"\-\*(R". .IP "\fBopen_command_is_continuous\fR" 4 .IX Item "open_command_is_continuous" If an \fIopen_command\fR has been specified and the command is the sort that never exits (ie. tcpdump or the like) you should set this to let log_analysis know what to expext. Such commands should only ever be used in real mode or gui mode. .IP "\fBpre_date_hook\fR" 4 .IX Item "pre_date_hook" This optional extension is an array of arbitrary perl commands that are run for each log line, before the date processing (or any other processing) is done. .IP "\fBdate_pattern\fR" 4 .IX Item "date_pattern" This mandatory extension is a scalar that contains a pattern with at least one parenthesized subpattern. Before any rules are applied to a log line, the engine strips off the date pattern. If the engine is only looking at one day (ie. the default), it takes the part of the string that matched the parenthesized subpattern, and if it isn't equal to the right date, it skips the line. The \fBdate_format\fR extension (next) describes what the date should look like. .IP "\fBdate_format\fR" 4 .IX Item "date_format" This mandatory extension is a scalar that describes the date using the same format as \fB\f(BIstrftime\fB\|(3)\fR. For example, syslog_date_format is \*(L"%b \f(CW%e\fR\*(R". .IP "\fBnodename_pattern\fR" 4 .IX Item "nodename_pattern" This optional extension is a pattern with at least one parenthesized subpattern. If it exists, then after the \fIdate_pattern\fR is stripped from the line, this pattern is stripped, and the part that matched the subpattern is compared to the nodename. If they're not equal, then the relevant counter for the category named by the \&\fIother_host_message\fR variable is incremented. Note that all nodenames are subject to having the local domain stripped from them; see \fIdomain\fR and \fIleave_FQDNs_alone\fR for details. .IP "\fBpre_skip_list_hook\fR" 4 .IX Item "pre_skip_list_hook" This optional extension is an array of perl commands to be run after the nodename check, just before the skip_list check. .IP "\fBskip_list\fR" 4 .IX Item "skip_list" This optional extension is obsolete and deprecated, but still works for backwards compatibility. .IP "\fBraw_rules\fR" 4 .IX Item "raw_rules" This optional extension is obsolete and deprecated, but still works for backwards compatibility. .Sh "\s-1GLOBAL\s0 \s-1VARIABLES\s0" .IX Subsection "GLOBAL VARIABLES" These variables are all globals. .IP "\fBlog_type_list\fR" 4 .IX Item "log_type_list" This variable is a mandatory global array that contains the list of all known log\-types, ie. \fIsyslog\fR, \fIsulog\fR, \fIwtmpx\fR, etc. .IP "\fBpat\fR" 4 .IX Item "pat" This variable is a madatory global array that contains a list of subpattern names followed by a comma, optional whitespace, and a perl regex that represents that subpattern. Some of the predefined patterns include \*(L"ip\*(R", \&\*(L"zone\*(R", \*(L"user\*(R", \*(L"mail_user\*(R", etc. Run \fIlog_analysis \-I pats\fR for a list. .IP "\fBhost_pat\fR" 4 .IX Item "host_pat" .PD 0 .IP "\fBfile_pat\fR" 4 .IX Item "file_pat" .IP "\fBip_pat\fR" 4 .IX Item "ip_pat" .IP "\fBmail_user_pat\fR" 4 .IX Item "mail_user_pat" .IP "\fBuser_pat\fR" 4 .IX Item "user_pat" .IP "\fBword_pat\fR" 4 .IX Item "word_pat" .IP "\fBzone_pat\fR" 4 .IX Item "zone_pat" .PD Legacy variables. Please don't use them. .IP "\fBother_host_message\fR" 4 .IX Item "other_host_message" .PD 0 .IP "\fBoutput_message_one_day\fR" 4 .IX Item "output_message_one_day" .IP "\fBoutput_message_all_days\fR" 4 .IX Item "output_message_all_days" .IP "\fBoutput_message_all_days_in_range\fR" 4 .IX Item "output_message_all_days_in_range" .PD Assorted mandatory scalars that are used for human-readable output. \&\fBother_host_message\fR defaults to \*(L"Other hosts syslogging to us\*(R", \&\fBoutput_message_one_day\fR defaults to \*(L"Logs for \f(CW%n\fR on \f(CW%d\fR\*(R", \&\fBoutput_message_all_days\fR defaults to \*(L"All logs for \f(CW%n\fR as of \f(CW%d\fR\*(R". \&\fBoutput_message_all_days_in_range\fR defaults to \*(L"All logs for \f(CW%n\fR for \f(CW%s\fR through \f(CW%e\fR\*(R". .IP "\fBdate_format\fR" 4 .IX Item "date_format" This variable is a mandatory global scalar that describes how you want the date printed in the output. Uses the format of \fB\f(BIstrftime\fB\|(3)\fR. Note that you probably shouldn't use characters that you wouldn't want in a filename (ie. whitespace or '/') if you want to use the \f(CW%d\fR tag for \&\fIoutput_file\fR. .IP "\fBoutput_file\fR" 4 .IX Item "output_file" Equivalent to \fI\-o file\fR. This variable is an optional global scalar that lists a filename that will be output to instead of to standard output. Works with \fImail_address\fR (if specified.) Note that this variable is subject to the usual tag substitutions (see \*(L"\s-1TAG\s0 \s-1SUBSTITUTIONS\s0\*(R", plus you can use the \f(CW%d\fR tag for the date, so you can set it to something like \&\*(L"/var/log_analysis/archive/%n\-%d\*(R". See \fIoutput_file_and_stdout\fR. .IP "\fBoutput_file_and_stdout\fR" 4 .IX Item "output_file_and_stdout" Equivalent to \fI\-O\fR. This variable is an optional global scalar that changes the behavior of \&\fI\-o\fR or \fIoutput_file\fR. By default, \fI\-o\fR or \fIoutput_file\fR causes output to only to only go to the named file. With this variable, output also goes to standard output. Note: this does not currently work with \fI\-m\fR. .IP "\fBnodename\fR" 4 .IX Item "nodename" This variable is an optional global scalar that is used in a bunch of places: in checking to see whether a message from syslog (or other log type that defines \fInodename_pattern\fR) originated on this host; in reading in various default config files; etc. If left unset in the config, its value is set from the output \&\fIuname\fR\|(2). Its value is used to set the \fIn\fR tag. Note that unless \fIleave_FQDNs_alone\fR is set, \fIlog_analysis\fR will try to strip the local domain name from \fInodename\fR. .IP "\fBosname\fR" 4 .IX Item "osname" .PD 0 .IP "\fBosrelease\fR" 4 .IX Item "osrelease" .PD These two optional global scalars default to the equivalent of \fIuname \-s\fR and \&\fIuname \-r\fR, respectively. They are only used for reading in default config files. Their values set the \fIs\fR and \fIr\fR tags, respectively. .IP "\fBdomain\fR" 4 .IX Item "domain" This variable is an optional global scalar. If you don't set it, \&\fIlog_analysis\fR will try to set it by looking for a \fIdomain\fR line in \&\fI/etc/resolv.conf\fR. If \fIlog_analysis\fR has \fIdomain\fR set, it will attempt to strip away the local domain name from all nodenames it encounters, unless \fIleave_FQDNs_alone\fR is set. See \fIleave_FQDNs_alone\fR for details. .IP "\fBleave_FQDNs_alone\fR" 4 .IX Item "leave_FQDNs_alone" This variable is an optional global scalar. By default, if \fIlog_analysis\fR has \fIdomain\fR set (either explicitly or implicitly), it will attempt to strip away the domain name in \fIdomain\fR, or \*(L"localdomain\*(R", from all nodenames it encounters. If you set this to \fI1\fR, or to some other true value, \fIlog_analysis\fR will not attempt to strip the domain name in \fIdomain\fR. .IP "\fB\s-1PATH\s0\fR" 4 .IX Item "PATH" This variable is an optional global scalar that sets the \fI\s-1PATH\s0\fR environment variable. This doesn't help the initial setting of \&\fInodename\fR, \fIosname\fR, or \fIosrelease\fR, which are set from \fIuname\fR\|(2). .IP "\fBumask\fR" 4 .IX Item "umask" This variable is an optional global scalar that sets the umask. See \fIumask\fR\|(2). .IP "\fBpriority\fR" 4 .IX Item "priority" This variable is an optional global scalar that sets the priority, or \&\*(L"niceness.\*(R" See \fInice\fR\|(1). Setting this to zero means run unchanged from the current niceness. Setting this negative is a bad idea unless you really know what you're doing, and is forbdidden to non-root users. .IP "\fBdecompression_rules\fR" 4 .IX Item "decompression_rules" This variable is an optional global array of rules to decompress compressed files, in the format: compression\-extension, comma, space, command to decompress to stdout. The command is subject to the usual tag substitutions (see \*(L"\s-1TAG\s0 \s-1SUBSTITUTIONS\s0\*(R", plus \f(CW%f\fR stands for the filename. For example, the rule for gzipped files is: .Sp \&\f(CW\*(C`gz, gzip \-dc %f\*(C'\fR .Sp The default rules support: .gz .Z .bz2 .Sp If both \fIdecompression_rules\fR and \fIopen_command\fR apply to a given file, the default is to use a temp file for the intermediate results unless \&\fIpipe_decompress_to_open\fR is used. See \*(L"pipe_decompress_to_open\*(R" for more info. .IP "\fBpgp_rules\fR" 4 .IX Item "pgp_rules" This variable is an optional global array of rules for \s-1PGP\s0 encrypting messages, in the format: \s-1PGP\s0 type (user defined), comma, space, command to \s-1PGP\s0 encrypt stdin to stdout. The command is subject to the usual tag substitutions, plus \f(CW%m\fR stands for the email address. For use with the "\fB\-p\fR\*(L" and \*(R"\fB\-m\fR" options. For example, the rule for gnupg is: .Sp \&\f(CW\*(C`g, gpg \-aer %m 2>&1\*(C'\fR .Sp Internally defined rules are \*(L"g\*(R" for \*(L"gnupg\*(R", \*(L"2\*(R" for \s-1PGP\s0 2.x, and \*(L"5\*(R" for \s-1PGP\s0 5.x. .Sp \&\fB\s-1WARNING\s0\fR: The user who runs log_analysis must have already imported the mail destination's key for this to work. Make sure to test this before you put it in a cronjob. .IP "\fBfilename_ignore_patterns\fR" 4 .IX Item "filename_ignore_patterns" This variable is an optional global array of patterns that describe filenames to be skipped in an include_dir/include_dir_if_exists context, such as emacs backup file (\*(L".*~\*(R") or vim backup files (\*(L"\e..*\e.swp\*(R"). Only the file component of the path is examined, not the directory component. Patterns implicitly begin with ^ and implicitly end with $. .IP "\fBmail_address\fR" 4 .IX Item "mail_address" This variable is an optional global scalar that can consist of an email address. If set, the output of the script will be mailed to the address it is set to. The \fB\-m\fR option does the same thing, and overrides this. .IP "\fBmail_command\fR" 4 .IX Item "mail_command" This variable is an optional global scalar that is the command used to send mail if \fB\-m\fR is user or \fBmail_address\fR is set. The \fB\-M\fR option does the same thing, and overrides this. This variable is subject to the usual tag substitutions, plus \f(CW%m\fR stands for mail_address and \f(CW%o\fR stands for the relevant output message. The default is: .Sp \&\f(CW\*(C`Mail \-s '%o' %m\*(C'\fR .IP "\fBmemory_size_command\fR" 4 .IX Item "memory_size_command" This variable is an optional global scalar that is the command used to determine the process' memory size. Subject to the usual tag substitutions, plus \f(CW%p\fR stands for the \s-1PID\s0 (process \s-1ID\s0) in question. If set, the command is run at the end of the report, and the output is included in the footer. .Sp The default value for Linux is: .Sp \&\f(CW\*(C`ps \-p %p \-o vsz | tail \-n +2\*(C'\fR .Sp The default value for Solaris/SunOS is: .Sp \&\f(CW\*(C`ps \-p %p \-o vsz | tail \-n +2\*(C'\fR .IP "\fBoptional_log_files\fR" 4 .IX Item "optional_log_files" This variable is an optional array of file globs that are to be processed. Note that, unlike \fIrequired_log_files\fR, these are globs rather than literal filenames, although literal filenames will also work. [Globs are filenames with wildcards, ie. \fI/var/adm/messages*\fR.] .Sp See \fI\-r\fR for an issue specific to real mode and gui mode. .IP "\fBcommands_to_run\fR" 4 .IX Item "commands_to_run" This variable is an optional array of commands that are also supposed to be run to give a snapshot of the system state. These are currently: \&\fIw\fR, \fIdf \-k\fR, and \fIcat /etc/dumpdates\fR. .IP "\fBrcs_command\fR" 4 .IX Item "rcs_command" This variable is an optional global scalar that is the command used to do \&\s-1RCS\s0 check-in on files (i.e. when gui_mode_config_save_does_rcs is set). This variable is subject to the usual tag substitutions, plus \f(CW%f\fR stands for the file in question. The default is intended for \s-1RCS\s0, although \s-1SCCS\s0, \s-1CVS\s0, \s-1SVN\s0, or other systems could be substituted. The default is: .Sp \&\f(CW\*(C`ci \-q \-l \-t\-%f \-m'automatic check\-in' %f\*(C'\fR .IP "\fBsuppress_commands\fR" 4 .IX Item "suppress_commands" If set, the commands in \fBcommands_to_run\fR are \s-1NOT\s0 run during report mode. This is equivalent to the \fB\-s\fR option. .IP "\fBsuppress_footer\fR" 4 .IX Item "suppress_footer" If set, the various report mode footers are not displayed. This is equivalent to the \fB\-S\fR option. .IP "\fBignore_categories\fR" 4 .IX Item "ignore_categories" This variable is an optional array of categories that you don't want to see. Rather than try to remove all the rules for these categories, you can just list them here. .IP "\fBpriority_categories\fR" 4 .IX Item "priority_categories" This variable is an optional array of categories that will be listed first in the output. .IP "\fBdays_ago\fR" 4 .IX Item "days_ago" This optional scalar variable is the config equivalent of the \fB\-d\fR option. .IP "\fBprocess_all_nodenames\fR" 4 .IX Item "process_all_nodenames" This optional scalar variable is the config equivalent of the \fB\-N\fR option. .IP "\fBtype_force\fR" 4 .IX Item "type_force" This optional scalar is the config equivalent of the \fB\-t\fR option. .IP "\fBallow_nodenames\fR" 4 .IX Item "allow_nodenames" This variable is an optional array of nodenames that can log to this host. Usually, logs labelled as being from another host will not be anaylzed, and each such line will be listed in a special category; if you chose to allow some nodenames (or if you choose to process all nodenames by setting \fB\-N\fR or setting \fIprocess_all_nodenames\fR) then these log messages will also be processed. .IP "\fBreal_mode\fR" 4 .IX Item "real_mode" This variable is the config equivalent of the \fB\-r\fR option; see the \&\fB\-r\fR option for more details. .IP "\fBreal_mode_output_format\fR" 4 .IX Item "real_mode_output_format" This is a required global scalar. It describes the per-output format for real mode and gui mode. It is subject to normal tag substitution (see \*(L"\s-1TAG\s0 \s-1SUBSTITUTION\s0\*(R"); in addition to the normal tags, \*(L"%c\*(R" is replaced with the category, \*(L"%#\*(R" is replaced with the count, \*(L"%d\*(R" is replaced with the formatted data, \*(L"%h\*(R" is replaced with the nodename of the message, and \*(L"%R\*(R" is the raw, original log line without the trailing newline. If \fIkeep_all_log_lines\fR is set, you also get \*(L"%A\*(R" for all the raw logs line. \&\fI\s-1WARNING:\s0\fR you usually want \*(L"%h\*(R" (nodename of the message), not \*(L"%n\*(R" (nodename of the host you're running on, which is one of the default tags substitutions.) Defaults to \*(L"%c: (loghost \f(CW%n\fR, from host \f(CW%h\fR)\en%\-10# \f(CW%d\fR\en\en\*(R". .IP "\fBreal_mode_sleep_interval\fR" 4 .IX Item "real_mode_sleep_interval" This optional global scalar is for use with real mode and gui mode. In these modes, \fIlog_analysis\fR reads log files for more data, sleeps for a little while, and then reads again. The sleep interval controls how long \fIlog_analysis\fR sleeps (in seconds). It defaults to 1. .IP "\fBreal_mode_check_interval\fR" 4 .IX Item "real_mode_check_interval" This optional global scalar is for use with real mode and gui mode. In these modes, \fIlog_analysis\fR sits in a loop reading from the logs files. Periodically, it wants to check if the log files have rolled over or if newer log files have appeared. If at least this long (in seconds) goes by since the last time we've checked, we check again. .IP "\fBkeep_all_raw_logs\fR" 4 .IX Item "keep_all_raw_logs" This optional global scalar is a boolean for use with real mode and gui mode. It enables a \f(CW%A\fR tag that contains all the raw logs for a given entry. That is, if you have multiple log lines that contain essentially the same data, only the first line shows up in \f(CW%R\fR, and the rest are thrown out. This variable lets you keep them all. It can eat up a lot of memory, so it's disabled by default. .IP "\fBreal_mode_backlogs\fR" 4 .IX Item "real_mode_backlogs" This optional global scalar is equivalent to \fI\-b\fR. .IP "\fBcolors\fR" 4 .IX Item "colors" This variable is an optional global array for use with real mode and gui mode. It defines the colors available on console, using \*(L"name, string\*(R" pairs. The usual tag substitution rules apply to the string, plus the special tag \f(CW%a\fR stands for octal character 007 (\s-1ASCII\s0 \s-1BEL\s0) and \&\f(CW%e\fR stands for octal character 033 (\s-1ASCII\s0 \s-1ESC\s0). Some of the colors are actually mode changes (ie. \*(L"normal\*(R", \*(L"inverse\*(R", \*(L"reverse\*(R", \*(L"blink\*(R", etc.) If you define any colors, you should also define a \*(L"normal\*(R" color. Note that \*(L"bell\*(R" is among the colors; it didn't belong anywhere else. You can list colors with \fIlog_analysis \-I colors\fR. .IP "\fBgui_mode\fR" 4 .IX Item "gui_mode" This variable is the config equivalent of the \fB\-g\fR option; see the \&\fB\-g\fR option for more details. It is an optional scalar. .IP "\fBgui_mode_modifier\fR" 4 .IX Item "gui_mode_modifier" In gui mode, the default modifier to do things with the keyboard is \&\*(L"alt\*(R", ie. \*(L"alt\-q\*(R" to exit. This lets you change it. It is an optional scalar. .IP "\fBreport_mode_output_node_per_category\fR" 4 .IX Item "report_mode_output_node_per_category" .PD 0 .IP "\fBreport_mode_combine_nodes\fR" 4 .IX Item "report_mode_combine_nodes" .IP "\fBreport_mode_combine_shows_nodes\fR" 4 .IX Item "report_mode_combine_shows_nodes" .IP "\fBreport_mode_combine_is_partway\fR" 4 .IX Item "report_mode_combine_is_partway" .PD These are assorted options for dealing with output for multiple node situations (ie. logservers.) They are all optional scalars. See \*(L"\s-1LOGSERVER\s0 \s-1CONSIDERATIONS\s0\*(R" for details. .IP "\fBwindow_command\fR" 4 .IX Item "window_command" In gui mode, if we need a window to run a command, say an action, this will be the command that is used. The tags are the same as \&\fIreal_mode_output_format\fR, plus we have \*(L"%t\*(R" as the title and \*(L"%C\*(R" as the command. It is an optional scalar. .IP "\fBlogin_action\fR" 4 .IX Item "login_action" This optional array lets you specify what action should be used to login to a given host in gui mode, overriding \fIdefault_login_action\fR. Lines are in the format \fIhost, login_action\fR. .IP "\fBdefault_login_action\fR" 4 .IX Item "default_login_action" This optional scalar specifies which login action should be used to login in hosts by default in gui mode. .IP "\fBdefault_throttle_format\fR" 4 .IX Item "default_throttle_format" See the \fIthrottle:\fR directive in the \fIaction\fR group. .IP "\fBdefault_action_format\fR" 4 .IX Item "default_action_format" See the \fIuse_pipe\fR directive in the \fIaction\fR group. .IP "\fBprint_command\fR" 4 .IX Item "print_command" .PD 0 .IP "\fBprint_format\fR" 4 .IX Item "print_format" .IP "\fBsave_format\fR" 4 .IX Item "save_format" .IP "\fBgui_mode_config_autosave\fR" 4 .IX Item "gui_mode_config_autosave" .IP "\fBgui_mode_config_savelocal\fR" 4 .IX Item "gui_mode_config_savelocal" .IP "\fBgui_mode_config_save_does_rcs\fR" 4 .IX Item "gui_mode_config_save_does_rcs" .IP "\fBgui_mode_config_file\fR" 4 .IX Item "gui_mode_config_file" .IP "\fBgui_mode_print_all\fR" 4 .IX Item "gui_mode_print_all" .IP "\fBgui_mode_save_all\fR" 4 .IX Item "gui_mode_save_all" .IP "\fBgui_mode_save_events_file\fR" 4 .IX Item "gui_mode_save_events_file" .PD These are for \s-1GUI\s0 use. .IP "\fBdefault_sort\fR" 4 .IX Item "default_sort" This variable is an optional global scalar that describes how certain things will be sorted. See \*(L"\s-1SORTING\s0\*(R" for info on what this can be set to. Defaults to \fIfunky\fR. .IP "\fBdefault_filter\fR" 4 .IX Item "default_filter" This variable is an optional global scalar that describes the default category filter. See \*(L"\s-1FILTERS\s0\*(R" for info on what this can be set to. .SH "PREPROCESSOR DIRECTIVES" .IX Header "PREPROCESSOR DIRECTIVES" \&\s-1NB:\s0 these get completely processed before all other directives, so they don't care about other syntax elements. Except as noted, these should appear at the beginning of the line after optional whitespace. .IP "\fB@@end\fR" 4 .IX Item "@@end" End of config file. .IP "\fB@@define\fR \fIvar\fR \fIval\fR" 4 .IX Item "@@define var val" Define \fIvar\fR as value \fIval\fR. \fIvar\fR should contain only alphanumerics and underscores, and start with an alphanumeric. \fIval\fR may contain no whitespace. .IP "\fB@@undef\fR \fIvar\fR" 4 .IX Item "@@undef var" Undo any previous definition of \fIvar\fR. .IP "\fB@@ifdef\fR \fIvar\fR" 4 .IX Item "@@ifdef var" .PD 0 .IP "\fB@@ifndef\fR \fIvar\fR" 4 .IX Item "@@ifndef var" .IP "\fB@@else\fR" 4 .IX Item "@@else" .IP "\fB@@endif\fR" 4 .IX Item "@@endif" .PD If variable \fIvar\fR is defined, even defined as a false value, the lines after the @@ifdef are used, otherwise the lines are effectively commented out. @@ifndef is the logical reverse. @@ifdef and @@ifndef must be terminated by an @@endif. They may contain an @@else section that works in the usual way. .IP "\fB@@ifhost\fR \fIname\fR" 4 .IX Item "@@ifhost name" .PD 0 .IP "\fB@@ifnhost\fR \fIname\fR" 4 .IX Item "@@ifnhost name" .PD These are just like @@ifdef and @@ifndef above, except that they test if the variable \fInodename\fR is equal to the value supplied for \fIname\fR. .IP "\fB@@ifos\fR \fIname\fR" 4 .IX Item "@@ifos name" .PD 0 .IP "\fB@@ifnos\fR \fIname\fR" 4 .IX Item "@@ifnos name" .PD These are just like @@ifdef and @@ifndef above, except that they test if the variable \fIosname\fR is equal to the value supplied for \fIname\fR. .IP "\fB@@{var}\fR" 4 .IX Item "@@{var}" If this string appears anywhere on any line, then if \fIvar\fR is a defined variable, its value is substituted. If \fIvar\fR is not a defined variable, the string is left literally. Note that this behaviour is different from that of \fIaide\fR\|(1). .IP "\fB@@warn\fR \fImessage\fR" 4 .IX Item "@@warn message" Print out \fImessage\fR as soon as the config is read. .IP "\fB@@error\fR \fImessage\fR" 4 .IX Item "@@error message" Print out \fImessage\fR and exit as soon as the config is read. .SH "SORTING" .IX Header "SORTING" You can sort category items using several different criteria. You can set the \fIdefault_sort\fR, and then on a per-category basis, you can use the \&\fIsort:\fR keyword to control things even closer. If you don't override it, \&\fIdefault_sort\fR defaults to \fIfunky\fR. Sorts stack, so you can use \&\*(L"reverse string\*(R" or \*(L"reverse value\*(R". In theory, you can stack all of them, ie. \*(L"reverse value reverse funky\*(R", but there is no guarantee that sorts are stable. .PP The available sorts are: .IP "\fBstring\fR" 4 .IX Item "string" Simple string \*(L"lexicographical\*(R" sort. Does not handle numbers well. .IP "\fBnumeric\fR" 4 .IX Item "numeric" Sorts numbers, including decimal numbers, correctly, but cannot handle non-numeric characters, and cannot handle IPs correctly. .IP "\fBfunky\fR" 4 .IX Item "funky" Tries to do the right thing with mixed integers and strings. Handles \s-1IP\s0 addresses correctly. It does not handle decimal numbers correctly. .IP "\fBreverse\fR" 4 .IX Item "reverse" Reverses the current order. Can be used in conjunction with another sort, ie. \*(L"reverse string\*(R". .IP "\fBvalue\fR" 4 .IX Item "value" Sorts by count (ascending) instead of by item. .IP "\fBnone\fR" 4 .IX Item "none" Does no additional sorting. .SH "FILTERS" .IX Header "FILTERS" Sometimes, you don't want to see all the information in a category, just the top few items, or whatever. Filters let you do this. You can set a default filter using \fIdefault_filter\fR (defaults to \*(L"none\*(R") or you can set filters on a per-category basis using the \fIfilter:\fR keyword. .PP Some commands you can use: .IP "\fB>= \fRN" 4 .IX Item ">= N" Only show items whose count is greater than or equal to N. .IP "\fB<= \fRN" 4 .IX Item "<= N" .PD 0 .IP "\fB> \fRN" 4 .IX Item "> N" .IP "\fB< \fRN" 4 .IX Item "< N" .IP "\fB= \fRN, \fB== \fRN" 4 .IX Item "= N, == N" .IP "\fB!= \fRN, \fB<> \fRN, \fB>< \fRN" 4 .IX Item "!= N, <> N, >< N" .PD These are analagous to >=. .IP "\fBtop \fRN" 4 .IX Item "top N" .PD 0 .IP "\fBtop \fRN\fB%\fR" 4 .IX Item "top N%" .IP "\fBtop_strict \fRN" 4 .IX Item "top_strict N" .IP "\fBtop_strict \fRN\fB%\fR" 4 .IX Item "top_strict N%" .PD Only show those items who count is in the top N or top N%. The difference between \fItop\fR and \fItop_strict\fR is what happens when there's a tie to be in the top N. \fItop\fR will include all the items that tie, even if this means there will be more than N. \fItop_strict\fR always cuts off after N. .IP "\fBbottom \fRN" 4 .IX Item "bottom N" .PD 0 .IP "\fBbottom \fRN\fB%\fR" 4 .IX Item "bottom N%" .IP "\fBbottom_strict \fRN" 4 .IX Item "bottom_strict N" .IP "\fBbottom_strict \fRN\fB%\fR" 4 .IX Item "bottom_strict N%" .PD Analagous to top. .IP "subfilter \fBand\fR subfilter" 4 .IX Item "subfilter and subfilter" .PD 0 .IP "subfilter \fBor\fR subfilter" 4 .IX Item "subfilter or subfilter" .PD Lets you \*(L"and\*(R" or \*(L"or\*(R" two or more subfilters togther (ie. "top 10 and >= 4"). .SH "UNIQUE DESTINATION" .IX Header "UNIQUE DESTINATION" \&\fIlog_analysis\fR has a relatively simple counting mechanism that is usually effective. One exception is when you want to track how often one value occurs in your log uniquely with another value. For example, suppose you're watching firewall logs, \f(CW$1\fR is the source \s-1IP\s0, \f(CW$2\fR is the destination \s-1IP\s0, and you want to know if you're being scanned. Tracking counts of \*(L"$1 \f(CW$2\fR\*(R" requires you to manually count how many times \f(CW$1\fR occurs. Tracking just \*(L"$1\*(R" doesn't really tell you what you want, because you don't know if the source \&\s-1IP\s0 is really scanning a bunch of different hosts, or just has a renegade process that's banging away at a single destination. What you want to track is how many times \f(CW$1\fR occurs with a unique \f(CW$2\fR. .PP To do this sort of thing in a pattern config, set \fIformat:\fR to \&\fIvalue1, value2\fR and set \fIdest:\fR to "\fI\s-1UNIQUE\s0\fR category\-name". In our example, we might say: .PP .Vb 2 \& format: $1, $2 \& dest: UNIQUE scans .Ve .PP The fields in format are not evaluated in a string context, and only the last comma acts as a separator. So, if \f(CW$3\fR contains the protocol information, you might say this: .PP .Vb 2 \& format: sprintf("%-15s %s", $1, $3), $2 \& dest: UNIQUE scans .Ve .PP When detecting scans in particular, it makes sense to specify an event filter, ie.: .PP .Vb 2 \& category: scans \& filter: >= 5 .Ve .PP Note that it's often useful to specify multiple dests with firewall pattern, ie. one regular category dest, one \s-1UNIQUE\s0 dest with a filter threshold to detect a scan. If so, you might want to add \fIdelete_if_unique\fR to the regular dest, so if it turns out you have a scan, you don't have to wade through lots of garbage. Ie.: .PP .Vb 1 \& pattern: kernel: block from ($pat{ip}):($pat{port}) to ($pat{ip}):($pat{port}) .Ve .PP .Vb 3 \& format: $1 => $3:$4 \& delete_if_unique \& dest: kernel block .Ve .PP .Vb 2 \& format: $1, $3 \& dest: UNIQUE scans .Ve .PP .Vb 2 \& category: scans \& filter: >=5 .Ve .SH "TAG SUBSTITUTIONS" .IX Header "TAG SUBSTITUTIONS" A few items are subject to \*(L"tag substitutions\*(R". These are kind of like printf's \*(L"%\*(R" sequences: a sequence like \*(L"%n\*(R" gets replaced with the nodename. You can optionally specify field widths, which default to right-justified (ie. \*(L"%10n\*(R") or can be preceeded with a \*(L"\-\*(R" to make them left-justified (ie. \*(L"%\-10n\*(R"). Also, a few of the basic C\-style backslash sequences are understood (ie. \en for newline, \et for tab, \e\e for backslash). Anything subject to tag substitutions will be listed as such. .PP Here are the standard tag sequences: .IP "\fB%%\fR literal %" 4 .IX Item "%% literal %" .PD 0 .IP "\fB%n\fR nodename (ie. the output of \fIuname \-n\fR.)" 4 .IX Item "%n nodename (ie. the output of uname -n.)" .IP "\fB%r\fR \s-1OS\s0 release (ie. the output of \fIuname \-r\fR.)" 4 .IX Item "%r OS release (ie. the output of uname -r.)" .IP "\fB%s\fR \s-1OS\s0 name (ie. the output of \fIuname \-s\fR.)" 4 .IX Item "%s OS name (ie. the output of uname -s.)" .PD .PP There are also other tag sequences that apply in special situations. They are listed where they apply. .PP If you try to use an undefined sequence (ie. \*(L"%Z\*(R" or something else), you'll get an error. .SH "LOGSERVER CONSIDERATIONS" .IX Header "LOGSERVER CONSIDERATIONS" \&\fIlog_analysis\fR defaults to single host operation. If you have a logserver that allows logs from multiple hosts (ie. centralized logging) then you potentially have two concerns: configuring what hostnames to allow, and how to display multi-node logs in report mode. .PP By default, log_analysis will only allow logs from the nodename of the logserver, so if you want to allow other nodes, you need to tell \&\fIlog_analysis\fR which hostnames it should allow logs from. Either set \&\fIallow_nodenames\fR to a list of nodenames to allow logs from, or set \&\fIprocess_all_nodenames\fR (\s-1AKA\s0 option \fI\-N\fR) to accept everything. Another useful variable here is \fIleave_FQDNs_alone\fR. .PP Once you've accepted multiple nodes, there are a number of ways \&\fIlog_analysis\fR can display them. Let's say I received two \&\*(L"Accepted publickey for morty from 192.168.1.1 port 50000 ssh2\*(R" events from \*(L"red\-sonja\*(R" and three from \*(L"conan\*(R". In the default mode, that would look like this: .PP .Vb 1 \& Logs found for other hosts. For host conan: .Ve .PP .Vb 4 \& ... \& sshd: accepted publickey: \& 3 morty from 192.168.1.1 \& ... .Ve .PP .Vb 1 \& Logs found for other hosts. For host red-sonja: .Ve .PP .Vb 4 \& ... \& sshd: accepted publickey: \& 2 morty from 192.168.1.1 \& ... .Ve .PP You can get the categories listed together more compactly by setting \fIreport_mode_output_node_per_category\fR. Ie: .PP .Vb 3 \& ... \& sshd: accepted publickey: (host conan) \& 3 morty from 192.168.1.1 .Ve .PP .Vb 3 \& sshd: accepted publickey: (host red-sonja) \& 2 morty from 192.168.1.1 \& ... .Ve .PP If you set \fIreport_mode_combine_nodes\fR, the category will be combined into a single category. Ie.: .PP .Vb 4 \& ... \& sshd: accepted publickey: \& 5 morty from 192.168.1.1 \& ... .Ve .PP If you set both \fIreport_mode_combine_nodes\fR and \&\fIreport_mode_combine_shows_nodes\fR, you get the combined messages along with a list of applicable hostnames. Ie.: .PP .Vb 4 \& ... \& sshd: accepted publickey: \& 5 morty from 192.168.1.1 (conan red-sonja) \& ... .Ve .PP If you set both \fIreport_mode_combine_nodes\fR and \&\fIreport_mode_combine_is_partway\fR, the messages are listed like so: .PP .Vb 5 \& ... \& sshd: accepted publickey: \& 3 morty from 192.168.1.1 (conan) \& 2 morty from 192.168.1.1 (red-sonja) \& ... .Ve .PP Other combinations of the variables \fIreport_mode_output_node_per_category\fR, \&\fIreport_mode_combine_nodes\fR, \fIreport_mode_combine_shows_nodes\fR, and \&\fIreport_mode_combine_is_partway\fR produce undefined results. .SH "EXAMPLES" .IX Header "EXAMPLES" \&\fBlog_analysis \-m root@whatever\fR .PP Analyze yesterday's logs and mail the results to root@whatever. You might want to put this in a cronjob. .PP \&\fBlog_analysis \-p5 \-m root@whatever\fR .PP Same as the last one, but \s-1PGP\s0 encrypt the logs using \s-1PGP\s0 5 before mailing. .PP \&\fBlog_analysis \-a\fR .PP Look at all the logs, not just yesterday's. .PP \&\fBlog_analysis \-sa /var/adm/sulog\fR .PP Analyze all the contents of sulog, don't bother with local state. .PP \&\fBlog_analysis \-san otherhost syslog-file\fR .PP Analyze all the contents of syslog\-file, which was created on \*(L"otherhost\*(R". Don't run the local state commands. .PP \&\fBlog_analysis \-sd1 \-f foo.conf \-U\fR .PP This style of command is useful while developing local configs to handle log messages unknown to the internal config. .PP Use \fIfoo.conf\fR as a config file in addition to the internal config. Output only the unknowns. .SH "COMPATIBILITY" .IX Header "COMPATIBILITY" Written for Solaris and Linux. May work for other OSs. .PP Written for perl 5.00503. May work with some earlier perl versions. .SH "NOTES" .IX Header "NOTES" You often need to be root to read interesting log files. .PP It is customary to regularly \*(L"rollover\*(R" log files. Many log file formats don't include year infomation; among other benefits, rollover makes the dates in such logfiles unambiguous. \fBlog_analysis\fR by default looks for log lines that match a particular day of the year, but does not even try to guess the year. If the \s-1OS\s0 you're using doesn't rollover some logfiles by default (ie. Solaris doesn't rollover /var/adm/wtmpx, /var/adm/wtmp, or /var/adm/sulog), you will need to rollover these files yourself to get valid output from this program. .PP On some OSes, '%' (ie. the percent symbol) has a special meaning in crontabs, and needs to be commented. See \fIcrontab\fR\|(1). .PP When there are a lot of unknowns, \fBlog_analysis\fR can take a lot longer to run. This is particularly a problem when you're first running it, before you customize for your site. To get around this problem, if you send \fBlog_analysis\fR a \s-1SIGINT\s0 (ie. if you hit control\-C), it will stop going through your logs and immediately output the results. .SH "FILES" .IX Header "FILES" .IP "\fB/etc/log_analysis.conf\fR" 4 .IX Item "/etc/log_analysis.conf" .PD 0 .IP "\fB/etc/log_analysis.conf\-%n\fR" 4 .IX Item "/etc/log_analysis.conf-%n" .IP "\fB/etc/log_analysis.conf\-%s\-%r\fR" 4 .IX Item "/etc/log_analysis.conf-%s-%r" .IP "\fB/etc/log_analysis.conf\-%s\fR" 4 .IX Item "/etc/log_analysis.conf-%s" .IP "\fB/etc/log_analysis.conf\fR" 4 .IX Item "/etc/log_analysis.conf" .IP "\fB/etc/log_analysis.conf\-%n\fR" 4 .IX Item "/etc/log_analysis.conf-%n" .IP "\fB/etc/log_analysis.conf\-%s\-%r\fR" 4 .IX Item "/etc/log_analysis.conf-%s-%r" .IP "\fB/etc/log_analysis.conf\-%s\fR" 4 .IX Item "/etc/log_analysis.conf-%s" .PD Config files, in order of precedence. \*(L"%n\*(R", \*(L"%s\*(R", and \*(L"%r\*(R" have the usual tag substitution meanings; see \*(L"\s-1TAG\s0 \s-1SUBSTITUTIONS\s0\*(R". .IP "\fB/etc/log_analysis.d\fR" 4 .IX Item "/etc/log_analysis.d" .PD 0 .IP "\fB/etc/log_analysis.d\fR" 4 .IX Item "/etc/log_analysis.d" .PD Plug-in directories. All files in these directories will be treated as config files and include'd. .IP "\fB$HOME/.log_analysis.conf\fR" 4 .IX Item "$HOME/.log_analysis.conf" If you start log_analysis with the \*(L"\-g\*(R" option, this file will be loaded as a config file after all other config files, except those specified by \fI\-f\fR. This is also the default file for the \*(L"save config\*(R" menu option. .SH "AUTHOR" .IX Header "AUTHOR" Mordechai T. Abzug .SH "See Also" .IX Header "See Also" \&\fIsyslogd\fR\|(8), \fIlast\fR\|(1), \fIperlre\fR\|(1)