clearaudit

Non-clearmake build and shell command auditing facility for dynamic views

Applicability

Product

Command type

VersionVault

command

Platform

UNIX

Linux

Windows

Synopsis

  • UNIX and Linux:
    clearaudit [ [ –c ] shell_cmd ]
  • Windows:
    clearaudit [ [ /c ] shell_cmd ]

Description

Note: clearaudit is applicable to dynamic views only.

The clearaudit command runs an audited shell with the same view and working directory as the current process. MVFS files created within an audited shell (or any of its immediate children) are derived objects (DOs). When it exits, an audited shell creates a configuration record (CR) and associates it with each of the newly created DOs.

Note: clearaudit (as well as clearmake, omake, and Ant) monitors its child processes and assumes that a build is complete when those processes have run to completion. However, clearaudit does not monitor a process that has been spawned by a child process. Thus, if a "grandchild" process is active when its parent process exits, its contributions to the audit file are not captured and the configuration record will be incomplete. An audit session of a build step ends when the last process started directly by a VersionVault build tool exits. If a process started directly by a VersionVault build tool starts subprocesses, that process must ensure that its entire process hierarchy exits before exiting itself, if it wants the work performed by the entire process hierarchy to be included as part of the audit session.

The CR and DOs produced by clearaudit are similar to those created by clearmake. They can be listed, compared, and deleted with the same cleartool commands used for other DOs (see below). They can be shared with other views through explicit winkin commands, but they cannot be winked in by clearmake. They can be checked in as DO versions. For more information about configuration records, see the VersionVault Guide to Building Software.

clearaudit itself is not a shell. It starts an audit and then executes an underlying shell. clearaudit determines which shell to run as follows:

  • First choice: the value of environment variable CLEARAUDIT_SHELL, which must be the full path name of a program.
  • Second choice: the value of the UNIX and Linux environment variable SHELL, or the Windows environment variable COMSPEC. These environment variables must be set to the full path name of a program.
  • If no EV is set: the Bourne shell, /bin/sh (UNIX and Linux) or cmd.exe (Windows).

View context

On UNIX and Linux systems, the process from which you invoke clearaudit must have a view context: set view or working directory view. In either case, the audited process is set to that view. An error occurs if the invoking process has no view context or if its working directory view differs from its set view. (See the pwv reference page.)

On Windows systems as well, the process from which you invoke clearaudit must have a view context for the audited process. An error occurs if the invoking process has no view context.

Location of temporary build files

clearaudit creates temporary build files in the directory specified by the CCASE_AUDIT_TMPDIR environment variable. If this EV is not set or is set to an empty value, clearaudit creates temporary files in the directory specified as follows:

  • On UNIX and Linux systems, by the TMPDIR environment variable. If neither EV is set, clearaudit creates temporary files in the /tmp directory.
  • On Windows systems, by the TMP environment variable.

All temporary files are deleted when clearaudit exits. If the value of CCASE_AUDIT_TMPDIR is a directory under a VOB tag, clearaudit prints an error message and exits.

Auditing any process

clearaudit can be used to document the work performed by any process. For example, you can use clearaudit to audit the creation of a UNIX or Linux tar(1) file or a Windows backup operation, producing a configuration record that describes exactly which files and/or versions were archived.

Auditing a non-VersionVault make

You can also use clearaudit to produce derived objects and configuration records for software builds performed with another make program, such as make(1) on UNIX and Linux or nmake on Windows. Follow these guidelines:

  • On UNIX and Linux systems:
    • Set the value of SHELL to /opt/hcl/ccm/versionvault/bin/clearaudit in the makefile.
    • Set your process's CLEARAUDIT_SHELL environment variable to your normal shell, for example, /bin/sh. This prevents recursive invocation of clearaudit: if CLEARAUDIT_SHELL is not set, clearaudit attempts to start the shell specified in SHELL, which was set to clearaudit.
    • If you want to produce a single CR for each target's build script, structure your makefiles so that each build script is a single shell command. Use continuation lines (\) as necessary.
  • On Windows systems:
    • Set the value of COMSPEC to versionvault-home-dir\bin\clearaudit in the makefile.
    • Set your process's CLEARAUDIT_SHELL environment variable to your normal shell, for example,%SYSTEMROOT%\system32\cmd.exe. This prevents recursive invocation of clearaudit: if CLEARAUDIT_SHELL is not set, clearaudit attempts to start the shell specified in COMSPEC, which was set to clearaudit.
    • If you want to produce a single CR for each target's build script, structure your makefiles so that each build script is a single shell command. Use continuation lines (^) as necessary.

UNIX and Linux systems only: Auditing a shell script

A shell script that begins with the following line is executed in an audited shell:

#! /opt/hcl/ccm/versionvault/bin/clearaudit

Be sure that the process from which the script is invoked has CLEARAUDIT_SHELL set, as described above.

Options and arguments

–c (UNIX and Linux) or /c (Windows)
Most UNIX and Linux shells (including sh, csh, tcsh, and ksh) and some Windows shells (including cmd.exe), require the use of this option, which tells the shell what command to execute. This option must precede any shell_cmd arguments.
shell_cmd
One or more words, which are passed as arguments to $CLEARAUDIT_SHELL, $SHELL, or /bin/sh (UNIX and Linux); or to %CLEARAUDIT_SHELL%, %COMSPEC%, or cmd.exe (Windows).

Examples

  • On a UNIX or Linux system, run program myscr in an audited C shell.

    % env SHELL=/bin/csh clearaudit -c myscr

  • On a Windows system, run program validation_suite in an audited third-party shell tool.

    C:\> set CLEARAUDIT_SHELL= R:\MKSNT\mksnt\bin\sh.exe
    C:\> clearaudit /c validation_suite

  • This example shows a typical CR produced by clearaudit. It describes all files produced by a software build using make on UNIX or Linux. View-private files are marked with time stamps.

    Target ClearAudit_Shell built by block.user
    Host "starfield" running Linux 3.10.0-957.21.3.el7.x86_64 (x86_64)
    Reference Time 2007-05-16T10:24:08, this audit started
    2007-05-16T10:24:08
    View was starfield:/usr/people/block/cc_views/view.bl62
    Initial working directory was /vobs/doc/reference_man/test
    ----------------------------
    MVFS objects:
    ----------------------------
    /vobs/doc/reference_man/test/hello@@2007-05-16T10:25.16742
    /vobs/doc/reference_man/test/hello.c <2007-05-16T10:11:34>
    /vobs/doc/reference_man/test/hello.o@@2007-05-16T10:25.16740
    /vobs/doc/reference_man/test/makefile <2007-05-16T10:23:57>

  • On a Windows system, run a batch file that performs a backup in an audited shell; create an empty derived object (bkup_do) whose CR lists all of the backed-up objects.

    C:\> clearaudit /c audit_bkup C:\users e:
    Batch file audit_bkup:
    rem
    echo Audited backup of %1
    echo Backup destination is %2
    backup %1 %2 /s
    rem
    echo Creating derived object bkup_do
    echo "" > .\bkup_dofc