README.md
1tenshi
2======
3
4tenshi 0.17 README
5Copyright 2004-2017 Andrea Barisani <andrea@inversepath.com>
6
7Introduction
8============
9
10tenshi is a log monitoring program, designed to watch one or more log files for
11lines matching user defined regular expressions and report on the matches. The
12regular expressions are assigned to queues which have an alert interval and a
13list of mail recipients.
14
15Please read the example `tenshi.conf` and `tenshi.8` man page for usage
16instructions.
17
18tenshi was formerly known as wasabi. The name was changed to tenshi after we
19were informed that wasabi is a registered trademark relating to another piece
20of software.
21
22It should be noted that tenshi was initially a perl rewrite of Oak
23(http://www.ktools.org).
24
25Installation
26============
27
28To install tenshi, add a user and group named `tenshi`. As root:
29
30```
31$ make install
32```
33
34Please read the manual before running tenshi to make sure you understand its
35operation and that you satisfy the REQUIREMENTS section. Then edit the
36configuration file `/etc/tenshi/tenshi.conf` according to your preferences.
37
38Examples init scripts for OpenRC (Gentoo) and Debian are provided.
39
40Examples
41========
42
43Consider the following settings in `tenshi.conf`:
44
45```
46set hidepid on
47
48set queue mail tenshi@localhost sysadmin@localhost [0 */12 * * *]
49set queue misc tenshi@localhost sysadmin@localhost [0 */24 * * *]
50set queue critical tenshi@localhost sysadmin@localhost [now]
51
52group ^ipop3d:
53
54mail ^ipop3d: Login user=(.+)
55mail ^ipop3d: Logout user=(.+)
56mail ^ipop3d: pop3s SSL service init from (.+)
57mail ^ipop3d: pop3 service init from (.+)
58mail ^ipop3d: Command stream end of file, while reading.+
59mail ^ipop3d: Command stream end of file while reading.+
60
61critical ^ipop3d: Login failed.+
62
63trash ^ipop3d:.+
64
65group_end
66
67critical ^sudo: (.+) : TTY=(.+) ; PWD=(.+) ; USER=root ; COMMAND=(.+)
68
69misc .*
70```
71
72Every ipop3d message not matched by the regexps assigned to the queue mail or
73critical will be matched by the queue trash (a builtin null queue), any other
74message will be matched by queue misc. Fields enclosed in (.+) are masked.
75
76This is a sample report for the mail queue (sent every 12 hours):
77
78```
79host1:
80 79: ipop3d: Login user=___
81 74: ipop3d: Logout user=___
82
83host2:
84 30: ipop3d: Login user=___
85 30: ipop3d: Logout user=___
86 19: ipop3d: pop3 service init from ___
87 12: ipop3d: pop3s SSL service init from ___
88 1: ipop3d: Command stream end of file while reading line user=??? host=bogus.domain.net [192.168.0.1]
89 1: ipop3d: Command stream end of file, while reading authentication host=bogus1.domain.net [10.1.7.1]
90```
91
92These are sample reports for the critical queue (sent every time a message
93matches the regexp):
94
95```
96host1:
97 1: /usr/bin/sudo: ___ : TTY=___ ; PWD=___ ; USER=root ; COMMAND=/bin/dmesg
98
99host1:
100 1: /usr/bin/sudo: ___ : TTY=___ ; PWD=___ ; USER=root ; COMMAND=/bin/bash
101
102host2:
103 1: ipop3d: Login failed user=admin auth=admin host=bogus1.domain.net [10.1.7.1]
104
105host2:
106 1: ipop3d: Autologout user=??? host=bogus.domain.net [192.168.0.1]
107```
108
109Requirements
110============
111
112 * Perl.
113
114 * A working `tail` implementation, when using the logfile option.
115
116 * The Net::SMTP perl module to mail reports, typically included in perl
117 installations.
118
119 * The IO::BufferedSelect perl module.
120
121 * The Redis perl module, when using the redisqueue option.
122
123Any missing module can be downloaded from CPAN (http://www.cpan.org) or
124installed using the CPAN shell (`perl -e shell -MCPAN`).
125
126Resources
127=========
128
129The tenshi repository is hosted at https://github.com/inversepath/tenshi
130
131Please report any bugs you find at <andrea@inversepath.com>.
132