Sun Java System Application Server Enterprise Edition 8.1 2005Q2 High Availability Administration Guide

- Previous: Chapter 1 Application Server High Availability Features
- Next: Chapter 3 Administering High Availability Database

# Chapter 2 Installing and Setting Up High Availability Database

This chapter covers the following topics:

- Overview of High Availability Database

- Preparing for HADB Setup

- Installation

- Setting up High Availability

- Upgrading HADB

# Overview of High Availability Database

This section introduces the high availability database (HADB) and describes how to set up and configure HADB for use with the Application Server.

This section contains the following topics:

- HADB and Application Server

- HADB Server Architecture

- HADB Nodes

## HADB and Application Server

HADB is a horizontally-scalable database that can be run and managed independently of the application server tier. It is designed to support up to 99.999% service and data availability with load balancing, failover, and state recovery capabilities.

Application Server uses HADB to store HTTP and stateful session bean (SFSB) session data. Without a session persistence mechanism, the HTTP or SFSB session state data is lost when a web or EJB container fails over.

Keeping state management separate from Application Server has significant benefits. Application Server instances spend their cycles performing as a scalable and high performance Java™ 2 Platform, Enterprise Edition (J2EE™ platform) containers delegating state replication to an external high availability state service. Due to this loosely coupled architecture, you can easily add application server instances to and remove instances from a cluster. You can independently scale HADB state replication service for optimum availability and performance.

## HADB Server Architecture

High availability means availability despite planned outages for upgrades or unplanned outages caused by hardware or software failures. HADB is based on a simple data model and redundant, scalable, and high performance technology. HADB offers an ideal platform for delivering all types of session state persistence within a high performance enterprise application server environment.

The following figure shows the architecture of a database with four active nodes and two spare nodes. Nodes 0 and 1 are a mirror node pair, as are nodes 2 and 3.

##### Figure 2–1 HADB Architecture

HADB achieves high data availability through fragmentation and replication of data. All tables in the database are partitioned to create subsets of approximately the same size called fragments. Fragmentation is based on a hash function that evenly distributes the data among the nodes of the database. Each fragment is stored twice in the database, in mirror nodes. This ensures fault tolerance and fast recovery of data. In addition, if a node fails, or is shut down, a spare node can take over until the node is active again.

HADB nodes are organized into two Data Redundancy Units (DRUs), which mirror each other. Each DRU consists of half of the active and spare nodes, and contains one complete copy of the data. To ensure fault tolerance, the computers that support one DRU must be completely self-supported with respect to power (use of uninterruptible power supplies is recommended), processing units, and storage. If a power failure occurs in one DRU, the nodes in the other DRU can continue servicing requests until the power returns.

Without a session persistence mechanism, the HTTP or SFSB session state, including the passivated session state, is lost when one web or EJB container fails over to another. Use of the HADB for session persistence overcomes this situation. The HADB stores and retrieves state information in a separate but well-integrated persistent storage tier.

HADB reclaims space when session data is deleted. HADB places session data records in fixed size blocks. When all records of a block are deleted, the block is freed. Records of a block can be deleted randomly, creating holes in the block. When a new record is inserted into a block and contiguous space is needed, the holes are removed and thus the block is compacted.

This is a brief summary of the architecture. For more information, see Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Deployment Planning Guide.

## HADB Nodes

A database node consists of a set of processes, a dedicated area of shared memory, and one or more secondary storage devices. The database stores, updates, and retrieves session data. Each node has a mirror node, therefore nodes occur in pairs. In addition, to maximize availability, include two or more spare nodes, one in each DRU, so if a node fails a spare can take over while the node is repaired.

For an explanation of node topology alternatives, see Chapter 3, Selecting a Topology, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Deployment Planning Guide.

## New Features and Improvements

The version of HADB provided with Sun Java System Application Server Enterprise Edition 8.1 has many new features and improvements.

HADB management is improved by changing the underlying components of the management system. The old `hadbm` interface functions are maintained with minor modifications. These changes also remove the dependency on SSH/RSH.

