HARTING MICA Device Management - User Manualmica-container.com/container/devman/MICA_Device... ·...

HARTING MICA Device Management - User Manual

MICA Device Management - User Manual Page 1 of 53

HARTING IT Software Development GmbH & Co. KG

Marienwerder Str. 3

32339 Espelkamp, Germany

[email protected]


mailto:[email protected]



1st Edition 2019

© HARTING IT Software Development, Espelkamp

All rights reserved, including those of the translation.

No part of this manual may be reproduced in any form (print, photocopy, microfilm or any other process),

processed, duplicated or distributed by means of electronic systems without the written permission of

HARTING IT Software Development GmbH & Co. KG, Espelkamp.

Version 1.0. Subject to alterations without notice.



Inhalt

1 INTRODUCTION ...................................................................................................................... 5

1.1 About MICA Device Management ..................................................................................... 5

1.2 Device Management Features .......................................................................................... 5

1.3 MICA Device Management Limitations ............................................................................. 5

2 GENERAL OVERVIEW ............................................................................................................ 5

2.1 License ............................................................................................................................. 6

2.2 Operation Requirements and Conditions .......................................................................... 6

3 SECURITY CONSIDERATIONS ............................................................................................... 6

4 INSTALLATION, INITIAL SETUP AND CONFIGURATION ..................................................... 6

4.1 Overview ........................................................................................................................... 7

4.2 Installation of MICA Device Management ......................................................................... 7

4.3 Installing a MICA Device Management License Key ......................................................... 9

5 BASIC SECURITY CONFIGURATION ................................................................................... 10

5.1 Securing MQTT and PostgreSQL ................................................................................... 11

Securing the ....................................................................................................................... 12

5.2 MICADevMan Container ................................................................................................. 12

5.3 ManageAccess Container ............................................................................................... 12

6 BASIC DEVICE MANAGEMENT OPERATIONS ................................................................... 13

6.1 Device List ...................................................................................................................... 13

6.2 Getting Status Information .............................................................................................. 15

6.3 Integrating New MICA Devices into MICA Device Management ..................................... 20

6.4 Grouping MICA Devices ................................................................................................. 23

6.5 Operations on MICA Devices .......................................................................................... 25

6.6 Configuring MICA Devices Using Profiles ....................................................................... 27



6.7 Configuring MICA Devices Directly ................................................................................. 32

6.8 Operations on Multiple MICA Devices ............................................................................. 34

7 PROFILES .............................................................................................................................. 34

7.1 Working with Profiles and Properties .............................................................................. 34

7.2 Using Placeholders in Profiles ........................................................................................ 37

8 ADVANCED TOPICS ............................................................................................................. 39

8.1 Architecture and Network Infrastructure .......................................................................... 39

8.2 The Device Management JSON Formats ........................................................................ 40

8.3 Direct Access to the MICA Web UI ................................................................................. 41

8.4 Security Certificates - Generation and Integration ........................................................... 42

8.5 Create Additional Database Users .................................................................................. 44

8.6 Define Managed MICA Devices in ManageAccess ......................................................... 46

8.7 Handling of Software Packages ...................................................................................... 47

8.8 Using an External MQTT Broker ..................................................................................... 50

8.9 Using an External PostgreSQL Database ....................................................................... 50

8.10 Configuring a Custom MQTT Connection ....................................................................... 51

8.11 Configuring a Custom MQTT Connection in ManageAccess ........................................... 52

8.12 Logging ........................................................................................................................... 52

8.13 MICA Devices with MICA Base System 2 or Earlier ........................................................ 53



1 Introduction

1.1 About MICA Device Management

MICA Device Management is an integrated collection of MICA containers that assist you in setting

up and maintaining small to medium sized MICA installations. It consists of the main Device

Management container where you can view and configure individual MICA devices or groups of

MICA devices, an agent which lets you discover and add MICA devices to be managed, a

database to store MICA information and profiles, and an MQTT broker. All components

communicate using MQTT or MQTTs over TCP/IP.

1.2 Device Management Features

MICA Device Management can assist you with the following tasks:

Discover MICA devices in a local or wide area network.

Quickly check the status of MICA devices.

Configure MICA network settings, time settings, and passwords.

Install and upgrade MICA firmware and containers.

Assign configuration profiles to MICA and groups of MICA.

Import configuration profiles and settings of all MICA in your network.

1.3 MICA Device Management Limitations

MICA Device Management is designed to support a technician or system administrator with

maintaining a small to medium number of MICA and R300 devices, typically less than 50.

MICA Device Management does not have a built in scheduler, so all operations are executed as

soon as they are initiated.

Since some operations like firmware upgrades or installation of multiple containers take

time, make sure that the MICA running the Device Management apps is continuously

available for the duration of the process.

MICA Device Management currently does not support alerting or remote notification of

maintenance issues.

2 General Overview

MICA Device Management is a software tool consisting of four containers.

The MICADevMan container provides the UI for the whole solution.

The ManageAccess container discovers and connects MICA devices to Device

Management.



The MQTT container handles communication between Device Management and

ManageAccess container.

The PostgreSQL container stores MICA statuses, profiles, groups, and logs of device

management operations.

For installation and upgrading of containers, MICA Device Management also needs access to an

HTTP File Server in your network to store the software packages. This files server has to be

accessible to ManageAccess.

2.1 License

MICA Device Management is a commercial software package subject to licencing.

You can use MICA Device Management for evaluation purposes without a license key. However,

without an activated license key, you can only manage ten MICA devices or less.

You can purchase a license from your local HARTING representative or at harting.com.

2.2 Operation Requirements and Conditions

MICA Device Management requires a MICA 2 or MICA Wireless with access to all managed MICA

devices in your network over IPv4 or IPv6.

