Chapter 26 BSM Services Reference

This chapter describes the important components of the BSM module, auditing and device allocation.

Auditing helps you detect potential security breaches by revealing suspicious or abnormal patterns of system usage. Auditing also provides a means to trace suspect actions back to a particular user, thus serving as a deterrent. If users know that their activities are likely to be audited, they might be less likely to attempt malicious activities.

This is a list of the reference information in this chapter.

• Audit Commands

• Audit Files

• Audit Flags

• Audit Policies

• Process Audit Characteristics

• Audit Trail

• Audit Record Structure

• Audit Token Formats

• Device Allocation Reference

Audit Commands

This section provides information about the commands that are used with the auditing service.

The Audit Daemon

The following list summarizes what the audit daemon, auditd, does.

• auditd opens and closes audit log files in the directories that are specified in the audit_control file, in the order in which they are specified.

• auditd reads audit data from the kernel and writes it to an audit log file.

• auditd executes the audit_warn script when the audit directories fill past limits that are specified in the audit_control file. The script, by default, sends warnings to the audit_warn mail alias and to the console.

• By default, when all audit directories are full, processes that generate audit records are suspended. In addition, the auditd command writes a message to the console and to the audit_warn mail alias. The audit policy can be reconfigured with the auditconfig. At this point, only the system administrator can log in to write audit files to tape, delete audit files from the system, or do other cleanup.

The auditd daemon can be started automatically when the machine is brought up to multiuser mode, or you can start it from the command line. When the audit daemon is started, it determines the amount of free space necessary for audit log files.

The daemon uses the list of audit directories in the audit_control file as possible locations for creating audit files. The audit daemon maintains a pointer into this list of directories, starting with the first directory. Every time the audit daemon needs to create an audit file, it puts the file into the first available directory in the list, starting at the audit daemon's current pointer. You can reset the pointer to the beginning of the list by running the audit -s command. When you use the audit -n command to instruct the daemon to switch to a new audit file, the new file is created in the same directory as the current file.

The audit Command

The audit command controls the actions of the audit daemon. The audit command can do the following tasks:

• Enable and disable auditing

• Reset the audit daemon

• Adjust the auditing preselection mask on the local machine

• Write audit records to a different audit log file

See the audit(1M) man page for a discussion of the available options.

The auditreduce Command

Use the auditreduce command to merge audit records from one or more input audit files or to perform a post selection of audit records. See the auditreduce(1M) man page. To merge the entire audit trail, you can run this command on the machine on which all the audit file systems for the installation are mounted.

The auditreduce command enables you to track all auditable actions on multiple machines from a single location. If you identically configure all machines at an installation for auditing, and create servers and local directories for the audit log files, then the auditreduce command can read the logical combination of all audit files in the installation as a single audit trail. auditreduce ignores how the records were generated or where they are stored. Without options, the auditreduce command merges audit records from all the audit files in all of the subdirectories in the audit root directory (/etc/security/audit) and sends the result to standard output. You can also place it into a single, chronologically ordered output file. The file contains binary data.

The auditreduce command also can select particular types of records for analysis. The merging and selecting functions of auditreduce are logically independent. auditreduce captures data from the input files as the records are read, before the files are merged and written to disk.

The praudit command makes the binary output of auditreduce readable.

By specifying options to the auditreduce command, you can also do the following:

• Request audit records that were generated by only certain audit flags

• Request audit records that were generated by one particular user

• Request audit records that were generated on specific dates

With no arguments, auditreduce checks the subdirectories within the /etc/security/audit directory, the default audit root directory. The command checks for a files directory in which the start-time.end-time.hostname files reside. The auditreduce command is very useful when the audit data for different hosts (Figure 26–1) or for different audit servers (Figure 26–2) reside in separate directories.

Figure 26–1 Audit Trail Storage Sorted by Host

Figure 26–2 Audit Trail Storage Sorted by Server

When you do not store audit data in the default directory, perhaps because the partition for /etc/security/audit is very small, you can pass the auditreduce command another directory by using the -R option:

# auditreduce -R /var/audit-alt 

You can also specify a particular subdirectory by using the -S option:

# auditreduce -S /var/audit-alt/host1 

You can direct auditreduce to process only certain audit log files by specifying them as command arguments:

# auditreduce /var/audit/egret/files/2001*.2001*egret

For other options and additional examples, see the auditreduce(1M) man page.

The praudit Command

The praudit command reads audit records in binary format from standard input and displays the records in a presentable format. The input can be piped from the auditreduce command or from a single audit file. Input can also be produced with the cat command to concatenate several files, or the tail command for a current audit file.

The praudit command can generate four output formats:

• Default – The default option displays one audit token per line. The default option displays the audit event by its description, such as ioctl(2), and displays any value that could be text in text format. For example, a user is displayed as the user name, not as the user ID.

• –l option – The long option displays one audit record per line. The -d option changes the delimiter used between token fields, and between tokens. The default delimiter is a comma.

• –r option – The raw option displays any value that could be numeric as a number. For example, a user is displayed by user ID, Internet addresses are in hexadecimal format, and modes are in octal format. The audit event is displayed as its event number, such as 158.

• –s option – The short option displays the audit event by its table name, for example, AUE_IOCTL. The option displays the other tokens as the default option displays them.

In the default output format of praudit, each record is easily identified as a sequence of audit tokens where each token is on a separate line. Each record begins with a header token. You could, for example, further process the output with the awk command.

Here is the default output from the praudit command for a header token:

header,240,1,ioctl(2),es,Tue Sept  7 16:11:44 1999, + 270 msec

Here is the output from the praudit -r command for the same header token:

20,240,1,158,0003,699754304, + 270 msec

Sometimes, you might want to manipulate output from the praudit command as lines of text. For example, you might want to select records that the auditreduce command cannot select. You can use a simple shell script to process the output of praudit. The following simple example script marks the header tokens by prefixing them with Control-A, combines all the audit tokens for one record onto one line while preserving the line breaks as Control-A, runs the grep command, and restores the original newline breaks.

#!/bin/sh
praudit | sed -e '1,2d' -e '$s/^file.*$//' -e 's/^header/^aheader/' \\
| tr '\\012\\001' '\\002\\012' \\
| grep "$1" \\
| tr '\\002' '\\012'

Note that the ^a in the script is Control-A, not the two characters ^ and a. The prefix distinguishes the header token from the string header that might appear as text.

The auditconfig Command

The auditconfig command provides a command-line interface to retrieve and set audit configuration parameters. See the auditconfig(1M) man page. Options to the auditconfig command include the following:

-chkconf

Checks the configuration of kernel event-to-class mappings and reports any inconsistencies

-conf

Reconfigures kernel event-to-class mappings at runtime to match the current mappings in the audit_event file.

-getcond

Retrieves the state of auditing on the machine. The following table shows the possible responses.

Table 26–1 Possible Auditing Conditions

