Setting up Cumulocity IoT Edge

Requirements

Installation requirements

To install Cumulocity IoT Edge, the following is required:

Network connectivity

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

• HTTPS
• MQTT over TLS
• SSH, only for configuring the appliance

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

• HTTPS
• MQTT over TLS

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):

Depending on additional integrations more ports must be opened.

Outgoing Traffic

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

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:

• 100 GB of free disk space
• Intel x86 CPU
• Recommended: 8 GB RAM, minimum: 4 GB RAM
• Recommended: 4 logical CPU cores, minimum: 2 logical CPU cores
• One NIC

Info: This does not cover host OS hardware requirements.

Setting up the environment

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

• Example setup for ESXi VMWare
• Example setup for VMWare Workstation Player
• Example setup for VirtualBox

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:

• Username: admin
• Password: manage

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. The default value for the Virtual Box is 192.168.56.120.

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:

• Cumulocity license file: “.licence”
• SSL Key file: “.key”
• SSL Certificate: “.crt” or “.cert”
• Apama license file: “.xml”

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 via 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. E.g. 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, e.g. “myown.iot.com”. The domain name must match the domain name of the SSL certificate.
Moreover, the domain name must match the Cumulocity licence’s domain. The Cumulocity licence is tied up to the domain name being used in the instance and mismatch would result in a setup failure.

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”, e.g. /home/admin/myown-selfsigned.crt. Make sure that the file path is valid and the file exists in the local machine.

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

c8y.license : Provide the absolute path of the license file. The file extension must be “.licence”, e.g. /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”, e.g. /home/admin/ApamaServerLicense101.xml.

This is an optional licence 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, e.g. 192.168.56.120

netmask : Provide the netmask IP for your network, e.g. 255.255.255.0

gateway.ip : Provide the gateway IP for your network, e.g. 192.168.56.1

dns.server.ip : Provide the DNS Server IP for your network, e.g. 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. Exit

Important: Option 3, 4 and 6 will only work after you have successfully completed the post-installation setup (Option 2). Option 1 and 4 cannot be invoked from a remote connection like SSH. You will have to run these directly from the terminal within the VM.

Option 1 - Configure network

Info: This option is not required if you use VirtualBox as with VirtualBox the IP is configured out of the box in VM. You can immediately proceed with running the post-installation.

Important: This task needs to be invoked from within the VM and cannot be invoked via 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 via the console or via a file.

Console input

1. Provide the new IP address for the ethernet interface, e.g. 192.168.56.120

`* Enter new IP address for ethernet interface:`

2. Provide the netmask IP for your network, e.g. 255.255.255.0

   * Enter netmask:

3. Provide the gateway IP for your network, e.g. 192.168.56.1

   * Enter gateway IP:

4. Provide the DNS Server IP for your network, e.g. 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 via the console or via 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, e.g. “myown.iot.com”. The domain name must match the domain name of the SSL certificate.
   Moreover, the domain name must match the Cumulocity licence’s domain. The Cumulocity licence is tied up to the domain name being used in the instance and mismatch would result in a setup failure.

   * 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”, e.g. /home/admin/myown-selfsigned.crt.

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

6. Provide the absolute path of the SSL certificate key file. The file extension must be “.key.”, e.g. /home/admin/myown-selfsigned.key.

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

7. Provide the absolute path of the license file. The file extension must be “.licence”, e.g. /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”, e.g. /home/admin/ApamaServerLicense101.xml.
   
   This is an optional licence 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 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 via the console or via a file.

Console input

1. Provide the absolute path of the SSL certificate file. The file extension should either be “.crt” or “.cert”, e.g. /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.”, e.g. /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”, e.g. /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 licence 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 via 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

Provide the new password for the edge tenant. This password is later used to login to the platform via the web browser as well as to login to the management tenant using the edgeadmin user.

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

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:

• Add an entry of domain name and IP mapping in DNS servers.
  OR
• Add the alias in order to reach the virtual machine via the domain name provided during configuration. This needs to done on each client host on which Cumulocity IoT Edge is accessed.

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. The default value for the Virtual Box is 192.168.56.120.

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:

• Port forwarding must be enabled as mentioned in Setting up the environment.
• The DNS entry needs to be added in your LAN’s DNS server/Name server. The DNS entry must have the domain name (provided in post_installation step) and the IP address of the host operating system. Note that this is not the Edge VM IP.

Entering Cumulocity

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

Entering Cumulocity via domain name

Enter the following:

https://<domain_name>

The Cumulocity Login screen opens up.

In the Login screen, log in with the following credentials:

• Username: <tenant admin username> (as provided during post-installation)
• Password: <tenant admin password> (as provided during post-installation)

Entering Cumulocity via IP

Enter the following:

https://<IP_Address_Of_Edge>;

The Cumulocity login screen opens up.

In the Login screen, log in with the following credentials:

• Username: edge/<tenant admin username> (as provided during post-installation)
• Password: <tenant admin password> (as provided during post-installation)

After successfully logging in, the Cumulocity platform will open:

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

Example setup for VMware ESXi

Setting up ESXi

To set up an EXSi 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

• Change VM compatibility to the latest ESXi version.
• Make sure that only one network interface is configured. Use VMXNET3 as type.
• Edit VM Settings -> VMware Tools: Check time synchronization
• Edit VM Settings -> General Options: Set guest OS to CentOs 7 (64bit)

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, it’s network has to be configured, so that it can be accessed from outside the VM.

To do so, the following information is required:

• Edge VM IP - Will be used to access the VM from outside
• Netmask
• Gateway IP
• DNS server IP (if unknown, you can use the gateway IP here as well)

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.

Info: The vmnetcfg utility is for Windows hosts only.

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

2. Store 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 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 especially the screenshots might slightly differ. The sample screenshot shared below were created using Virtual Box 6.0.

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.

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.