xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-05-22 03:32:04 +00:00
Code Issues Releases Wiki Activity

Merge pull request #745 from gurevichmark/bypass_man_fixes

Browse Source 
Add bypass flag description to xdcp and xdsh commands
This commit is contained in:
Victor Hu 2016-03-03 13:17:02 -05:00
commit b8e868bb7f
5 changed files with 120 additions and 122 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
docs/source/guides/admin-guides/references/man1/xdcp.1.rst
View File

@ -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

73
docs/source/guides/admin-guides/references/man1/xdsh.1.rst
View File

@ -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

4
perl-xCAT/xCAT/DSHCLI.pm
View File

@ -3825,7 +3825,7 @@ sub usage_dsh
## usage message
my $usagemsg1 = " xdsh -h \n xdsh -q \n xdsh -V \n";
my $usagemsg1a = "xdsh <noderange> [-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 <noderange>\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 =

46
xCAT-client/pods/man1/xdcp.1.pod
View File

@ -4,7 +4,7 @@ B<xdcp> - Concurrently copies files to or from multiple nodes. In addition, prov
=head1 B<SYNOPSIS>
B<xdcp> I<noderange> [[B<-f> I<fanout>] [B<-L>] [B<-l> I<userID>] [B<-o> I<node_options>] [B<-p>] [B<-P>] [B<-r> I<node_remote_shell>] [B<-R>] [B<-t> I<timeout>] [B<-T>] [B<-v>] [B<-q>] [B<-X> I<env_list>] I<sourcefile.... targetpath>
B<xdcp> I<noderange> [[B<-B> | B<--bypass>] [B<-f> I<fanout>] [B<-L>] [B<-l> I<userID>] [B<-o> I<node_options>] [B<-p>] [B<-P>] [B<-r> I<node_remote_shell>] [B<-R>] [B<-t> I<timeout>] [B<-T>] [B<-v>] [B<-q>] [B<-X> I<env_list>] I<sourcefile.... targetpath>
B<xdcp> I<noderange> [B<-F> I<rsync input file>]
@ -20,15 +20,13 @@ B<xdcp> [B<-h> | B<-V> | B<-q>]
=head1 B<DESCRIPTION>
The B<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 B<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 B<-P> flag.
If the Management Node is target node, it must be defined in the xCAT database with nodetype=mn. When the B<xdcp> command runs the Management Node as the target, it does not use remote commands but uses the local OS copy (B<cp>) command.
B<REMOTE> B<USER>:
@ -37,6 +35,7 @@ specification is identical for the xdcp and xdsh commands. See the xdsh
command for more information.
B<REMOTE> B<COMMAND> B<COPY>:
The B<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
@ -50,24 +49,23 @@ ing order of precedence:
2. The B</usr/bin/scp> command.
B<COMMAND> B<EXECUTIONS>
B<COMMAND> B<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 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<xdcp> command can be executed silently using the B<-Q> flag; no target
standard output or standard error is displayed.
=head1 B<OPTIONS>
@ -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<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 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<rsync input file>
Specifies the path to the file that will be used to
build the rsync command.
build the B<rsync> command.
The format of the input file is as follows, each line contains:
<path to source file1> <path to source file2> ... -> < path to destination file/directory>
@ -117,7 +118,8 @@ or
<path to source file> -> <path to destination directory ( must end in /)>
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<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 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<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 (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<timeout>, B<xdsh>
displays an error and terminates execution for the remote
available from any target in the specified I<timeout>,
B<xdsh> displays an error and terminates execution for the remote
targets that failed to respond. If I<timeout> is not specified,
B<xdsh> waits indefinitely to continue processing output from
all remote targets. When specified with the B<-i> flag, the

70
xCAT-client/pods/man1/xdsh.1.pod
View File

@ -4,9 +4,8 @@ B<xdsh> - Concurrently runs remote commands on multiple nodes (Management Node,
=head1 B<SYNOPSIS>
B<xdsh> I<noderange> [B<-B> I<bypass>] [B<--devicetype> I<type_of_device>] [B<-e>] [B<-E> I<environment_file>] [B<-f> I<fanout>]
[B<-L>] [B<-l> I<userID>] [B<-m>] [B<-o>
I<node_options>] [B<-Q>] [B<-r> I<node_remote_shell>] [B<-s>] [B<-S> B<csh>|B<ksh>] [B<-t> I<timeout>]
B<xdsh> I<noderange> [B<-B> | B<--bypass>] [B<--devicetype> I<type_of_device>] [B<-e>] [B<-E> I<environment_file>] [B<-f> I<fanout>]
[B<-L>] [B<-l> I<userID>] [B<-m>] [B<-o> I<node_options>] [B<-Q>] [B<-r> I<node_remote_shell>] [B<-s>] [B<-S> {B<csh>|B<ksh>}] [B<-t> I<timeout>]
[B<-T>] [B<-v>] [B<-X> I<env_list>] [B<-z>] [B<--sudo>] I<command_list>
B<xdsh> I<noderange> [B<-K>]
@ -31,9 +30,8 @@ The B<xdsh> command is an xCAT Distributed Shell Utility.
B<COMMAND> B<SPECIFICATION>:
The commands to execute on the targets are specified by the
I<command_list> B<xdsh> parameter, or executing a local script using the B<-e>
flag.
The commands to execute on the targets are specified by the
I<command_list> B<xdsh> parameter, or executing a local script using the B<-e> flag.
The syntax for the I<command_list> B<xdsh> parameter is as follows:
@ -44,14 +42,12 @@ where I<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 B<-e>
flag. If B<-e> is specified, I<command_list> is the
executed on each of the remote targets by using the B<-e> flag. If B<-e> is specified, I<command_list> is the
script name and arguments to the script. For example:
xdsh hostname -e I<script_filename> [I<arguments>]...
The I<script_filename> file is copied to a random filename in the B</tmp>
directory on each remote target and then executed on the targets.
The I<script_filename> file is copied to a random filename in the B</tmp> directory on each remote target and then executed on the targets.
The B<xdsh> command does not work with any interactive commands, including
those that read from standard input.
@ -85,8 +81,7 @@ B<REMOTE> B<SHELL> B<ENVIRONMENT>:
The shell environment used on the remote target defaults to the shell
defined for the I<user_ID> on the remote target. The command
syntax that B<xdsh> 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<sh> syntax.
syntax that B<xdsh> 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<sh> syntax.
When commands are executed on the remote target, the path used is
determined by the B<DSH_PATH> 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<command_list> 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<COMMAND> B<EXECUTION>:
@ -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</opt/xcat/share/xcat/devicetype/> as the base.
=item B<-f>|B<--fanout> I<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 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<xdsh -K> command must be run from the Management Node.
=item B<-l>|B<--user> I<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.
=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<node_remote_shell>
@ -306,16 +298,16 @@ Specifies that output is returned as it becomes available
from each target, instead of waiting for the I<command_list>
to be completed on a target before returning output.
=item B<-S>|B<--syntax> B<csh>|B<ksh>
=item B<-S>|B<--syntax> {B<csh>|B<ksh>}
Specifies the shell syntax to be used on the remote target.
If not specified, the B<ksh> 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<Compatibility with AIX dsh>
To provide backward compatibility for scripts written using dsh in
AIX and CSM, a tool has been provide B<groupfiles4dsh>,
AIX and CSM, a tool has been provided B<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 B<man groupfiles4dsh>.
=head1 B<Security>
=head1 B<SECURITY>
The B<xdsh> 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<Exit Status>
=head1 B<EXIT STATUS>
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<Examples>
=head1 B<EXAMPLES>
=over 3
@ -500,7 +492,7 @@ To run the B<ps -ef> command on node targets B<node1> and B<node2>, enter:
=item 3.
To run the B<ps> command on node targets B<node1> 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<myfile> in the B<XCAT>