The management agent server process (`ma`) constitutes a domain and keeps the database configuration in a repository. The repository information is distributed among all agents.

The following topics provide more details:

- General Improvements

- Specific Changes

### General Improvements

This version of HADB has the following general improvements:

- HADB no longer requires SSH/RSH.

- Administrator password for HADB management enhances security.

- Automatic online upgrade to future versions.

- Dependency on a single host is removed.

- Heterogeneous configurations of the database is supported. The device paths and history paths can be set individually.

- Ability to manage multiple platforms uniformly.

### Specific Changes

This version of HADB includes the following changes from the previous version.

- UDP multicast is now required for network configuration.

- The management agent, `ma`, is now required to be running on all HADB hosts.

- New `hadbm` commands for domain management: `hadbm createdomain, hadbm deletedomain, hadbm extenddomain, hadbm reducedomain, hadbm listdomain, hadbm disablehost`. New commands for package management: `hadbm registerpackage, hadbm unregisterpackage, hadbm listpackage`

- All `hadbm` commands have the following new options:

  - `adminpassword`

  - `adminpasswordfile`

  - no-adminauthentication

  - `agent`

  - `javahome`

  Changes made to `hadbm create`:

  - New options:

    - `no-clear`

    - `no-cleanup`

    - `package`

    - `packagepath`

    - `agent`

    Extended options

    - `hosts` (registers hosts in the domain).

    - `set`

    Options removed:

    - `inetd`

    - `inetdsetupdir`

    - `configpath`

    - `installpath`

    - `set TotalDataDevideSizePerNode`

    - `set managementProtocol`

    Modified: `devicesize` is now optional, not required.

  The `hadbm startnode` and `hadbm restartnode` commands' `startlevel` option has a new value, `clear` .

  Changes made to `hadbm addnodes`: New options: `set`, `historypath`, `devicepath`. The `inetdsetupdir` option was removed.

  Changes made to `hadbm get` and `hadbm set`: New attributes are `historypath` (heterogeneous path for history files) and `packagename`. Attributes eliminated are: `managementProtocol`, `TotalDeviceSizePerNode`, `installpath`, and `syslogging`.

## Using Customer Support for HADB

Before calling customer support about HADB issues, gather as much of the following information as possible:

- System use profile:

  - Number of active concurrent users

  - Number of passive users

  - Number of users entering the system per second

  - Average session size

  - Session state timeout period (`SessionTimeout` value)

  - Transaction rate per user per second

  Machine properties:

  - RAM

  - Number of CPUs

  - CPU speed

  - Operating system version

  - Number of physical disks

  - Total disk size

  - Available disk space

  - Data transfer capacity

  Network properties:

  - Transfer capacity

  - Number of host names (network interfaces) per node

  HADB data:

  - History files

  - `cfg` and `meta` files, located in `dbconfigpath/`databasename `/`nodeno directory. `dbconfigpath` is defined in the variable `ma.server.dbconfigpath` in the management agent configuration file.

  - Version information (`hadbm --version`)

# Preparing for HADB Setup

This section discusses the following topics:

- Prerequisites

- Configuring Shared Memory and Semaphores

- Configuring Network Redundancy

- Synchronizing System Clocks

- File System Support

  After performing these tasks, see Chapter 3, Administering High Availability Database.

  For the latest information on HADB, see Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Release Notes.

## Prerequisites

Before setting up and configuring HADB, make sure your environment meets the following requirements:

- IPv4 is enabled. HADB supports IPv4 only. Disable IPv6 on the interfaces being used for HADB.

- The network (routers, switches, and network interfaces on the hosts) must be configured for User Datagram Protocol (UDP) multicast. If HADB hosts span multiple subnets, configure routers between the subnets to forward UDP multicast messages between the subnets.

- Configure any firewalls located between HADB hosts, or between HADB and Application Server hosts to allow all UDP traffic, both ordinary and multicast.

