SirScan setup

As of Model 204 V7.5, the functions and facilities necessary to run SirScan are built into the Model 204 kernel. For versions of Model 204 before 7.5, the installation of the Sirius Mods is required and sufficient to install and run the SIRSCAN subsystem, the SirScan engine.

In addition, optimal results using SirScan require your attention to the settings of:

• The Model 204 system parameters SCANTIME and SCANPARM
• The SIRSCAN subsystem user SCLASS controls

Setting SirScan system parameters

The "background" subsection below describes some native limitations in selecting and formatting journal entries that are remedied by functionality controlled by two User 0 parameters.

Background

The Model 204 journal records contain only a user number and do not contain other potentially useful identifying information, such as user ID, terminal ID, or IP address. So when SirScan scan specifications in the SIRSCAN subsystem are based on things like userid, IP address, or port name, there is often no way to determine whether a single journal entry is associated with the requested attributes or not.

In very early versions of the product, selection criteria based on userid would only work for currently logged on threads, and then only for journal entries from the current session. This is because, for logged in users, SirScan can determine user number and login time. From these two pieces of information, it can be sure that all journal entries for the thread associated with a requested user ID, and with a date/time stamp after the login time of the user, are associated with that user.

Outside of being very limiting — it was impossible to select journal information based on userid for non-logged in users — SirScan could also produce anomalous behavior in auto-refresh mode. Because SirScan only collects data from the previous end of the interval when in auto-refresh mode, if a userid that was present and selected in a previous interval logged off before the data is refreshed for the new interval, none of the journal records for that user would appear between the end of the previous interval and the end of the current. Outside of the annoyance of not seeing the expected data, this could cause confusion among SirScan end-users, because a user's journal entries might seem to suddenly stop without a logoff record or any other hint as to why.

In later versions, SirScan made more of an effort to use information in the journal to associate journal records with userids or other attributes not actually on the journal records. For example, if SirScan sees a M204.0352 message for a login, it knows that from that time on, all journal records for that thread number are associated with the userid on the M204.0352 message, until the end of the interval or a M204.0352 logout message is reached for that thread.

In a similar way, SirScan could use the MSIR.0114 message, which indicates a Janus port and client IP address for any Janus server request, to associate a thread number with an IP address and port name. Unfortunately, while this approach makes it possible to use non-thread-number and non-thread-type based selection criteria for sessions that are no longer active, it also makes SirScan's behavior even more anomalous and confusing: whether or not a journal record is selected might depend on whether or not SirScan happened to see an identifying message in the journal for that thread. For example, if user MOE was logged on from 8:37 to 11:43, and a request for MOE's records is made for the interval 8:38 to 9:30, none of MOE's records are seen. But if the selected interval was 8:37 to 9:30, they are all seen.

To fix the anomalous behaviors, SirScan now uses "heartbeat" messages: RK type audit messages that contain identifying information about a thread such as userid, terminal ID, and IP address and port number for Janus server threads. The heartbeat messages are controlled by the SCANTIME system parameter. And the SCANPARM parameter ensures SirScan's detection of the login of Janus Web Server threads.

Using the SCANTIME system parameter

SirScan heartbeat messages are controlled by the SCANTIME system parameter, which must be set with the User 0 parameters in the CCAIN stream. This parameter indicates the maximum number of seconds between journal messages for a thread before a heartbeat message is issued. If a message is about to be sent to the journal for a thread, and it has been more than SCANTIME seconds since the last heartbeat message, then the heartbeat message is first sent to the journal. This means that if a journal message is found for a thread, the userid and other identifying information can always be found by looking backwards in the journal no more than SCANTIME seconds.

The default value for SCANTIME is 0, which means that heartbeat messages are not logged. If SCANTIME is set to a positive value up to its maximum value of 3600, the SirScan heartbeat messages will be logged to the journal.

If SCANTIME is set to a non-zero value, the SIRSCAN subsystem detects this and, on the scan specification screen, gives users the option of reading an extra SCANTIME seconds on every interval collected from the journal. The extra SCANTIME seconds read are before the start of the requested interval. While the data from the extra SCANTIME seconds worth of journal entries is not formatted, it is scanned for the heartbeat messages, and any information in those messages is saved for each thread. In this way, all messages for all threads after the start of the requested interval can be deterministically associated with a userid, terminal ID, and IP address and Janus port for Janus server requests.

