icon-unified.svg
Experience Center

Configuring the Zscaler Incident Receiver for Amazon Web Services EC2 VMs

Before you can use a Zscaler Incident Receiver, you must configure the virtual machine (VM) image for the Incident Receiver on an Amazon Web Services (AWS) EC2 instance, on an Azure VM, or an on-premises VM.

To learn more, see Configuring the Zscaler Incident Receiver for Azure VMs and Configuring the Zscaler Incident Receiver for On-Premises VMs.

Deploying a Zscaler Incident Receiver VM on AWS

To deploy a Zscaler Incident Receiver VM on AWS:

  • Before you can configure your Incident Receiver with AWS, you must contact Zscaler Support and request the Zscaler Incident Receiver AMI for your shared AWS account and region. Zscaler Support then provides you with the shared AMI ID and description to use when launching the EC2 instance that hosts the Zscaler Incident Receiver VM. To learn more, refer to the AWS documentation.

    Close

  • To deploy the Zscaler Incident Receiver on an EC2 instance on AWS, you need:

    • Access to one of the following types of storage servers where the Incident Receiver can store files:
    • The Zscaler Incident Receiver Amazon Machine Image (AMI).

    • A minimum t2.medium or t3.medium EC2 instance type.

      The AMI deployment includes minimum specifications for various settings (e.g., disk size and network interface). You can increase those specifications as needed.

    • (Optional) A static public IP address for the VM.

      Zscaler recommends using a static IP address to ensure that the IP address does not change when the VM is rebooted. Alternatively, you can associate the IP address with a fully qualified domain name (FQDN) and then use the FQDN when configuring the Incident Receiver in the Admin Portal.

    • A security group configured on the EC2 instance to allow inbound ICAP messages from the FCC cloud to the correct TCP port on the Incident Receiver VM (e.g., port 1344).
    • A Zscaler Incident Receiver added in the Admin Portal. You need this configuration to complete the VM setup.
    • For Zscaler Incident Receiver to check your network connectivity and get access to and from your IP address, your firewalls must be enabled for the appropriate location. To understand the needed access requirements, see DLP Incident Receiver Connections.
    Close

  • To create a security group in AWS:

    1. Log in to the AWS Management web UI or console.
    2. In the AWS Management console, click the Services icon. The Services navigation menu is displayed.
    3. Go to Compute > EC2. The EC2 Management Console appears, displaying the EC2 Dashboard.
    4. Open a new tab and perform the following steps:
      1. Browse to config.zscaler.com. The Zscaler Config page is displayed.
      2. Select your organization's Zscaler cloud from the Cloud drop-down menu at the top left of the page.
      3. Select DLP Incident Receiver in the left-side navigation, then click the Zscaler Hub IP Addresses link in the Source column of the table. The Hub IP Addresses page is displayed listing all of the outbound connections that need to be configured for the Zscaler Incident Receiver to communicate with the Zscaler cloud.

        Zscaler Hub IP Addresses page

        Close
      4. Click Copy IPs in the Required, Recommended, and Combined columns as needed so you can add them to the security group.
    5. Return to the EC2 Management Console, and go to Network & Security > Security Groups. The Security Groups page is displayed.

      Viewing Security Groups on the Security Groups Page in AWS

      Close
    6. On the Security Groups page, click Create security group in the top right of the page. The Create security group page is displayed.

    7. On the Create security group page:

      • Basic details: Enter a name for the security group in the Security Group Name field.
      • Inbound rules: Add the incoming traffic IPs for the Zscaler Incident Receiver VM. Make sure that you add the IPs that you copied from the Zscaler Hub IP Addresses page earlier.
      • Outbound Rules: Add the outgoing traffic IPs for the Zscaler Incident Receiver VM.

      Viewing a Security Group configuration on the Create Security Group Page in Amazon Web Services

      Close

    8. Click Create security group.

    To learn more, refer to the AWS documentation.

    Close

  • Because the Zscaler Incident Receiver does not store files locally, it requires either an S3 bucket or an SFTP server to store incident data.

    • To use an S3 bucket, you should configure the EC2 VM with an Identity and Access Management (IAM) role for the Incident Receiver EC2 instance so that the instance has list and write access (ListBucket and PutObject, respectively) to the S3 storage volume.

      If you are using your Incident Receiver with Zscaler Workflow Automation, two separate S3 buckets are created for you during the creation of the CloudFormation stack in AWS. If you are not using your Incident Receiver with Zscaler Workflow Automation, you can use a single S3 bucket for data and JSON files, or you can use separate buckets. The following example uses separate S3 buckets.

      To create an AWS IAM role and then associate it with your EC2 Incident Receiver VM:

      1. From the EC2 instance, go to Actions > Security > Modify IAM role. The Modify IAM role page is displayed.
      2. Click Create new IAM role.

        The IAM Management Console Roles page is displayed in a new tab.
      3. Click Create role in the upper right of the page. The Select trusted entity page is displayed.
      4. Select AWS service as the Trusted entity type, then select EC2 in the Common use cases section.

        The Select Trusted Entity page

        Close
      5. Click Next. The Add permissions page is displayed.
      6. Click Create policy in the upper right of the page. The Create policy page is displayed in a new tab.
      7. Click the JSON tab, then paste the contents of one of the following sample JSON files to create a policy with list and write access to the S3 bucket, depending on whether or not you are using AWS KMS Keys.
      8. Click Next: Tags. The Add tags page is displayed.
      9. Specify any optional tags, then click Next: Review. The Review policy page is displayed.
      10. Specify a name and optional description for the policy, review the permissions and tags, then click Create policy.

        Review and create permissions policy for AWS

        Close
      11. Return to the tab where the Add permissions page is displayed.
      12. Click the Refresh button next to the Create policy button, then select the policy you created from the list.
      13. Click Next. The Name, review, and create page is displayed.
      14. Specify a name and optional description for the role, review the permissions for the role, then click Create role.

        The Name, Review, Create page

        Close
      15. Return to the tab where the Modify IAM role page is displayed.
      16. Click the button next to the drop-down menu to refresh the list, then select the IAM role you created from the drop-down menu.
      17. Click Update IAM role.

      To learn more, refer to the AWS documentation.

      Close

    • If you do not use an S3 bucket to store Incident Receiver data, then you must set up a storage server that supports SFTP/SCP and public key authentication. You must also have a preconfigured account that allows write access to the server’s intended directory. You link the SFTP server to the Incident Receiver VM when you configure storage options later in the process.

      Close
    Close

  • To launch an EC2 instance for the Incident Receiver VM:

    1. In the EC2 Management Console, go to Instances > Instances. The Instances page is displayed.
    2. On the Instances page, click Launch instances at the top right of the page. The Launch an instance page is displayed.
    3. (Optional) In the Name and tags section, enter a name for the Incident Receiver VM in the Name field.
    4. In the Application and OS Images (Amazon Machine Image) section:
      1. Click the My AMIs tab.
      2. Select the Shared with me option.
      3. In the Amazon Machine Image (AMI) drop-down menu, select the AMI image that Zscaler Support shared with you.
    5. In the Instance type section, in the Instance type drop-down menu, select the appropriate instance type required for the Incident Receiver VM (e.g., t2.medium or t3.medium). The instance type that you select must allow access to either an EC2 serial console or an instance screenshot.
    6. Specify a Key pair (login) option, based on your organization's requirements.
    7. In the Network settings section, under Firewall (security groups):
      1. Select the Select existing security group option.

      2. In the Security groups drop-down menu, select the security group you previously created.

        AWS automatically assigns the network IP address for the instance. You do not need to enter the IP address information unless it is required by your organization.

    8. Click Launch instance in the lower right of the page. A message is displayed stating that the launch of the instance was successfully initiated and it lists the instance ID that was created.
    9. Right-click on the instance ID, and select Open Link in New Tab. The Instances page is displayed listing the instance with an Instance state of Pending. After a few seconds, the Instance state changes from Pending to Running.

    10. On the Instances page, click the Instance ID. The Instance summary page is displayed. On the Instance summary page you can view the details for the instance, including the IP addresses that were assigned to the instance.

      If you are using a public IP address, when you shut down and restart the instance, the IP address changes.

    11. Find and make note of the initial root password. When the instance state is running, depending on the type of instance you're using, you can get the initial root password either from the instance screenshot (Actions > Monitor and troubleshoot > Get instance screenshot) or from the EC2 serial console. The initial root password for this user is randomly generated.

    To learn more, refer to the AWS documentation.

    Close

  • To configure the Incident Receiver VM:

    1. Ensure that you have added a Zscaler Incident Receiver in the Admin Portal. You need this configuration to complete the VM setup.
    2. Log in to the VM as user zsroot. The initial root password for this user is randomly generated.

    3. Change the root password:

      1. Enter the following command:

        sudo zirsvr change-password

      2. Log in to the newly created Zscaler Incident Receiver.
      3. Enter the initial root password, the one that was randomly generated for you.

      4. Enter a new root password.

      5. Re-enter the new root password.
      6. Go to the Admin Portal and go to Policies > Data Protection > Common Resources > DLP Incident Receiver. Then click the Zscaler Incident Receiver tab.
      7. Locate the Zscaler Incident Receiver you added previously, and under the Certificate column click Download.

    4. Copy over the certificate .zip file to the VM and install it:

      1. In this example, we’re using scp to copy over the file:

        scp <certificate_zip_filename> zsroot@<ip>:/home/zsroot

        For example: scp IncidentReceiverCertificate.zip zsroot@10.66.108.100:/home/zsroot

      2. Enter the following command to install the SSL certificate:

        sudo zirsvr configure ~/<certificate_zip_filename>

        For example: sudo zirsvr configure ~/IncidentReceiverCertifcate.zip

    5. For icaps_port, enter the Zscaler Incident Receiver port number that you’ve previously added to the Zscaler Incident Receiver URI in the Admin Portal.

      (Optional) You can enter a different port number to change the Incident Receiver’s port number. However, you must also update the Incident Receiver’s URI in the Admin Portal to include the new port number. To learn more, see Adding a Zscaler Incident Receiver.

    6. Specify whether the Incident Receiver uses S3 or SFTP storage. For SFTP storage, configure the storage server and public key authentication:

        1. Specify that your organization uses Zscaler Workflow Automation (y).
        2. For storage_s3_region_name, enter the region where the S3 server resides (e.g., ap-east-1).
        3. For storage_s3_data_bucket_name, enter the name of the S3 bucket where the Incident Receiver can store data.
        4. For storage_s3_data_dir, enter a slash (/) to indicate the directory within the S3 bucket where the Incident Receiver can store data. You must enter a slash and not any other directory path. Workflow Automation expects the data to be available in the S3 root directory.
        5. For storage_s3_json_bucket_name, enter the name of the S3 bucket where the Incident Receiver can store JSON files that contain incident details.
        6. For storage_s3_json_bucket_dir, enter a slash (/) to indicate the directory within the S3 bucket where the Incident Receiver can store JSON files that contain incident details. You must enter a slash and not any other directory path. Workflow Automation expects the data to be available in the S3 root directory.

        Close

        1. Specify that your organization does not use Zscaler Workflow Automation (n).
        2. For storage_s3_region_name, enter the region where the S3 server resides (e.g., ap-east-1).
        3. For storage_s3_data_bucket_name, enter the name of the S3 bucket where the Incident Receiver can store data.
        4. For storage_s3_data_dir, enter the directory within the S3 bucket where the Incident Receiver can store data.
        5. Specify whether you want to use a different bucket for JSON files (y/n).
        6. If you are using a different bucket for JSON files, for storage_s3_json_bucket_name, enter the name of the S3 bucket where the Incident Receiver can store JSON files that contain incident details.
        7. If you are using a different bucket for JSON files, for storage_s3_json_bucket_dir, enter the directory within the S3 bucket where the Incident Receiver can store JSON files that contain incident details.

        Close

        1. For storage_sftp_fqdn, enter the FQDN for the storage server.
        2. For storage_sftp_port, enter the upload port of the SFTP server.
        3. For storage_dir, enter the storage server directory.
        4. For storage_sftp_username, enter a username for storage server login.
        5. Enter a password for the username to set up the public key. This password is used temporarily and is not saved.

        If the SFTP server doesn't allow password-based authentication, you receive an error that the service is unable to update the public key on the server. If you receive that error, add the contents of the public key to the authorized_keys file on the SFTP server:

        1. Copy the contents from the file /.ssh/id_ed25519.pub.
        2. On the SFTP server, add the copied content to the end of the following file: /.ssh/authorized_keys.

        3. On the Incident Receiver VM, enter the following command:

          sudo zirsvr configure ~/<certificate_zip_filename>
        Close

      By default, the Incident Receiver Health Check is enabled. The health check notes if there are any changes in behavior and is set to 5 minute intervals. To verify the Health Check is working, you receive the Health Status JSON <systmld>_<iphash>_ir_health_status_timestamp.json file in your evidence folder. If you would like to disable the Health Check, contact Zscaler Support.

      • {
"ipAddress":"10.66.103.169",
"version":"6.3.2404",
"updatedAt":"1726848892",
"systemId":"65533",
"lastIncidentReceivedAt":"1726828921",
"lastFileUploadSuccessAt":"1726828921",
"storageType": "SFTP",
"storageLocation":"/sc/temp",
"healthcheckIntervalInSec":"300"
}
        Close

      If the Zscaler Incident Receiver was configured properly, it:

      • Downloads the latest build
      • Installs the certificate you specified
      • Checks if the service is configured correctly
      • Starts the service

      After the Zscaler Incident Receiver service has started, you can add it to the DLP policy rule. To learn more, see Configuring DLP Policy Rules with Content Inspection, Configuring DLP Policy Rules without Content Inspection, and Configuring the SaaS Security API DLP Policy.

      You can log in to the storage server to see information about DLP policy violations. For each policy violation, the storage server creates a directory containing the policy-violating file and a JSON file for the DLP policy scan metadata.

      Download a sample JSON file for Endpoint DLP policy

      Download a sample JSON file for DLP policy with and without content inspection

      Download a sample JSON file for SaaS Security DLP policy

    Close

  • To configure a load balancer for the Incident Receiver:

    1. In the EC2 Management Console, go to Services > EC2. The EC2 Dashboard page is displayed.
    2. On the EC2 Dashboard page, click Load Balancers on the bottom left of the page.

      The Load balancers page is displayed.
    3. On the Load balancers page, select Create load balancer > Create Network Load Balancer.

      The Create Network Load Balancer page is displayed.
    4. In the Load balancer name field, provide a name for the load balancer.
    5. In the Network mapping section, select one or more availability zones for the load balancer. To learn more, refer to the AWS documentation.
    6. In the Security groups - recommended drop-down menu, select the security group you created for the Incident Receiver.
    7. In the Listeners and routing section, select TCP as the Protocol, and enter 1344 as the Port.
    8. Click Create target group.

      The Specify group details page is displayed on a new browser tab.
    9. On the Specify group details page:
      1. In the Choose a target type section, select Instances.
      2. In the Target group name field, specify a name for the target group.
      3. Select TCP as the Protocol, and enter 1344 as the Port.
      4. In the Health checks section, select TCP from the Health check protocol drop-down menu.
      5. Click Next.

        The Register targets page is displayed.
    10. On the Register targets page, select the Incident Receiver from the Available instances list, then click Include as pending below.

      Close

      The Incident Receiver appears in the Review targets list.
    11. Click Create target group.

      Close

      A confirmation page is displayed.

      Target group confirmation page.

      Close
    12. Return to the browser tab where the Create Network Load Balancer page is open.
    13. In the Listeners and routing section, click the Refresh button next to the Default action drop-down menu, then use the drop-down menu to select the target group you created.
    14. Click Create load balancer.

      A confirmation page for the load balancer appears.
    15. On the confirmation page for the load balancer, click View load balancer.

      The Load balancers page is displayed.
    16. On the Load balancers page, click the name of the load balancer you created.

      Close

      The Load balancer details page is displayed.
    17. On the Load balancer details page, in the DNS name section, click the Copy DNS name to clipboard button.
    18. Go to the Admin Portal and go to Policies > Data Protection > Common Resources > DLP Incident Receiver. Then click the Zscaler Incident Receiver tab.
    19. Locate the Zscaler Incident Receiver you added previously, and click the Edit icon.
      The Edit Zscaler Incident Receiver page is displayed.
    20. On the Edit Zscaler Incident Receiver page, in the Server URI field, paste the DNS name for the load balancer (i.e., icaps://<DNS Name>).

      The Incident Receiver is updated to use the AWS load balancer.
    Close

Updating and Customizing a Deployed Zscaler Incident Receiver VM

With your Incident Receiver VM running, you can update and customize the VM based on your organization's needs.

  • If you have successfully configured the service, the service automatically downloads the latest build before it starts. To manually update the service:

    1. Enter the following command to stop the service:

      sudo zirsvr stop

    2. Enter the following command to install the update:

      sudo zirsvr update-now

    3. Enter the following command to start the service:

      sudo zirsvr start
    Close

  • To run the Incident Receiver in explicit proxy mode:

    1. Log in to the VM as user zsroot

    2. Enter the following command:

      sudo zirsvr configure-proxy
    3. For Do you require a proxy server configuration? enter y and press Enter.
    4. For proxyserver enter the IP address of your proxy server (e.g., proxy.zscaler.net) and press Enter.
    5. For proxyport enter your proxy port number (e.g., 1344) and press Enter.

    The VM then tests the connection and when this is successful, the configuration is complete.

    To remove the explicit proxy configuration:

    1. Enter the following command:

      sudo zirsvr configure-proxy
    2. For Do you require proxy server configuration? enter n and press Enter.
    3. For Do you want to delete current proxy configuration? enter y and press Enter.

    Requirements for Explicit Proxy Mode

    If you're using explicit proxy mode, DNS and NTP connections are not tunneled, meaning, you need an internal DNS server to run in this mode. The Zscaler Incident Receiver needs to have DNS resolution for the current Master CA IP, update server, and the NTP server. The Zscaler Incident Receiver host also needs to be able to query a DNS server to resolve the following:

    • smcacluster.<cloudname>
    • update1.<cloudname>
    • update2.<cloudname>
    • zdistribute.<cloudname>
    • The NTP server. By default, the VM has the following FQDNs for NTP servers configured:
      • 0.freebsd.pool.ntp.org
      • 1.freebsd.pool.ntp.org
      • 2.freebsd.pool.ntp.org

    You can override these FQDNs to your internal IP address in your DNS server configuration or using other methods.

    In addition, since the proxy configuration doesn't allow authentication, you need to configure the proxy server to allow specific IP/MAC addresses without user and password authentication.

    Close

  • You can use the Mutual Transport Layer Security (MTLS) method to support client authentication for the Zscaler Incident Receiver. MTLS is a method for mutual authentication. It ensures that parties at each end of the connection are who they claim to be. Zscaler provides the MTLS CA Certificate for the Zscaler Incident Receiver and you have the option to enable mutual authentication for the Zscaler Incident Receiver, which then uses this certificate for client authentication.

    To run the Incident Receiver VM with mutual transport security enabled:

    sudo zirsvr restart
    1. Log in to the VM as user zsroot.
    2. Enable MTLS by updating the icap_mtls_enabled parameter to 1 (icap_mtls_enabled=1). By default, this parameter is disabled.
    3. Enter the following command to restart the Zscaler Incident Receiver service:
    Close

  • You can configure the Zscaler Incident Receiver VM to allow multiple simultaneous SFTP connections if you notice that SFTP upload is slower than expected or if you notice that the Zscaler Incident Receiver internal queue is full. You can find the logs for the Incident Receiver internal queue at /sc/log/zirsvr.log. To configure this setting:

    1. Log in to the VM as user zsroot.
    2. Specify the number of simultaneous SFTP connections by updating the storage_sftp_conn_max parameter to a value from 1-16 (e.g., storage_sftp_conn_max=2). This parameter has a value of 1 by default.

    3. Enter the following command to restart the Zscaler Incident Receiver service:

      scp sudo zirsvr restart
    • Be sure to conduct thorough end-to-end testing before enabling this setting in your production environment.
    • If changing this setting does not solve the problem of the Zscaler Incident Receiver internal queue filling up, you may also need to increase the specifications on your SFTP server to ensure faster throughput, or you may need to configure multiple incident receivers with load balancing.
    • If you need assistance enabling this setting in your environment, contact Zscaler Support.
    Close

  • An admin can request remote assistance and allow Zscaler Support to log in to an Incident Receiver without having to open a firewall connection for inbound traffic. This feature is disabled by default and must be enabled explicitly for the duration that remote support assistance is required.

    • To enable Zscaler Support to access your Incident Receiver:

      sudo zirsvr support-access-start

      This command creates a long-lived SSH tunnel to the Zscaler cloud and sets up remote port forwarding. Zscaler Support can then use this tunnel to log in to your Incident Receiver.

    • To disable Zscaler Support access to your Incident Receiver:

      sudo zirsvr support-access-stop

      This command brings down the long-lived SSH tunnel to the Zscaler cloud and all the remote connections.

    • To check the status of the Zscaler Support access to your Incident Receiver:

      sudo zirsvr support-access-status
    Close

  • If your organization requires you to update your SSH key, upgrade to the ED25519 key. To upgrade:

    1. Run the following command:

      sudo zirsvr troubleshoot

      If you see the following warning, you must update your SSH key:

      Checking SFTP server connection
	 External SFTP server is configured as ...
	 SFTP server is setup correctly, connection, read, and write are all successful. However, disk quota is not checked.
	 Warning: SFTP is configured with older key type "rsa", consider upgrading it to newer keytype "ed25519" using command "sudo zirsvr update-sshkey". If your SFTP server is a Windows based server, please read SFTP server's Admin Guide.

      You can do a snapshot of your VM before executing the following command.

    2. Run the following command:

      sudo zirsvr update-sshkey

      If the SSH key was migrated correctly:

      • It creates an SSH key with ED25519 to the file authorized_keys under the directory /home/zsroot/.ssh.
      • It adjusts the file /sc/conf/sc.conf to use the new ED25519 key.

      • On a Linux-based SFTP server, it uses a new public key.

        If your SFTP server doesn't support ssh-copy-id, you receive a message that the operation was unsuccessful. To update the SSH public key with the new ED25519 key, contact Zscaler Support.

    Close

Zscaler Incident Receiver Commands

You can use the following commands to configure, update, and troubleshoot your VM.

  • CommandDescription
    sudo zirsvr stopStops the Zscaler Incident Receiver service.
    sudo zirsvr startStarts the Zscaler Incident Receiver service.
    sudo zirsvr update-nowUpdates the Zscaler Incident Receiver service. The service must be stopped before you can run this command.
    sudo zirsvr configure-s3Updates the S3 bucket used by the Incident Receiver.
    sudo zirsvr configure-sftpUpdates the SFTP server used by the Incident Receiver.
    sudo zirsvr restartRestarts the Zscaler Incident Receiver service.
    sudo zirsvr statusDisplays whether the Zscaler Incident Receiver service is running or stopped.
    sudo zirsvr force-update-nowForces the Zscaler Incident Receiver service to update to the latest version regardless of what version is on the VM. The service is automatically stopped before the update begins.
    sudo zirsvr troubleshootRuns a series of checks to help troubleshoot issues, such as checking the installed certificate, the zcloud server configuration, all services, and whether or not an update is needed.
    sudo zirsvr collect-diagnosticsCreates a file with diagnostic information to send to Zscaler Support for troubleshooting purposes.
    sudo zirsvr configure-syslog-serverConfigures external syslog server forwarding on the Zscaler Incident Receiver to forward file SFTP events and to log any critical changes to the configuration files monitored by the Incident Receiver. The external syslog server forwarding happens over UDP port 514, which cannot be modified.
    sudo zirsvr install-server-certInstalls server certificates.
    sudo zirsvr update-sshkeyCreates a new SSH key and updates Zscaler Incident Receiver to use the new SSH key as authentication.
    Close
Related Articles
About Zscaler Incident ReceiverAdding a Zscaler Incident ReceiverModifying a Zscaler Incident ReceiverConfiguring the Zscaler Incident Receiver for On-Premises VMsConfiguring the Zscaler Incident Receiver for Amazon Web Services EC2 VMsConfiguring the Zscaler Incident Receiver for Azure VMsAbout ICAP Receivers for DLPAbout ICAP Communication Between Zscaler and DLP ServersEnabling Secure ICAPEnabling Unencrypted ICAPAdding an ICAP Receiver for DLPConfiguring the ICAP Server with the Mutual Transport Layer Security (MTLS) CA Certificate