> 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.7/onboard-cortex-xsoar/cortex-xsoar-installation/install-cortex-xsoar-on-a-vm-deployed-on-aws.md). # Install Cortex XSOAR on a VM deployed on AWS The following procedure describes the steps for deploying an OVA image on AWS and then installing Cortex XSOAR on your deployed virtual machines. {% hint style="info" %} ### 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. {% endhint %}
Task 1. Download the OVA image and license from Cortex Gateway 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. Downloading a file image from Cortex Gateway ensures you have the latest pre-configured software package for easy deployment and updates. If you have multiple or development tenants, you must repeat these tasks for each tenant. {% hint style="warning" %} ### Prerequisite * 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](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 Verify, 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.7/onboard-cortex-xsoar/cortex-xsoar-installation/system-requirements.md) for deploying a Cortex XSOAR tenant. * Have a basic understanding of how to deploy the OVA file format. * For VMWare ESXi 6.5 and later, you need hardware version 13. {% endhint %} How to download the image and license 1. Log in to [Cortex Gateway](https://cortex-gateway.paloaltonetworks.com/accounts). 2. In the **Available for Activation** section, use the serial number to locate the tenant to download. 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. If you want to use a production and a development tenant with a private remote repository, select **Dev**. If you don't select it now, you can install a development tenant later. 3. Select **Download On Prem**. 4. Click **Next**. 5. Select the OVA image format to download. OVA is supported by AWS, Oracle Cloud Infrastructure (OCI), and VMWare (for example, VSphere). 6. Select the checkbox to agree to the terms and conditions of the license and click **Download**.

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.

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) 7. Extract (unzip) the license and image files.
Task 2. Deploy your virtual machine on AWS **Considerations** * Currently, only AWS Commercial Cloud, also known as AWS Global, is supported (not GovCloud). * Cortex XSOAR supports only Nitro hypervisor-based instance types, for example m5.4xlarge. For more information, see [Amazon EC2 instance types](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-types.html#instance-hypervisor-type). * 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.7/onboard-cortex-xsoar/cortex-xsoar-installation/post-installation/optimize-performance-and-robustness-from-the-textual-ui.md#UUID-16e8f05d-3d05-3da9-7f90-00305ee4c18d). * Before importing the VM image, export the VM from your virtualization environment. You need an Amazon S3 bucket in the correct region, and the VM image file must be uploaded to the S3 bucket. * The VM Import/Export feature in AWS requires a role to perform certain operations on your behalf. You must create a service role named **`vmimport`** with a trust relationship policy document that allows VM Import/Export to assume the role, and you must attach an IAM policy to the role. This will allow the **`vmimport`** role to access the S3 bucket you created. For more information, see [VM Import/Export Requirements](https://docs.aws.amazon.com/vm-import/latest/userguide/vmie_prereqs.html), [Required service role](https://docs.aws.amazon.com/vm-import/latest/userguide/required-permissions.html#vmimport-role), and [IAM Roles](https://docs.aws.amazon.com/IAM/latest/UserGuide/roles-toplevel.html).

Important

Ensure the AWS VM role has gp2 ec2:CreateVolume permission.

### High Availability and backup and restore To implement built-in High Availability, deploy a cluster with three nodes (VMs), with each VM on a different hypervisor. This ensures that if one hypervisor fails, the other VMs continue to operate. You then need to: * Establish trust between all nodes in the cluster (Task 5). * Set the **Cluster FQDN** to the reverse proxy/ingress controller IP address (Task 6). The reverse proxy/ingress controller serves as a single entry point to distribute traffic across the nodes in the cluster. 1. In AWS, under **Region**, confirm the correct region is selected. 2. On your local computer, rename the OVA file to include the prefix `migrationhub-orchestrator-vmie-` to follow the AWS naming convention. 3. Upload the OVA image file to a private and secure S3 bucket that you set up. 1. Under **General purpose buckets**, select the bucket. 2. Under **Amazon S3** → **Buckets** → `` → **Objects**, select the folder for the OVA file. The folder must start with `migrationhub-orchestrator-vmie-`. It can contain only one OVA file. 3. In **Upload**, drag the OVA image file into the page. Select **Upload**. 4. Create a workflow using AWS Migration Hub Orchestrator. Use the **Import virtual machine images to AWS** template. 1. Open the **Migration Hub Orchestrator** console. 2. From the side menu, select **Migration & Transfer** → **AWS Migration Hub**.

AWS Migration Hub is available only in certain regions.

3. From the **Migration Hub** side menu, select **Orchestrate** → **Workflows** → **Create workflow**. 4. On **Choose a workflow template**, select **Import new virtual machine images to AWS**. Select **Next**. 5. Configure the workflow properties: * Set the workflow name. * Set **Disk container** to the uploaded image path. * Under **Target environment configuration**, set **Boot mode - optional** to **legacy-bios**. 6. Select **Next**. 7. Select the new workflow, then select **Run**. 5. Launch the virtual machine from the relevant AMI template. 1. In AWS, select **Services** → **Compute** → **EC2**. 2. Select **Images** → **AMIs**. 3. Select the AMI created by the workflow. Select **Launch instance from AMI**. 4. Configure the instance: * Select an instance type that meets the [system requirements](/cortex-xsoar-8-on-prem/8.7/onboard-cortex-xsoar/cortex-xsoar-installation/system-requirements.md). * Configure a static IP address, security group, and subnet. * Under **Key pair**, select **Proceed without a key pair**. 5. Select **Launch instance**. Confirm that you want to proceed without a key pair. 6. Create a block volume. The block volume size depends on the deployment scale. For a small-scale deployment, use a 1,024 GB (1 TB) volume. This provides a 256 GB data disk and a separate 775 GB data disk.

Important

Each virtual machine includes a 256 GB OS disk. Add an extra hard disk for each virtual machine that runs the application.

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

Ensure the disks meet the performance requirements in System requirements.

7. Repeat these steps for every virtual machine in the cluster. 8. For the first login, use an external terminal and run the following command: ```shell ssh admin@ ``` The default user name and password are both `admin`. ![](/files/6Mm3URTci18lbiAQzLzv)\ Set a new password for the `admin` user.

Important

Save the SSH password securely. You cannot recover or change it. Redeploy the cluster if you lose it.

The password must contain at least eight characters, including: * One lowercase letter * One uppercase letter * One number or one of these special characters: `!@#%` For later logins, use the web console or run `ssh admin@`. The textual UI opens with all configuration and installation options.

Tip

  • Click anywhere on the screen to start using the textual UI.
  • Use the up and down arrows to navigate. Press Enter to select an item.
  • Use Tab to move between fields. Press Esc to return to the previous menu.
Task 3. Validate tenant network and IP settings Since the Cloud platform handles network and IP settings, you can skip the Host Configuration menu in the textual UI. Confirm the following network and IP settings are added to the rules of the security group or the firewall rules for each node in a cluster (for standalone there is just a single node). If they are not added to the rules, the installation may fail. **Port configurations** Communication ports For standalone (one VM) and a three-node cluster (three VMs): | Port | Protocol | Purpose | | ---- | -------- | ------------------ | | 22 | TCP | SSH communication | | 8880 | TCP | Node communication | Control plane ports A Kubernetes cluster consists of a control plane and one or more worker nodes. For Cortex XSOAR, in standalone (one VM), the VM acts as both control plane and as a worker node. In multi-node clusters, the first three nodes act as both control plane and as worker nodes, and any additional node added acts as a worker node. | Name | Port | Protocol | | ----------------------- | ----- | -------- | | etcd client port | 2379 | TCP | | etcd peer port | 2380 | TCP | | Kubernetes API | 6443 | TCP | | Kubelet API | 10250 | TCP | | kube-scheduler | 10257 | TCP | | kube-controller-manager | 10259 | TCP | Worker node port | Name | Port | Protocol | | ------------------- | ----------- | -------- | | kube nodeport range | 30000:32767 | TCP | Intra-node port For a multi-node cluster (three VMs): | Name | Port | Protocol | | -------------------------- | ----- | -------- | | Calico with IPv4 Wireguard | 51820 | UDP | **URLs** Check the following URLs to ensure Cortex XSOAR operates properly. | Function | Service | Port | Direction | | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | --------- | | Web interface | HTTPS | 443 | Inbound | | Engine connectivity | HTTPS | 443 (configurable) | Inbound | | Integrations | Integration-specific ports | | Outbound | | Unit42 Intel Inventory (TIM license) | | 443 | Outbound | | Marketplace | | 443 | Outbound | | On-prem Gateway |

onpremgw\.crtx.\[region].paloaltonetworks.com

Cortex XSOAR accesses new versions from and uploads licenses to this repository.

| 443 | Outbound | | Download packages required for installation | | 80 | Outbound | **NTP** Ensure all nodes are synchronized with no NTP offset in order to prevent degraded storage performance.
Task 4. (Optional) Configure proxy settings When a proxy is configured in Cortex XSOAR, the system by default routes internal node-to-node communication and other internal traffic through that configured proxy. If you do not configure a proxy, the system uses standard network routing and DNS resolution. 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 You can either enter the address as `IP:port` without a `http://` or `https://` prefix, or enter the host name. * Proxy Port 3. Select
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. 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. ![](https://paloaltonetworks.fluidtopics.net/api/khub/maps/VpFvGNmm_LKax62aqKBcmg/resources/BYVbniBMypiX91tU1r0z5Q-VpFvGNmm_LKax62aqKBcmg/content?v=de436d249e4adcb4\&Ft-Calling-App=ft/turnkey-portal) 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: ![](https://paloaltonetworks.fluidtopics.net/api/khub/maps/VpFvGNmm_LKax62aqKBcmg/resources/2uKeEik_S45WXZ7BKkLW3Q-VpFvGNmm_LKax62aqKBcmg/content?v=4d4f542d02b7292b\&Ft-Calling-App=ft/turnkey-portal) 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. ![](https://paloaltonetworks.fluidtopics.net/api/khub/maps/VpFvGNmm_LKax62aqKBcmg/resources/HQJuCEvSxXaane_1Y9LeTA-VpFvGNmm_LKax62aqKBcmg/content?v=9ebb8856dc75d4a2\&Ft-Calling-App=ft/turnkey-portal) 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 on your VM 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. * **`xsoar..`**: 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. 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. For a single virtual machine (standalone), configure the settings for a single node. 2. Configure the following settings. 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. | Field | Description | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 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

Copy the IP of each VM from the Private IPv4 address field in the AWS EC2 → Instances → Instance summary page and paste it in this field, separated by a space.

| | Cluster FQDN |

The Cortex XSOAR environment DNS name. For example, \.\.\

Copy the FQDN from the Public IPv4 DNS field in the AWS EC2 → Instances → Instance summary page and paste it in this field.

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.

For a multi-node cluster: To implement built-in HA using a reverse proxy/ingress controller, you need to set this field value to match the IP of the reverse proxy/ingress controller, and it must be registered in your DNS server so the FQDN will be resolved to the IP of the reverse proxy/ingress controller.

The reverse proxy/ingress controller IP address serves as a single entry point for the entire Cortex XSOAR cluster. The reverse proxy/ingress controller checks the health endpoint of the node for any issues. If the node is healthy it can be used to process requests. To use a reverse proxy/ingress controller IP address:

  • Set access to the cluster nodes through port 443.
  • Use HTTP 10254 with the path /healthz as the health endpoint.

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) |

(Hypervisor deployments only) The Cortex XSOAR environment virtual IP for the multi-node cluster. It is a virtual interface assigned to one of the nodes to provide a single access point to the cluster. The virtual IP address must be a dedicated, available IP address that is not assigned to any nodes in the cluster.

Do not fill in this field (Cortex XSOAR does not support virtual IPs in Cloud deployments).

| | Cluster Region | The region the cluster is located in. For example, US. | | Cortex XSOAR Admin Email, Password, and Confirm Password |

Credentials for the first user to log in to Cortex XSOAR.

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.

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. ![](https://paloaltonetworks.fluidtopics.net/api/khub/maps/VpFvGNmm_LKax62aqKBcmg/resources/gpnt0ugV8bI0Dr1S9I2ECw-VpFvGNmm_LKax62aqKBcmg/content?v=888696c54611ad52\&Ft-Calling-App=ft/turnkey-portal) The virtual machine you use to run the installer will deploy Cortex XSOAR on all virtual machines in a cluster.
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.7/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.7/onboard-cortex-xsoar/cortex-xsoar-installation/install-cortex-xsoar-on-a-vm-deployed-on-aws.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.