Additionally, one ManageAccess container needs to be installed in every subnet MICA devices

should be managed in.

3 Security Considerations

MICA Device Management uses the built-in security mechanisms of the connected MICA and

secure communications, so using Device Management does not create new attack vectors on the

connected MICA. You still should be aware of potential security risks, including, but not limited to:

If passwords are stored in the Device Management database, any user with access to the

device management UI can log into and perform operations on any connected device.

Passwords have to be transmitted between Device Management and the connected MICA

over MQTT once per session, to create and exchange the session token. For added

security, you should enable encrypted communication over MQTTS.

To perform its management functionality, Device Management connects to MICA with admin

rights, be aware that this can potentially lead to privilege escalation on the connected MICA.

In other words: any user with access to Device Management automatically has administrator

access to all connected MICA which passwords have been saved in the Device

Management database.

The Device Management database is stored on the MICA the PostgreSQL container is running on.

Make sure that this MICA is adequately secured from unauthorized access.

4 Installation, Initial Setup and Configuration

http://harting.com/



4.1 Overview

MICA Device Management is available in two different formats:

Universal.tar installation package for installation on a single MICA

Container packages for installation in a distributed MICA network

Both installation packages include the same modules, but require different procedures for

installation and setup.

4.2 Installation of MICA Device Management

As mentioned in the chapter above, the MICA Device Management is available in two variants. The

following sections describe the default installation using the Universal.tar file. For instructions how

to install individual container packages in a distributed environment, see 8.2.

4.2.1 Default Installation with the Device Management Universal.tar

With this software package, you can install the MICA Device Management on a MICA.

The installation process will overwrite software containers with identical names as the ones

that will be installed by MICA Device Management and all user data in these containers will

be deleted.

1. Log in to the MICA with admin rights.

2. Click Install.

3. Click Select File and select the installation archive of the Device Management

(devman_2.3.0_r.tar).

4. Click Execute to start the installation.

5. The installer will display the readme file with information about the installation archive.

6. Scroll to the end of the readme file and click Continue.



7. Wait until the installation is finished and click Close.



The four installed containers (MICADevMan, ManageAccess, PostgreSQL and MQTT) are

initially turned off. To run MICA Device Management with default setting, start the containers in

following the order: MQTT, PostgreSQL, MICADevMan and ManageAccess.

Most users should be able to use MICA Device Management with the default configuration. We

do recommend that you at least perform the default security configuration described in chapter

5, though.

4.3 Installing a MICA Device Management License Key

MICA Device Management requires a license key to remove the restriction to ten devices. Follow

these steps to activate your license.

4.3.1 Obtaining a License Key

1. Open MICADevMan

2. Click Activate

3. Email the information for Product and S/N from the dialog to auto-id-HARTING.com. After we

checked the purchase status, a license key will be emailed to you.

4.3.2 Activating MICA Device Management

After receiving the license file, follow the steps bellow:

1. Open the received license file with an editor.

mailto:[email protected]/



{"Licensee": "DTP Testing", "product": "MICA Device Management", "serial":

"46932414602"}

eyJsaWNlbnNlZSI6ICJEVFAgVGVzdGluZyIsICJwcm9kdWN0IjogIk1JQ0EgRGV2aWNlIE1hbmFnZW1lbnQiLCAi

c2VyaWFsIjogIjQ2OTMyNDE0NjAyIn0AE7YzK1rIf8S99obi71vccgeQM1tQSoLQohMAm/aFjZgX6JoT1OF0cBEQ

qMkwlHZAsgJQZKZSUUY1THniaJFsXCXy3wuQtshNYtSwsH0EyxpP4+WF7beF6rc3wNEMzxLJA8iDHQkgfbNhUQ0l

A37lSZmis+Z75BTmJSIRVInVjgsLuid0UFJK3EJAuOPcMcf8rjZOU/guO5WrHUeUx0/H2UCLISOu5LZQEGBANGQa

a/hPd9cWz7KOafG+0IXQ9BZT1MLzfegCSFqVsn2x6IDlwwuRoP2ZsNp0xZviKe9haWZ9GTWrMEB4HRMJdYKQ7OhS

YQd5jPgxo4drKpQdDZUqA4fASpYFizpfMXd2t+svqA+l9W6kdhH/rEAsRvx5jHWmHp1QzzP1wt+ANc09AJGFcmbP

rn5n2cAtxp6SqBMe3m6huPhY+qOaHdN5gTXlMAavy5HDEFtwJ4ON+Zya3hy0cLt6xPWkPqan258iM08bCrJnIDPX

GHSVNIHgfY9+JbsZLof4arkWVRUMbN8fLVXqHmeo4EwSMyZ5zYCbDm2s4L9N1pNOpW+pc1zNN36Dap3RokQMZDet

vvPou0LKG1TB+2QW+6i6vVqsn26JMOBGYFGEQZYWPVn3qnPE55wvj18ux4DybJvqUJ5XWlMMrIW+d7zktplmU/JN

vNzgQ8DxsyY=

2. Copy the complete key (here: starting with the "e" and ending with the "=") to the clipboard.

3. Open the License dialog (see above) and paste the key into the Key field. Make sure that no

additionally carriage return or line feed characters are inserted into the key string.

3. Click Apply

Your MICA Device Management version is activated now and the Activate button has been

removed from the UI.

In case the license installation fails, you will get an error message. Please check and if necessary

repeat the steps above.

If you are still unable to activate your license, please contact the support

[email protected]

5 Basic Security Configuration

MICA Device Management exchanges data between MICADevMan, ManageAccess and MICA

devices. To prevent information leaks, we recommend that you secure the communication in

between the MICA Device Management components by enabling MQTTs and installing the

necessary security certificates.