- Do not use dynamic IP addresses (assigned by Dynamic Host Configuration Protocol, or DHCP) for hosts that are part of `hadbm createdomain`, `hadbm extenddomain`, `hadbm create,` or `hadbm` `addnodes` commands.

## Configuring Network Redundancy

Configuring a redundant network will enable HADB to remain available, even if there is a single network failure. You can configure a redundant network in two ways:

- On Solaris 9, you can set up network multipathing.

- Configure a double network, supported on all platforms except Windows Server 2003.

### Setting Up Network Multipathing

Before setting up network multipathing, refer to the Administering Network Multipathing section in the IP Network Multipathing Administration Guide.

#### To configure HADB host machines that already use IP multipathing:

1. Set network interface failure detection time.

   For HADB to properly support multipathing failover, the network interface failure detection time must not exceed one second (1000 milliseconds), as specified by the `FAILURE_DETECTION_TIME` parameter in `/etc/default/mpathd`. Edit the file and change the value of this parameter to 1000 if the original value is higher:

       FAILURE_DETECTION_TIME=1000

   To put the change into effect, use this command:

       pkill -HUP in.mpathd

2. Set up IP addresses to use with HADB.

   As described in the IP Network Multipathing Administration Guide, multipathing involves grouping physical network interfaces into multipath interface groups. Each physical interface in such a group has two IP addresses associated with it:

   - a physical interface address used for transmitting data.

   - a test address for Solaris internal use only.

   Specify only one physical interface address from the multipath group when you use `hadbm create --hosts`.

##### Example 2–1 Setting up Multipathing

Suppose there are two host machines named host1 and host2. If they each have two physical network interfaces, then set up the two interfaces as a multipath group. Run `ifconfig -a` on each host.

The output on host1 is:

    bge0: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4>
    mtu 1500 index 5 inet 129.159.115.10 netmask ffffff00 broadcast 129.159.115.255
    groupname mp0

    bge0:1: flags=9040843<UP,BROADCAST,RUNNING,MULTICAST,DEPRECATED,IPv4,NOFAILOVER>
    mtu 1500 index 5 inet 129.159.115.11 netmask ffffff00 broadcast 129.159.115.255

    bge1: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4>
    mtu 1500 index 6 inet 129.159.115.12 netmask ffffff00 broadcast 129.159.115.255
    groupname mp0

    bge1:1: flags=9040843<UP,BROADCAST,RUNNING,MULTICAST,DEPRECATED,IPv4,NOFAILOVER>
    mtu 1500 index 6 inet 129.159.115.13 netmask ff000000 broadcast 129.159.115.255

The output on host2 is:

    bge0: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4>
    mtu 1500 index 3 inet 129.159.115.20 netmask ffffff00 broadcast 129.159.115.255
    groupname mp0

    bge0:1: flags=9040843<UP,BROADCAST,RUNNING,MULTICAST,DEPRECATED,IPv4,NOFAILOVER>
    mtu 1500 index 3 inet 129.159.115.21 netmask ff000000 broadcast 129.159.115.255

    bge1: flags=1000843<UP,BROADCAST,RUNNING,MULTICAST,IPv4>
    mtu 1500 index 4 inet 129.159.115.22 netmask ffffff00 broadcast 129.159.115.255
    groupname mp0

    bge1:1: flags=9040843<UP,BROADCAST,RUNNING,MULTICAST,DEPRECATED,IPv4,NOFAILOVER>
    mtu 1500 index 4 inet 129.159.115.23 netmask ff000000 broadcast 129.159.115.255

In this example, the physical network interfaces on both hosts are listed after `bge0` and `bge1`. Those listed after `bge0:1` and `bge1:1` are multipath test interfaces (marked DEPRECATED in the `ifconfig` output), as described in the IP Network Multipathing Administration Guide.

To set up HADB in this environment, select one physical interface address from each host. In this example, HADB uses IP address 129.159.115.10 from host1 and 129.159.115.20 from host2. To create a database with one database node per host, use the command `hadbm create --host`. For example

    hadbm create --host 129.159.115.10,129.159.115.20

