Cumulocity IoT Edge on Hyper-V

Knowledge base
, , ,
1

How to setup Cumulocity IoT Edge on Hyper-V

This tutorial explains setting up Cumulocity IoT Edge version 10.5 on Hyper-V. In this tutorial, we will configure Cumulocity IoT Edge version 10.5 with the IP address 192.168.66.10.

Note: This tutorial is an example and the IP addresses may vary in your setup.

Actors

  • System administrators

Preconditions

  • Hyper-V on Microsoft Windows 10 Pro and Windows 10 Enterprise, version 1809
  • Cumulocity IoT Edge image
  • Cumulocity IoT Edge license file
  • SSL key and SSL certificate
  • DNS entry – required in case you want your Edge VM to connect to internet

Basic Flow

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

Creating a NAT adapter

Run all the commands in Windows PowerShell as an administrator.

Note: 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
  2. Verify that the new NAT adapter is created. 
    PS C:\WINDOWS\system32> Get-NetAdapter
    1079×271 15 KB

    Note down the ifIndex value of the adapter. The ifIndex value in the above screenshot is 31. The ifIndex value may vary in your system and the same ifIndex value must be used in the next step.

  3. Assign an IP address for the adapter. 
    PS C:\WINDOWS\system32> New-NetIPAddress -IPAddress 192.168.66.1 -PrefixLength 24 -InterfaceIndex 31
  4. Create a NAT rule. 
    PS C:\WINDOWS\system32> New-NetNat -Name NATSwitchForEDGE -InternalIPInterfaceAddressPrefix 192.168.66.0/24

Next steps: Import and install Cumulocity IoT Edge on Hyper-V.

Importing and installing Cumulocity IoT Edge on Hyper-V

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

    1078×630 81.7 KB

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

    878×666 49.1 KB

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

    878×662 36.8 KB

     
  4. Select the Edge VM and click Next.

    881×662 42.4 KB

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

    877×667 51.5 KB

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

    875×662 60.4 KB

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

    1915×1145 215 KB

     

Next steps: Configure the Cumulocity IoT Edge server.

Configuring the Cumulocity IoT Edge server

After you start the Cumulocity IoT Edge server, you must log in to the Edge server and run the post-installation script to configure the Edge server. As a first step, you must configure the network for the Edge server and then perform the post-installation process.

Configuring the network for the Edge server

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

  1. Log in to the Edge server using the following credentials:
    Username: admin
    Password: manage
    You will be prompted to change the password.
     
  2. Go to /opt/c8y/utilities. 
    [admin@server ~]$ cd /opt/c8y/utilities
  3. Run the following commands:> 
    [admin@server ~]$ su admin
[admin@server ~]$ Password: <Enter the password for admin user>
  4. Run the post-installation script post_installation.sh. 
    [admin@server ~]$ sudo ./post_installation.sh

  1. Select the option 1. Configure network.
     
  2. 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. In this tutorial, we are providing the network parameters through console.
     
  3. Provide the new IP address for the ethernet interface. For example: 
    * Enter new IP address for ethernet interface: 192.168.66.10
  4. Provide the netmask IP for your network. For example: 
    * Enter netmask: 255.255.255.0
  5. Provide the gateway IP for your network. For example: 
    * Enter gateway IP: 192.168.1.1
  6. Provide the DNS Server IP for your network. For example: 
    * Enter DNS Server IP: 192.168.1.1
    Note: 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.

    The following image presents the snapshot of the example:

    1252×582 118 KB

     
  7. Confirm to continue with the network configuration process.

The network configuration process consists of multiple steps that are executed sequentially. After a step has been executed, the status appears on the console. In case of any failure in any of the steps, the process halts and a failure message appears on the console.

Note: If you are using Cumulocity IoT Edge 10.6, you must restart the Edge VM after configuring the network.

Next steps: Run the post installation process.

Running the post installation process

  1. Run the post-installation script post_installation.sh. 
    [admin@server ~]$ sudo ./post_installation.sh

768×310 7.25 KB

  1. Select the option 2. Run post-installation.
     
  2. Select the type of input you want to use.

    750×118 1.92 KB


    You have the choice to enter the post-installation parameters manually through the console or through a file. In this tutorial, we are providing the post-installation parameters through console.
     
  3. Provide a new username for the tenant admin. This username is later used to login to the system using the web browser.

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

    Note: 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: 
    `~!@#$%^&*()_|+-=?;:‘“,.<>{}[]\/
  5. Re-enter the password to confirm.
     
  6. 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.
     
  7. 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.

    Note: The SSL certificate that you provide here must be valid for the domain name that you have provided in the previous step.
     
  8. Provide the absolute path of the SSL certificate key file. The file extension must be “.key.”.

    For example, /home/admin/myown-selfsigned.key.
     
  9. Provide the absolute path of the license file. The file extension must be “.licence”.

    For example, /home/admin/myown.iot.com.licence.
     
  10. (Optional) 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. Press [Enter] to continue without providing license. 
    * Enter Software AG Apama licence file path (optional):
  11. (Optional) 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):
  12. Confirm the post installation process.

    725×725 19.5 KB
Next steps: Access the Edge VM through a browser using the domain name or the IP address of the Edge VM. In this example, the IP address of the Edge VM is 192.168.66.10.