Operating Cumulocity IoT Edge

This section describes the main operating procedures for standard tasks that have to be carried out when managing Cumulocity IoT Edge.

Troubleshooting the system

In case of any issues we provide a number of options which help you find out what might be the cause and give advice how to fix it.

We recommend you to follow these steps:

If you still need to contact SAG support, include the output of the diagnostics script. See the Diagnostics section on details how to run it.

Health check

Network

Without working network connection the system is not able to work. The following instructions show how to check the network connectivity of the platform.

Check network interface of the node

The following commands will show the interface and network settings of the machine:

[admin@server ~]$ ip a

This will list all interfaces and their current configuration.

Example:

[admin@server ~]$ ip a

1: lo: <LOOPBACK,UP,LOWER_UP> mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
inet 127.0.0.1/8 scope host lo
   valid_lft forever preferred_lft forever
inet6 ::1/128 scope host
   valid_lft forever preferred_lft forever

2: enp0s3: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
link/ether 08:00:27:88:e7:de brd ff:ff:ff:ff:ff:ff
inet 10.0.2.15/24 brd 10.0.2.255 scope global noprefixroute dynamic enp0s3
   valid_lft 85338sec preferred_lft 85338sec
inet6 fe80::a00:27ff:fe88:e7de/64 scope link noprefixroute
   valid_lft forever preferred_lft forever

3: enp0s8: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc pfifo_fast state UP group default qlen 1000
link/ether 08:00:27:81:fe:9d brd ff:ff:ff:ff:ff:ff
inet 192.168.56.120/24 brd 192.168.56.255 scope global noprefixroute enp0s8
   valid_lft forever preferred_lft forever
inet6 fe80::5b3a:bc65:40b5:f9ea/64 scope link noprefixroute
   valid_lft forever preferred_lft forever

You need to make sure that the node has an external interface (ethX) and the loopback interface configured (lo). The loopback interface needs to have the fixed IP 127.0.0.1 with subnet mask 255.0.0.0 and the IP address of the external interface must reside in the correct subnet with the correct subnet mask (in this example 255.255.252.0).

The following command lists the local routing information.

[admin@server ~]$ netstat -rn

Example:

[admin@server ~]$ netstat -rn
Kernel IP routing table
Destination     Gateway         Genmask         Flags   MSS Window  irtt Iface
0.0.0.0         10.0.2.2        0.0.0.0         UG        0 0          0 enp0s3
10.0.2.0        0.0.0.0         255.255.255.0   U         0 0          0 enp0s3
192.168.56.0    0.0.0.0         255.255.255.0   U         0 0          0 enp0s8

Make sure you have the destination 0.0.0.0 in the list which then also has the gateway flag (G) set.

Check access to the internet

Try to reach a well-known address in the internet with the following command:

[admin@server ~]$ ping -s 1500 8.8.8.8
PING 8.8.8.8 (8.8.8.8) 1500(1528) bytes of data.
64 bytes from 8.8.8.8: icmp_seq=1 ttl=56 time=2.61 ms
64 bytes from 8.8.8.8: icmp_seq=2 ttl=56 time=2.80 ms
64 bytes from 8.8.8.8: icmp_seq=3 ttl=56 time=2.82 ms
64 bytes from 8.8.8.8: icmp_seq=4 ttl=56 time=2.75 ms
64 bytes from 8.8.8.8: icmp_seq=5 ttl=56 time=2.79 ms

As when checking the internal reachability you need to make sure that you can see replies from the address you tried to reach. Use Ctrl-C to end the ping command.

Processing

This section lists the required services and processes on the Edge server.

Check platform status

You can check the status of the platform by running the following command:

curl -v http://localhost:8181/tenant/health