For securing the communication, you need server certificates for the PostgreSQL and the MQTT

containers and client certificates for ManageAccess and MICADevMan.

The following section assumes that you have already client and server certificates available. If not,

see section 7.4 for instructions how to generate certificates using OpenSSL.

For securing the communication, it is necessary to enable SSL features in all containers involved.

mailto:[email protected]



After setting up the SSL configuration, the MQTT communication between MICADevMan and

ManageAccess on the one hand and between MICADevMan and PostgreSQL will be encrypted.

5.1 Securing MQTT and PostgreSQL

To enable secure MQTT communication, you need to enable SSL in the PostgreSQL and MQTT

containers and upload the server security certificates.

To enable SSL in either the MQTT or the PostgreSQL container:

1. Open the SSL Section

2. Import the CA Certificate

3. Import the Server Certificate

4. Enter the Server Certificate Passphrase and import the Key file

5. Set the Enable slider to Enabled.

See section 8.4 for instruction to create security certificates.

On Linux the keyfile needs to be set to readable.



5.2 Securing the MICADevMan Container

Click Settings at the top level of MICADevMan.

The MICADevMan container is preconfigured to use the PostgreSQL and MQTT container that

shipped in the installation package. If you want to use an external database or an external MQTT

broker, see section 8.8 and 8.9.

To use secure connection to the database, you have to:

1. Activate SSL

2. Import the CA Certificate

3. Import the Server Certificate

4. Enter the Client Certificate passphrase

5. Import the Key file

5.3 ManageAccess Container

If the ManageAccess container is turned off, start the container by right clicking and choosing Start

App.

Enter the container UI by clicking on the container icon.

You will get the following screen:



The ManageAccess container is setup with default settings for its operation mode and MQTT

connection.

To use secure connection to the database, you have to:

1. Activate SSL

2. Import the MQTT Broker client certificate

3. Enter the client certificate passphrase

4. Import the key file

For information about the discovery mode see section 8.6.

6 Basic Device Management Operations

Devices is the main section for using MICA Device Management. It provides an overview of the

managed MICA devices and lets you group and filter them. Furthermore, it lets you configure the

devices as well as initiate operations on them.

6.1 Device List

The section Devices in MICADevMan shows all MICA reported by ManageAccess.

MICA are stored in logical groups in MICADevMan. Two default groups are predefined: Default and

Ignored.



All devices found by ManageAccess are added to the group Default.

If you do not want to manage discovered MICA devices, you can put them into the group Ignored.

If you have not activated your License key for MICA Device Management, you can store up

to 10 MICA devices across all device groups. Additional MICA are added to Ignored and

remain unmanaged.

To expand a group, click the arrow symbol to the left of the group name.

The number of MICA assigned to a group is shown in square brackets next to the group name.

6.1.1 Sorting and Filtering

You can sort MICA in ascending or descending order by names (or labels

if used). The selected sort order applies to all groups.

You can also filter the list by

Name

Product

FW-Version

Status

Log In Status

Profile



The filter option applies to all groups. If a filter is set, only those MICA devices matching the filter

are shown in the group. The number of MICA devices matching the filter, and the total number of

devices in the group are shown next to the group name.

6.2 Getting Status Information

MICA Device Management displays the status of all connected MICA devices.

Group assignment and its connectivity status are always current. The remaining information are

only accessible if the MICA has sent at least one status report. If a MICA has never been online,

no status information is available.

Item Up to Date

MICA groups assignment Always

Connectivity status Always

Authentication status Login data entered in database: always

Validity of login data: After MICA was

online once.

Device status information (incl.

settings)

If the MICA is online status information is

updated once a minute.

If the MICA is offline, the last status is shown.

Installed software on MICA devices Shown if the MICA is online and the login

information is current.



Success status of last operation on

MICA

Always

6.2.1 Group Display

All detected MICA devices are listed within the groups they have been assigned.

The Default Group contains all detected MICA devices not assigned to a specific group.

6.2.2 Connectivity Status

MICA Device Management regularly checks the connectivity status of the MICA:

MICA is online.

MICA is offline

If you mouse over the connectivity status symbol, you can see the time stamp of the last status

information of the MICA device. If the MICA device is online, the time stamp shall usually not be

older than one minute.

6.2.3 Authentication Status

On the left side next to the connectivity status icon, the authentication status is displayed: .

MICA Device Management distinguishes three different authentication states for a MICA device:



No symbol - Login data of MICA stored and valid.

No login data stored for MICA

The stored login data is invalid for MICA

6.2.4 Device Status and Settings

The connectivity status icons and are buttons. To see the device information including the

latest device status report click on that button to open the device status window.

If the MICA is offline , the most recent status reported for the device is shown. If the MICA has

never reported a status, all the status information are shown as undefined.

If the MICA is online and the login data in MICADevMan is valid, you will get the complete

status information. If the login data is missing or invalid, the status information will be restricted to

the set of information accessible without any authentication on the MICA.

The status report is composed of four sections:



Device Information:

Basic information about the MICA

NTP: Time settings

IPv4 Configuration

IPv6 Configuration

You cannot make any changes in the setting of the MICA in the status report. Use Profiles

for changing the settings.

6.2.5 Installed Software on MICA Device

MICA Device Management collects container status information for MICA that are online with valid

login data stored in the MICADevMan.

1. Select the MICA device



2. Click the drop down button on the left side of the

device button

All containers installed on the MICA will be displayed. Those

coloured yellow are running. The containers coloured grey are

stopped.

Click on the container icon to get information about the container including its network settings.

You cannot make any changes in the setting of the container here. Use Profiles for

changing the settings.

6.2.6 Status of the Last Device Management Operation on a Device

After an operation is performed on a MICA device, MICADevMan displays the result to the right the

