Requirements

Installation requirements

Item Details
Hypervisor - VMWare ESXi 7.0
- VMware Workstation Player 17.x and VMware Workstation Pro 17.x
- Hyper-V on Microsoft Windows 10 Enterprise, version 1809. The supported VM configuration version is 9.0.
Important: Ensure that you keep the virtualization platform updated and free from vulnerabilities by following the security advisories provided by the vendors of the hypervisor.
Edge appliance 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:
- Cumulocity IoT Edge - VMWare [Disc 1] (version)
- Cumulocity IoT Edge - VMWare [Disc 2] (version)
- Cumulocity IoT Edge - VMWare .mf (version)
- Cumulocity IoT Edge - VMWare .ovf (version)

For Hyper-V, download the ZIP file:
- Cumulocity IoT Edge - HyperV (version)

The fixes for Edge:
- Cumulocity IoT Edge (version) Update
Edge license file To request the license file for Edge, 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 (for example, myedge.domain.com), where Edge will be reachable
For more information, see Domain name validation for Edge license key generation.
SSL key and SSL certificate Optional. Use your internal or an external CA (Certification Authority) to generate these files. These files must not be password-protected. Ensure that the SSL certificate has the complete certificates chain in the right order.
Info: The .crt and .key files must be in the PEM format and the .key file must not be encrypted.
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 appliance within your LAN, the DNS entry must be added for the domain name (URL under which Edge can be reached) with the IP address of the host.
Edge cloud remote access To connect and manage one (or multiple) Edge appliances 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 Edge.

Domain name validation for Edge license key generation