Response	Meaning
auditing	Auditing is enabled and turned on.
no audit	Auditing is enabled, but the audit daemon is not running.
disabled	Auditing is not enabled.

-setcond condition

Sets the state of auditing on the machine to one of auditing or noaudit.

-getclass event_number

Retrieves the preselection classes to which the specified event is mapped.

-setclass event_number audit_flags

Sets the preselection classes to which the specified event is mapped.

-lsevent

Displays the currently configured (runtime) kernel and user audit event information.

-getpinfo pid

Retrieves the audit ID, preselection mask, terminal ID, and audit session ID of the specified process.

-setpmask pid flags

Sets the preselection mask of the specified process.

-setsmask asid flags

Sets the preselection mask of all processes with the specified audit session ID.

-setumask auid flags

Sets the preselection mask of all processes with the specified user audit ID.

-lspolicy

Displays the list of audit policies with a short description of each policy.

-getpolicy

Shows the current audit policy flags.

-setpolicy policy_flag[,policy_flag]

Sets the audit policy flags to the specified policies (see Determining Which Audit Policies to Use).

Audit Files

Auditing uses the following files:

• The /etc/system File

• The audit_class File

• The audit_control File

• The audit_data File

• The audit_event File

• The audit_startup Script

• The audit_user File

• The audit_warn Script

The /etc/system File

The /etc/system file contains commands that the kernel reads during initialization to customize the system operations. The bsmconv and bsmunconv shell scripts, which are used to activate and deactivate auditing, modify the /etc/system file. The bsmconv shell script adds the following lines to the /etc/system file:

set c2audit:audit_load=1
set abort_enable=0

The first command causes the c2audit loadable kernel module (auditing module) to be loaded when the system is booted. The second command disables the use of the Stop-A keyboard sequence. The Stop-A keyboard sequence halts the system and can invoke a debugger, which could be a security breach. The bsmunconv shell script removes these lines, which results in auditing being disabled when the system is rebooted.

The audit_class File

The audit_class file contains definitions of the existing audit classes. Audit classes are groups of audit events. Each class has an associated audit flag, which is the short name that stands for the class. You use the short name in the audit_control file, optionally with a + or – prefix, to preselect the classes whose events you want to audit. The root user, or an administrator in an equivalent role, can define new audit classes, rename existing classes, or otherwise edit existing classes by using vi, ed, or some other editor. See the audit_class(4) man page for more information. For descriptions of the audit flags, see Definitions of Audit Flags.

The audit_control File

An audit_control file on each machine is read by the audit daemon (see the audit_control(4) man page). The audit_control file is located in the /etc/security directory. Each machine has its own local audit_control file so that every machine can mount their audit file systems from different locations or in a different order. For example, the primary audit file system for machineA might be the secondary audit file system for machineB.

You specify four kinds of information in the audit_control file:

• The audit flags line (flags:) contains the audit flags that preselect which classes of events are audited for all users on the machine. The audit flags specified here are referred to as the machine-wide audit flags or the machine-wide audit preselection mask. Audit flags are separated by commas, with no spaces.

• The nonattributable flags line (naflags:) contains the audit flags that preselect which classes of events are audited when an action cannot be attributed to a specific user. The flags are separated by commas, with no spaces.

• The audit threshold line (minfree:) defines the minimum free-space level for all audit file systems. The minfree percentage must be greater than or equal to 0. The default is 20 percent.

• The directory definition lines (dir:) define which audit file systems and directories the machine will use to store its audit log files. You can define one or more directory definition lines. The order of the dir: lines is significant. The auditd daemon creates audit files in the directories in the specified order (see the audit(1M) man page). The first directory is the primary audit directory for the machine. The second directory is the secondary audit directory where the audit daemon creates audit trail files when the first directory becomes full, and so forth.

You create an audit_control file during the configuration process on each machine.

When you make changes to the audit_control file, you then run the audit -s to instruct the audit daemon to reread the file.

The audit -scommand does not change the preselection mask for existing processes. Use auditconfig, setaudit (see the getuid(2) man page), or auditon for existing processes.

Sample audit_control File

The following is a sample audit_control file for the machine dopey. dopey uses two audit file systems on the audit server blinken, and a third audit file system that is mounted from the second audit server winken. The third file system is used only when the audit file systems on blinken become full or unavailable. The minfree value of 20 percent specifies that the warning script is run when the file systems are 80 percent filled and the audit data for the current machine will be stored in the next available audit directory, if any (see the audit_warn(1M) man page). The flags specify that all logins and administrative operations are to be audited (whether or not they succeed), and that failures of all types, except failures to create a file system object, are to be audited.

flags:lo,ad,-all,^-fc
naflags:lo,nt
minfree:20
dir:/etc/security/audit/blinken/files
dir:/etc/security/audit/blinken.1/files
#
# Audit filesystem used when blinken fills up
#
dir:/etc/security/audit/winken 

The audit_data File

When the auditd daemon starts on each machine, it creates the file /etc/security/audit_data. The format of the file consists of a single entry with the two fields separated by a colon (see the audit_data(4) man page). The first field is the audit daemon's process ID. The second field is the path name of the audit file to which the audit daemon is currently writing audit records. Here is an example:

# cat /etc/security/audit_data
116:/etc/security/audit/blinken.1/files/19990320100002.not_terminated.dopey

The audit_event File

The audit_event file, located in the /etc/security directory, contains the default event-to-class mappings (see the audit_event(4) man page). You can edit this file to change the class mappings. However, if you do so, you must reboot the system or run auditconfig -conf to read the changed mappings into the kernel.

The audit_startup Script

Auditing is enabled by starting the audit daemon, auditd. You can start the audit daemon by executing /usr/sbin/auditd as root or in an equivalent role. See the auditd(1M) man page.

The existence of the file /etc/security/audit_startup causes the audit daemon to be run automatically when the system enters multiuser mode. This file is an executable script that is invoked as part of the startup sequence, just prior to the execution of the audit daemon (see the audit_startup(1M) man page). A default audit_startup script that automatically configures the event-to-class mappings and sets the audit policies is created during the BSM package installation.

The audit_user File

To audit some users differently from others, you can edit the audit_user file to add audit flags for individual users. If specified, these flags are combined with the system-wide flags in the audit_control file to determine which classes of events to audit for that user. The flags that you add to the user's entry in the audit_user file modify the defaults from the audit_control file in two ways:

• By specifying a set of event classes that are never to be audited for this user

• By specifying a set of event classes that are always to be audited for this user

Each user entry in the audit_user file contains three fields.

• The username field

• The always-audit field

• The never-audit field

The audit fields are processed in sequence. Auditing is enabled by the always-audit field and turned off by the never-audit field.

Avoid the common mistake of leaving the all audit flag in the never-audit field. This mistake causes all auditing to be turned off for that user, which overrides the flags that are set in the always-audit field.