device name.

- confirms a successful execution

- reports an error

You can get more information about the operation performed or the error message by moving your

mouse over the feedback mark.

6.2.7 Triggering a Status Report

If you need to get the current status information of your MICA devices, you can trigger a status

report manually.



Enter ManageAccess. Click Report to trigger the MICA devices to report their statuses

immediately.

When you switch back to MICADevMan, the status information of the all managed MICA devices

will be updated.

6.3 Integrating New MICA Devices into MICA Device Management

MICA Device Management allows two options to find and integrate new MICA devices into the

MICADevMan:

automatic detection of MICA devices in your network

manual integration of MICA devices to be connected to your network

Both options require the ManageAccess to be set in Discovery Mode (default setting of

ManageAccess)

Make sure that the MICA devices you want to add into the MICA Device Management are

or will be connected to the same network as the ManageAccess container.

6.3.1 Automatic detection of MICA devices

Automatic detection finds any MICA devices in the same local subnet as ManageAccess.

After the boot process of the MICA is finished, the devices will be detected and displayed in the

Default Group device list.

6.3.2 Store Username and Password for MICA

In order to fully access the MICA and execute operations on a MICA you need to store its

username and password in MICADevMan.



Click on the device button to open the device information dialog. Choose the login role and enter

the password. Click Apply to save the login data and close the dialog.

The warning icon missing key will disappear and you can now use all features of the MICA

Device Management to manage this MICA.

If the missing key icon turns red , your login data is wrong. Please try again to enter the correct

login data.

6.3.3 Adding MICA Devices to MICA Device Management Manually

Usually, MICA will be detected automatically by the MICA Device Management as soon as they

connect to the network as long as they are in the same subnet as ManageAccess.

You can also add MICA devices manually and assign profiles to them. This profile will then be

applied to a MICA Device as soon as it is connected to MICA Device Management.

Enter Device of the MICADevMan.

1. Enter the group you want to add the new MICA to.

2. Click the New Device button

3. Enter the name of the MICA into the New Device window.

Optionally, you can enter:



a label for that device

the username and password

Additionally, you can select the initial profile to be executed on that device.

4. Click Apply to close the dialog. The new device will be added to the group’s device list, but

marked as offline until MICADevMan can connect to it.

You can add a set of MICA devices by using

the Import function (see 8.2).

MICA Device Management will detect the MICA as soon as the MICA connects to your network.

6.3.4 Initial Configuration of MICA Devices

MICA Device Management lets you define an initial configuration of the MICA devices.

It will be executed only for those MICA devices that have been added manually to the

MICADevMan (see 6.3.3) and not to devices discovered automatically by MICA Device

Management.

An initial setup can contain any configuration that can be defined in a profile (see 7). This includes

the network IP configuration and firmware updates as well as container installation.



While adding the MICA, you can select the Profile which has to be executed as initial setup for your

MICA. Make sure that you have entered the login data of the MICA as a profile execution requires

authorization.

This initial profile is executed as soon as the MICA is detected in the network by MICA Device

Management.

Connect the MICA that you added manually to the network. The MICA will be detected and its

status will be set to online: .The execution of the profile starts immediately. While the profile is

being applied, the device button shows up a spinning icon . After successful execution of the

profile, a green check mark shows up on the right side of the device button.

6.4 Grouping MICA Devices

MICA Device Management lets you perform the following group operations:

Create groups of MICA devices.

Move devices between groups.

Perform operations on groups or a selection of devices within groups.

6.4.1 Creating Groups

1. Click



2. Enter a name and description for the group and confirm the group by click on Accept.

The group will be added into the list of groups in Devices

6.4.2 Editing a Group

Click on the Edit icon to change the group name or description.

Make your changes in the dialog and confirm with Apply.

6.4.3 Moving Devices between Groups

You can drag single devices from one group to another or move multiple MICA using the multi-

select feature:

1. Activate the Multiselect option for the group that contains the MICA to be moved

2. Select the devices you want to move by clicking Select all or selecting the MICA devices

individually.



3. Select Move… from the drop down menu

4. Select the destination group and click Apply.

The selected MICA devices are put into the desired group

6.4.4 Deleting a Group

If you want to delete a group, first remove all the MICA devices from the group. Then click the

delete icon that shown next to the empty group.

6.5 Operations on MICA Devices

From the device list, you can perform the following operations on MICA devices.

Restart the MICA device

Start/Stop/Delete a container

Access a MICA's Web UI

To perform these operations the MICA device has to be online and valid login data stored in

MICADevMan.



6.5.1 Device Restart

1. Select the MICA device you want to restart.

2. Mouse over the device button to open the menu bar

3. Click Reboot

The MICA device will be marked as offline until the reboot process is finished. After the boot

process is finished, the MICA will to be online again.

6.5.2 Container Start/Stop/Delete

1. Select the MICA device on which the container should be started/stopped/deleted

2. Open the container view by clicking on the left side of the device button

3. Right click on container you would like to start/stop/delete

4. Click Start App / Stop App / Delete. The device will be in the progress status. After finishing the

operation, the success/failed icon will show up.

6.5.3 Accessing the Web UI of a MICA (Visit MICA)

MICA Device Management allows to open the MICA's WebUI in a new browser tab. The MICA

must be directly accessible from your browser and the Visit-settings have to be configured

according to your network configuration. See section 8.3 for more information.

To open the MICA's Web UI from the device list:

1. Select the MICA device you want to visit and mouse over the device button to open the menu

bar.

2. Click Visit

A new tab in your browser should be opened with the URL of MICA as destination.



3. Enter your login data to access the MICA

6.6 Configuring MICA Devices Using Profiles

MICA Device Managements lets you define Profiles for MICA devices. A profile is a set of