* About to connect() to localhost port 8181 (#0)
*   Trying ::1...
* Connected to localhost (::1) port 8181 (#0)
> GET /tenant/health HTTP/1.1
> User-Agent: curl/7.29.0
> Host: localhost:8181
> Accept: */*
>
< HTTP/1.1 200 OK
< Content-Type: application/json
< Date: Sat, 05 May 2018 18:13:28 GMT
< Transfer-Encoding: chunked
< Server: Jetty(8.1.19.v20160209)
<
* Connection #0 to host localhost left intact
{
	"status": "UP",
	"services": {
		"details": {},
		"status": "UP"
	},
	"mongodb": {
		"details": {},
		"status": "UP"
	},
	"tenant": {
		"details": {},
		"status": "UP"
	}
}

The ‘status:”UP”’ shows that all services are running.

If something went wrong, the endpoint should respond a different error code then 200 OK. The response should contain something like:

{
   "status":"DOWN",
   "services":{
      "details":{

      },
      "status":"UP"
   },
   "mongodb":{
      "details":{

      },
      "status":"UP"
   },
   "tenant":{
      "details":{
         "notFullyInitializedTenants":{
            "savenindia":"PAYPAL_REFUND",
            "nowa":"PAYPAL_REFUND",
            "ttc":"PAYPAL_REFUND",
            "controllogichh":"PAYPAL_REFUND",
            "jonathan":"PAYPAL_REFUND",
            "barcotrail":"PAYPAL_REFUND",
            "ngservices":"PAYPAL_REFUND",
            "sixsenses":"PAYPAL_REFUND",
            "trav2":"PAYPAL_REFUND",
            "lucaslocatrix":"PAYPAL_REFUND"
         }
      },
      "status":"DOWN"
   }
}

The response contains checks for the most important components:

The list describes the tenants which on the core node have not been fully initialized and the initialization status they are in.

Status Description
UNINITIALIZED Tenant has not been initialized
DB_INITIALIZED Database initialisation is performed
LOCAL_APPLICATION_INITIALIZED Local applications are deployed
CEP_INITIALIZED CEP rules are been deployed
HEART_BEAT_MONITORING_INITIALIZED Heartbeat monitoring for devices is been started
PAYPAL_REFUND Failed PayPal operations are refunded (when tenant is using PayPal)
BULK_OPERATION_INITIALIZED Support for bulk operations is initialized
FULLY_INITIALIZED Tenant is in working state (should not be displayed)

Checking the system services

Checking REST API availability

Run the following command to check the REST API availability:

[admin@server ~]$ curl -u 'edge/<username>:<password>' -v -X GET http://<base_url>/platform

* About to connect() to <base_url> port 80 (#0)
*   Trying 52.29.189.245... connected
* Connected to <base_url> (52.29.189.245) port 80 (#0)
* Server auth using Basic with user 'management/<username>'
> GET /platform HTTP/1.1
> Authorization: Basic bWFuYWdlbWVudC90c3NjaHVlbDohITQ3TmV1bjI3MQ==
> User-Agent: curl/7.19.7 (x86_64-redhat-linux-gnu) libcurl/7.19.7 NSS/3.21 Basic ECC zlib/1.2.3 libidn/1.18 libssh2/1.4.2
> Host: <base_url>
> Accept: */*
>
< HTTP/1.1 200 OK
< Server: nginx
< Date: Tue, 23 Aug 2016 15:39:29 GMT
< Content-Type: application/vnd.com.nsn.cumulocity.platformApi+json; charset=UTF-8; ver=0.9
< Transfer-Encoding: chunked
< Connection: keep-alive
<
{"alarm":{"alarms":{"alarms":null,"self":"http://management.<base_url>/alarm/alarms"},"alarmsForSource":"http://management.<base_url>/alarm/alarms?source={source}","alarmsForSourceAndStatus":"http://management.<base_url>/alarm/alarms?source={source}&status={status}","alarmsForSourceAndStatusAndTime":"http://management.<base_url>/alarm/alarms?source={source}&status={status}&dateFrom={dateFrom}&dateTo={dateTo}","alarmsForSourceAndTime":"http://management.<base_url>/alarm/alarms?source={source}&dateFrom={dateFrom}&dateTo={dateTo}","alarmsForStatus":"http://management.<base_url>/alarm/alarms?status={status}","alarmsForStatusAndTime":"http://management.<base_url>/alarm/alarms?status={status}&dateFrom={dateFrom}&dateTo={dateTo}","alarmsForTime":"http://management.<base_url>/alarm/alarms?dateFrom={dateFrom}&dateTo={dateTo}","self":"http://management.<base_url>/alarm"},…}

This example shows the correct response of the platform. The username and password need to have full read access to the management tenant. The <base_url> needs to be given to connect to the correct platform and the management tenant must not be blocked from outside.

Monitoring

Monit is a small open-source utility for managing and monitoring Unix systems. It conducts automatic maintenance and repair and can execute meaningful causal actions in error situations.

In Edge, Monit is used to monitor processes and take a restart action if any of them is down/inactive. The usual Monit interval (cycle) is 30 seconds.

Using Monit

Monit can provide a quick status report of all configured services and processes by running the following command as admin user:

[admin@server ~]$ sudo monit summary

There might be cases where Monit has stopped monitoring some resources because of timeout on constant failures or dependency issues.

A specific component, for example, apama-ctrl_proc, can be restarted using the following command:

[admin@server ~]$ sudo monit restart apama-ctrl_proc

The Monit status can be checked by running:

[admin@server ~]$ sudo systemctl status monit

Monit can be restarted by running:

[admin@server ~]$ sudo systemctl restart monit

The log file for monit is located in /var/log/monit.log.

Log files

Log level locations

The solution stores log files at the following locations for the different nodes.

Core node log file locations
Directory Files Usage
/var/log/cumulocity access.log
error.log
karaf.log
mqtt.log
logfile for client access
logfile for errors and general information
logfile for the Karaf Container
logfile for mqtt protocol communication
/var/log/nginx access.log
error.log
logfile for client access
logfile for nginx errors
/var/log messages general log file, contains also the messages from HAProxy
Apama log file locations

To access the apama-ctrl log files, run the command:

[admin@server ~]$ sudo docker logs apama-ctrl-edge
MongoDB log file locations
Directory Files Description
/var/log/mongodb mongod.log
mongod.log.X.gz
mongomongod7.log
mongomongod7.log.X.gz
Log file generated by mongod service
Archive of previous log files generated by mongod service
Log file generated by mongodmongod7 service
Archive of previous log files generated by mongodmongod7 service
/var/log messages general log file
Agent log file locations
Component Files Location
opcua-mgmt-service opcua-mgmt-service.log /var/log/opcua/
opcua-device-gateway opcua-device-gateway.log /var/log/opcua/
Smartrule-agent-server-apama smartrule-agent-server-apama-gc.log
smartrule-agent-server-apama.log
smartrule.log
/var/log/smartrule/
cumulocity-agent cumulocity-agent.log /var/log/cumulocity-agent/
DataHub log file locations

See Log files for details on DataHub log files.

Adjust log level

This section describes how to change the log level for Cumulocity IoT specific applications on the backend side. It does not explain how to change log settings for standard components like databases or other operating system related services.

Changing log level for Karaf

The log level for Karaf is defined in the following file.

/usr/share/cumulocity-core-karaf/etc/org.ops4j.pax.logging.cfg

The file has the following structure:

# Root logger
log4j.rootLogger=INFO,out,osgi:*
log4j.throwableRenderer=org.apache.log4j.OsgiThrowableRenderer

# Error appender
log4j.appender.out=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.out.rollingPolicy=org.apache.log4j.rolling.FixedWindowRollingPolicy
log4j.appender.out.rollingPolicy.maxIndex=10
log4j.appender.out.triggeringPolicy=org.apache.log4j.rolling.SizeBasedTriggeringPolicy
log4j.appender.out.triggeringPolicy.MaxFileSize=104857600
log4j.appender.out.rollingPolicy.FileNamePattern=${karaf.data}/log/error-%i.log.gz
log4j.appender.out.rollingPolicy.ActiveFileName=${karaf.data}/log/error.log
log4j.appender.out.layout=org.apache.log4j.PatternLayout
log4j.appender.out.layout.ConversionPattern=%d{yyyy-MM-dd} %d{HH:mm:ss}  | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
log4j.appender.out.append=true

# CXF request and response info:
# * ERROR - none
# * INFO - just headers (default)
# * DEBUG - whole, with payloads
log4j.additivity.com.cumulocity.rest.interceptors=false
log4j.logger.com.cumulocity.rest.interceptors=INFO,access

# Access appender
log4j.appender.access=org.apache.log4j.rolling.RollingFileAppender
log4j.appender.access.rollingPolicy=org.apache.log4j.rolling.FixedWindowRollingPolicy
log4j.appender.access.rollingPolicy.maxIndex=10
log4j.appender.access.triggeringPolicy=org.apache.log4j.rolling.SizeBasedTriggeringPolicy
log4j.appender.access.triggeringPolicy.MaxFileSize=262144000
log4j.appender.access.rollingPolicy.FileNamePattern=${karaf.data}/log/access-%i.log.gz
log4j.appender.access.rollingPolicy.ActiveFileName=${karaf.data}/log/access.log
log4j.appender.access.layout=org.apache.log4j.PatternLayout
log4j.appender.access.layout.ConversionPattern=%d{yyyy-MM-dd} %d{HH:mm:ss}  | %-5.5p | %-16.16t | %-32.32c{1} | %X{bundle.id} - %X{bundle.name} - %X{bundle.version} | %m%n
log4j.appender.access.append=true

# Error response info:
# * INFO - just error message (default)
# * DEGUB - full stack trace
log4j.logger.com.cumulocity.rest.mediatypes=INFO

Change the following entries to adjust the log levels:

log4j.rootLogger=INFO,out,osgi:*

log4j.logger.com.cumulocity.rest.interceptors=INFO,access

log4j.logger.com.cumulocity.rest.mediatypes=INFO

Adjust the log levels by changing the level attribute according to the following values. The levels are inclusive - meaning a given level will also include all “lower” log levels, e.g. when you set the level to WARN you will also get ERROR events.

Level Description
ERROR Log errors only
WARN Give information up to warnings
INFO Give information about normal operations
DEBUG Log all internal debug information

Save the file. It is re-read by the application every few minutes so you do not have to restart the Java process.

Diagnostics

The diagnostic utility is enabled by default and runs periodically. However, this can also be triggered manually on demand. To execute it manually, follow the steps below.

cd /opt/c8y/utilities/diagnostic-utility
sudo ./run_data_collector.py

Hardware information

The basic hardware information of the target system is captured. These reports are placed under the ‘hardware’ directory.

The following hardware information is available:

Information
Description
CPU Reads and gathers CPU information from “/proc/cpuinfo”
Memory Reads and gathers memory information from “/proc/meminfo”
Detailed system summary Data is captured using the ‘lswh’ command. Data includes multiple components like network, display adapter, bridge, IDE etc. This command is executed as sudo to capture all available details.
Short system summary Data is captured using the ‘lswh’ command, here the data is in precise format. This command is executed as sudo to capture all available details.
PCI Data related to installed PCI devices is captured using the ‘lspci’ command
Storage Data is an aggregation of the output of the commands ‘df’ and ‘lsblk’

Software information

The basic software information of the target system is captured. These reports are placed under the ‘software’ directory.

The following software information is available:

Information
Description
IP Reads basic IP information from the target system using the ‘ip’ command
OS Collects various OS information like name, version, release etc. using the commands ‘lsb_release’ and ‘uname’
Installed package A list of installed packages is prepared using the ‘rpm’ command
Running processes A list of running processes is prepared using the ‘ps’ command
Top result Captures the output of top command. This report is very informative as it holds information of running processes at argument level and their respective resource consumption.

Cumulocity IoT information

This section contains information on the running Cumulocity IoT processes, health endpoint check result, Cumulocity IoT logs etc.

The following Cumulocity IoT information is collected:

Information
Description
Health endpoint result Cumulocity IoT and its microservices provide health endpoints, from which the user can get the system status.
Mongo command execution result MongoDB supports commands execution, which can give the status of the MongoDB server. Currently ‘ping’, ‘dbstats’ and ‘serverStatus’ commands are executed on each of the MongoDB nodes (currently it is management and edge). The MongoDB commands give vital information about the MongoDB server like the db version, process-id, uptime information etc.
Mongo top output The output of mongo top command is captured here
Thread dumps Thread dumps of all the running java processes and mongo processes are captured. For java processes the ‘jstack’ command is executed to get the thread dumps. For non-java processes like MongoDB, the ‘pstack’ command is used. Furthermore the ‘pstack’ command is applied on java processes as well.
Log files Archive of log files from Cumulocity IoT, its microservices and Apama is created. In case of Cumulocity IoT, only the ‘live’ logs are considered and roll-over log files are discarded.
Configuration files Archive of Cumulocity IoT configuration files from Cumulocity IoT and its microservices is created.
Jstat dumps Jstat command provides performance statistics for a given JVM.

Jstat dumps can provide information on the following options:

As per the current implementation, the 5 statistics counts are collected at an interval of 50ms. To improve performance, this task is executed via threads.

Optional startup parameters

Following are the supported startup parameters for the monitor and the data collector.

Data collector

The data collector can be started by running the “run_data_collector.py” script located under “/opt/c8y/utilities/diagnostic-utility/src/”.

Following are the supported command line arguments which can be used while invoking the script. More than one of the supported arguments can be used simultaneously.

Monitor

The monitor can be started by running the “run_monitor.py” script located under “/opt/c8y/utilities/diagnostic-utility/src/”.

The monitor script supports only one optional startup parameter:

Microservices log file locations

The logs of the Kubernetes components are captured at: /tmp/diagnostic-utility/diagnostic_report_XXXXX/cumulocity/log_archive/kubernetes_logs.zip.

The kubernetes_logs.zip file contains the logs of all Kubernetes platform components at “kube-system” path in the archive. The components captured are:

Info: The XX represents randomly generated alphanumeric sequences in these pod names and would vary in your environment.

The hosted microservices are captured at cumulocity-single-node path in the archive. The pre-installed component kube-registry-persistent-secure-xx-xx is already available in the archive. The logs of any additional microservices that are uploaded will also be available at this path.

Utility configuration file

The diagnostic utility can be customized using a properties file located under “/etc/diagnostic-utility/diagnostic_utility.properties”.

Important: The SMTP properties in the table below are only for collecting diagnostics information. For configuring the email server, see Administration > Changing settings> Configuration settings in the User guide.

Following are the available keys used in the configuration file:

Information
Description
email.notification Allows users to select whether they want to receive the diagnostic report via email
recipient.email Email ID to be used by the utility while sending support email
smtp.server.host SMTP host for sending support email
smtp.server.port SMTP port to be used by the utility while sending support email
smtp.username SMTP username to be used by the utility while sending support email
smtp.password SMTP password to be used by the utility while sending support email
components.for.log.backup Components for which the log backup has to be performed
components.for.configuration.backup Components for which the configuration backup has to be performed
report.directory Report directory where the diagnostic reports have to be placed
{component-name}.log.path Absolute log path of the components under “component.for.log.backup” which do not use /var/log as the logging directory
containers.to.monitor Containers for which log backup is required. The container names are separated by a comma. These log files are retrieved using docker logs.
services.to.monitor Services for which log backup is required. The service names are separated by a comma. These log files are retrieved using journalctl.

Docker bridge network CIDR

The Docker bridge network fails in the following scenarios:

  1. Docker bridge network unavailable on boot time.

    Description: The default Docker bridge network range is not available in the network. If the network range is already utilized, the Docker bridge network does not start properly and the Kubernetes cluster startup fails.

  2. Invalid Docker bridge network provided during IP change.

    Description: You tried to change the Docker bridge network of the properly running Edge VM, but the range is not available in the network.

To troubleshoot these scenarios:

  1. Configure the Edge VM’s network and gateway to a different network range using the post-installation script. Configure the Edge VM to a different network disconnects the Edge VM from the existing network.
  2. Configure Docker CIDR to a new non-conflicting value using the post-installation script.
  3. Configure the Edge VM’s network and gateway back to the network range using the post-installation script.

Upgrading on VMware ESXi

Info: Upgrading OPC UA artifact from an older version to the newer version is not supported.

To upgrade the Edge VM on VMware ESXi:

  1. Power off the Edge VM from the ESXi console.

  2. Select the Edge VM and click Actions > Export.

  3. Click OK to download the files.
    This action downloads the following files:

    • disk-0.vmdk (primary disk)
    • disk-1.vmdk (secondary disk)
    • An OVF file (for example, Generic-Edge-10.4.0.0.8.ovf)
  4. Download the latest version to a separate folder.
    For example, if you are upgrading to Cumulocity IoT Edge version 10.5, save the following files to a separate folder:

    • EDGE-server-10.5.0.0-147-ESXi-disk1.vmdk
    • EDGE-server-10.5.0.0-147-ESXi-disk2.vmdk
    • EDGE-server-10.5.0.0-147-ESXi.ovf
    • EDGE-server-10.5.0.0-147-ESXi.mf
  5. Copy the DATA/secondary disk of the exported VM to the latest version.
    For example, copy the secondary disk disk-1.vmdk to the folder to which you have downloaded the latest version.

  6. Remove the secondary disk of the latest version and rename the secondary disk of the exported version to the latest version.
    For example:

    • Delete EDGE-server-10.5.0.0-147-ESXi-disk2.vmdk
    • Rename disk-1.vmdk to EDGE-server-10.5.0.0-147-ESXi-disk2.vmdk.
  7. If the size of the secondary disk has expanded, you must update the OVF file of the latest version accordingly. In the OVF file, search for the fields ovf:capacity and ovf:capacityAllocationUnits and update the values as per the values in the exported OVF file.

  8. Import the Edge VM image as described in Setting up ESXi.

  9. Start the Edge VM by clicking Power on.

  10. Run the post-upgrade task to complete the upgrade process. See Running post-upgrade.

Upgrading on VMware Workstation Player

Info: Upgrading OPC UA artifact from an older version to the newer version is not supported.

To upgrade the Edge VM on VMware Workstation Player:

  1. Power off the Edge VM from VMware Workstation Player.

  2. Go to the disk folder of the Edge VM.
    To find the location of the disk folder, in VMware Workstation Player, click Edit virtual machine settings > Hardware > Hard Disk 2 (SCSI) and see Disk file field.

  3. Back up the data disk to a different folder.
    For example, if you are upgrading from Edge version 10.5 to version 10.6, back up EDGE-server-10.5.0.0-584-VMware-disk2.vmdk.

  4. Remove the Edge VM from VMware Workstation Player.
    To remove the Edge VM, right-click the Edge VM and click Delete from Disk.

  5. Import the latest version of the Edge VM.
    For example, import the 10.6 version of the Edge VM.

  6. Go to the disk folder of the Edge VM.

  7. Copy the backed-up data disk to the disk folder of the Edge VM.
    For example, copy the data disk EDGE-server-10.5.0.0-584-VMware-disk2.vmdk to the disk folder of the Edge VM.

  8. Delete the data disk of the latest version.
    For example, delete EDGE-server-10.6.0.0-1483-VMware-disk2.vmdk.

  9. Rename the data disk of the previous version to the latest version.
    For example, rename EDGE-server-10.5.0.0-584-VMware-disk2.vmdk to EDGE-server-10.6.0.0-1483-VMware-disk2.vmdk.

  10. Start the Edge VM by clicking Power on.

  11. Run the post-upgrade task to complete the upgrade process. See Running post-upgrade.

Upgrading on Hyper-V

Info: Upgrading OPC UA artifact from an older version to the newer version is not supported.

To upgrade the Edge VM on Hyper-V:

  1. Shut down the Edge VM from Hyper-V console.

  2. Right-click the Edge VM and click Export.

  3. Specify the location where you want to save the exported files and click Export.
    This action creates three folders: Snapshots, Virtual Hard Disks, and Virtual Machines. The Virtual Hard Disks folder contains the disk files:

    • EDGE-server-10.5.0.0-582-HyperV.vhdx (primary disk)
    • EDGE-server-10.5.0.0-582-HyperV-0.vhdx (secondary disk or data disk)
  4. Download the latest version to a separate folder.
    For example, if you are upgrading to Cumulocity IoT Edge version 10.6, the 10.6 disk files are available in the Virtual Hard Disks folder:

    • EDGE-server-10.6.0.0-1484-HyperV.vhdx
    • EDGE-server-10.6.0.0-1484-HyperV-0.vhdx
  5. Copy the secondary disk of the exported VM to the Virtual Hard Disks folder of the latest version.
    For example, copy the 10.5 version secondary disk EDGE-server-10.5.0.0-582-HyperV-0.vhdx to the 10.6 version.

  6. Delete the secondary disk of the latest version and rename the secondary disk of the exported version to the latest version.
    For example:

    • Delete EDGE-server-10.6.0.0-1484-HyperV-0.vhdx.
    • Rename EDGE-server-10.5.0.0-582-HyperV-0.vhdx to EDGE-server-10.6.0.0-1484-HyperV-0.vhdx.
  7. Import the Edge VM image as described in Setting up Hyper-V.

  8. Start the Edge VM by clicking Start.

  9. Run the post-upgrade task to complete the upgrade process. See Running post-upgrade.

Backup and restore in VMware Workstation Player

VMware Workstation Player does not support backup functionality. However, you can restore a virtual machine in VMware Workstation Player. To restore a virtual machine, go to Player > File > Open and follow the prompts.

Backup and restore in VMware Workstation Pro

Creating a backup in VMware Workstation Pro

  1. Power off the Edge VM.

  2. Select the Edge VM that you want to back up.

  3. Click File > Export to OVF.

  4. Click Save.

Restoring an Edge VM in VMware Workstation Pro

  1. Click File > Open.

  2. Select the Edge VM that you want to restore and click Open.

  3. Click Import.

Backup and restore in VMware ESXi

Creating a backup in VMware ESXi

  1. Power off the Edge VM in the ESXi console.

  2. Select the Edge VM and click Actions > Export.

  3. Click OK to download the files.

Restoring an Edge VM in VMware ESXi

Restoring an Edge VM from an OVF file is similar to deploying a virtual machine in VMware ESXi. To restore an Edge VM, perform the steps as described in Setting up an Edge VM on VMware ESXi.

Administration and configuration

Unlocking the tenant admin user

The tenant admin user could be locked if incorrect credentials are passed during login into UI, REST API or MQTT.

To unlock the tenant admin user, perform the following steps:

  1. Login as management/sysadmin user to unlock a user in the management tenant.
    Login as edge/sysadmin user to unlock a user in the edge tenant.
  2. In the Administration application, navigate to the Users page and open the tenant admin user.
  3. Activate the user account by switching the toggle next to the username to Enabled and save your settings.

Configuring email server and password template settings

To configure the “reset password” template and email server settings, perform the following steps:

  1. Log into the management tenant using https://<Edge_VM_IP_Address>/apps/administration/index.html#/configuration.
    • Tenant: management
    • User: edgeadmin
    • Password: Will be the same as the Edge tenant admin password provided in the post-installation execution
  2. Update the email server details and templates following the instructions in Administration > Changing settings> Configuration settings in the User guide.

Increasing the system performance

If the system performance is slow, the memory should be increased. First, increase the memory of the VM. This is done by stopping the VM and increasing its memory.

Increasing the VM memory should be followed by a JVM memory increase.

This is done by starting the VM (follow the steps described in the Installation section). Log into VM, open the file /usr/share/cumulocity-core-karaf/bin/setenv and edit it as described below. The parameter is the following, default size is 1024.

export JAVA_MAX_MEM=1024M # Maximum memory for the JVM

After increasing the size, restart Karaf by executing:

[admin@server ~]$  sudo service cumulocity-core-karaf stop

and

[admin@server ~]$  service cumulocity-core-karaf start

Log rotation

The components for which log rotation is configured are as follows:

Component Log file location Log file rotation Max file size Max backup index
Karaf ${karaf.data}/log/error.log Daily 50 MB 14
MQTT ${karaf.data}/log/mqtt.log Daily 50 MB 14
Access ${karaf.data}/log/access.log Daily 50 MB 14
DataBroker ${karaf.data}/log/databroker.log Daily 50 MB 14

**Under /etc/ configured via logrotate.conf and config files under /etc/logrotate.d**

The components for which log rotation is configured are as follows:

Component Log file location Log file rotation Max file size Max backup index
MongoDB /var/log/mongodb/*.log Daily 50 MB 14
NginX /var/log/nginx/*.log Daily 50 MB 14
Apama /var/log/apama/*.log Daily 50 MB 14

For microservices, there currently is no specific log rotation configured.

Time synchronization

For many use cases, and especially when using Apama, the time inside the Edge appliance must be synchronized with the network.

chrony or ntp services can be configured by end users based on their time synchronization needs. These services are by default stopped and disabled in Edge and can be enabled by standard commands. Use the following commands to interact with the chrony or ntp services:

sudo systemctl start|stop|status|restart ntpd
sudo systemctl start|stop|status|restart chronyd

By default, for VMWare-based installations, the vmtools service is responsible for time synchronization with the host operating system.

For HyperV, the chronyd service is enabled by default for accurate time synchronization.

Info: As HyperV relies on the chronyd service for time synchronization, do not stop the chronyd service.

Restarting services

Important: If the processes are monitored by monit, the processes restart after you run the stop command.

Karaf processes

On the Edge server, run the following commands as admin user.

Process Command
Start [admin@server ~]$ sudo service cumulocity-core-karaf start
Stop [admin@server ~]$ sudo service cumulocity-core-karaf stop

opcua-mgmt-service

On the Edge server, run the following commands as admin user.

Process Command
Start [admin@server ~]$ sudo service opcua-mgmt-service start
Stop [admin@server ~]$ sudo service opcua-mgmt-service stop
Restart [admin@server ~]$ sudo service opcua-mgmt-service restart
Status [admin@server ~]$ sudo service opcua-mgmt-service status

opcua-device-gateway

On the Edge server, run the following commands as admin user.

Process Command
Start [admin@server ~]$ sudo service opcua-device-gateway start
Stop [admin@server ~]$ sudo service opcua-device-gateway stop
Restart [admin@server ~]$ sudo service opcua-device-gateway restart
Status [admin@server ~]$ sudo service opcua-device-gateway status

smartrule

On the Edge server, run the following commands as admin user.

Process Command
Start [admin@server ~]$ sudo systemctl start smartrule
Stop [admin@server ~]$ sudo systemctl stop smartrule
Restart [admin@server ~]$ sudo systemctl restart smartrule

Apama

On the Edge server, run the following commands as admin user.

Process Command
Start [admin@server ~]$ sudo service apama start
Stop [admin@server ~]$ sudo service apama stop
Restart [admin@server ~]$ sudo service apama restart