Using the never-audit flags for a user is not the same as removing classes from the always-audit set. For example, suppose you want to audit everything for user tamiko for except for successful reads of file system objects. This strategy audits almost everything for a user, while generating only about three-quarters of the audit data that would be produced if all data reads were audited. You also want to apply the system defaults to tamiko. Here are two possible audit_user entries:

The correct entry:

tamiko:all,^+fr:

The incorrect entry:

tamiko:all:+fr

The first example means, “always audit everything except for successful file-reads.” The second example means, “always audit everything, but never audit successful file-reads.” The second example is incorrect because it overrides the system default. The first example achieves the desired effect: the system defaults apply, as well as what is specified in the audit_user entry.

Successful events and failed events are treated separately, so a process can generate more audit records when an error occurs than when an event is successful.

The audit_warn Script

Whenever the audit daemon encounters an unusual condition while writing audit records, it invokes the /etc/security/audit_warn script. See the audit_warn(1M) man page. You can customize this script for your site to warn of conditions that might require manual intervention, or you could specify how to handle them automatically. For all error conditions, audit_warn writes a message to the console and sends a message to the audit_warn mail alias. You should set up this alias when you enable auditing.

When audit daemon detects the following conditions, it invokes the audit_warn script.

• An audit directory has become more full than the minfree value allows. The minfree value or soft limit is a percentage of the space available on an audit file system.

  The audit_warn script is invoked with the string soft and the name of the directory whose available space has gone below the minimum value. The audit daemon switches automatically to the next suitable directory and writes the audit files there until this new directory reaches its minfree limit. The audit daemon then goes to each remaining directory in the order that is listed in the audit_control file, and writes audit records until each directory is at its minfree limit.

• All the audit directories have reached the minfree threshold.

  The audit_warn script is invoked with the string allsoft. A message is written to the console and mail is sent to the audit_warn alias.

  When all audit directories that are listed in the audit_control file have reached their minfree threshold, the audit daemon switches back to the first directory, and writes audit records until the directory becomes completely full.

• An audit directory has become completely full with no space remaining.

  The audit_warn script is invoked with the string hard and the name of the directory. A message is written to the console and mail is sent to the audit_warn alias.

  The audit daemon switches automatically to the next suitable directory with any space available, if any. The audit daemon goes to each remaining directory in the order that is listed in the audit_control file, and writes audit records until each directory is full.

• All the audit directories are completely full. The audit_warn script is invoked with the string allhard as an argument.

  In the default configuration, a message is written to the console and mail is sent to the audit_warn alias. The processes that generate audit records are suspended. The audit daemon goes into a loop, waiting for space to become available, and resumes processing audit records when that happens. While audit records are not being processed, no auditable activities occur. Every process that attempts to generate an audit record is suspended. For this reason, you should set up a separate audit administration account that could operate without any auditing enabled. Then, you could continue operations without being suspended.

• An internal error occurs, such as:

  • Another audit daemon process is already running (string ebusy)

  • A temporary file cannot be used (string tmpfile)

  • The auditsvc() system call fails (string auditsvc)

  • A signal was received during auditing shutdown (string postsigterm)

  Mail is sent to the audit_warn alias.

• A problem is discovered with the syntax of the audit_control file. By default, mail is sent to the audit_warn alias and a message is sent to the console.

Audit Flags

Audit flags indicate classes of events to audit. Machine-wide defaults for auditing are specified for all users on each machine by flags in the audit_control file, which is described in The audit_control File.

You can modify what is audited for individual users by putting audit flags in a user's entry in the audit_user file. The audit flags are also used as arguments to the auditconfig command (see the auditconfig(1M) man page).

Definitions of Audit Flags

The following table shows each predefined audit class with the audit flag (which is the short name that stands for the class), the long name, and a short description. You use these audit flags in the auditing configuration files to specify which classes of events to audit. You can define new classes and rename existing classes by modifying the audit_class file (see the audit_class(4) man page).

Audit Flag Syntax

The prefixes determine whether a class of events is audited whether it succeeds or fails, or only if it succeeds, or only if it fails. Here is the format of the audit flag:

prefixflag

The following table shows prefixes that specify whether the audit class is audited for success or failure, or both.

For example, the audit flag lo (without any prefix) means that auditing should occur for “all successful attempts to log in and log out, and all failed attempts to log in.” You cannot fail an attempt to log out. As another example, the -all flag means that auditing should occur only for all failed attempts of any kind. The +all flag means that auditing should only occur for all successful attempts of any kind.

The -all flag can generate large amounts of data and fill up audit file systems quickly. Use the -all flag only if you have extraordinary reasons to audit all activities.

Prefixes to Modify Audit Flags

Use the following prefixes in any of three ways:

• In the flags line in the audit_control file to modify already specified flags

• In flags field in the user's entry in the audit_user file

• With arguments to the auditconfig command

See the auditconfig(1M) man page.

The prefixes in the following table, along with the short names of audit classes, turn on or turn off previously specified audit classes.

The ^- prefix is used in the flags line in the following example from an audit_control file.

In the following example, the lo and ad flags specify that all logins and administrative operations are to be audited when they succeed and when they fail. The -all means audit “all failed events.” Because the ^- prefix means “turn off auditing for the specified class for failed attempts,” the ^-fc flag modifies the previous flag that specified the auditing of all failed events. The two fields together mean: “audit all failed events, except for failed attempts to create file system objects.”

flags:lo,ad,-all,^-fc

Audit Policies

Audit policies determine if additional tokens or information is added to the audit trail. Each policy is defined in Determining Which Audit Policies to Use.

Process Audit Characteristics

The following audit characteristics are set at initial login:

• Process preselection mask – When a user logs in, the login command combines the machine-wide audit flags from the audit_control file with the user-specific audit flags (if any) from the audit_user file, to establish the process preselection mask for the user's processes. The process preselection mask specifies whether events in each audit event class are to generate audit records.

  The algorithm for obtaining the process preselection mask is as follows: the audit flags from the flags: line in the audit_control file are added to the flags from the always-audit field in the user's entry in the audit_user file. Then, the flags from the never-audit field from the user's entry in the audit_user file are subtracted from the total, as follows:

  user's process preselection mask = (flags: line + always audit flags) - never audit flags

• Audit ID – A process also acquires its audit ID when the user logs in. This audit ID is inherited by all child processes that were started by the user's initial process. The audit ID helps enforce accountability. Even after a user becomes root, the audit ID remains the same. The audit ID that is saved in each audit record always allows you to trace actions back to the original user who had logged in.

• Audit Session ID – The audit session ID is assigned at login and inherited by all descendant processes.

• Terminal ID (port ID, machine ID) –The terminal ID consists of the host name and the Internet address, followed by a unique number that identifies the physical device on which the user logged in. Most often, the login is through the console and the number that corresponds to the console device is 0.

Audit Trail

The audit trail is created by the audit daemon (see the auditd(1M) man page). The audit daemon starts on each machine when the machine is brought up. After the auditd daemon starts at boot time, it is responsible for collecting the audit trail data and writing the audit records into audit files, which are also called audit log files. For a description of the file format, see the audit.log(4) man page.