configuration settings and software that will be added to a MICA. Profiles are additive, so any

configuration or software not specified in a profile will not be affected by the operations performed

by the profile.

Profiles let you define

login data

NTP configuration

network settings

container installation and configuration

for a MICA device or a number or MICA devices. You only need to configure those parts that are

relevant for the desired status.

6.6.1 Creating a New Profile

1. In MICADevMan, click Profiles

2. Click New Profile to open the New Profile window.

3. Enter a name for the profile.



If you enter an existing name, the application automatically adds an incremented counter.

Optionally, you can add a description for the profile.

4. Enter your Profile configuration

Profile Field Input

SW-Archive URL of the SW Archive (in universal.tar format); the software archive has to

be located on a http server.

New Credentials User role (admin, containeradmin, or user) and password.

NTP NTP Timeserver Address and Time Zone

IPv4 configuration Set the IPv4 network configuration

IPv6 configuration Set the IPv6 network configuration

Containers Define and configure the containers to be installed with that profile

Click Save to save your profile and to close the dialog.

6.6.2 Applying a Profile

To change the settings on a MICA device, you have to apply the profile.



Applying a Profile to One MICA Device

1. Open the MICA device's information screen (by clicking on the MICA device button)

2. Select the profile to be applied on the MICA device from drop-down menu

3. Click Apply to confirm the profile execution and to close the window.

While the profile is executing, the processing icon is displayed. After finishing, the feedback

check mark will appear on the right side of the device button (e.g. if profile execution was

successful).

Applying a Profile to Multiple MICA Devices

Use the Multiselect operation to apply a profile on more than one MICA at once.

1. Click Multiselect icon icon to enable selection of multiple MICA devices

2. Select the MICA you want to apply the profile to



3. Choose Profile in the Action drop-down

4. Select the Profile from drop down menu and click Apply

The profile is applied on the selected MICA devices. After finishing the execution, the MICA

devices will show the feedback marks.

6.6.3 Installing Containers Using Profiles

In a profile, you can specify containers to be installed on a MICA when a profile is applied.



1. Activate Containers in the profile

2. Click New Container icon to open the window for container configuration:

a. Enter the container name

b. Enter the URL of the container archive on an http file server

c. Choose whether to reinstall (delete if exists and install) the container or

just install (update) the container

d. Select the desired status of the container (Stopped or Started); default setting is

Stopped

e. Choose optional settings:

i. SSO Mode for the container

ii. USB and TTY devices to be assigned to the container

iii. IP settings for the container

3. Click Accept to store the container settings



The container is added to your profile. You can add additional containers by repeating steps 2

and 3.

4. Click Save to store the profile configuration.

6.7 Configuring MICA Devices Directly

You can also change settings directly on a MICA without defining a profile.

We recommend to use this option for simple status changes like changing passwords or

configuring individual IP settings.

6.7.1 Changing Passwords on a MICA Device

Changing passwords requires the admin user role.

1. Click on the MICA’s device button in the device list.

2. Open the Profile drop down menu and click New....



The profile configuration dialog will be opened.

3. Expand New Credentials

4. Select the user role for which the password should be changed

5. Enter the new password. You can verify that the password is set correctly with the Eye button

6. Click Apply.

After a successful password change, a warning icon will appear to remind you to s save the new

login data for that MICA in MICADevMan

6.7.2 Changing the Network-Settings of a MICA Device

Changing network settings requires the admin user role.

1. Click on the MICA’s device button in the device list.

2. Open the Profile drop down menu and click New....

3. Expand IPv4 configuration

4. Enter the IPv4 settings

5. Click Apply.



The progress icon will show up while the change of the network settings is performed. After the IP

settings change, the MICA will reboot and come back online.

6.8 Operations on Multiple MICA Devices

MICA Device Management can perform operations on a group or multiple MICA devices within a

group.

The group operations are: Profile, Properties, Move and Ignore.

1. Select and open the group that contains the MICA devices you want to perform the operation

on

2. Activate the Multiselect option

3. Select the MICA devices in the group individually or choose the Select All option if the

operation shall be performed on all devices in the group

4. Choose the Action from the drop down menu you want to execute on the

set of MICA

5. Follow the instructions on the screen to enable the execution of the

selected operation

7 Profiles

7.1 Working with Profiles and Properties

7.1.1 Overview

In MICA Device Management, Profiles are the key concept to initiate operations on MICA devices.

These include:

setting new login data (Credentials)

configuring NTP time servers

changing network settings

installing and configuring MICA firmware and containers

Profiles define the desired status change for MICA devices and – when applied – perform additive

changes.

Any empty field in the profile's definition will not initiate any change on the MICA. For all unused

fields in the profile, the MICA device's previous configurations stay untouched when the profile is

applied.



In Profiles, you can see the list of stored profiles. Usually, there are no Profiles predefined on

delivery

Each profile can be selected and modified by clicking its button. You can also Delete or Export a

profile by mousing over the button and clicking on the desired operation.

7.1.2 Profile Export

To export a profile, mouse over the profile button and click Export.

The profile will be downloaded as a JSON-File (see 8.2)

7.1.3 Profile Import

You can import profiles. The file has to correspond to the JSON structure defined in 8.2.

It is possible to import multiple profiles by one import file.

Mouse over the New Profile-button. Click on Import. Select the file that defines the profile(s) from

your file system.

If a profile with the same name already exists, the name of the newly imported profile will be

extended by a dash and an index '-i' (e.g. "MyProfile-1").



7.1.4 Shadow Profiles - Initiate Operations without explicitly applying a Profile

You can directly initiate all the status changes that can be defined in a profile, without having

previously defined a profile. Furthermore, if that status change will only be executed once without

any need to preserve the changes in a profile, you can use so called 'Shadow profiles'.

