1
by Willi Mann
Import upstream version 5.1 |
1 |
First of all, each filter must process data from one or more "Logfile |
2 |
Group". |
|
3 |
||
4 |
***********************************************
|
|
5 |
* Logfile Groups |
|
6 |
***********************************************
|
|
7 |
||
8 |
Logfile groups are defined by a configuration file in |
|
9 |
/etc/log.d/conf/logfiles named <logfile_group_name>.conf. It is usually |
|
10 |
easier to copy an existing logfile group configuration than it is to create |
|
11 |
a brand new one. |
|
12 |
||
13 |
There is only one required line in the logfile group config file. This |
|
14 |
command is called 'LogFile'. |
|
15 |
||
16 |
# This will be the logfile named 'messages' in the default logfile
|
|
17 |
# directory (probably /var/log).
|
|
18 |
LogFile = messages |
|
19 |
||
20 |
# You can also give this command with an absolute path, like this:
|
|
21 |
LogFile = /var/log/messages |
|
22 |
||
23 |
You can have as many LogFile entries as you wish. All the files specified |
|
24 |
will be merged into one input stream for any filters that use this logfile |
|
25 |
group. You can also use standard wildcards when you specify the filename. |
|
26 |
||
27 |
Another command that is optional is called 'Archive'. You can specify a |
|
28 |
file to also include in the data stream if the '--archives' option is used. |
|
29 |
If these files do not exist it is okay. For example: |
|
30 |
||
31 |
# These 2 'Archive' entries will allow users of most Red Hat Linux
|
|
32 |
# systems to access their archives of the 'messages' logfile:
|
|
33 |
Archive = messages.? |
|
34 |
# If they configure Compression to be on in /etc/logrotate.conf:
|
|
35 |
Archive = messages.?.gz |
|
36 |
# It is best just to include both of these so that the logfile group
|
|
37 |
# will work for most systems.
|
|
38 |
||
39 |
Now, the general theory is that the LogFile Group should apply the date |
|
40 |
range requested. If the logfile is in the standard syslog format, you can |
|
41 |
use the shared script 'ApplyStdDate' to filter out only the appropriate log |
|
42 |
entries. The way to call shared scripts (located in |
|
43 |
/etc/log.d/scripts/shared) is: |
|
44 |
||
45 |
*ApplyStdDate = |
|
46 |
||
47 |
Anything following the equal sign will be passed to the program as arguments |
|
48 |
(the equal sign can be eliminated if no arguments are needed). You should |
|
49 |
look at the current logfile group config files for examples. |
|
50 |
||
51 |
Finally, if the directory /etc/log.d/scripts/logfiles/<logfile_group_name>/ |
|
52 |
exists, any scripts in that directory will be executed. All of these |
|
53 |
scripts take the contents of all the specified logfiles in through STDIN and |
|
54 |
output the modified logfile trought STDOUT. These scripts can be written in |
|
55 |
any language that can be executed on your system. |
|
56 |
||
57 |
***********************************************
|
|
58 |
* Service Filter Configuration File |
|
59 |
***********************************************
|
|
60 |
||
61 |
Okay, once you have defined one or more logfile groups (or decided on one or |
|
62 |
more existing logfile groups), you need to define your service filter. |
|
63 |
||
64 |
This file needs to be in /etc/log.d/conf/services/ and it needs to be named |
|
65 |
service.conf. You should probably copy an existing config for another |
|
66 |
service to create a new one. |
|
67 |
||
68 |
There is only one required line. This is the command 'LogFile'. The |
|
69 |
LogFile command allows you to specify one or more *LogFile Groups* (as |
|
70 |
described above) that this filter will process. Remember, any filter can |
|
71 |
process any number of LogFile Groups, and any LogFile Group may contain the |
|
72 |
data from any number of logfiles (and archives). |
|
73 |
||
74 |
For a service filter that needs messages from /var/log/messages you would |
|
75 |
add this line: |
|
76 |
||
77 |
LogFile = messages |
|
78 |
||
79 |
NOTE: This is *not* because the name of the logfile is 'messages', but it |
|
80 |
is because the name of the LogFile Group that has been defined is |
|
81 |
'messages'. |
|
82 |
||
83 |
You can have commands in the form of: |
|
84 |
||
85 |
*SharedScriptName = Arguments |
|
86 |
||
87 |
that will execute a script found in the /etc/log.d/scripts/shared/ |
|
88 |
directory named 'SharedScriptName' with arguments 'Arguments'. |
|
89 |
This filter will modify the input to the service's filter. |
|
90 |
||
91 |
You can also have commands in the form: |
|
92 |
||
93 |
$EnvironmentVariable = Value |
|
94 |
||
95 |
This command will set the 'EnvironmentVariable' environment variable to the |
|
96 |
value 'Value'. This environment variable will be accessable by your filter |
|
97 |
program. |
|
98 |
||
99 |
You will also usually want to specify a title for your script (new in |
|
100 |
Logwatch 4.0). If specified, then a start and stop delimiter will be added |
|
101 |
by Logwatch for your specific service (with your script's output between |
|
102 |
those delimiters). This will *only* happen if you produce output. If you |
|
103 |
produce no output, the headers will not be created. Here is how you define |
|
104 |
your title: |
|
105 |
||
106 |
Title = "My Service Title" |
|
107 |
||
108 |
***********************************************
|
|
109 |
* Service Filter Executable |
|
110 |
***********************************************
|
|
111 |
||
112 |
Once everything above has been done, you are ready to actually write |
|
113 |
your filter. This can be done in any language as all it does is: |
|
114 |
1) Read logfile entries from STDIN |
|
115 |
2) Access some environment variables |
|
116 |
3) Generate a report on STDOUT |
|
117 |
||
118 |
Before you try to write a filter, you should create the filter and make its |
|
119 |
contents the test script given below. The filter needs to be located in |
|
120 |
/etc/log.d/scripts/services/ and named service (because you named the |
|
121 |
config file service.conf). |
|
122 |
||
123 |
###################### Cut Here #########################
|
|
124 |
#!/bin/bash
|
|
125 |
# This is as nice script that will show you the lines you will
|
|
126 |
# be processing and reporting on. It will first display the
|
|
127 |
# standard environment variables and then it takes STDIN and
|
|
128 |
# dump it right back out to STDOUT.
|
|
129 |
||
130 |
# These are the standard environment variables. You can define
|
|
131 |
# more in your service config file (see above).
|
|
132 |
echo "Date Range: $LOGWATCH_DATE_RANGE" |
|
133 |
echo "Detail Level: $LOGWATCH_DETAIL_LEVEL" |
|
134 |
echo "Temp Dir: $LOGWATCH_TEMP_DIR" |
|
135 |
echo "Debug Level: $LOGWATCH_DEBUG" |
|
136 |
||
137 |
# Now take STDIN and dump it to STDOUT
|
|
138 |
cat
|
|
139 |
###################### Cut Here #########################
|
|
140 |
||
141 |
If you temorarily replace a script such as 'pam' with the above, you will |
|
142 |
notice that much has been cut out of /var/log/messages before it gets to |
|
143 |
this filter. |
|
144 |
||
145 |
The value of the environment variable LOGWATCH_DETAIL_LEVEL can be any |
|
146 |
integer. In reality, it is usually 0 (for low), 5 (for medium), and 10 |
|
147 |
(for high). |
|
148 |
||
149 |
Your script should only produce output as appropriate. If there are no |
|
150 |
relevant log entries, no output should be produced. Likewise, if you are |
|
151 |
reporting two things, such as "Good Logins" and "Bad Logins", you should |
|
152 |
only produce even the headers when appropriate. For example: |
|
153 |
||
154 |
Bad Logins: |
|
155 |
amber (2 time(s)) |
|
156 |
kirk (3 time(s)) |
|
157 |
||
158 |
Good Logins: |
|
159 |
amber (5 time(s)) |
|
160 |
kirk (10 time(s)) |
|
161 |
||
162 |
But, if no failed logins occur, you should only output: |
|
163 |
||
164 |
Good Logins: |
|
165 |
amber (5 time(s)) |
|
166 |
kirk (10 time(s)) |
|
167 |
||
168 |
Note that there is no "Bad Logins:" header as there were no bad logins. You |
|
169 |
should also use the detail environment variable when deciding what to |
|
170 |
output. Bad logins might always be displayed, but good logins might only be |
|
171 |
displayed at higher detail levels. Here is a guide on how you should |
|
172 |
use the detail setting: |
|
173 |
||
174 |
0 (Low): Display only errors and security-related issues |
|
175 |
5 (Med): Display anything that a typical administator would be interested in |
|
176 |
10 (High): Display anything that a paranoid administrator would want to see |
|
177 |
||
178 |
In some cases, you can use a security setting higher than 10. This would be |
|
179 |
reserved for information so trivial that it would not even interest the US |
|
180 |
Government. |
|
181 |