Even though you can physically locate audit directories within other file systems that are not dedicated to auditing, do not do so except for directories of last resort. Directories of last resort are directories where audit files are written only when there is no other suitable directory available.

There is one other scenario where locating audit directories outside of dedicated audit file systems could be acceptable. You might do so in a software development environment where auditing is optional, and where it is more important to make full use of disk space than to keep an audit trail. Putting audit directories within other file systems is not acceptable in a security-conscious production environment.

You should also consider the following:

• A host should have at least one local audit directory, which it can use as a directory of last resort if the host is unable to communicate with the audit server.

• Mount audit directories with the read-write (rw) option. When you mount audit directories remotely (using NFS software), also use the intr and noac options.

• List the audit file systems on the audit server where they reside. The export list should include all machines in the configuration.

More About the Audit Files

Each audit file is a self-contained collection of records. The file's name identifies the time span during which the records were generated and the machine that generated them.

Audit File Naming

Audit files that are complete have names of the following form:

start-time.finish-time.machine 

where start-time is the time that the first audit record in the audit file was generated, finish-time is the time that the last record was written to the file, and machine is the name of the machine that generated the file. For an example of these names, see Example of a Closed Audit File Name.

An audit log file that is still active has a name of the following form:

start-time.not_terminated.machine

How Audit File Names Are Used

The file name time stamps are used by the auditreduce command to locate files that contain records for the specific time range that has been requested. These time stamps are important because there can be a month's accumulation or more of audit files online, and searching them all for records that were generated in the last 24 hours would be unacceptably expensive.

Time-Stamp Format and Interpretation

The start-time and end-time are timestamps with one-second resolution. They are specified in Greenwich Mean Time (GMT). The format is four digits for the year, followed by two digits for each month, day, hour, minute, and second, as follows:

YYYYMMDDHHMMSS

The timestamps are in GMT to ensure that they will sort in proper order even across a daylight savings time boundary. Because they are in GMT, the date and hour must be translated to the current time zone to be meaningful. Beware of this point whenever you manipulate these files with standard file commands rather than with the auditreduce command.

Example of a File Name for a Still-Active File

The format of a file name of a still-active file is as follows:

YYYYMMDDHHMMSS.not_terminated.machine

Here is an example:

19990327225243.not_terminated.dopey

The audit log files are named by the beginning date. So, in the example above the audit file was created in 1999, on March 27, at 10:52:43 p.m, GMT. The not_terminated in the file name means either that the file is still active or that the auditd daemon was unexpectedly interrupted. The name dopey at the end is the host name of the machine whose audit data is being collected.

Example of a Closed Audit File Name

The format of the name of a closed audit log file is as follows:

YYYYMMDDHHMMSS.YYYYMMDDHHMMSS.hostname

Here is an example:

19990320005243.19900327225351.dopey

In this example, the audit log file was created in 1999, on March 20, at 12:52:43 a.m., GMT. The file was closed March 27, at 10:53:51 p.m., GMT. The name dopey at the end is the host name of the machine whose audit data was collected.

Whenever auditd is unexpectedly interrupted, the audit file that is open at the time retains the not_terminated file name designation. Also, when a machine is writing to a remotely mounted audit file and the file server crashes or becomes inaccessible, the not_terminated designation remains in the current file's name. The audit daemon opens a new audit file and keeps the old audit file name intact.

Audit Record Structure

An audit record is a sequence of audit tokens. Each audit token contains event information such as user ID, time, and date. A header token begins an audit record, and an optional trailer token concludes the record. Other audit tokens contain information relevant to the auditable event. The following figure shows a typical audit record.

Figure 26–3 Typical Audit Record Structure

Audit Token Formats

Each token has a token type identifier followed by data that is specific to the token. Each token type has its own format. The following table shows the token names with a description of each token.

An audit record always contains a header token. The header token indicates where the audit record begins in the audit trail. Every audit record contains a subject token, except for audit records from some nonattributable events. In the case of attributable events, these two tokens refer to the values of the process that caused the event. In the case of asynchronous events, the process tokens refer to the system.

acl Token

The acl token records information about Access Control Lists. This token consists of four fixed fields. The fixed fields are:

• a token ID that identifies this token as an acl token

• a field that specifies the ACL type

• an ACL ID field

• a field that lists the permissions associated with this ACL

The praudit command displays the acl token as follows:

acl,tpanero,staff,0755

The acl token format is as follows:

Figure 26–4 acl Token Format

arbitrary Token

The arbitrary token encapsulates data for the audit trail. This token consists of four fixed fields and an array of data. The fixed fields are as follows:

• a token ID that identifies this token as an arbitrary token

• a suggested format field (for example, hexadecimal)

• a size field that specifies the size of the data that is encapsulated (for example, short)

• a count field that provides the number of following items

The remainder of the token is composed of one or more items of the specified type. The praudit command displays the arbitrary token as follows:

arbitrary,decimal,int,1
42

The format of arbitrary token is as follows:

Figure 26–5 arbitrary Token Format

The following table shows the possible values of the print format field. Table 26–6.

The following table shows the possible values of the item size field.

arg Token

The arg token contains system call argument information: the argument number of the system call, the augment value, and an optional description. This token allows a 32-bit integer system-call argument in an audit record. The arg token has five fields:

• a token ID that identifies this token as an arg token

• an argument ID that tells which system call argument the token refers to

• the argument value

• the length of the descriptive text string

• the text string

The praudit command displays the arg token as follows:

argument,1,0x00000000,addr

The following figure shows the format of the arg token.

Figure 26–6 arg Token Format

attr Token

The attr token contains information from the file vnode. This token has seven fields:

• a token ID that identifies this token as an attr token

• the file access mode and type

• the owner user ID

• the owner group ID

• the file system ID

• the inode ID

• the device ID the file might represent

See the statvfs(2) man page for further information about the file system ID and the device ID.

The attr token usually accompanies a path token and is produced during path searches. In the event of a path-search error, the attr token is not included as part of the audit record since there is no vnode available to obtain the necessary file information. The praudit command displays the attr token as follows:

attribute,100555,root,staff,1805,13871,-4288

The following figure shows the format of an attr token.

Figure 26–7 attr Token Format

exec_args Token

The exec_args token records the arguments to an exec() system call. The exec_args token has two fixed fields:

• a token ID field that identifies this token as an exec_args token

• a count that represents the number of arguments that are passed to the exec() system call

The remainder of this token is composed of zero or more null-terminated strings. The praudit command displays the exec_args token as follows:

vi,/etc/security/audit_user

The following figure shows the format of an exec_args token.

Figure 26–8 exec_args Token Format

The exec_args token is output only when the audit policy argv is active.

exec_env Token

The exec_env token records the current environment variables to an exec() system call. The exec_env token has two fixed fields:

• a token ID field that identifies this token as an exec_env token

• a count that represents the number of arguments that are passed to the exec() system call