Shadow profiles are profiles which are not stored in the profile's database (in section 'Profiles').

Please be aware: Such a shadow profile cannot be rerun. It can only be executed once on one

MICA device.

To apply a status change on a MICA by using a Shadow profile:

1. Click on the MICA button to open the MICA info dialog.

2. In the field Profile select New…

3. Enter all your settings in the Profile dialog, but do not enter any Name for the profile.

4. Click Apply



7.2 Using Placeholders in Profiles

For operations on multiple MICA devices, you can define placeholder in a profile. These

placeholders will be replaced with parameters when the profile is applied to devices.

7.2.1 Adding Placeholders to a Profile

1. Enter the Device Management UI and click on Profiles.

2. Create a new profile or edit an existing profile

3. Add a placeholder in following notation: ${}

4. Save the profile

7.2.2 Defining Properties for Placeholders

There are two ways to add properties to devices.

1. For a single device

a. Enter the Device Management UI and switch into the devices view

b. Select the device, for which you want to add properties

c. Enter the property key. The property key has to be the placeholder name defined

according to 7.2 without ${}.



d. Enter a value for the property

e. You can enter as many properties you like

2. For multiple devices

a. Enter the Device Management UI and click on Devices.

b. Select the devices, for which you want to add properties.

c. Select Properties from the drop-down menu.

d. In the following mask, you can enter lists of properties, or define map operations.

i. Map: Every selected device will get the same property key/value

ii. List/Range: You can enter a list of properties which will be applied in order..

(First device will get the first property value, the second the second ...)

e. Click Apply

If a placeholder does not have a corresponding device property, the profile execution will fail.

Mouse over the red flag to see information about the missing property



8 Advanced Topics

8.1 Architecture and Network Infrastructure

MICA Device Management is composed of four containers running on a single MICA and

communicating over MQTT or MQTTs.

MICADevMan

ManageAccess

MQTT

PostgreSQL

MICA Device Management – at least the ManageAccess container – requires direct connection to

the MICA devices to be able to detect them in the network. Make sure that ManageAccess is in the

same subnet as the MICA devices.

8.1.1 Network Configuration of MICA Device Management

As default, the containers composing MICA Device Management do not need any IPv4 network

configuration.

However, if ManageAccess requires connection to services provided over IPv4, ManageAccess

requires IPv4 network configuration. For example, ManageAccess is responsible for executing

profiles. Profiles can define the installation of containers from a container repository stored on a

http server. If http server only supports IPv4, you need to configure IPv4 network settings for

ManageAccess.



8.1.2 IPv4 / IPv6

In the normal use of MICA Device Management, it is not necessary to configure the address mode

of the included containers.

All components are designed for IPv6. One exception is that if you are using a HTTP server that is

only accessible via IPv4 to store software packages for installation via MICA Device Management,

ManageAccess needs to be configured to support IPv4 as well.

8.2 The Device Management JSON Formats

Device List JSON Format

MICA Device Management enables to import files defining the list of MICA devices. The structure

of the file is for example.

[

{

"name": "mica-abc01",

"profile": null,

"role": "admin",

"passwd": "admin",

"label": "MICA on machine 1",

"properties" : [{"key" : "ipv4", "value" : "10.10.10.11" }]

},

{

"name": "mica-abc02",

"profile": null,

"role": "admin",

"passwd": "admin",

"label": "MICA on machine 2",

"properties" : [{"key" : "ipv4", "value" : "10.10.10.12" }]

}

]

The MICA device import file requires at least the definition of the key name for a successful import

of a device.

Profile JSON Format

MICA Device Management enables to import files defining a set of Profiles. The structure of the file

is for example.

[

{

"lxc": [

{

"status": 1,

"devices": [],



"ipv4Mode": "1",

"baseDownloadUri": "http:///debian_stretch_v2.3.0_r.tar.lzo",

"name": "Debian"

}

],

"name": "Debian",

"system": {},

"description": "Install Debian Container v2.3.0"

}

]

8.3 Direct Access to the MICA Web UI

MICA Device Management allows you to directly open the WebUI of a MICA device in a new

browser tab.

Two prerequisites that must be fulfilled to be able to use this feature:

The MICA must be accessible from your browser. If you are using a remote ManageAccess and

cannot reach the MICA device, please check that a route from your PC to the MICA device is

available.

8.3.1 Configure the Visit Settings

The Visit settings have to be configured according to your network configuration.

Click on Settings in the MICADevMan container

Select a Visit method that is supported by your network from the drop down. You can choose

between:

Name, e.g. https://mica-abc01/

Name with Domain, e.g. https://mica-abc01.acme.com

IPv4, e.g. https://10.10.10.10

IPv6 ULA, e.g. https://[fd96:8d76:d432:0:a:edf2:f6dd:0]

The chosen method will be used to connect from your web browser to the device when you click

Visit in Device.

https://mica-opcuo/https://mica-abc01.acme.com/https://10.10.10.10/https://[fd96:8d76:d432:0:a:edf2:f6dd:0/



8.4 Security Certificates - Generation and Integration

This section describes how to create Server and Client Certificate via OpenSSL and CLI on Linux

8.4.1 Preparation

Install OpenSSL (e.g. apt-get install openssl)

Create the following directories to store the files created during the certificate generation. You may

need to have root access or use sudo.

mkdir -p /etc/ssl/server/certs

mkdir -p /etc/ssl/server/newcerts

mkdir -p /etc/ssl/server/private

mkdir -p /etc/ssl/server/tmp

Create a list for OpenSSL to keep track of certificate IDs.

echo 00 > /etc/ssl/server/serial

touch /etc/ssl/server/index.txt

Copy /etc/ssl/openssl.cnf to /etc/ssl/server/openssl.cnf

