Setting up Cumulocity IoT Edge

This document describes how to set up Cumulocity IoT Edge, the local version of Cumulocity IoT Core, in a Virtual Machine (VM).

Requirements

Installation requirements

Item Details
Hypervisor - VMWare ESXi 6.5 and 6.7
- VMware Workstation Player 15.x
- Hyper-V on Microsoft Windows 10 Pro and Windows 10 Enterprise, version 1809
- Virtualbox version 5.2.8, to be downloaded from https://www.virtualbox.org
Info: Support for VirtualBox is deprecated and it is not recommended to be used in a production environment. The Virtualbox version 5.2.8 can be used only for testing.
Edge VM image To be downloaded from the Software AG Empower portal, based on the target hypervisor.
For VMware (ESXi and Workstation Player), download all the 4 files of VMware (ovf, mf and two disks vmdk files).
For Hyper-V, download the ZIP file.
For VirtualBox, download the OVA file.
Cumulocity IoT Edge license file To request the license file for Cumulocity, please contact the logistics team for your region:
- North and South America: LogisSrvus@softwareagusa.com
- All Other Regions: LogisticsServiceCenterGER@softwareag.com
In the email, you must include
- your company name, under which the license has been bought
- the domain name (e.g. myEdge.domain.com), under which Cumulocity IoT Edge will be reachable
For more information, see Domain name validation for Edge license key generation.
SSL key and SSL certificate Use your internal or an external CA (Certification Authority) to create these.
Apama license The Apama license key is provided as part of your purchase. To request the license keys for your Apama purchase, please contact the logistics team for your region:
- North and South America: LogisSrvus@softwareagusa.com
- All Other Regions: LogisticsServiceCenterGER@softwareag.com
The Apama license is optional and NOT required for an Cumulocity IoT Edge installation.
DNS entry The DNS (Domain Name System) is used to resolve human readable host names like www.cumulocity.com to machine readable IP addresses like 192.198.1.10.
If you want to connect to Edge VM within your LAN, the DNS entry has to be added for the domain name (URL under which Cumulocity IoT Edge can be reached) with the IP address of the host.
Edge cloud remote access To connect and manage one (or multiple) Edge devices to your Cumulocity IoT cloud tenant, you need an active Cumulocity IoT standard tenant with the Data Broker and Cloud Remote Access extensions.
Info: The Edge cloud remote access is an optional feature in Cumulocity IoT Edge.

Domain name validation for Edge license key generation

To procure the Cumulocity IoT Edge license file, you must provide the right domain name to the Software AG’s logistics team for Edge license key generation.

When you provide the domain name, consider the following points:

Network connectivity

The following network ports must be reachable from the local network:

If Cumulocity IoT Edge should communicate with the cloud, the following ports of www.cumulocity.com (or another instance) need to be available:

There is no internet connection required during installation. Internet connection during runtime is optional, and only used if this is configured in the Data Broker.

Incoming traffic

The following ports need to be enabled by default in order to accept traffic from users and devices on the internet (also refer to “Setting up port forwarding” in Setting up the environment):

Source IP Source Port Destination IP Destination Port Service
any any Edge VM IP TCP/80 HTTP
any any Edge VM IP TTCP/443 HTTPS
any any Edge VM IP TCP/1883 MQTT
any any Edge VM IP TCP/8883 MQTT/TLS

Depending on additional integrations more ports must be opened.

Outgoing Traffic

The core node must be able to connect to the internet. Ports required to outside are:

Service Port
HTTP 80
HTTPS 443

Depending on the installed integrations (email, SMS, etc.) different ports might have to be opened in order to make these services available to the Cumulocity platform. The descriptions of these ports are delivered with the corresponding integrations.

Depending on the DNS and NTP setup it might be the case that DNS (UDP/53) and NTP (UDP/123) connections to the internet must be possible from all hosts.

Hardware requirements

The virtual machine has the following hardware requirements:

Info: This does not cover host OS hardware requirements.

Setting up the environment

For your convenience, we provide the hypervisor examples for setting up Cumulocity IoT Edge:

Info: VirtualBox support is deprecated, so it is not recommended to use it in a production environment.

VM login details

SSH login into Cumulocity IoT Edge is allowed through the “admin” user. All operational activities described in this guide need to be carried out through the admin user.

