> 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-xdr-3.x/cortex-xdr-3.x-documentation/data-management/broker-vm/set-up-and-configure-broker-vm/broker-vm-image-installations/set-up-broker-vm-on-amazon-web-services.md). # Set up Broker VM on Amazon Web Services After you download your Cortex XDR Broker **VMDK** image, you can convert the image to an Amazon Web Services (AWS) Amazon Machine Image (AMI) using the AWS CLI. The task below explains how to do this on Linux. {% hint style="warning" %} ### Prerequisite * Download a Cortex XDR Broker VM **VMDK** image. For more information, see the virtual machine compatibility requirements in [Set up and configure Broker VM](/cortex-xdr-3.x/cortex-xdr-3.x-documentation/data-management/broker-vm/set-up-and-configure-broker-vm.md). * You need to set up an AWS VM Import role (`vmimport`) before running the `import-snapshot` CLI command. If the role `vmimport` does not exist or does not have the required permissions, you can create it using the steps below or use a different role with the necessary permissions. You'll need an Administrator role or the required permissions to create or modify this role. For more information on setting up an AWS VM Import role and the permissions required, see [Required service role](https://docs.aws.amazon.com/vm-import/latest/userguide/vmie_prereqs.html#vmimport-role). {% endhint %} To convert the image to AWS, perform the following procedures in the order listed below.
Task 1. Create an IAM User with Proper Permissions You need to log in using an AWS Identity and Access Management (IAM) user, where the permissions are defined in the IAM policy to use the virtual machine Import and export. 1. Log in to the [AWS IAM Console](https://console.aws.amazon.com/iam/home), and in the navigation pane, select Access Management → Users, and click **Create user**. 2. Under **User name**, specify a username, and click **Next**. 3. In the **Permissions options** section, select **Attach Existing Policies directly**, and then in the **Permissions policies** section, click **Create policy**. 4. In the **JSON** tab, copy and paste the following syntax to define the policy: ```programlisting {   "Version": "2012-10-17",   "Statement": [     {       "Effect": "Allow",       "Action": [         "s3:GetBucketLocation",         "s3:GetObject",         "s3:PutObject"       ],       "Resource": ["arn:aws:s3:::mys3bucket","arn:aws:s3:::mys3bucket/*"]     },     {       "Effect": "Allow",       "Action": [         "ec2:CancelConversionTask",         "ec2:CancelExportTask",         "ec2:CreateImage",         "ec2:CreateInstanceExportTask",         "ec2:CreateTags",         "ec2:DescribeConversionTasks",         "ec2:DescribeExportTasks",         "ec2:DescribeExportImageTasks",         "ec2:DescribeImages",         "ec2:DescribeInstanceStatus",         "ec2:DescribeInstances",         "ec2:DescribeSnapshots",         "ec2:DescribeTags",         "ec2:ExportImage",         "ec2:ImportInstance",         "ec2:ImportVolume",         "ec2:StartInstances",         "ec2:StopInstances",         "ec2:TerminateInstances",         "ec2:ImportImage",         "ec2:ImportSnapshot",         "ec2:DescribeImportImageTasks",         "ec2:DescribeImportSnapshotTasks",         "ec2:CancelImportTask"       ],       "Resource": "*"     }   ] } ``` 5. Click **Next**. 6. In the **Policy details** section, under **Policy name**, specify a name for the policy, and click **Create policy**. 7. Select the policy that you created above based on the syntax you added, and click **Next**. 8. Complete the user creation process by clicking **Create user**.
Task 2. Create access credentials 1. After confirmation that the user is created, select the user that you created. 2. Open the **Security credentials** tab, scroll down to the **Access key** section, and click **Create access key**. 3. In **Step 1 Access key best practices & alternatives** perform the following: 1. Select the **Command Line Interface (CLI)** option. 2. Select the **Confirmation** checkbox. 3. Click **Next**. 4. (Optional) In **Step 2 Set description tag**, you can enter a description for the access key, or leave it empty, and then click **Create access key**. 5. In **Step 3 Retrieve access keys**, copy the following user information, which you will need later: * User name * Access key ID * Secret access key
Task 3. Setup AWS CLI You can run the AWS CLI commands using one of the two options below. **Option 1: AWS CloudShell (Recommended - No Installation)** AWS CloudShell is a browser-based shell that is pre-authenticated with your Console credentials. 1. Log in to the AWS Management Console. 2. Select the **Region** where your S3 bucket is located. 3. Click the CloudShell icon (![AWS\_icon.png](/files/Os22fU1wZBwGD8kshgJm)) on the top navigation bar. **Option 2: External Terminal** Install the AWS CLI and configure it with the IAM user that you created. 1. Login to the server with admin privilege and install the AWS CLI. ```programlisting # sudo bash # apt update # apt install awscli ``` 2. Run the following command to configure the AWS CLI: ```programlisting # aws configure ``` You need to specify the proper configurations for the following: * **AWS Access Key ID**: The **Access key ID** for the IAM user you created. * **AWS Secret Access Key**: The **Secret access key** for the IAM user you created. * **Default region name**: The **Region** where you've defined the IAM user you created. You are now ready to implement commands in the AWS CLI.
Task 4. Create an AMI Image To create an AMI image, you need to download Broker VM VMDK file from the Cortex XDR Web Console, import this file to your S3 bucket, and then convert the VMDK file to an AMI Image. 1. In the Cortex XDR Web Console , select Settings → Configurations → Data Broker → **Broker VMs** → **Add Broker** → **VMDK**. 2. Download the VMDK file, such as **`broker-vm-.vmdk`**, to your computer. 3. Navigate and log in to your AWS account. 4. In the AWS Console, select All services → Storage → S3. 5. On the **Buckets** page, click **Create bucket** to upload your Broker VM image to this bucket. Specify a unique name for the S3 bucket and use the default configurations. 6. Upload the Broker VM VMDK you downloaded from Cortex XDR to the AWS S3 bucket using one of the following methods: * Using the AWS Management Console: On the **Buckets** page, select your bucket, and click **Upload** to upload the VMDK file. * Using an external terminal: ```programlisting Run # aws s3 cp ~/ s3:// ``` 7. Prepare the following configurations files on your hard drive. **configuration.json** 1. Run the following command in the terminal: ```` ``` programlisting # vi configuration.json ``` ```` 2\. Copy and paste the following syntax into the json file. ```` In **S3Bucket**, replace **\** with the Bucket Name and not its ARN Name. **S3Key** is the VMDK filename, which you should replace instead of **\**. ``` programlisting { "Description":"Cortex XDR Broker VM ", "Format":"vmdk", "UserBucket":{ "S3Bucket":"", "S3Key":"" } } ``` ```` **trust-policy.json** 1. Run the following command in the terminal: ```` ``` programlisting # vi trust-policy.json ``` ```` 2\. Copy and paste the following syntax into the json file. ```` ``` programlisting { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "vmie.amazonaws.com" }, "Action": "sts:AssumeRole", "Condition": { "StringEquals":{ "sts:Externalid": "vmimport" } } } ] } ``` ```` **role-policy.json** 1. Run the following command in the terminal. ```` ``` programlisting # vi role-policy.json ``` ```` 2\. Copy and paste the following syntax into the json file. Replace the **\** and **\** with the correct bucket name. You can specify \* to configure access to all your S3 buckets. ```` ``` programlisting { "Version":"2012-10-17", "Statement":[ { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:GetObject", "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::", "arn:aws:s3:::/*" ] }, { "Effect": "Allow", "Action": [ "s3:GetBucketLocation", "s3:GetObject", "s3:ListBucket", "s3:PutObject", "s3:GetBucketAcl" ], "Resource": [ "arn:aws:s3:::", "arn:aws:s3:::/*" ] }, { "Effect": "Allow", "Action": [ "ec2:ModifySnapshotAttribute", "ec2:CopySnapshot", "ec2:RegisterImage", "ec2:Describe*", "ec2:ImportSnapshot", "ec2:DescribeImportSnapshotTasks" ], "Resource": "*" } ] } ``` ```` 2. Use the **`create-role`** command to create a role named **`vmimport`** and grant VM import and export permissions using the **`trust-policy.json`** file. ```programlisting # aws iam create-role --role-name vmimport --assume-role-policy-document "file://trust-policy.json" ``` 3. Use the **`put-role-policy`** command to attach the policy to the **`vmimport`** role created above. `# aws iam put-role-policy --role-name vmimport --policy-name vmimport --policy-document "file:// role-policy.json"` 4. Create a snapshot from the VMDK file. Run the following command to start the import process: ```programlisting # aws ec2 import-snapshot --description "" --disk-container "file://configuration.json" ``` To track the progress, use the task `id` value from the output and run: ```programlisting # aws ec2 describe-import-snapshot-tasks --import-task-ids import-snap- ``` Example 46. Completed status output example: ```programlisting { "ImportSnapshotTasks": [ { "Description": "Broker VM snapshot import", "ImportTaskId": "import-snap-12346b69617c1395t", "SnapshotTaskDetail": { ... "DiskImageSize": 2976817664.0, "Format": "vmdk", "SnapshotId": "snap-1234567890", "Status": "completed", "UserBucket": { "S3Bucket": "broker-vm", "S3Key": "broker-vm-.vmdk" } }, "Tags": [] } ] } ``` 5. Register the AMI from the snapshot. Once the `describe-import-snapshot-tasks` command shows a status of `completed`, a new Snapshot has been created in your account. You must now register this snapshot as an AMI. 1. Locate the snapshot ID. In the output of your completed task, find the `SnapshotId`, for example `snap-0123456789abcdef0`. Alternatively, you can find it in the AWS Console: 1. Select **All services** → **EC2**. 2. In the left sidebar, under **Elastic Block Store**, select **Snapshots**. 3. Locate the snapshot with the description you provided during the import. 2. Create the image from the snapshot. 1. Select the checkbox next to your snapshot. 2. Select **Actions** → **Create image from snapshot**. 3. Specify mandatory settings in the **Create image from snapshot** section. To ensure the Broker VM functions correctly, configure these settings in the following sections: * **Image settings** * **Architecture**: **x86\_64** * **Root device name**: `/dev/sda1` * **Virtualization type**: **Hardware-assisted virtualization** * **Boot mode**: **Legacy BIOS** * **Block device mappings - optional** * **Size (GIB)**: `480GB` * **Volume type**: **General Purpose SSD (gp3)** * **IOPS**: `3000` * **Throughput (MB/s)**: **125** Once the task is complete, the AMI Image is ready for use. 6. (Optional) After the AMI image has been created, you can define a new name for the image. Select All services → EC2 → IMAGES → **AMIs** and locate your AMI image using the task ID. Select the pencil icon to specify a new name.
Task 5. Launch a Broker VM Instance in AWS EC2 You can launch the a Broker VM instance in AWS EC2 using the AMI Image created. {% hint style="info" %} ### Important A t3.xlarge (16 GB RAM) is the lowest machine type that can be used as an instance type to meet the mandatory 4 vCPU requirement. {% endhint %} 1. To view the AMI image that you added, select All services → EC2 → **Images** → **AMIs**. 2. Select EC2 → Instances, and click **Launch instances** to create an instance of the AMI image. 3. In the **Launch Instance Wizard** define the instance according to your company requirements and **Launch**. 4. (Optional) In the **Instances** page, locate your instance and use the pencil icon to rename the instance **Name**. 5. Define HTTPS and SSH access (optional) to your instance. Select your instance and then choose Actions → **Security** → **Change security groups**. Attach a security group that allows HTTPS to access the Broker VM Web UI and SSH for remote access when troubleshooting. Make sure to allow these connections to the Broker VM from secure networks only.

Note

Assigning security groups can take up to 15 minutes.

6. Verify the Broker VM has started correctly. On the Instances page, select your instance, and the choose Actions → **Monitor and troubleshoot** → **Troubleshoot** → **Get instance screenshot**. You are directed to your Broker VM console listing your Broker details.
--- # 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-xdr-3.x/cortex-xdr-3.x-documentation/data-management/broker-vm/set-up-and-configure-broker-vm/broker-vm-image-installations/set-up-broker-vm-on-amazon-web-services.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.