All directives are shown with the standard default value where applicable, if omitted the default value
will be used.
EXTERNALCONFIGURATIONFILES
All configuration directives can be optionally split into different configuration files and then read
with the two following statements.
include<configurationfile>
Parse the specified configuration file.
includedir<directory>
Parse all files inside <directory>. The files will be parsed in alphabetical order, keep in mind
that regexps order matters so includedir should be used carefully, see REGEXPDEFINITIONS for
details.
STATICOPTIONS
These options will be read the first time tenshi reads its config file. They cannot be changed by re-
reading the config file. If you change one of these options and HUP tenshi it will die. You have been
warned.
setuidtenshi
Specify the effective user ID of the process when in daemon mode. The user must be able to read
the selected log files, the configuration file and write the specified pid file. Never use
privileged users here since it's not usually necessary (log files perms can be set accordingly
with most syslog implementations).
setgidtenshi
Specify the effective group ID of the process when in daemon mode.
setpidfile/var/run/tenshi.pid
The file containing the PID of the process, useful for start/stop scripts.
setlogfile<logfilepath>
A log file to monitor, this may be specified multiple times to watch more than one log file.
Depending on your tail implementation you might need to use the tail_multiple setting for multiple
files to work. This mode can be used along with fifo and listen settings.
settail/usr/bin/tail-q--follow=name--retry-n0
Specify the path and arguments for the tail binary used for reading the log files. The invocation
must be tuned against your current 'tail' implementation. Default values are configured for
standard GNU coreutils tail. The --follow=name and --retry flags should deal properly with log
rotation, if missing on your implementation we suggest that you use something like 'cp /dev/null
logfile' as a safe way for clearing the log file upon rotation.
settail_multiple<on|off>
Some tail implementations do not handle more than one log file. When this option is enabled
multiple tail commands will be forked, instead of a single command with multiple arguments. This
option is disabled by default.
setfifo<fifopath>
A FIFO file to monitor. This option allows you to use a syslog-ng pipe() destination (or any other
syslog implementation that allows FIFO usage). This may be specified multiple times to watch more
than one fifo file. This option is meant to be used only when the installed 'tail' binary doesn't
behave properly with FIFOs, please test your tail implementation before using this. This mode can
be used along with logfile and listen settings.
setlisten0.0.0.0:514
Enables syslog server mode. With this option tenshi will bind to the specified address:port pair
and read messages acting like a syslog server. We always recommend to filter the port accordingly
and possibly use something like stunnel for encrypting the traffic. This mode can be used along
with logfile and fifo settings.
DYNAMICOPTIONS
These options are set each time the config file is read. tenshi reads its config file once on start-up
and whenever it receives a HUP.
setsleep5
The loop sleep time for the notification process. The value must be <= 60 seconds.
setlimit<numberoflines>
The maximum number of messages per hostname allowed in a report, any lines after the maximum will
be omitted and a warning included. If this option is omitted then no limit is applied.
setpager_limit<numberoflines>
The maximum number of messages per hostname allowed in pager friendly reports, any lines after the
maximum will be omitted. If this option is omitted then no limit is applied.
setlogprefix<regexp>
All valid syslog messages are parsed by default, while non-syslog ones are discarded unless the
special noprefix queue is set. This option allows one to define an additional valid prefix for
watching other type of logs. If the regexp is matched then the prefix is removed from the log and
the first grouped string is used for the hostname field. This may be specified multiple times to
watch many different non-syslog logs.
setmask______
The mask for strings enclosed by the grouping operators ( ). See the REGEXPDEFINITIONS section.
'set mask' on its own will set the mask to an empty string.
setmailserverlocalhost
The mail server to be contacted for sending out reports.
setmailtimeout10
The timeout in seconds for mail server reply.
setsubjecttenshireport
The subject of report emails, the queue name is always automatically appended.
sethidepid<on|off>
This option turns on automatic stripping of 'foo[1234]:' style PID strings from the start of log
lines i.e. 'foo[1234]:' becomes 'foo:'. This allows you to write regexps without worrying about
masking the PID. Bear in mind that any time you change this option you will need to re-write your
regex rules or they will not work. This option is disabled by default.
setfilter<queue><filterpath><arguments>
When this option is enabled all reports matching the specified queue will be passed as STDIN to
the specified filter, the resulting output is sent via smtp instead of the original report. The
full path of the filter application must be specified.
setcsv<cron_spec><filterpath><arguments>
This feature allows periodic reporting, using a five-field cron-style specification like the setqueue option, to the specified filter. The output is pre-formatted as CSV (Comma Separated Values)
with hostname,log,hits format. This feature was coded for using AfterGlow(http://afterglow.sf.net) as a filter and graphing tenshi output. Check the FAQ for sample usage.
setsort_order<descending|ascending>
The sorting order for reports. It can be either descending or ascending, the number of messages is
used as a key for sorting the log messages. The default order is ascending.
setresolve<on|off>
This option turns on resolution of the fully qualified domain name for the hostname passed along
with log messages and, if found, reports it along with the original one. This only affects reports
and not pager messages. The name resolution is cached in order to avoid re-resolving addresses
that have been seen already, you have to restart or HUP tenshi in order to flush the cache. This
option is disabled by default.
setthreshold<queue><count><regex>
This option can be used to discard lines from a report that have a count below the given
threshold. If a line matches the regex in the given queue but has fewer hits than count, it is
discarded and omitted from the report. Note that this matches on the content of the lines that
will actually appear in the report, in contrast to queue escalation which uses a count based on
the regex that is matched.
QUEUESOPTIONS
All messages are assigned to queues. Every queue is processed periodically according to its notification
interval. There are four default builtin queues, trash to which unwanted messages can be assigned (think
/dev/null), repeat which is used for smart repeat messages handling, group and group_host , see REGEXPDEFINITIONS for details. There's also a special noprefix queue, read further for details about it.
All queues are automatically flushed before shutdown when a SIGTERM is received. Please see section
SIGNALS for additional information.
The syntax is the following:
setqueue<queue_name><mail_from>[pager:]<mail_to><cron_spec>[<subject>]<queue_name>
The queue name. Can be any alphanumeric character string except for the builtin queues name.
<mail_from>
The mail sender for reports related to the queue.
<mail_to>
The mail recipient(s) for reports related to the queue. Multiple address can be specified,
separated by commas. Using the pager: prefix enables a pager friendly report.
[<cron_spec>]
This is a five-field cron-style specification for when the reports should be emailed. Ranges and
skip values are supported as per the de facto crontab syntax with a few exceptions. Please see
crontab man page for crontab syntax explanation. The supported day names are: Mon, Tue, Wed, Thu,
Fri, Sat, Sun. Monday is 1, Sunday 0 or 7. Supported month names are: Jan, Feb, Mar, Apr, May,
Jun, Jul, Aug, Sep, Oct, Nov, Dec. Day and Month names are not case sensitive. Additionally, 'now'
can be specified for immediate notifications.
<subject>
This is the subject for to use for email reports regarding this queue. If this isn't specified
then the default subject will be used.
The special noprefix queue can be used and defined like any other queue with the difference that it will
get all messages that don't match any configured prefix.
Examples:
set queue report tenshi@localhost sysadmin@localhost [0 9-17 * * *]
set queue report tenshi@localhost sysadmin@localhost [30 18 * * *]
set queue report tenshi@localhost sysadmin@localhost [*/10 * * * *]
set queue critical tenshi@localhost sysadmin@localhost,noc@localhost [now] CRITICAL WARNING -
set queue pager tenshi@localhost pager:sysadmin_pager@localhost,pager:noc_pager@localhost [now] ALERT
REGEXPDEFINITIONS
All valid syslog messages are matched against standard perl regexps, all regexps are defined with the
following syntax:
<queue_name>[,<queue_name>[:<escalation_number>]..]<regexp>
The regexps are evaluated in order so a matched message is not checked against the subsequent regexps.
Keep this in mind when assembling the configuration file. It's advisable to catch all messages by placing
an all matching regexp at the end of the configuration file. It's also good for performance having trash
rules not logically connected with other matching rules at the beginning of the section. Multiple queues
can be defined with a comma separated list, builtin queues cannot be used when using this syntax.
If an escalation number is provided for a queue, the matched message will only be placed into the queue
when <escalation_number> messages have matched the regexp. The queue will receive the message that
matched the regexp at the time of escalation, with a count equal to the escalation number. The count of
messages matching the regexp will be reset when the left most queue mentioned in the queue list is
mailed. The left most queue cannot have an escalation number unless it is the only queue listed. When the
number of messages that match the regexp reaches the greatest escalation number mentioned, escalation
will begin again into the escalation queues, modulus the greatest escalation number. For example, using
the queues `a,b:10,c:50', when 10 messages match the regexp, a message will go into b, when 50 match, one
will go into c. At 60, another will go into b, and at 100, another into c, 110 to b, 150 to c, and so on.
Escalation numbers must be positive integers greater than zero and must be listed in increasing order
from left to right. All queues without escalation numbers must be listed more left than the queues with
escalation numbers.
The standard grouping operators () can be used for string masking, literal "(" and ")" can be protected
with the standard quotation operator "\". There's a lot of documentation about regular expressions, a
good start could be perl perlre and perlretut manual pages.
You can also use the (?: ) operators to use groups without masking. This allows you to match, for
example, output from several programs in a similar format. There is an example of this below (the
sudo/su line).
The builtin queue repeat can be used for special handling of "last message repeated x times" style log
lines. When the assigned regexps are matched the line count for the last line received from the same host
is incremented by the first grouped string. Keep in mind that it is possible for syslog lines to be
received from remote hosts out of order. If this happens you should not use this feature because tenshi
will mis-report line counts.
The builtin queue group can be used to group sets of regex together to speed up line matching. If a line
fails to match a regex assigned to the group queue then tenshi will skip all the regex up until the next
group_end statement. Nested groups are allowed. An example of this is included below.
The builtin group_host queue can be used for selective hostname matching. Like the group queue it is also
terminated with the group_end statement. All regex definitions within that group will only apply if the
hostname associated to the log entries matches the regex passed to the group_host definition.
The regexps below assume hidepid is turned on. If you have it turned off then you will need to add in
\[(.+)\] to the regex following the program name to get them to work.
For example: mail ^sendmail: (.+): to=(.+),(.+)delay=(.+) becomes: mail ^sendmail\[(.+)\]: (.+):
to=(.+),(.+)delay=(.+)
Examples:
trash ^xinetd
repeat ^(?:last message repeated|above message repeats) (\d+) time
group ^sendmail:
mail ^sendmail: (.+): to=(.+),(.+)delay=(.+)
mail ^sendmail: (.+): to=(.+),(.+)relay=(.+),(.+)stat=Sent
group_end
group_host mailserver1
mail1 ^sendmail
mail1 ^sendmail:.+
critical,mail1 ^sendmail:.+SYSERR.+
group_end
mail ^ipop3d: Login user=(.+)
critical,report ^sshd: Illegal user
general,urgent:200,critical:1000 ^sshd: Illegal user
root ^sshd\(pam_unix\): session opened for user root by root\(uid=0\)
report ^sshd: Accepted rsa for (.+) from (.+) port (.+)
trash ^sshd
critical ^(?:sudo|su):
critical,pager ^Oops
misc .*
Install Now
PNG Icons
Emojis
SVG Icons