Configuration Generator for Oracle Maximum Availability Architectures

Specification

This page describes the XML document used to specify the MAAGEN configuration

The XML document is used by the Perl script (maagen.pl) to generate the MAA configuration files and scripts.

The Perl script (maagen.pl) converts the XML elements in the document into objects and attributes from which the scripts are generated.

Sample XML Document

The following is an example of an XML configuration file for an MAA configuration containing the following:

Within the XML document:

<configuration name="PROD">
  <operating_system>Linux</operating_system>
  <shell>/bin/bash</shell>
  <scripts_dir>/home/oracle/scripts/dataguard</scripts_dir>
  <orainst_location>/etc/oraInst.loc</orainst_location>
  <inventory_location>/u01/app/oraInventory</inventory_location>
  <dba_group>dba</dba_group>
  <temp_dir>/tmp</temp_dir>
  <domain_name>juliandyke.com</domain_name>
  <tns_domain_name>JULIANDYKE.COM</tns_domain_name>
  <cluster name="bristol">
    <grid_user>grid</grid_user>
    <location>Bristol</location>
    <base_dir>/u01/app/grid</base_dir>
    <home_name>ORACLE_11204_grid_1</home_name>
    <home_path>/u01/app/11.2.0.4/grid_1</home_path>
    <disk_group_name>BRISTOL_OCRVOTE</disk_group_name>
    <default_listener_name>LISTENER</default_listener_name>
    <vip_template>{nodename}-vip</vip_template>
    <scan_name>bristol-scan</scan_name>
    <scan_addresses>10.223.66.41,10.223.66.42,10.223.66.43</scan_addresses>
    <scan_port>1521</scan_port>
    <scan_protocol>TCP</scan_protocol>
    <user name="grid">
      <group_name>oinstall</group_name>
      <home_dir>/u01/app/grid</home_dir>
    </user>
    <user name="oracle">
      <group_name>oinstall</group_name>
      <home_dir>/u01/app/oracle</home_dir>
    </user>
    <node name="bristol1">
      <node_number>1</node_number>
    </node>
    <node name="bristol2">
      <node_number>2</node_number>
    </node>
    <adapter name="bond0">
      <network_type>PUBLIC</network_type>
      <subnet>10.223.66.0</subnet>
      <subnet_mask>255.255.255.0</subnet_mask>
    </adapter>
    <adapter name="bond1">
      <network_type>PRIVATE</network_type>
      <subnet>192.168.1.0</subnet>
      <subnet_mask>255.255.255.0</subnet_mask>
    </adapter>
    <listener name="LISTENER">
      <protocol>TCP</protocol>
      <port>1521</port>
    </listener>
    <disk_group name="BRISTOL_OCRVOTE">
      <redundancy>NORMAL</redundancy>
      <au_size>1</au_size>
      <disk_file name="/dev/mapper/ORA_BRISTOL_OCRVOTE_01p1">
        <size>10GB</size>
      </disk_file>
      <disk_file name="/dev/mapper/ORA_BRISTOL_OCRVOTE_02p1">
        <size>10GB</size>
      </disk_file>
      <disk_file name="/dev/mapper/ORA_BRISTOL_OCRVOTE_03p1">
        <size>10GB</size>
      </disk_file>
    </disk_group>
    <disk_group name="PRODBRIS_DATA">
      <redundancy>EXTERNAL</redundancy>
      <au_size>4</au_size>
      <disk_file name="/dev/mapper/ORA_PRODBRIS_DATA_01p1">
        <size>255000</size>
      </disk_file>
    </disk_group>
    <disk_group name="PRODBRIS_FRA">
      <redundancy>EXTERNAL</redundancy>
      <au_size>4</au_size>
      <disk_file name="/dev/mapper/ORA_PRODBRIS_FRA_01p1">
        <size>255000</size>
      </disk_file>
    </disk_group>
    <disk_group name="PRODBRIS_REDO">
      <redundancy>EXTERNAL</redundancy>
      <au_size>4</au_size>
      <disk_file name="/dev/mapper/ORA_PRODBRIS_REDO_01p1">
        <size>255000</size>
      </disk_file>
    </disk_group>
    <home name="ORACLE_11204_db_1">
      <user_name>oracle</user_name>
      <path>/u01/app/oracle/product/11.2.0.4/db_1</path>
    </home>
  </cluster>
  <cluster name="cardiff">
    <grid_user>grid</grid_user>
    <location>Cardiff</location>
    <base_dir>/u01/app/grid</base_dir>
    <home_name>ORACLE_11204_grid_1</home_name>
    <home_path>/u01/app/11.2.0.4/grid_1</home_path>
    <disk_group_name>CARDIFF_OCRVOTE</disk_group_name>
    <default_listener_name>LISTENER</default_listener_name>
    <vip_template>{nodename}-vip</vip_template>
    <scan_name>cardiff-scan</scan_name>
    <scan_addresses>10.230.123.71,10.230.123.72,10.230.123.73</scan_addresses>
    <scan_port>1521</scan_port>
    <scan_protocol>TCP</scan_protocol>
    <user name="grid">
      <group_name>oinstall</group_name>
      <home_dir>/u01/app/grid</home_dir>
    </user>
    <user name="oracle">
      <group_name>oinstall</group_name>
      <home_dir>/u01/app/oracle</home_dir>
    </user>
    <node name="cardiff1">
      <node_number>1</node_number>
    </node>
    <node name="cardiff2">
      <node_number>2</node_number>
    </node>
    <adapter name="bond0">
      <network_type>PUBLIC</network_type>
      <subnet>10.230.123.0</subnet>
      <subnet_mask>255.255.255.0</subnet_mask>
    </adapter>
    <adapter name="bond1">
      <network_type>PRIVATE</network_type>
      <subnet>192.168.2.0</subnet>
      <subnet_mask>255.255.255.0</subnet_mask>
    </adapter>
    <listener name="LISTENER">
      <protocol>TCP</protocol>
      <port>1521</port>
    </listener>
    <disk_group name="CARDIFF_OCRVOTE">
      <redundancy>NORMAL</redundancy>
      <au_size>1</au_size>
      <disk_file name="/dev/mapper/ORA_CARDIFF_OCRVOTE_01p1">
        <size>10GB</size>
      </disk_file>
      <disk_file name="/dev/mapper/ORA_CARDIFF_OCRVOTE_02p1">
        <size>10GB</size>
      </disk_file>
      <disk_file name="/dev/mapper/ORA_CARDIFF_OCRVOTE_03p1">
        <size>10GB</size>
      </disk_file>
    </disk_group>
    <disk_group name="PRODBRIS_DATA">
      <redundancy>EXTERNAL</redundancy>
      <au_size>4</au_size>
      <disk_file name="/dev/mapper/PRODBRIS_DATA_01p1">
        <size>255000</size>
      </disk_file>
    </disk_group>
    <disk_group name="PRODBRIS_FRA">
      <redundancy>EXTERNAL</redundancy>
      <au_size>4</au_size>
      <disk_file name="/dev/mapper/PRODBRIS_FRA_01p1">
        <size>255000</size>
      </disk_file>
    </disk_group>
    <disk_group name="PRODBRIS_REDO">
      <redundancy>EXTERNAL</redundancy>
      <au_size>4</au_size>
      <disk_file name="/dev/mapper/PRODBRIS_REDO_01p1">
        <size>255000</size>
      </disk_file>
    </disk_group>
    <home name="ORACLE_11204_db_1">
      <user_name>oracle</user_name>
      <path>/u01/app/oracle/product/11.2.0.4/db_1</path>
    </home>
  </cluster>
  <group name="PROD">
    <standby_type>PHYSICAL</standby_type>
    <dg_configuration_name>DGPROD</dg_configuration_name>
    <dg_net_timeout>10</dg_net_timeout>
    <member name="PRODBRIS">
      <cluster_name>bristol</cluster_name>
      <standby_name>PRODCARD</standby_name>
      <base_dir>/u01/app/oracle</base_dir>
      <audit_dir>/u01/app/oracle/admin/PRODBRIS/adump</audit_dir>
      <temp_dir>/tmp</temp_dir>
      <home_name>ORACLE_11204_db_1</home_name>
      <data_disk_group>PRODBRIS_DATA</data_disk_group>
      <fra_disk_group>PRODBRIS_FRA</fra_disk_group>
      <redo_disk_groups>PRODBRIS_REDO</redo_disk_groups>
      <redo_threads>3</redo_threads>
      <redo_groups_per_thread>3</redo_groups_per_thread>
      <redo_log_size>512M</redo_log_size>
      <instance name="PRODBRIS1">
        <instance_number>1</instance_number>
        <node>bristol1</node>
        <sid>PROD1</sid>
        <undo_tablespace_name>UNDOTBS1</undo_tablespace_name>
      </instance>
      <instance name="PRODBRIS2">
        <instance_number>2</instance_number>
        <node>bristol2</node>
        <sid>PROD2</sid>
        <undo_tablespace_name>UNDOTBS2</undo_tablespace_name>
      </instance>
      <parameter name="compatible">
        <value>'11.2.0.4.0'</value>
      </parameter>
      <parameter name="standby_file_management">
        <value>'AUTO'</value>
      </parameter>
    </member>
    <member name="PRODCARD">
      <cluster_name>cardiff</cluster_name>
      <standby_name>PRODBRIS</standby_name>
      <base_dir>/u01/app/oracle</base_dir>
      <audit_dir>/u01/app/oracle/admin/PRODCARD/adump</audit_dir>
      <temp_dir>/tmp</temp_dir>
      <home_name>ORACLE_11204_db_1</home_name>
      <data_disk_group>PRODCARD_DATA</data_disk_group>
      <fra_disk_group>PRODCARD_FRA</fra_disk_group>
      <redo_disk_groups>PRODCARD_REDO</redo_disk_groups>
      <redo_threads>3</redo_threads>
      <redo_groups_per_thread>3</redo_groups_per_thread>
      <redo_log_size>512M</redo_log_size>
      <instance name="PRODCARD1">
        <instance_number>1</instance_number>
        <node>cardiff1</node>
        <sid>PROD1</sid>
        <undo_tablespace_name>UNDOTBS1</undo_tablespace_name>
      </instance>
      <instance name="PRODCARD2">
        <instance_number>2</instance_number>
        <node>cardiff2</node>
        <sid>PROD2</sid>
        <undo_tablespace_name>UNDOTBS2</undo_tablespace_name>
      </instance>
      <parameter name="compatible">
        <value>'11.2.0.4.0'</value>
      </parameter>
      <parameter name="standby_file_management">
        <value>'AUTO'</value>
      </parameter>
    </member>
  </group>
