From 847f2fcaf36e8cc8b7b620526b30b2318fcb8731 Mon Sep 17 00:00:00 2001 From: Mark Gurevich Date: Fri, 26 Feb 2016 13:57:01 -0500 Subject: [PATCH] Add bypass flag description to xdcp and xdsh commands --- .../admin-guides/references/man1/xdcp.1.rst | 49 +++++++------ .../admin-guides/references/man1/xdsh.1.rst | 73 +++++++++---------- perl-xCAT/xCAT/DSHCLI.pm | 4 +- xCAT-client/pods/man1/xdcp.1.pod | 46 ++++++------ xCAT-client/pods/man1/xdsh.1.pod | 70 ++++++++---------- 5 files changed, 120 insertions(+), 122 deletions(-) diff --git a/docs/source/guides/admin-guides/references/man1/xdcp.1.rst b/docs/source/guides/admin-guides/references/man1/xdcp.1.rst index 609be1379..a6ad48ea0 100644 --- a/docs/source/guides/admin-guides/references/man1/xdcp.1.rst +++ b/docs/source/guides/admin-guides/references/man1/xdcp.1.rst @@ -19,7 +19,7 @@ xdcp.1 **************** -\ **xdcp**\ \ *noderange*\ [[\ **-f**\ \ *fanout*\ ] [\ **-L**\ ] [\ **-l**\ \ *userID*\ ] [\ **-o**\ \ *node_options*\ ] [\ **-p**\ ] [\ **-P**\ ] [\ **-r**\ \ *node_remote_shell*\ ] [\ **-R**\ ] [\ **-t**\ \ *timeout*\ ] [\ **-T**\ ] [\ **-v**\ ] [\ **-q**\ ] [\ **-X**\ \ *env_list*\ ] \ *sourcefile.... targetpath*\ +\ **xdcp**\ \ *noderange*\ [[\ **-B**\ | \ **-**\ **-bypass**\ ] [\ **-f**\ \ *fanout*\ ] [\ **-L**\ ] [\ **-l**\ \ *userID*\ ] [\ **-o**\ \ *node_options*\ ] [\ **-p**\ ] [\ **-P**\ ] [\ **-r**\ \ *node_remote_shell*\ ] [\ **-R**\ ] [\ **-t**\ \ *timeout*\ ] [\ **-T**\ ] [\ **-v**\ ] [\ **-q**\ ] [\ **-X**\ \ *env_list*\ ] \ *sourcefile.... targetpath*\ \ **xdcp**\ \ *noderange*\ [\ **-F**\ \ *rsync input file*\ ] @@ -36,15 +36,13 @@ xdcp.1 The \ **xdcp**\ command concurrently copies files to or from remote target -nodes. The command issues a remote copy com- -mand 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 +nodes. The 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. If using hierarchy, then xdcp runs on the service node that is servicing the compute node. The file will first be copied to the path defined in the site table, SNsyncfiledir attribute, or the default path /var/xcat/syncfiles on the service node, if the attribute is not defined. The -P flag will not automatically copy the files from the compute node to the Management node, hierarchically. There -is a two step process, see -P flag. -If the Management Node is target node, it must be defined in the xCAT database with nodetype=mn. When the \ **xdcp**\ command runs the Management Node as the target, it does not use remote commands but uses the local OS copy (cp) command. +is a two step process, see \ **-P**\ flag. +If the Management Node is target node, it must be defined in the xCAT database with nodetype=mn. When the \ **xdcp**\ command runs the Management Node as the target, it does not use remote commands but uses the local OS copy (\ **cp**\ ) command. \ **REMOTE**\ \ **USER**\ : @@ -53,6 +51,7 @@ specification is identical for the xdcp and xdsh commands. See the xdsh command for more information. \ **REMOTE**\ \ **COMMAND**\ \ **COPY**\ : + The \ **xdcp**\ command uses a configurable remote copy command to execute remote copies on remote targets. Support is explicitly provided for Remote Shell rcp command, the OpenSSH scp command and the @@ -65,24 +64,23 @@ ing order of precedence: 2. The \ **/usr/bin/scp**\ command. -\ **COMMAND**\ \ **EXECUTIONS**\ +\ **COMMAND**\ \ **EXECUTIONS**\ : + The maximum number of concurrent remote copy command processes (the -fanout) can be specified with the -f flag or the DSH_FANOUT environment +fanout) 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 +the \ **-t**\ flag or DSH_TIMEOUT environment variable. If any remote target does not respond within the timeout value, the xdcp command displays an error message and exits. -The -T flag provides diagnostic trace information for dcp command exe- -cution. Default settings and the actual remote copy commands that are -executed to the remote targets are displayed. +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 xdcp command can be executed silently using the -Q flag; no target +The \ **xdcp**\ command can be executed silently using the \ **-Q**\ flag; no target standard output or standard error is displayed. @@ -114,19 +112,25 @@ standard output or standard error is displayed. +\ **-B | -**\ **-bypass**\ + + Runs in bypass mode, use if the xcatd daemon is hung. + + + \ **-f | -**\ **-fanout**\ \ *fanout_value*\ Specifies a fanout value for the maximum number of concur- rently executing remote shell processes. Serial execution - can be specified by indicating a fanout value of \ **1**\ . If \ **-f**\ - is not specified, a default fanout value of \ **64**\ is used. + can be specified by indicating a fanout value of \ **1**\ . + If \ **-f**\ is not specified, a default fanout value of \ **64**\ is used. \ **-F | -**\ **-File**\ \ *rsync input file*\ Specifies the path to the file that will be used to - build the rsync command. + build the \ **rsync**\ command. The format of the input file is as follows, each line contains: @@ -152,11 +156,12 @@ standard output or standard error is displayed. For example: - /etc/password /etc/hosts -> /etc .. code-block:: perl + /etc/password /etc/hosts -> /etc + /tmp/file2 -> /tmp/file2 /tmp/file2 -> /tmp/ @@ -289,7 +294,7 @@ standard output or standard error is displayed. 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 + them. When the \ **-P**\ flag is used with the \ **-R**\ flag, ._target is appended to the directory. Only one file per invocation of the xdcp pull command can be pulled from the specified targets. Hierarchy is not automatically support yet. You must first pull @@ -318,7 +323,7 @@ standard output or standard error is displayed. \ **-R | -**\ **-recursive**\ \ *recursive*\ Recursively copies files from a local directory to the remote - targets, or when specified with the -P flag, recursively pulls + targets, or when specified with the \ **-P**\ flag, recursively pulls (copies) files from a remote directory to the local host. A single source directory can be specified using the source_file parameter. @@ -327,7 +332,7 @@ standard output or standard error is displayed. \ **-s**\ \ *synch service nodes*\ - Will only sync the files listed in the synclist (-F), to the service + Will only sync the files listed in the synclist (\ **-F**\ ), to the service nodes for the input compute node list. The files will be placed in the directory defined by the site.SNsyncfiledir attribute, or the default /var/xcat/syncfiles directory. @@ -338,8 +343,8 @@ standard output or standard error is displayed. Specifies the time, in seconds, to wait for output from any currently executing remote targets. If no output is - available from any target in the specified \ *timeout*\ , \ **xdsh**\ - displays an error and terminates execution for the remote + available from any target in the specified \ *timeout*\ , + \ **xdsh**\ displays an error and terminates execution for the remote targets that failed to respond. If \ *timeout*\ is not specified, \ **xdsh**\ waits indefinitely to continue processing output from all remote targets. When specified with the \ **-i**\ flag, the diff --git a/docs/source/guides/admin-guides/references/man1/xdsh.1.rst b/docs/source/guides/admin-guides/references/man1/xdsh.1.rst index 134f85744..817dc0c04 100644 --- a/docs/source/guides/admin-guides/references/man1/xdsh.1.rst +++ b/docs/source/guides/admin-guides/references/man1/xdsh.1.rst @@ -19,9 +19,8 @@ xdsh.1 **************** -\ **xdsh**\ \ *noderange*\ [\ **-B**\ \ *bypass*\ ] [\ **-**\ **-devicetype**\ \ *type_of_device*\ ] [\ **-e**\ ] [\ **-E**\ \ *environment_file*\ ] [\ **-f**\ \ *fanout*\ ] -[\ **-L**\ ] [\ **-l**\ \ *userID*\ ] [\ **-m**\ ] [\ **-o**\ -\ *node_options*\ ] [\ **-Q**\ ] [\ **-r**\ \ *node_remote_shell*\ ] [\ **-s**\ ] [\ **-S**\ \ **csh | ksh**\ ] [\ **-t**\ \ *timeout*\ ] +\ **xdsh**\ \ *noderange*\ [\ **-B**\ | \ **-**\ **-bypass**\ ] [\ **-**\ **-devicetype**\ \ *type_of_device*\ ] [\ **-e**\ ] [\ **-E**\ \ *environment_file*\ ] [\ **-f**\ \ *fanout*\ ] +[\ **-L**\ ] [\ **-l**\ \ *userID*\ ] [\ **-m**\ ] [\ **-o**\ \ *node_options*\ ] [\ **-Q**\ ] [\ **-r**\ \ *node_remote_shell*\ ] [\ **-s**\ ] [\ **-S**\ {\ **csh | ksh**\ }] [\ **-t**\ \ *timeout*\ ] [\ **-T**\ ] [\ **-v**\ ] [\ **-X**\ \ *env_list*\ ] [\ **-z**\ ] [\ **-**\ **-sudo**\ ] \ *command_list*\ \ **xdsh**\ \ *noderange*\ [\ **-K**\ ] @@ -49,9 +48,8 @@ The \ **xdsh**\ command is an xCAT Distributed Shell Utility. \ **COMMAND**\ \ **SPECIFICATION**\ : -The commands to execute on the targets are specified by the -\ *command_list*\ \ **xdsh**\ parameter, or executing a local script using the \ **-e**\ -flag. +The commands to execute on the targets are specified by the +\ *command_list*\ \ **xdsh**\ parameter, or executing a local script using the \ **-e**\ flag. The syntax for the \ *command_list*\ \ **xdsh**\ parameter is as follows: @@ -61,14 +59,12 @@ where \ *command*\ is the command to run on the remote target. Quotation marks are required to ensure that all commands in the list are executed remotely, and that any special characters are interpreted correctly on the remote target. A script file on the local host can be -executed on each of the remote targets by using the \ **-e**\ -flag. If \ **-e**\ is specified, \ *command_list*\ is the +executed on each of the remote targets by using the \ **-e**\ flag. If \ **-e**\ is specified, \ *command_list*\ is the script name and arguments to the script. For example: xdsh hostname -e \ *script_filename*\ [\ *arguments*\ ]... -The \ *script_filename*\ file is copied to a random filename in the \ **/tmp**\ -directory on each remote target and then executed on the targets. +The \ *script_filename*\ file is copied to a random filename in the \ **/tmp**\ directory on each remote target and then executed on the targets. The \ **xdsh**\ command does not work with any interactive commands, including those that read from standard input. @@ -102,8 +98,7 @@ dence: The shell environment used on the remote target defaults to the shell defined for the \ *user_ID*\ on the remote target. The command -syntax that \ **xdsh**\ uses to form the remote commands can be specified using the \ **-S**\ -flag. If \ **-S**\ is not specified, the syntax defaults to \ **sh**\ syntax. +syntax that \ **xdsh**\ uses to form the remote commands can be specified using the \ **-S**\ flag. If \ **-S**\ is not specified, the syntax defaults to \ **sh**\ syntax. When commands are executed on the remote target, the path used is determined by the \ **DSH_PATH**\ environment variable defined in the shell of @@ -116,11 +111,15 @@ DSH_PATH=$PATH The \ **-E**\ flag exports a local environment definition file to each remote target. Environment variables specified in this file are defined in the remote shell environment before the \ *command_list*\ is executed. -The definition file should contain entries like the following - and be executable. One environment variable per line. +The definition file should contain entries like the following and be executable. One environment variable per line. + + +.. code-block:: perl + export NEWENVVARIABLE="yes" export ANOTHERENVVARIABLE="yes" + \ **COMMAND**\ \ **EXECUTION**\ : The maximum number of concurrent remote shell command processes (the @@ -196,12 +195,18 @@ running commands, are terminated (SIGTERM). +\ **-B | -**\ **-bypass**\ + + Runs in bypass mode, use if the xcatd daemon is hung. + + + \ **-c | -**\ **-cleanup**\ This flag will have xdsh remove all files from the subdirectories of the the directory on the servicenodes, where xdcp stages the copy to the compute nodes as defined in the site table SNsyncfiledir and nodesyncfiledir - attribute, when the target is a service node. + attribute, when the target is a service node. It can also be used to remove the nodesyncfiledir directory on the compute nodes, which keeps the backup copies of files for the xdcp APPEND function support, if a compute node is the target. @@ -247,10 +252,7 @@ running commands, are terminated (SIGTERM). \ **-f | -**\ **-fanout**\ \ *fanout_value*\ - Specifies a fanout value for the maximum number of concur- - rently executing remote shell processes. Serial execution - can be specified by indicating a fanout value of \ **1**\ . If \ **-f**\ - is not specified, a default fanout value of \ **64**\ is used. + Specifies a fanout value for the maximum number of concurrently executing remote shell processes. Serial execution can be specified by indicating a fanout value of \ **1**\ . If \ **-f**\ is not specified, a default fanout value of \ **64**\ is used. @@ -280,7 +282,7 @@ running commands, are terminated (SIGTERM). Set up the SSH keys for the user running the command to the specified node list. The userid must have the same uid, gid and password as the userid on the node - where the keys will be setup. + where the keys will be setup. If the current user is root, roots public ssh keys will be put in the authorized_keys\* files under roots .ssh directory on the node(s). If the current user is non-root, the user must be in the policy table and have credential to run the xdsh command. @@ -289,14 +291,13 @@ running commands, are terminated (SIGTERM). Other device types, such as IB switch, are also supported. The device should be defined as a node and nodetype should be defined as switch before connecting. - The xdsh -K command must be run from the Management Node. + The \ **xdsh -K**\ command must be run from the Management Node. \ **-l | -**\ **-user**\ \ *user_ID*\ - Specifies a remote user name to use for remote command exe- - cution. + Specifies a remote user name to use for remote command execution. @@ -335,9 +336,7 @@ running commands, are terminated (SIGTERM). \ **-Q | -**\ **-silent**\ - Specifies silent mode. No target output is written to stan- - dard output or standard error. Monitoring messages are - written to standard output. + Specifies silent mode. No target output is written to standard output or standard error. Monitoring messages are written to standard output. @@ -356,18 +355,18 @@ running commands, are terminated (SIGTERM). -\ **-S | -**\ **-syntax**\ \ **csh | ksh**\ +\ **-S | -**\ **-syntax**\ {\ **csh | ksh**\ } Specifies the shell syntax to be used on the remote target. If not specified, the \ **ksh**\ syntax is used. -\ **-**\ **-sudo | -**\ **-sudo**\ +\ **-**\ **-sudo**\ - Adding the --sudo flag to the xdsh command will have xdsh run sudo before - running the command. This is particular useful when using the -e option. - This is required when you input -l with a non-root user id and want that id + Adding the \ **-**\ **-sudo**\ flag to the xdsh command will have xdsh run sudo before + running the command. This is particular useful when using the \ **-e**\ option. + This is required when you input \ **-l**\ with a non-root user id and want that id to be able to run as root on the node. The non-root userid will must be previously defined as an xCAT user, see process for defining non-root ids in xCAT and setting up for using xdsh. The userid sudo setup will have @@ -545,13 +544,13 @@ running commands, are terminated (SIGTERM). To provide backward compatibility for scripts written using dsh in -AIX and CSM, a tool has been provide \ **groupfiles4dsh**\ , +AIX and CSM, a tool has been provided \ **groupfiles4dsh**\ , which will build node group files from the -xCAT database that can be used by dsh. See man groupfiles4dsh. +xCAT database that can be used by dsh. See \ **man groupfiles4dsh**\ . **************** -\ **Security**\ +\ **SECURITY**\ **************** @@ -569,7 +568,7 @@ userdefined. ******************* -\ **Exit Status**\ +\ **EXIT STATUS**\ ******************* @@ -577,7 +576,7 @@ The dsh command exit code is 0 if the command executed without errors and all re **************** -\ **Examples**\ +\ **EXAMPLES**\ **************** @@ -607,7 +606,7 @@ The dsh command exit code is 0 if the command executed without errors and all re .. code-block:: perl - xdsh node1,node2 -o"-v -t" ps + xdsh node1,node2 -o "-v -t" ps diff --git a/perl-xCAT/xCAT/DSHCLI.pm b/perl-xCAT/xCAT/DSHCLI.pm index 870f919d5..8dc10874b 100644 --- a/perl-xCAT/xCAT/DSHCLI.pm +++ b/perl-xCAT/xCAT/DSHCLI.pm @@ -3825,7 +3825,7 @@ sub usage_dsh ## usage message my $usagemsg1 = " xdsh -h \n xdsh -q \n xdsh -V \n"; my $usagemsg1a = "xdsh [-K] [-l logonuserid]\n"; - my $usagemsg2 = " [-B bypass ] [-c] [-e] [-E environment_file] + my $usagemsg2 = " [-B | --bypass ] [-c] [-e] [-E environment_file] [--devicetype type_of_device] [-f fanout]\n"; my $usagemsg3 = " [-l user_ID] [-L] "; my $usagemsg4 = "[-m] [-o options][-q] [-Q] [-r remote_shell] @@ -4276,7 +4276,7 @@ sub usage_dcp { ### usage message my $usagemsg1 = " xdcp -h \n xdcp -q\n xdcp -V \n xdcp \n"; - my $usagemsg2 = " [-B bypass] [-c] [-f fanout] [-l user_ID] [--sudo]\n"; + my $usagemsg2 = " [-B | --bypass] [-c] [-f fanout] [-l user_ID] [--sudo]\n"; my $usagemsg3 = " [-m] [-o options] [-p] [-P] [-q] [-Q] [-r node_remote_copy]\n"; my $usagemsg4 = diff --git a/xCAT-client/pods/man1/xdcp.1.pod b/xCAT-client/pods/man1/xdcp.1.pod index 2d2bc4613..71c10d931 100644 --- a/xCAT-client/pods/man1/xdcp.1.pod +++ b/xCAT-client/pods/man1/xdcp.1.pod @@ -4,7 +4,7 @@ B - Concurrently copies files to or from multiple nodes. In addition, prov =head1 B -B I [[B<-f> I] [B<-L>] [B<-l> I] [B<-o> I] [B<-p>] [B<-P>] [B<-r> I] [B<-R>] [B<-t> I] [B<-T>] [B<-v>] [B<-q>] [B<-X> I] I +B I [[B<-B> | B<--bypass>] [B<-f> I] [B<-L>] [B<-l> I] [B<-o> I] [B<-p>] [B<-P>] [B<-r> I] [B<-R>] [B<-t> I] [B<-T>] [B<-v>] [B<-q>] [B<-X> I] I B I [B<-F> I] @@ -20,15 +20,13 @@ B [B<-h> | B<-V> | B<-q>] =head1 B The B command concurrently copies files to or from remote target -nodes. The command issues a remote copy com- -mand 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 +nodes. The 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. If using hierarchy, then xdcp runs on the service node that is servicing the compute node. The file will first be copied to the path defined in the site table, SNsyncfiledir attribute, or the default path /var/xcat/syncfiles on the service node, if the attribute is not defined. The -P flag will not automatically copy the files from the compute node to the Management node, hierarchically. There -is a two step process, see -P flag. -If the Management Node is target node, it must be defined in the xCAT database with nodetype=mn. When the B command runs the Management Node as the target, it does not use remote commands but uses the local OS copy (cp) command. +is a two step process, see B<-P> flag. +If the Management Node is target node, it must be defined in the xCAT database with nodetype=mn. When the B command runs the Management Node as the target, it does not use remote commands but uses the local OS copy (B) command. B B: @@ -37,6 +35,7 @@ specification is identical for the xdcp and xdsh commands. See the xdsh command for more information. B B B: + The B command uses a configurable remote copy command to execute remote copies on remote targets. Support is explicitly provided for Remote Shell rcp command, the OpenSSH scp command and the @@ -50,24 +49,23 @@ ing order of precedence: 2. The B command. -B B +B B: + The maximum number of concurrent remote copy command processes (the -fanout) can be specified with the -f flag or the DSH_FANOUT environment +fanout) can be specified with the B<-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 +the B<-t> flag or DSH_TIMEOUT environment variable. If any remote target does not respond within the timeout value, the xdcp command displays an error message and exits. -The -T flag provides diagnostic trace information for dcp command exe- -cution. Default settings and the actual remote copy commands that are -executed to the remote targets are displayed. +The B<-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 xdcp command can be executed silently using the -Q flag; no target +The B command can be executed silently using the B<-Q> flag; no target standard output or standard error is displayed. =head1 B @@ -92,18 +90,21 @@ under target_path and the remote target name is appended to the copied source_file name in the target_path directory. Note: the targetpath directory must exist. +=item B<-B>|B<--bypass> + +Runs in bypass mode, use if the xcatd daemon is hung. =item B<-f>|B<--fanout> I Specifies a fanout value for the maximum number of concur- rently executing remote shell processes. Serial execution -can be specified by indicating a fanout value of B<1>. If B<-f> -is not specified, a default fanout value of B<64> is used. +can be specified by indicating a fanout value of B<1>. +If B<-f> is not specified, a default fanout value of B<64> is used. =item B<-F>|B<--File> I Specifies the path to the file that will be used to -build the rsync command. +build the B command. The format of the input file is as follows, each line contains: ... -> < path to destination file/directory> @@ -117,7 +118,8 @@ or -> For example: -/etc/password /etc/hosts -> /etc + + /etc/password /etc/hosts -> /etc /tmp/file2 -> /tmp/file2 @@ -237,7 +239,7 @@ 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 +them. When the B<-P> flag is used with the B<-R> flag, ._target is appended to the directory. Only one file per invocation of the xdcp pull command can be pulled from the specified targets. Hierarchy is not automatically support yet. You must first pull @@ -262,7 +264,7 @@ for remote command execution on node targets. =item B<-R>|B<--recursive> I Recursively copies files from a local directory to the remote -targets, or when specified with the -P flag, recursively pulls +targets, or when specified with the B<-P> flag, recursively pulls (copies) files from a remote directory to the local host. A single source directory can be specified using the source_file parameter. @@ -270,7 +272,7 @@ parameter. =item B<-s> I -Will only sync the files listed in the synclist (-F), to the service +Will only sync the files listed in the synclist (B<-F>), to the service nodes for the input compute node list. The files will be placed in the directory defined by the site.SNsyncfiledir attribute, or the default /var/xcat/syncfiles directory. @@ -279,8 +281,8 @@ directory defined by the site.SNsyncfiledir attribute, or the default Specifies the time, in seconds, to wait for output from any currently executing remote targets. If no output is -available from any target in the specified I, B -displays an error and terminates execution for the remote +available from any target in the specified I, +B displays an error and terminates execution for the remote targets that failed to respond. If I is not specified, B waits indefinitely to continue processing output from all remote targets. When specified with the B<-i> flag, the diff --git a/xCAT-client/pods/man1/xdsh.1.pod b/xCAT-client/pods/man1/xdsh.1.pod index d305d4c89..88c3a61dd 100644 --- a/xCAT-client/pods/man1/xdsh.1.pod +++ b/xCAT-client/pods/man1/xdsh.1.pod @@ -4,9 +4,8 @@ B - Concurrently runs remote commands on multiple nodes (Management Node, =head1 B -B I [B<-B> I] [B<--devicetype> I] [B<-e>] [B<-E> I] [B<-f> I] -[B<-L>] [B<-l> I] [B<-m>] [B<-o> -I] [B<-Q>] [B<-r> I] [B<-s>] [B<-S> B|B] [B<-t> I] +B I [B<-B> | B<--bypass>] [B<--devicetype> I] [B<-e>] [B<-E> I] [B<-f> I] +[B<-L>] [B<-l> I] [B<-m>] [B<-o> I] [B<-Q>] [B<-r> I] [B<-s>] [B<-S> {B|B}] [B<-t> I] [B<-T>] [B<-v>] [B<-X> I] [B<-z>] [B<--sudo>] I B I [B<-K>] @@ -31,9 +30,8 @@ The B command is an xCAT Distributed Shell Utility. B B: -The commands to execute on the targets are specified by the -I B parameter, or executing a local script using the B<-e> -flag. +The commands to execute on the targets are specified by the +I B parameter, or executing a local script using the B<-e> flag. The syntax for the I B parameter is as follows: @@ -44,14 +42,12 @@ where I is the command to run on the remote target. Quotation marks are required to ensure that all commands in the list are executed remotely, and that any special characters are interpreted correctly on the remote target. A script file on the local host can be -executed on each of the remote targets by using the B<-e> -flag. If B<-e> is specified, I is the +executed on each of the remote targets by using the B<-e> flag. If B<-e> is specified, I is the script name and arguments to the script. For example: xdsh hostname -e I [I]... -The I file is copied to a random filename in the B -directory on each remote target and then executed on the targets. +The I file is copied to a random filename in the B directory on each remote target and then executed on the targets. The B command does not work with any interactive commands, including those that read from standard input. @@ -85,8 +81,7 @@ B B B: The shell environment used on the remote target defaults to the shell defined for the I on the remote target. The command -syntax that B uses to form the remote commands can be specified using the B<-S> -flag. If B<-S> is not specified, the syntax defaults to B syntax. +syntax that B uses to form the remote commands can be specified using the B<-S> flag. If B<-S> is not specified, the syntax defaults to B syntax. When commands are executed on the remote target, the path used is determined by the B environment variable defined in the shell of @@ -99,10 +94,10 @@ DSH_PATH=$PATH The B<-E> flag exports a local environment definition file to each remote target. Environment variables specified in this file are defined in the remote shell environment before the I is executed. -The definition file should contain entries like the following - and be executable. One environment variable per line. - export NEWENVVARIABLE="yes" - export ANOTHERENVVARIABLE="yes" +The definition file should contain entries like the following and be executable. One environment variable per line. + + export NEWENVVARIABLE="yes" + export ANOTHERENVVARIABLE="yes" B B: @@ -176,13 +171,16 @@ running commands, are terminated (SIGTERM). =over 5 +=item B<-B>|B<--bypass> + +Runs in bypass mode, use if the xcatd daemon is hung. =item B<-c>|B<--cleanup> This flag will have xdsh remove all files from the subdirectories of the the directory on the servicenodes, where xdcp stages the copy to the compute nodes as defined in the site table SNsyncfiledir and nodesyncfiledir - attribute, when the target is a service node. +attribute, when the target is a service node. It can also be used to remove the nodesyncfiledir directory on the compute nodes, which keeps the backup copies of files for the xdcp APPEND function support, if a compute node is the target. @@ -220,10 +218,7 @@ I as the base. =item B<-f>|B<--fanout> I -Specifies a fanout value for the maximum number of concur- -rently executing remote shell processes. Serial execution -can be specified by indicating a fanout value of B<1>. If B<-f> -is not specified, a default fanout value of B<64> is used. +Specifies a fanout value for the maximum number of concurrently executing remote shell processes. Serial execution can be specified by indicating a fanout value of B<1>. If B<-f> is not specified, a default fanout value of B<64> is used. =item B<-h>|B<--help> @@ -246,7 +241,7 @@ normally the Management Node. The command you run must not prompt for input, the Set up the SSH keys for the user running the command to the specified node list. The userid must have the same uid, gid and password as the userid on the node - where the keys will be setup. +where the keys will be setup. If the current user is root, roots public ssh keys will be put in the authorized_keys* files under roots .ssh directory on the node(s). If the current user is non-root, the user must be in the policy table and have credential to run the xdsh command. @@ -255,12 +250,11 @@ the authorized_keys* files under the non-root users .ssh directory on the node(s Other device types, such as IB switch, are also supported. The device should be defined as a node and nodetype should be defined as switch before connecting. -The xdsh -K command must be run from the Management Node. +The B command must be run from the Management Node. =item B<-l>|B<--user> I -Specifies a remote user name to use for remote command exe- -cution. +Specifies a remote user name to use for remote command execution. =item B<-L>|B<--no-locale> @@ -289,9 +283,7 @@ identify the source context of the setting. =item B<-Q>|B<--silent> -Specifies silent mode. No target output is written to stan- -dard output or standard error. Monitoring messages are -written to standard output. +Specifies silent mode. No target output is written to standard output or standard error. Monitoring messages are written to standard output. =item B<-r>|B<--node-rsh> I @@ -306,16 +298,16 @@ Specifies that output is returned as it becomes available from each target, instead of waiting for the I to be completed on a target before returning output. -=item B<-S>|B<--syntax> B|B +=item B<-S>|B<--syntax> {B|B} Specifies the shell syntax to be used on the remote target. If not specified, the B syntax is used. -=item B<--sudo>|B<--sudo> +=item B<--sudo> -Adding the --sudo flag to the xdsh command will have xdsh run sudo before -running the command. This is particular useful when using the -e option. -This is required when you input -l with a non-root user id and want that id +Adding the B<--sudo> flag to the xdsh command will have xdsh run sudo before +running the command. This is particular useful when using the B<-e> option. +This is required when you input B<-l> with a non-root user id and want that id to be able to run as root on the node. The non-root userid will must be previously defined as an xCAT user, see process for defining non-root ids in xCAT and setting up for using xdsh. The userid sudo setup will have @@ -459,11 +451,11 @@ flag. =head1 B To provide backward compatibility for scripts written using dsh in -AIX and CSM, a tool has been provide B, +AIX and CSM, a tool has been provided B, which will build node group files from the -xCAT database that can be used by dsh. See man groupfiles4dsh. +xCAT database that can be used by dsh. See B. -=head1 B +=head1 B The B command has no security configuration requirements. All remote command security requirements - configuration, @@ -478,12 +470,12 @@ pertain to the remote environment and remote shell command are userdefined. -=head1 B +=head1 B The dsh command exit code is 0 if the command executed without errors and all remote shell commands finished with exit codes of 0. If internal dsh errors occur or the remote shell commands do not complete successfully, the dsh command exit value is greater than 0. The exit value is increased by 1 for each successive instance of an unsuccessful remote command execution. If the remotely issued command is run in the background, the exit code of the remotely issued command is 0. -=head1 B +=head1 B =over 3 @@ -500,7 +492,7 @@ To run the B command on node targets B and B, enter: =item 3. To run the B command on node targets B and run the remote command with the -v and -t flag, enter: - xdsh node1,node2 -o"-v -t" ps + xdsh node1,node2 -o "-v -t" ps =item 4. To execute the commands contained in B in the B