The remainder of this token is composed of zero or more null-terminated strings. The praudit command displays the exec_env token as follows:

exec_env,25,
GROUP=staff,HOME=/export/home/matrix,HOST=mestrix,HOSTTYPE=sun4,HZ=100,
LC_COLLATE=en_US.ISO8859-1,LC_CTYPE=en_US.ISO8859-1,LC_MESSAGES=C,
LC_MONETARY=en_US.ISO8859-1,LC_NUMERIC=en_US.ISO8859-1,
LC_TIME=en_US.ISO8859-1,LOGNAME=matrix,MACHTYPE=sparc,
MAIL=/var/mail/matrix,OSTYPE=solaris,PATH=/usr/sbin:/usr/bin,PS1=#,
PWD=/var/audit,REMOTEHOST=209.198.087.208,SHELL=/usr/bin/csh,SHLVL=1,
TERM=dtterm,TZ=US/Pacific,USER=matrix,VENDOR=sun

The following figures shows the format of an exec_env token.

Figure 26–9 exec_env Token Format

The exec_env token is output only when the audit policy arge is active.

exit Token

The exit token records the exit status of a program. The exit token contains the following fields:

• a token ID that identifies this token as an exit token

• a program exit status as passed to the exit() system call

• a return value that describes the exit status or provides a system error number

The praudit command displays the exit token as follows:

exit,Error 0,0

The following figure shows the format of an exit token.

Figure 26–10 exit Token Format

file Token

The file token is a special token that is generated by the audit daemon to mark the beginning of a new audit trail file and the end of an old audit trail file as it is deactivated. The audit daemon builds a special audit record that contains this token to “link” together successive audit files into one audit trail. The file token has four fields:

• a token ID that identifies this token as a file token

• a time and date stamp that identifies the time that the file was created or closed

• a byte count of the file name that includes a null terminator

• a field that holds the file null-terminated name

The praudit command displays the file token as follows:

file,Tue Sep  1 13:32:42 1992, + 79249 msec,
	/var/audit/localhost/files/19990901202558.19990901203241.quisp

The following figure shows the format of a file token.

Figure 26–11 file Token Format

groups Token (Obsolete)

This token has been replaced by the newgroups token, which provides the same type of information but requires less space. A description of the groups token is provided here for completeness, but the application designer should use the newgroups token. Notice that praudit does not distinguish between the two tokens, as both token IDs are labelled groups when ASCII output is displayed.

The groups token records the groups entries from the process's credential. The groups token has two fixed fields:

• A token ID that identifies this token as a groups token

• An array of groups entries of size NGROUPS_MAX (16)

The remainder of the token consists of zero or more group entries. The praudit command displays the group token as follows:

group,staff,admin,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1,-1

The following figure shows the format of a groups token.

Figure 26–12 groups Token Format

The groups token is output only when the audit policy group is active.

header Token

The header token is special in that it marks the beginning of an audit record and combines with the trailer token to bracket all the other tokens in the record. The header token has six fields:

• a token ID field that identifies this token as a header token

• a byte count of the total length of the audit record, including both the header and the trailer

• a version number that identifies the version of the audit record structure

• the audit event ID that identifies the type of audit event that the record represents

• the ID modifier that identifies special characteristics of the audit event

• and the time and date that the record was created

On 64-bit systems, the header token is displayed with a 64-bit time stamp, in place of the 32-bit time stamp.

The praudit command displays the header token for a ioctl() system call as follows:

header,240,1,ioctl(2),es,Tue Sept  1 16:11:44 2001, + 270000 msec

The following figure shows the format of a header token.

Figure 26–13 header Token Format

The ID modifier field has the following flags defined:

0x4000			PAD_NOTATTR						nonattributable event
0x8000			PAD_FAILURE						fail audit event

in_addr Token

The in_addr token contains a 4-byte Internet Protocol address. The in_addr token has two fields:

• a token ID that identifies this token as an ip address token

• an Internet address

The praudit command displays the in_addr token as follows:

ip address,129.150.113.7

For the Solaris 8 release, the Internet address can be displayed as an IPv4 address that uses 4 bytes, or as an IPv6 address that uses 16 bytes to describe the type, and 16 bytes to describe the address.The following figure shows the format of an in_addr token.

Figure 26–14 in_addr Token Format

ip Token

The ip token contains a copy of an Internet Protocol header but does not include any IP options. The IP options can be added by including more of the IP header in the token. The ip token has two fields:

• a token ID that identifies this token as an ip token

• a copy of the IP header (all 20 bytes)

The praudit command displays the ip token as follows:

ip address,0.0.0.0

The IP header structure is defined in the /usr/include/netinet/ip.h file. The following figure shows the format of an ip token.

Figure 26–15 ip Token Format

ipc Token

The ipc token contains the System V IPC message/semaphore/shared-memory handle that is used by the caller to identify a particular IPC object. The ipc token has three fields:

• a token ID that identifies this token as an IPC token

• a type field that specifies the type of IPC object

• the handle that identifies the IPC object

The praudit command displays the ipc token as follows:

IPC,msg,3

The IPC object identifiers violate the context-free nature of the Solaris CMW audit tokens. No global “name” uniquely identifies IPC objects. Instead, they are identified by their handles, which are valid only during the time the IPC objects are active. The identification should not be a problem since the System V IPC mechanisms are seldom used, and they all share the same audit class.

The following table shows the possible values for the IPC object type field. The values are defined in the /usr/include/bsm/audit.h file.

The following figure shows the format of an ipc token.

Figure 26–16 ipc Token Format

ipc_perm Token

The ipc_perm token contains a copy of the System V IPC access information. This token is added to audit records that are generated by IPC shared-memory events, IPC semaphore events, and IPC message events. The ipc_perm token has eight fields:

• a token ID that identifies this token as an ipc_perm token

• the user ID of the IPC owner

• the group ID of the IPC owner

• the user ID of the IPC creator

• the group ID of the IPC creator

• the access modes of the IPC

• the sequence number of the IPC

• the IPC key value

The praudit command displays the ipc_perm token as follows:

IPC perm,root,wheel,root,wheel,0,0,0x00000000

The values are taken from the ipc_perm structure that is associated with the IPC object. The following figure shows the format of an ipc_perm token.

Figure 26–17 ipc_perm Token Format

iport Token

The iport token contains the TCP (or UDP) port address. The iport token has two fields:

• a token ID that identifies this token as an iport token

• the TCP/UDP port address

The praudit command displays the iport token as follows:

ip port,0xf6d6

The following figure shows the format of an iport token.

Figure 26–18 iport Token Format

newgroups Token

This token replaces the groups token. Notice that the praudit command does not distinguish between the two tokens, as both token IDs are labelled groups when ASCII output is displayed.

The newgroups token records the groups entries from the process's credential. The newgroups token has two fixed fields:

• a token ID field that identifies this token as a newgroups token

• a count that represents the number of groups that are contained in this audit record

