04/04/86 monitor_sys_log, msl Syntax as a command: msl {log_selector} {-control_args} Function: monitors activity in system logs. Contents of the selected logs are periodically examined, and any new messages are printed on the terminal or passed as arguments to a specified command line. Control arguments determine what action the command performs, and also supply message selection and formatting options. There are three types of control arguments--log selection, action, and monitoring control arguments. Only one action control argument may be specified in any given invocation of the command. For all actions (except -status), a log must be specified; for some actions (-update, -on, -off, -remove, -status), -all may be specified to select the log, indicating that the action applies to all logs currently being monitored. All other control arguments specify monitoring operations: message selection, message processing, message format. A separate set of monitoring options is kept for each log being monitored. A specific log may be monitored more than once, by specifying -add to establish separate monitors; this is useful when different sets of monitoring options are desired to process messages from the same log differently. Arguments: log_selector is the pathname of a log to be monitored. The pathname must specify the first segment in a log. This argument is incompatible with any of the log selection control arguments. If a log is selected, either by pathname or one of the control arguments below, and no "action" is specified, monitoring is started or updated, as appropriate (see -update, below). To replace the monitor information for a log, or start an independent monitor with different parameters, -replace or -add must be specified. For all actions except -status, either a log pathname or a log selection control argument must be specified. Control arguments (log selection): -admin specifies that the admin log is to be examined. The admin log is called "admin_log", and is located in the >sc1>as_logs directory. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -all, -a specifies that the monitor information for all logs is to be changed. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -answering_service, -as specifies that the answering service log is to be examined. The answering service log family is called "log", and is located in the >sc1>as_logs directory. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -dm_system, -dms specifies that the data management system log for the process's current AIM authorization is to be examined. The data management log family is called "dm_system_log", and its location depends on the AIM access class of the log. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. Reading the log requires access to the dm_admin_ gate. -mc_log log_name, -mcl log_name specifies that the message coordinator (daemon) log named LOG_NAME is to be examined. All message coordinator logs are located in the >sc1>as_logs directory; their names depend on the daemon to which they belong. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -number N, -nb N specifies that the monitor information for log number N is to be changed. The log numbers are listed in the output from "monitor_sys_log -status". This argument is incompatible with any of the other log selection control arguments, -all, or an explicit log pathname. -syserr specifies that the syserr log is to be examined. The syserr log family is named "syserr_log". The first segment in the family is >sl1>syserr_log; there may be a history segment in >sl1, and older history segments are in the directory >sc1>syserr_log. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. Control arguments (action to be performed): -add adds the specified log to the list being monitored, with the parameters specified by the other control arguments. This is incompatible with -all and -number, and any other "action" control argument. -off turns monitoring off for the specified log(s), remembering the monitoring parameters. Monitoring must already have been started on the specified log. This is incompatible with the other "action" control arguments. No monitoring parameters may be specified with this control argument. -on turns monitoring back on for the specified log(s), reversing the effect of -off. Monitoring must already have been started on the specified log. This is incompatible with the other "action" control arguments. No monitoring parameters may be specified with this control argument. -remove, -rm removes the specified log(s) from the list being monitored. Monitoring must already have been started on the specified log. This is incompatible with the other "action" control arguments. No monitoring parameters may be specified with this control argument. -replace, -rp replaces all the monitoring parameters for the specified log(s) with those specified by the other control arguments. The log(s) must already be being monitored; it is an error to specify a log pathname or selection control argument identifying a log not being monitored already. This is incompatible with -all and any other "action" control argument. -status, -st displays the status of monitoring for the specified log(s), or for all logs currently being monitored if none is specified explicitly. This is incompatible with the other "action" control arguments. No monitoring parameters may be specified with this control argument. -update, -ud if the specified log is not already being monitored, monitoring is started for the specified log. Otherwise, the monitoring parameters for the specified log are updated by the other control arguments specified, as if those control arguments had been specified at the end of the command line that initially started the monitoring. This is incompatible with the other "action" control arguments. (Default) Control arguments (message processing): -call COMMAND, -cl COMMAND specifies a command line to be executed each time a message is selected from the specified log(s). If the command is the null string (""), command line processing is turned off, and new entries are printed on the specified switch, instead. The command line receives the following parameters: 1) log prefix string 2) date-time of message 3) sequence number of message 4) severity of message 5) text of message 6) data class of message 7) expanded text of message Parameters 6 and 7 are only supplied if the message has binary data, and -expand was specified. -time N, -tm N specifies the monitoring interval, in seconds; the specified log(s) will be sampled once every monitoring interval. If the specified interval is zero, periodic monitoring is turned off. (Default: 10) Control arguments (message selection): -all_severities, -asv specifies that messages of all severities are printed. This cancels the effect of any previous -severity control arguments. (Default) -exclude STR-1...STR-n, -ex STR-1...STR-n specifies that no message whose text contains one of the specified strings (STR-1 to STR-n) is processed. A string is interpreted either as a text string, which must be an exact substring of the message text, or, if surrounded by slashes, as a regular to match against the message text. See the "Notes on String Matching" section below for details. -match STR-1...STR-n specifies that only messages whose text contains one of the specified strings (STR-1 to STR-n) are processed. The strings are processed as for -exclude. -no_match_exclude, -nmx specifies that all log messages are to be processed, regardless of text contents, cancelling the effect of any preceding -match or -exclude. (Default) -severity SEV-1...SEV-n, -sv SEV-1...EV-n specifies that only messages of the specified severity (severities) are processed. The severity values (SEV-1 to SEV-n) may either be decimal integers, or ranges consisting of a pair decimal integers separated by a colon ("20:29"). If multiple severities are specified, or the -severity control argument is specified more than once, all messages with any of those severities are printed. A severity value must be between -100 and 100. See the "Notes on Severity Values" below for details. Control arguments (message expansion): -exclude_data STR-1...STR-n, -exd STR-1...STR-n no messages whose interpreted expanded data contains one of the specified strings (STR-1 to STR-n) is processed. The strings are processed as for -exclude. Note: this control argument merely matches against the textual interpretation of the expanded data; if this interpretation is to be displayed as well, the -interpret control argument must also be specified. -expand {CLASS-1...CLASS-n} specifies that binary data is to be expanded and displayed along with the message text for the selected messages. If a data class value (CLASS-1 to CLASS-n is specified, only binary data of the specified classes will be expanded; otherwise, all selected messages with binary data will be expanded. The type of expansion depends on whether the -octal or -interpret control arguments are also specified. See the "Notes on data classes" section below for details. By default, no messages are expanded. -interpret, -int specifies that the binary data in expanded messages is to be displayed as interpreted text, by calling the appropriate expand_XXX_msg_ program for the data class of the message. If the -octal control argument is also specified, the binary data is displayed both in interpreted form and as octal data. (Default) -match_data STR-1...STR-n, -md STR-1...STR-n specifies that only messages whose interpreted expanded data contains one of the specified strings (STR-1 to STR-n) are processed. The strings are processed as for -exclude. Note: this control argument merely matches against the textual interpretation of the expanded data; if this interpretation is to be displayed as well, the -interpret control argument must also be specified. -no_expand, -nex specifies that no messages are to be displayed with binary data expanded. This cancels the effect of any previous -expand control arguments. (Default: no messages are expanded) -octal, -oc specifies that the binary data in expanded messages is to be displayed in octal, rather than, or in addition to, the interpreted representation. If both octal and interpreted representations are desired, both the -octal and -interpret control arguments must be supplied. Control arguments (message format): -continuation_indent N, -ci N specifies that all messages are to be formatted for printing with continuation lines prefixed by N spaces, or, if the keyword "standard" or "std" is used in place of a number, with the continuation lines indented sufficiently to line up under the first character of the text of the message. The value of N must be between zero and fifty. (Default: continuation lines are indented three spaces) -date_format FORMAT_STRING, -dfmt FORMAT_STRING specifies a date/time format string (see time_format.gi.info or the Multics Programmer's Reference Manual (AG91) to be used when formatting the date when successive messages are printed with different dates. The date string is printed on a line entirely by itself, preceded by a blank line. If the date format string is blank, no date separators will be printed; this should be used if a -time_format string is specified that includes the date as well. The default date string is "^9999yc-^my-^dm ^da ^za", which prints as (for example) "1984-10-31 Wed est". By specifying null strings for date, time, and number formats, the log can be printed and saved, so that it can be compared to another log script later, without spurious mis-compares because the times and sequence numbers do not match. -duplicates, -dup inhibits the printing of "=" messages for messages whose text is the same as the previous message printed. All messages are printed exactly as they appear in the log. -indent N, -ind N specifies that all messages are to be formatted for printing prefixed with N spaces. The value of N must be between zero and fifty. The indentation is printed before any data associated with the message, including the message prefix. (Default: no indentation) -line_length N, -ll N specifies the line length used when formatting message text and data for printing. The value (N) must be between 25 and 500. By default, it is the line length associated with the user_output I/O switch, or, if none (as for an absentee), it is 132 (for line printer output). -no_duplicates, -ndup prints "==" for messages whose text is the same as the previous message printed. (Default) -number_format IOA_STRING, -nfmt IOA_STRING specifies an ioa_ string to be used when printing the sequence number for the message. If the string is null, no sequence number is printed with the message. The default is "^7d". (See the Multics Subroutines and I/O Modules manual (AG93) for a description of ioa_ control strings.) -prefix STRING, -pfx STRING specifies that all messages are to be formatted with the specified string as a prefix. This prefix appears after the indentation (if any was specified). The prefix must explicitly include trailing spaces, if any are desired to separate the prefix from the message text. The default prefix for a log is the entryname of the log except for logs specified by the log selection control arguments. The default prefix for a log selected by the log selection control arguments are listed below: Control Argument prefix -syserr "SYSERR: " -answering_service "AS: " -admin "ADMIN: " -dm_system "DMS: " -time_format FORMAT_STRING, -tfmt FORMAT_STRING specifies a date/time format string (see time_format.gi.info or the Multics Programmer's Reference Manual (AG91) to be used when formatting the message time portion of the message. If the string is null, no time is printed with the messages. (Default: "iso_time", which prints as "23:21:59") Control arguments (miscellaneous): -absolute_pathname, -absp specifies that the absolute pathname of any log segment examined while processing messages is to be printed; the pathname of each segment is printed only once, whenever segments are switched. -header, -he specifies that a header is to be printed giving the times and sequence numbers of the first and last messages processed. (Default) -no_absolute_pathname, -nabsp specifies that log segment pathnames are not to be printed. (Default) -no_header, -nhe specifies that no header is to be printed. -output_switch NAME, -osw NAME specifies that the messages are to be written on the named I/O switch. (Default: user_output) -procedure NAME, -proc NAME specifies that entrypoints in the procedure called NAME are to be used instead of entrypoints in log_read_ to read the log. This is used to read logs protected by inner-ring subsystems, where the inner-ring subsystem provides a replacement log-reading procedure. See "Access required" below. Access required: For all except inner-ring logs, read permission is required on the log segments themselves, and status permission is required on their containing directories. If an access error is encountered searching for older history logs, the search is stopped at that point, and no further history will be available. For the logs selected by control arguments, the control argument descriptions list the standard history directories for the logs. For inner-ring logs (the data management system log is the only standard inner-ring log), access to the logs is required, as is access to the gate used by the log-reading procedure (see -procedure). Notes on string matching: The strings specified by -match and -exclude, or by -match_data and -exclude_data, are processed in sequence. An arbitrary number of strings may follow any of those control arguments, and each string will be treated as if it was preceded by another instance of the control argument, except that any string beginning with a hyphen and not immediately following one of the match/exclude control arguments is treated as a new control argument, and no more strings are picked up until the next match/exclude argument. A string may be either a text string, in which case it is tested simply to see whether it is a substring in the message, or it may be a regular expression, which is matched against the message. A string will be interpreted as a regular expression if it begins and ends with "/" characters. Each log message is processed against the set of strings, matching its text (or data) to see if it contains the string. There are two simple cases: only match strings, and only exclude strings. In the case of only match strings, any log message that matches any of the strings will be printed. In the case of only exclude strings, a log message will be printed only if it matches none of the strings. The more complicated case where match and exclude strings are mixed is handled as follows: test the message against each string in turn. If the message matches, and the string is a "-match" string, the "print-this-message" flag is set on. If the message matches, and the string is a "-exclude" string, the flag is set off. Otherwise, the flag is unaffected. The flag's initial value is on if the first string was a "-exclude" string, and off if the first string was a "-match" string. Notes on data classes: A data class is a short string (1 to 16 characters) stored with any message that contains binary data, and is used to identify the expander procedure used to expand the data into its interpreted textual form. The data class is specified when the message is placed into the log. syserr identifies an old-style syserr log message. The "syserr binary" code (see syserr_binary_defs.incl.pl1 for a list) is the first word of the data in the message; the remaining words of data are the real binary syserr data. Notes on message selection: Messages are selected for printing in a series of steps, each of which filters out certain messages according to the control arguments specified. The set of messages at each step is any that were left after the previous step. If a control argument was not specified, then its corresponding step eliminates no messages. Note that the -expand control arguments do NOT select messages, but only affect how their contents are displayed 1) -severity 2) -exclude (eliminate matching messages) 3) -match (eliminate non-matching messages) 4) -exclude_data (eliminate matching messages) 5) -match_data (eliminate non-matching messages) Notes on severity values: Severity values in log messages are used to indicate the importance of the message being logged, in a general way. Most logs use increasing severity to indicate increasing importance, but the actual meaning depends on the log. For the Answering Service and Message Coordinator logs, the severities have the following meanings: 0 => Message just logged 1 => Message logged and printed on a console 2 => Message logged and printed on a console with bells 3 => Message logged, printed, and the system crashed For the syserr log, the severities have different meanings. 0 => Message logged and printed on syserr console 1 => Message logged, printed, and the system crashed 2 => Message logged, printed, and the process writing the message is terminated. 3 => Message logged and printed, and console alarm sounded 4 => Message just logged, or printed if logging mechanism is inoperable 5 => Message just logged, or discarded if it can't be logged The severities 20 to 25 are handled just like 0 to 5, but are different to indicate that the originating program was writing an access audit message, rather than just an informative message. Notes on inner-ring logs: Some applications create logs in an inner ring that must be read using a special interface. The only standard log to do this is the Data Management system log, and it is read by specifying the -dm_system control argument which supplies both the pathname and the procedure name (dm_log_read_). Other applications may provide their own special procedures for log reading, in which case both the log pathname and the procedure name must be supplied explicitly via the and -procedure control arguments. Note that a log read using a reader procedure may enforce additional access requirements as well as requiring access to the log itself. In particular, the user must have access to the reader procedure. ----------------------------------------------------------- Historical Background This edition of the Multics software materials and documentation is provided and donated to Massachusetts Institute of Technology by Group BULL including BULL HN Information Systems Inc. as a contribution to computer science knowledge. This donation is made also to give evidence of the common contributions of Massachusetts Institute of Technology, Bell Laboratories, General Electric, Honeywell Information Systems Inc., Honeywell BULL Inc., Groupe BULL and BULL HN Information Systems Inc. to the development of this operating system. Multics development was initiated by Massachusetts Institute of Technology Project MAC (1963-1970), renamed the MIT Laboratory for Computer Science and Artificial Intelligence in the mid 1970s, under the leadership of Professor Fernando Jose Corbato. Users consider that Multics provided the best software architecture for managing computer hardware properly and for executing programs. Many subsequent operating systems incorporated Multics principles. Multics was distributed in 1975 to 2000 by Group Bull in Europe , and in the U.S. by Bull HN Information Systems Inc., as successor in interest by change in name only to Honeywell Bull Inc. and Honeywell Information Systems Inc. . ----------------------------------------------------------- Permission to use, copy, modify, and distribute these programs and their documentation for any purpose and without fee is hereby granted,provided that the below copyright notice and historical background appear in all copies and that both the copyright notice and historical background and this permission notice appear in supporting documentation, and that the names of MIT, HIS, BULL or BULL HN not be used in advertising or publicity pertaining to distribution of the programs without specific prior written permission. Copyright 1972 by Massachusetts Institute of Technology and Honeywell Information Systems Inc. Copyright 2006 by BULL HN Information Systems Inc. Copyright 2006 by Bull SAS All Rights Reserved