SirScan setup: Difference between revisions

From m204wiki
Jump to navigation Jump to search
m (link repair)
m (minor formatting)
Line 4: Line 4:
<!-- Page name: SirScan setup-->
<!-- Page name: SirScan setup-->


As of Model&nbsp;204 V7.5, the functions and facilities necessary to run <var class="product">SirScan</var> are built into the Model&nbsp;204 kernel. For versions of Model 204 before 7.5, the installation of the <var class="product">[[Sirius Mods]]</var> is required and sufficient to install and run the SIRSCAN subsystem, the <var class="product">SirScan</var> engine.
As of Model&nbsp;204 V7.5, the functions and facilities necessary to run <var class="product">SirScan</var> are built into the Model&nbsp;204 kernel. For versions of Model 204 before 7.5, the installation of the <var class="product">[[Sirius Mods]]</var> is required and sufficient to install and run the <code>SIRSCAN</code> subsystem, the <var class="product">SirScan</var> engine.


In addition, optimal results using <var class="product">SirScan</var> require your attention to the settings of:
In addition, optimal results using <var class="product">SirScan</var> require your attention to the settings of:
Line 10: Line 10:
<li>The Model&nbsp;204 system parameters <var>SCANTIME</var> and <var>SCANPARM</var> </li>
<li>The Model&nbsp;204 system parameters <var>SCANTIME</var> and <var>SCANPARM</var> </li>


<li>The SIRSCAN subsystem user <var>SCLASS</var> controls </li>
<li>The <code>SIRSCAN</code> subsystem user <var>SCLASS</var> controls </li>
</ul>
</ul>


Line 20: Line 20:


===Background===
===Background===
The Model 204 journal records contain only a user
The Model&nbsp;204 journal records contain only a user
number and do not contain other potentially useful identifying information,
number and do not contain other potentially useful identifying information, such as user ID, terminal ID, or IP address.
such as user ID, terminal ID, or IP address.
So when <var class="product">SirScan</var> scan specifications in the <code>SIRSCAN</code> subsystem are
So when <var class="product">SirScan</var> 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
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.
requested attributes or not.


Line 31: Line 29:
would only work for currently logged on threads, and then only for journal
would only work for currently logged on threads, and then only for journal
entries from the current session.
entries from the current session.
This is because, for logged in users, <var class="product">SirScan</var> can determine user number
This is because, for logged in users, <var class="product">SirScan</var> can determine user number and login time.
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.
From these two pieces of information, it can be sure that all journal entries
for the thread associated with a requested userid, and with a date/time stamp
after the login time of the user, are associated with that user.


