dsh command

Use the dsh command to run Distributed Shell from the IBM® Flex System Manager CLI with the purpose of running commands on remote systems. This command applies to IBM Flex System Manager for AIX® only.

Synopsis

smcli [-c] [-prompt] [-user user_name] [-pw password] dsh options

smcli dsh {-h | -? | --help}

smcli dsh {-n system_name | -i ipaddress | -N nodegroup_name} [-O | --fanout fanout_value] [-m | --format {c|g}] [-o | --output output_path] [-l | --log log_file] [-c | --no-locale] [-r | --report report_path] [-e | --report-name report-name] [-Q] [-S csh|ksh] [-M | --timeout seconds] [-v] [-V] [-z] command_list

Description

The dsh command runs commands concurrently on remote targets. It issues a remote shell command for each specified target and returns the output from all targets. The output is formatted so that you can easily manage the command results from all targets.

Specify targets as a comma separated list of individual systems or as a comma separated list of groups. You can list individual systems using their names, object IDs, or TCP/IP addresses or host names. Groups are listed using their names. If a group is listed, the command is executed on all members of that group.

Options

-c | --no-locale
Specifies to not send locale information to the target machine.
-e | --report-name
Specifies the name to use when generating the report. If not specified, the name defaults to Unspecified. This flag can only be used with the --report flag.
-h | -?
Displays the syntax and a brief description of the command.
Tip: If you specify additional options other than -h | -? | --help, the options are ignored.
--help
Displays detailed information about the command, including the syntax, a description of the command, a description of the options and operands, error codes, and examples.
Tips:
  • If you specify additional options other than -h | -? | --help, the options are ignored.
  • You can also display detailed help in the form of man pages using the man command_name command.
-i | --ipaddress {ip_address | host_name}[,{ip_address | host_name}...]
Targets one or more systems, specified by IP address or host name.

The list can be a mixture of IP addresses and host names, separated by a comma.

ip_address
The IP address of the system.
Tips:
  • You can enter lssys -A IP_address to list the IP address of each discovered system.
  • You can use either the IPv4 or IPv6 format to specify the IP address.
host_name
Either the host name or the host name and Domain Name System (DNS) suffix of the system. If the host name contains spaces, enclose it in quotation marks. If it contains a comma, prefix the comma with a backslash (\).
Tips:
  • You can enter lssys -A HostName to list the host name of each discovered system.
  • The host names are not locale specific.
  • A given IP address or host name might resolve multiple systems. For example, both the OperatingSystem and Server instance of a particular system will have the same host name. Use system Object ID (option -n) to target a system uniquely.
-l | --log
Enables logging to the specified log_file. Output is appended to the file each time the smcli dsh command runs.
-m | --format c|g
Specifies an output formatting option for system information. One of either the c or g flags must be specified. Without --format, the smcli dsh command will display the output from each managed system as soon as it arrives. Each line of the output is preceded with the managed system name, OID, or hostname. With --format, the smcli dsh command will wait for all the output from each managed system to arrive before displaying it. The output is displayed as follows:
c
Compresses the output. Collapses identical output from more than one managed system so that it is displayed only once.
g
Groups the output from each managed system together.
-M | --timeout
Specifies the time, in seconds, to wait for the output from any command currently running on a remote managed system. If no output is available from any managed system in the specified timeout, smcli dsh displays an error and terminates the command for the remote managed system that failed to respond. If timeout is not specified, smcli dsh waits indefinitely to continue processing output from all remote managed systems.
-N | --groups {group_name}[,{group_name}...]
Targets all systems in one or more specified groups that are identified by name.
Tips:

  • If the same systems are members of more than one group, they are targeted only once.

  • To target all systems, specify the "All Systems" group.
group_name
The name of the group. If the group name contains spaces, enclose it in quotation marks. If it contains a comma, prefix the comma with a backslash (\) and enclose the name in quotation marks.
Tips:
  • Group names are unique.
  • Use the lsgp command without any options to list all group names.
  • The group names are not locale specific.
-n | --names {system_oid | system_name}[,{system_oid | system_name}...]
Targets one or more systems specified by name or ID.

The list can be a mixture of system names and IDs, separated by a comma and containing no blank spaces.

If the -n option is not specified, then a customized event action that starts a noninteractive task on the system on which the event occurred is created. If the -n option is specified, then a customized event action that starts a noninteractive task on a specified system is created.

system_oid
The unique ID of the system, specified as a hexadecimal value prefixed with 0x (for example, 0x37) or a decimal value (for example, 123).
Tip: Use the lssys -o command to list all system IDs.
system_name
The name of the system. If the system name contains a comma, prefix the comma with a backslash (\).
Tips:
  • The system names might not be unique. This command acts on all systems with the specified name. Use the -v | --verbose option to generate a message when this command targets multiple systems with the same name. To target a particular system that has a name that is not unique, identify the system by specifying its unique, hexadecimal ID, or use additional target options to refine the selection.
  • Use the lssys command without any options to list all system names.
  • The system names are not locale specific.
-O | --fanout
Specifies a maximum number of target systems on which to run the command in parallel. Serial execution can be specified by indicating a fanout value of 1. If --fanout is not specified, a default value of 16 is used.
-o | --output
Copies the standard output to output_path/target_name.output and the standard error to output_path/target_name.error. Output continues to be sent to the standard output and standard error. Use the -Q flag to suppress standard output and standard error. When used together with the --report-name option, the output is placed into the directory specified by --report-name.
Note: The dsh command sends the dsh request to the server. The output files and folders are then created by a daemon thread within the IBM Flex System Manager Java™ process. Thus, the UID of the IBM Flex System Manager Java process (generally the root) is the owner of the output files and folders created by this option.
-Q | --silent
Specifies silent mode. No remote command output is written to standard output or standard error.
-r | --report
Enables report generation and specifies the path to the directory where reports are saved.
-S | --syntax csh | ksh
Specifies the shell syntax to be used. The default flag is ksh.
-v | --verbose
Writes verbose messages to standard output.

If this option is not specified, this command suppresses noncritical messages.

-V | --version
Display DSH command version information.
-z | --exit-status
Displays exit status of the last remotely run command on each managed system. If the command issued on the remote system is run in the background, the exit status is not displayed.
command_list "command[;command;…]"
Specifies a list of commands to execute on the remote managed system. Quotation marks around the command are required to ensure that all commands in the list are executed remotely and that any special characters are interpreted correctly on the remote managed system.

Exit status

The smcli dsh command exit code is 0 if the command runs without errors and all remote shell commands finished with exit codes of 0. If internal smcli dsh errors occur or if the remote shell commands do not complete successfully, the smcli dsh command exit value is greater than 0. The following codes are returned by this command.
  • 0: The operation completed.
  • 1: A usage error occurred.
  • 2: The command or bundle was not found.
  • 3: The command was not performed because either authentication failed or you are not authorized to perform the action.
  • 200: The command execution failed. The exit value is increased by 1 for each successive instance of an unsuccessful remote command instance or target that is not valid.

Examples

  1. Run a command on managed systems

    This example illustrates how to run the date command on managed systems Node1 and Node2.

    smcli dsh –n Node1DisplayName,Node2DisplayName "date"
  2. Display users on all systems in a group

    This example illustrates how to display the number of users on all managed systems in the "All Operating Systems" group.

    smcli dsh –N "All Operating Systems" "who | wc –l"
Related reference:
smcli - Systems management command-line interface
How to read syntax diagrams
Alphabetical listing of all smcli commands