To create a database with two database nodes on each host, use the command:

    hadbm create --host 129.159.115.10,129.159.115.20,
    129.159.115.10,129.159.115.20

In both cases, you must configure the agents on host1 and host2 with separate parameters to specify which interface on the machines the agents should use. So, on host1 use:

    ma.server.mainternal.interfaces=129.159.115.10

And on host2 use:

    ma.server.mainternal.interfaces=129.159.115.20

For information on the `ma.server.mainternal.interfaces` variable, see Configuration File.

### Configuring Double Networks

To enable HADB to tolerate single network failures, use IP multipathing if the operating system (for example, Solaris) supports it. Do not configure HADB with double networks on Windows Server 2003—the operating system does not work properly with double networks.

If your operating system is not configured for IP multipathing, and HADB hosts are equipped with two NICs, you can configure HADB to use double networks. For every host, the IP addresses of each of the network interface card (NIC) must be on separate IP subnets.

Within a database, all nodes must be connected to a single network, or all nodes must be connected to two networks.

Note –

Routers between the subnets must be configured to forward UDP multicast messages between subnets.

When creating an HADB database, use the –hosts option to specify two IP addresses or host names for each node: one for each NIC IP address. For each node, the first IP address is on net-0 and the second on net-1. The syntax is as follows, with host names for the same node separated by a plus sign (+):

    --hosts=node0net0name+node0net1name
    ,node1net0name+node1net1name
    ,node2net0name+node2net1name
    , ...

For example, the following argument creates two nodes, each with two network interfaces. The following host option is used to create these nodes:

    --hosts 10.10.116.61+10.10.124.61,10.10.116.62+10.10.124.62

Thus, the network addresses

- For node0 are `10.10.116.61` and `10.10.124.61`

- For node1 are `10.10.116.62` and `10.10.124.62`

Notice that `10.10.116.61` and `10.10.116.62` are on the same subnet, and `10.10.124.61` and `10.10.124.62` are on the same subnet.

In this example, the management agents must use the same subnet. Thus, the configuration variable `ma.server.mainternal.interfaces` must be set to, for example, `10.10.116.0/24`. This setting can be used on both agents in this example.

## Configuring Shared Memory and Semaphores

You must configure shared memory and semaphores before installing HADB. The procedure depends on your operating system.

### To configure shared memory and semaphores on Solaris

1. Log in as root.

2. Configure shared memeory.

   Set the value of `shmmax` to the size of the physical memory on the HADB host machine. The maximum shared memory segment size must be larger than the size of the HADB database buffer pool. For example, for a machine with a 2 GByte (0x8000000 hexadecimal) main memory, add the following to the `/etc/system` file:

       set shmsys:shminfo_shmmax=0x80000000
        set shmsys:shminfo_shmseg=20

   On Solaris 9 and later, `shmsys:shminfo_shmseg` is obsolete.

   Set `shminfo_shmmax` to the total memory in your system (in hexadecimal notation the value `0x80000000` shown is for 2 Gigabytes of memory).

   Note –

   Specify the value of `shmsys:shminfo_shmmax` using the hexadecimal value for the memory size. To determine your host’s memory, use this command:

       prtconf | grep Memory

3. Configure semaphores.

   Check the `/etc/system` file for semaphore configuration entries. This file might already contain `semmni`, `semmns`, and `semmnu` entries. For example:

       set semsys:seminfo_semmni=10
       set semsys:seminfo_semmns=60
       set semsys:seminfo_semmnu=30

   If the entries are present, increment the values by adding 16, 128, and 1000 respectively. So, the entries in the example above would change to:

       set semsys:seminfo_semmni=26
       set semsys:seminfo_semmns=188
       set semsys:seminfo_semmnu=1030

   If the `/etc/system` file does not these entries, add them at the end of the file:

       set semsys:seminfo_semmni=16
       set semsys:seminfo_semmns=128
       set semsys:seminfo_semmnu=1000

   This is sufficient to run up to 16 HADB nodes on the computer. For information on setup for more than 16 nodes, see the HADB chapter in the Sun Java System Application Server Enterprise Edition 8.1 2005Q1 Performance Tuning Guide.

