1fetchlog(1) fetchlog documentation fetchlog(1)
2
6 fetchlog - fetch and convert new messages of a logfile
7
9 fetchlog -f first:last:len:conv logfile bookmarkfile [ pattern .. ]
10 fetchlog -F first:last:len:conv logfile bookmarkfile [ pattern .. ]
12 fetchlog [-h|-V]
14
16 The fetchlog utility displays the last new messages of a logfile. It is
17 similar like tail(1) but offers some extra functionality for output
18 formatting. To show only the new messages appeared since the last call
19 fetchlog uses a bookmark to remember which messages have been fetched.
20 fetchlog scans backwards logfile and collects all messages, optionally
22 only those matching any of the given regex-style patterns. Then
23 fetchlog converts found message lines for output. It stops scanning
24 when one of these conditions become true: The bookmark from bookmark‐
25 file is reached, or len characters are ready for output, or an error
26 occurs. fetchlog knows about rotated and uncompressed logfiles and
27 continues scanning in rotated logfiles by appending '.0', '.1' upto
28 '.9' to logfile when scanning in rotated logfiles. Scanning stops with‐
29 out error when a rotated logfile does not exist.
30
32 -f do not update bookmark in bookmarkfile.
33 -F update bookmark in bookmarkfile : set bookmark to the very last
35 line fetched from logfile
36 first The first column of text fetchlog will read from logfile. Lines
38 shorter than first will be show up as a single newline. The col‐
39 umn count starts with 1.
40 last The maximum last column fetchlog will read from logfile. Lines
42 longer than last will be cut off and a `~` will be set at column
43 last for output. The column count starts with 1.
44 len The maximum number of characters fetchlog will output. If more
46 than len characters are available after cutting and conversion,
47 the first line put out will start with '...'.
48 conv Conversion: one ore more of characters 'bpsno'.
50 b [brackets] convert '<' and '>' to '(' and ')' for safe HTML
52 output.
53 p [percent] convert '%' to 'p' for safe printf(1) output.
55 s [shell] convert '$', '^', and the three quotes (backquote,
57 doublequote, singlequote) and '|' to '_' and '\' to '/'. This
58 conversion is useful when passing the result of fetchlog to a
59 shell command as a parameter.
60 n [newline] convert newline characters to '\n' sequence to get a
62 single line of output.
63 o [ok message] Show 'OK: no messages' if no new messages are
65 available for output.
66 logfile
68 Absolute path to the unrotated logfile to fetch data from. The
69 user needs read access to logfile.
70 bookmarkfile
72 Absolute path to the file holding the bookmark. The user needs
73 read access to the file when using option -f and write access
74 plus permission to create files in the directory of bookarkfile
75 when using option -F (update bookmark).
76 If bookmarkfile does not exist fetchlog assumes an infinite old
78 bookmark.
79 pattern
81 A extended regular expression pattern, see re_format(7) for
82 details. If one or more pattern are defined, fetchlog will only
83 pick lines where any of these pattern match. Pattern matching is
84 done after trimming the lines with respect to first and last and
85 before any conversions takes place. In other words: pattern
86 matching operates on data that fetchlog shows when no conversion
87 is set.
88 -h print help message
91 -V print version
93
95 Fetching the same logfile with different bookmarks works without
96 problem. Simultanously fetching with option -F (update mode)
97 using the same bookmark file works too, but unpredictable
98 results will occur. For safety reasons bookmarkfile will never
99 be opened for writing directly, instead a temporary file will be
100 used and renamed to bookmarkfile when writing has finished.
101
103 Before opening logfiles for scanning fetchlog first checks the
104 modification time of logfile and compares this time with the
105 modification time stored in bookmarkfile. If both timestamps
106 are the same then fetchlog exits with 0 (no messages). Other‐
107 wise the logfile(s) get mapped to memory step by step and are
108 scanned backwards line by line until one of the end conditions
109 become true. fetchlog uses the logfiles inode to distinguish
110 different logs.
111
113 fetchlog may be used as a local plugin for the Nagios network
114 monitoring system to monitor a local logfile. It follows the
115 calling convention for Nagios plugins if at least conversions on
116 are set and len is 'short' enough for Nagios. It is recommended
117 to use conversion s also because shell metacharacters in fetched
118 messages may confuse Nagios' notification system.
119 When using fetchlog as a local plugin for Nagios then return
121 status is as follows:
122 OK No new messages in logfile where found. The single line
124 'OK: no messages' will be send to stdout.
125 WARNING
127 fetchlog detected an internal error while fetching. A one
128 line error message starting with 'ERROR: fetchlog:' is
129 send to stdout.
130 CRITICAL
132 New messages in logfile where found. A single line with
133 the last new messages will be send to stdout.
134 UNKNOWN
136 fetchlog was called with wrong parameters. A multiline
137 usage message is send to stdout.
138 Nagios can monitor remote logfiles together with NET-SNMP and
140 fetchlog using the check-snmp plugin. Please read the README
141 files coming with fetchlog how to setup this.
142
144 The motivation for fetchlog was to create a helper tool for NET-
145 SNMP's snmpd to enable monitoring of remote kernel syslogs using
146 SNMP. If configured properly, snmpd replies to a specific SNMP
147 request with the output of an external helper program. With
148 fetchlog using update mode -F and conversions on one can peek at
149 a remote syslog file and gets either 'OK: no messages' or one
150 line with the new syslog messages appeared since the last SNMP
151 request.
152 Because of some limitiations of SNMP itself and the monitoring
154 applications using SNMP, the length of the SNMP reply must not
155 exceed a specific size. To ease the integration of SNMP in moni‐
156 toring software it is useful to have the SNMP reply only consist
157 of a single line of text rather than multiple lines.
158
160 The syslog messages fetched can be compressed by increasing
161 first to skip the timestamp and host entry from syslog. Lower‐
162 ing last gives even more compression for long syslog lines. As a
163 result one gets a very short message that gives an idea of what
164 is going wrong.
165
167 fetchlog sends all output and error messages to stdout. Exit
168 codes:
169 0 No new messages in logfile were found. If conversion o is
171 set, the single line 'OK: no messages' will be send to
172 stdout.
173 1 An internal error in fetchlog occured. A one line error
175 message will be send to stdout. The error message starts
176 with 'ERROR: fetchlog:' and shows detailed information
177 about what went wrong. Length limitation by parameter len
178 is applied, if an error message is too long the last part
179 will be cut off and a '~' is appended.
180 2 New messages in logfile were found. The new messages will
182 be send to stdout. If conversion n is set, a single line
183 of text is send, else zero or more lines of converted
184 syslog messages are send.
185 3 fetchlog was called with wrong parameters, a multiline
187 usage message is print to stdout.
188 Note: Since version 0.93 the meanings of exit code 1 and 2 have
190 been exchanged.
191
193 Alexander Haderer, LoeScap Technology GmbH, Berlin - Germany
194
196 tail(1), cat(1), head(1), sed(1), re_format(7), syslogd(8),
197 newsyslog(8)
198 NET-SNMP - Various tools relating to the Simple Network Manage‐
200 ment Protocol SNMP (NET-SNMP: formerly known as UCD-SNMP)
201 http://www.net-snmp.org
202 Nagios - A Network monitoring system
204 http://www.nagios.org
205 Nagios Plugins - Plugins for Nagios
207 http://nagiosplug.sourceforge.net
208 fetchlog homepage - download, support and bugtracking
210 http://fetchlog.sourceforge.net
211
213 Bookmarkfiles are not portable across plattforms or fetchlog
214 versions.
215 Logfiles are expected not to shrink.
217 fetchlog does not work with compressed logfiles.
219 Fetching when logfile rotation takes place may result in some
221 messages to appear twice.
222 If an regex error occurs during pattern matching this error is
224 silently ignored and will be handled as non-match.
225
227 Nagios is a registered trademark of Ethan Galstad.
228fetchlog(1) 23 Nov 2008 (1.2) fetchlog(1)