REPLICATE NODE (Replicate data in file spaces that belong to a client node)

Use this command to replicate data in file spaces that belong to one or more client nodes or defined groups of client nodes.

When you issue this command, a process is started in which data that belongs to the specified client nodes is replicated according to replication rules. Files that are no longer stored on the source replication server, but that exist on the target replication server, are deleted during this process.

Tip: Avoid conflicts in managing administrative IDs and client option sets by identifying the IDs and option sets that are replicated to the target server and the IDs and option sets that are managed in an enterprise configuration. You cannot define an administrative user ID for a registered node if an administrative ID exists for the same node.

If a node replication process is already running for a client node that is specified by this command, the node is skipped, and replication begins for other nodes that are enabled for replication.

After the node replication process is completed, a recovery process can be started on the target replication server. Files are recovered only if all the following conditions are met:

Version 7.1.1 or later, is installed on the source and target replication servers.
The REPLRECOVERDAMAGED system parameter is set to ON. The system parameter can be set by using the SET REPLRECOVERDAMAGED command.
The source server includes at least one file that is marked as damaged in the node that is being replicated.
The node data was replicated before the damage occurred.

The following table describes how settings affect the recovery of damaged, replicated files.

Restriction: You cannot use the REPLRECOVERDAMAGED parameter for directory-container or cloud storage pools.

Table 1. Settings that affect the recovery of damaged files
Setting for the REPLRECOVERDAMAGED system parameter	Value of the RECOVERDAMAGED parameter on the REPLICATE NODE command	Value of the RECOVERDAMAGED parameter on the REGISTER NODE and UPDATE NODE commands	Result
OFF	YES, NO, or not specified	YES or NO	During node replication, standard replication occurs and damaged files are not recovered from the target replication server.
OFF	ONLY	YES or NO	An error message is displayed because files cannot be recovered when the REPLRECOVERDAMAGED system parameter is set to OFF.
ON	YES	YES or NO	During node replication, standard replication occurs and damaged files are recovered from the target replication server.
ON	NO	YES or NO	During node replication, standard replication occurs and damaged files are not recovered from the target replication server.
ON	ONLY	YES or NO	Damaged files are recovered from the target replication server, but standard node replication does not occur.
ON	Not specified	YES	During node replication, standard replication occurs and damaged files are recovered from the target replication server.
ON	Not specified	NO	During node replication, standard replication occurs and damaged files are not recovered from the target replication server.

Tip: When the QUERY PROCESS command is issued during node replication, the output can show unexpected results for the number of completed replications. The reason is that, for node replication purposes, each file space is considered to contain three logical file spaces:

One for backup objects
One for archive objects
One for space-managed objects

By default, the QUERY PROCESS command generates results for each logical file space. Other factors also affect the output of the QUERY PROCESS command:

If a file space has a replication rule that is set to NONE, the file space is not included in the count of file spaces that are being processed.
If you specify data types in the REPLICATE NODE command, only those data types are included in the count of file spaces that are being processed, minus any file spaces that are excluded.

Issue this command on the server that acts as a source for replicated data.

Privilege class

To issue this command, you must have system privilege.

Syntax


                   .-,-----------------------.   
                   V                         |   
>>-REPLicate Node------+-node_name-------+---+------------------>
                       '-node_group_name-'       

   .-*------------------------------.   
>--+--------------------------------+--------------------------->
   |       .-,------------------.   |   
   |  (1)  V                    |   |   
   '-----+-----filespace_name---+-+-'   
         | .-,------------.       |     
         | V        (2)   |       |     
         '-----FSID-------+-------'     

   .-NAMEType--=--SERVER-------.   
>--+---------------------------+-------------------------------->
   '-NAMEType--=--+-SERVER---+-'   
                  +-UNIcode--+     
                  |      (2) |     
                  '-FSID-----'     

   .-CODEType--=--BOTH-----------.   
