Creating SSH actions

You can create an action of type script by using the SSH provider. The Operating System of the endpoint system can be either UNIX (including AIX® and Linux®) or Windows. For UNIX, the SSH provider executes a script using the default shell. Alternatively, a shebang (#!) can be used to execute the script in any scripting language the target system can interpret. The SSH provider does not require an additional agent as it uses a direct remote execution connection through SSH.

For Windows, the SSH provider can execute a Powershell script.

Note:

  • To access the system through SSH you must set up an SSH server on the Windows system, for example OpenSSH for Windows Server 2019 or Windows 10. The Windows System must have Powershell installed as the default shell of the SSH server.
  • If you are using a jumpserver, the jumpserver must be a Linux system. You cannot use a Windows system as a jumpserver.

Complete the following steps to enable script actions:

  1. Create an SSH integration. For more information about how to set up an integration, see Configuring Integrations.

  2. Create an action of type SSH. Click Actions > Create action. Complete the following fields:

    • Type:

      Select SSH. If you want to run a script as an action, you must configure an SSH Action Provider on the Integrations page.

    • Name:

      Provide a name that describes what this action does. For example, the name can be Find large file systems.

    • Prerequisites:

      If this action requires prerequisites, add this information. For example, Db2 10.5 or higher.

    • Description:

      Provide any helpful additional information so that the user can immediately understand which problem this action solves.

    • Tags:

      Provide tags to filter actions. You can select any existing tags from the drop-down list and click the plus icon "+" to add them. To create a new tag, type the text into the field, select the text string displayed, and click the plus icon "+".

    • Shell:

      Select Bash for scripts that run on UNIX systems using bash as the ssh shell. Within the script you can specify other script interpreters that are installed on the target system, for example python. See the item "Script" below for an example.

      • Notes about how Runbook Automation invokes Bash scripts:
        • It generates a temporary file with the script content.
        • It exports parameters as environment variables.
        • It runs the temporary script file.
        • It deletes the temporary script file.
        • It returns the script return code of the temporary script execution.

      Select Powershell for scripts that run on Windows systems using powershell as the ssh shell (using cmd as the ssh shell is not supported).

      • Notes about how Runbook Automation invokes Powershell scripts:
        • It assigns parameter values to variables with the selected type.
        • It executes the commands from the script.

    • Script:

      You can either select Import to select the script from your file system, or you can directly enter the script into the editor. If you selected Bash the script can only be run on UNIX systems using the default shell or the interpreter, which is specified after the shebang #!. If you selected Powershell the script can only be run on Windows systems using Powershell.

      Notes:

      • Imported scripts must be in UTF-8 format if they contain non-ascii characters (for example, Chinese).
      • If the "Bash" shell type is selected, then any Windows line endings from the imported script are automatically converted to UNIX line endings.

      Examples:

      1. Create an SSH action with the following Bash script that uses the python interpreter:

        #!/usr/bin/env python3
import os
import platform
print("Your message \'" + os.environ.get("message") + "\' is presented by python version " + platform.python_version())

        Create a parameter message and assign the default value Hello python to the parameter. Run the script on a target system where python3 is installed. The output looks similar to the following output:

        Your message 'Hello python' is presented by python version 3.9.13

      2. Create an SSH action with the following Bash script that uses the IBM WebSphere Application Server CLI to start, stop, or get the server status of the server:

        $profilePath/bin/$serverAction.sh $serverName

        Create the parameters:

        • profilePath (the path name of the WAS profile, set the type to a single string, example default value: /opt/IBM/JazzSM/profile)
        • serverAction (the action to take on the WAS server, set the type to an enumeration of strings (serverStatus, startServer, stopServer), example default value: serverStatus)
        • serverName (the name of the WAS server, set the type to a single string, example default value: server1).

        Run the script on a target system where IBM WebSphere Application Server is installed and has administrative credentials configured in $profilePath/properties/soap.client.props. Alternatively, add parameters for the administrative user name and password and modify the CLI command accordingly.

    • Action output:

      • Filter action output By default, all action output gets collected and printed to the action output field. If you are only interested in a subset of the action output (for example, because you want to create a chain of two actions within a runbook, where some particular information from the first action is used as input to the second action, then you can enable the Filter action output toggle and specify a pattern that controls which part of the action output gets returned.
      • Choose query syntax Depending on the type of output that gets created you can choose between three types of pattern-matching engines and their respective syntax:
        • XPath: best suited for parsing XML data
        • JSONPath: best suited for parsing JSON data
        • Regular expression: best suited for parsing unstructured data
      • Choose query syntax at runtime Select this checkbox if you want to allow the query syntax to be chosen when testing the automation, and also within the parent runbook. This checkbox is typically disabled. If this checkbox is enabled, the system property filter-syntax is added to the action.
      • Enter query pattern Enter a pattern that is supported by the selected query syntax. For example, if the JSON output object is expected to contain an attribute called "version" and you selected the "JSONPath" query syntax, then you can use the query pattern "$.version" to pick the value of the version attribute out of the overall JSON output.
      • Enter query pattern at runtime Select this checkbox if you want to allow the query pattern to be chosen when testing the automation, and also within the parent runbook. If this checkbox is enabled, the system property filter-query is added to the action.
      • Test output filter Click this link (or the Test button in the actions menu) when you are ready to test the action. This saves the action and directly opens the Test action page for the current action. For many developers, working with query patterns is an iterative process. Therefore it is recommended to enable Enter query pattern at runtime at least while you are developing the action, and switch to Test action to fine-tune the query pattern. The development of the query pattern is also supported within the Test action page itself, where you can toggle between Show filtered output and Show unfiltered output after you have run the action. You can also toggle between Edit action and Test action until you are satisfied with the result.

    • Parameters:

      Add input parameters to run the action script. Those input parameters are available to the script as environment variables. For example, a parameter filesystem is used in a Linux script as $filesystem. The $ sign is automatically added to distinguish user-defined parameters from system parameters such as target and user. The parameter is exported without the dollar sign. Note: input parameter names must consist of alphanumeric characters and the underscore character only. System parameters are not available for use within your own script code. If you want to use some of that data within your script code, you must create related user-defined parameters. The following system parameters exist:

      • target: Mandatory parameter. Applies to actions of type Script. The target parameter is created to define the target machine where the script is running. By default, it is assumed that the SSH server on the target machine is listening on port 22. If a different SSH port is used, then set the value for the target parameter to hostname:port, for example, mytarget.mycompany.com:2022.

      • user: Mandatory parameter. Applies to actions of type SSH. The user parameter defines the UNIX or Windows username that is used to run the script on the target machine.

      • filter-syntax, filter-query: These system parameters are added if you enable the related checkboxes for action output parsing.

        Note: If the value of the user parameter contains the @ symbol, for example an email address, the @ symbol and all characters that follow it are ignored.

  3. Add the action to the runbook, see Adding actions.

  4. Run the runbook, see Run your first runbook.

For more information about SSH actions, see the following topics: