mkrpdomain Command

Purpose

Creates a new peer domain definition.

Syntax

To create a peer domain definition...

...by specifying node names on the command line:
mkrpdomain [-t TS_port] [-g GS_port] [ -Q quorum_type | quorum_type_name ] [-c] [-m fanout] [ -k cssk_type [-r refresh_interval] ] [ –6 ] [ -C cluster_type -R repository_disk [ -D shared_disk1[,shared_disk2…] ] ] [-h] [-TV] peer_domain node_name1 [node_name2 ... ]
...using a list of node names in an input file:
mkrpdomain -f │ -F { file_name │ "–" } [-t TS_port] [-g GS_port] [-Q {quorum_type | quorum_type_name}] [-c] [-m fanout] [ -k cssk_type [-r refresh_interval] ] [ –6 ] [ -C cluster_type -R repository_disk [ -D shared_disk1[,shared_disk2…] ] ] [-h] [-TV] peer_domain

Description

The mkrpdomain command creates a new peer domain definition with the name specified by the peer_domain parameter. The nodes specified by node_name are defined to the new peer domain. A peer domain can be used to provide high-availability services when configuring application and system resources.

The preprpnode command must have been run on each of the nodes to be defined to the peer domain. The preprpnode command prepares the security environment for the peer domain operations. See the preprpnode command for more information about peer domain definition requirements. Only those nodes that have the appropriate security setup will be successfully defined to the peer domain.

The mkrpdomain command will fail if one or more of these situations occurs:

The name of the peer domain is already in use.
One or more nodes cannot be successfully defined to the peer domain.
The UDP port numbers for group services and topology services are not available on all of the nodes to be defined to the peer domain.

Use the -c flag to enable mkrpdomain to continue when there is an error on one of the nodes. The peer domain quorum rules can be modified using the -Q flag. The quorum rules determine under what conditions operational changes, such as starting or stopping resources, and configuration changes, such as adding or removing a node, can be made. Start-up quorum defines how many nodes are contacted to get configuration information to start the peer domain. In a typical environment, two quorum rule types are used: normal and quick. For the quick quorum type, only one node is contacted before starting the peer domain. Operational and configuration quorum rules are the same. To see what quorum rule types are available on a node, run:

lsrsrc -c IBM.PeerDomain AvailableQuorumTypes

You can use the -k flag to set the cluster shared secret key (CSSK). The CSSK is used for message authentication in the peer domain. By default, the CSSK is disabled (that is, set to CSSKTYPE_None). To enable message authentication, use a CSSK value such as CSSKTYPE_DES_MD5 with the -k flag. Enabling message authentication will affect performance. The complexity of the encryption algorithm determines the effect.

Message authentication also requires that the time-of-day clocks (TODs) of the nodes in the peer domain are synchronized — according to the system time — to within two minutes of each other. When the nodes' TODs are synchronized across the peer domain, this function helps to defend against message replay attacks. If the nodes' TODs are not synchronized to within two minutes of each other, messages passed between a sending node and a receiving node with a time difference that is longer than two minutes will be discarded.

When message authentication is enabled using the -k flag, a key refresh interval can be specified using the -r flag. By default, the key is refreshed daily.

To change the CSSK type for a peer domain, use the chrsrc command. For example:

chrsrc -c IBM.RSCTParameters CSSKType=cssk_type

To list the CSSK type that is used for an online peer domain, use the lsrsrc command. For example:

lsrsrc -c IBM.RSCTParameters CSSKType

To cause the CSSK to be refreshed, use the runact command. For example:

runact -c IBM.PeerDomain UpdateKey

For information about setting up and managing CSSK settings, see the Administering RSCT guide.

Use the -6 flag to establish a peer domain in which the IPv6 addresses that are configured on the nodes' network interfaces will be visible as resources in IBM®.NetworkInterface class. These IPv6 addresses will not be used for heartbeating or internal peer domain operations. If the -6 flag is not specified, no IPv6 addresses will be visible as resources in IBM.NetworkInterface.