>--+-----------------------------+------------------------------>
   '-CODEType--=--+-BOTH-------+-'   
                  +-UNIcode----+     
                  '-NONUNIcode-'     

   .-DATAtype--=--ALl------------------.   
>--+-----------------------------------+------------------------>
   |              .-,----------------. |   
   |              V                  | |   
   '-DATAtype--=----+-ALl----------+-+-'   
                    +-BACKUP-------+       
                    +-BACKUPActive-+       
                    +-ARCHive------+       
                    '-SPACEManaged-'       

   .-PRIORITY--=--ALL--------.   
>--+-------------------------+---------------------------------->
   '-PRIORITY--=--+-ALL----+-'   
                  +-HIGH---+     
                  '-NORMAL-'     

   .-MAXSESSions--=--10------------------.   
>--+-------------------------------------+---------------------->
   '-MAXSESSions--=----number_sessions---'   

   .-Preview--=--No---------------------------------.   
>--+------------------------------------------------+----------->
   '-Preview--=--+-No-----------------------------+-'   
                 |      .-LISTfiles--=--No------. |     
                 '-Yes--+-----------------------+-'     
                        '-LISTfiles--=--+-No--+-'       
                                        '-Yes-'         

   .-Wait--=--No------.                                    
>--+------------------+--+-----------------------------+-------->
   '-Wait--=--+-No--+-'  '-RECOVERDamaged--=--+-Yes--+-'   
              '-Yes-'                         +-No---+     
                                              '-Only-'     

   .-FORCEREConcile--=--No------.   
>--+----------------------------+------------------------------->
   '-FORCEREConcile--=--+-No--+-'   
                        '-Yes-'     

   .-TRANSFERMethod--=--Tcpip--------.   
>--+---------------------------------+-------------------------><
   '-TRANSFERMethod--=--+-Tcpip----+-'   
                        |      (3) |     
                        '-Fasp-----'

Notes:

Do not mix file space identifiers (FSIDs) and file space names in the same command.
Do not specify FSID if you use wildcard characters for the client node name.
The TRANSFERMETHOD parameter is available only on Linux x86_64 operating systems.

Parameters

node_name or node_group_name (Required)

Specifies the name of the client node or defined group of client nodes whose data is to be replicated. You can also specify a combination of client node names and client-node group names. To specify multiple client node names or client-node group names, separate the names with commas with no intervening spaces. You can use wildcard characters with client node names but not with client-node group names. The replication rules for all file spaces in the specified client nodes are checked.

filespace_name or FSID

Specifies the name of the file space or the file space identifier (FSID) to be replicated. A name or FSID is optional. If you do not specify a name or an FSID, all the data in all the file spaces for the specified client nodes is eligible for replication.

filespace_name: Specifies the name of the file space that has data to be replicated. File space names are case-sensitive. To determine the correct capitalization for the file space, issue the QUERY FILESPACE command. Separate multiple names with commas with no intervening spaces. When you specify a name, you can use wildcard characters.
A server that has clients with file spaces that are enabled for Unicode might have to convert the file space name. For example, the server might have to convert a name from the server code page to Unicode. For details, see the NAMETYPE parameter. If you do not specify a file space name, or if you specify a single wildcard character for the name, you can use the CODETYPE parameter to limit the operation to Unicode file spaces or to non-Unicode file spaces.
FSID: Specifies the file space identifier for the file space to be replicated. The server uses FSIDs to find the file spaces to replicate. To determine the FSID for a file space, issue the QUERY FILESPACE command. Separate multiple FSIDs with commas with no intervening spaces. If you specify an FSID, the value of the NAMETYPE parameter must be FSID.

NAMEType

Specifies how you want the server to interpret the file space names that you enter. You can use this parameter for IBM Spectrum Protect™ clients that are enabled for Unicode and that have Windows, Macintosh OS X, or NetWare operating systems.

Use this parameter only when you enter a partly qualified or fully qualified file space name. The default value is SERVER. You can specify one of the following values:

