mkrpdomain Command

Purpose

Creates a 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] [ -S mode ] [ -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] [ -S mode ] [ -k cssk_type [-r refresh_interval] ] [ –6 ] [ -C cluster_type -R repository_disk [ -D shared_disk1[,shared_disk2…] ] ] [-h] [-TV] peer_domain

To create a peer domain definition with the policy information:

mkrpdomain [ -p Policy ] ApplDomain nameA [ @host_nameA ] [ nameB [ @host_nameB ] ... ]

Description

The mkrpdomain command creates a peer domain definition with the name specified by the peer_domain parameter. The nodes that are specified by node_name are defined to the new peer domain. A peer domain can be used to provide high-availability services when you configure 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 are successfully defined to the peer domain.

The mkrpdomain command fails 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 by 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 the peer domain group is started. 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 affects 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 2 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 2 minutes of each other, messages that are passed between a sending node and a receiving node with a time difference that is longer than 2 minutes are discarded.

When message authentication is enabled by using the -k flag, a key refresh interval can be specified by 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 are visible as resources in IBM®.NetworkInterface class. These IPv6 addresses are not used for heartbeating or internal peer domain operations. If the -6 flag is not specified, no IPv6 addresses are 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 by 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

Item	Description
-6	Specifies that the IPv6Support persistent class attribute of the IBM.NetworkInterface class has 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 are 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 refers to the interface (through the Name attribute), one with the IP address 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 addresses 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	Continues to run the mkrpdomain command on the remaining nodes. By default, if the mkrpdomain command fails on any node, it fails on all nodes. The -c flag overrides this behavior, so that the mkrpdomain command runs on the other nodes, even if it fails on one node.
-C cluster_type	Specifies the cluster type. Valid values are as follows: 0 Creates a peer domain. This value 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 by using the -R flag. Also, you can optionally specify one or more shared disks by using the -D 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.
-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. Note: The command requires that the following conditions be met to display a valid output: Specify 1 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. Specify the actual host name of the node by using @ sign without any space between node name and its host name. An example of the syntax follows: `[nodeA@hostA]` By default, all of the nodes that are 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 by 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 be specified for quorum nodes only. ! 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 it results 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.
-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 - 65535 can be assigned. The command fails if the specified port is unavailable. The default is 12348.
-h	Writes the command's usage statement to standard output.
-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 and message digest, the stronger the encryption algorithm. The stronger the algorithm, the slower the performance. The valid key types are as follows: CSSKTYPE_None Indicates that message authentication is disabled. This is the default value. Note: If the -S flag is specified with mode value `nist_sp800_131a`, the default CSSK type is `CSSKTYPE_AES256_SHA256`. 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 more data protection than CSSKTYPE_3DES_MD5, but with slower performance and more data overhead. The following CSSK types are compliant with the National Institute of Standards and Technology (NIST) Special Publications SP800-131a. You must be running RSCT 3.2.0.0, or later, to configure these key types. CSSKTYPE_AES128_SHA256 Indicates that an Advanced Encryption Standard (AES) 128-bit key that has an SHA-1 (Secure Hash Algorithm) 256-bit digest is used to generate a 16-byte signature. CSSKTYPE_AES128_SHA512 Indicates that an AES 128-bit key that has an SHA-1 512-bit digest is used to generate a 16-byte signature. CSSKTYPE_AES256_SHA256 Indicates that an AES 256-bit key that has an SHA-2 256-bit digest is used to generate a 32-byte signature. CSSKTYPE_AES256_SHA512 Indicates that an AES 256-bit key that has an SHA-2 512-bit digest is used to generate a 32-byte signature. Notes: You must be running RSCT 2.4.7.1 or later to use this flag. If the -S flag is specified with the mode value `nist_sp800_131a`, the CSSK type must be either `CSSKType_None` or a key type that is compliant with the mode. If the created domain is compliant with the mode value `nist_sp800_131a`, and the -k flag is not specified, the domain is configured to use CSSK type `CSSK_AES256_SHA256`.
-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.
-p Policy	Reads the policy from the user input when the mkrpdomain command creates the domain. You can use this command to specify the policy information when you create the domain. The valid values for the Policy attribute are 0 and 1. If you do not specify the -p flag for the mkrpdomain command, the default value 0 is set in non-CAA clusters and 1 is set in CAA clusters. If the value of policy is set as 1, the Name field of the IBM.PeerNode class is maintained in sync with the host name of the IBM.PeerNode class. If the value of policy is set as 0, the Name field is not maintained in sync with the host name, irrespective of the domain. However, the -p 0 flag cannot be specified for CAA domain as a limitation. The policy information can be changed by using a chrsrc class action after the cluster is created.
-Q quorum_type \| quorum_type_name	Specifies the quorum rules that are used for startup, operational, and configuration quorum. Startup quorum defines how many nodes are contacted to obtain configuration information before the peer domain is started. Operational quorum defines how many nodes must be online to start and stop resources and how tie breaking is used. Configuration quorum defines how many nodes must be online to change 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 as follows: 0 \| normal Specifies normal quorum rules. This value is the default. For startup quorum, at least half of the nodes are 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 startup quorum, even if no other nodes can be contacted, the node still comes 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.
-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 1 day. The minimum refresh interval is 30 seconds. The maximum refresh interval is 30 days. The -r flag can be specified when the -k flag is used. You must be running RSCT 2.4.7.1 or later to use this 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.
-S `mode`	Enforces a security compliance mode for RSCT in the peer domain. The `mode` parameter can have the following values: none The domain does not enforce a security compliance mode. nist_sp800_131a RSCT is configured to be compliant with the National Institute of Standards and Technology (NIST) Special Publications SP800-131a. This mode value requires that all nodes that are specified in the mkrpdomain command must already be migrated to `nist_sp800_131a` mode or the nodes must be configured to use public or private keys that are compliant with this specification. Note: You must be running RSCT 3.2.0.0, or later, to use the -S flag.
-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 - 65535 can be assigned. The command fails if the specified port is unavailable. The default is 12347.
-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 use these ASCII characters only 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 host name. The node name must resolve to an IP address.