To procure the 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 Edge should communicate with the cloud, the following ports of www.cumulocity.com (or another instance) must 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 must be enabled by default in order to accept traffic from users and devices on the internet (also see Setting up port forwarding:

Source IP Source Port Destination IP Destination Port Service
any any Edge appliance IP TCP/443 HTTPS
any any Edge appliance IP TCP/1883 MQTT
any any Edge appliance 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
HTTPS 443

Depending on the installed integrations (email, SMS, and so on), different ports might have to be opened in order to make these services available to the Cumulocity IoT 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 minimum hardware requirements:

Hardware Configuration
Disk space 100 GB
CPU Intel x86
Number of CPU cores 2 - without microservice
4 - with microservice
RAM 6 GB - without microservice
8 GB - with microservice
Network Interface Controller (NIC) 1

These are the minimum system requirements to enable the microservice hosting feature. If the microservice requires additional system resources, you must configure the system requirements accordingly in addition to minimum system requirements. For example, if the microservice requires 2 CPU cores and 4 GB of RAM, then the VM must have 6 CPU cores (4 cores for VM + 2 cores for microservice) and 12 GB of RAM (8 GB for VM + 4 GB for microservice).

Info
This does not cover host operating system hardware requirements. The host operating system resource requirements must be sized independently and should be over and above the resource allocated to the virtual machines.

Installing Edge using the UI

To install Edge using the user interface:

  1. Connect and start the Edge appliance in the hypervisor. Wait until the network configuration screen appears.

    Info
    The network configuration blue screen does not appear post installation. After the installation, you must use the Administration application or the REST API to configure the network.
  2. Configure the network for your Edge appliance, see the sample screenshot.

    Important

    While configuring the network on VMware based hypervisors, do not us the IP addresses:

    • X.X.X.1 (used by VMnet8 network adapter on host)

    • X.X.X.2 (used by VMnet8 network adapter’s gateway)

    • X.X.X.254 (used by VMnet8 network adapter’s DHCP server)

  3. Press Enter to save the network configuration.

    Note down the URL to perform the installation. In the screenshot above, the URL is https://192.168.66.10/apps/installation/.

  4. Open the URL in a browser to start the installation process.

    Read the prerequisites and ensure that you have the domain name, SSL certificate and key associated with your domain name, and the license file.

  5. Click Start Installation.

  6. Create an administrator account for the guest operating system below Guest OS admin.

  7. Provide a password for the root user of the guest operating system below Guest OS root, and click Next.

    Important
    Do not use the root credentials to perform any task. The root credentials must be used only when asked by Software AG support personnel. Using it otherwise might void the appliance support.
  8. Create an administrator account to access the “edge” tenant and the Management tenant, and click Next.

  9. Provide a fully qualified domain name below Domain name.

    For example, “myown.iot.com”. Here, you must have the 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.

  10. Provide the Edge license file associated with your domain name below Licence file.

  11. Provide the SSL certificate file and the SSL certificate key file.

    If you do not have an SSL certificate, select Generate self-signed certificate to generate one.

  12. Click Install.

During the installation, the certificates are updated in the Edge appliance. If these certificates are not accepted by your browser, the browser does not get the progress of the installation. In such case, you must refresh the browser and follow the browser instructions for more details. The installation takes some time to complete. After the installation is complete, the “Cumulocity IoT Edge installation is now complete” message appears.

Info
If you still see the installation in progress, refresh the browser.

Next, click Open Cumulocity IoT Edge.

Important
In case you need to reset the password, you must configure the “reset password” template and email server settings to receive the password reset email. For more information, see Configuring password reset and Configuring email server in the User guide.

Accessing the Edge appliance

After the installation, you can access the Cumulocity IoT Edge appliance using a domain name in a web browser.

Supported browsers

[1] Only the latest Extended Support Release of Mozilla Firefox is explicitly supported. Possible incompatibilities will be removed during the regular maintenance process of Cumulocity IoT. Due to frequent upgrades of the Mozilla Firefox consumer release, the compatibility of the Edge appliance with other versions of Mozilla Firefox cannot be guaranteed.

[2] The Google Chrome support is based on Google Chrome Version 84. Due to frequent version upgrades of Google Chrome, compatibility of the Edge appliance with future versions of Google Chrome cannot be fully guaranteed. Possible incompatibilities will be removed during the regular maintenance process of Cumulocity IoT.

Important
[3] Though the Edge appliance is functional on Internet Explorer 11, it does not allow us to provide you with a state-of-the-art user experience. As a result, Edge 10.7 will be the last release that supports this browser. With upcoming releases we will continue to support the latest version of the Microsoft Edge browser as the successor to the Internet Explorer.

You may also use recent smartphone and tablet web browsers. We have tested our products with the following mobile web browsers:

Info

Edge on mobile devices shows some limitations. The limitations could be the following:

  • The usage may be constrained by the memory and the processing power available on the devices.

    For example, loading graphs with large amounts of data points may make the mobile device unresponsive.
  • Using the private mode on browsers may not work.
  • The Streaming Analytics application does not support mobile or touch devices.

Accessing the Edge appliance using the domain name

The Edge appliance is accessible using the domain name configured as part of the installation.

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

Info
The first option is always preferable so that the Edge appliance is accessible over LAN.

Adding the alias

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

<IP address> <domain_name>

Use the IP address provided during the 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.

[admin@iot-edge-server ~]$ ping <domain_name>

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

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

To access the Edge appliance

Enter the URL in the browser:

https://<domain_name>

The Edge appliance login screen appears. Log in with your credentials created during the installation.

Important
Make sure that the address bar of your browser shows a lock icon. The lock icon indicates that you are using a secure connection and that you are indeed connected to the Edge appliance.

If you are logging in for the first time, you will see a cookie banner at the bottom:

Login prompt
Info
The cookie banner is turned on by default on the Edge appliance instances. This feature can be configured, see Enterprise tenant > Customizing your platform > Branding.
Info
If you have enabled functional cookies you can opt-out from the product experience tracking later on via the User settings dialog, see User options and settings.

Select the Remember me checkbox if you want the browser to remember your credentials, so that you do not have to enter them again when opening the application the next time. This is especially convenient if you frequently switch between Cumulocity IoT applications, as the Edge appliance requests you to authenticate each time when starting an application. You can make the browser “forget” your credentials by explicitly logging out.

Finally, click Login to enter the Edge appliance. Initially, you will be taken to the Cockpit application (if not configured differently).

image alt text

To explicitly logout, click the User button at the right of the top bar, then select Logout from the context menu.

Info
The maximum number of failed logins (due to invalid credentials), after which a user is locked, can be configured by the Management tenant on platform level, see Cumulocity IoT Core - Operations guide. The default value is 100.

How to reset your password

To reset your password, you must first configure the “reset password” template and email server settings in the Edge appliance. For information about configuring the email server, see Configuring the email server.

For information about resetting the password, see How to reset your password in the User guide.

How to access pages using URLs

For information about accessing pages using the URLs, see How to access pages using URLs in the User guide.

Security harden the Edge appliance

For information about security configuration, see Configuring security.

Standard platform applications

See Standard platform applications in the User guide.

UI functionalities and features

See UI functionalities and features in the User guide.

User options and settings

See User options and settings in the User guide.

Knowledge Hub

See Knowledge Hub in the User guide.