Use the following login credentials for SSH login into the Edge instance:

Use the following command to log into Edge server via SSH:

ssh admin@<IP address>
	
$ Password: manage

Use the IP address provided during network configuration.

Hypervisor Default IP Address
Virtual Box 192.168.56.120
Hyper-V 192.168.66.10

Info: Root access is not supported in the Edge VM instance. Changes made as root user might cause failure of the described operational procedures. Moreover, the Edge VM is tested and validated with the configuration shipped (i.e. OS version/patch level, other components compatibility etc). Root access would alter Cumulocity IoT Edge to an unknown and not tested configuration and handling support tickets would no longer work.

Configuration

Preparation

Copy the Edge license, SSL key, SSL certificate and Apama license (if obtained) into the Edge VM. Use WINSCP, SCP, FTP or any other file transfer tool to transfer the files from your host OS to Edge VM (Linux OS).

You can copy the files to the Edge VM folder /home/admin.

The files have the following extensions:

Important: Do not rename the license file received from Cumulocity support. Renaming the license file causes failure of the post-installation process.

Preparing the Cumulocity post-installer configuration file

The post-installer configuration file is a key-value based configuration file which acts as input to the post-installation script while configuring the EDGE server.

A template of this configuration file is placed within the EDGE VM under /opt/c8y/utilities/post-installer/ as config.dat. In order to use this, you need to update the file with the correct values.

Important: This template file is overwritten if the post-installation script is invoked and inputs are entered manually through console. Therefore it is advisable to copy this template file to a different location and edit the same.

The following keys are available in the configuration file:

tenant.admin.username : Provide a new username for the tenant admin. This username is later used to login to the system using the web browser.

tenant.admin.password : Provide a new password for the tenant admin username. This password is later used to login to the system using the web browser.

Info: The password should be base64-encoded only. For example, if you want the password to be edge@123 then the encoded value ZWRnZUAxMjM= should be used in the configuration file.

