[an error occurred while processing this directive]

HP OpenVMS Systems Documentation
Content starts here

Compaq ACMS for OpenVMS
Managing Applications
Previous Contents Index

11.8 Summary of ACMSGEN Commands and Qualifiers

ACMSGEN commands allow you to change ACMS system parameters to define lower limits, quotas, process names, user names, proxy accounts, and priorities for components of ACMS. Table 11-4 lists the ACMSGEN commands and qualifiers and provides a brief description of each ACMSGEN command. For detailed information about ACMSGEN commands and qualifiers, see Chapter 22.

Table 11-4 Summary of ACMSGEN Commands
Commands and Qualifiers Description
EXIT Ends the ACMSGEN session and returns you to the DCL prompt.
HELP Displays help information about ACMSGEN commands, parameters, and qualifiers.
SET Places a new parameter value in the ACMSGEN work area.
SHOW
/ACC
/ALL
/CP
/EXC
/MSS
/QTI
/TSC 		Displays the value in the work area, the default value, the minimum value, the maximum value, the unit of measure, and the dynamic/fixed status for ACMS system parameters.
USE Initializes the ACMSGEN work area with values from a work file.
USE ACTIVE Initializes the ACMSGEN work area with active values for all parameters from an ACMS system global section.
USE CURRENT Initializes the ACMSGEN work area with current values for all parameters from the SYS$SYSTEM:ACMSPAR.ACM parameter file.
USE DEFAULT Initializes the ACMSGEN work area with ACMS default values for all ACMS parameters.
WRITE Writes values from the ACMSGEN work area to a work file, creating a new version of the file.
WRITE ACTIVE Changes active values for dynamic parameters by writing values from the ACMSGEN work area to an ACMS system global section.
WRITE CURRENT Changes current values by writing values from the ACMSGEN work area to the SYS$SYSTEM:ACMSPAR.ACMS file.

Chapter 12
Auditing Applications with the Audit Trail Logger

This chapter explains how to use the Audit Trail Logger (ATL) and the Audit Trail Report (ATR) Utility to monitor the use and misuse of your application. See Section 12.9 for a summary of ATR commands and qualifiers. For reference information on the commands described in this chapter, refer to Chapter 23.

12.1 Understanding the Audit Trail Logger

The Audit Trail Logger records application and user activity in the audit trail log. The Audit Trail Logger records:

  • ACMS system starts and stops
  • ACMS application starts and stops
  • User sign-ins and sign-outs
  • What tasks users run and where they encounter errors
  • What activities are taking place on distributed ACMS systems
  • User errors
  • Modifications to application, task, and server attributes
  • Server process dumps
  • Queued Task Initiator (QTI) process events
  • Server image replacement
  • Other significant events

The Audit Trail Logger is automatically started with the ACMS system. Disable the Audit Trail Logger by using the /NOAUDIT qualifier either on the ACMS/START SYSTEM command or the ACMS/SET SYSTEM command. When the Audit Trail Logger is disabled, it only records file opens and closes. Use the /AUDIT qualifier with either of these commands to reenable auditing.

Use the ATR Utility to display audit trail records or write them to an output file.

12.2 Using the Audit Trail Log File

Each time the ACMS system starts, it creates a new version of the audit trail log file. ACMS writes Audit Trail Logger information to the file SYS$ERRORLOG:ACMSAUDIT.LOG by default. The default protection for the audit trail log file is (S:RD,O:RWED,G:R). The Audit Trail Logger must have write access to the audit trail log file for you to start your ACMS system.

The Audit Trail Logger attempts to translate the following logical names, which you can define, and uses the values of the logical names for file allocation when ACMS creates the audit trail log file:

  • ACMS$ATL_DEQ_BLOCKS --- The default extension quantity (DEQ) specifies the number of blocks to be added when the file is extended. Valid values are 0 through 65535.
  • ACMS$ATL_ALQ_BLOCKS --- The allocation quantity (ALQ) specifies the number of blocks to be initially allocated when the log is created. Valid values are 0 through 4,294,967,295.

See the OpenVMS Record Management Services Reference Manual for additional information about these fields.

To write audit trail information to a different file on a disk or on a magnetic tape volume set, define the system logical name ACMS$AUDIT_LOG to point to that file. If you omit any parts of the file specification in defining the logical name, missing parts are supplied from SYS$ERRORLOG:ACMSAUDIT.LOG. For example, the following command defines the audit trail log file as ACMSAUDIT.LOG in the directory [ACMS.AUDIT] on SYS$DISK. The file name and file type are supplied by default. 