</configuration>

MAAGEN Objects

The MAAGEN Perl script (maagen.pl) converts the XML document into a set of objects. These objects are used to generated the files and scripts for the MAA configuration.

In the following documentation:

Each Perl object has a name which is equivalent to the name attribute of the XML parent element

Configuration

There is one Configuration object.

The Configuration object does not have a parent.

The Configuration object includes following attributes:

Tag Description
operating_system Operating systen - Can be Linux, Solaris, AIX, HPUX
shell Command shell. Used as the interpreter directive for generated shell scripts. No restriction on values but will typically be /bin/bash for Linux, and /bin/ksh for AIX
scripts_dir Scripts directory. Directory in which scripts will be stored on the target nodes. Required by some scripts to locate init.ora files during standby creation and/or recreation.
orainst_location Location of /etc/oraInst.loc file which contains the location of the inventory. Usually /etc/oraInst.loc on Linux and AIX; /var/opt/oracle/oraInst.loc on Solaris.
inventory_location Location of the Oracle inventory on each node.
dba_group Name of the DBA group. Usually dba or oinstall
temp_dir Temporary directory. Used for some temporary files during standby creation / recreation. Defaults to /tmp
domain_name DNS Domain name. Optional. If specified will be appended to all node names, node VIP names and scan names
tns_domain_name TNS Domain name. Optional. If specified will be appended to all net service names in TNSNAMES.ORA

