icon-zia.svg
Secure Internet and SaaS Access (ZIA)

Configuring the Zscaler Incident Receiver for On-Premises VMs

New or clean deployment of Zscaler Incident Receiver requires a virtual machine (VM) image running on Zscaler OS version 24.

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

To learn more, see Configuring the Zscaler Incident Receiver for Amazon Web Services EC2 VMs and Configuring the Zscaler Incident Receiver for Azure VMs.

Deploying a Zscaler Incident Receiver VM on an On-Premises VM

To deploy a Zscaler Incident Receiver VM on an on-premises VM:

  • To deploy the Zscaler Incident Receiver, you need:

    • Access to one of the following types of storage servers where the Incident Receiver can store files:
      • 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.
      • An Amazon S3 storage bucket where the Incident Receiver can store data.

    Zscaler recommends using an SFTP storage server to store data for on-premises Incident Receiver VMs. To use an S3 storage bucket with an on-premises VM, you must set up an S3 credentials file on the VM where the Incident Receiver resides. For this method, manually create a /root/.aws/credentials file and a /home/zsroot/.aws/credentials file with the proper aws_access_key_id and aws_secret_access_key on the VM. To learn more, refer to the AWS documentation.

    • A static public IP address for the Incident Receiver VM. Additionally, you need a firewall rule configured to allow inbound ICAP messages from the FCC cloud to the correct TCP port on the Incident Receiver VM (e.g., port 1344).
    • VM specifications:
      • Hypervisor: VMware ESX/ESXi version 6.0 or later, Oracle VM VirtualBox
      • CPUs: 4 CPUs
      • RAM: 8 GB
      • Disk: 600 GB
      • VM Network: 1 Virtual NIC
    • 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

  • Before you configure the Zscaler Incident Receiver VM, you must download it.

    To download the VM:

    1. In the ZIA Admin Portal, go to Administration > DLP Incident Receiver.
    2. Click the Zscaler Incident Receiver tab.
    3. Click Download Incident Receiver.

    Close

  • To configure the Incident Receiver VM:

    1. Make sure you have added a Zscaler Incident Receiver in the ZIA Admin Portal. You need this configuration to complete the VM setup.
    2. In your hypervisor, install the Incident Receiver VM you downloaded previously.
    3. Log in to the VM as user zsroot. The initial root password for this user is randomly generated.

    1. Change the root password:
      1. Enter the following command:
    sudo zirsvr change-password

    1. Enter the initial root password, the one that was randomly generated for you.
    2. Enter a new root password.

    1. Re-enter the new root password.
    2. Configure the network:
      1. Enter the following command:
    sudo zirsvr configure-network
    1. For nameserver, enter c to change the IP address and press Enter.
    2. Enter the IP address and press Enter.
    3. If you want to add a new nameserver enter y, otherwise enter n, and press Enter.
    4. Optionally, you can use DHCP to obtain the IP address and default router information. If there’s no DHCP server, you can configure the IP address and default router information manually.
    5. Enter the VM hostname.

    The VM restarts the network and checks the connection.

    1. Go back to the ZIA Admin Portal and go to Administration > DLP Incident Receiver. Then click the Zscaler Incident Receiver tab.
    2. Locate the Zscaler Incident Receiver you added previously, and under the Certificate column click Download.

    1. 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

    1. Enter the following command to install the SSL certificate:
    sudo zirsvr configure ~/<certificate_zip_filename>

    For example: sudo zirsvr configure ~/IncidentReceiverCertifcate.zip

    1. For icaps_port, enter the Zscaler Incident Receiver port number that you’ve previously added to the Zscaler Incident Receiver URI in the ZIA 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 ZIA Admin Portal to include the new port number. To learn more, see Adding a Zscaler Incident Receiver.

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

        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>

        1. Specify whether your organization uses Zscaler Workflow Automation (y/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. 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 the directory within the S3 bucket where the Incident Receiver can store JSON files that contain incident details.

        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 DLP policy with Evaluate All Rules mode enabled

    Download a sample JSON file for SaaS Security DLP policy

    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
    1. Enter the following command to install the update:
    sudo zirsvr update-now
    1. 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-network
    1. For Do you require a proxy server configuration? enter y and press Enter.
    2. For proxyserver enter the IP address of your proxy server (e.g., proxy.zscaler.net) and press Enter.
    3. 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-network
    1. For Do you require proxy server configuration? enter n and press Enter.
    2. 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:

    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:
    sudo zirsvr restart
    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-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.
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