$ DEFINE/SYSTEM ACMS$AUDIT_LOG SYS$DISK:[ACMS.AUDIT]

Note the logical must be a system logical so that the Audit Trail Logger has access to it.

If you write audit trail information to a file on disk, take the steps needed to process audit trail log files as ACMS creates them. For example, you can purge audit trail log files or store them on a separate volume.

If the Audit Trail Logger runs out of space for audit trail information on disk, the audit trail logs the error in the software event log (generated by SWL), and the Audit Trail Logger process stops. ACMS sends a message to ACMS operator terminals. Restart the Audit Trail Logger process with the ACMS/SET SYSTEM /AUDIT command or the ACMS/RESET AUDIT command.

If you write audit trail information to a magnetic tape volume set, define the logical name ACMS$AUDIT_LOG to point to a file specification of the form:


MTxn:name.ext

The components of this file specification are:

  • MT --- Device type for a magnetic tape drive
  • x --- Controller code for the tape drive
  • n --- Unit number of the tape drive
  • name --- File name for the log file
  • ext --- File type for the log file

The following command defines ACMS$AUDIT_LOG to point to ACMSAUDIT.LOG on the magnetic tape mounted on the MTA0 device: 


$ DEFINE /SYSTEM ACMS$AUDIT_LOG MTA0:

The default file name and file type are taken from the file specification SYS$ERRORLOG:ACMSAUDIT.LOG.

If you write audit trail information to magnetic tape, load and initialize the magnetic tape before you start the ACMS system. If you do not, the ACMS/START SYSTEM command can time out before the initialization is complete. Initialize the magnetic tape with a volume name the same as the first six characters of the file name for the audit trail log file. For example: 


$ INIT MTA0: ACMSAU

If the file name is longer than six characters, the Audit Trail Logger truncates the volume name to six characters. Do not use the MOUNT command after initializing the tape. ACMS logically mounts the magnetic tape when it starts the Audit Trail Logger. If the tape is already mounted, ACMS returns a fatal error on the ACMS/START SYSTEM command.

If the Audit Trail Logger is logging information to magnetic tape, and the end of volume is encountered, OpenVMS sends a message to OpenVMS operator terminals asking the operator to mount the next volume in the volume set. The operator loads the tape on the drive, initializes and mounts the volume, and responds to the operator request with a DCL REPLY command. The Audit Trail Logger then logs information to the new volume.

Note
If the audit trail log file is being written to magnetic tape that runs out of space, ACMS may interrupt its work until a new tape is ready. OpenVMS operator terminals are informed that a new tape must be mounted. Eventually, terminal users do not get any system response. To avoid this problem, store your audit information on large magnetic tapes. Inspect the tape regularly to make sure that it is not full.

For information about magnetic tapes, see OpenVMS System Manager's Manual: Essentials. For information about the REPLY command, see the OpenVMS DCL Dictionary.

12.3 Events Recorded by the Audit Trail Logger

The Audit Trail Logger logs the following types of events:

  • Flagged events --- Events flagged when auditing is enabled using the application-level AUDIT clause or subclause, or with the AUDIT keyword in ACMS operator commands.
  • Default events --- Events that the Audit Trail Logger logs regardless of application definition or operator command. Table 12-1 marks default events in the "When Recorded" column with the word "Always".

Table 12-1 shows the events logged by the Audit Trail Logger, an explanation of recorded events, and the conditions under which events are recorded.