The Configuration object includes the following subobjects:

Cluster

There are usually two Cluster objects in each configuration.

The Cluster object is a child of the Configuration object.

The Cluster object has the following attributes:

Tag Description
grid_user Grid user - operating system user owning Grid Infrastructure home
location Location - site where cluster is located
base_dir Base directory for grid user
home_name Oracle home name for Grid Infrastructure home
home_path Operating system path for Grid Infrastructure home
disk_group_name Grid Infrastructure disk group. Usually separated from database disk groups. Includes OCR / Voting Disk / ASM SPFILE
default_listener_name Name of default listener. Default value is LISTENER
scan_name SCAN name. Name added to DNS for SCAN addresses
scan_addresses Comma-separated list of SCAN addresses
scan_port Port number for SCAN listeners. Defaults to 1521
scan_protocol Protocol for SCAN listeners. Defaults to TCP

The Cluster object includes the following subobjects:

User

There are usually one or two User objects in each cluster. There will always be a User object for owner of the RDBMS home (oracle). There may also be a User object for owner of the Grid Infrastructure home (grid). Alternatively both the Grid Infrastructure home and the RDBMS home may be owned by the same user (usually oracle).

Note that it is possible for each RDBMS home to be owned by a different user (e.g. oracle1, oracle2 etc). This may be appropriate if different DBA teams administer each RDBMS home.

The User object is a child of the Cluster object.

The User object has the following attributes:

Tag Description
group_name Operating system group name
home_dir Home directory for user

The User object does not have any subobjects.

Node

There are usually two or more Node objects in each cluster.

The Node object is a child of the Cluster object.

The Node object has the following attributes:

Tag Description
node_number Node number - usually between 1 and number of nodes

The Node object does not have any subobjects.

Adapter

There are usually two Adapter objects in each cluster, one for the public network and the other for the private network.