SERVER: The server uses the server code page to interpret file space names.
UNIcode: The server converts file space names from the server code page to the UTF-8 code page. The success of the conversion depends on the characters in the name and the server code page. Conversion can fail if the string includes characters that are not available in the server code page or if the server cannot access system conversion routines.
FSID: The server interprets file space names by using their file space identifiers.

CODEType

Specifies the type of file spaces to be included in node replication processing. Use this parameter only when you enter a single wildcard character for the file space name. The default value is BOTH, which specifies that file spaces are included regardless of code page type. You can specify one of the following values:

UNIcode: Specifies file spaces that are only in Unicode.
NONUNIcode: Specifies file spaces that are not in Unicode.
BOTH: Specifies all file spaces regardless of code page type.

DATAtype

Specifies the type of data to be replicated. Data is replicated according to the replication rule that applies to the data type. This parameter is optional. You can specify one or more data types. If you do not specify a data type, all backup, archive, and space-managed data is replicated. Separate multiple data types with commas with no intervening spaces. You cannot use wildcard characters. You can specify one of the following values:

ALl

Replicates all backup, archive, and space-managed data in a file space according to the rule that is assigned to the data type. For example, suppose that NODE1 has a single file space. The following replication rules apply:

The file space rules for backup and archive data in the file space are set to ALL_DATA.
The file space rule for space-managed data is set to DEFAULT.
The client node rule for space-managed data is set to NONE.

If you issue REPLICATE NODE NODE1 DATATYPE=ALL, only backup data and archive data are replicated.

BACKUP

Replicates active and inactive backup data in a file space if the controlling replication rule is ALL_DATA, ACTIVE_DATA, ALL_DATA_HIGH_PRIORITY, or ACTIVE_DATA_HIGH_PRIORITY.

BACKUPActive

Replicates only active backup data in a file space if the controlling replication rule is ACTIVE_DATA or ACTIVE_DATA_HIGH_PRIORITY.

ARCHive

Replicates archive data only in a file space if the controlling replication rule is ALL_DATA or ALL_DATA_HIGH_PRIORITY.

SPACEManaged

Replicates only space-managed data in a file space if the controlling replication rule is ALL_DATA or ALL_DATA_HIGH_PRIORITY.

PRIority

Specifies the data to replicate based on the priority of the replication rule. You can specify one of the following values:

All: Replicates all data in a file space if the controlling replication rule is ALL_DATA, ACTIVE_DATA, ALL_DATA_HIGH_PRIORITY, or ACTIVE_DATA_HIGH_PRIORITY.
High: Replicates only data in a file space that has a controlling replication rule of ALL_DATA_HIGH_PRIORITY or ACTIVE_DATA_HIGH_PRIORITY.
Normal: Replicates only data in a file space that has a controlling replication rule of ALL_DATA or ACTIVE_DATA.

MAXSESSions

Specifies the maximum allowable number of data sessions to use for sending data to a target replication server. This parameter is optional. The value can be 1 - 99. The default value is 10.

Increasing the number of sessions can improve node replication throughput.

When you set this value, consider the number of logical and physical drives that can be dedicated to the replication process. To access a sequential-access volume, IBM Spectrum Protect uses a mount point and, if the device type is not FILE, a physical drive. The number of available mount points and drives depends on the following factors:

Other IBM Spectrum Protect and system activity
The mount limits of the device classes for the sequential access storage pools that are involved

Ensure that sufficient mount points and drives are available to allow node replication processes to complete. Each replication session might need a mount point on the source and target replication servers for storage pool volumes. If the device type is not FILE, each session might also need a drive on both the source and target replication servers.

When you set a value for MAXSESSIONS, also consider the available bandwidth and the processor capacity of the source and target replication servers.

Tip:

The value that is specified by the MAXSESSIONS parameter applies only to data sessions. Data sessions are sessions during which data is sent to a target replication server. However, if you issue a QUERY SESSION command, the total number of sessions might exceed the number of data sessions. The difference is because of short control sessions that are used for querying and setting up replication operations.
The value of the MAXSESSIONS parameter represents the maximum allowable number of sessions. The number of sessions that are used for replication depends on the amount of data to be replicated. If you are replicating only a small amount of data, you do not achieve any benefit by increasing the number of sessions. The total number of sessions might be less than the value that is specified by the MAXSESSIONS parameter.

