dcp Command

Purpose

Runs commands concurrently on multiple nodes and hardware devices.

Syntax

dcp -h dcp -V dcp -q dcp [-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 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 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. See the dsh man page for more information.
REMOTE USER	A user_ID can be specified for the remote copy command. Remote user specification is identical for the dcp and dsh commands. See the dsh command for more information.
REMOTE COPY COMMAND	The dcp command uses a configurable remote copy command to execute remote commands on remote targets. Support is explicitly provided for AIX® Remote Shell rcp command, the OpenSSH scp command and the /usr/bin/rsync command. For node targets, the remote copy command is determined 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 defined for the device target. The remote copy command is specified with a command-line flag or environment variable 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 specified without a context applies to all other contexts where an explicit remote copycommand path has not been specified in the list. Remote copy command options can be configured 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 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 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 dcp options.
COMMAND EXECUTION	Specifies concurrent remote copy command processes (the 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 if 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 executed to the remote targets are displayed. The dcp command can be executed silently using the -Q flag; no target standard output or standard error is displayed. Parameters 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 recreated 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 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 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 defined in the contexts listed in context_list. The default context is not implicitly included in this list. This flag is disabled on HMC.
--all-nodescontext_list	Includes in the target list all nodes defined in the contexts listed in context_list. The default context is not implicitly included in this list.
-C	Specifies the full path of the remote copy command 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.
--contextcontext	Specifies the default context to use when resolving 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	The device_remote_copy syntax is: [context:]path[,[context:]path]... This flag is disabled on HMCs. -D \| --devicegroups devicegroups Includes in the target list all devices defined in the device groups specified in the devicegroup. Starts the audit subsystem. This keyword reads the instructions in the configuration files and performs the following tasks:
-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 defined in the device groups specified in the devicegroups list. The devicegroups syntax is: [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 executing 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 (lowercase 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 is: [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 dcp flags. Options for nodes in a specific context can be defined by including context: before the option list. The syntax of node_options is: [context:]"options"[, [context:]"options"]...
-N \| --nodegroups nodegroups	Includes in the target list all nodes defined in the node groups specified in the nodegroups list. The syntax of nodegroups is: [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 dcp flags. Options for devices in a specific context can be defined by including context: before the option list. The syntax of device_options is: [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 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 \| --show-config	Displays the current environment settings relevant to all DSH Utilities 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 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 is: [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 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 terminates 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 dcp command diagnostic messages to standard output.
-v \| --verify	Verifies each target before running any remote commands on the target. If a target is not responding, remote command execution for the target is cancelled.
-X env_list	Ignores dcp 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 thedcp 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 resolving 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 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 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. The DSH_NODE_LIST variable has replaced WCOLL. DSH_NODEGROUP_PATH 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 used as the transport for rsync. See the rsync command for details. Exit Status 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 executed without errors and all remote copy commands finished with exit codes of 0. If internal dcp 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 configured for dcp. 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 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:
```
dcp -aP /etc/hosts /tmp/hosts.dir
```
A suffix specifying the name of the target is appended to each file name. The contents of the /tmp/hosts.dir directory are like:
Item Description

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. Save each directory on the local host as /var/log._target, enter:
```
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 using rsync, enter:
```
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:
```
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. Ignore all the dcp environment variables except the DCP_NODE_OPTS, enter:
```
dcp -n node1,node2 -P -X ’DCP_NODE_OPTS’ /etc/hosts /tmp/hosts.dir
```

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