The mkrpdomain command does not bring the peer domain online automatically. To bring the peer domain online, run the startrpdomain command. You can add nodes to the peer domain using the addrpnode command. To remove nodes from the peer domain, use the rmrpnode command.

A node can be defined in more than one peer domain but it can be online in only one peer domain at a time.

Flags

-t TS_port

Specifies the topology services port number. This UDP port is used for daemon-to-daemon communication. Any unused port in the range 1024 to 65535 can be assigned. The command will fail if the specified port is unavailable. The default is 12347.

-g GS_port

Specifies the group services port number. This UDP port is for daemon-to-daemon communication. Any unused port in the range 1024 to 65535 can be assigned. The command will fail if the specified port is unavailable. The default is 12348.

-c

Continues to run the mkrpdomain command on the remaining nodes.

By default, if the mkrpdomain command fails on any node, it will fail on all nodes. The -c flag overrides this behavior, so that the mkrpdomain command will run on the other nodes, even if it fails on one node.

-Q quorum_type | quorum_type_name

Specifies the quorum rules that are used for start-up, operational, and configuration quorum. Start-up quorum defines how many nodes are contacted to obtain configuration information before starting the peer domain. Operational quorum defines how many nodes must be online in order to start and stop resources and how tie breaking is used. Configuration quorum defines how many nodes must be online to make changes to the peer domain (adding or removing a node, for example). To see what quorum rule types are available on a node, run:

lsrsrc -c IBM.PeerDomain AvailableQuorumTypes

The valid values are:

0 | normal: Specifies normal quorum rules. This is the default. For start-up quorum, at least half of the nodes will be contacted for configuration information. For configuration quorum, more than half of the nodes must be online to make configuration changes. For operational quorum, the cluster or subcluster must have a majority of the nodes in the peer domain. If a tie exists between subclusters, the subcluster that holds the tiebreaker has operational quorum.
1 | quick: Specifies quick quorum rules. For start-up quorum, even if no other nodes can be contacted, the node will still come online. For configuration quorum, more than half of the nodes must be online to make configuration changes. For operational quorum, the cluster or subcluster must have a majority of the nodes in the peer domain. If a tie exists between subclusters, the subcluster that holds the tiebreaker has operational quorum.

-m fanout

Specifies the maximum number of threads to use in parallel operations for the specified peer domain. This value is stored as a persistent attribute in the peer domain's IBM.PeerNode class. fanout can be an integer from 16 to 2048. If this flag is not specified, the default value (128) is used.

-f | -F { file_name | "–" }

Specifies that node names are read from a file or from standard input. Use -f node_file or -F node_file to read the node names from a file.