Preview

Specifies whether to preview data. This parameter is optional. The default value is NO. You can specify one of the following values:

No

Specifies that the data is replicated to the target server but that the data is not previewed.

Yes

Specifies that data is previewed but not replicated. If you specify PREVIEW=YES, only volumes that must be physically mounted, such as tape volumes, are displayed. Volumes that are assigned to storage pools that have a device class of FILE are not displayed.

The following information is displayed in the output:

The names of client nodes whose data would be replicated.
The number of files that would be replicated or deleted.
The estimated amount of time it would take to complete the node replication process.
A list of volumes that would be mounted.
A summary of information about replicated, damaged data. The summary lists the number of nodes, file spaces, files, and bytes that can be recovered during a replication recovery process. The summary is displayed only if RECOVERDAMAGED=YES or RECOVERDAMAGED=ONLY is specified.

If the client node data that is specified by the REPLICATE NODE command was never replicated and you specify PREVIEW=YES, the node and its file spaces are automatically defined on the target replication server.

LISTfiles

Specifies whether to list the names of files that would be replicated. This parameter is optional. The default is NO. Specifying this parameter signifies that the WAIT parameter is set to YES and that you cannot issue the WAIT parameter from the server console.

You can specify one of the following values:

No: Specifies that the names of files that would be replicated are not displayed.
Yes: Specifies that the names of files that would be replicated are displayed.

Wait

Specifies whether to wait for the server to complete processing this command in the foreground. This parameter is optional. The default value is NO. You can specify one of the following values:

No: Specifies that the command processes in the background. To monitor the background processing of the REPLICATE NODE command, issue the QUERY PROCESS command.
Yes: Specifies that the command processes in the foreground. Messages are not displayed until the command completes processing. You cannot specify WAIT=YES from the server console.

RECOVERDamaged

Specifies whether a recovery process is started on a target replication server after the node replication process is completed. This parameter is optional, and it overrides any value that you specified for the RECOVERDamaged parameter when you defined or updated a node. You can specify one of the following values:

Yes: Specifies that a replication process is started to recover damaged files, but only if the setting for the REPLRECOVERDAMAGED system parameter is ON. If the setting is OFF, damaged files are not recovered.
No: Specifies that damaged files are not recovered.
Only: Specifies that a replication process is started for the sole purpose of recovering damaged files, but only if the setting for the REPLRECOVERDAMAGED system parameter is ON. If the setting is OFF, damaged files are not recovered, and you receive a notification that recovery was not started.
Restriction: If you specify an invalid combination of values and settings for file recovery, replication is stopped, and an error message is displayed.

FORCEREConcile

Specifies whether to compare all files on the source replication server with files on the target replication server and to synchronize the differences between them. Before V7.1.1, this behavior was the default for replication processing. When IBM® Tivoli® Storage Manager V7.1.1 or later is installed on the source and target replication servers, a reconcile is automatically completed during initial replication. After initial replication, you might use this parameter for the following reasons:

To synchronize files on the source and target replication servers if they are different.
To replicate inactive files that were skipped after you change your replication rules from ACTIVE_DATA to ALL_DATA.
To delete inactive files from the target replication server when you change your replication rules from ALL_DATA to ACTIVE_DATA.
To ensure that you replicate only active data when you are using the ACTIVE_DATA replication rule so that the target replication server has active files only.
To resynchronize the files so that the target replication server has the same files as the source replication server if you have previously or are currently using the policies on the target replication server to manage replicated files.
To resynchronize the files on the source and target replication servers if the database is regressed to an earlier point-in-time by using a method other than the DSMSERV RESTORE DB command.
To rebind files to the new management class on the target replication server if this management class did not exist when the files were replicated. You must be using the policies that are defined on the target replication server to manage replicated files.