Important: The password must have a minimum of 8 and a maximum of 32 characters and it may contain letters, numbers or any of these symbols: `~!@#$%^&*()_|+-=?;:'",.<>{}[]/

tenant.domain.name : Provide a fully qualified domain name. For example, “myown.iot.com”. Here, you must have the Cumulocity IoT Edge license for the domain name iot.com or myown.iot.com.
The domain name must adhere to all the domain name validation rules as described in Domain name validation.

Important: Once configured, the domain name cannot be changed. Make sure to use the name finally desired.

ssl.certificate : Provide the absolute path of the SSL certificate file. The file extension should either be “.crt” or “.cert”. For example, /home/admin/myown-iot-com.crt. Make sure that the file path is valid and the file exists in the local machine.

Info: The SSL certificate that you provide here must be valid for the domain name that you have provided in the previous step.

ssl.certificate.key : Provide the absolute path of the SSL certificate key file. The file extension must be “.key.”. For example, /home/admin/myown-iot-com.key. Make sure that the file path is valid and the file exists in the local machine.

Info: The SSL key that you provide here must be valid for the domain name that you have provided in the previous step.

c8y.license : Provide the absolute path of the license file. The file extension must be “.licence”. For example, /home/admin/myown.iot.com.licence. Make sure that the file path is valid and the file exists in the local machine.

apama.license : Provide the absolute path of the Software AG Apama license file. The file extension must be “.xml”. For example, /home/admin/ApamaServerLicense101.xml.

This is an optional license file, in case you do not want to use it you should leave this field empty. If the file path is specfied, make sure that the file path is valid and the file exists in the local machine.

The following parameters are required only if you want to update the network parameters in the EDGE VM. You may skip these parameters if network is already configured or it is not applicable in your case.

network.ip : Provide the new IP address for the ethernet interface. For example, 192.168.56.120

netmask : Provide the netmask IP for your network. For example, 255.255.255.0

gateway.ip : Provide the gateway IP for your network. For example, 192.168.56.1

dns.server.ip : Provide the DNS Server IP for your network. For example, 192.168.56.1

Info: If the DNS Server IP is unknown, you can enter the previously entered gateway IP here. If any of the network parameters are not available, contact your network administrator.

Configuring the Edge server

Once Edge VM is started, you need to run the script post_installation.sh to configure the Edge server. The post-installation script is available in the folder /opt/c8y/utilities.

Post installation should only be run after the platform initialization is successful which can be checked by running below REST API:

Usually the platform comes up within 2 minutes.

  1. Browse to the folder /opt/c8y/utilities.

    $ cd /opt/c8y/utilities

  2. Run the following command and provide the password when prompted.

    $ su admin

    $ Password: <Enter password for admin user>

  3. Run the script post_installation.sh.

    $ sudo ./post_installation.sh

You will be prompted to select one of the following options:

  1. Configure network
  2. Run post-installation
  3. Update license and SSL certificates
  4. Run post-upgrade
  5. Expand data disk size
  6. Update tenant password
  7. Configure Edge Agent
  8. Exit

Important:

Option 1 - Configure network

Important: This task needs to be invoked from within the VM and cannot be invoked through a remote connection.

First, select the type of input you want to use.

* Enter [F] to take input from file or [C] to take input from console:

You have the choice to enter the network parameters manually through the console or through a file.

Console input
  1. Provide the new IP address for the ethernet interface. For example, 192.168.56.120
`* Enter new IP address for ethernet interface:`
  1. Provide the netmask IP for your network. For example, 255.255.255.0

    * Enter netmask:

  2. Provide the gateway IP for your network. For example, 192.168.56.1

    * Enter gateway IP:

  3. Provide the DNS Server IP for your network. For example, 192.168.56.1

    * Enter DNS Server IP:

    Info: If the DNS Server IP is unknown, you can enter the previously entered gateway IP here. If any of the network parameters are not available, contact your network administrator.

File input

Provide the absolute path of the configuration file. The network parameters will be loaded from the file. In case of any incorrect parameters, the utility will fall back to console mode and will prompt the user to enter the parameters as described above.

* Enter existing file path containing network parameters:

Confirm to continue with the network configuration process.

The network configuration process consists of multiple steps which are executed sequentially. After a step has been executed, its status will be shown on the console. In case of any failure in any of the steps, the process will halt and a failure message will be displayed on the console.

Option 2 - Run post-installation

First, select the type of input you want to use.

* Enter [F] to take input from file or [C] to take input from console:

You have the choice to enter the post-installation parameters manually through the console or through a file.

Console input
  1. Provide a new username for the tenant admin. This username is later used to login to the system using the web browser.

    * Enter tenant admin username:

  2. Provide a new password for the “tenant admin username”. This password is later used to login to the system using the web browser.

    * Enter tenant admin password:

    Info: The password must have a minimum of 8 and a maximum of 32 characters and it may contain letters, numbers or any of these symbols: `~!@#$%^&*()_|+-=?;:'",.<>{}[]/

  3. Re-enter the previously entered password to confirm it.

    * Re-enter tenant admin password:

  4. Provide a fully qualified domain name. For example, “myown.iot.com”. Here, you must have the Cumulocity IoT Edge license for the domain name iot.com or myown.iot.com.
    The domain name must adhere to all the domain name validation rules as described in Domain name validation.

    * Enter tenant domain name:

    Important: Once configured, the domain name cannot be changed. Make sure to use the name finally desired.

  5. Provide the absolute path of the SSL certificate file. The file extension should either be “.crt” or “.cert”. For example, /home/admin/myown-iot-com.crt.

    * Enter domain ({your-domain-name}) SSL certificate file path (*.crt|*.cert):

    Info: The SSL certificate that you provide here must be valid for the domain name that you have provided in the previous step.

  6. Provide the absolute path of the SSL certificate key file. The file extension must be “.key.”. For example, /home/admin/myown-iot-com.key.

    * Enter domain ({your-domain-name}) SSL certificate key file path (*.key):

    Info: The SSL key that you provide here must be valid for the domain name that you have provided in the previous step.

  7. Provide the absolute path of the license file. The file extension must be “.licence”. For example, /home/admin/myown.iot.com.licence.

    * Enter domain ({your-domain-name}) Cumulocity licence file path (*.licence):

  8. Provide the absolute path of the Software AG Apama license file. The file extension must be “.xml”. For example, /home/admin/ApamaServerLicense101.xml.

    This is an optional license file, you can press [Enter] to continue without providing license.

    * Enter Software AG Apama licence file path (optional):

  9. Provide the URL for the Cumulocity tenant (cloud or on-premise) to control your Edge device remotely. For example, “https://<tenant-domain>.cumulocity.com”.

    * Enter cloud URL (leave blank to disable remote management):

    You can also configure the Edge agent with the Cumulocity tenant URL by running the post-installation script and selecting Option 7 - Configure Edge Agent.

