runtask command

Use the runtask command to run a non-interactive IBM® Flex System Manager task on a specific system.

Synopsis

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

smcli runtask [-h | -? | --help]

smcli runtask [-v] [-t system_type] [-W seconds] {-a | -f file_name | -w query | -i ip_address_list | -N group_list | [-n] system_list} noninteractive_task

Description

None.

Operands

This command uses a noninteractive task title, ID or string ID as an operand.
task_oid
The unique ID of the task, specified as a hexadecimal value prefixed with 0x (for example, 0x37).
Tip: You can use the lstask -o -r command to list all task IDs that are valid for the targeted system.
task_id_string
The unique ID string of the task, prefixed with a percent sign (%) (for example, %ServerCfgTask). If the string ID contains a comma, prefix the comma with a backslash (\).
Tip: You can use the lstask -I command to list all task ID strings that are valid for the targeted system.
task_title
The title of the task. The task title must be fully qualified with the parent task (for example, grandparent_task_title/parent_task_title/task_title). If the task name contains a comma, prefix the comma with a backslash (\). Enclose the task title in quotation marks if it contains a space character.
Tips:
  • Task names might not be unique. This command acts on all tasks with the specified name. Use the -v | --verbose option to generate a message when this command targets multiple tasks with the same name. To target a task that has a name that is not unique, identify the task by specifying its unique, hexadecimal task ID, or use additional target options to refine the selection.
  • Locale-specific task names might not exist for every noninteractive task. The name specified must match the locale being used by the command line interface.
  • Use the lstask -r command to list all tasks that are valid for the targeted system.
Tip:
  • This option cannot be used with the -s | --task option.
  • An error is displayed if the specified task is not a noninteractive task.

Options

-a | --all
Targets all systems.
-f | --file {file_name | -}
Retrieves data either from the input file file_name or from input piped from another command.

To retrieve input piped from another command, specify a hyphen (-) instead of a file name (for example, smcli cmd1 | smcli cmd2 -f -). To retrieve input from a file, specify the full path. If the path contains spaces, enclose it in quotation marks.

The input data is the list of noninteractive tasks. This list can be a mixture of task titles, IDs, and string IDs, separated by a comma and delimited by an end-of-line character.
-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 noninteractive targets that can be run on the specified systems, identified 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.
-n | --names {system_oid | system_name}[,{system_oid | system_name}...]
Targets one or more noninteractive tasks that run on the specified systems, identified by name or ID. The list can be a mixture of system names and IDs, separated by a comma.
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.
-N | --groups {group_oid | group_name}[,{group_oid | group_name}...]
Targets one or more noninteractive tasks that run on the specified groups, identified by name or ID. The list can be a mixture of group names and IDs, separated by a comma.

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

group_oid
The unique ID of the group, specified as a hexadecimal value prefixed with 0x (for example, 0x3e7).
Tip: Use the lsgp -o command to list all group IDs.
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.
-t | --type system_type

Narrows the specified targeted systems to all systems of the specified type.

The system types are organized in a hierarchy in which child subtypes extend parent types. When you specify a parent type (for example, Platforms), its children (in this case, PhysicalPlatforms) are also targeted.

Tips:
  • This options is not a targeting option by itself. It must be used with another targeting option, such as -n | --names or -i | --ipaddress.
  • You can use this option in conjunction with other targeting options; however, this targeting option acts before all other targeting options.
  • Use the lssys -T command to obtain a list of valid system types.
  • The system types are not locale specific.
-v | --verbose
Writes verbose messages to standard output.

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

-W | --wait seconds

Displays the results of the command after waiting the specified number of seconds, regardless of whether or not the task has been completed.

Possible values for seconds are:
  • -1: Waits indefinitely for the task to finish before exiting and displaying the results. This value is the default if this option is not specified.
  • 0: Exits immediately, and the task continues to run in the background. Use the lsjob or lsjobhistory command to check the status.
  • 1 or greater: Exits after the specified number of seconds. If the task is completed before the specified wait period, this command displays the results. If the task is not completed before the specified wait period, the command exits and the task continues to run in the background. Use the lsjob or lsjobhistory command to check the status.

Exit status

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.
  • 10: The file was not found.
  • 20: A specified system is not valid.
  • 21: A specified system group is not valid.
  • 25: A number-formatting error occurred.
  • 26: A specified system type is not valid.
  • 27: A specified attribute is not valid.
  • 29: The specified locale is not valid or not supported.
  • 50: The specified task or subtask is not valid.
  • 51: The task name or ID is not unique or valid.
  • 52: The task or subtask is interactive.
  • 53: The task ID was not found.
  • 54: The task failed to start.
  • 126: The task did not complete before the specified wait time. The command is still running in the background.
  • 127: The command timed out.

Examples

  1. Run a task on a system using the task ID string

    This example illustrates how to run a non-interactive task with ID string bluelight_ON on the system named websvr.

    smcli runtask -n websvr %bluelight_ON
  2. Collect inventory on multiple groups

    This example illustrates how to run the collect-inventory task on systems that are members of the payrollgroup and financegroup groups.

    smcli runtask -N payrollgroup, financegroup "Inventory/Collect Inventory"
  3. Shut down a system

    This example illustrates how to gracefully quiesce all running processes and then shut down the operating system on systems that are members of the mychassis group.

    smcli runtask -N mychassis "shutdown"
  4. Turn power off for a system

    This example illustrates how to gracefully quiesce all running processes, shut down the operating system, and then power off the system named system1.

    smcli runtask -n system1 "power off"
  5. Turn power off for all virtual servers

    This example illustrates how to gracefully quiesce all running processes, shut down the operating system, and then power off all virtual servers.

    smcli runtask -a "power off"
  6. Turn power on for a system

    This example illustrates how to power on a system named system1.

    smcli runtask -n system1 "power on"
  7. Restart a system

    This example illustrates how to restart a system named system1.

    smcli runtask -n system1 "restart"
  8. Turn on the LED on a system

    This example illustrates how to cause the LED to start blinking on a System x server named systemx_1.

    smcli runtask -n systemx_1 %BlueLight_BLINK
  9. Turn off the LED on a system

    This example illustrates how to cause the LED to stop blinking on a System x server named systemx_1.

    smcli runtask -n systemx_1 %BlueLight_OFF
Related reference:
smcli - Systems management command-line interface
How to read syntax diagrams
Alphabetical listing of all smcli commands