Deploying FortiSOAR on a Docker Platform

You can deploy FortiSOAR on Docker platforms such as VMware ESX or AWS. This allows you to easily provision FortiSOAR into your microservice's architecture and use it as cloud-native and DevOp-enabled.

You can also deploy the FortiSOAR Docker on Amazon Elastic Kubernetes (EKS) cluster, in the Amazon Web Services (AWS) Cloud. For more information, see the Deploying FortiSOAR Docker on Amazon Elastic Kubernetes cluster chapter. For information on upgrading your FortiSOAR Docker image, see the "Upgrade Guide."

FortiSOAR also has a management extension (MEA) (Docker image) that is built with FortiAnalyzer and FortiManager. To learn more about the FortiAnalyzer MEA, see the FortiAnalyzer documentation; to learn more about the FortiManager MEA, see the FortiManager documentation.

The following topics introduce how to deploy the FortiSOAR image on Docker.

Planning

Prerequisites

To deploy the FortiSOAR image on Docker, you must have already installed Docker in your environment. If not, refer to the Docker official website for Docker installation instructions: https://docs.docker.com/.
To check whether Docker has been successfully installed, run docker version.

For resource requirement specifications, see the Deploying FortiSOAR chapter.

System Requirements

Supported Hypervisors

• Docker Engine CE 18.09.1 or higher versions, and the equivalent Docker Engine EE versions.

For best performance in hypervisor deployments, install FortiSOAR on a “bare metal” (Type 1) hypervisor. Hypervisors that are installed as applications on top of a general-purpose operating system (Windows, Mac OS X, or Linux) host have fewer computing resources available due to the host OS’s own overhead. To ensure high performance, it is recommended to deploy FortiSOAR on machine types with a minimum of 8 vCPUs and a memory size larger than 32 GB.

Downloading the FortiSOAR Docker image

You can download the required FortiSOAR Docker image from the support portal.

To download the FortiSOAR Docker image, do the following:

1. Log on to support.fortinet.com.
2. Click Support > Firmware Download.
   
3. On the Fortinet Firmware Images And Software Releases page, from the Select Product drop-down list, select FortiSOAR.
   The page contains information about released versions of FortiSOAR images, and contains two tabs: Release Notes and Downloads.
   To view the Release Notes for a particular version, click the version and build number link, which opens the FortiSOAR Document Library, from where you can view or download the release notes for that particular version.
4. To download the Docker image, do the following:
   1. Click the Download tab.
   2. Navigate through the directory structure in the format, <version number category> > <major version > > <minor version>, to open the page containing the required image. For example, to download a Docker image for version 7.4.1, click v7.00 > 7.5 > 7.5.0, and locate the required Docker image.
      
   3. Download the Docker image by clicking the HTTPS link.
      An HTTPS connection is used to download the Docker image.
   4. Click the Checksum link for the image that you have downloaded.
      The image file name and checksum code are displayed in the Get Checksum Code dialog box.
      
   5. Confirm that the checksum of the downloaded image file matches the checksum provided on the download site.

Deploying the FortiSOAR Docker image

1. Load the downloaded Docker image using the following command:
   docker load -i <image-path>
2. Download the FortiSOAR Docker installer from https://repo.fortisoar.fortinet.com/<release_version>/install-fortisoar-docker-<release_version>.bin
   For example, https://repo.fortisoar.fortinet.com/7.5.0/install-fortisoar-docker-7.5.0.bin
3. Extract the default fortisoar.env file using the following command:
   ./install-fortisoar-docker-<release_version>.bin --export-default-env
   For example, ./install-fortisoar-docker-7.5.0.bin --export-default-env
   NOTE: This command exports the fortisoar.env file to the current directory.
   
4. Update the fortisoar.env file as per your environment. For more information, see Understanding the fortisoar.env file topic.
5. Once you have updated the fortisoar.env file, run the following command:
   ./install-fortisoar-docker-<release_version>.bin --env-file fortisoar.env
   For example, ./install-fortisoar-docker-7.5.0.bin --env-file fortisoar.env
   NOTE: The fortisoar.env file is an important configuration file. Therefore, it is recommended that you take a backup of this file for future reference.
6. To connect to FortiSOAR Docker using SSH, use the following CLI:
   docker exec -it <FSR container id or name> bash

If the FortiSOAR Configuration Wizard fails when provisioning your instance, then a failure screen detailing the status of each configuration step is presented on the FortiSOAR UI, making it simpler to identify the issue. Before using FortiSOAR, you must use the CLI to fix any issues with the failed steps as their functioning might be hampered. However, if you decide to access FortiSOAR without rectifying the failed steps, a Proceed Anyway button is provided that enables you to continue using the product while acknowledging the configuration failure. If the FortiSOAR UI does not come up even after clicking Proceed Anyway, you can try to fix the issue using the steps mentioned in the Deploying FortiSOAR chapter.