The configuration can be extended to include additional Adapter objects, usually where a dedicated network is created for redo transport.

The Adapter object is a child of the Cluster object.

The Adapter object has the following attributes:

Tag Description
network_type Network type - can be PUBLIC or PRIVATE
subnet Subnet number for adapter e.g. 10.223.60.0
subnet_mask Subnet mask for adapter e.g. 255.255.255.0

The Adapter object does not have any subobjects.

Listener

There is usually one Listener object in each cluster. However MAAGEN can be extended to support multiple listeners on each cluster. Multiple listeners are appropriate where redo traffic is separated from public and private network traffic. Some sites also implement multiple listeners to improve monitoriing.

The Listener object is a child of the Cluster object.

The default name of a Listener object is LISTENER.

The Listener object has the following attributes:

Tag Description
protocol Protocol of listener. Defaults to TCP
port Port number of listener. Defaults to 1521

The Listener object does not have any subobjects.

Disk Group

There are usually three or more DiskGroup objects in each cluster.

Most clusters include a DiskGroup object for the CRS disk group which contains the OCR, Voting Disk and ASM SPFILE. There is usually at least one disk group for data files (DATA) and at least one disk group for Fast Recovery Area (FRA) files.

Some sites create separate DATA and FRA disk groups for each database; others allocate multiple databases to the same DATA and FRA disk groups. The decision is usually driven by administrative expedience.

The DiskGroup object is a child of the Cluster object.

The DiskGroup object has the following attributes:

Tag Description
redundancy ASM disk group redundancy - can be EXTERNAL, NORMAL or HIGH
au_size Allocation unit size (in megabytes)

The DiskGroup object includes the following subobject:

DiskFile

There is usually one or more DataFile object for each disk group.

DataFile objects are typically used in advanced configurations and for automated builds so may not be required for basic MAA configurations.

The DataFile object is a child of the Disk Group object.

The DataFile object has the following attributes:

Tag Description
size Size of datafile in bytes, megabytes (e.g. 100M), gigabytes (e.g. 20G)

The DataFile object does not have any subobjects.

Group

A Group is an MAAGEN concept which represents a group of databases sharing the same global database name. Within the group one database will usually be the primary and the remainder will be standby databases. An MAAGEN group is equivalent to a Data Guard Broker configuration.

There will be one or more Group objects in each configuration.

The Group object is a child of the Configuration object.

The Group object has the following attributes:

Tag Description
standby_type Type of standby. Usually PHYSICAL for a physical standby
configuration_name Data Guard Broker configuration name
dg_net_timeout Data Guard Broker network timeout. Default is 10 seconds

The Group object includes the following subobjects:

Member

A Member is an MAAGEN concept which represents a database that is a member of a group. Each member has a different database unique name which is effectively the primary key. At any time each member can be a primary database or a standby database. There can be a maximum of one primary database within a group; the remaining databases must be standbys.

There will be usually be two or more Member objects in each group.

The Member object is a child of the Group object.

The Member object has the following attributes:

Tag Description
cluster_name Name of the cluster. This is the name attribute of the cluster object
standby_name Member name of physical standby database. This is the name attribute of the member object
base_dir Base operating system directory of Oracle user
audit_dir Operating system pathname of audit directory. This directory must exist before an instance can be created.
temp_dir Temporary directory. Defaults to /tmp
home_name Oracle home name for RDBMS home
data_disk_group ASM disk group for data files (DATA)
fra_disk_group ASM disk group for Fast Recovery Area files (FRA)
redo_disk_groups Comma-separated list of ASM disk groups for redo files. Can be dedicated redo disk group(s). Alternatively can be DATA, FRA or both
redo_threads Number of redo threads. Usually equal to number of instances for symmetric configurations. For asymmetric configurations equal to highest number of instances on any member database. Used when creating standby redo logs.
redo_groups_per_thread Number of redo groups per thread. Usually 2 or more. Should be the same for all member databases. Used when creating standby redo logs.
redo_log_size Size of redo logs e.g. 512M. Used when creating standby redo logs.

The Member object includes the following subobjects:

Instance

There is one Instance object for each instance in each member database.

The Instance object is a child of the Member object.

The Instance object has the following attributes:

Tag Description
instance_number Instance number betwen 1 and number of instances in the database
node Name of node on which instance is configured
sid SID of instance. SID must be unique within the member, but does not need to be unique within the group
undo_tablespace_name Name of undo tablespace for instance

The Instance object does not have any subobjects.

Parameter

The Parameter object allows initialization parameters to be specified for any member

The Parameter object is a child of the Member object.

The Parameter object has the following attributes:

Tag Description
value The value of the parameter. Strings should be enclosed by single quotes

The Parameter object does not have any subobjects.