dcp Command

Purpose

Runs commands concurrently on multiple nodes and hardware devices.

Syntax

dcp [-h] [-V] [-q] [-a] [--all-nodes context_list] [-A] [--all-devices context_list] [-n node_list] [-N nodegroups] [-d device_list] [-D devicegroups] [-C context] [-f fanout] [-l user_ID] [-o node_options] [-O device_options] [-p] [-P] [-Q] [-r node_remote_copy] [--device-rcp device_remote_copy] [-R] [-t timeout] [-X env_list] [-T] [-v] source_file... target_path

Description

The dcp command concurrently copies files to or from remote target nodes, hardware devices, or both. Targets can be selected from multiple contexts. A context is a target database that contains definitions of nodes and devices, such as NIM. The dcp command issues a remote copy command for each node or device specified. When files are pulled from a target, they are placed into the target_path with the name of the remote node or device that is appended to the copied source_file name. The /usr/bin/rcp command is the model for syntax and security. The dcp command is a DSM Distributed Shell Utility. The configuration and environmental settings for dsh impact the behavior of dcp. See the dsh command for more details.

Parameters

Item	Description
TARGET CONTEXT	Target context specification is identical for the dcp and dsh commands. See target context in the dsh man page for details on specifying contexts for the dcp command.
TARGET SPECIFICATION	Target specification is identical for the dcp and dsh commands. See the dsh man page for details on specifying targets for the dcp command.
TARGET LISTS	Target list syntax is identical for the dcp and dsh commands.
REMOTE USER	A `user_ID` can be specified for the remote copy command. Remote user specification is identical for the dcp and dsh commands.
REMOTE COPY COMMAND	The dcp command uses a configurable remote copy command to run remote commands on remote targets. Support is explicitly provided for AIX® Remote Shell rcp command, the OpenSSH scp command and the rsync command. For node targets, the remote copy command is determined by using the parameters in the order of precedence: The -r flag. The DCP_NODE_RCP environment variable. The /usr/bin/rcp command. For device targets, the remote shell is determined by the following order of precedence: The --device-rcp flag. The DCP_DEVICE_RCP environment variable. The default device remote copy command as defined by the target context. The RemoteCopyCmd attribute that is defined for the device target. The remote copy command is specified with a command-line flag or environment variable by using the following syntax: `[context:]path[,[context:]path]...` where `path` is the path to the remote copy command, and `context:` identifies the remote copy command context to use for copying files. A remote copy command path that is specified without a context applies to all other contexts where an explicit remote copy command path is not specified in the list. The remote copy command options can be configured by using command-line flags or environment variables. For node targets, the remote copy command options are determined by the following order of precedence: The -o flag. The DCP_NODE_OPTS environment variable. For device targets, the remote copy command options are determined by the following order of precedence: The -O flag. The DCP_DEVICE_OPTS environment variable. The remote copy command options are specified by using the following syntax: `[context:]"options"[, [context:]"options"]...` where `options` are the remote copy command options, and `context:` identifies the remote shell options context to use for copying files. Options that are specified without a context apply to all other contexts where explicit options have not been specified in the list. The options must be specified within double quotation marks ("") to distinguish them from the dcp options.
COMMAND EXECUTION	Specifies concurrent remote copy command processes (fanout) that can be specified with the -f flag or the DSH_FANOUT environment variable. The fanout is only restricted by the number of remote shell commands that can be run in parallel. You can experiment with the DSH_FANOUT value on your management server to see whether higher values are appropriate. A timeout value for remote copy command execution can be specified with the -t flag or DSH_TIMEOUT environment variable. If any remote target does not respond within the timeout value, the dcp command displays an error message and exits. The -T flag provides diagnostic trace information for dcp command execution. Default settings and the actual remote copy commands that are run to the remote targets are displayed. The dcp command can be run silently by using the -Q flag; no target standard output or standard error is displayed. The parameters for this variable follow: `source_file...` Specifies the complete path for the file to be copied to or from the target. Multiple files can be specified. When used with the -R flag, only a single directory can be specified. When used with the -P flag, only a single file can be specified. `target_path` Specifies the complete path to copy one or more `source_file` files to on the target. If the -P flag is specified, the `target_path` is the local host location for the copied files. The remote file directory structure is re-created under `target_path` and the remote target name is appended to the copied `source_file` name in the `target_path` directory.

Keywords

