SirScan scan specification

From m204wiki
Revision as of 00:34, 4 November 2015 by JAL (talk | contribs) (misc cleanup)
Jump to navigation Jump to search

Installation of SirScan is described in RKTools installation. SirScan should be installed as a private APSY subsystem in order to use the I/O limits assigned to each SCLASS. To access the system, enter SIRSCAN (or the name of the subsystem you have installed) on the Model 204 command line. A scan specification screen is presented:

Journal scan criteria screen

This screen allows the user to specify the journal data to be retrieved and the format in which it should be displayed. Input fields are:

Start time Formatted HH:MM:SS or -MMMMMM. The earliest audit trail entry to be formatted. The second syntax identifies the number of minutes to go back from the current time to begin formatting the journal. If Start time is not specified, data is formatted from the start of the run or the oldest ring journal (if using ring journals) if the requesting user is a system manager (or is in one of the ADMIN SCLASSes). Otherwise data is formatted from the logon time of the requesting user.
Start date Formatted YY/MM/DD. The date of the earliest audit trail entry to be formatted. If this is not specified, it is determined based on the start time. If the start time is less than the current time the current date is used, otherwise yesterday's date is used.
Interval Valid formats are MM:SS, HH:MM:SS, or MMMMMMM, where H is hours, M is minutes, and S is seconds. If an interval is not specified, data is formatted up to the current time (or until I/O limits are hit). In addition, by leaving this time blank, SirScan runs in auto-refresh mode, so the data being scanned is constantly refreshed to reflect any new audit trail data that was generated after the initial data was collected.
User Users to be included in the formatted output. This input field indicates which thread's/user's audit entries will be viewed.

The selection criteria can be a set of blank or comma delimited "phrases," each made up of one or more "clauses" separated by the ampersand (&) symbol. Each clause can contain one of the following criteria:

IODEVn A number n indicating a specific IODEV type, as in IODEV15, IODEV7, or IODEV11.
PST Entries for all Model 204 Psuedo-SubTasks.
n1.n2.n3.n4 An IP address for a Janus thread,

as in 198.242.244.97 or 150.209.8.51. The IP address can also be followedby a slash (/) and a subnet mask, or by a hyphen (-) and a number of bits in a subnet mask, as in 198.242.244.0/255.255.255.0 or 198.242.244.0-24.

These two subnetted IP addresses encompass the same set of IP addresses.
JAN:sss The name of a Janus port, possibly containing wildcards, as in JAN:WEBPORT, JAN:WEB*, or JAN:???PORT.
xxx A specific user number, as in 0, 233, or 1024.
xxx-yyy A range of user numbers, as in 0-20 or 111-1000.
ssss A string, possibly containing wildcards, that indicates a specific userid, as in RASPUTIN, RAS*, ???PUTIN. For users in the ADMIN_xxx SCLASSes, a userid of just an asterisk (*) is special-cased to mean not only all logged-on users, but all threads, whether logged on or not.

Criteria can be mixed and matched using the & separator, which indicates an "And" operation, or using blanks or commas, which indicate an "Or" operation. For example, the following string requests information for all IODEV 15 threads logged on as userid LENIN, and requests all the information for user numbers 11 through 20:

IODEV15&LENIN 11-20

And this:

TROT*&198.242.244.33 JAN:SOCIALIST&MARX PST

requests information for all of the following:

  • All connections from IP address 198.242.244.33 that log on a userid that begins with TROT
  • All connections to Janus port SOCIALIST that log on to userid MARX
  • All PSTs

Portnames and userids can contain special wildcard characters. These characters and their meanings are:

* Matches any number of characters. For example, BRE* matches BREAD, BREEZY, and BREZHNEV.
? Matches a single character. For example, ?RUSHCHEV matches TRUSHCHEV,BRUSHCHEV, and KRUSHCHEV.
" Means the next character is to be treated literally, even if it is wildcard character. Using the double-quotation character is necessary if a wildcard character appears in the name to be matched.For example, E"*BARTER matches E*BARTER.

Users in USER_HI, USER_MED or USER_LO SCLASSes, no matter what selection criteria are specified, are only able to view audit entries associated with their own userid or, if the system SCANPARM 1 bit is set, entries for public logins on Janus Web Server threads. So if a user in the USER_MED SCLASS specifies the following for a selection criterion:

IODEV15

The user will be able to see only IODEV 15 activity for her own userid or perhaps for public logins to a Janus Web thread (if the SCANPARM 1 bit is set).

Because the specified time interval may not include the journal entries that would allow SirScan to associate a thread's activity with a particular userid, IP address, or port number, it is possible that entries associated with a particular userid, IP address, or port number will not be formatted. It is also possible that many entries in a time interval for a requested userid, IP address, or port number will not be formatted, but those after an audit entry that allows determination of all these entities (a since-last statistic or a SirScan RK line), will be.

