1fetchlog(1)                 fetchlog documentation                 fetchlog(1)
2
3
4

NAME

6       fetchlog - fetch and convert new messages of a logfile
7

SYNOPSIS

9       fetchlog -f first:last:len:conv logfile bookmarkfile [ pattern ..  ]
10
11       fetchlog -F first:last:len:conv logfile bookmarkfile [ pattern ..  ]
12
13       fetchlog [-h|-V]
14

DESCRIPTION

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
21       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

OPTIONS

33       -f     do not update bookmark in bookmarkfile.
34
35       -F     update  bookmark in bookmarkfile : set bookmark to the very last
36              line fetched from logfile
37
38       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
42       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
46       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
50       conv   Conversion: one ore more of characters 'bpsno3'.
51
52              b [brackets] convert '<' and '>' to '(' and ')'  for  safe  HTML
53              output.
54
55              p [percent] convert '%'  to 'p' for safe printf(1) output.
56
57              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
62              n [newline] convert newline characters to '\n' sequence to get a
63              single line of output.
64
65              o  [ok  message]  Show  'OK: no messages' if no new messages are
66              available for output.
67
68              3 [Nagios3] output in  multiline  format  required  for  plugins
69              since Nagios3.
70
71       logfile
72              Absolute  path  to the unrotated logfile to fetch data from. The
73              user needs read access to logfile.
74
75       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
81              If  bookmarkfile does not exist fetchlog assumes an infinite old
82              bookmark.
83
84       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
93
94       -h     print help message
95
96       -V     print version
97

MULTIPLE FETCHING

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

PERFORMANCE

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

NAGIOS

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
125       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
133       When using fetchlog as a local plugin for Nagios then exit  sta‐
134       tus is as follows:
135
136       OK     No  new  messages in logfile where found. The single line
137              'OK: no messages' will be send to stdout.
138
139       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
144       CRITICAL
145              New messages in logfile where found. A single  line  with
146              the last new messages will be send to stdout.
147
148       UNKNOWN
149              fetchlog  was  called  with wrong parameters. A multiline
150              usage message is send to stdout.
151
152       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

SNMP

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
166       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

COMPRESSING OUTPUT

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

DIAGNOSTICS

180       fetchlog  sends  all  output  and error messages to stdout. Exit
181       codes:
182
183       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
187       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
194       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
199       3      fetchlog was called with wrong  parameters,  a  multiline
200              usage message is print to stdout.
201
202       Note:  Since version 0.93 the meanings of exit code 1 and 2 have
203       been exchanged.
204

AUTHOR

206       Alexander Haderer, LoeScap Technology GmbH, Berlin - Germany
207

SEE ALSO

209       tail(1),  cat(1),  head(1),  sed(1),  re_format(7),  syslogd(8),
210       newsyslog(8)
211
212       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
216       Nagios - A Network monitoring system
217       http://www.nagios.org
218
219       Nagios Plugins - Plugins for Nagios
220       http://nagiosplug.sourceforge.net
221
222       fetchlog homepage - download, support and bugtracking
223       http://fetchlog.sourceforge.net
224

BUGS

226       Bookmarkfiles are not portable  across  plattforms  or  fetchlog
227       versions.
228
229       Logfiles are expected not to shrink.
230
231       fetchlog does not work with compressed logfiles.
232
233       Fetching  when  logfile  rotation takes place may result in some
234       messages to appear twice.
235
236       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.
241
242fetchlog(1)                    23 Nov 2008 (1.2)                   fetchlog(1)
Impressum