Hyperion Shared Services OpenLDAP FAQ - Common Errors, Backup Techniques, Advanced Usage

Hyperion Shared Services OpenLDAP FAQ - Common Errors, Backup Techniques, Advanced Usage [ID 763771.1]
		Modified 10-JAN-2012     Type FAQ     Status PUBLISHED

In this Document
  Purpose
  Questions and Answers
     Fundamentals
     What is OpenLDAP?
     What does Shared Services store in OpenLDAP ?
     Which version of OpenLDAP is shipped with Shared Services?
     Where can I find any documentation on OpenLDAP?
     What is BDB and why it is also included with SharedServices ?
     Maintenance
     Is it really necessary to backup OpenLDAP ?
     Can I run a "hot" backup, without stopping the service ?
     How can you create a back up?
     How can you restore a back up?
     Can I delete all those "logfiles" ?
     Common Errors
     Service fails to start with error code 21
     Advanced configuration
     How to reset OpenLDAP without losing registration information.

---

Applies to:

Hyperion Financial Management - Version: 4.1.1.0.00 to 11.1.1.4.000 - Release: 4.1 to 11.1
Hyperion Planning - Version: 4.1.0.0.00 to 11.1.1.4.000   [Release: 4.1 to 11.1]
Hyperion Essbase - Version: 9.0.0.0.00 to 11.1.1.4.000   [Release: 9.0 to 11.1]
Hyperion BI+ - Version: 9.0.0.0.00 to 11.1.1.4.000   [Release: 9.0 to 11.1]
Information in this document applies to any platform.

Purpose

Since the very first release of Hyperion System 9, the Shared Services product has used an OpenLDAP instance for rapid storage and retrieval of provisioning information. This document will try to clarify what this means, which problems it might involve, how you can perform common maintenance tasks and advanced configuration. 

Questions and Answers

Fundamentals

What is OpenLDAP?

LDAP is an acronym for the Lightweight Directory Access Protocol, a network standard developed for managing large hierarchies (directories) of objects.
As defined on the main project page, OpenLDAP is "a robust, commercial-grade, fully featured, and open source LDAP suite of applications and development tools. The project is managed by a worldwide community of volunteers".

What does Shared Services store in OpenLDAP ?

All the provisioning information related to Roles is stored in OpenLDAP. All products contact this service at authentication time to define which roles are assigned to the user. If the OpenLDAP service is not available, users cannot log on to any product.
"Native Directory" users' information is also entirely stored in OpenLDAP.

Which version of OpenLDAP is shipped with Shared Services?

Shared Services ships with a pre-configured version of OpenLDAP release 2.3.7

Where can I find any documentation on OpenLDAP?

See the extensive OpenLDAP Administrator Guide

What is BDB and why it is also included with SharedServices ?

Oracle Berkeley DB is "the industry-leading open source, embeddable database engine that provides developers with fast, reliable, local persistence". OpenLDAP uses BDB for data persistence in its default configuration.

Maintenance

Is it really necessary to backup OpenLDAP ?

Yes. OpenLDAP is an essential service for Hyperion System 9, and it's required by any System 9 version, up to and including the 9.3.x release. A corrupted repository will mean the complete loss of all provisioning information. All Native Directory users will also be deleted and the content linked to them will be mostly unrecoverable.

Unfortunately, it's not uncommon for the repository to become corrupted following an unexpected (power loss etc) or forced shutdown. Often, a simple reboot will produce minor corruptions. For this reason, Oracle strongly recommends daily or weekly backups.

Can I run a "hot" backup, without stopping the service ?

You can do this, but you should keep in mind that what you will obtain from a "hot backup" is not a full snapshot, but rather an incremental backup. As described by the BDB documentation page on archiving and restoring, "a snapshot is a full backup, whereas the periodic archival of the current log files is an incremental backup. For example, it might be reasonable to take a full snapshot of a database environment weekly or monthly, and archive additional log files daily. Using both the snapshot and [all] the log files [archived since then], a catastrophic crash at any time can be recovered to the time of the most recent log archival; a time long after the original snapshot."

How can you create a back up?

The easiest way to perform a backup is simply to copy the entire $HYPERION_HOME/SharedServices/9.x.x/OpenLDAP folder. However, this will not perform BDB transaction-log trimming, so you will end up with an ever-growing folder and increased risks of repository corruption.

The best way to create a backup is by following this procedure:

1. Create a folder where you want to store your backup, e.g. C:\my_hss_backup
2. Stop the SharedServices web application
3. Stop the OpenLDAP service.
   Note: this will mean that nobody can log on any System9 product.