4. Reboot the machine.

### To configure shared memory on Linux

1. Log in as root.

2. Edit the file `/etc/sysctl.conf`

3. Set the `kernel.shmax` and `kernel.shmall` parameters.

   The `kernel.shmax` parameter defines the maximum size in bytes for a shared memory segment. The `kernel.shmall` parameter sets the total amount of shared memory in pages that can be used at one time on the system. Set the value of both of these parameters to the amount physical memory on the machine. Specify the value as a decimal number of bytes. For example, for a machine having 512 Mbytes of physical memory:

       kernel.shmmax=536870912
        kernel.shmall=536870912

4. Reboot the machine. using this command:

   `sync; sync; reboot`

### Procedure for Windows

Windows does not require any special system settings. However, if you want to use an existing J2SE installation, set the `JAVA_HOME` environment variable to the location where the J2SE is installed.

## Synchronizing System Clocks

You must synchronize clocks on HADB hosts, because HADB uses time stamps based on the system clock. HADB uses the system clock to manage timeouts and to time stamp events logged to history files. For troubleshooting, you must analyze all the history files together, since HADB is a distributed system. So, it is important that all the hosts’ clocks be synchronized

Do not adjust system clocks on a running HADB system. Doing so can cause problems in the operating system or other software components that can in turn cause problems such as hangs or restarts of HADB nodes. Adjusting the clock backward can cause some HADB server processes to hang as the clock is adjusted.

To synchronize clocks:

- On Solaris, use `xntpd` (network time protocol daemon).

- On Linux, use `ntpd`.

- On Windows, use `NTPTime` on Windows

If HADB detects a clock adjustment of more than one second, it logs it to the node history file, for example:

    NSUP INF 2003-08-26 17:46:47.975 Clock adjusted.
     Leap is +195.075046 seconds.

## File System Support

This section describes some restrictions of HADB with certain file systems.

### Red Hat Enterprise Linux

HADB supports the ext2 and ext3 file systems on Red Hat Enterprise Linux 3.0. For Red Hat Enterprise Linux 2.1, HADB supports the ext2 file system.

### Veritas File System

When using the Veritas File System on Solaris, HADB writes the message `WRN: Direct disk I/O mapping failed` to the history files. This message indicates that HADB cannot turn on direct input/output (I/O) for the data and log devices. Direct I/O reduces the CPU cost of writing disk pages. It also reduces overhead of administering “dirty” data pages in the operating system.

To use direct I/O with Veritas File System, do one of the following:

- Create the data and log devices on a file system that is mounted with the option `mincache=direct`. This option applies to all files created on the file system. Check the `mount_vxfs(1M)` command for details.

- Use the Veritas Quick I/O facility to perform raw I/O to file system files. For details, see the VERITAS File System 4.0 Administrator’s Guide for Solaris.

Note –

These configurations have not been tested with the Sun Java System Application Server.

# Installation

In general, you can install HADB on the same system as Application Server (co-located topology) or on separate hosts (separate tier topology). For more information on these two options, see Chapter 3, Selecting a Topology, in Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Deployment Planning Guide. However, you must install the HADB management client to be able to set up high availability with the `asadmin ha-config-cluster` command. When using the Java Enterprise System installer, you must install an entire HADB instance to install the management client, even if the nodes are to be installed on a separate tier.

## HADB Installation

On a single or dual CPU system, you can install both HADB and Application Server if the system has at least two Gbytes of memory. If not, install HADB on a separate system or use additional hardware. To use the `asadmin ha-configure-cluster command` , you must install both HADB and Application Server.

Each HADB node requires 512 Mbytes of memory, so a machine needs one Gbyte of memory to run two HADB nodes. If the machine has less memory, set up each node on a different machine. For example, you can install two nodes on:

- Two single-CPU systems, each with 512 Mbytes to one Gbyte of memory

