1 04/04/86  monitor_sys_log, msl
  2 
  3 Syntax as a command:  msl {log_selector} {-control_args}
  4 
  5 
  6 Function: monitors activity in system logs.  Contents of the selected
  7 logs are periodically examined, and any new messages are printed on the
  8 terminal or passed as arguments to a specified command line.  Control
  9 arguments determine what action the command performs, and also supply
 10 message selection and formatting options.
 11 
 12 
 13 There are three types of control arguments--log selection, action, and
 14 monitoring control arguments.  Only one action control argument may be
 15 specified in any given invocation of the command.  For all actions
 16 (except -status), a log must be specified; for some actions (-update,
 17 -on, -off, -remove, -status), -all may be specified to select the log,
 18 indicating that the action applies to all logs currently being
 19 monitored.  All other control arguments specify monitoring operations:
 20 message selection, message processing, message format.  A separate set
 21 of monitoring options is kept for each log being monitored.  A specific
 22 log may be monitored more than once, by specifying -add to establish
 23 separate monitors; this is useful when different sets of monitoring
 24 options are desired to process messages from the same log differently.
 25 
 26 
 27 Arguments:
 28 log_selector
 29    is the pathname of a log to be monitored.  The pathname must specify
 30    the first segment in a log.  This argument is incompatible with any
 31    of the log selection control arguments.
 32 
 33    If a log is selected, either by pathname or one of the control
 34    arguments below, and no "action" is specified, monitoring is started
 35    or updated, as appropriate (see -update, below).  To replace the
 36    monitor information for a log, or start an independent monitor with
 37    different parameters, -replace or -add must be specified.  For all
 38    actions except -status, either a log pathname or a log selection
 39    control argument must be specified.
 40 
 41 
 42 Control arguments (log selection):
 43 -admin
 44    specifies that the admin log is to be examined.  The admin log is
 45    called "admin_log", and is located in the >sc1>as_logs directory.
 46    This argument is incompatible with any of the other log selection
 47    control arguments, or an explicit log pathname.
 48 -all, -a
 49    specifies that the monitor information for all logs is to be
 50    changed.  This argument is incompatible with any of the other log
 51    selection control arguments, or an explicit log pathname.
 52 
 53 
 54 -answering_service, -as
 55    specifies that the answering service log is to be examined.  The
 56    answering service log family is called "log", and is located in the
 57    >sc1>as_logs directory.  This argument is incompatible with any of
 58    the other log selection control arguments, or an explicit log
 59    pathname.
 60 -dm_system, -dms
 61    specifies that the data management system log for the process's
 62    current AIM authorization is to be examined.  The data management
 63    log family is called "dm_system_log", and its location depends on
 64    the AIM access class of the log.  This argument is incompatible with
 65    any of the other log selection control arguments, or an explicit log
 66    pathname.  Reading the log requires access to the dm_admin_ gate.
 67 
 68 
 69 -mc_log log_name, -mcl log_name
 70    specifies that the message coordinator (daemon) log named LOG_NAME
 71    is to be examined.  All message coordinator logs are located in the
 72    >sc1>as_logs directory; their names depend on the daemon to which
 73    they belong.  This argument is incompatible with any of the other
 74    log selection control arguments, or an explicit log pathname.
 75 -number N, -nb N
 76    specifies that the monitor information for log number N is to be
 77    changed.  The log numbers are listed in the output from
 78    "monitor_sys_log -status".  This argument is incompatible with any
 79    of the other log selection control arguments, -all, or an explicit
 80    log pathname.
 81 
 82 
 83 -syserr
 84    specifies that the syserr log is to be examined.  The syserr log
 85    family is named "syserr_log".  The first segment in the family is
 86    >sl1>syserr_log; there may be a history segment in >sl1, and older
 87    history segments are in the directory >sc1>syserr_log.  This
 88    argument is incompatible with any of the other log selection control
 89    arguments, or an explicit log pathname.
 90 
 91 
 92 Control arguments (action to be performed):
 93 -add
 94    adds the specified log to the list being monitored, with the
 95    parameters specified by the other control arguments.  This is
 96    incompatible with -all and -number, and any other "action" control
 97    argument.
 98 -off
 99    turns monitoring off for the specified log(s), remembering the