Modify /etc/ssl/server/openssl.cnf as follows

/etc/ssl/openssl.cnf /etc/ssl/server/openssl.cnf

dir = ./demoCA # Where everything is kept dir = /etc/ssl/server # Where everything is kept

certificate = $dir/cacert.pem # The CA

certificate

certificate = $dir/certs/cacert.pem # The CA

certificate

8.4.2 Setup Root Certificate Authority (CA)

Create a private root CA key

openssl genrsa -aes256 -out /etc/ssl/server/private/cakey.pem 4096

Create a self-signed Root CA Certificate



openssl req -config /etc/ssl/server/openssl.cnf -key /etc/ssl/server/private/cakey.pem -

new -x509 -days 7300 -sha256 -extensions v3_ca -out /etc/ssl/server/certs/cacert.pem

Create a private server key

openssl genrsa -aes256 -out /etc/ssl/server/private/key.pem 2048

Create a server certificate request which will be signed by the root CA

openssl req -config /etc/ssl/server/openssl.cnf -key /etc/ssl/server/private/key.pem -new

-sha256 -out /etc/ssl/server/tmp/csr.pem

For the passphrase, use the private server key password created above.

For the fully qualified domain name (FQDN) use

the container name on the MICA, if you are connecting to a container on the same MICA

(e.g. PostgreSQL)

the FQDN to connect to a container on another MICA

For IPv4 you can use the hostname or IP. For IPv6 use the hostname or Unique Local Addresses

(ULA) of the MICA container.

8.4.3 Sign the Requested Certificate with the Root CA

openssl ca -config /etc/ssl/server/openssl.cnf -extensions usr_cert -days 375 -notext -md

sha256 -in /etc/ssl/server/tmp/csr.pem -out /etc/ssl/server/certs/cert.pem

For the passphrase, use the private root CA password created above.

8.4.4 Create the Client Certificate

Create a private client key

openssl genrsa -aes256 -out /etc/ssl/server/private/client.key.pem 2048

Create a client certificate request, which will be signed by the root CA.

openssl req -config /etc/ssl/server/openssl.cnf -key

/etc/ssl/server/private/client.key.pem -new -sha256 -out

/etc/ssl/server/tmp/client.csr.pem

For the passphrase, use the private client key password created above.

Sign the requested certificate by the root CA

openssl ca -config /etc/ssl/server/openssl.cnf -extensions usr_cert -days 375 -notext -md

sha256 -in /etc/ssl/server/tmp/client.csr.pem -out /etc/ssl/server/certs/client.cert.pem

For the passphrase, use the root CA password created above.



8.5 Create Additional Database Users

MICA Device Management comes preconfigured with a default user for the PostgreSQL database.

You do not need to create a user to work with the MICA Device Management.

If you decide to create a new user in the PostgreSQL database for MICA Device Management,

please follow the instructions below:

We recommend to use the user name 'management_user'. We also use this user name as sample

in the instructions for configuration of the MICA Device Management container.

To create a new user:

1. Expand the User section.

2. Click New.

3. Enter the name of the new database user e.g. 'management_user'.

4. Click Apply

Create a new database:

1. Expand Database.



2. Click New.

3. Enter the name of the new database e.g. 'mica_devicemanagment'.

4. Choose a user as owner of the database. Usually, you should assign the user, which you have

created for MICA Device Management in the step above.

5. Click Apply

Define a new access rule:

1. Expand Access

2. Click New

3. Select a database. You should choose the database created for the MICA Device Management

e.g. 'mica_devicemanagement'.

4. Select a user; you should choose the database user created for MICA Device Management

e.g. 'management_user'.

5. Enter the IP address, host name or address range that you want the database to trust; if

MICADevMan is running on the same MICA, you can just enter the container name.

6. Select the method 'trust'.

7. Click Apply.



8.6 Define Managed MICA Devices in ManageAccess

ManageAccess is responsible for detecting MICA devices in your network. All the MICA devices

included in the Devices list will be reported to the MICA Device Management.

ManageAccess provides two modes for discovery: automatic and manual. The mode can be

configured in ManageAccess by enabling or disabling the Discovery mode switch.

After changing the Discovery mode’s configuration you need to save your

settings!

8.6.1 Automatic discovery mode

In default settings of ManageAccess, Discovery mode enabled. In this mode, the network is

scanned automatically for MICA devices. All the detected MICA will be reported in the Devices list

in MICADevMan.

8.6.2 Manual discovery mode

Instead of discovering MICA devices automatically, manual discovery mode lets you define a list of

MICA devices to be reported to MICADevMan.

In the manual discovery mode, you can

Delete MICA devices that have been detected automatically

Add MICA devices that are not (yet) present in the network or that have not been detected

through the MDNS-services (e.g. for MICA base system older than FW 2)

To activate this mode, disable Discovery mode and click Save.

8.6.3 Adding MICA Devices to the Devices List

To add a MICA manually, type the name listed on its type shield into the Add device entry at the

bottom of the Devices list:

Confirm your entry by pressing the Enter key on your keyboard or click on the enter icon .

After finalizing the device list, click Save to save your configuration.

Manually added MICA devices will be reported to MICADevMan only after they have been

connected to the network.



8.6.4 Deleting MICA devices from Devices list

If Discovery mode is disabled, you can remove MICA devices by clicking the delete icons . If

Discovery mode is enabled, move detected MICA devices that you do not want to manage into the

Ignore group in MICADevMan.

After finalizing the device list, click Save to save your device list configuration.

8.7 Handling of Software Packages

MICA Device Management differentiates between three different software packages1.

Container (.lzo)

Container as Software Archive (Universal tar)

Software Archive (Universal tar)

You can configure the container installation in the Container section of the Profile.