4. Open a shell or command prompt
5. Navigate to $HYPERION_HOME/SharedServices/9.x.x/server/scripts, for example:
   
   cd C:\Hyperion\SharedServices\9.x.x\server\scripts
6. execute the backup.bat / backup.sh script, passing as parameter the location of the previously created empty folder, e.g.:
   
   backup.bat C:\my_hss_backup
7. Restart the OpenLDAP instance
8. Restart the Shared Services web application

By following this procedure, you will end up with a full backup of your configuration in the specified folder (C:\my_hss_backup in the example), ready to be used for recovery. This backup procedure will also trim the BDB transaction logs to free up space.

Note that the provided scripts are just running standard BDB tools available in $HYPERION_HOME\SharedServices\9.x.x\OpenLDAP\bdb, pointing them at the repository files under $HYPERION_HOME\SharedServices\9.x.x\OpenLDAP\var\openldap-data. You can fine tune them, or build your own scripts, by following the instructions on the BDB documentation page on archiving and restoring.

How can you restore a back up?

Assuming you created a cold backup as specified in the previous question, you can simply follow this procedure:

1. Stop Shared Services web application
2. Stop the OpenLDAP service. If the service is already stopped, make sure that you don't have any "slapd" processes still running (in Windows by using Task Manager, in Unix environments with PS or similar), by killing them if necessary.
3. Navigate to $HYPERION_HOME/SharedServices/9.x/server/scripts, for example:
   
   cd C:\Hyperion\SharedServices\9.x\server\scripts
4. execute the recover.bat / recover.sh script, passing as parameter the location of the previously created backup, e.g.:
   
   recover.bat C:\my_hss_backup
5. Restart the OpenLDAP instance
6. Restart the Shared Services web application

If you did not take a cold backup at any point in time, you cannot use the provided recovery script.

If you did take a old backup at some point in time, and hot backups after that, you can restore that backup with this script, and then apply the following backups in the original sequence by following the instructions on the BDB documentation page on archiving and restoring.

Can I delete all those "logfiles" ?

No! Those are transaction logs produced by BDB, and are necessary to maintain repository integrity. Do not delete them manually. Perform a cold backup as specified above, and they will be automatically discarded.

When performing "hot" backups, the logs will NOT be discarded and will still be required.

Common Errors

Service fails to start with error code 21

This is the most common error, due to minor corruptions in the repository structure, usually following forced or unexpected system shutdown. Follow this procedure to attempt a simple recovery:

1. Make sure that you don't have any "slapd" processes still running (in Windows by using Task Manager, in unix environments with ps or similar), by killing them if necessary.
2. Open a shell or Command Prompt
3. Navigate to $HYPERION_HOME/SharedServices/9.x/OpenLDAP/var/openldap-data, e.g.:
   
   cd C:\Hyperion\SharedServices\9.x\OpenLDAP\var\openldap-data
4. launch db_recover like this:
   
   ..\..\bdb\bin\db_recover
5. If you receive an error message reporting a version mismatch, it means that db_recover found some files to be still in use by a process, killed that process, but couldn't execute the full procedure. Launch it again and again until the message stops appearing.

The BDB documentation page on Recovery contains further details and procedures to attempt.

Advanced configuration

How to reset OpenLDAP without losing registration information.

The quickest way to get back to a new blank openLDAP repository is to reset all the OpenLDAP data to the way it was just after the installation of Shared Services. At the end of this procedure, only the admin user will be available, but so long as you registered your products with the admin user and your Shared Services relational database is not touched, you will not have to reregister the products.

1. Stop the openLDAP service
2. Remove all files under $HYPERION_HOME/SharedServices/9.x.x/openLDAP/var/openldap-data
3. Run $HYPERION_HOME/SharedServices/9.x.x/openLDAP/ConfigureHubLDAP.bat
4. Start the OpenLDAP service and the Shared Services web application
5. Log into Shared Services and select Administration -> Sync Native Directory

Related Products Middleware > Enterprise Performance Management > Financial Management > Hyperion Financial Management Middleware > Enterprise Performance Management > Planning > Hyperion Planning Middleware > Enterprise Performance Management > Essbase > Hyperion Essbase Middleware > Business Intelligence > Hyperion Query & Reporting > Hyperion BI+ Keywords AUTHENTICATION; BACKUP; BERKELEY DB; DYNAMIC ADV FAQ; DYNAMIC ADV INSTALLTROUBLESHOOT; DYNAMIC ADV TROUBLESHOOT; HOT BACKUP; HYPERION FINANCIAL MANAGEMENT; HYPERION SHARED SERVICES; INCREMENTAL BACKUP; LDAP; LIGHTWEIGHT DIRECTORY ACCESS PROTOCOL; OPENLDAP; SERVICES; SHARED SERVICES

Back to top