Understanding the fortisoar.env file

The FortiSOAR Docker installer uses the fortisoar.env file for information for FortiSOAR container configuration. You can use the FortiSOAR installer to export the default configuration using the following command:
./install-fortisoar-docker-<release_version>.bin --export-default-env
For example, ./install-fortisoar-docker-7.5.0.bin --export-default-env

Sample fortisoar.env file:

# cat fortisoar.env
#
# Do not use space before or after of =
# You can retrieve the image id by executing the 'docker images' command
#
IMAGE_ID=1xxxxxxxxxx
PROJECT_NAME=fortisoar
HOSTNAME_DOCKER_HOST=docker-host.myorg.mydomain
HOSTNAME_CONTAINER=fsr-container.myorg.mydomain
PORT_UI=443
ENABLE_SME=true
PORT_SME=5671
EXTRA_PARAM="docker --publish docker_port/host_port:container_port"
# RAM in GB
RAM=32
CPUS=8
IP_REPO=10.1xx.2xx.1xx
HOSTNAME_REPO=fortisoar-offline.myorgdomain
IPV6=false
#

Configurable parameters of the fortisoar.env file:

• IMAGE_ID: The image ID of your FortiSOAR Docker image. You can find the image ID using docker images.
• PROJECT_NAME: The identifier for your FortiSOAR container resources. The FortiSOAR installer creates the container name as '<PROJECT_NAME>_fortisoar_1', and names all the required volumes as '<PROJECT_NAME>_fortisoar_*'.
• HOSTNAME_DOCKER_HOST: The DNS of the Docker host, which is added by default to the self-signed certificate SAN list.
• HOSTNAME_CONTAINER: The DNS of the Docker host, which is added by default to the self-signed certificate SAN list.
  NOTE: The value of this parameter is set as the default hostname of the Docker.
  
• PORT_UI: The host port of the Docker used to access the FortiSOAR UI. The traffic on this Docker host port is forwarded by the Docker to the container on port 443 (default). For example, if you want to change the default port (443) and set the PORT_UI as 5443, then you can access FortiSOAR at https://<HOSTNAME_DOCKER_HOST>:5443/.
• ENABLE_SME: By default, the FortiSOAR Docker image enables the embedded SME, and therefore the value of this parameter by default is set to true.
• PORT_SME: By default, the FortiSOAR Docker image enables the embedded SME. The PORT_SME is the host port of the Docker to access the TCP port of the embedded SME. The traffic on this Docker host port is forwarded by Docker to the container port 5671.
• RAM: The value of the RAM (in GB) of the FortiSOAR container.
• CPUS: The number of CPUs for the FortiSOAR container.
• IP_REPO: Only applicable if you are using offline repository for FortiSOAR. This parameter refers to IP address of the offline repository. The /etc/hosts file of the container contains the following entry:
  <IP_REPO> repo.fortisoar.fortinet.com
• HOSTNAME_REPO: Only applicable if you are using offline repository for FortiSOAR. This parameter refers to hostname of the offline repository. For offline repository, you must update the CA bundle/chain of the offline repository certificate in the container using the following steps:
  # docker cp <offline-repo-certificate-CA-bundle> <FortiSOAR-container-name>:/etc/pki/ca-trust/source/anchors/
# docker exec -ti <FortiSOAR-container-name> bash -c "update-ca-trust force-enable"
# docker exec -ti <FortiSOAR-container-name> bash -c "update-ca-trust extract"
• IPV6: This parameter determines whether or not IPv6 should be enabled for the docker. Specify true to enable IPv6 after you have ensured that the docker runtime is able to assign IPv6 to the FortiSOAR container.
  

Running the FortiSOAR Docker

Prerequisites

If your Docker runtime uses SELinux, ensure you enable the 'setsebool' parameter before starting the FortiSOAR Docker as follows:
setsebool -P container_manage_cgroup 1

Mode of running the FortiSOAR Docker

The FortiSOAR Docker runs in the 'non-privileged' mode. The following default privileges are assigned to the FortiSOAR, which are also applied, by default, to your FortiSOAR instance:

• SYS_ADMIN: Required for bind mounting /tmp on /var/tmp and for various systemd services.
• SYS_RAWIO: Required for running ‘dmidecode’ and for various systemd services.
• SYS_TIME: Required for running 'ntpd'.
• SYS_PTRACE: Required for running 'systemd-journal'.

FortiSOAR High Availability Support on Dockers