Outside of being very limiting &mdash; it was impossible to select journal
Outside of being very limiting &mdash; it was impossible to select journal
Line 41: Line 36:
produce anomalous behavior in [[SirScan browsing of the journal#autoref|auto-refresh mode]].
produce anomalous behavior in [[SirScan browsing of the journal#autoref|auto-refresh mode]].
Because <var class="product">SirScan</var> only collects data from the previous end of the interval
Because <var class="product">SirScan</var> 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
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.
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
Outside of the annoyance of not seeing the expected data, this could cause
confusion among <var class="product">SirScan</var> end-users, because a user's journal entries might
confusion among <var class="product">SirScan</var> end-users, because a user's journal entries might seem to suddenly stop without a logoff record or any other hint as to why.
seem to suddenly stop without a logoff record or any other hint as to why.


In later versions, <var class="product">SirScan</var> made more of an effort to use information in the journal to associate journal
In later versions, <var class="product">SirScan</var> made more of an effort to use information in the journal to associate journal
Line 56: Line 47:


In a similar way, <var class="product">SirScan</var> could use the MSIR.0114 message, which indicates
In a similar way, <var class="product">SirScan</var> could use the MSIR.0114 message, which indicates
a Janus port and client IP address for any Janus server request, to associate
a Janus port and client IP address for any Janus server request, to associate a thread number with an IP address and port name.
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 <var class="product">SirScan</var>'s behavior even more anomalous and confusing:
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 <var class="product">SirScan</var>'s behavior even more anomalous and confusing:
whether or not a journal record is selected might depend on whether or not
whether or not a journal record is selected might depend on whether or not
<var class="product">SirScan</var> 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.
<var class="product">SirScan</var> 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.
But if the selected interval was 8:37 to 9:30, they are all seen.


To fix the anomalous behaviors, <var class="product">SirScan</var> now uses
To fix the anomalous behaviors, <var class="product">SirScan</var> now uses "heartbeat" messages: RK type audit messages that contain
"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.
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 <var>SCANTIME</var> system parameter. And the <var>SCANPARM</var> parameter ensures <var class="product">SirScan</var>'s detection of the login of <var class="product">[[Janus Web Server]]</var> threads.  
The heartbeat messages are controlled by the <var>SCANTIME</var> system parameter. And the <var>SCANPARM</var> parameter ensures <var class="product">SirScan</var>'s detection of the login of <var class="product">[[Janus Web Server]]</var> threads.  
Line 127: Line 114:
be a good starting point.
be a good starting point.


If you are setting <var>SCANTIME</var> for the first time in an Online, it is prudent
If you are setting <var>SCANTIME</var> 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%).
to anticipate a 3% increase in journal usage, though the actual increase
<blockquote class="note"><b>Note:</b> The heartbeat message can even be useful outside of <var class="product">SirScan</var>. Since the heartbeat messages are regular RK type messages, they can be viewed with [[Tracking system activity (CCAJRNL, CCAAUDIT, CCAJLOG)#AUDIT204 utility|AUDIT204]] as well as <var class="product">SirScan</var>.
will almost undoubtedly be much less than that (probably less than
even 1%).
<blockquote class="note"><b>Note:</b> The heartbeat message can even be useful outside of <var class="product">SirScan</var>. Since the heartbeat messages are regular RK type messages, they can be viewed with AUDIT204 as well as <var class="product">SirScan</var>.
<p>
<p>
This means that if one is using AUDIT204 for a previous run's journal,
This means that if one is using AUDIT204 for a previous run's journal,
Line 152: Line 136:
<table class="thJustBold">
<table class="thJustBold">
<tr><th>X'01'</th>
<tr><th>X'01'</th>
<td>Allow non-system-manager users to browse journal entries for public requests on <var class="product">[[Janus Web Server]]</var> threads. Public requests are those that are not protected from access by userid.</td></tr>
<td>Allow non-system-manager users to browse journal entries for public requests on <var class="product">[[Janus Web Server]]</var> threads. Public requests are those that are not protected from access by user ID.</td></tr>


<tr><th>X'02'</th>
<tr><th>X'02'</th>
Line 163: Line 147:


==SIRSCAN subsystem definition==
==SIRSCAN subsystem definition==
<var class="product">SirScan</var> is a full-screen utility (the SIRSCAN [[Application Subsystem development|subsystem]]) that allows users in a <var class="product">Model 204</var>
<var class="product">SirScan</var> is a full-screen utility (the <code>SIRSCAN</code> [[Application Subsystem development|subsystem]]) that allows users in a <var class="product">Model 204</var>
Online to browse the contents of the journal.
Online to browse the contents of the journal.
<var class="product">SirScan</var> permits
<var class="product">SirScan</var> permits
"ordinary" users to view journal entries generated by their own
"ordinary" users to view journal entries generated by their own
Online session, and it allows users in the <var>ADMIN</var> [[Application Subsystem development#User class|subsystem user class (SCLASS)]] to browse journal entries for any set of users.
Online session, and it allows users in the <var>ADMIN</var> [[Application Subsystem development#User class|subsystem user class (<var>SCLASS</var>)]] to browse journal entries for any set of users.


The data displayed in <var class="product">SirScan</var> may be filtered by
The data displayed in <var class="product">SirScan</var> may be filtered by date, time, <var>IODEV</var>, user (thread) number, and user ID string.
date, time, <var>IODEV</var>, User (thread) number and UserID.
In addition, you can request any combination of specific journal record types.
In addition, you can request any combination of specific journal record types.


<var class="product">SirScan</var> lets you view an ordinary journal dataset 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
<var class="product">SirScan</var> lets you view an ordinary journal dataset 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
buffer(s) are included in the display, without you having to know
what journal configuration is being used.
what journal configuration is being used.


===Updating the SirScan SCLASS maximums in SIRADMIN===
===Updating the SirScan SCLASS maximums in SIRADMIN===
The SIRSCAN application subsystem (APSY) is distributed with a setup
The <code>SIRSCAN</code> 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 <var class="product">SirScan</var> from each of the six subsystem user classes.
screen that allows the subsystem manager to limit the amount of disk
This setup screen is part of the <code>SIRADMIN</code> subsystem, and it can only be altered by privileged users.  
I/O generated by users of <var class="product">SirScan</var> from each of the six subsystem user classes.
This setup screen is part of SIRADMIN, and can only be altered by privileged users.  


<p class="caption" style="width:428px">SirScan I/O and Record Caps</p>
<p class="caption" style="width:428px">SirScan I/O and Record Caps</p>
<p class="figure">[[File:ScanSCLASS.png|428px]]</p>
<p class="figure">[[File:ScanSCLASS.png|428px]]</p>


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


A user's <var class="product">Model 204</var> privileges while in <var class="product">SirScan</var> are based on the user's <var>SCLASS</var>.
A user's <var class="product">Model 204</var> privileges while in <var class="product">SirScan</var> are based on the user's <var>SCLASS</var>.
Line 201: Line 177:
You can change the <var>SCLASS</var> privileges with the subsystem management facility. The default <var>SCLASS</var> definitions
You can change the <var>SCLASS</var> privileges with the subsystem management facility. The default <var>SCLASS</var> definitions
allow users in <var>USER_LO</var>, <var>USER_MED</var>, and <var>USER_HI</var> to view information only
allow users in <var>USER_LO</var>, <var>USER_MED</var>, and <var>USER_HI</var> to view information only
for their own logon session, and allow users in <var>ADMIN_LO</var>, <var>ADMIN_MED</var>, and
for their own logon session, and allow users in <var>ADMIN_LO</var>, <var>ADMIN_MED</var>, and <var>ADMIN_HI</var> to view journal entries for any user.
<var>ADMIN_HI</var> to view journal entries for any user.


==See also==
==See also==

Revision as of 23:31, 3 November 2015


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 browse the contents of the journal. 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 dataset 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