06/26/86 summarize_sys_log, ssl Syntax as a command: ssl {log_selector} -control control_path {-control_args} Function: summarizes activity in a system log. The specified range of messages in the log are matched against the selection and printing criteria in the control file and written or summarized to the specified I/O switches. This command requires that a set of I/O switches (used to write log messages and summaries) be attached before the command is executed and detached afterwards. Control arguments determine what range of messages are processed, and how those messages are formatted in the output. Arguments: log_selector is the pathname of a log to be summarized The pathname must specify the first segment in the log. This argument is incompatible with any of the log selection control arguments. Control arguments for log section: -admin specifies that the admin log is to be summarized. The admin commands 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. -answering_service, -as specifies that the answering service log is to be summarized. 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 summarized. The data management log 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. -dsa_sys_log, -dsasl specifies that the DSA system log is to be examined. The location of this log is specified in the DSA NIT. This is a ring 1 log, and the user must have access to dsa_log_admin_gate_ to read it. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -dsa_sys_aep_log, -dsasal specifies that the DSA system AEP log is to be examined. The location of this log is specified in the DSA NIT. This is a ring 1 log, and the user must have access to dsa_log_admin_gate_ to read it. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -mc_log LOG_NAME, -mcl LOG_NAME specifies that the message coordinator (daemon) log named LOG_NAME is to be summaried. 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. -pathname LOG_PATH, -pn LOG_PATH specifies the pathname of the log to be summarized. the pathname must specify the first segment in the log. This argument is incompatible with any of the other log selection control arguments, or an explicit log pathname. -syserr specifies that the syserr log is to be summarized. The syserr log 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 for control: -control CONTROL_PATH specifies the pathname of the selection control file to be used in summarizing the log messages. See "Control File Syntax" and "List of Selection Operators", below for details of the syntax. This argument must be specified. -for TIME, -for NUMBER specifies a number of messages to process, or a time interval relative to the starting time (specified by -from) in which the messages must be contained. The number of messages is the actual number of messages processed, not the number of messages examined in the log. This is incompatible with -to and -last. -from TIME, -fm TIME, -from NUMBER, -fm NUMBER specifies that the first message processed is the first message at or after the specified time or sequence number; if -reverse is specified, the first message is the one at or before the specified value. If no -from value is specified, the default is the first message in the log, or the last if -reverse is specified. This is incompatible with -last. -last NUMBER, -lt NUMBER, -last TIME, -lt TIME specifies that only the last NUMBER messages, or the messages since TIME, are to be processed. If a NUMBER is specified, it specifies the actual number of messages to be processed, not the number of messages examined in the log. This is incompatible with -from and -for. -to TIME, -to NUMBER specifies the last message to be processed, either by message time or sequence number. If not specified, the default is all the remaining messages in the log. This is incompatible with -for. Control arguments for message expansion: -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. This is the default. -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 for 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. By default, continuation lines are indented to the "standard" indentation. -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, Order No. 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. By default, there is 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). -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. By default, there is no prefix. -no_duplicates, -ndup prints "==" for messages whose text is the same as the previous message printed. This is the 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, Order No. AG93 for a description of ioa_control strings.) -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, Order No. 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. The default time format is "iso_time", which prints as (for example) "23:21:59". Miscellaneous control arguments: -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. Notes: The summarize_sys_log command produces multiple copies of printable files, each containing different abstracts of the log being scanned. There are two basic abstracting techniques: writing lines selected by character string matching into the file, and writing the total number of occurrences of specified types of lines. There are two possible methods for specifying the starting point of an invocation of the sys_log_scan_report command. The recommended method is to use a value segment to record the times, as follows: vs first_entry [clock calendar_clock [vg last_entry] +1usec] vs last_entry [clock calendar_clock] ssl LOG_PATH -from [vg first_entry] -to [last_entry] Notes on output: Rather than writing directly into files, the command writes its output through user-specified I/O switches. No I/O switch attachment or detachment is done by the program. It is the responsibility of the caller to ensure that all switches named in the control segment are attached and opened with the io_call command. Usually, these are attached to storage system segments through the vfile_ I/O module. Notes on control file syntax: The control file names the output switches and selection operations used by the command. The general format of a control line in the file is: SWITCHNAME,SEVERITY,OPCODE,LITERAL. switchname is the name of an I/O switch to which this information will be written. severity indicates the minimum severity message this control line applies to, or a range of severities. The severity value may either be a decimal integer, or ranges consisting of a pair decimal integers separated by a colon ("20:29"). opcode describes the kind of selection desired. It may have any one of the values listed below: all selects all lines. any selects any lines containing the string . allx like all, but messages with binary data have the data expanded when printed. anyx like any, but messages with binary data have the data expanded when printed. bcount counts all lines that begin with the string and places the total on the named switch after all entries are written. begin selects all lines with the string as their beginning. beginx like begin, but messages with binary data have the data expanded when printed. count counts all lines that contain the string and places the total on the named switch after all entries are written. nbegin diverts any lines that begin with the string from the output switch if later selected by an all, any, or begin opcode. not diverts any lines that contain the string from the output switch if later selected by an all or begin opcode. To be effective, the not and nbegin lines for a particular switch may precede the all, any, and begin control lines. The not and nbegin lines do not affect the counting of lines. If no lines were written on a switch, and a count is zero, the total line is omitted. If any lines were written on a switch, a count of total lines written follows the totals for count and bcount. Thus, nothing is written on a switch only if all selections fail. literal is an operand used to select the message; its function is described individually for each opcode. All characters following the comma are taken literally; no quote processing is performed. 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 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_). If DSA is installed on a system, then the -dsasl and -dsasal arguments can be used in a similar fashion (they will use the dsa_log_admin_gate_ procedure). 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 -pathname 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