- A single or dual CPU system with one Gbyte to two Gbytes of memory

  You can install HADB with either the Java Enterprise System installer or the Application Server standalone installer. In either installer, choose the option to install HADB (called High Availability Session Store in Java ES) in the Component Selection page. Complete the installation on your hosts. If you are using the Application Server standalone installer, and choose two separate machines to run HADB, you must choose an identical installation directory on both machines.

### Default Installation Directories

Throughout this manual, HADB_install_dir represents the directory in which HADB is installed. The default installation directory depends on whether you install HADB as part of the Java Enterprise System. For Java Enterprise System, the default installation directory is `/opt/SUNWhadb/4`. For the standalone Application Server installer, it is `/opt/SUNWappserver/hadb/4` .

## Node Supervisor Processes Privileges

The node supervisor processes (NSUP) ensure the availability of HADB by exchanging “I’m alive” messages with each other. The NSUP executable files must have root privileges so they can respond as quickly as possible. The `clu_nsup_srv` process does not consume significant CPU resources, has a small footprint, and so running it with real-time priority does not affect performance.

Note –

The Java Enterprise System installer automatically sets the NSUP privileges properly, so you do not need to take any further action. However, with the standalone Application Server (non-root) installer, you must set the privileges manually before creating a database.

### Symptoms of Insufficient Privileges

If NSUP executables do not have the proper privileges, you might notice symptoms of resource starvation such as:

- Performance issues or `HIGH LOAD` messages in the HADB history log.

- False network partitioning and node restarts, preceded by a warning “Process blocked for x seconds” in HADB history files.

- Aborted transactions and other exceptions.

### Restrictions

If NSUP cannot set the real-time priority `errno` is set to EPERM on Solaris and Linux. On Windows it issues the warning “Could not set realtime priority”. The error is written to the `ma.log` file, and the process continues without real-time priority.

Setting real-time priorities is not possible when:

- HADB is installed in Solaris 10 non-global zones

- `PRIV_PROC_LOCK_MEMORY` (allow a process to lock pages in physical memory) and/or `PRIV_PROC_PRIOCNTL` privileges are revoked in Solaris 10

- Users turn off setuid permission

- Users install the software as tar files (the non-root installation option for the Application Server)

### To Give Node Supervisor Processes Root Privileges

1. Log in as root.

2. Change your working directory to HADB_install_dir`/lib/server`.

   The NSUP executable file is `clu_nsup_srv` .

3. Set the file’s `suid` bit with this command:

   `chown root clu_nsup_srv`

4. Set the file’s ownership to root with this command:

   `chmod u+s clu_nsup_srv`

   This starts the `clu_nsup_srv` process as root, and enables the process to give itself realtime priority.

   To avoid any security impact, the real-time priority is set immediately after the process is started and the process falls back to the effective UID once the priority has been changed. Other HADB processes run with normal priority.

# Setting up High Availability

This section provides the steps for creating a highly available cluster, and testing HTTP session persistence.

This section discusses the following topics:

- Prerequisites

- Starting the HADB Management Agent

- Configuring a Cluster for High Availability

- Configuring an Application for High Availability

- Restarting the Cluster

## Prerequisites

Before configuring HADB, do the following:

### To prepare your system for High Availability

1. Install Application Server instances and the Load Balancer Plug-in.

   For more information, see the Java Enterprise System Installation Guide (if you are using Java ES) or Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Installation Guide (if you are using the standalone Application Server installer).

2. Create Application Server domains and clusters.

   For more information, see the Sun Java System Application Server Enterprise Edition 8.1 2005Q2 Administration Guide.

3. Install and configure your web server software.

   For more information, see Configuring Web Servers for Load Balancing

4. Setup and configure load balancing.

   For more information, see Setting Up HTTP Load Balancing.

## Starting the HADB Management Agent

The management agent, `ma`, executes management commands on HADB hosts and ensures availability of the HADB node supervisor processes by restarting them if they fail.

For a production deployment, start the management agent as a service to ensure its availability. This section provides abbreviated instructions for starting the management agent as a service with its default configuration.

