icon-unified.svg
Experience Center

Deploying Branch Connector with Hyper-V

This deployment guide provides information on prerequisites, how to deploy Zscaler Branch Connector as a virtual machine (VM) on Hyper-V platforms, and post-deployment configurations.

Infrastructure as Code (IaC) deployment templates are not available for Branch Connector deployment on Hyper-V platforms.

Prerequisites

The role that you assign dictates the level of access an admin has to the Admin Portal. Zscaler provides a default admin account that provides full access to the portal and scope over the entire organization. Admins must have full access to Branch Connector configuration permissions to perform the procedures in this article. To learn more, see About Role Management and Adding Admin Roles.

Make sure the following prerequisites are met:

  • In the Admin Portal, create a dedicated username for the Branch Connector deployment.
  • In the Admin Portal, create a dedicated password for the Branch Connector deployment. The password must be at least 8 characters in length and include at least one uppercase letter, one number, and one special character. The password must not contain a $, &, >, <, ;, ', or ". If the password does not meet these requirements, the deployment fails.
  • Configure a Branch Provisioning Template and copy the Branch Provisioning URL for later use.
  • Download the Branch Connector Virtual Hard Disk v2 (VHDX) image from the Branch Connector Images page for Hyper-V.
  • Branch Connector uses an API key to authenticate and register the VM with the Zscaler service. If you do not already have an API key, generate a new key. Then copy the API key from the API Keys page.
  • Review the following Branch Connector specifications and sizing requirements:
    • Small VM: Requires 4 GB of memory, two CPU cores, 128 GB data disk size, and two network interface cards (NICs).
    • Medium VM: Requires 8 GB of memory, 4 CPU cores, 128 GB data disk size, and 4 NICs.
  • If a Hyper-V switch does not already exist, create one.
  • VM specification for Branch Connector deployed in high availability (HA): MAC Address Spoofing must be enabled on each network adapter.

Creating and Applying User Data

You must create user data information for your Branch Connector VM. You can either apply this information to the VM in the Hyper-V Manager UI with an ISO file that is mounted via a virtual CD-ROM drive or apply it manually in the VM console in the /etc/cloud/cloud.cfg.d/ directory. For both methods, you must create a text file containing the user data.

  1. Create your user data in a text file named userdata.cfg using one of the following templates, formatted in YAML:

    • ZSCALER:
  cc_url: <CC_URL>
  http_probe_port: 50035 #Optional to change the port for load balancer status checks from the default value 50001 to 50035.
  api_key: <API Key>
  password: <Admin Password>
  username: <Admin Username>
network: 
  config:
  - name: hn0
    type: physical
    subnets:
    - type: dhcp
  version: '1'
#ssh keys are optional
ssh_authorized_keys: 
  - ssh-rsa <Key>

      ZSCALER:
  cc_url: connector.zscaler.net/api/v1/provUrl?name=DemoBC
  api_key: adfads2sd
  password: demopass
  username: bac-demoadmin@12345689.zscaler.net
network: 
  config:
  - name: hn0
    type: physical
    subnets:
    - type: dhcp 
  version: '1'
      Close

      ZSCALER:
  cc_url: connector.zscaler.net/api/v1/provUrl?name=DemoBC
  http_probe_port: 50035
  api_key: adfads2sd
  password: demopass
  username: bac-demoadmin@12345689.zscaler.net
network: 
  config:
  - name: hn0
    type: physical
    subnets:
    - type: dhcp 
  version: '1'