Table 12-1 Events Logged by the Audit Trail Logger
Events Recorded Explanation When Recorded
Abnormal terminations of applications Stopping of applications for any reason other than ACMS/STOP SYSTEM or ACMS/STOP APPLICATION commands Always
Abnormal terminations of server processes Stopping of server processes due to error Always
ACMS errors ACMS system internal errors Always
Application starts and stops Each use of ACMS/START APPLICATION and ACMS/STOP APPLICATION commands Always
Application modifications Each use of the ACMS/MODIFY APPLICATION command Application auditing enabled
Open new audit trail log file Each use of an ACMS/RESET AUDIT command Always
Enabling and disabling of the Audit Trail Logger Each use of the ACMS/SET SYSTEM, ACMS/START SYSTEM, or ACMS/STOP SYSTEM command to enable or disable the Audit Trail Logger Always
Enabling and disabling of ACMS operator terminals Each use of the ACMS/SET SYSTEM command to enable or disable ACMS operator terminal Always
Error allocating ACMS-controlled terminals Why an ACMS-controlled terminal was unable to be allocated by the ACMS terminal subsystem controller Always
Errors returned or signaled by cancel handling procedures Each error encountered by user-written cancel handlers Always
Errors returned or signaled on initialization and termination procedures Each error encountered by user-written initialization and termination procedures Always
Errors signaled by processing steps Each error signaled during a processing step Always
Failure to start a server process Why a server process failed to start Always
Sign-ins and sign-outs Who signed in to or out of ACMS and at what time Always
Queue starts and stops Each use of the ACMS/START QUEUE, or ACMS/STOP QUEUE commands Always
Queue modifications Each use of the ACMS/SET QUEUE command Always
Queued task failures Each error that caused the task invocation to fail Always
Server replacement Each use of the ACMS/REPLACE SERVER command Always
System starts and stops Each use of ACMS/START SYSTEM or ACMS/STOP SYSTEM command Always
Task calls Tasks called by other tasks Task subclause
Task chains Tasks chained to from another task Task auditing enabled
Task cancellations Tasks canceled by any method Task auditing enabled
Composed task transaction aborts When a composed task transaction was aborted Always
Task completions Completed tasks, who completed each task, and when Always
Task selections Each task selected by a user Task auditing enabled
User errors not elsewhere reported User errors, including errors ACMS cannot report back to the user Always
Submitter authentications in remote applications As a security measure, when a submitter first selects a task in a remote application, the submitter is authenticated by the application execution controller (ACC) on the submitter node Always

Use ATR commands to read the events recorded in the audit trail log file or to produce a report that lists the events. The following sections describe how to run the ATR Utility and use ATR commands.

12.4 Running the ATR Utility

Use either of the following commands to run ATR: 


$ RUN SYS$SYSTEM:ACMSATR
ATR>

or 


$ MCR ACMSATR
ATR>

You can also enter ATR Utility commands from DCL level by defining ATR as a DCL foreign command. For example: 


$ ATR:==$SYS$SYSTEM:ACMSATR

Place this command in your login command file to permanently define this foreign command. Once you define ATR as a DCL foreign command, you can use ATR commands from DCL. For example: 


$ ATR LIST /APPLICATION=EXEX_APPL /BEFORE=14-JAN-1991

When you see the ATR> prompt, enter ATR commands. Use the LIST command to display or list audit trail records. Use the HELP command to get information about ATR commands. For example: 


ATR> HELP LIST

Instead of typing ATR commands, you can use keypad keys to enter commands. Press [PF1] and [PF2] for access to the ATR keypad. Press [Ctrl/B] to recall the last 20 ATR commands you enter (one at a time).

When you are finished using the ATR Utility, type EXIT or press [Ctrl/Z] to return to DCL: 


ATR> EXIT
$

In DCL, get help information about the ATR Utility by using the following HELP command: 


$ HELP @ACMSATR

12.5 Creating Log Reports

The ATR Utility LIST command generates an ACMS log report consisting of records from the Audit Trail Logger. Include a file specification with the LIST command to identify a concatenated file containing several audit trail log files, or omit the file specification altogether. If you omit the file specification, ATR searches for a translation for the logical ACMS$AUDIT_LOG. If ACMS$AUDIT_LOG is not defined, ATR uses the default file specification, SYS$ERRORLOG:ACMSAUDIT.LOG.

12.5.1 Creating Full Log Reports

The LIST command with the /OUTPUT qualifier writes full Audit Trail Logger reports to a listing file. If you do not use the /OUTPUT qualifier, the ATR Utility displays information on the terminal.

Example 12-1 provides an sample log report containing a full version of each record in the audit trail log file. Instead of displaying the entire log file on your terminal as shown here, use the /OUTPUT qualifier to send the output to a listing file.

Example 12-1 ATR LIST Command 

ATR> LIST

(1)     ACMS Log Report   5-JAN-1991  (2)10:08:08.83
     Type   : ALL
     Since  : *
     Before : *
     Appl   : *
     Task   : *         (3)
     ID     : *
     User   : *
     Sub    : *
     Term   : *
