Runs commands concurrently on multiple nodes and hardware devices.
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]
[-o node_options] [-O device_options]
[-r node_remote_copy] [--device-rcp
device_remote_copy] [-R] [-t timeout]
[-v] source_file... target_path
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.
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:
[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:
[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. |
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. |
dcp -n node3-node5 -d NIM:gregb@device16 /tmp/etc/hosts /etc:
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 |
dcp -C DSH -N NIM:NodeGroup1 -D DeviceGroup 4 -f 12 \ -RP /var/log/testlogdir /var/log
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. dcp -X -a /etc/hosts /etc/hosts
dcp -n node1,node2 -P -X ’DCP_NODE_OPTS’ /etc/hosts /tmp/hosts.dir