Set up the audit-data store

You can store the audit information in a database or system file, or you can send the information to a custom Java class for processing.

Specifying where to store audit information

Using any standard ASCII text editor, open the security.properties file. The location of the file depends on your application server:
- EAServer – JAGUAR/java/classes/com/sybase/ep/security.
- WebLogic – BEA_ROOT/sybepsecurity/etc/com/sybase/ep/security.
Set the following properties, which are defined in Table 15-1:
- auditSPI – dbconncache, file, database, or the name of a Java class.
- auditLog – file name for primary or backup audit storage.
- auditOverflowLog – secondary backup location.

Setting up the audit database

If you set auditSPI to either “dbconncache” or “database,” you must set up an audit database.

Choose a database to host the auditing information. To maintain complete audit records, Sybase recommends that you use the ACDB. If you are using an Adaptive Server Enterprise database, and you need information on managing the database log, see Chapter 27, “Developing a Backup and Recovery Plan,” in the Adaptive Server Enterprise System Administration Guide, which is available on the Sybase Product Manuals Web page.
If you are using the ACDB, the SecDboCache is configured automatically when Security is installed, so you may skip this step.

To use a database other than the ACDB, create a connection cache to the database, and link the com.sybase.ep.security.audit/SecureAuditWriter component’s jdbc/Audit resource reference to the new connection cache.

If you are using EAServer, see these chapters:
- Chapter 4, “Database Access,” in the EAServer System Administration Guide for information on creating connection caches.
- Chapter 21, “Creating Web Applications,” in the EAServer Programmer’s Guide for information on configuring resource references.
If your application server is WebLogic, refer to your BEA documentation.

Choose a schema for your audit records. The following is the default schema, which can be created in an Adaptive Server Enterprise database:

create table Audit(recordID varchar(64), 
                   timeStamp DATETIME, 
                    auditData TEXT)

If you are using an Oracle database, you must use a name other than “Audit” for your audit table, which is a keyword in Oracle.

The information contained in the auditData field is specific to the object type and the AccessType—see “Object-level auditing”.

Table 6-12 defines the complete list of information you can audit. An asterisk identifies the default items.

**Table 6-12: Auditable information**
VALUES	Information to audit	Field name	Datatype	Can be null
1	* Audit record ID	recordID	varchar(64)	No
2	* Audit timestamp	timeStamp	DATETIME in ASA and Adaptive Server Enterprise DATE in Oracle	No
3	* XML audit record	auditData	CLOB (character large object) TEXT in Adaptive Server Enterprise Reader in java.sql	No
4	Domain primary key	domainPK	varchar(30)	No
5	Subject primary key	subjectPK	varchar(30)	Yes
6	Subject DN	subjectDN	varchar(255)	Yes
7	Session primary key	sessionPK	varchar(64)	Yes
8	Resource class name (AssetType)	resourceClass	varchar(255)	No
9	Resource ID	resourceID	varchar(255)	No
10	Action (AccessType)	action	varchar(255)	No
11	Decision (permit or deny)	decision	BIT Boolean in java.sql	Yes

To audit more than the default items, update this statement in the security.properties file:
```
auditDatabaseInsertSql=INSERT INTO Audit(recordID, timeStamp, auditData) VALUES ({1}, {2}, {3})
```
For each additional piece of information you want to audit, append the field name to the comma-separated list of fields for the Audit table, and add the corresponding VALUES number (from Table 6-12) enclosed by curly braces to the VALUES list. For example, to include the action and decision in each audit record, the auditDatabaseInsertSql statement should be:
```
auditDatabaseInsertSql=INSERT INTO Audit(recordID, timeStamp, auditData, action, decision) VALUES ({1}, {2}, {3}, {10}, {11})
```
Create the Audit table in your database, and configure the following:
- Add row-level locking to the table.
  
  For an Adaptive Server Enterprise database, see Performance and Tuning: Locking.
- For each field whose value can be null, create a database column that supports null values. Adaptive Server Enterprise database columns support null values only if you specifically configure them to do so.
In security.properties, verify that auditSPI is set to this value:
```
auditSpi=dbconncache
```
Alternately, you can enable the standard JDBC database SPI by defining these values in security.properties; however, Sybase does not recommend using this SPI due to performance issues:
```
auditDatabaseJdbcDriver=com.sybase.jdbc2.jdbc.SybDriver
auditDatabaseJdbcUrl=jdbc:sybase:Tds:<host_name>:<port>/<db_name>
auditDatabasePassword=<password>
auditDatabaseUsername=<user_name>
auditSpi=database
```
If you enable the standard JDBC database SPI, you can skip step 2.
Restart your application server to enable the new SPI, and verify that authentication is working. If configuration errors exist, debugging information may be written to both JAGUAR/bin/Jaguar.log and SECURITY/security.log.