A Universal tar created by exporting container contains in most cases two different files.

The container base file system

The Overlay containing the runtime and user data of the container.

Therefore, if you configure a container in this format with a profile, you are not allowed to configure

a separate overlay containing new user data.

A software archive, for example the archive MICA Device Management is distributed in, can

contain any combination of containers, firmware and configuration settings.

In any profile operation, the execution of a software archive will be performed last. This means, if

there are any configuration commands in the software archive, they will override other

configurations in a profile.

1 For more information about the structure of MICA software packages, see Introduction to MICA

Programming on www.harting-mica.com.



8.7.1 Configure Software Packages in a Profile

1. Simple Container

a. Activate Containers in the Profiles window

b. Add a new container and enter the container name

c. Choose if you want to delete/reinstall the container with given Name (if exists)

i. To delete a container, leave the Container URL blank, activate Delete and click

Accept.

ii. To reinstall a container, enter the Container URL and activate Reinstall.

d. To update the user/runtime data, enter a container overlay URL

e. Click Accept.

2. Containers packaged in a Software Archive

a. Activate Containers in the Profiles window.

b. Add a new container and enter the container name.

c. Click Accept.

3. Software Archive



a. To configure a profile with a container installation via a Software Archive, enter the Web

UI of Device Management and switch into the profile view

b. Create a new profile or edit an existing profile.

c. Enter a URL in SW-Archive.

d. Click Accept.

All operations/commands defined in the Software Archive will be performed (Container

Installation, Container update, Firmware update, etc.). This may cause inconsistencies with

profile parameters.



8.8 Using an External MQTT Broker

You can also host your own Mosquito 1.5.2 MQTT Broker on a server of your choice. To use an

external MQTT Broker you need to configure a client access method.

The MQTT Broker should offer at least one of the following client Authentication methods:

No Authentication

Certificate Authentication

Make sure that the IP setting of MICADevMan, ManageAccess and the MQTT Broker match.

8.9 Using an External PostgreSQL Database

You can also host your own PostgreSQL Version 11.1 database on a server of your choice. To use

it with MICA Device Management, the following database configurations should be made:

Create a database for MICA Device Management (e.g. 'mica_devicemanagment').

Create a new database user (e.g. 'management_user').

Configure the database access for created user.

Example (pg_hba.conf)

TYPE DATABASE USER ADDRESS METHOD

host 'mica_devicemanagement' 'management_user' 192.168.2.113 trust/md5/…

…

The Database should offer at least one of the following client Authentication methods:

Trust Authentication

Password Authentication

Certificate Authentication

Grant the privileges SELECT, INSERT, UPDATE, DELETE, CREATE, TRIGGER, REFERENCES,

TRUNCATE (=> ALL) on the created database for the created user (e.g. GRANT ALL ON

mica_devicemanagement TO management_user;)

MICA Device Management will create the necessary tables in the PostgreSQL database on initial

start-up.



Make sure that network settings of MICA Device Management and the PostgreSQL host match.

8.9.1 Configuring a Custom PostgreSQL (DB) connection

1. By default, Host is set to the PostgreSQL database server included in MICA Device

Management. If you are using another PostgreSQL database server, you can specify the host

by its hostname or IP address. If you run a PostgreSQL DB container on the same MICA, you

only need to insert the name of that container.

2. In Database, enter the name of the database that will be used by MICA Device Management.

3. In User enter the database user. The user name has to be match the user name defined in the

database.

8.10 Configuring a Custom MQTT Connection

1. In Host, enter the host of the MQTT Broker. The host can be either an IPv4 address, an IPv6

address or a DNS hostname. If you run an MQTT container on the same MICA, you only need

to insert the name of that MQTT container. When using the default container name "MQTT",

you do not need to change this configuration.

2. To use secure MQTT connection, you have activate SSL. This is required if you have

configured your MQTT Broker to use secure communication as well.

Please upload the required certificate files:

a. Import the CA Certificate

b. Import the Broker Client Certificate

c. Enter the Client Certificate passphrase and import the Key file

For using secure MQTT connection, you need to have a client certificate (see 8.4) for your

host.



8.11 Configuring a Custom MQTT Connection in ManageAccess

Enter the address of the MQTT broker. The address can be either an IPv4 address, an IPv6

address or a DNS hostname. If you run an MQTT container on the same MICA, you only need to

insert the name of that MQTT container.

To use secure MQTT connection, you have to activate SSL, upload the CA Certificate and the

Broker Client Certificate, enter the Client Certificate passphrase, and import the Key file.

8.12 Logging

The Device Management logs the messages that exchanged between the Device Management

itself and Manage Access. All messages are logged with a UTC time stamp.

This messages can be downloaded in the section Device Management→ Settings → Tools.

The content of downloaded file might look like:

[

{

"id":45,

"msg":{

"id":"1812876e-b178-40c7-a606-52de314ad7f3",

"profile":"Test",

"status":"WARNING",

"timestamp":"2019-02-04T12:01:00.729522",

"target":"mica-4nj7",

"result":"install_utar->WARNING:Additional Command found",

"operation":"profile.apply"

}

},

…

]



8.13 MICA Devices with MICA Base System 2 or Earlier

MICA devices with MICA Base System lower than firmware 2 are not supported by MICA Device

Management. You can add them manually to perform a remote firmware upgrade, but most other

functions of MICA Device Management are not available for devices running firmware 5 or lower.

You should always keep your system updated and use the current MICA Base System

version. You should not run the MICA with older MICA Base System version.

Date post:	31-Jan-2021
Category:	Documents
Upload:	others
View:	0 times
Download:	0 times

HARTING MICA Device Management - User Manualmica-container.com/container/devman/MICA_Device... ·...

Documents