Install Cortex XSOAR from an OVA image - Administrator Guide - 8.5 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR On-prem Documentation

Product
Cortex XSOAR
Version
8.5
Creation date
2024-03-10
Last date published
2025-01-15
Category
Administrator Guide
Solution
On-prem
Abstract

Download an OVA image from Cortex Gateway, deploy the image, and use the textual user interface to configure network, IP, and environment settings, and to install a Cortex XSOAR tenant.

To install a Cortex XSOAR 8 tenant, you need to log into Cortex Gateway, which is a portal for downloading the relevant image file and license. If you have multiple or development tenants, you must repeat this task for each tenant.

Danger

  • A Customer Support Portal (CSP) account.

    You need to set up your CSP account. For more information, see How to Create Your CSP User Account.

    When you create a CSP account you can set up two-factor authentication (2FA) to log into the CSP, by using an Email, Okta Verfiy, or Google Authenticator (non-FedRAMP accounts). For more information, see How to Enable a Third Party IdP.

  • You have one of the following roles assigned:

    Role

    Details

    CSP role

    The Super User role is assigned to your CSP account. The user who creates the CSP account is granted the Super User role.

    Cortex role

    You must have the Account Admin role.

    If you are the first user to access Cortex Gateway with the CSP Super User role, you are automatically granted Account Admin permissions for the Cortex Gateway. You can also add Account Admin users as required.

  • To download the Cortex XSOAR 8 images from Cortex Gateway, you need a license (or evaluation license via sales) assigned to your CSP account.

  • Review the System requirements for deploying a Cortex XSOAR tenant.

  • Have a basic understanding of how to deploy OVA file formats.

  • Add DNS records that point the following host names to the cluster IP address.

    • Cluster FQDN - The Cortex XSOAR DNS name for accessing the UI. For example, xsoar.mycompany.com.

    • API-FQDN - The Cortex XSOAR DNS name that is mapped to the API IP address. For example, api-xsoar.mycompany.com.

    • ext-FQDN - The Cortex XSOAR DNS name that is mapped to external IP address. For example, ext-xsoar.mycompany.com.

Tip

In Google Chrome, to download the image and license files together, you may need to set the the browser SettingsPrivacy and securitySite settingsAdditional permissionsAutomatic downloads to the default behavior Sites can ask to automatically download multiple files.

How to download the image and license
  1. Log in to Cortex Gateway. For your Cortex XSOAR license, select Download On Prem.

    By default, the Production-Standalone license is selected. You can also select Dev.

    Production and development are separate Kubernetes clusters with no dependency between them. For example, you can deploy a three-node cluster for production and a standalone node for development. Or you can support small scale for development and large scale for production.

  2. Click Next.

  3. Select the OVA image format to download.

    OVA is supported by VMWare.

  4. Select the checkbox to agree to the terms and conditions of the license and click Download.

    Two files download: A zipped license file containing one or more JSON license files with instructions, and a zipped image file of the type you selected (.ova, .vhd)

  5. Extract (unzip) the license and image files.

The following is an example of deploying your VM on VSphere from an OVA image. For more details, see Deploying OVF Templates.

If you set your Cortex XSOAR environment as a standalone (single node), you cannot add nodes to it and switch to a cluster. If you deploy three nodes, you can later add nodes and expand the cluster. For more information, see Manage nodes in a cluster.

  1. Copy the downloaded image file into your hypervisor.

  2. Wherever the templates are located, right click one of the templates and choose to deploy a new virtual machine from the template.

    Note

    Although you can create a virtual machine directly from the OVA image file, deploying from a template enables creating multiple configured virtual machines from one downloaded OVA instead of downloading the same OVA for each virtual machine, which can be time consuming.

  3. Right click the template file and select New Virtual Machine.

  4. Follow the wizard instructions to define the virtual machine properties:

    1. Set the storage for the virtual machine configuration and disk files.

      • Batch configure or configure per disk.

      • Set the virtual disk format to Thin Provision (for SSD).

      • Set the VM storage policy.

      • Disable storage DRS.

    2. Select Customize this virtual machine's hardware and Power on virtual machine after creation from the clone options and go to the Customize hardware step.

      Important

      Every virtual machine is provided with a 256 GB hard disk to run the OS. However, you also need to add an extra hard disk for each virtual machine instance you want to deploy to run the application.

      All virtual machines in a cluster must have the same storage size.

      To ensure successful deployment, make sure the hard disks meet performance requirements detailed in the System requirements.

      1. Select ADD NEW DEVICEHard Disk.

      2. Set the disk space for the extra hard disk according to your scale size. For example, for small scale, set it to 775 GB.

      3. Choose the Thick Provision hard disk type.

      4. If the virtual machine is running, reset it.

    3. Click FINISH.

    4. Go to the folder the virtual machine was deployed to and select the virtual machine name you defined.

    5. In the Summary tab, click LAUNCH WEB CONSOLE.

  5. Repeat from Step 2 for each additional virtual machine in the cluster.

  6. Log in to each virtual machine console. For first time login, the default user name and password is admin.

    opp-first-login.png

    Give the admin a new password as follows.

    The password must be at least eight characters long and contain at least:

    • One lower case letter

    • One upper case letter

    • One number, or one of the following special characters: !@#%

    The textual UI menu opens with all the configuration and installation options.

    Tip

    • To start using the textual UI, click anywhere on the screen.

    • To navigate between the menu items, use the up and down arrow keys. To select a menu item, press the Enter key.

    • To navigate between fields within a menu item, use the Tab key. To save settings, tab to the Save button and press the Enter key.

    • To go back to the menu from a specific menu item field, press the esc key.

You need to configure network and IP settings in each node in a cluster. For standalone, there is just a single node.

Note

