community.sap_libs.sap_hostctrl_exec module – Ansible Module to execute SAPHostControl

Note

This module is part of the community.sap_libs collection (version 1.6.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.sap_libs.

To use it in a playbook, specify: community.sap_libs.sap_hostctrl_exec.

New in community.sap_libs 1.6.0

Synopsis

Parameters

Parameter

Comments

force

boolean

Forces the execution of the function Stop.

Choices:

  • false ← (default)

  • true

function

string / required

The function to execute.

Choices:

  • "ACOSPrepare"

  • "AttachDatabase"

  • "CallServiceOperation"

  • "CancelOperation"

  • "ConfigureOutsideDiscovery"

  • "ConfigureOutsideDiscoveryDestination"

  • "ConfigureOutsideDiscoveryPath"

  • "DeployConfiguration"

  • "DeployManagedObjectsFromSAR"

  • "DetachDatabase"

  • "DetectManagedObjects"

  • "ExecuteDatabaseOperation"

  • "ExecuteInstallationProcedure"

  • "ExecuteOperation"

  • "ExecuteOutsideDiscovery"

  • "ExecuteUpgradeProcedure"

  • "FinalizeDatabaseCopy"

  • "GetCIMObject"

  • "GetComputerSystem"

  • "GetDatabaseProperties"

  • "GetDatabaseStatus"

  • "GetDatabaseSystemStatus"

  • "GetIpAddressProperties"

  • "GetOperationResults"

  • "ListDatabases"

  • "ListDatabaseSystems"

  • "ListInstances"

  • "LiveDatabaseUpdate"

  • "PrepareDatabaseCopy"

  • "RegisterInstanceService"

  • "SetDatabaseProperty"

  • "StartDatabase"

  • "StartInstance"

  • "StopDatabase"

  • "StopInstance"

  • "UnregisterInstanceService"

hostname

string

The hostname to connect to the sapstartsrv.

Could be an IP address, FQDN or hostname.

Default: "localhost"

parameters

dictionary

A dictionary containing all the parameters to pass to the function.

This option is mandatory for most of the functions, only a few like ListInstances or ListDatabases can be run without option.

Be careful, no validation is done by this module regarding the suboptions.

An analysis of the WSDL file must be done to provide correct parameters.

See also the examples section for more appreciation.

password

string

The password to connect to the sapstartsrv.

port

integer

The port number of the sapstartsrv (usually 1128 and 1129).

If provided, the module will use always use http connection instead of local socket.

username

string

The username to connect to the sapstartsrv.

Notes

Note

  • Does not support check_mode.

Examples

- name: ListDatabases with custom host and port
  community.sap_libs.sap_hostctrl_exec:
    hostname: 192.168.8.15
    function: ListDatabases
    port: 1128

- name: ListInstances using local Unix socket (requires become)
  community.sap_libs.sap_hostctrl_exec:
    function: ListInstances
  become: true

- name: ListInstances using local Unix socket as SAP admin user and selector parameters
  community.sap_libs.sap_hostctrl_exec:
    function: ListInstances
    parameters:
      aSelector:
        aInstanceStatus: S-INSTALLED # S-INSTALLED | S_RUNNING | S-STOPPED | S-LAST
  become: true
  become_user: "{{ sap_sid | lower }}adm"

- name: StartInstance with authentication
  community.sap_libs.sap_hostctrl_exec:
    hostname: 192.168.8.15
    username: tstadm
    password: test1234
    function: StartInstance
    parameters:
      aInstance:
        mSid: 'TST'
        mSystemNumber: '01'
      aOptions:
        mTimeout: -1 # -1=synchronous, 0=async, >0=wait timeout in seconds
        mSoftTimeout: 0
        mOptions:
          - O-INSTANCE

- name: Synchronous StartDatabase using local Unix socket with arguments
  community.sap_libs.sap_hostctrl_exec:
    function: StartDatabase
    parameters:
      aArguments:
        item: "{{ dict_arguments | dict2items(key_name='mKey', value_name='mValue') }}"
      aOptions:
        mTimeout: -1
  vars:
    dict_arguments:
      Database/Name: SYSTEMDB@XDH
      Database/Type: hdb # hdb|ora|mss|db6|ada|sap|syb|ase|db2|max
      # Database/InstanceName: HDB00 # the following parameters are optional
      # Database/Host: mydbhost.example.com
      # Database/Username: SYSTEM
      # Database/Password: StarWarsFTW123!
  become: true

- name: Example of GetDatabaseStatus
  community.sap_libs.sap_hostctrl_exec:
    function: GetDatabaseStatus
    parameters:
      aArguments:
        item: "{{ dict_arguments | dict2items(key_name='mKey', value_name='mValue') }}"
  vars:
    dict_arguments:
      Database/Name: XDH
      Database/Type: hdb
  become: true

# Example from https://help.sap.com/docs/host-agent/saphostcontrol-web-service-interface/executeoperation
- name: Asynchronous ExecuteOperation
  community.sap_libs.sap_hostctrl_exec:
    function: ExecuteOperation
    parameters:
      aOperation: "sayhello"
      aArguments:
        item:
          mKey: "MY_NAME"
          mValue: "Sally"
  register: operation_say_hello
  become: true

- name: Check results of previous ExecuteOperation
  community.sap_libs.sap_hostctrl_exec:
    function: GetOperationResults
    parameters:
      aOperationID: "{{ operation_say_hello.out[0].mOperationID }}"
      aOptions:
        mTimeout: -1
  become: true

# Output of GetOperationResults for the above ExecuteOperation :
#
# changed: true
# error: ""
# msg: Succesful execution of: GetOperationResults
# out:
#   - mOperationID: "42010A3F050B1FD0B5A26EF66B9FA7B7"
#     mOperationResults:
#       item:
#         - mMessageKey: description
#           mMessageValue: Say hello
#         - mMessageKey: null
#           mMessageValue: "\"hello Sally\""
#         - mMessageKey: exitcode
#           mMessageValue: 0

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

msg

string

Success-message with functionname.

Returned: always

Sample: "Succesful execution of: ListInstances"

out

list / elements=dictionary

The full output of the required function.

Returned: always

Sample: [{"item": [{"mHostname": "test-vm-001", "mSapVersionInfo": "793, patch 200, commit ec1833e294d84a70c04c6a1b01fd1a493f5c72fb", "mSid": "TST", "mSystemNumber": "01"}, {"mHostname": "test-vm-001", "mSapVersionInfo": "793, patch 200, commit ec1833e294d84a70c04c6a1b01fd1a493f5c72fb", "mSid": "TST", "mSystemNumber": "00"}]}]

Authors

  • Rainer Leber (@RainerLeber)

  • Robert Kraemer (@rkpobe)

  • Yannick Douvry (@ydouvry)