Installing Edge

Requirements

Installation requirements

Domain name validation for Edge license key generation

To procure the Cloud of Things Private license file, you must provide the right domain name to the Telekom’s logistics team for Edge license key generation.

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

• The domain name does not need to be a Fully Qualified Domain Name (FQDN).
  For example, to access the Edge platform with the domain name yourtenant.ram.m2m.telekom.com, request the Edge license for yourtenant.ram.m2m.telekom.com or iot.com (without the sub-domain myown).

  Important: When you are running the Edge post installation process, you must use the FQDN. For example, yourtenant.ram.m2m.telekom.com.

• If you exclude the sub-domain from the domain name in the Edge license, you should possess a wildcard SSL certificate which can be used with multiple sub-domains (myown or others) of the domain (iot.com).
  For example, if you provide iot.com as the domain name, you should possess an SSL certificate for *.iot.com.

• If you have an Internationalized Domain Name (IDN), then you should provide the translated ASCII equivalent domain name.
  For example, if your domain name is myown.iöt.com (for example, containing ö), then you should use myown.xn–it-fka.com.
  Also, provide the same translated ASCII equivalent domain name as the tenant domain name during the Edge post installation process.
  

  Info: An Internationalized Domain Name (IDN) is an internet domain name that contains at least one label, in whole or in part, in a language-specific script or alphabet, such as Arabic, Chinese, Cyrillic, Devanagari, Hebrew or the Latin alphabet-based characters with diacritics or ligatures, such as French. The internationalization of domain names is a technical solution to translate names written in language-native scripts into an ASCII text representation that is compatible with the Domain Name System. See Wikipedia.

• Ensure that you adhere to the following domain name validation rules:

  • The domain name may contain lowercase letters, digits or hyphens. It must start with a letter; hyphens are only allowed in the middle; minimum is 2 characters. The domain name can be a combination of lowercase or alphanumeric characters separated by dot ( . ) or hyphen ( - ) Note that the usage of underscore characters is deprecated, but still possible for backward compatibility reasons.
    • Cannot contain any letters of languages like Chinese, Latin or Arabic.
    • Cannot contain any special characters like (+ , ! @ # $ % ^ & * ( ) ; \ \ / | < > \ " \ ' ) other than dot ( . ) or hyphen ( - ).
  • The length of the domain name including the dot must not exceed 255 characters.
  • Each segment of the domain name separated by a dot must be between 1 to 63 characters long.
    • The Top-Level Domain (TLD) which refers to the last segment of the domain name must be between two to six characters long.
    • The domain name cannot begin or end with a hyphen.

Network connectivity

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

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

If Cloud of Things Private should communicate with the cloud, the following ports of www.telekom.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 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 Cloud of Things 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:

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 should 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 DT IoT 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, “yourtenant.ram.m2m.telekom.com”. Here, you must have the Edge license for the domain name iot.com or yourtenant.ram.m2m.telekom.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 “Cloud of Things Private installation is now complete” message appears.

Next, click Open Cloud of Things Private.

Installing Edge using the REST APIs

To install Edge using the REST APIs, see the edge/install API in the Cloud of Things Edge OpenAPI Specification.

Setting up the environment

For your convenience, we provide the hypervisor examples for setting up Cloud of Things Private:

• Example setup for ESXi VMWare
• Example setup for VMWare Workstation Player
• Example setup for Hyper-V

For all hypervisors, we recommend you to use UTC on your host machines.

VM login details

SSH login into Cloud of Things Private 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

Important: Changing the hostname of the Edge VM is not supported.

In the Edge VM, the default keyboard layout is en_US. If your keyboard is other than en_US, the characters that you type might not match the keys on the keyboard. This might affect your Edge VM password when setting the password or logging in to Edge VM directly through the VM console.

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.

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 Cloud of Things Private to an unknown and not tested configuration and handling support tickets would no longer work.

Accessing the Edge appliance

After the installation, you can access the Cloud of Things Edge appliance using a domain name in a web browser.

Supported browsers

• Microsoft Edge (latest Chromium-based version)
• Mozilla Firefox (latest Extended Support Release [1])
• Google Chrome [2]
• Internet Explorer 11 [3]

[1] Only the latest Extended Support Release of Mozilla Firefox is explicitly supported. Possible incompatibilities will be removed during the regular maintenance process of Cloud of Things. 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 Cloud of Things.

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

• Chrome on Android (latest version) on Galaxy smartphones and tablets
• Safari on iOS (latest version) on Apple iPhone and iPad

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:

• Add an entry of the domain name and IP mapping in the DNS servers.
  OR
• Add the alias to access the Edge appliance through the domain name provided during installation. This needs to be performed on each client host on which the Edge appliance is accessed.

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.

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:

• On VMware platforms, port forwarding must be enabled as mentioned in Port forwarding on a VMware platform.
• The DNS entry must be added in your LAN’s DNS server/Name server. The DNS entry must have the domain name and the IP address of the host operating system. Note that this is not the Edge appliance IP.

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.

• To log in to the Management tenant, prefix the username with management:

  • Username: management/<Edge admin username>
  • Password: password provided during the installation

• To log in to the “edge” tenant, use the Edge admin credentials or prefix the Edge admin username with edge:

  • Username: edge/<Edge admin username>
  • Password: password provided during the installation

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

• Click Agree and Proceed to accept the default cookie settings (required and functional cookies enabled).
• Click Reject all to reject all of the default cookie settings.
• Click Preferences to select your individual cookie preferences:
  • Required - Required to enable core site functionality. They perform a task or operation without which a site’s functionality would not be possible. Required cookies cannot be disabled.
  • Functional - Used to track site usage and to process personal data to measure and improve usability and performance. Functional cookies must be actively enabled.
• Click See also our Privacy Notice to open the DT IoT privacy statement with details on the DT IoT privacy policy.

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 Cloud of Things 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).

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

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.