ssh_authorized_keys: 
  - ssh-rsa ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCh3ru9CCnEow69WlQyJuxvZJGHcjhcgJzp8XnoKTJk6o1bit+rq4BNyjS0orauMF6fNMHAyGZqDWw6RICvoeh386xNqnD7+AGE9VGz4cPv0CjoV2HvkKnA2Dj8KZFFJ/bBV0BndNdGATsbDnhq0wkJ+WXFmamb9kx4dSDL5ZD15SybFop0b/3JoqXoU+9pxFc0bQ/cediaifCztliI9i7NAmvIUinLy2OlDW/uPEcB8nBgXhAAc9ALe6+Q4wZt8JUdrcF04bgoAHYsNuzyEk4dNvov97JyExCAwzSLomiHFtdzhGw7/o6KhfhxxBRodKy4wQBwDzPbD6EbN9iCqoK8DY4HZ2L7HyQKRjhnnY/Y0uldO0tleogElbk+4LsoyAPjPAbogu89xSOa6D7sl2G+dPpqTlFBmO/3m/2JhBnGU= admin@branchpc
      Close

      Close
    • ZSCALER:
  cc_url: <CC_URL>
  http_probe_port: 50035 #Optional to change the port for load balancer status checks from the default value 50001 to 50035.
  api_key: <API Key>
  password: <Admin Password>
  username: <Admin Username>
network: 
  config:
  - name: hn0
    type: physical
    subnets:
    - address: <IP Address/Netmask>
      gateway: <Gateway>
      type: static
  - type: nameserver
    address: 
    - <IP Address>
    - <IP Address>
    search:
    - zscaler.net
  version: '1'
#ssh keys are optional 
ssh_authorized_keys:  
- ssh-rsa <Key>


      ZSCALER:
  cc_url: connector.zscaler.net/api/v1/provUrl?name=DemoBC
  api_key: adfads2sd
  password: demopass
  username: bac-demoadmin@12345689.zscaler.net
network: 
  config:
  - name: hn0
    type: physical
    subnets:
    - address: 10.66.118.71/24
      gateway: 10.66.118.254
      
      type: static
  - type: nameserver
    address:
    - 8.8.8.8
    - 8.8.4.4
    search:
    - zscaler.net
  version: '1'
      Close

      ZSCALER:
  cc_url: connector.zscaler.net/api/v1/provUrl?name=DemoBC
  http_probe_port: 50035
  api_key: adfads2sd
  password: demopass
  username: bac-demoadmin@12345689.zscaler.net
network: 
  config:
  - name: hn0
    type: physical
    subnets:
    - address: 10.66.118.71/24
      gateway: 10.66.118.254
      
      type: static
  - type: nameserver
    address:
    - 8.8.8.8
    - 8.8.4.4
    search:
    - zscaler.net
  version: '1'
ssh_authorized_keys:  
  - ssh-rsa ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQCh3ru9CCnEow69WlQyJuxvZJGHcjhcgJzp8XnoKTJk6o1bit+rq4BNyjS0orauMF6fNMHAyGZqDWw6RICvoeh386xNqnD7+AGE9VGz4cPv0CjoV2HvkKnA2Dj8KZFFJ/bBV0BndNdGATsbDnhq0wkJ+WXFmamb9kx4dSDL5ZD15SybFop0b/3JoqXoU+9pxFc0bQ/cediaifCztliI9i7NAmvIUinLy2OlDW/uPEcB8nBgXhAAc9ALe6+Q4wZt8JUdrcF04bgoAHYsNuzyEk4dNvov97JyExCAwzSLomiHFtdzhGw7/o6KhfhxxBRodKy4wQBwDzPbD6EbN9iCqoK8DY4HZ2L7HyQKRjhnnY/Y0uldO0tleogElbk+4LsoyAPjPAbogu89xSOa6D7sl2G+dPpqTlFBmO/3m/2JhBnGU= admin@branchpc
      Close

      Close

  2. Apply your user data to the VM in one of the following ways:

      1. Apply the user data to the VM as an ISO image:

        • On Centos, install the genisoimage:

          sudo yum install genisoimage

        • On Ubuntu, install the genisoimage:

          sudo apt install genisoimage

      2. Configure the required user data.

        The user data file must be named user-data.

        zuser@hostname:~$ mkdir isodir