The cost of getting this deterministic behavior is the overhead of scanning an extra SCANTIME seconds worth of journal. If scanning is being done in auto-refresh mode, each refresh (attempt to move past the current bottom) will cause an extra SCANTIME seconds to be scanned. This means that the setting of SCANTIME involves a trade-off between the number of heartbeat messages logged to the journal and the overhead of scanning an extra SCANTIME seconds of journal on every SirScan browse request. The bigger the value of SCANTIME, the fewer heartbeat messages will be logged, but the more journal records would need to be scanned on each SirScan browse request. A small value of SCANTIME will, of course, have the opposite effect.

Since journal messages tend to be bunched (when a thread gets one audit message logged it is likely to get several around the same time), there is probably not a significantly higher cost to a relatively small SCANTIME, like 10 or even 5, than to a much larger one, like 60. On the other hand, the amount of extra work performed by SirScan associated with the extra SCANTIME second scan for each browse request will be roughly proportional to the size of SCANTIME. All this would suggest using a fairly small SCANTIME: a value of 10 might be a good starting point.

If you are setting SCANTIME for the first time in an Online, it is prudent to anticipate a 3% increase in journal usage, though the actual increase will almost undoubtedly be much less than that (probably less than even 1%).

Note: The heartbeat message can even be useful outside of SirScan. Since the heartbeat messages are regular RK type messages, they can be viewed with AUDIT204 as well as SirScan.

This means that if one is using AUDIT204 for a previous run's journal, and one wants to find entries for a particular userid in a particular time interval, one can simply request from AUDIT204 all records for all users in the desired interval plus SCANTIME seconds before. By doing so, one can be certain that any messages formatted by AUDIT204 will be preceded by a message identifying the user associated with that message.

Using the SCANPARM system parameter

The second SirScan-related User 0 parameter is SCANPARM. This parameter is a collection of bits that indicate certain SirScan behavior.

The SCANPARM bits are:

X'01'

Allow non-system-manager users to browse journal entries for public requests on Janus Web Server threads. Public requests are those that are not protected from access by user ID.

X'02'

Issue a redundant MSIR.0361 Processing request method URL message after login. Normally, MSIR.0361 is issued on web threads before login, since the method and URL are known before the userid and password, if a login is even required for the request. Unless the X'02' SCANPARM bit is set, users browsing journal entries for Janus Web Server threads based on userid do not see the MSIR.0361 message (since it occurs before the login), so they have a difficult time ascertaining the method and URL being processed in a particular request.

The default for the SCANPARM parameter is X'00'.

SIRSCAN subsystem definition

SirScan is a full-screen utility (the SIRSCAN subsystem) that allows users in a Model 204 Online to view the contents of the journal. As of RKTools 7.7, SirScan functionality is also available in the RKWeb browser interface.

SirScan permits "ordinary" users to view journal entries generated by their own Online session, and it allows users in the ADMIN subsystem user class (SCLASS) to browse journal entries for any set of users.

The data displayed in SirScan may be filtered by date, time, IODEV, user (thread) number, and user ID string. In addition, you can request any combination of specific journal record types.

SirScan lets you view an ordinary journal data set or any member of a ring journal, including the offload data sets if they are not on tape. Even the current unflushed contents of the journal buffer(s) are included in the display, without you having to know what journal configuration is being used.

Updating the SirScan SCLASS maximums in SIRADMIN

The SIRSCAN application subsystem (APSY) is distributed with a setup screen that allows the subsystem manager to limit the amount of disk I/O generated by users of SirScan from each of the six subsystem user classes. This setup screen is part of the SIRADMIN subsystem, and it can only be altered by privileged users.

SirScan I/O and Record Caps

Each of the six SCLASS options is assigned a limit to the physical I/O permitted for each journal scan, and the maximum number of records SirScan will format for the user. The I/O settings prevent excessive amounts of disk activity during journal scans, and the record maximum prevents excessive use of CCATEMP. If the subsystem is semi-public, the default SCLASS value is treated the same as USER_LO for these limits.

A user's Model 204 privileges while in SirScan are based on the user's SCLASS. If they include System Administrator privileges, the user can view any journal entries; otherwise the user can view entries only for his or her own logon session.

You can change the SCLASS privileges with the subsystem management facility. The default SCLASS definitions allow users in USER_LO, USER_MED, and USER_HI to view information only for their own logon session, and allow users in ADMIN_LO, ADMIN_MED, and ADMIN_HI to view journal entries for any user.

See also

• SirScan
• SirScan setup
• SirScan scan specification
• SirScan browsing of the journal
• SirScan date processing