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', if that file
28 does not exist '.1', then upto '.9' to logfile when scanning in rotated
29 logfiles. Scanning stops without error when a rotated logfile does not
30 exist.
31
33 -f do not update bookmark in bookmarkfile.
34 -F update bookmark in bookmarkfile : set bookmark to the very last
36 line fetched from logfile
37 first The first column of text fetchlog will read from logfile. Lines
39 shorter than first will be show up as a single newline. The col‐
40 umn count starts with 1.
41 last The maximum last column fetchlog will read from logfile. Lines
43 longer than last will be cut off and a `~` will be set at column
44 last for output. The column count starts with 1.
45 len The maximum number of characters fetchlog will output. If more
47 than len characters are available after cutting and conversion,
48 the first line put out will start with '...'.
49 conv Conversion: one ore more of characters 'bpsno3'.
51 b [brackets] convert '<' and '>' to '(' and ')' for safe HTML
53 output.
54 p [percent] convert '%' to 'p' for safe printf(1) output.
56 s [shell] convert '$', '^', and the three quotes (backquote,
58 doublequote, singlequote) and '|' to '_' and '\' to '/'. This
59 conversion is useful when passing the result of fetchlog to a
60 shell command as a parameter.
61 n [newline] convert newline characters to '\n' sequence to get a
63 single line of output.
64 o [ok message] Show 'OK: no messages' if no new messages are
66 available for output.
67 3 [Nagios3] output in multiline format required for plugins
69 since Nagios3.
70 logfile
72 Absolute path to the unrotated logfile to fetch data from. The
73 user needs read access to logfile.
74 bookmarkfile
76 Absolute path to the file holding the bookmark. The user needs
77 read access to the file when using option -f and write access
78 plus permission to create files in the directory of bookarkfile
79 when using option -F (update bookmark).
80 If bookmarkfile does not exist fetchlog assumes an infinite old
82 bookmark.
83 pattern
85 A extended regular expression pattern, see re_format(7) for
86 details. If one or more pattern are defined, fetchlog will only
87 pick lines where any of these pattern match. Pattern matching is
88 done after trimming the lines with respect to first and last and
89 before any conversions takes place. In other words: pattern
90 matching operates on data that fetchlog shows when no conversion
91 is set.
92 -h print help message
95 -V print version
97
99 Fetching the same logfile with different bookmarks works without
100 problem. Simultanously fetching with option -F (update mode)
101 using the same bookmark file works too, but unpredictable
102 results will occur. For safety reasons bookmarkfile will never
103 be opened for writing directly, instead a temporary file will be
104 used and renamed to bookmarkfile when writing has finished.
105
107 Before opening logfiles for scanning fetchlog first checks the
108 modification time of logfile and compares this time with the
109 modification time stored in bookmarkfile. If both timestamps
110 are the same then fetchlog exits with 0 (no messages). Other‐
111 wise the logfile(s) get mapped to memory step by step and are
112 scanned backwards line by line until one of the end conditions
113 become true. fetchlog uses the logfiles inode to distinguish
114 different logs.
115
117 fetchlog may be used as a local plugin for the Nagios network
118 monitoring system to monitor a local logfile. It follows the
119 calling convention for Nagios plugins if at least conversions on
120 are set and len is 'short' enough for Nagios (330 prior to
121 Nagios 3, 4000 since Nagios 3). It is recommended to use con‐
122 version s also because shell metacharacters in fetched messages
123 may confuse Nagios' notification system.
124 Nagios 3 introduces a new interface for plugins sending out mul‐
126 tiline output as fetchlog does. Even with conversion 'n' Nagios
127 reads this as a multiline message. To be compatible with Nagios
128 3 plugin format enable conversion '3' also. Output format is
129 then: SHORT_MESSAGE|\nMESSAGE_LINE_1\n...\nMESSAGE_LINE_N where
130 SHORT_MESSAGE will be the last line fetched MESSAGE_LINE_N.
131 Please see README.Nagios for details.
132 When using fetchlog as a local plugin for Nagios then exit sta‐
134 tus is as follows:
135 OK No new messages in logfile where found. The single line
137 'OK: no messages' will be send to stdout.
138 WARNING
140 fetchlog detected an internal error while fetching. A one
141 line error message starting with 'ERROR: fetchlog:' is
142 send to stdout.
143 CRITICAL
145 New messages in logfile where found. A single line with
146 the last new messages will be send to stdout.
147 UNKNOWN
149 fetchlog was called with wrong parameters. A multiline
150 usage message is send to stdout.
151 Nagios can monitor remote logfiles together with NET-SNMP and
153 fetchlog using the check-snmp plugin. Please read the README
154 files coming with fetchlog how to setup this.
155
157 The motivation for fetchlog was to create a helper tool for NET-
158 SNMP's snmpd to enable monitoring of remote kernel syslogs using
159 SNMP. If configured properly, snmpd replies to a specific SNMP
160 request with the output of an external helper program. With
161 fetchlog using update mode -F and conversions on one can peek at
162 a remote syslog file and gets either 'OK: no messages' or one
163 line with the new syslog messages appeared since the last SNMP
164 request.
165 Because of some limitiations of SNMP itself and the monitoring
167 applications using SNMP, the length of the SNMP reply must not
168 exceed a specific size. To ease the integration of SNMP in moni‐
169 toring software it is useful to have the SNMP reply only consist
170 of a single line of text rather than multiple lines.
171
173 The syslog messages fetched can be compressed by increasing
174 first to skip the timestamp and host entry from syslog. Lower‐
175 ing last gives even more compression for long syslog lines. As a
176 result one gets a very short message that gives an idea of what
177 is going wrong.
178
180 fetchlog sends all output and error messages to stdout. Exit
181 codes:
182 0 No new messages in logfile were found. If conversion o is
184 set, the single line 'OK: no messages' will be send to
185 stdout.
186 1 An internal error in fetchlog occured. A one line error
188 message will be send to stdout. The error message starts
189 with 'ERROR: fetchlog:' and shows detailed information
190 about what went wrong. Length limitation by parameter len
191 is applied, if an error message is too long the last part
192 will be cut off and a '~' is appended.
193 2 New messages in logfile were found. The new messages will
195 be send to stdout. If conversion n is set, a single line
196 of text is send, else zero or more lines of converted
197 syslog messages are send.
198 3 fetchlog was called with wrong parameters, a multiline
200 usage message is print to stdout.
201 Note: Since version 0.93 the meanings of exit code 1 and 2 have
203 been exchanged.
204
206 Alexander Haderer, LoeScap Technology GmbH, Berlin - Germany
207
209 tail(1), cat(1), head(1), sed(1), re_format(7), syslogd(8),
210 newsyslog(8)
211 NET-SNMP - Various tools relating to the Simple Network Manage‐
213 ment Protocol SNMP (NET-SNMP: formerly known as UCD-SNMP)
214 http://www.net-snmp.org
215 Nagios - A Network monitoring system
217 http://www.nagios.org
218 Nagios Plugins - Plugins for Nagios
220 http://nagiosplug.sourceforge.net
221 fetchlog homepage - download, support and bugtracking
223 http://fetchlog.sourceforge.net
224
226 Bookmarkfiles are not portable across plattforms or fetchlog
227 versions.
228 Logfiles are expected not to shrink.
230 fetchlog does not work with compressed logfiles.
232 Fetching when logfile rotation takes place may result in some
234 messages to appear twice.
235 If an regex error occurs during pattern matching this error is
237 silently ignored and will be handled as non-match.
238
240 Nagios is a registered trademark of Ethan Galstad.
241fetchlog(1) 23 Nov 2008 (1.2) fetchlog(1)