(4)    File   : SYS$SYSROOT:[SYSERR]ACMSAUDIT.LOG;3

     ************************************************************
(5)    Type   : TASK  (6)  Time   :  1-JAN-1991 12:16:55.00
(7)    Appl   : TEST
(8)    Task   : TSK1M2
(9)    User   : LTUSER2
(10)   ID     : CARAT::00010036-00000001-47E6F8C0-008DDDDE
(11)   Sub    : CARAT::00010036-00000000-47E6F8C0-008DDDDE
(12)   Text   : Task started
     ************************************************************)

     Type   : TASK      Time   :  1-JAN-1991 12:17:19.06
     Appl   : TEST
     Task   : TSK1M2
     User   : LTUSER2
     ID     : CARAT::00010036-00000001-47E6F8C0-008DDDDE
     Sub    : CARAT::00010036-00000000-47E6F8C0-008DDDDE
     Text   : Task end
     Task completion status:  Task completed normally
     ************************************************************
(13)     End Report   1-JAN-1991 13:09:01.41

The following is a description of the numbered items in Example 12-1.

  1. ACMS Log Report
    The name of the report.
  2. Date and time
    The date and starting time for processing the report.
  3. The criteria for selecting the records in the report. An asterisk (*) indicates that you did not use a criterion to select records. "ALL" indicates that you did not select records by record type.
  4. File
    The information included to identify the source file, including the file name or file specification.
  5. Type
    The type of information in the record.
  6. Time
    The time the record was created.
  7. Appl
    The application name for an active task.
  8. Task
    The name of the active task.
  9. User
    The OpenVMS user name of the user who submitted the task.
  10. ID
    The ACMS task identification code for one task instance.
  11. Sub
    The ACMS task submitter identification code for an ACMS user running a task.
  12. Text
    A description of the event recorded.
  13. End Report
    The date and time that report processing concluded.

12.5.2 Creating Brief Log Reports

The /BRIEF qualifier limits how much information is included in the report. Each record in a brief report contains the time of the entry in the Audit Trail Logger and the type of information in the entry. For information about record types, see the description of the /TYPE qualifier. The default is to include full records in the report. Example 12-2 provides an example of an ACMS log report containing a brief version of each record in the Audit Trail Logger.

Example 12-2 ATR LIST/BRIEF Command 

ATR> LIST/BRIEF

(1)       ACMS Log Report   5-JAN-1991 (2)  10:01:02.74
       Type   : ALL
       Since  : *
       Before : *
       Appl   : *
       Task   : *          (3)
       ID     : *
       User   : *
       Sub    : *
       Term   : *
(4)       File   : SYS$ERRORLOG:RWGAUDIT.LOG;3
       ************************************************************
       Type   : OTHER     Time   :  1-JAN-1991 11:57:35.03
       Type   : COMMAND   Time   :  1-JAN-1991 11:57:42.97
       Type   : COMMAND   Time   :  1-JAN-1991 11:59:05.42
       Type   : LOGIN     Time   :  1-JAN-1991 11:59:34.61
       Type   : LOGIN     Time   :  1-JAN-1991 11:59:35.63
       Type   : LOGIN     Time   :  1-JAN-1991 11:59:42.04
       Type   : LOGIN     Time   :  1-JAN-1991 11:59:43.05
       Type   : TASK      Time   :  1-JAN-1991 12:00:55.00
       Type   : TASK      Time   :  1-JAN-1991 12:00:55.92      (5)
       Type   : TASK      Time   :  1-JAN-1991 12:01:06.52
       Type   : TASK      Time   :  1-JAN-1991 12:01:09.39
       Type   : LOGIN     Time   :  1-JAN-1991 12:02:15.76
       Type   : TASK      Time   :  1-JAN-1991 12:02:16.53
       Type   : TASK      Time   :  1-JAN-1991 12:02:18.22
       Type   : LOGIN     Time   :  1-JAN-1991 12:02:19.82
       Type   : TASK      Time   :  1-JAN-1991 12:02:19.87
       Type   : LOGIN     Time   :  1-JAN-1991 12:02:19.98
       Type   : TASK      Time   :  1-JAN-1991 12:02:20.81
       Type   : TASK      Time   :  1-JAN-1991 12:02:22.15

(6)       End Report   5-JAN-1991 10:01:58.42

A brief log report consists of a header and one or more records. The following is a description of the numbered items in Example 12-2.

Previous Next Contents Index