Edge Documentation

This page details the steps for configuring the enPortal 4.x system to fail over during an outage to a backup system.

Database Configuration

This section outlines the procedures for converting the database configuration from a standard, single-node enPortal system to a multi-node system that can fail over to a backup database in the event that the primary database server becomes unavailable.

The examples in this section use an Oracle database. This is the most common database platform used with enPortal systems that support failover.

Implement Pre-requisites

Perform the following steps prior to making any changes to the enPortal configuration:

• Verify that the portal is running and properly connecting to the Oracle database using the standard thin client configuration in $PORTAL_HOME/config/persist.properties.
• Go to the Oracle website. Download and install the Oracle client into /opt/oracle/.

Oracle Instant Client is a minimal Oracle installation that contains the JDBC libraries, OCI libraries, SQLplus library, and other basic core components. This installation is sufficient for enPortal’s needs, and is much smaller than the full Oracle Client package. Make sure sqlplus is downloaded as part of Oracle Instant Client package.

• Determine if there is a folder $PORTAL_HOME/xmlroot/server/backup/ that represents the current data in the database. If not, you should create this folder as a database backup by navigating to $PORTAL_HOME/bin/ and executing the portal XMLexport command.
• Obtain a template Oracle configuration file tnsnames.ora, and place it in /opt/oracle/.

Configure Database Failover Connections

You must update the Oracle and enPortal configuration files to instruct the system how to fail over from the primary database to the alternate database. To do this, perform the following steps:

• Edit the file /opt/oracle/tnsnames.ora.
  • Provide an ADDRESS line for each database in the failover sequence. Enter the appropriate host and port for each database.
  • Enter the appropriate SERVICE_NAME for connecting to the database.

• Verify that the LD_LIBRARY_PATH variable contains a path to the libraries downloaded as part of Instant Client. One way to do this is to just make links from /usr/lib/ to all of the libraries included in the Instant Client download. The reason is that /usr/lib/ is by default in the LD_LIBRARY_PATH, so just linking in these libs will automatically make them available.
  • Example: Instant Client downloaded to /opt/oracle/, and there was a lib in that directory called libodbc.so. Create a link in the /usr/lib/ directory by executing the command: ln -s /opt/oracle/libodbc.so /usr/lib/libodbc.so.
  • Repeat for each library in the Instant Client package.

• Use the sqlplus command line tool to verify that a connection to database is working as configured in tnsnames.ora.
  • Make sure you have the directory where you downloaded the package in your LD_LIBRARY_PATH, and make sure the TNS_ADMIN variable is also set to that same install directory.
  • From the directory where you downloaded the Instant Client package, execute the following command: ./sqlplus username@DB_NAME where username is a valid password to the portal database, and DB_NAME corresponds to the entry in your tnsnames.ora file for the portal. A prompt for the portal password will display.
  • If you enter the correct password, you should have command-line SQL access to the Database. This will verify that the tnsnames.ora file is configured correctly.

• Edit the file $PORTAL_HOME/config/persist.properties.
  • Verify that persisting=true.
  • Update the db.driver: oracle.jdbc.driver.OracleDriver.
  • Update the db.URL: jdbc\:oracle\:oci\:@TNSLABEL where TNSLABEL is the label for the failover configuration to use in the tnsnames.ora file.

• Edit the portal start script $PORTAL_HOME/bin/portal. Add the parameter tns_admin=opt/oracle.

Re-start enPortal

Restarting enPortal will test whether the changes are successful.

Develop a thorough understanding of the procedures in this section on a test system before deploying any changes to your production system.

Perform the following steps to re-start enPortal:

1. Confirm whether the database you will be using under the new configuration already contains the portal data.
   • If the database already contains data, then make sure there are not any load*.txt files under $PORTAL_HOME/xmlroot/server/. These files should all be renamed with alternate extensions such as .completed.
   • If enPortal will now be connecting to a new (empty) database, verify the existence of the file $PORTAL_HOME/xmlroot/server/load_restore.txt. This file will load all of the XML data from $PORTAL_HOME/xmlroot/server/backup/ into the new database.
2. Navigate to $PORTAL_HOME/bin/.
3. Execute the command: portal portalstop.
4. Execute the command: portal portalstart.
5. Review the output to the terminal for indication of a successful database connection.
6. Open a browser from a location with network access to the portal web server. Navigate to the URL: https://hostname:port. If the system login page is displayed, this confirms that the portal made a successful connection to the database.