SirScan makes every effort to use all available information (current logged on userids and log times, M204.0352 messages, M204.0118 messages, since-last stat entries, etc.) to ascertain this information about each audit trail entry, but these attempts are necessarily hit and miss: While most of the time, SirScan will pick up the desired information, it is possible that information will also seem to be inexplicably missing. Often this information can still be retrieved by varying the date/time interval.

Alternatively, if the SCANTIME system parameter is set, and the "Read extra SCANTIME seconds" switch is set to Y, SirScans behavior can be made completely consistent and predictable at a (hopefully slight) cost.

If no criteria are specified for User, only audit entries for the requesting user are displayed.

Note: One additional selection criterion is applied to any User phrase if SirScan has not been purchased but instead is automatically authorized by Limited Janus Web Server. Limited Janus Web Server is a free, restricted version of Janus Web Server; they are both documented in Janus Web Server.

To assist in web development, sites that don't already have SirScan can use it for free if they are using Limited Janus Web Server. Sites using SirScan for free are automatically limited to viewing the journal activity of Janus Web threads and the TCP/IP subtask; any User selection will thus be automatically restricted.

You may, of course, upgrade to a full SirScan at any time.

Line Width The audit trail data can be formatted for any line width from one less than the screen width to 255. The minimum output line width is 131 for MODEL 5 terminals, and it is 79 for all other terminal types.
Read extra
SCANTIME seconds		 This field only appears if the SCANTIME system parameter is set to a non-zero value.The value of this field must be either Y or N.

Setting this field to N allows anomalous and confusing behavior on SirScan's part so should be avoided unless following are all true:

  • The SCANTIME parameter is set, against recommendations, to a very high value.
  • You are very concerned about security.
  • You understand the anomalous behavior that is likely to result, and either you feel it doesn't apply to your selection criteria, or you don't care.
Max I/O's The maximum number of full-track journal reads SirScan will perform when scanning the journal. The maximum value allowed for this field is determined by the user's subsystem SCLASS. This value should generally be kept to a relatively small number such as 100 or 1000 in the case of very busy systems to avoid accidentally scanning too much of the journal when an inappropriate time interval is specified.
Max records The maximum number of journal records to be formatted by SirScan. The maximum value allowed for this field is determined by the user's subsystem SCLASS. This value should generally be kept to a reasonably small number such as 10000 to avoid accidentally building an unmanageably large list of formatted records.
Display
Date Indicates whether the date of each entry is to appear in the formatted audit trail data. The dates are displayed in YYMMDD format.
Server number Indicates whether server numbers are to appear in the fomatted audit trail data.
Entry type Indicates whether the type of each entry is to be included in the formatted audit trail data. The types are described in Journal entry types. If entry types are not displayed, colors are automatically turned off.
Time Indicates whether the time of each entry is to appear in the formatted audit trail data. The times are displayed in HHMMSSTH format.
User numbers Indicates whether user numbers are to appear in the fomatted audit trail data.
Use color Indicates whether the formatted journal output is to be shown using the user-specified colors. Colors are only displayed if Entry type is Y.
Format entry types
ST Responding Y to this prompt causes ST records (all types of statistics records) to be included in the formatted output. Specifying N excludes these records.
All Audit Types Responding Y to this prompt causes all audit type records to be included in the formatted output.

Specifying N causes SirScan to pay attention to the specific Y/N settings for each record type in the bottom two rows on the screen. The various record types are described in Journal entry types and also in Audit trail format.

SirScan RK lines Responding Y to this prompt causes SirScan heartbeat RK messages for the SCANTIME system parameter to be formatted.

These messages largely exist to help SirScan identify threads by userid or other selection criteria and are not particularly interesting so are ordinarily suppressed regardless of the All Audit Types or RK switch settings.

If this prompt is set to Y, the SirScan heartbeat messages will be displayed.
Bookmarks Creates extra lines in the display listing that mark the time range for each scan.
AD, CI, ... QT Journal entry types; see Journal entry types.

Commands and function keys

The following commands and PF keys are valid on the scan specification screen:

Commands
=x.yy.z Commands prefixed by = invoke fastpath navigation of the UL/SPF menu system. =M sends the user to the RKTools main menu if RKTools is active. =X exits to command level. =M.4.5.2 sends the user to the "Active Subsystems" display in SirMon (if SirMon is active).
X Exits to command level.
PF keys
PF1 Accesses online help.
PF3 Quit (return to command level).

See also

Retrieved from "https://m204wiki.rocketsoftware.com/index.php?title=SirScan_scan_specification&oldid=81523"