Security

The user of the mkrpdomain command requires write permission to the IBM.PeerDomain resource class on each node that is to be defined to the peer domain. This permission 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 runs 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 has meaning only 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) file set 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 that is called ApplDomain that consists of a node that is called nodeA, run this command on nodeA:
```
mkrpdomain ApplDomain nodeA
```
To define a peer domain that is called ApplDomain that consists of three nodes that are called nodeA, nodeB, and nodeC, run this command on nodeA, nodeB, or nodeC:
```
mkrpdomain ApplDomain nodeA nodeB nodeC
```
To define a peer domain that is called ApplDomain that consists of 2 nodes that are 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 that is called ApplDomain that consists of 2 nodes that are called nodeA and nodeB by 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 that is called ApplDomain that consists of the nodes nodeA, nodeB, nodeC, nodeD, and nodeE, by using the /pd/pdnodes.config file, run the following command on any of the nodes:
```
mkrpdomain -f /pd/pdnodes.config ApplDomain
```
where the contents of /pd/pdnodes.config are as follows:
```
      # 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 that is called ApplDomain that consists of nodeA, nodeB, nodeC, nodeD, and nodeE, by 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 the following command on any of the nodes:
```
mkrpdomain -f /pd/pdnodes.config ApplDomain
```
where the contents of /pd/pdnodes.config are as follows:
```
      # 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
```
To define a peer domain that is called ApplDomain, which consists of 2 nodes that are called nodeA and nodeB, with the policy NamePolicy 1, run the following command:
```
mkrpdomain -p 1 ApplDomain nodeA nodeB
```
NamePolicy 1 means that any change in host name also updates the node name. In this case, the host name is not specified in the beginning. Hence, the node names (nodeA and nodeB) are set as host names for the respective nodes.
To define a peer domain that is called ApplDomain, which consists of 2 nodes that are called nodeA and nodeB, whose host names are hostA and hostB, run the following command:
```
mkrpdomain ApplDomain nodeA@hostA nodeB@hostB
```
These host names are the actual host names that are used for communication.

Location

/opt/rsct/bin/mkrpdomain

Files

The /etc/services file is modified.