{"componentChunkName":"component---src-templates-default-template-tsx","path":"/documentation/integration/Standard_ActionHandlers/AHconfig/","result":{"data":{"asciidoc":{"id":"610b442c-3856-5636-aa3a-e12847e3b024","html":"
\n
Table of Contents
\n\n
\n
\n

Introduction

\n
\n
\n

ActionHandlers are integration components of the HIRO system. They are used to\ninvoke actions on target systems. The ActionHandler establishes a websocket\nconnection with the HIRO Action-API.\nAn ActionHandler can be deployed either on our SaaS platform or can be hosted on\na machine in your network. The latter has the advantage of not needing to open\ninbound ports on firewall. This document is for our customers who choose the latter.

\n
\n
\n

The installation requires three steps:

\n
\n
\n
    \n
  • \n

    Setting up docker

    \n
    • \n
  • \n

    Defining docker composition (docker-compose.yml)

    \n
    • \n
  • \n

    Starting the ActionHandler container

    \n
    • \n
\n
\n
\n
\n
\n

Setting up docker

\n
\n
\n

The HIRO standard Action Handlers (SSH and HTTP) are provided using a docker image.\nThis image must be mounted in a maschine in your network running docker.\nFor general information on docker, please refer to the help pages on\nDockerHub. We assume you’ve installed docker and docker-compose.\nYou can verify by checking the versions:

\n
\n
\n
\n
$ docker -v\nDocker version xx.xx.xx, build xxxxxxxxxx\n$ docker-compose -v\ndocker-compose version x.xx.x, build xxxxxxxx
\n
\n
\n
\n

Linux based container images

\n
\n

All arago docker images are Linux based. The Docker image is published on our DockerHub repository. Please ensure that your docker installation can run linux based images.\nYou can confirm by pulling the latest image and check for error messages.

\n
\n
\n
\n
docker pull almatoai/hiro-actionhandler:latest
\n
\n
\n
\n

In case you are presented with an error message about Linux images not usable on your platform, please refer to the DockerHub help pages and adjust your installation.

\n
\n
\n
\n
\n
\n

Defining docker composition (docker-compose.yml)

\n
\n
\n

The docker composition defines which image and how the container is started. It is defined in a configuration file in YAML format and holds the information about for your docker image, the HIRO instance and the type of actions you seek to execute.

\n
\n
\n
Sample docker-compose.yml
\n
\n
version: \"3.7\"\nservices:\n  actionhandler:\n    image: almatoai/hiro-actionhandler:latest # Please update version number to the most recent tagged version\n    container_name: actionhandler\n    env_file: ~/[path to your environment file]/config.env\n    restart: always\n    volumes: #required for SSH only\n      - type: bind\n        source: [absolute path]/[private key file]\n        target: /home/hiro/.ssh/id_rsa\n    environment:\n      USE_DEFAULT_AH_CONFIGS: ExecuteCommand,HTTPRequest\n      AH_CONFIG: >\n        {}
\n
\n
\n
\n

The next sections walk you through the required adjustments: We will pass an environment variable file with HIRO credentials, mount the SSH private key and pass environment (when required) and define the Action Handler configuration map.

\n
\n
\n

Creating environment variable file (config.env)

\n
\n

You need to create an ActionHandler environment variable file for the docker image, typically named config.env. This file holds the credentials for your HIRO instance.

\n
\n
\n
Sample config.env
\n
\n
HIRO_USER=XXXXXXX\nHIRO_PASS=XXXXXXX\nHIRO_EXTERNAL_USER=XXXXXXX\nHIRO_EXTERNAL_PASS=XXXXXXX
\n
\n
\n
\n

Each ActionHandler should have a dedicated service user account for the respective HaaS instance.\nIn case you do not have the credentials ready, please login to the arago account management application Almato ID,\nnavigate to Member tab and search for users named 'actionhandler'.

\n
\n
\n
\n\"Search\n
\n
\n
\n

If a dedicated ActionHandler user does not exist for your haas-instance yet, please contact\nyour organization admin. Make a note of the username and password and enter them in the environment variable file for HIRO_USER and HIRO_PASS. You can change the password by clicking the\noptions icon and select Edit Profile. In case of questions, you can also contact the HIRO Support.

\n
\n
\n

The HIRO_EXTERNAL_USER and HIRO_EXTERNAL_PASS environment variables are optional if the \"supply_token\" functionality is required and the token passed to the actual handler should use a different user account than the ActionHandler itself.

\n
\n
\n
\n

Mounting RSA private key (for SSH only)

\n
\n

If you want to invoke SSH commands using the ActionHandler, you need to mount an RSA private key into the container and exchange the public key with the target system.\nThe key needs to be in pkcs8 format and should not have a passphrase. You can generate a new key pair with the following command:

\n
\n
\n
\n
ssh-keygen -m pkcs8
\n
\n
\n
\n

Save the key pair to the server running docker and set the source attributes in the docker composition to the location of the private key- and cert-file. Make sure the files are readable for the ActionHandler (by default, the ActionHandler is run as user hiro with id 1000).\nDo not forget to add the content of the generated public key into ~/.ssh/authorized_keys on your the target system.

\n
\n
\n

Please note: From a container perspective, even the local host is a remote target system, so you should be following the same steps. However, you might find some shortcuts in the DockerHub help pages for network configuration.

\n
\n
\n
\n

Action Handler configuration map (AH_CONFIG)

\n
\n

Your connector needs a configuration of which actions or capabilities to\nprocess and how to execute them. This is configured in a configuration variable\ncalled AH_CONFIG.

\n
\n
\n

Please refer to How to configure capabilities in the standard Action Handler (Docker image)\nfor details on the configuration map.

\n
\n
\n
\n
\n
\n

Starting the ActionHandler container

\n
\n
\n

Once the composition is defined, you can start the ActionHandler docker container by issuing the following command:

\n
\n
\n
\n
docker-compose up
\n
\n
\n
\n

Please make sure you are issuing this command from the same directory your docker-compose.yml file is located in. Upon sucess, you should see the following log entries:

\n
\n
\n
Sample log entris after successfull composition
\n
\n
[...]\nCreating network \"docker_default\" with the default driver\nCreating actionhandler ... done\nAttaching to actionhandler\nactionhandler_1  | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"Loaded configuration for capabilities: [\\\"HTTPRequest\\\"]\",\"metadata\":{}}\n[...]\nactionhandler    | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"Authenticating...\",\"metadata\":{}}\nactionhandler    | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"Successfully authenticated.\",\"metadata\":{}}\n[...]\nactionhandler    | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"Connected to core.almato.ai using http\",\"metadata\":{}}\nactionhandler    | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"Upgrading connection...\",\"metadata\":{}}\nactionhandler    | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"WebSocket upgrade succeeded.\",\"metadata\":{}}\nactionhandler    | {\"time\":\"...\",\"severity\":\"info\",\"message\":\"[ActionHandler] New ActionWS status: :ready\",\"metadata\":{}}\n[...]
\n
\n
\n
\n

In case of generic docker problems, please refer to the DockerHub help pages. On problems related to the ActionHandler docker image, please contact HIRO Support.

\n
\n
\n

The command above composes a docker container attached to your current console. In other words: If you close the console, the container will be terminated. To compose a detached container, please issue the following command:

\n
\n
\n
\n
docker-compose up --detach
\n
\n
\n
\n

More information on attached and detached containers and their lifespan can be found on the DockerHub help pages.

\n
\n
\n

Sample KIs for testing

\n
\n

You can test your ActionHandler by executing the follow KIs from HIRO™:

\n
\n
\n
Sample KI for a HTTP request
\n
\n
on\n  ogit/_id\nwhen\n  ProcessIssue == \"TestHTTPRequest\"\ndo\n  code: LOCAL::STATUS,\n  body: LOCAL::RESULT = action(\n\tcapability: \"HTTPRequest\",\n\tparams: \"format=json\",\n\turl: \"https://api64.ipify.org/\",\n\ttimeout: \"10\"\n  )\n  if LOCAL::STATUS == \"200\" then\n    log(\"SUCCESS: Your IP adress is ${LOCAL::RESULT}\")\n  else\n    log(\"ERROR ${LOCAL::STATUS}: ${LOCAL::RESULT}\")\n  end\n  delete(ProcessIssue)
\n
\n
\n
\n
Expected HIRO Engine log
\n
\n
action action executed: GET https://api64.ipify.org/?format=json\ninfo\naction arguments: {\"Arguments\":{\"params\":\"format=json\",\"timeout\":\"10\",\"url\":\"https://api64.ipify.org/\"},\"Capability\":\"HTTPRequest\"}, results: {\"body\":\"{\\\"ip\\\":\\\"52.30.30.78\\\"}\",\"code\":200,\"exec\":\"GET https://api64.ipify.org/?format=json \",\"headers\":\"{\\\"Connection\\\":\\\"keep-alive\\\",\\\"Content-Length\\\":\\\"20\\\",\\\"Content-Type\\\":\\\"application/json\\\",\\\"Date\\\":\\\"Mon, 04 Oct 2021 12:41:42 GMT\\\",\\\"Server\\\":\\\"nginx/1.19.7\\\",\\\"Vary\\\":\\\"Origin\\\"}\"}\ndebug\nlog SUCCESS: Your IP adress is xxx.xxx.xxx.xxx\ninfo
\n
\n
\n
\n
Sample KI for a SSH command
\n
\n
on\n  ogit/_id\nwhen\n  ProcessIssue == \"TestSSH\"\ndo\n  stdout: LOCAL::OUTPUT,\n  stderr: LOCAL::ERROR,\n  exit: LOCAL::SYSTEMRC = action(\"ExecuteCommand\", command: \"echo Hello World\", host: \"{ip of your target system}\", user: \"{user for your target system}\", timeout: \"20\")\n  if LOCAL::SYSTEMRC == \"0\" then\n    log(\"SUCCESS: ${LOCAL::OUTPUT}\")\n  else\n    log(\"ERROR ${LOCAL::SYSTEMRC}: ${LOCAL::ERROR}\")\n  end\n  delete(ProcessIssue)
\n
\n
\n
\n
\n
","document":{"main":"On-premise Action Handler Installation Guide","title":"On-premise Action Handler Installation Guide","subtitle":""},"fields":{"toc":true,"location":["documentation","integration","Standard_ActionHandlers","AHconfig"]}},"sidebarYaml":{"id":"6d066bdd-c982-5a69-b909-a31e6fc044e0","showIndex":null}},"pageContext":{"id":"610b442c-3856-5636-aa3a-e12847e3b024","parent":"documentation"}},"staticQueryHashes":["1010459453","1010459453","2356112386","2356112386","2603905930","2603905930","3026652197","3026652197","3167850324","3167850324","63159454","63159454"]}