Managing the Essbase Security File (essbase.sec)

In This Section:

About the Essbase Security File

When Essbase is in EPM System security mode, some security information is stored by Shared Services and external user directories, and some security information is stored in the Essbase security file (essbase.sec).

The following information is stored by Shared Services or by the external user directories:

Users
Groups
Passwords
User and group role information for applications

The following information is stored in essbase.sec:

Calculation script access
Filter access
Application access type
Application and database properties, including substitution variables and DISKVOLUMES settings (block storage databases only)

When Essbase is in native security mode, all information about users, groups, passwords, permissions, filters, applications, databases, and their corresponding directories is stored in essbase.sec.

The essbase.sec file is located in the ARBORPATH/bin directory.

The content of essbase.sec is encrypted.

Managing Essbase Security Backup Files

Each time you start Essbase Server, Essbase creates a temporary file, named tempessbase.sec, that is used to validate the Essbase security file (essbase.sec). When Essbase Server successfully starts using essbase.sec, tempessbase.sec is deleted and Essbase creates a security backup file, named essbase_timestamp.bak.

You can manage the number of security backup files that Essbase maintains; the interval at which the security backup files are created; and whether to switch to the latest, valid security backup file on startup if the essbase.sec file is invalid.

NUMBEROFSECFILEBACKUPS configuration setting: Specifies the maximum number (2 to 10) of security backup files that Essbase creates and maintains. When the limit is exceeded, Essbase deletes the security backup file with the oldest timestamp and creates the latest backup file.
By default, Essbase maintains a minimum of two versions of essbase_timestamp.bak.
SECFILEBACKUPINTERVAL configuration setting: Specifies the amount of time Essbase waits before creating a security backup file.
By default, Essbase creates a new security backup file every 300 seconds (which is five minutes).
ENABLESWITCHTOBACKUPFILE configuration setting: Specifies whether Essbase automatically loads a valid security backup file at startup if the essbase.sec file is invalid.
By default, Essbase does not load a security backup file at startup if the security file is invalid.
Also see Reconciling the Essbase Security File to the State of Essbase on an External Disk.

The content of essbase_timestamp.bak is encrypted.

To update the essbase_timestamp.bak file, use a tool:

Tool

Topic

Location

Administration Services

Updating the Security Backup File

Oracle Essbase Administration Services Online Help

MaxL

alter system sync security backup

Oracle Essbase Technical Reference

essbase.cfg

NUMBEROFSECFILEBACKUPS

SECFILEBACKUPINTERVAL

ENABLESWITCHTOBACKUPFILE

Note:

Essbase automatically creates a backup of the security file before and after migration (essbase.bak_preUPM and essbase.bak_postUPM). See Migrating Essbase to EPM System Security.

Restoring the Essbase Security File

If you attempt to start Essbase Server and cannot get a password prompt or your password is rejected, no backup files are created. You can restore essbase.sec from the latest, valid security backup file by copying essbase_timestamp.bak to essbase.sec. Both files are in the ARBORPATH/bin directory.

If you are using Essbase in EPM System security mode, you must also restore the latest backups from Shared Services and any external user directories that you are using.

For information on backup procedures for Shared Services and Essbase, see the Oracle Hyperion Enterprise Performance Management System Backup and Recovery Guide and the documentation for the appropriate external user directories.

Caution!

Back up the Essbase security file and Shared Services simultaneously.

Changing Essbase Security Backup File Comparison Frequency

Essbase updates the latest, valid security backup file (essbase_timestamp.bak) if Essbase determines that the security file (essbase.sec) has changed since the latest security backup file (essbase_timestamp.bak) was created. By default, Essbase performs this check at specified intervals instead of only when Essbase Server starts.

Consider the following facts before changing the interval value:

In Administration Services, the same check box manages how often the security backup file is checked against the security file and how often user inactivity is checked.
The default value is five minutes, the recommended setting to ensure that the security backup file is checked frequently enough to capture security changes. Five minutes is also the recommended value for the inactivity check.
If you set the value to zero, the inactivity check is disabled, and the essbase_timestamp.bak file is compared to essbase.sec every five minutes (and updated if necessary).
Enter a larger value if your security file does not need to be updated frequently. Enter a smaller value if performance is not an issue.

You can also update the security backup file anytime, not only at specified intervals.

To manually update the security backup file or change the frequency of backup file comparisons, use a tool:

Tool	Topic	Location
Administration Services	Updating the Security Backup File	Oracle Essbase Administration Services Online Help
MaxL	alter system sync security_backup	Oracle Essbase Technical Reference

Reconciling the Essbase Security File to the State of Essbase on an External Disk

When Essbase is started using the latest, valid security backup file (essbase_timestamp.bak) instead of essbase.sec, you can use the alter system MaxL statement to reconcile the security file to match the state of Essbase applications and databases on an external disk.

The alter system reconcile grammar logs messages in essbase.log when:

An application or database folder is on the disk but not in the security file
An application or database is in the security file but not on the disk. In this scenario, using the alter system reconcile force grammar removes the application or database from the security file.

Managing Essbase Security File Fragmentation

Changing or deleting Essbase security entities, such as filters, users, groups, applications, databases, substitution variables, disk volumes, passwords, and other Essbase artifacts, can cause fragmentation in the security file (essbase.sec). Too much fragmentation in files can slow down security-related performance.

Essbase compacts the security file automatically each time the Agent is stopped. You can check the fragmentation status of the security file and you can compact the security file without stopping the Agent.

Displaying the Essbase Security File Fragmentation Status

The fragmentation status of the security file is displayed as a percent.

To display the fragmentation status of the security file, use the display system MaxL statement with the security file fragmentation_percent grammar.

Compacting the Essbase Security File While the Agent is Running

Besides manually compacting the security file, you can use the SECURITYFILECOMPACTIONPERCENT configuration setting to define a percentage of fragmentation that triggers compaction automatically.

To compact the security file without stopping the Agent, use a tool:

Tool	Topic	Location
Agent	COMPACT	Enter the Agent command at the command prompt in the Essbase Server console window
MaxL	alter system compact security file	Oracle Essbase Technical Reference
essbase.cfg	SECURITYFILECOMPACTIONPERCENT	Oracle Essbase Technical Reference

Note:

Compacting the security file while the Agent is running slows down Agent activity until the operation is completed, which could take a few minutes.

Exporting the Essbase Security File to a Readable Format

An Essbase Administrator can export the contents of the essbase.sec file for an Essbase Server instance to a readable text file format, which is useful for review purposes.

Caution!

When exporting essbase.sec, follow your company’s security procedures to ensure the integrity of the data.

The export security file command, which can be run from Administration Services Console or as a MaxL statement, is run against the Essbase Server session for which you are currently logged in. The Essbase Server session can be run as a service.

To export essbase.sec, use a tool:

Tool	Topic	Location
Administration Services	Exporting the Security File	Oracle Essbase Administration Services Online Help
MaxL	export security_file	Oracle Essbase Technical Reference

Note:

The DUMP agent command is similar to the export security file command, except that the DUMP command cannot be executed against an Essbase Server running as a service. See Table 133, Agent Commands and MaxL, ESSCMD, or Administration Services Equivalents.