Once the input parameters are entered correctly, the parameters will be saved under /opt/c8y/utilities/post-installer/config.dat for future reference. You can use this file for providing the input parameters to the post-installer.

File Input

Provide the absolute path of the configuration file. The installation parameters will be loaded from the file. In case of any incorrect parameters, the utility will fall back to console mode and will prompt the user to enter the parameters as described above.

* Enter existing file path containing post-installation parameters:

Confirm to continue with the post-installation process.

The post-installation process consists of multiple steps which are executed sequentially. After a step has been executed, its status will be shown on the console. In case of any failure in any of the steps, the process will halt and a failure message will be displayed on the console.

Option 3 - Update license and SSL certificates

First, select the type of input you want to use.

* Enter [F] to take input from file or [C] to take input from console:

You have the choice to enter the update parameters manually through the console or through a file.

Console input
  1. Provide the absolute path of the SSL certificate file. The file extension should either be “.crt” or “.cert”. For example, /home/admin/myown-selfsigned.crt.

    * Enter domain ({previously-entered-domain-name}) SSL certificate file path (*.crt|*.cert):

  2. Provide the absolute path of the SSL certificate key file. The file extension must be “.key.”. For example, /home/admin/myown-selfsigned.key.

    * Enter domain ({previously-entered-domain-name}) SSL certificate key file path (*.key):

  3. Provide the absolute path of the license file. The file extension must be “.licence”. For example, /home/admin/myown.iot.com.licence.

    * Enter domain ({previously-entered-domain-name}) Cumulocity licence file path (*.licence):

  4. Provide the absolute path of the Software AG Apama license file. The file extension must be “.xml”, e.g. /home/admin/ApamaServerLicense101.xml.

    This is an optional license file, you can press [Enter] to continue without providing license.

    * Enter Software AG Apama licence file path (optional):

Once the input parameters are entered correctly, the parameters will be saved under /opt/c8y/utilities/post-installer/config.dat for future reference. You can use this file for providing the input parameters to the post-installer.

File input

Provide the absolute path of the configuration file. The update parameters will be loaded from the file. In case of any incorrect parameters, the utility will fall back to console mode and will prompt the user to enter the parameters as described above.

* Enter existing file path containing update parameters:

Confirm to continue with the update process.

The update process consists of multiple steps which are executed sequentially. After a step has been executed, its status will be shown on the console. In case of any failure in any of the steps, the process will halt and a failure message will be displayed on the console.

Option 4 - Run post-upgrade

Important: This task needs to be invoked from within the VM and cannot be invoked through a remote connection.

Info: During this process, the previously used password in the source will be validated as per Cumulocity’s password policy. In case the password is not compliant with the policy, the user will be prompted to enter the tenant password without which the post-upgrade task cannot be completed.

Confirm to continue with the post-upgrade process.

The post-upgrade process consists of multiple steps which are executed sequentially. After a step has been executed, its status will be shown on the console. In case of any failure in any of the steps, the process will halt and a failure message will be displayed on the console.

If users have configured the network in the ‘source’ version the new configuration will be done in the upgrade version when this task is executed.

Option 5 - Expand data disk size

Expanding the data disk size consists of two steps:

  1. Increasing the physical HDD size from the hypervisor level
  2. From within the VM, add space to the disk by executing option 5 of the post-installation script

So as a first step you need to carry out the following prior to selecting option 5.

  1. Shutdown the VM.

  2. Edit the VM and on the Virtual Hardware tab increase the disk space of Hard disk 2 to your needs.

  3. Start the VM and run the post_installation.sh script.

  4. From the option list, select option 5, and confirm to continue with expanding the data disk size.

The disk size expanding process consists of multiple steps which are executed sequentially. After a step has been executed, its status will be shown on the console. In case of any failure in any of the steps, the process will halt and a failure message will be displayed on the console.

Option 6 - Update tenant password

The password updated using this option acts as the password for the administrators of both the tenants, that is, admin user of the ‘edge’ tenant and edgeadmin user of the management tenant. Using these credentials, the administrators can log in to the respective tenant through a web browser.