zuser@hostname:~$ cat > isodir/user-data <<EOF #cloud-config
<TEXT FROM TEXT FILE>
EOF
user@hostname:~genisoimage -o user-data.iso -r isodir/user-data

        You attach the ISO to your Branch Connector VM in the Deploying the Branch Connector procedure.

      Close

    • You apply your user data at the end of the Deploying the Branch Connector procedure.

      Close

Deploying the Branch Connector

After you have met all the prerequisites, created user data, and applied user data to the VM (if you used the ISO method), perform the following procedure to deploy your Branch Connector with Hyper-V.

  1. In Hyper-V Manager, right-click your desired host and select New > Virtual Machine.

  2. Complete the New Virtual Machine Wizard.
    1. If the Before You Begin tab is displayed, click Next.

    2. On the Specify Name and Location tab, enter the name and location. Then click Next.

    3. On the Specify Generation tab, select Generation 1 as the VM generation to support your VHDX file. Then click Next.

    4. On the Assign Memory tab, in the Startup memory field, enter 4096 for a Small VM or 8192 for a Medium VM. Deselect the Use Dynamic Memory for this virtual machine checkbox. Then click Next.

    5. On the Configure Networking tab, select the virtual switch you want the provided network adapter to use. Then click Next.

    6. On the Connect Virtual Hard Disk tab, select Use an existing virtual hard disk and select the location you specified for the VHDX file you downloaded earlier. Then click Next.

    7. On the Summary tab, review the information and then click Finish.

  3. In Hyper-V Manager, right-click the VM and select Settings > Hardware.

    1. Select Processor. In the Number of virtual processors field, select 2 for a Small VM or 4 for a Medium VM. Then click Apply.

    2. If you applied user data to the VM using the ISO Method, select the DVD drive under IDE Controller 1. Select Image file and map the userdata ISO file you created in the ISO Method procedure to the DVD drive. Then click Apply.

    3. Select Add Hardware > Network Adapter and then click Add. Create two network adapters for a Small VM or 4 network adapters for a Medium VM. For each adapter, select the required virtual switch. If you require VLAN tagging, select the VLAN ID checkbox. Then click Apply.

    4. For each network adapter, click + and select Advanced Features. Under MAC address, select the Enable MAC address spoofing checkbox. Then click Apply.

      MAC address spoofing must be enabled for high availability (HA) deployments. Zscaler recommends that you enable MAC address spoofing for non-HA deployments, as well.

    5. Select BIOS. In the boot device Startup order list, move IDE above CD. Then click OK.

  4. In Hyper-V Manager, right-click the VM and select Start.

  5. If you are using the Manual Method to apply user data to the VM:

    1. In the VM console, create a new userdata.cfg file:

      zsroot@zscaler_node : ~ > sudo ee /etc/cloud/cloud.cfg.d/userdata.cfg

    2. Paste in the contents of your user data file.
    3. Press Esc (Escape) to exit the editor.
    4. Press a to leave the editor.
    5. Press a to save the file.

    6. Reboot the VM:

      zsroot@zscaler_node : ~ > sudo reboot

Close

Managing the Branch Connector

After your VM is fully deployed, you can manage the Branch Connector VM from the Admin Portal. A deployed VM is displayed in the dashboard. The Cloud & Branch Connector Monitoring page provides information on the name, group, location, geolocation, and status of the VMs deployed in your branch account.

After verifying deployment, you can configure the following policies:

Related Articles
Downloading Branch Connector ImagesDeployment Templates for Branch Connector & App ConnectorDeploying Branch Connector on VMware PlatformsDeploying Branch Connector & App Connector on VMware PlatformsDeploying Branch Connector with Linux KVMDeploying Branch Connector & App Connector with Linux KVMDeploying Branch Connector with Hyper-VDeploying Branch Connector & App Connector with Hyper-VHandling DNS Resolutions for Zscaler Branch Connector