For more details, including instructions on starting the management agent in console mode for testing or evaluation and information on customizing its configuration, see Using the HADB Management Agent.

This section describes how to start the management agent as a service with default configuration when using Java Enterprise System.

### To Start the Management Agent with Java Enterprise System on Solaris or Linux

1. Create the following softlinks to the file `/etc/init.d/ma-initd`:

       /etc/rc0.d/K20ma-initd
       /etc/rc1.d/K20ma-initd
       /etc/rc2.d/K20ma-initd
       /etc/rc3.d/S99ma-initd
       /etc/rc5.d/S99ma-initd
       /etc/rcS.d/K20ma-initd

2. Reboot the machine.

   To deactivate automatic start and stop of the agent, remove the links or change the letters K and S in the link names to lowercase.

### To Start the Management Agent with Java Enterprise System on Windows

1. Open a command window.

2. Enter the command: `HADB_install_dir\bin\ma -i`.

   This installs and starts the management agent with its default configuration.

##### Next Steps

To stop the management agent and remove (deregister) it as a service, use the command: `HADB_install_dir\bin\ma -r`

### To Start the Management Agent with Standalone Application Server on Solaris or Linux

1. In a shell, change your current directory to HADB_install_dir `/bin`.

2. Edit the shell script `ma-initd` .

   Replace the default values of HADB_ROOT and HADB_MA_CFG in the script to reflect your installation:

   - HADB_ROOT is the HADB installation directory, HADB_install_dir.

   - HADB_MA_CFG is the location of the management agent configuration file. For more information, see Customizing Management Agent Configuration

3. Copy `ma-initd` to the directory `/etc/init.d`

4. Create the following soft links to the file `/etc/init.d/ma-initd`:

       /etc/rc0.d/K20ma-initd
       /etc/rc1.d/K20ma-initd
       /etc/rc2.d/K20ma-initd
       /etc/rc3.d/S99ma-initd
       /etc/rc5.d/S99ma-initd
       /etc/rcS.d/K20ma-initd

### To Start the Management Agent with Standalone Application Server on Windows

1. Open a command window.

2. Enter the command: `HADB_install_dir\bin\ma -i ma.cfg`

   Now if the process fails or the machine reboots, the management agent will automatically restart.

##### Next Steps

To stop the management agent and remove (deregister) it as a service, use the command: `HADB_install_dir\bin\ma -r ma.cfg`

## Configuring a Cluster for High Availability

Before starting this section, you must have created one or more Application Server clusters. For information on how to create a cluster, see To Create a Cluster.

From the machine on which the Domain Administration Server is running, configure the cluster to use HADB using this command:

`asadmin configure-ha-cluster --user admin --hosts hadb_hostname,hadb_hostname --devicesize 256 clusterName`

Replace hadb_hostname with the host name of the machine where HADB is running, and clusterName with the name of the cluster. If you are using just one machine, you must provide the host name twice.

This simplified example runs two nodes of HADB on the same machine. In production settings, using more than one machine is recommended.

## Configuring an Application for High Availability

In Admin Console, select the application under Applications > Enterprise Applications. Set Availability Enabled and then click Save.

## Restarting the Cluster

To restart a cluster in Admin Console, choose Clusters > cluster-name. Click Stop Instances. Once the instances have stopped, click “Start Instances.”

Alternatively, use these `asadmin` commands:

    asadmin stop-cluster --user admin cluster-name
    asadmin start-cluster --user admin cluster-name

For more information on these commands, see stop-cluster(1) and start-cluster(1).

## Restarting the Web Server

To restart the Web Server, type this Web Server command:

    web_server_root/https-hostname/reconfig

Replace web_server_root with your Web Server root directory and hostname with the name of your host machine.

## To Clean Up the Web Server Instance Acting as Load Balancer

1. Delete the Load Balancer configuration:

   `asadmin delete-http-lb-ref --user admin --config MyLbConfig FirstCluster`

   `asadmin delete-http-lb-config --user admin MyLbConfig`