The remainder of this token is composed of zero or more group entries. The praudit command displays the ip port token as follows:

group, staff, admin

The following figure shows the format of a newgroups token.

Figure 26–19 newgroups Token Format

The newgroups token is output only when the group audit policy is active.

opaque Token

The opaque token contains unformatted data as a sequence of bytes. The opaque token has three fields:

• a token ID that identifies this token as an opaque token

• a byte count of the data

• an array of byte data

The praudit command displays the opaque token as follows:

opaque,12,0x4f5041515545204441544100

The following figure shows the format of an opaque token.

Figure 26–20 opaque Token Format

path Token

The path token contains access path information for an object. This token contains the following fields:

• a token ID that identifies this token as an path token

• a byte count of the path length

• the absolute path to the object that is based on the real root of the system

The praudit command displays the path token as follows. Note that the path length field is not displayed.

path,/etc/security/audit_user

The following figure shows the format of a path token.

Figure 26–21 path Token Format

process Token

The process token contains information about a user who is associated with a process, such as the recipient of a signal. The process token has nine fields:

• a token ID that identifies this token as a process token

• the invariant audit ID

• the effective user ID

• the effective group ID

• the real user ID

• the real group ID

• the process ID

• the audit session ID

• a terminal ID that consists of a device ID and a machine ID

The praudit command displays the process token as follows:

process,root,root,wheel,root,wheel,0,0,0,0.0.0.0

The following figure shows the format of a process token.

Figure 26–22 process Token Format

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

The process token fields for the session ID, the real user ID, or the real group ID might be unavailable. The value is then set to -1.

Any token that contains a terminal ID has several variations. The praudit command hides these variations on output of the terminal ID so that they all appear the same. This field is handled the same way for any token that contains it. The terminal ID is either an IP address and port number, or a device ID, such as the serial port that is connected to a modem, in which case it is zero. The terminal ID is specified in one of several formats:

For device numbers:

• 32-bit applications: 4-byte device number, 4-bytes unused

• 64-bit applications: 8-byte device number, 4-bytes unused

For port numbers in the Solaris 7 release or earlier releases:

• 32-bit applications: 4-byte port number, 4-byte IP address

• 64-bit applications: 8-byte port number, 4-byte IP address

For port numbers in the Solaris 8 or 9 releases:

• 32-bit with IPV4: 4-byte port number, 4-byte IP type, 4-byte IP address

• 32-bit with IPV6: 4-byte port number, 4-byte IP type, 16-byte IP address

• 64-bit with IPV4: 8-byte port number, 4-byte IP type, 4-byte IP address

• 64-bit with IPV6: 8-byte port number, 4-byte IP type, 16-byte IP address

return Token

The return token contains the return status of the system call (u_error) and the process return value (u_rval1). This token has three fields:

• a token ID that identifies this token as a return token

• the error status of the system call

• the system call return value

The return token is always returned as part of kernel-generated audit records for system calls. This token indicates exit status and other return values in application auditing.

The praudit command displays the return token as follows:

return,success,0

The following figures shows the format of a return token.

Figure 26–23 return Token Format

seq Token

The seq token (sequence token) is an optional token that contains a sequence number. Used for debugging, this token is added to each audit record when the seq policy is active. The seq token has two fields:

• a token ID that identifies this token as a seq token

• a 32-bit unsigned long field that contains the sequence number

The sequence number is incremented every time an audit record is generated and added to the audit trail. The praudit command displays the seq token as follows:

sequence,1292

The following figure shows the format of a seq token.

Figure 26–24 seq Token Format

The seq token is output only when the seq audit policy is active.

socket Token

The socket token contains information that describes an Internet socket. This token has six fields:

• a token ID that identifies this token as a socket token

• a socket type field that indicates the type of socket referenced (TCP/UDP/UNIX)

• the local port address

• the local Internet address

• the remote port address

• the remote Internet address

The praudit command displays the socket token as follows:

socket,0x0000,0x0000,0.0.0.0,0x0000,0.0.0.0

For the Solaris 8 release, the Internet address can be displayed as a IPv4 address that uses 4 bytes, or as an IPv6 address that uses 16 bytes to describe the type, and 16 bytes to describe the addresses. The following figure shows the format of a socket token.

Figure 26–25 socket Token Format

subject Token

The subject token describes a user who performs or attempts to perform an operation. The format is the same as the process token. The subject token has nine fields:

• an ID that identifies this token as a subject token

• the invariant audit ID

• the effective user ID

• the effective group ID

• the real user ID

• the real group ID

• the process ID

• the audit session ID

• a terminal ID that consists of a device ID and a machine ID

The subject token is always returned as part of kernel-generated audit records for system calls. The praudit command displays the subject token as follows:

subject,cjc,cjc,staff,cjc,staff,424,223,0 0 quisp

The audit ID, user ID, group ID, process ID, and session ID are long instead of short.

The subject token fields for the session ID, the real user ID, or the real group ID might be unavailable. The value is then set to -1.

Any token that contains a terminal ID has several variations. The praudit command hides these variations on output of the terminal ID so that they all appear the same. This field is handled the same way for any token that contains it. The terminal ID is either an IP address and port number, or a device ID, such as the serial port that is connected to a modem, in which case it is zero. The terminal ID is specified in one of several formats:

For device numbers:

• 32-bit applications: 4-byte device number, 4-bytes unused

• 64-bit applications: 8-byte device number, 4-bytes unused

For port numbers in the Solaris 7 release or earlier releases:

• 32-bit applications: 4-byte port number, 4-byte IP address

• 64-bit applications: 8-byte port number, 4-byte IP address

For port numbers in the Solaris 8 or 9 releases:

• 32-bit with IPV4: 4-byte port number, 4-byte IP type, 4-byte IP address

• 32-bit with IPV6: 4-byte port number, 4-byte IP type, 16-byte IP address

• 64-bit with IPV4: 8-byte port number, 4-byte IP type, 4-byte IP address

• 64-bit with IPV6: 8-byte port number, 4-byte IP type, 16-byte IP address

The following figure shows the format of the subject token.

Figure 26–26 subject Token Format

text Token

The text token contains a text string. This token has three fields:

• a token ID that identifies this token as a text token

• the length of the text string

• the text string itself

The praudit command displays the text token as follows:

text,aw_test_token

The following figure shows the format of a text token.

Figure 26–27 text Token Format

trailer Token

The two tokens, header and trailer, are special in that they distinguish the end points of an audit record and bracket all the other tokens. A header token begins an audit record. A trailer token ends an audit record. The trailer token is an optional token and is added as the last token of each record only when the trail audit policy has been set.

The trailer token supports backward seeks of the audit trail. The trailer token has three fields:

• a token ID that identifies this token as a trailer token

• a pad number to aid in marking the end of the record

• the total number of characters in the audit record, including both the header and trailer tokens

The praudit command displays the trailer token as follows:

trailer,136

The following figure shows the format of a trailer token.

