1FETCHLOG(1)                 General Commands Manual                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',  '.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

OPTIONS

32       -f     do not update bookmark in bookmarkfile.
33
34       -F     update bookmark in bookmarkfile : set bookmark to the very  last
35              line fetched from logfile
36
37       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
41       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
45       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
49       conv   Conversion: one ore more of characters 'bpsno'.
50
51              b  [brackets]  convert  '<' and '>' to '(' and ')' for safe HTML
52              output.
53
54              p [percent] convert '%'  to 'p' for safe printf(1) output.
55
56              s [shell] convert '$', '^', and  the  three  quotes  (backquote,
57              doublequote, singlequote) to '_' and '\' to '/'. This conversion
58              is useful when passing the result of fetchlog to a shell command
59              as a parameter.
60
61              n [newline] convert newline characters to '\n' sequence to get a
62              single line of output.
63
64              o [ok message] Show 'OK: no messages' if  no  new  messages  are
65              available for output.
66
67       logfile
68              Absolute  path  to the unrotated logfile to fetch data from. The
69              user needs read access to logfile.
70
71       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
77              If  bookmarkfile does not exist fetchlog assumes an infinite old
78              bookmark.
79
80       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
89
90       -h     print help message
91
92       -V     print version
93

MULTIPLE FETCHING

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

PERFORMANCE

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

NAGIOS

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
120       When  using  fetchlog  as  a local plugin for Nagios then return
121       status is as follows:
122
123       OK     No new messages in logfile where found. The  single  line
124              'OK: no messages' will be send to stdout.
125
126       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
131       CRITICAL
132              New  messages  in logfile where found. A single line with
133              the last new messages will be send to stdout.
134
135       UNKNOWN
136              fetchlog was called with wrong  parameters.  A  multiline
137              usage message is send to stdout.
138
139       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

SNMP

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

COMPRESSING OUTPUT

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

DIAGNOSTICS

167       fetchlog sends all output and error  messages  to  stdout.  Exit
168       codes:
169
170       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
174       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
181       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
186       3      fetchlog  was  called  with wrong parameters, a multiline
187              usage message is print to stdout.
188
189       Note: Since version 0.93 the meanings of exit code 1 and 2  have
190       been exchanged.
191

AUTHOR

193       Alexander Haderer, Radiology Department, Charite Berlin
194

SEE ALSO

196       tail(1),  cat(1),  head(1),  sed(1),  re_format(7),  syslogd(8),
197       newsyslog(8)
198
199       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
203       Nagios - A Network monitoring system
204       http://www.nagios.org
205
206       Nagios Plugins - Plugins for Nagios
207       http://nagiosplug.sourceforge.net
208
209       fetchlog homepage - download, support and bugtracking
210       http://fetchlog.sourceforge.net
211

BUGS

213       Bookmarkfiles  are  not  portable  across plattforms or fetchlog
214       versions.
215
216       Logfiles are expected not to shrink.
217
218       fetchlog does not work with compressed logfiles.
219
220       Fetching when logfile rotation takes place may  result  in  some
221       messages to appear twice.
222
223       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.
228
229Charite                        26 Mar 2004 (1.0)                   FETCHLOG(1)
Impressum