Install Splunk Automation Broker on a Docker host

Perform these steps in combination with the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator if you are not the Splunk SOAR administrator.

1. Install the Splunk SOAR Automation Broker container.
2. Register the Splunk SOAR Automation Broker with Splunk SOAR (Cloud) or Splunk SOAR (On-premises).
3. Verify that setup and registration are complete.
4. Start the Splunk SOAR Automation Broker and verify that the connection is active.

If you get an error such as mkdir: cannot create directory '/splunk_data/broker': Permission denied, verify that the logged-in user has permissions to write to the mounted directory on the host machine. See the manual page for the chmod *nix system utility, man chmod for more information about changing directory permissions.

Before you can install the Splunk SOAR Automation Broker container on your host, you must install and configure Docker and Docker Compose. See Prepare to install the Splunk SOAR Automation Broker in this manual.

If your Docker host cannot use Docker Hub to retrieve container images, please follow the instructions in the topic Install Splunk Automation Broker when you cannot use DockerHub in this manual.

After you have installed Docker and Docker Compose on your Docker host, install the Splunk SOAR Automation Broker container.

Before you begin, follow these steps:

1. Log in to either your Splunk SOAR (Cloud) or Splunk SOAR (On-premises) instance.

2. From the Home menu, select Administration then Product Settings then Automation Broker (Classic). Select +Automation Broker.

Perform these steps on the Add new automation broker page. Step numbers here match the numbers on that page.

1. Perform these steps on your environment.
   1. Install and configure Docker Compose for your local environment. See the Docker website for details.
   2. On the Add new automation broker page, locate the sample configuration file. Use the icons within the text block to either download or copy the sample configuration file. Save the configuration file on your Docker hoas docker-compose.yml.

   3. Edit the docker-compose.yml file. Change environment variables as needed for your local environment. Each environment variable in the file is listed as a comment using a pound sign (#). To use an environment variable, remove the pound sign.

   4. Start the Splunk SOAR Classic Automation Broker by using the command docker compose up -d.

2. Copy the docker-compose.yml file to your Docker host.
3. On your Docker host, create a directory for the Splunk SOAR Automation Broker to store persistent data, such as logs and authentication tokens. The rest of this document will call that directory /splunk_data.
   mkdir <data_directory>
   • This directory must be on the Docker host's file system, not inside the container.
   • You are responsible for setting the appropriate file system permissions on this directory to prevent unauthorized access.
   • This directory must be accessible to the UID and GID of the accounts that run Automation Broker.
   CAUTION: If you intend to run multiple Splunk SOAR Automation Brokers each instance of Automation Broker requires its own data directory. Do not share data directories between Automation Brokers.
4. Edit the docker-compose.yml file to set environment variables as needed. Environment variables are in the environment section. Each environment variable in the file is listed as a comment using a pound sign ( # ). To use an environment variable, remove the pound sign.
   1. Set the PHANTOM_BASE_URL.
   2. Set the path to the data directory on the Docker host's file system that you created earlier:
      - </path/to/splunk_data>:/splunk_data
   3. (Conditional) if you want to change the user that runs the automation broker, specify the UID and GUID of the user account that will run the automation broker on the PUID= and PGID= entires.
   4. (Conditional) If you need to use an HTTP proxy server for outgoing HTTP traffic, set the https_proxy=http environment variable.
   5. (Conditional) If you need to use an HTTPS proxy server for outgoing HTTPS traffic, set the https_proxy=https environment variable.
   Note: Both the https_proxy and http_proxy environment variables are case sensitive and must use all lowercase letters. Any special characters for proxy settings must be url-encoded.
5. Launch the Splunk SOAR Automation Broker container.
   docker compose up -d
   For older releases of Docker, you may need to use the command docker-compose up -d.
6. As a user with docker permissions, use the docker logs command to see the startup output of the Splunk SOAR Automation Broker, including the encryption key.
   CODECopy

   docker logs <container ID>

   docker logs <container ID>

7. Copy the key and provide it to the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator.
   CODECopy

   ******************************************** Automation Broker Encryption Key: ENCRYPTIONKEYISVISIBLEHERE ********************************************

   ********************************************
   Automation Broker Encryption Key:
   ENCRYPTIONKEYISVISIBLEHERE
   ********************************************

8. The log output also contains a Splunk SOAR Authorization Code. Copy the code and provide it to the Splunk SOAR (Cloud) or Splunk SOAR (On-premises) administrator.
   CODECopy

   **************************************************************************************** Splunk SOAR Authorization Code: AUTOGENERATEDCODEISVISIBLEHERE Please provide this code to your Splunk SOAR administrator to continue setup. ****************************************************************************************

   ****************************************************************************************
   Splunk SOAR Authorization Code:
        AUTOGENERATEDCODEISVISIBLEHERE
   Please provide this code to your Splunk SOAR administrator to continue setup.
   ****************************************************************************************

   Note: The authorization code expires after 15 minutes.
9. (Conditional) If your authorization code expires before you can use it to authorize your Splunk SOAR Automation Broker, as a user with docker permissions, do the following steps:
   1. Get the name of your running automation broker by listing running containers.
      docker ps
   2. Stop the Splunk SOAR Automation Broker container.
      docker stop <container_name>
   3. Launch a new container.
      docker compose up -d
      For older versions of docker, you may need to use the command docker-compose up -d.

The Splunk SOAR administrator performs these steps.

Before you begin, follow these steps:

1. Log in to Splunk SOAR (Cloud) or Splunk SOAR (On-premises).
2. In Splunk SOAR, click Home then Administration, then navigate to Product Settings and select Automation Broker (Classic).
3. Select + Automation Broker.

Continue with the steps on the Add new automation broker page.

1. Paste the encryption key from your Automation Broker in the Enter encryption key obtained from the Automation Broker field to encrypt the credentials used in the connection to the Splunk SOAR Automation Broker.
2. Take the Splunk SOAR Authorization Code provided by the broker during installation and add it in the Enter authorization code obtained from the Automation Broker field. If you do not have this code, obtain it from the administrator who installed the broker.
3. Enter a unique name for the Splunk SOAR Classic Automation Broker to help you identify it. Each Classic Automation Broker must have its own, unique name.
4. Select Complete to save the configuration.

Confirm successful setup and registration with Splunk SOAR (Cloud) or Splunk SOAR (On-premises).

1. Use the Docker logs command to see the log output for the Splunk SOAR Automation Broker container:
   CODECopy

   docker logs <container ID>

   docker logs <container ID>

2. Confirm that a message like the following appears:
   CODECopy

   Waiting for Splunk SOAR registration......................Successfully paired broker. Automation Broker pairing succeeded.

   Waiting for Splunk SOAR registration......................Successfully paired broker.
   Automation Broker pairing succeeded.

Confirm that the connection between Splunk SOAR (Cloud) or Splunk SOAR (On-premises) and the Splunk SOAR Automation Broker works.

After installing the Splunk SOAR Automation Broker, confirm that the connection is active.

1. In Splunk SOAR, select Home and navigate to Administration then Product Settings then select Automation Broker (Classic).
2. Locate the Splunk SOAR Automation Broker configuration that you added and confirm that the broker status is Active.