FortiSOAR High Availability (HA) clusters are supported on multiple Docker hosts, requiring FortiSOAR HA nodes to be deployed on separate Docker host instances. Adding HA support provides improved uptime, scalability, load balancing, fault tolerance, and simplified management for your FortiSOAR Dockers.

FSR Agents are not supported on FortiSOAR HA clusters that are deployed on separate Docker host instances. This feature is also not supported on MSSP environments.

Steps to add another FortiSOAR node on a different Docker host and then create a FortiSOAR HA cluster are as follows:

1. Deploy the FortiSOAR Docker image to create another node on a separate host machine using the steps mentioned in the Deploying the FortiSOAR Docker image topic.
2. Edit the fortisoar.env file as follows (see the Understanding the fortisoar.env file topic for information on the fortisoar.env file)
   1. Update the HOSTNAME_DOCKER_HOST parameter to the DNS of the Docker host of your other node. This must not be set to localhost.
   2. Update the HOSTNAME_CONTAINER parameter to the DNS of the Docker host of your other node. This must not be set to localhost.
   3. Change the ENABLE_SME parameter flag to "false".
   4. Update the EXTRA_PARAM parameter to publish the Docker port for your other node:
      EXTRA_PARAM="docker ---publish docker_port/host_port:container_port"
      For example:
      EXTRA_PARAM="--publish 5671:5671 --publish 9200:9200 --publish 5432:5432 --add-host <other_node_hostname>:<other_node_ip>"
3. To configure the other node as a secondary node, do the following:
   1. SSH to your active primary node as a root user, and run the csadm ha export-conf command to export the configuration details of the active primary node to a configuration file named ha.conf.
      You must copy the ha.conf file from the active primary node to the node that you want to configure as a secondary node.
   2. On the active primary server, add the hostnames of the secondary nodes to the allowlist, using the following command:
      # csadm ha allowlist --nodes <other_node_hostnames>
      You can add a comma-separated list of hostnames of the cluster nodes that you want to add to the allowlist after the --nodes argument.
   3. Ensure that all HA nodes are resolvable through DNS, and then SSH to the host that you want to configure as a secondary node and run the following command:
      # csadm ha join-cluster --status <active, passive> --role <primary, secondary> --conf <location of the ha.conf file>
      For example,
      # csadm ha join-cluster --status passive --role secondary --conf tmp/ha.conf
      This adds the node as a secondary node in the cluster.
      

Troubleshooting

FortiSOAR HA nodes deployed across various Docker hosts encounter post-takeover join cluster failures

After running the takeover operation, the join cluster operation on existing HA cluster nodes fails.

Resolution

FortiSOAR does not provide automated "join cluster" for other nodes in the HA cluster once "takeover" has been executed on a system.You must manually run the join cluster operation on the other nodes by exporting the config file from the new primary node.

SSO login is being redirected to the hostname of the FortiSOAR node instead of the load balancer hostname

After configuring FortiSOAR High Availability (HA) clusters on multiple Docker hosts with load balancers, you observe that the SSO login page is redirected to the hostname of the FortiSOAR node rather than the hostname of the load balancer.

Resolution

To redirect the SSO login page correctly to the load balancer' s hostname, add the following key to the fortisoar.env file:
HOSTNAME_LOAD_BALANCER: Hostname of load balancer

For information on the fortisoar.env file, see the Understanding the fortisoar.env file topic.

Frequently Asked Questions

How to clean up the FortiSOAR container?

To clean up the FortiSOAR container, run the following commands:

docker stop <container id>

docker rm <container id>

docker volume prune

What happens if users re-installs the FortiSOAR container without removing its volumes?

If users re-installs the FortiSOAR container without removing its volumes, then the FortiSOAR container is restored from its last saved state.

How to resolve the issue of Elasticsearch-based recommendations not working on a FortiSOAR instance on a Docker platform?

By default, Elasticsearch-based recommendations do not work on a FortiSOAR Docker instance due to size limitations. To know more about Elasticsearch-based recommendations, see the Recommendation Engine topic in the Application Editor chapter of the "Administration Guide".

To use Elasticsearch-based recommendations, you must increase the memory allocated to Elasticsearch to 4 GB, using the following steps:

1. Update the value of the following parameters in the /etc/elasticsearch/jvm.options.d/fsr.options file to 4 GB:
   -Xms4g
-Xmx4g
2. Restart the Elasticsearch service using the following command:
   systemctl restart elasticsearch
3. Reindex Elasticsearch data using the following command:
   sudo -u nginx php /opt/cyops-api/bin/console app:elastic:create --sync=true
   Now, you should be able to view Elasticsearch-based recommendations on your FortiSOAR Docker instance.