* Enter new tenant admin password:

Info: The password must have a minimum of 8 and a maximum of 32 characters and it may contain letters, numbers or any of these symbols: `~!@#$%^&*()_|+-=?;:'",.<>{}[]/

Re-enter the previously provided password to confirm it.

* Re-enter tenant admin password:

Confirm to continue with updating the tenant password.

The update tenant password process consists of multiple steps which are executed sequentially. After a step has been executed, its status will be shown on the console. In case of any failure in any of the steps, the process will halt and a failure message will be displayed on the console.

Info: The Cumulocity platform does not allow to use any of the last 10 previously used passwords.

Option 7 - Configure Edge Agent

Provide the URL for the Cumulocity tenant (cloud or on-premise). For example, “https://<tenant-domain>.cumulocity.com”.

`* Enter cloud URL (leave blank to disable remote management):`

After providing the tenant URL, you have to register your Edge device with the Cumulocity tenant. For more information, see Registering the Edge device with a Cumulocity tenant.

Important: If you have configured the Cumulocity tenant URL during the post installation and then use this option with a blank URL, you will disable the Cumulocity tenant connectivity.

Accessing the Cumulocity platform

Configuring the access via domain name

The Cumulocity platform is accessible with the domain name provided as part of the post installation script.

There are two ways to configure the accessibility with domain names:

Info: The first option is always preferable so that Cumulocity IoT Edge is reachable in LAN.

Adding the alias

On Linux machines, add the following entry to /etc/hosts:

<IP address> <domain_name>

Use the IP address provided during network configuration. For example, the default value for Hyper-V is 192.168.66.10.

On Windows machines, add the same entry to C:\Windows\System32\Drivers\etc\hosts.

Ping the <domain_name> to verify it.

$ ping <domain_name>

If the ping is successful the DNS resolution is working properly.

Using <domain_name>, Cumulocity IoT Edge can be connected from the host operating system (operating system which is hosting the Edge VM instance). If you want to connect Edge VM within your LAN, which is outside of the host operating system, you need to do following:

Entering Cumulocity

Once the machine is in running state, open a web browser.

Important: You must first login as sysadmin user (password = sysadmin-pass) and change the password for sysadmin user. The sysadmin user account is used for unlocking the tenant admin user. To change the password, see User options and settings.

Entering Cumulocity via domain name

Enter the following:

https://<domain_name>

The Cumulocity Login screen appears.

In the Login screen, log in with the tenant admin credentials provided during post-installation.

Entering Cumulocity via IP

Enter the following:

https://<IP_Address_Of_Edge>;

The Cumulocity login screen appears.

In the Login screen, log in with the tenant admin credentials provided during post-installation.

Important: If you have to log in as edgeadmin user, log in to the management tenant using the URL https://<Edge_VM_IP_Address>/apps/administration/index.html.

  • Tenant: management
  • Username: edgeadmin
  • Password: Will be the same as the Edge tenant admin password provided during the post-installation process

When you log into Cumulocity for the first time, you will be taken to the Cockpit application where the Home screen initially opens up.

Info: You cannot access the Cockpit and Device Management application as edgeadmin user.

Example setup for VMware ESXi

Setting up ESXi

To set up an ESXi virtual machine, follow these steps:

  1. Click Create/Register VM to open a window to select the creation type.

  2. Under Select creation type, select Deploy a virtual machine from OVA or OVF template and click Next.

  3. In the next window, provide a name for the VM, e.g. EDGE-server, and drag and drop the required files (ovf, vmdk1, vmdk2) and click Next.

  4. Under Select storage, select the datastore where the VM will reside and click Next.

  5. Under Deployment options, select options like thin/thick provisioning and click Next.

  6. Review the machine settings and click Finish to complete the setup.

A VM with the provided name, e.g. “EDGE-server”, should now show up in the Virtual Machines section. Notifications will appear accordingly in the Recent tasks pane.

VM hardware configuration

Cumulocity IoT Edge configuration

Perform the following steps to configure the network once the image is imported into ESXi.

  1. Run /opt/c8y/utilities/post_installation.sh -> Option 1 -> “Configure network”.

  2. Run /opt/c8y/utilities/post_installation.sh -> Option 2 -> “Run post-installation”.

Example setup for VMware Workstation Player

Setting up for VMware

To set up a VM in VMware Workstation Player, follow the steps below.

Info: The following steps show a reference example. Refer to the VMware documentation for the exact setup. The final configuration also depends on the end user setup.

  1. In VMWare, navigate to Player > File > Open to import the Edge VM.

  2. Navigate to the folder where the Edge VM files are located, select the OVF file and click Open.

  3. Change the VM name if required and click Import. You can also change the VM storage path here.

  4. Start the Edge VM by clicking Play virtual machine.

Configuring Cumulocity IoT Edge

Once the VM starts up successfully, you have to configure the network so that it can be accessed from outside the VM.

To do so, the following information is required:

If this information is not available to you, contact your network administrator.

You may also use the vmnetcfg utility provided by VMware (see below) to obtain the netmask and gateway IP.

Configure the network by completing the “Configure network” task using the post-installer utility, see Configuration.

Finish the Cumulocity IoT Edge configuration by completing the “Run post-installation” task using the post-installer utility, see Configuration.

Setting up for vmnetcfg utility

You can use the VMware vmnetcfg utility to get the necessary details like subnet mask and gateway IP required for completing the “Configure network” task using the post-installer.

The following example illustrates the network configuration on a Windows platform. For instructions on Linux platform, see VMware Knowledge Base.

  1. Download the correct version of the vmnetcfg utility. It can also be extracted from the VMware Workstation Pro installer.

  2. Save the vmnetcfg binary file (vmnetcfg.exe) in the VMware Workstation Player installation directory. In a Windows environment, this is usually C:\Program Files (x86)\VMware\VMware Player.

  3. Open the file with the appropriate rights.

  4. Select “NAT” as external connection.

  5. Click NAT settings to open the NAT Settings window.

  6. Note down the gateway IP address and close the NAT settings window.

  7. Click DHCP Settings to open the DHCP Settings window.

  8. In the fields Starting IP address and Ending IP address, change the IP range from 3 to 254, i.e. if your gateway IP is 192.168.117.2, set the IP range from 192.168.117.3 to 192.168.117.254.

  9. Click OK to save your settings.

Example setup for Hyper-V

To set up Hyper-V, you must first enable Hyper-V on your system, and create Network Address Translation (NAT) adapter. For enabling Hyper-V, see the Microsoft documentation.

Creating a NAT adapter

You can create a NAT adapter using two ways:

Run all the commands in Windows PowerShell as an administrator.

Creating a NAT adapter using default settings

Info: You must use the default adapter name NATSwitchForEdge and the default IP address 192.168.66.1.

  1. Create a new NAT adapter.
PS C:\WINDOWS\system32> New-VMSwitch -SwitchName "NATSwitchForEDGE" -SwitchType Internal
  1. Verify that the new NAT adapter is created.
PS C:\WINDOWS\system32> Get-NetAdapter

Note down the `ifIndex` of the adapter. The `ifIndex` in the above screenshot is 31. The `ifIndex` may vary in your system and the same `ifIndex` should be used in the next step.
  1. Assign an IP address for the adapter.
PS C:\WINDOWS\system32> New-NetIPAddress -IPAddress 192.168.66.1 -PrefixLength 24 -InterfaceIndex 31
  1. Create a NAT rule.
PS C:\WINDOWS\system32> New-NetNat -Name NATSwitchForEDGE -InternalIPInterfaceAddressPrefix 192.168.66.0/24

Creating a NAT adapter using user-defined settings

You can define the adapter name and configure the IP address for your Edge VM. In this example, the adapter name is EdgeAdapter1 and the IP address is 10.20.30.40.

Info: The following steps show a reference example. The final configuration also depends on the end user setup.

  1. Create a new NAT adapter.
PS C:\WINDOWS\system32> New-VMSwitch -SwitchName "EdgeAdapter1" -SwitchType Internal
  1. Verify that the new NAT adapter is created.
PS C:\WINDOWS\system32> Get-NetAdapter

Note down the ifIndex of the adapter. The ifIndex may vary in your system and the same ifIndex should be used in the next step.

  1. Assign an IP address for the adapter.
PS C:\WINDOWS\system32> New-NetIPAddress -IPAddress 10.20.30.40 -PrefixLength 24 -InterfaceIndex 71
  1. Create a NAT rule.
PS C:\WINDOWS\system32> New-NetNat -Name EdgeNATRule1 -InternalIPInterfaceAddressPrefix 10.20.30.0/24

Setting up Hyper-V

After creating a NAT adapter, you must import the Edge VM image into Hyper-V.

  1. In Hyper-V Manager, go to Action > Import Virtual Machine.

  2. In the Before You Begin wizard, click Next.

  3. Provide the location of the Edge VM image and click Next.

  4. Select the Edge VM and click Next.

  5. In the Choose Import Type wizard, select Register the virtual machine in-place (use the existing unique ID) and click Next.

  6. If you have used the default NAT adapter name, skip this step and proceed with step 7.
    If you have used a different NAT adapter name, you will see the following screen:
    Select the adapter from the Connection drop down list and click Next.

  7. Click Finish. The Edge VM image appears in the Hyper-V Manager.

  8. Right-click the Edge VM image and click Connect.

  9. If you have defined the adapter name and IP address other than the default settings, you must first configure the network before running the post installation. See Configuring the Edge Server.

Info: By default, the NTP servers are configured to Europe NTP servers. You can configure the NTP server as per your requirements.

Example setup for VirtualBox

Setting up VirtualBox

Download the VirtualBox package for your operating system from https://www.virtualbox.org/wiki/Downloads and install it.

Important: VirtualBox support is deprecated, therefore we do not recommended to use it in a production environment.

Info: Depending on the operating system and VirtualBox version you are using, the following steps and the screenshots might slightly differ. The sample screenshots shared below were created using Virtual Box 5.2.8.

  1. In the VirtualBox, click Tools > Network in the top left.

  2. Click Create to set a host-only network interface for VM.

  3. Navigate to File > Preferences > Network to check the network settings.

  4. In the NAT Networks tab, click the plus icon to add a new network.

  5. Click the settings icon on the right and make sure that Enable network is activated, which is the default. This network interface is used for outbound Internet/Intranet access.

  6. Click Tools > Network in the top left. Select VirtualBox Host-Only Ethernet Adapter.

  7. Click the properties icon on the right and make sure that IPv4 Address and IPv4 Mask are set to the following values: IPv4 Adress = 192.168.56.1, IPv4 Mask = 255.255.255.0

    If, in your VirtualBox, there already is a Host-Only Ethernet Adapter configured with the same IPv4 address, then update its properties as described in the next steps.

  8. Click the DHCP Server tab and make sure that the DHCP server is not enabled.

The VirtualBox now is installed and the network is set.

Starting the virtual machine

In the VirtualBox, the virtual machine is imported via File > Import Appliance > Select .ova file.

Alternatively, you can double-click on the provided .ova file. The machine will automatically be added to the VirtualBox VM Manager.

The machine has predefined settings for disk, CPU and memory.

Once the machine has been imported it will show up in the Manager application.

Start the virtual machine by clicking Start on the top left.

Info: The machine description can be found on the Description tab (right-click on Machine > Settings > General > Description).

Troubleshooting

In case of the following error, proceed as described below.

Error

Click Change network setting and select the VirtualBox Host-Only Ethernet Adapter which has been configured in Step 8 above.

The VirtualBox metadata files for VM appliance keep the “VirtualBox Host-Only Ethernet Adapter” name based on the host OS. If this adapter name differs with what is bundled in Cumulocity IoT Edge, it has to be manually selected.

Setting up port forwarding

Follow the steps below, to setup port forwarding.

  1. In the Virtual Box, click Machine Tools in the top right.

  2. Click Settings in the top left. Under settings, click Network, open the network you previously created and then click Port forwarding.

  3. In the Port Forwarding Rules window, click the plus icon. Add the following details for HTTP:
    Name: HTTP
    Protocol: TCP
    Host IP: The Operating System IP address on which Edge VM is running.
    Host port: 80
    Guest IP: The Edge VM IP address which is always 192.168.56.120.
    Guest port: 80

  4. Follow the same steps and add details for other incoming and outgoing traffic, see Prerequisites > Network connectivity. Once all port details have been added, it should look similar to the following screenshot:

  5. Click OK in the Port Forwarding Rules window and then in the Settings window to complete port forwarding on Edge VM.