Item	Description
-a	Includes in the target list all nodes that are defined in the default context. The default context can be set by using the -C flag or the DSH_CONTEXT environment variable.
-A	Includes in the target list all devices that are defined in the default context. The default context can be set by using the -C flag or the DSH_CONTEXT environment variable. This flag is disabled on HMCs.
--all-devices `context_list`	Includes in the target list all devices that are defined in the contexts that are listed in `context_list`. The default context is not implicitly included in this list. This flag is disabled on HMC.
--all-nodes `context_list`	Includes in the target list all nodes that are defined in the contexts that are listed in `context_list`. The default context is not implicitly included in this list.
-C	Specifies the full path of the remote copy command that is used to copy files to or from device targets. A remote copy command for a specific context can be defined by including `context:` before the path.
--context`context`	Specifies the default context to use when the dcp command resolves target names. The context value must correspond to a valid context extension module in the /opt/ibm/sysmgt/dsm/pm/Context directory.
--device-rcp `device_remote_copy`	Starts the audit subsystem. The `device_remote_copy` syntax follows: `[context:]path[,[context:]path]...` This flag is disabled on HMCs. This keyword reads the instructions in the configuration files and determines the remote shell for device targets.
-d \| --devices `device_list`	Specifies a list of device targets to include in the target list. The `device_list` syntax is: `[context:] [user_ID@] device_name[,\` `[context:][user_ID@]device_name]...` This flag is disabled on HMCs.
-D \| --devicegroups `devicegroups`	Includes in the target list all devices that are defined in the device groups that are specified in the `devicegroups` list. The `devicegroups` syntax follow: `[context:] [user_ID@]devicegroup[,\` `[context:] [user_ID@]devicegroup]...` This flag is disabled on HMCs.
-f \| --fanout `fanout`	Specifies a fanout value for the maximum number of concurrently running remote shell processes. Sequential execution can be specified by indicating a fanout value of 1. If this flag is omitted, the default fanout value of 64 is used.
-l \| --user `user_ID`	Specifies a remote user name to use for remote copy execution.
-h \| --help	Displays command usage information.
-n \| --nodes `node_list`	Specifies a list of node targets to include in the target list. The `node_list` syntax follows: `[context:] [user_ID@]node_name[,\` `[context:] [user_ID@]node_name]...`
-o \| --node-options `node_options`	Specifies options to pass to the remote copy command for node targets. The options must be specified within double quotation marks to distinguish them from the dcp command flags. Options for nodes in a specific context can be defined by including `context:` before the option list. The syntax of `node_options` follows: `[context:]"options"[, [context:]"options"]...`
-N \| --nodegroups `nodegroups`	Includes all nodes in the target list that are defined in the node groups that are specified in the `nodegroups` list. The syntax of `nodegroups` follows: `[context:] [user_ID@]nodegroup[,\` `[context:] [user_ID@]nodegroup]...`
-O --device-options `device_options`	Specifies options to pass to the remote copy command for device targets. The options must be specified within double quotation marks to distinguish them from the dcp command flags. Options for devices in a specific context can be defined by including `context:` before the option list. The syntax of `device_options` follows: `[context:]"options"[,[context:]"options"]...` This flag is disabled on HMCs.
-p \| --preserve	Preserves the source file characteristics as implemented by the configured remote copy command.
-P \| --pull	Pulls (copies) the files from the targets and places them in the `target_path` directory on the local host. The `target_path` must be a directory. Files that are pulled from remote machines have `_target` appended to the file name to distinguish between them. When the -P flag is used with the -R flag, `_target` is appended to the directory. Only one file per invocation of the dcp -P \| --pull command can be pulled from the specified targets.
-Q	Runs the dcp command silently such that no target standard output or standard error is displayed.
-q \| --show-config	Displays the current environment settings relevant to all dsh utility commands. This flag includes the values of all environment variables and settings for all currently installed and valid contexts. Each setting is prefixed with `context:` to identify the source context of the setting.
-r \| --node-rcp `node_remote_copy`	Specifies the full path of the remote copy command that is used to copy files to or from node targets. A remote copy command for a specific context can be defined by including `context:` before the path. The `node_remote_copy` syntax follows: `[context:]path[,[context:]path]...` If `path` contains rsync, it is assumed that the rsync command performs the remote copy.
-R \| --recursive	Recursively copies files from a local directory to the remote targets, or when specified with the -P flag. It recursively pulls (copies) files from a remote directory to the local host. A single source directory can be specified by using the `source_file` parameter.
-t \| --timeout `timeout`	Specifies the time, in seconds, to wait for the remote copy command to finish each remote target. If a target does not respond within the timeout value, the dcp command displays an error message and stops the remote copy process for the remote target. If not specified, the dcp command waits indefinitely for the remote copy process to finish each target.
-T \| --trace	Activates the trace mode. Sends the dcp command diagnostic messages to standard output.
-v \| --verify	Verifies each target before it runs any remote commands on the target. If a target is not responding, remote command execution for the target is canceled.
-X `env_list`	Ignores the dcp command environment variables. This option accepts an argument, which is a comma-separated list of environment variable names, that must not be ignored. If there is no argument to this option, or the argument is an empty string, all the dcp environment variables are not accepted.
-V \| --version	Displays version information for the dcp command environment variables. DSH_CONTEXT Specifies the default context to use when it resolves targets. This variable is overridden by the -C flag. DSH_DEVICE_LIST Specifies a file that contains a list of device targets. This variable is overridden by the -d flag. This environment variable is ignored on HMCs. DCP_DEVICE_OPTS Specifies the options to use for the remote shell command with device targets only. This variable is overridden by the -O flag. This environment variable is ignored on HMCs. DCP_DEVICE_RCP Specifies the full path of the remote copy command that is used to copy files to or from device targets. This variable is overridden by the --device-rcp flag. This environment variable is ignored on HMCs. DSH_FANOUT Specifies the fanout value. This variable is overridden by the -f flag. DCP_NODE_OPTS Specifies the options to use for the remote copy command with node targets only. This variable is overridden by the -o flag. DCP_NODE_RCP Specifies the full path of the remote command that is used to copy files to and from node targets. This variable is overridden by the -r flag. DSH_NODE_LIST Specifies a file that contains a list of node targets. This variable is overridden by the -n flag. This variable has replaced the WCOLL. DSH_NODEGROUP_PATH variable. The DSH_NODE_LIST variable also specifies a colon-separated list of directories that contain node group files for the dsh context. When the -a flag is specified in the dsh context, a list of unique node names is collected from all node group files in the path. DSH_TIMEOUT Specifies the time, in seconds, to wait for output from each remote target. This variable is overridden by the -t flag. RSYNC_RSH This rsync environment variable specifies the remote shell to be used as the transport for the rsync command. Exit status and exit values for each remote copy command execution are displayed in messages from the dcp command, if the remote copy command exit value is non-zero. A non-zero return code from a remote copy command indicates that an error was encountered during the remote copy. If a remote copy command encounters an error, execution of the remote copy on that target is bypassed. The dcp command exit code is 0 if the dcp command ran without errors and all remote copy commands finished with exit codes of 0. If internal dcp command errors occur or the remote copy commands do not complete successfully, the dcp command exit value is greater than 0. The exit value is increased by 1 for each successive instance of an unsuccessful remote copy command execution. Security: The dcp command has no security configuration requirements. All remote command security requirements (configuration, authentication, and authorization) are imposed by the underlying remote command that is configured for the dcp command. Authentication and authorization are assumed to be configured between the local host and remote targets. Interactive password prompting is not supported; execution is bypassed and an error is displayed for a remote target if password prompting occurs. The security configurations as they pertain to the remote environment and remote shell command are user-defined. When /usr/bin/rcp is configured as your remote command by using Kerberos Version 5, you must first run the Kerberos kinit command to obtain a ticket-granting ticket. You must also ensure that your Kerberos principal is in the .k5login file in the remote user&csqg;s home directory on the targets.

Examples

To copy the /tmp/etc/hosts file from the local host to the /etc directory on node3, node4, node5, and to user gregb on device16 in the NIM context, enter the following command:
```
dcp -n node3-node5 -d NIM:gregb@device16 /tmp/etc/hosts /etc:
```
To copy the /etc/hosts file from all managed nodes in the cluster to the /tmp/hosts.dir directory on the local host, enter the following command:
```
dcp -aP /etc/hosts /tmp/hosts.dir
```
A suffix that specifies the name of the target is appended to each file name. The contents of the /tmp/hosts.dir directory are like:

hosts._node1 hosts._node4 hosts._node7

hosts._node2 hosts._node5 hosts._node8

hosts._node3 hosts._node6
To copy the /var/log/testlogdir directory from all targets in NodeGroup1 in the NIM context and DeviceGroup4 in the dsh context, with a fanout of 12, and save each directory on the local host as /var/log._target, enter the following command:
```
dcp -C DSH -N NIM:NodeGroup1 -D DeviceGroup 4 -f 12 \ -RP /var/log/testlogdir /var/log
```
To copy /localnode/smallfile and /tmp/bigfile to /tmp on node1 by using the rsync command, enter the following command:
```
RSYNC_RSH=/usr/bin/ssh; dcp -r /usr/bin/rsync -o "-z" \ -n node1 /localnode/smallfile /tmp/bigfile /tmp
```
This command uses rsync with the RSYNC_RSH environment variable and the -z flag on rsync.
To copy the /etc/hosts file from the local host to all the nodes in the cluster, and ignore all the dcp environment variable, enter the following command:
```
dcp -X -a /etc/hosts /etc/hosts
```
To copy the /etc/hosts file from node1 and node2 to the /tmp/hosts.dir directory on the local host and ignore all the dcp environment variables except the DCP_NODE_OPTS, enter the following command:
```
dcp -n node1,node2 -P -X ’DCP_NODE_OPTS’ /etc/hosts /tmp/hosts.dir
```


hosts._node1	hosts._node4	hosts._node7
hosts._node2	hosts._node5	hosts._node8
hosts._node3	hosts._node6