Figure 26–28 trailer Token Format

The audit trail analysis software ensures that each record contains both the header and trailer tokens. In the case of a write error, as when a file system becomes full, an audit record can be incomplete and truncated. The auditsvc() system call, that is responsible for writing data to the audit trail, attempts to write complete audit records. When file system space runs out, the system call terminates without releasing the current audit record. When the system call resumes, it can then repeat the truncated record. For more information, see the auditsvc(2) man page.

Device Allocation Reference

Device allocation protects removable media from unauthorized use. By requiring that a user allocate a device, or by denying a user permission to use a device, you can protect your site from loss of data, computer viruses, and other security breaches. The following section provides information about BSM device allocation.

Components of the Device-Allocation Mechanism

The components of the device-allocation mechanism are as follows:

• The allocate, deallocate, dminfo, and list_devices commands. For more information, see Using the Device-Allocation Commands.

• The /etc/security/device_allocate file. See the device_allocate(4) man page.

• The /etc/security/device_maps file. See the device_maps(4) man page.

• A lock file in the /etc/security/dev directory for each allocatable device.

• The changed attributes of the device-special files that are associated with each allocatable device.

• Device-clean scripts for each allocatable device.

The device_allocate file, the device_map file, and the lock files are local configuration files. These files are not administered as name service databases because tape drives, diskette drives, and printers are all connected to specific machines.

Using the Device-Allocation Commands

This section describes some of the options to the allocate, deallocate, and list_devices commands that are usable only by root or a role of equivalent power. The commands are detailed on their respective man pages.

allocate -F device_special_filename

Reallocates the specified device. This option is often used with the -U option to reallocate the specified device to the specified user. Without the -U option, the device is allocated to root.

allocate -U username

Causes the device to be allocated to the user who is specified rather than to the current user. This option allows you to allocate a device for another user while you are root, without having to assume that user's identity.

deallocate -F device_special_filename

Forces the deallocation of a device. Devices that a user has allocated are not automatically deallocated when the process terminates or when the user logs out. When a user forgets to deallocate a tape drive, you can force deallocation by using the -F option while you are root.

deallocate -I

Forces the deallocation of all allocatable devices. This option should be used only at system initialization.

list_devices

Lists all the device-special files that are associated with any device that is listed in the device_maps file.

list_devices -U username

Lists the devices that are allocatable or allocated to the user ID that is associated with the specified user name. This option allows you to check which devices are allocatable or allocated to another user while you are root.

The Allocate Error State

An allocatable device is in the allocate error state if it is owned by user bin and group bin with a device-special file mode of 0100. If a user wants to allocate a device that is in the allocate error state, you should try to force the deallocation of the device, by using the deallocate command with the -F option. Or, you can use allocate -U to assign the device to the user, then investigate any error messages that appear. After any problems with the device are corrected, you must rerun the deallocate -F or allocate -F command to clear the allocate error state from the device.

The device_maps File

You can examine the /etc/security/device_maps file to determine the device names, device types, and device-special files that are associated with each allocatable device. See the device_maps(4) man page. Device maps are created when you set up device allocation. A rudimentary device_maps file is created by bsmconv when the BSM is enabled. This initial device_maps file should be used only as a starting point. You can then augment and customize the device_maps file for your site.

The device_maps file defines the device-special file mappings for each device, which in many cases is not intuitive. This file allows various programs to discover which device-special files map to which devices. You can use the dminfo command, for example, to retrieve the device name, the device type, and the device-special files to specify when you set up an allocatable device. The dminfo command uses the device_maps file to report this information.

Each device is represented by a one-line entry of the form:

device-name:device-type:device-list

Lines in the device_maps file can end with a backslash (\) to continue an entry on the next line. Comments can also be included. A “#” makes a comment out of all subsequent text until the next newline not immediately preceded by a backslash. Leading and trailing blanks are allowed in any field.

device-name

Specifies the name of the device, for example st0, fd0, or audio. The device name that is specified here must correspond to the name of the lock file that is used in the /etc/security/dev directory.

device-type

Specifies the generic device type (which is the name for the class of devices, such as st, fd, audio). The device-type field logically groups related devices.

device-list

Lists of the device-special files that are associated with the physical device. The device-list must contain all of the special files that allow access to a particular device. If the list is incomplete, a malevolent user can still obtain or modify private information. Valid entries for the device-list field are either the real device files located under /devices or the symbolic links that are in /dev. The symbolic links in the /dev directory are provided for binary compatibility.

The following is an example of a device_maps file entries for SCSI tape st0 and diskette fd0.

fd0:\
	fd:\
	/dev/fd0 /dev/fd0a /dev/fd0b /dev/rfd0 /dev/rfd0a /dev/rfd0b:\
					.
					.
					.
st0:\
	st:\
	/dev/rst0 /dev/rst8 /dev/rst16 /dev/nrst0 /dev/nrst8 /dev/nrst16:\

The device_allocate File

You can modify the device_allocate file to change devices from allocatable to nonallocatable, or to add new devices. A sample device_allocate file follows.

st0;st;;;;/etc/security/lib/st_clean
fd0;fd;;;;/etc/security/lib/fd_clean
sr0;sr;;;;/etc/security/lib/sr_clean
audio;audio;;;*;/etc/security/lib/audio_clean

You define which devices should be allocatable during initial BSM configuration. You can decide to accept the default devices and their defined characteristics, as shown in the preceding sample device_allocate file. Whenever you add a device to any machine after the system is up and running, you must decide whether to make the new device allocatable.

After installation, you can modify the entries for devices in the device_allocate file. Any device that needs to be allocated before use must be defined in the device_allocate file on each machine. Currently, cartridge tape drives, diskette drives, CD-ROM devices, and audio chips are considered allocatable and have device-clean scripts.

Xylogics^TM tape drives or Archive tape drives also use the st_clean script that is supplied for SCSI devices. Other devices that you can make allocatable are modems, terminals, graphics tablets, and similar devices. However, you need to create your own device-clean scripts for such devices, and the script must fulfill object-reuse requirements for that type of device.

An entry in the device_allocate file does not mean that the device is allocatable, unless the entry specifically states that the device is allocatable. In the sample device_allocate file, note the asterisk (*) in the fifth field of the audio device entry. An asterisk in the fifth field indicates to the system that the device is not allocatable. That is, the system administrator does not require a user to allocate the device before it is used nor to deallocate it afterward. Any other string placed in this field indicates that the device is allocatable.

In the device_allocate file, you represent each device by a one-line entry of the form:

device-name;device-type;reserved;reserved;alloc;device-clean

For example, the following line shows the entry for device name st0:

st0;st;;;;;/etc/security/lib/st_clean

Lines in the device_allocate file can end with a “\” to continue an entry on the next line. Comments can also be included. A “#” makes a comment out of all subsequent text until the next newline not immediately preceded by a “\”. Leading and trailing blanks are allowed in any field.

The following paragraphs describe each field in the device_allocate file.