Remember: When the ACTIVE_DATA rule is assigned, a reconcile is completed only for active files on the source replication server.

This parameter is optional. You can specify one of the following values:

No: Specifies that replication processing does not force a reconcile to compare all files on the source replication server with files on the target replication server. Instead, replication processing tracks file changes on the source replication server since the last replication and synchronizes these changes on the target replication server. NO is the default value.
Yes: Specifies that replication processing forces a reconcile to compare all files on the source replication server with files on the target replication server and synchronizes the files on the target replication server with the source replication server.

TRANSFERMethod

Specifies the method that is used for server-to-server data transfer. This parameter is optional. You can specify one of the following values:

Tcpip

Specifies that TCP/IP is used to transfer data. This value is the default.

Fasp

Specifies that Aspera® Fast Adaptive Secure Protocol (FASP) technology is used to transfer data. Aspera FASP technology can help you optimize data transfer in a wide area network (WAN). If you specify TRANSFERMETHOD=FASP, you override any TRANSFERMETHOD parameters that you specified on the DEFINE SERVER or UPDATE SERVER commands.

Restrictions:

Only data that is stored in a directory-container storage pool can be transferred by using Aspera FASP technology. Data that is not stored in a directory-container storage pool is transferred by using TCP/IP.
Before you enable Aspera FASP technology, determine whether the technology is appropriate for your system environment and install the appropriate licenses. For instructions, see Determining whether Aspera FASP technology can optimize data transfer in your system environment. If the licenses are missing or expired, node replication fails.
If WAN performance meets your business needs, do not enable Aspera FASP technology.

Example: Replicate data by data type and priority

Replicate high-priority active backup data and high-priority archive data that belongs to all the client nodes in group PAYROLL.

replicate node payroll datatype=backupactive,archive priority=high

Example: Replicate all the data that belongs to a node according to the assigned replication rules

NODE1 has a single file space. The following replication rules apply:

File space rules:
- Backup data: ACTIVE_DATA
- Archive data: DEFAULT
- Space-managed data: DEFAULT
Client node rules:
- Backup data: DEFAULT
- Archive data: ALL_DATA_HIGH_PRIORITY
- Space-managed data: DEFAULT
Server rules:
- Backup data: ALL_DATA
- Archive data: ALL_DATA
- Space-managed data: NONE

replicate node node1 priority=all

Active backup data in the file space is replicated with normal priority. Archive data is replicated with high priority. Space-managed data is not replicated.

Example: Recover damaged files without starting the full replication process

Without starting the full replication process, recover any damaged files in the client nodes of the PAYROLL group. Ensure that the setting for the REPLRECOVERDAMAGED system parameter is ON. Then, issue the following command:

replicate node payroll recoverdamaged=only

Related commands

Table 2. Commands related to REPLICATE NODE
Command	Description
CANCEL PROCESS	Cancels a background server process.
CANCEL REPLICATION	Cancels node replication processes.
QUERY FILESPACE	Displays information about data in file spaces that belong to a client.
QUERY NODE	Displays partial or complete information about one or more clients.
QUERY REPLICATION	Displays information about node replication processes.
QUERY REPLNODE	Displays information about the replication status of a client node.
QUERY REPLRULE	Displays information about node replication rules.
QUERY SERVER	Displays information about servers.
QUERY STATUS	Displays the settings of server parameters, such as those selected by the SET commands.
REGISTER NODE	Defines a client node to the server and sets options for that user.
REMOVE REPLNODE	Removes a node from replication.
PROTECT STGPOOL	Protects a directory-container storage pool.
SET REPLRECOVERDAMAGED	Specifies whether node replication is enabled to recover damaged files from a target replication server.
UPDATE FILESPACE	Changes file-space node-replication rules.
UPDATE NODE	Changes the attributes that are associated with a client node.
UPDATE REPLRULE	Enables or disables replication rules.
VALIDATE REPLICATION	Verifies replication for file spaces and data types.