100    monitoring parameters.  Monitoring must already have been started on
101    the specified log.  This is incompatible with the other "action"
102    control arguments.  No monitoring parameters may be specified with
103    this control argument.
104 
105 
106 -on
107    turns monitoring back on for the specified log(s), reversing the
108    effect of -off.  Monitoring must already have been started on the
109    specified log.  This is incompatible with the other "action" control
110    arguments.  No monitoring parameters may be specified with this
111    control argument.
112 -remove, -rm
113    removes the specified log(s) from the list being monitored.
114    Monitoring must already have been started on the specified log.
115    This is incompatible with the other "action" control arguments.  No
116    monitoring parameters may be specified with this control argument.
117 
118 
119 -replace, -rp
120    replaces all the monitoring parameters for the specified log(s) with
121    those specified by the other control arguments.  The log(s) must
122    already be being monitored; it is an error to specify a log pathname
123    or selection control argument identifying a log not being monitored
124    already.  This is incompatible with -all and any other "action"
125    control argument.
126 -status, -st
127    displays the status of monitoring for the specified log(s), or for
128    all logs currently being monitored if none is specified explicitly.
129    This is incompatible with the other "action" control arguments.  No
130    monitoring parameters may be specified with this control argument.
131 
132 
133 -update, -ud
134    if the specified log is not already being monitored, monitoring is
135    started for the specified log.  Otherwise, the monitoring parameters
136    for the specified log are updated by the other control arguments
137    specified, as if those control arguments had been specified at the
138    end of the command line that initially started the monitoring.  This
139    is incompatible with the other "action" control arguments. (Default)
140 
141 
142 Control arguments (message processing):
143 -call COMMAND, -cl COMMAND
144    specifies a command line to be executed each time a message is
145    selected from the specified log(s).  If the command is the null
146    string (""), command line processing is turned off, and new entries
147    are printed on the specified switch, instead.  The command line
148    receives the following parameters:
149          1) log prefix string
150          2) date-time of message
151          3) sequence number of message
152          4) severity of message
153          5) text of message
154          6) data class of message
155          7) expanded text of message
156 
157 
158    Parameters 6 and 7 are only supplied if the message has binary data,
159    and -expand was specified.
160 -time N, -tm N
161    specifies the monitoring interval, in seconds; the specified log(s)
162    will be sampled once every monitoring interval.  If the specified
163    interval is zero, periodic monitoring is turned off.  (Default: 10)
164 
165 
166 Control arguments (message selection):
167 -all_severities, -asv
168    specifies that messages of all severities are printed.  This cancels
169    the effect of any previous -severity control arguments.  (Default)
170 -exclude STR-1...STR-n, -ex STR-1...STR-n
171    specifies that no message whose text contains one of the specified
172    strings (STR-1 to STR-n) is processed.  A string is interpreted
173    either as a text string, which must be an exact substring of the
174    message text, or, if surrounded by slashes, as a regular to match
175    against the message text.  See the "Notes on String Matching"
176    section below for details.
177 
178 
179 -match STR-1...STR-n
180    specifies that only messages whose text contains one of the
181    specified strings (STR-1 to STR-n) are processed.  The strings are
182    processed as for -exclude.
183 -no_match_exclude, -nmx
184    specifies that all log messages are to be processed, regardless of
185    text contents, cancelling the effect of any preceding -match or
186    -exclude.  (Default)
187 
188 
189 -severity SEV-1...SEV-n, -sv SEV-1...EV-n
190    specifies that only messages of the specified severity (severities)
191    are processed.  The severity values (SEV-1 to SEV-n) may either be
192    decimal integers, or ranges consisting of a pair decimal integers
193    separated by a colon ("20:29").  If multiple severities are
194    specified, or the -severity control argument is specified more than
195    once, all messages with any of those severities are printed.  A
196    severity value must be between -100 and 100.  See the "Notes on
197    Severity Values" below for details.
198 
199 
200 Control arguments (message expansion):
201 -exclude_data STR-1...STR-n, -exd STR-1...STR-n
202    no messages whose interpreted expanded data contains one of the
203    specified strings (STR-1 to STR-n) is processed.  The strings are
204    processed as for -exclude.  Note: this control argument merely
205    matches against the textual interpretation of the expanded data; if
206    this interpretation is to be displayed as well, the -interpret
207    control argument must also be specified.
208 
209 
210 -expand {CLASS-1...CLASS-n}
211    specifies that binary data is to be expanded and displayed along
212    with the message text for the selected messages.  If a data class
213    value (CLASS-1 to CLASS-n is specified, only binary data of the
214    specified classes will be expanded; otherwise, all selected messages
215    with binary data will be expanded.  The type of expansion depends on
216    whether the -octal or -interpret control arguments are also
217    specified.  See the "Notes on data classes" section below for
218    details.  By default, no messages are expanded.
219 -interpret, -int
220    specifies that the binary data in expanded messages is to be
221    displayed as interpreted text, by calling the appropriate
222    expand_XXX_msg_ program for the data class of the message.  If the
223    -octal control argument is also specified, the binary data is
224    displayed both in interpreted form and as octal data.  (Default)
225 
226 
227 -match_data STR-1...STR-n, -md STR-1...STR-n
228    specifies that only messages whose interpreted expanded data
229    contains one of the specified strings (STR-1 to STR-n) are
230    processed.  The strings are processed as for -exclude.  Note: this
231    control argument merely matches against the textual interpretation
232    of the expanded data; if this interpretation is to be displayed as
233    well, the -interpret control argument must also be specified.
234 -no_expand, -nex
235    specifies that no messages are to be displayed with binary data
236    expanded.  This cancels the effect of any previous -expand control
237    arguments. (Default: no messages are expanded)
238 
239 
240 -octal, -oc
241    specifies that the binary data in expanded messages is to be
242    displayed in octal, rather than, or in addition to, the interpreted
243    representation.  If both octal and interpreted representations are
244    desired, both the -octal and -interpret control arguments must be
245    supplied.
246 
247 
248 Control arguments (message format):
249 -continuation_indent N, -ci N
250    specifies that all messages are to be formatted for printing with
251    continuation lines prefixed by N spaces, or, if the keyword
252    "standard" or "std" is used in place of a number, with the
253    continuation lines indented sufficiently to line up under the first
254    character of the text of the message.  The value of N must be
255    between zero and fifty.  (Default: continuation lines are indented
256    three spaces)
257 
258 
259 -date_format FORMAT_STRING, -dfmt FORMAT_STRING
260    specifies a date/time format string (see time_format.gi.info or the
261    Multics Programmer's Reference Manual (AG91) to be used
262    when formatting the date when successive messages are printed with
263    different dates.  The date string is printed on a line entirely by
264    itself, preceded by a blank line.  If the date format string is
265    blank, no date separators will be printed; this should be used if a
266    -time_format string is specified that includes the date as well.
267    The default date string is "^9999yc-^my-^dm ^da ^za", which prints
268    as (for example) "1984-10-31 Wed est".
269 
270    By specifying null strings for date, time, and number formats, the
271    log can be printed and saved, so that it can be compared to another
272    log script later, without spurious mis-compares because the times
273    and sequence numbers do not match.
274 
275 
276 -duplicates, -dup
277    inhibits the printing of "=" messages for messages whose text is the
278    same as the previous message printed.  All messages are printed
279    exactly as they appear in the log.
280 -indent N, -ind N
281    specifies that all messages are to be formatted for printing
282    prefixed with N spaces.  The value of N must be between zero and
283    fifty.  The indentation is printed before any data associated with
284    the message, including the message prefix. (Default: no indentation)
285 
286 
287 -line_length N, -ll N
288    specifies the line length used when formatting message text and data
289    for printing.  The value (N) must be between 25 and 500.  By
290    default, it is the line length associated with the user_output I/O
291    switch, or, if none (as for an absentee), it is 132 (for line
292    printer output).
293 -no_duplicates, -ndup
294    prints "==" for messages whose text is the same as the previous
295    message printed.  (Default)
296 -number_format IOA_STRING, -nfmt IOA_STRING
297    specifies an ioa_ string to be used when printing the sequence
298    number for the message.  If the string is null, no sequence number
299    is printed with the message.  The default is "^7d".  (See the
300    Multics Subroutines and I/O Modules manual (AG93) for a
301    description of ioa_ control strings.)
302 
303 
304 -prefix STRING, -pfx STRING
305    specifies that all messages are to be formatted with the specified
306    string as a prefix.  This prefix appears after the indentation (if
307    any was specified).  The prefix must explicitly include trailing
308    spaces, if any are desired to separate the prefix from the message
309    text.  The default prefix for a log is the entryname of the log
310    except for logs specified by the log selection control arguments.
311    The default prefix for a log selected by the log selection control
312    arguments are listed below:
313          Control Argument              prefix
314          -syserr                       "SYSERR:  "
315          -answering_service            "AS:  "
316          -admin                        "ADMIN:  "
317          -dm_system                    "DMS:  "
318 
319 
320 -time_format FORMAT_STRING, -tfmt FORMAT_STRING
321    specifies a date/time format string (see time_format.gi.info or the
322    Multics Programmer's Reference Manual (AG91) to be used
323    when formatting the message time portion of the message.  If the
324    string is null, no time is printed with the messages.  (Default:
325    "iso_time", which prints as "23:21:59")
326 
327 
328 Control arguments (miscellaneous):
329 -absolute_pathname, -absp
330    specifies that the absolute pathname of any log segment examined
331    while processing messages is to be printed; the pathname of each
332    segment is printed only once, whenever segments are switched.
333 -header, -he
334    specifies that a header is to be printed giving the times and
335    sequence numbers of the first and last messages processed. (Default)
336 -no_absolute_pathname, -nabsp
337    specifies that log segment pathnames are not to be printed.
338    (Default)
339 -no_header, -nhe
340    specifies that no header is to be printed.
341 
342 
343 -output_switch NAME, -osw NAME
344    specifies that the messages are to be written on the named I/O
345    switch.  (Default: user_output)
346 -procedure NAME, -proc NAME
347    specifies that entrypoints in the procedure called NAME are to be
348    used instead of entrypoints in log_read_ to read the log.  This is
349    used to read logs protected by inner-ring subsystems, where the
350    inner-ring subsystem provides a replacement log-reading procedure.
351    See "Access required" below.
352 
353 
354 Access required: For all except inner-ring logs, read permission is
355 required on the log segments themselves, and status permission is
356 required on their containing directories.  If an access error is
357 encountered searching for older history logs, the search is stopped at
358 that point, and no further history will be available.  For the logs
359 selected by control arguments, the control argument descriptions list
360 the standard history directories for the logs.
361 
362 For inner-ring logs (the data management system log is the only
363 standard inner-ring log), access to the logs is required, as is access
364 to the gate used by the log-reading procedure (see -procedure).
365 
366 
367 Notes on string matching: The strings specified by -match and
368 -exclude, or by -match_data and -exclude_data, are processed in
369 sequence.  An arbitrary number of strings may follow any of those
370 control arguments, and each string will be treated as if it was
371 preceded by another instance of the control argument, except that any
372 string beginning with a hyphen and not immediately following one of the
373 match/exclude control arguments is treated as a new control argument,
374 and no more strings are picked up until the next match/exclude
375 argument.
376 
377 A string may be either a text string, in which case it is tested simply
378 to see whether it is a substring in the message, or it may be a regular
379 expression, which is matched against the message.  A string will be
380 interpreted as a regular expression if it begins and ends with "/"
381 characters.
382 
383 
384 Each log message is processed against the set of strings, matching its
385 text (or data) to see if it contains the string.  There are two simple
386 cases: only match strings, and only exclude strings.  In the case of
387 only match strings, any log message that matches any of the strings
388 will be printed.  In the case of only exclude strings, a log message
389 will be printed only if it matches none of the strings.
390 
391 The more complicated case where match and exclude strings are mixed is
392 handled as follows: test the message against each string in turn.  If
393 the message matches, and the string is a "-match" string, the
394 "print-this-message" flag is set on.  If the message matches, and the
395 string is a "-exclude" string, the flag is set off.  Otherwise, the
396 flag is unaffected.  The flag's initial value is on if the first string
397 was a "-exclude" string, and off if the first string was a "-match"
398 string.
399 
400 
401 Notes on data classes: A data class is a short string (1 to 16
402 characters) stored with any message that contains binary data, and is
403 used to identify the expander procedure used to expand the data into
404 its interpreted textual form.  The data class is specified when the
405 message is placed into the log.
406 syserr
407    identifies an old-style syserr log message.  The "syserr binary"
408    code (see syserr_binary_defs.incl.pl1 for a list) is the first word
409    of the data in the message; the remaining words of data are the real
410    binary syserr data.
411 
412 
413 Notes on message selection: Messages are selected for printing in a
414 series of steps, each of which filters out certain messages according
415 to the control arguments specified.  The set of messages at each step
416 is any that were left after the previous step.  If a control argument
417 was not specified, then its corresponding step eliminates no messages.
418 Note that the -expand control arguments do NOT select messages, but
419 only affect how their contents are displayed
420    1) -severity
421    2) -exclude       (eliminate matching messages)
422    3) -match         (eliminate non-matching messages)
423    4) -exclude_data  (eliminate matching messages)
424    5) -match_data    (eliminate non-matching messages)
425 
426 
427 Notes on severity values: Severity values in log messages are used to
428 indicate the importance of the message being logged, in a general way.
429 Most logs use increasing severity to indicate increasing importance,
430 but the actual meaning depends on the log.  For the Answering Service
431 and Message Coordinator logs, the severities have the following
432 meanings:
433    0 => Message just logged
434    1 => Message logged and printed on a console
435    2 => Message logged and printed on a console with bells
436    3 => Message logged, printed, and the system crashed
437 
438 
439 For the syserr log, the severities have different meanings.
440    0 => Message logged and printed on syserr console
441    1 => Message logged, printed, and the system crashed
442    2 => Message logged, printed, and the process writing the
443            message is terminated.
444    3 => Message logged and printed, and console alarm sounded
445    4 => Message just logged, or printed if logging mechanism is
446            inoperable
447    5 => Message just logged, or discarded if it can't be logged
448 
449 The severities 20 to 25 are handled just like 0 to 5, but are different
450 to indicate that the originating program was writing an access audit
451 message, rather than just an informative message.
452 
453 
454 Notes on inner-ring logs: Some applications create logs in an inner
455 ring that must be read using a special interface.  The only standard
456 log to do this is the Data Management system log, and it is read by
457 specifying the -dm_system control argument which supplies both the
458 pathname and the procedure name (dm_log_read_).  Other applications may
459 provide their own special procedures for log reading, in which case
460 both the log pathname and the procedure name must be supplied
461 explicitly via the and -procedure control arguments.  Note
462 that a log read using a reader procedure may enforce additional access
463 requirements as well as requiring access to the log itself.  In
464 particular, the user must have access to the reader procedure.