> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.5/onboard-cortex-xsoar/cortex-xsoar-installation/install-cortex-xsoar-from-an-ova-image.md). # Install Cortex XSOAR from an OVA image 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. {% hint style="warning" %} ### Prerequisite * Set up your CSP account. For more information, see [How to Create Your CSP User Account](https://knowledgebase.paloaltonetworks.com/KCSArticleDetail?id=kA10g000000ClNVCA0). 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](https://knowledgebase.paloaltonetworks.com/KCSArticleDetail?id=kA14u000000sZ8mCAE). * 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](/cortex-xsoar-8-on-prem/8.5/onboard-cortex-xsoar/cortex-xsoar-installation/system-requirements.md) for deploying a Cortex XSOAR tenant. * Have a basic understanding of how to deploy OVA file formats. * For VMWare ESXi 6.5 and later, you need hardware version 13. * Ensure the following DNS records were added to your DNS server to resolve hostnames to the cluster IP address (only static, DHCP is not supported). These DNS records (for a given tenant) should all point to the same cluster IP address to ensure a single entry point. For MSSP, each tenant must have its own set of **`xsoar.*`**, **`api-*`**, and **`ext-*`** FQDNs pointing to the tenant cluster's single entry point. * Cluster FQDN - The Cortex XSOAR DNS name for accessing the UI. For example, `xsoar.mycompany.com`. * **`api-.`**: The Cortex XSOAR DNS name that is mapped for API access. For example, **`api-xsoar.mycompany.com`**. This should be a CNAME entry pointing to the same cluster IP address. * **`ext-.`**: The Cortex XSOAR DNS name that is mapped to access long running integrations. For example, **`ext-xsoar.mycompany.com`**. This should be a CNAME entry pointing to the same cluster IP address. * Ensure 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. {% endhint %}
Task 1. Select and download the OVA image and license from Cortex Gateway {% hint style="info" %} ### Tip In Google Chrome, to download the image and license files together, you may need to set the the browser **Settings** → **Privacy and security** → **Site settings** → **Additional permissions** → **Automatic downloads** to the default behavior **Sites can ask to automatically download multiple files**. {% endhint %} How to download the image and license 1. Log in to [Cortex Gateway](https://cortex-gateway.paloaltonetworks.com/accounts). 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.
Task 2. Deploy your virtual machine The following is an example of deploying your VM on VSphere from an OVA image. For more details, see [Deploying OVF Templates](https://docs.vmware.com/en/VMware-vSphere/7.0/com.vmware.vsphere.vm_admin.doc/GUID-AFEDC48B-C96F-4088-9C1F-4F0A30E965DE.html). 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](/cortex-xsoar-8-on-prem/8.5/onboard-cortex-xsoar/cortex-xsoar-installation/post-installation/manage-nodes-in-a-cluster.md). 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 DEVICE** → **Hard 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](/files/zQ1A1sWcMa9dbD5REhaU) 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.
Task 3. Configure Cortex XSOAR tenant network and IP settings You need to configure network and IP settings in each node in a cluster. For standalone, there is just a single node. {% hint style="info" %} ### Note When choosing the network settings, either use private IPs or a public IP covered by an access policy defined in a security group. {% endhint %} 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](/files/ZTgZcLGeUUNonPp0lKck) 3. Select **Save**.
Task 4. (Optional) Configure proxy settings 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

You can either enter the address as IP:port without a http:// or https:// prefix, or enter the host name.

* **Proxy Port** 3. Select **Save**.
Task 5. Establish trust between all nodes in a cluster 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. {% hint style="info" %} ### 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. {% endhint %} 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](/files/TMWD0DcESW0LX5mCcW4k) 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](/files/YkcQzOzgUSTGMwIyXs99)

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](/files/pXd9KVxZXS3hTdjKCT8d) 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.
Task 6. Install Cortex XSOAR 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, `..`

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. * **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](/files/8ZqmByPvCGyVTgx5Y2YR) 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.
Task 7. Verify you can log in to Cortex XSOAR 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](/cortex-xsoar-8-on-prem/8.5/onboard-cortex-xsoar/cortex-xsoar-installation/post-installation/add-the-cortex-xsoar-license.md).
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.5/onboard-cortex-xsoar/cortex-xsoar-installation/install-cortex-xsoar-from-an-ova-image.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.