Specify one node name per line. The command ignores any blank characters to the left of the node name.
Use a number sign (#) to indicate that the remainder of the line (or the entire line if the # is in column 1) is a comment.

By default, all of the nodes listed in node_file:

are group services group leader candidates
are used for quorum decisions
have access to the peer domain's tiebreaker mechanism

You can customize node characteristics using an at sign (@) control character followed by one or more of these special characters:

P | p: Specifies that the node is a group services group leader candidate.
Q | q: Specifies that the node is a quorum node.
B | b: Specifies that the node has access to the peer domain's tiebreaker mechanism. B or b can only be specified for quorum nodes.
!: Specifies that the node does not have a certain characteristic. For example, !Q indicates that the node is not a quorum node.

When customizing node characteristics, consider the following (where x is P, Q, or B):

Use only one @ control character per line, followed immediately by one or more special characters, after the node name and before any comments.
Do not specify !QB for a node, as this will result in an error.
If you use a node number, add it after the node name and before any comments. The node number can precede or follow the node characteristic specifications.
If x is specified for one or more nodes and !x is not specified for any nodes, the nodes that do not have an x specified are assumed to have a value of !x.
If !x is specified for one or more nodes and x is not specified for any nodes, the nodes that do not have an !x specified are assumed to have a value of x.
If x and !x are specified for different nodes in the same node file, all of the nodes in the file must have a specification of x or !x.

See the Administering RSCT for more information.

Use -f "-" or -F "-" to read the node names from standard input.

-k cssk_type

Specifies the cluster shared secret key (CSSK) to be used for message authentication in the peer domain. Use the CSSK that best suits your applications in terms of the degree of data protection, overhead, and performance. The longer the key, the stronger the encryption algorithm. The stronger the algorithm, the slower the performance. The valid key types are:

CSSKTYPE_None: Indicates that message authentication is disabled. This is the default.
CSSKTYPE_DES_MD5: Indicates that a Data Encryption Standard (DES) key with the message digest function MD5 is used to generate a 16-byte signature. This CSSK is recommended if a high degree of data protection is not required and if you want good performance with less data overhead.
CSSKTYPE_3DES_MD5: Indicates that a triple DES key with an MD5 digest is used to generate a 16-byte signature. Compared to CSSKTYPE_DES_MD5, this CSSK provides added data protection with slower performance, but with the same data overhead.
CSSKTYPE_AES256_MD5: Indicates that an Advanced Encryption Standard (AES) 256-bit key with an MD5 digest is used to generate a 24-bit signature. This CSSK provides the most data protection, but with slower performance and more data overhead.

You must be running RSCT 2.4.7.1 or later to use this flag.

-r refresh_interval

Specifies the CSSK refresh interval when message authentication is enabled in the peer domain. This is the interval at which the CSSK is refreshed. The format of refresh_interval is: dd:hh:mm:ss, where dd is the number of days between key refreshes, hh is the number of hours, mm is the number of minutes, and ss is the number of seconds. The refresh_interval value can be truncated on the right, so -r 5 means refresh every 5 days and -r 0:12 means refresh every 12 hours.

The default refresh interval is one day. The minimum refresh interval is 30 seconds. The maximum refresh interval is 30 days.

The -r flag can only be specified when the -k flag is used.

You must be running RSCT 2.4.7.1 or later to use this flag.

-6

Specifies that the IPv6Support persistent class attribute of the IBM.NetworkInterface class will have a value of 1 rather than the default (0) in the peer domain that is to be created. For any IP interface on any node in a cluster that has one or more IPv6 addresses configured, only one of these IPv6 addresses will be made visible as a resource in IBM.NetworkInterface. Therefore, if a network interface has IPv4 addresses and IPv6 addresses configured on it, two resources in IBM.NetworkInterface will refer to the interface (through the Name attribute), one with the IPAddress value set to the primary IPv4 address, and one with the selected IPv6 address. If multiple IPv6 addresses are configured on an interface, preference is given to global addresses over link-local addresses for representation as a resource. In addition, IPv6 address are used for heartbeating or internal peer domain operations.

Note: Even if IPv6Support is changed, the current registered applications do not receive the notification for any resource addition or deletion until the domain or the IBM.ConfigRM class is restarted.

-C cluster_type

Specifies the cluster type. Valid values are:

0: Creates a peer domain. This is the default.
1: Creates a peer domain and the underlying Cluster-Aware AIX® (CAA) cluster.

If you specify the -C 1 flag, you must also specify a repository disk using the -R flag. Also, you can optionally specify one or more shared disks using the -D flag.

-R repository_disk

Specifies the repository disk for a CAA cluster. If you specify the -R flag, you must also specify the -C flag.

-D shared_disk1[,shared_disk2…]

Specifies one or more shared disks for a CAA cluster. If you specify the -D flag, you must also specify the -C and -R flags.

-h

Writes the command's usage statement to standard output.

-T

Writes the command's trace messages to standard error. For your software service organization's use only.

-V

Writes the command's verbose messages to standard output.

Parameters

peer_domain: Specifies the name of the new peer domain to be created. You can only use these ASCII characters in the peer domain name: A to Z, a to z, 0 to 9, . (period), and _ (underscore). In addition, the peer domain name cannot be IW.
node_name1 [node_name2 ... ]: Specifies the node (or nodes) to include in this peer domain definition. The node name is the IP address or the long or short version of the DNS hostname. The node name must resolve to an IP address.

Security

The user of the mkrpdomain command needs write permission to the IBM.PeerDomain resource class on each node that is to be defined to the peer domain. This is set up by running the preprpnode command on each node that is to be defined to the domain, specifying the name of the node on which the user will run mkrpdomain.

Exit Status

0: The command ran successfully.
1: An error occurred with RMC.
2: An error occurred with a command-line interface script.
3: An incorrect flag was entered on the command line.
4: An incorrect parameter was entered on the command line.
5: An error occurred that was based on incorrect command-line input.

Environment Variables

CT_CONTACT: Determines the system where the session with the resource monitoring and control (RMC) daemon occurs. When CT_CONTACT is set to a host name or IP address, the command contacts the RMC daemon on the specified host. If CT_CONTACT is not set, the command contacts the RMC daemon on the local system where the command is being run. The target of the RMC daemon session and the management scope determine the resource classes or resources that are processed.
CT_IP_AUTHENT: When the CT_IP_AUTHENT environment variable exists, the RMC daemon uses IP-based network authentication to contact the RMC daemon on the system that is specified by the IP address to which the CT_CONTACT environment variable is set. CT_IP_AUTHENT only has meaning if CT_CONTACT is set to an IP address; it does not rely on the domain name system (DNS) service.

Restrictions

Any node to be defined to the peer domain must be reachable from the node on which this command runs.

Implementation Specifics

This command is part of the Reliable Scalable Cluster Technology (RSCT) fileset for AIX.

Standard Input

When the -f "-" or -F "-" flag is specified, this command reads one or more node names from standard input.

Standard Output

When the -h flag is specified, this command's usage statement is written to standard output. All verbose messages are written to standard output.

Standard Error

All trace messages are written to standard error.

Examples

To define a peer domain called ApplDomain that consists of a node called nodeA, run this command on nodeA:
```
mkrpdomain ApplDomain nodeA
```
To define a peer domain called ApplDomain that consists of three nodes called nodeA, nodeB, and nodeC, run this command on nodeA, nodeB, or nodeC:
```
mkrpdomain ApplDomain nodeA nodeB nodeC
```
To define a peer domain called ApplDomain that consists of two nodes called nodeA and nodeB, with a topology services port number of 1200 and a group services port number of 2400, run this command on nodeA or nodeB:
```
mkrpdomain -t 1200 -g 2400 ApplDomain nodeA nodeB
```
To define a peer domain called ApplDomain that consists of two nodes called nodeA and nodeB using message authentication key algorithm CSSKTYPE_DES_MD5, run this command on nodeA or nodeB:
```
mkrpdomain -k CSSKTYPE_DES_MD5 ApplDomain nodeA nodeB
```

To define a peer domain called ApplDomain that consists of the nodes nodeA, nodeB, nodeC, nodeD, and nodeE, using the /pd/pdnodes.config file, run this command on any of the nodes:

mkrpdomain -f /pd/pdnodes.config ApplDomain

where the contents of /pd/pdnodes.config are:

      # peer domain nodes for mkrpdomain
      nodeA       # dev node
      nodeB       # dev node
      nodeC       # prod node
      nodeD       # test node
      nodeE       # test node

To define a peer domain called ApplDomain that consists of nodeA, nodeB, nodeC, nodeD, and nodeE, using the /pd/pdnodes.config file, which specifies that nodeA has access to the peer domain's tiebreaker mechanism, nodeB and nodeC cannot be used in quorum decisions, and nodeC and nodeD cannot be the group services group leader, run this command on any of the nodes:
```
mkrpdomain -f /pd/pdnodes.config ApplDomain
```
where the contents of /pd/pdnodes.config are:
```
      # peer domain nodes for mkrpdomain
      nodeA    @QB     # dev node
      nodeB    @!Q     # dev node
      nodeC    @!Q!P   # prod node
      nodeD    @!P     # test node
      nodeE    @Q      # test node
```

Location

/usr/sbin/rsct/bin/mkrpdomain

Files

The /etc/services file is modified.