2. If you created a new Web Server instance you can delete it by:

   1. Log on to the Web Server’s Administration Console.

   2. Stop the instance.

      Delete the instance.

# Upgrading HADB

HADB is designed to provide “always on” service that is uninterrupted by upgrading the software. This section describes how to upgrade to a new version of HADB without taking the database offline or incurring any loss of avaiability.

The following sections describe how to upgrade your HADB installation:

- To upgrade HADB to a newer version

- Registering HADB Packages

- Unregistering HADB Packages

- Replacing the Management Agent Startup Script

## To upgrade HADB to a newer version

1. Install new version of HADB.

2. Unregister your existing HADB installationas described in Unregistering HADB Packages

3. Register the new HADB version, as described in Registering HADB Packages

   Registering the HADB package in the HADB management domain makes it easy to upgrade or change HADB packages. The management agent keeps track of where the software packages are located, as well as the version information for the hosts in the domain. The default package name is a string starting with V and containing the version number of the `hadbm` program.

4. Change the package the database uses.

   Enter the following command:

       hadbm set PackageName=package

   where package is the version number of the new HADB pacakge.

5. If neccessary, replace the management agent startup script.

   For more information, see Replacing the Management Agent Startup Script

## Registering HADB Packages

Use the `hadbm registerpackage` command to register the HADB packages that are installed on the hosts in the management domain. HADB packages can also be registered when creating a database with `hadbm create`.

Before using the `hadm registerpackage` command, ensure that all management agents are configured and running on all the hosts in the hostlist, the management agent’s repository is available for updates, and no software package is already registered with the same package name.

The command syntax is:

`hadbm registerpackage `--packagepath=`path [`--hosts`=hostlist] [`--adminpassword`=password | `--adminpasswordfile`=file] [`--agent`=maurl]` [[package-name]]

The package-name operand is the name of the package.

The following table describes the special `hadbm registerpackage` command option. See Security Options and General Options for a description of other command options.

Table 2–1 `hadbm registerpackage` Options

Option | Description
--- | ---
--hosts=hostlist -H | List of hosts, either comma-separated or enclosed in double quotes and space separated.
--packagepath=path -L | Path to the HADB software package.

For example, the following command registers software package v4 on hosts host1, host2, and host3:

    hadbm registerpackage
    --packagepath=hadb_install_dir/SUNWHadb/4.4
    --hosts=host1,host2,host3 v4

The response is:

`Package successfully registered.`

If you omit the `--hosts` option, the command registers the package on all enabled hosts in the domain.

## Unregistering HADB Packages

Use the `hadbm unregisterpackage` command to remove HADB packages that are registered with the management domain.

Before using the `hadbm unregisterpackage` command, ensure that all management agents are configured and running on all the hosts in the hostlist, the management agent’s repository is available for updates, the package is registered in the management domain, and no existing databases are configured to run on the package about to be unregistered.

The command syntax is:

    hadbm unregisterpackage
    --hosts=hostlist
    [--adminpassword=password | --adminpasswordfile= file]
    [--agent= maurl]
    [package-name ]

The package-name operand is the name of the package.

See Registering HADB Packages above for a description of the `--hosts` option. If you omit the `--hosts` option, the hostlist defaults to the enabled hosts where the package is registered. See Security Options and General Options for a description of other command options.

##### Example 2–2 Example of unregistering HADB

To unregister software package v4 from specific hosts in the domain:

`hadbm unregisterpackage --hosts=host1,host2,host3 v4`

The response is:

`Package successfully unregistered.`

## Replacing the Management Agent Startup Script

When you install a new version of HADB, you may need to replace the management agent startup script in `/etc/init.d/ma-initd`. Check the contents of the file, HADB_install_dir`/lib/ma-initd`. If it is different from the old `ma-initd` file, replace the old file with the new file.

- Previous: Chapter 1 Application Server High Availability Features
- Next: Chapter 3 Administering High Availability Database

- © 2010, Oracle Corporation and/or its affiliates