device-name

Specifies the name of the device; for example, st0, fd0, or sr0. When you make a device allocatable, retrieve the device-name from the device-name field in the device_maps file, or use the dminfo command. (The name is also the DAC file name for the device.)

device-type

Specifies the generic device type (which is the name for the class of devices, such as st, fd, and sr). This field groups related devices. When you make an allocatable device, retrieve the device-type from the device-type field in the device_maps file, or use the dminfo command.

reserved

These two fields are reserved for future use.

alloc

Specifies whether the device is allocatable. An asterisk (*) in this field indicates that the device is not allocatable. Any other string, or an empty field, indicates that the device is allocatable.

device-clean

Supplies the path name of a script to be invoked for special handling, such as cleanup and object-reuse protection during the allocation process. The device-clean script is run any time that the device is acted on by the deallocate command, such as when a device is forcibly deallocated with deallocate -F.

Device-Clean Scripts

The device-clean scripts address the security requirement that all usable data be purged from a physical device before reuse. By default, cartridge tape drives, diskette drives, CD-ROM devices, and audio devices require device-clean scripts, which are provided. This section describes what device-clean scripts do.

Object Reuse

Device allocation satisfies part of the object-reuse requirement. The device-clean scripts make sure that data that is left on a device by one user is cleared before the device is allocatable by another user.

Device-Clean Script for Tapes

The st_clean device-clean script supports three tape devices. The supported tape devices are:

• SCSI 1/4-inch tape

• Archive 1/4-inch tape

• Open-reel 1/2-inch tape

The st_clean script uses the rewoffl option to the mt command to affect the device cleanup. For more information, see the mt(1) man page. If the script runs during system boot, it queries the device to see if the device is online and has media in it. The 1/4-inch tape devices that have media in them, are placed in the allocate error state to force the administrator to clean up the device manually.

During normal system operation, when the allocate or deallocate command is executed in interactive mode, the user is prompted to remove the media from the device that is being deallocated. The script pauses until the media is removed from the device.

Device-Clean Scripts for Diskettes and CD-ROM Devices

The following table shows the device-clean scripts for diskettes and CD-ROM devices.

The scripts use the eject command to remove the media from the drive. See the eject(1) man page. If the eject command fails, the device is placed in the allocate error state.

Device-Clean Script for Audio

Audio devices are cleaned up with an audio-clean script. The script performs an AUDIO_DRAIN ioctl system call to flush the device, then an AUDIO_SETINFO ioctl system call command to reset the device configuration to default. In addition, the script retrieves the audio chip registers by using the AUDIOGETREG ioctl system call. Any registers that deviate from the default settings are reset by using the AUDIOSETREG ioctl system call.

Writing New Device-Clean Scripts

If you add more allocatable devices to the system, you might need to create your own device-clean scripts. The deallocate command passes a parameter to the device-clean scripts. The parameter, shown here, is a string that contains the device name (see the device_allocate(4) man page):

st_clean -[I|F|S] device-name

Device-clean scripts must return “0” for success and greater than “0” for failure. The options -I, -F, and -S help the script determine its running mode.

The -I option is needed during system boot only. All output must go to the system console. Failure or inability to forcibly eject the media must put the device in the allocate error state.

The -F option is for forced cleanup. This option is interactive and assumes that the user is available to respond to prompts. A script with this option must attempt to complete the cleanup if one part of the cleanup fails.

The -S option is for standard cleanup. This option is interactive and assumes that the user is available to respond to prompts.

How the Device-Allocation Mechanism Works

This section gives an example of how the device-allocate mechanism works.

The allocate command first checks for the presence of a lock file under the device name for the specified device in the /etc/security/dev directory. If the file is owned by allocate, then the ownership of the lock file is changed to the name of the user who initiated the allocate command.

The allocate command then checks for an entry for the device in the device_allocate file, and checks whether the entry shows that the device as allocatable.

The first listing in the following example shows that a lock file exists with owner bin, group bin, and mode 600 for the st0 device in /etc/security/dev. The second listing shows that the associated device-special files are set up properly, with owner bin, group bin, and mode 000.

untouchable% ls -lg /etc/security/dev/st0
-rw------- 1 bin bin      		      0 Dec 6 15:21 /etc/security/dev/st0
untouchable% ls -lg /devices/sbus@1,f8000000/esp@0,800000
c--------- 1 bin bin		       18,  4 May 12 13:11 st@4,0:
c--------- 1 bin bin	       18, 20 May 12 13:11 st@4,0:b
c--------- 1 bin bin	       18, 28 May 12 13:11 st@4,0:bn
c--------- 1 bin bin	       18, 12 May 12 13:11 st@4,0:c
					 .
					 .
					 .
c--------- 1 bin bin	       18,  0 May 12 13:11 st@4,0:u
c--------- 1 bin bin	       18, 16 May 12 13:11 st@4,0:ub
c--------- 1 bin bin	       18, 24 May 12 13:11 st@4,0:ubn
c--------- 1 bin bin	       18,  8 May 12 13:11 st@4,0:un

In this example, the user vanessa allocates device st0.

untouchable% whoami
vanessa
untouchable% allocate st0

When the user vanessa runs the allocate command to allocate the tape st0, allocate first checks for the existence of an /etc/security/dev/st0 file. If no lock file exists or if the lock file is owned by a user other than allocate, then user vanessa could not allocate the device.

If the allocate command finds the lock file for the device with the correct ownership and permissions, it then checks to make sure that the device has an entry in the device_allocate file and that the entry specifies that the device is allocatable.

In this example, the default device_allocate entry for the st0 device specifies that the device is allocatable. Because the allocate command finds that all these conditions are met, the device is allocated to user vanessa.

The allocate command changes the ownership and permissions of the device-special files that are associated with the device in the /dev directory. To allocate the st0 device to the user vanessa, the mode on its associated device-special files is changed to 600 and the owner is changed to vanessa.

The allocate command also changes the ownership of the lock file that is associated with the device in the /etc/security/dev directory. To allocate the st0 device to the user vanessa, the owner of /etc/security/dev/st0 is changed to vanessa.

In the following example, after the user vanessa executes the allocate command with the device name st0, the owner of /etc/security/dev/st0 is changed to vanessa and the owner of the associated device-special files is now also vanessa. Lastly, user vanessa now has permission to read and write the files.

untouchable% whoami
vanessa
untouchable% allocate st0
untouchable% ls -lg /etc/security/dev/st0
-rw------- 1 vanessa staff 		      0 Dec 6 15:21 /etc/security/dev/st0
untouchable% ls -la /devices/sbus@1,f8000000/esp@0,800000
.
.
.
crw------- 1 vanessa 18,  4 May 12 13:11 st@4,0:
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:b
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:bn
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:c
.
.
.
crw------- 1 vanessa 18,  4 May 12 13:11 st@4,0:u
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:ub
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:ubn
crw------- 1 vanessa 18, 12 May 12 13:11 st@4,0:un