Install Cortex XSOAR on a VM deployed on AWS

Install Cortex XSOAR On-prem 8.7 (EoL) on an AWS VM.

The following procedure describes the steps for deploying an OVA image on AWS and then installing Cortex XSOAR on your deployed virtual machines.

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.

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.

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.

  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.
• 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 the OVA file format.
• For VMWare ESXi 6.5 and later, you need hardware version 13.

How to download the image and license

1. Log in to Cortex Gateway.
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.
• 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.
• 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, Required service role, and IAM Roles.

  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-<filename> 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 → <your bucket name> → 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.
      • 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:

   ssh admin@<server ip address>

   The default user name and password are both admin.

   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@<server ip address>.

   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)	https://unit42intel.xsoar.paloaltonetworks.com	443	Outbound
Marketplace	https://marketplace.xsoar.paloaltonetworks.com/ Download content packs and view the Marketplace (to view content pack images, the domain should also be reachable from the browser). storage.googleapis.com Download content packs and view the Marketplace. This domain stores content pack artifacts (to view content pack images, the domain should also be reachable from the browser). It is possible to further limit the url prefix to: https://storage.googleapis.com/marketplace-dist/ api.demisto.com Download content Packs and view the Marketplace (this file maps the Marketplace URL to the Cortex XSOAR version). You must add marketplace.xsoar.paloaltonetworks.com, storage.googleapis.com, and api.demisto.com otherwise you cannot access the Marketplace. xsoar-contrib.pan.dev Contribute content packs.	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	deb.debian.org security.debian.org	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.

   

   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:

   

   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.

   

   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.<hostname>.<domain>: The Cortex XSOAR DNS name for accessing the UI. For example, xsoar.mycompany.com.
• api-<hostname>.<domain>: 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-<hostname>.<domain>: 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, <subdomain>.<domain name>.<top level domain> 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.

   

   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.