When choosing the network settings, either use private IPs or a public IP covered by an access policy defined in a security group.

  1. In the textual UI menu, select Host Configuration.

  2. Configure the following network and IP settings for each node/virtual machine.

    • Network interface  - A list of available interfaces on the node that the textual UI runs on. For example, ens160

    • IP address - IP address for this node. After deployment, this field will not be editable. For example, 10.196.37.10

    • Default gateway - IP address of the default gateway for this interface. For example, 10.196.37.1

    • DNS server 1 - IP address of the DNS server. For example, 10.196.4.10

    • DNS server 2 (optional) - IP address of a secondary DNS server. For example, 10.196.4.11

    • NTP - The IP address of NTP server that the node will be synced with. By default, the nodes get an out-of-the-box NTP server, you can override the value.

    opp-oci-host-config.png
  3. Select Save.

If you want to use a proxy, define the proxy address and port settings. The proxy can be set at any point, during Cortex XSOAR deployment or at a later stage.

  1. From the textual UI menu, select Proxy Configuration.

  2. Configure the following settings.

    • Proxy Address

      Note

      Enter the address as IP:port without a http:// or https:// prefix.

    • Proxy Port

  3. Select Save.

This task is not relevant for a standalone deployment (single node).

For each VM (node) in a cluster, the nodes must have SSH connections between them, where all the nodes trust one another. To establish trusted connections in a cluster, one node is designated as the signing server host, generating a token for secure communication and authentication. Other nodes connect to the host using the token displayed on the host's screen.

The IPs of all VMs (nodes) in a cluster as well as the virtual IP must be on the same subnet, they currently cannot be split across subnets.

Important

To implement built-in High Availability, after establishing trust between all nodes in a cluster, in the cluster installation step (Task 6) you need to set a single entry point to distribute traffic across the nodes in the cluster. Do this by setting the Cluster FQDN to either the virtual IP address or to the reverse proxy/ingress controller IP address.

  1. In the textual UI menu for the VM you want to be the host, select Connect Nodes.

  2. Select Host.

    opp-nodes-trust-host-8-7.png

    A message displays that this action cancels prior trust established with other nodes. Select Yes to continue.

    This node becomes the host, and a token is generated on the screen. Copy the token, for example:

    opp-establish-trust-token.png

    Note

    Keep this window open (do not select Stop) until trust is established between all nodes to enable the host to listen for the token from the other nodes.

  3. In the textual UI for each additional node (VM) in the cluster:

    1. Select Connect Nodes.

    2. Select Join.

    3. Paste the Token generated for the host.

    4. Enter the Host IP Address.

    5. Select Submit.

    opp-nodes-trust-join.png

    A message displays that this action cancels prior trust established with other nodes. Select Yes to continue.

  4. Select OK.

  5. After trust is established between all the nodes in the cluster, go back to the host node and select Stop to close the listening window.

  1. From the textual UI menu, select Cluster Installation.

    The virtual machine you use to run the installer will deploy Cortex XSOAR on all virtual machines in a cluster.

  2. Configure the following settings.

    Important

    The IPs of all VMs (nodes) in a cluster as well as the virtual IP must be on the same subnet, they currently cannot be split across subnets.

    You can only change these field values in the textual UI menu before installing. To change these values after installing, you need to redeploy your cluster and then reinstall. Contact support or engineering for assistance.

    • Cluster Nodes: A list of IPs of all virtual machines/nodes in the cluster, separated by a space. For example, 10.196.37.10 10.196.37.11 10.196.37.12

    • Cluster FQDN: The Cortex XSOAR environment DNS name. For example, <subdomain>.<domain name>.<top level domain>

      Note

      For a single node: This field value must be registered in your DNS server so the FQDN will be resolved to the IP of the node.

      Cortex XSOAR supports only static IP addresses for each virtual machine in the cluster, it does not support a DHCP (dynamic IP) network interface.

    • Virtual IP (optional): The Cortex XSOAR environment virtual IP for the multi-node cluster. It must be a different IP than the IPs of the nodes. It is a virtual interface assigned to one of the nodes to provide load balancing to the cluster. For more details, see Set up the IP address to access Cortex XSOAR.Set up the IP address to access Cortex XSOAR

    • Cluster Region: The region the cluster is located in. For example, US.

    • Cortex XSOAR Admin Email, Password, and Confirm Password: These are credentials for the first user to log in to Cortex XSOAR .

      Important

      These fields can only be changed before installation, so it is important to keep this information secure. To change values like username or password after installation, you will need to redeploy your cluster and reinstall. Contact support or engineering for assistance.

      For the Cortex XSOAR Admin Email, we recommend using a service account rather than a specific user email address since this cannot be changed after installation.

      Note

      The password must be at least eight characters long and contain at least:

      • One lower case letter

      • One upper case letter

      • One number, or one of the following special characters: !@#%

  3. Select Install.

    Verify all nodes meet the required hardware and network requirements, and select Install again.

    opp-oci-cluster-installation-2.png

    The virtual machine you use to run the installer will deploy Cortex XSOAR on all virtual machines in a cluster.

    When you select Install again, after the installation tasks run an Installation completed successfully message displays. However, you need to wait until the installation process fully completes (approximately 30 minutes) and then check that you can open the Cortex XSOAR UI.

After the installation tasks run, an Installation completed successfully message displays in the textual UI. However, you need to wait until the installation process fully completes (approximately 30 minutes) and then check that you can log in to Cortex XSOAR. You then need to upload your license to enable all Cortex XSOAR pages.

  1. Log in to Cortex XSOAR.

    When you log in for the first time, use the Admin password and email you set during installation.

  2. Upload your license to Cortex XSOAR.

    For more information, see Add the Cortex XSOAR license.