VMware Pulse IoT Center Server Installation Guide GA - Word€¦ · VMware Pulse IoT Center Server...

VMware Pulse IoT Center Server Install Guide

2 VMware, Inc

Copyright © 2018 VMware, Inc. All rights reserved. Copyright and trademark information.

VMware, Inc. 3401 Hillview Ave Palo Alto, CA 94304 www.vmware.com

http://pubs.vmware.com/copyright-trademark.html

http://www.vmware.com/


3 VMware, Inc

Introduction .................................................................................................................................... 6

Before you Start .......................................................................................................................... 6

Prerequisites ............................................................................................................................... 7

OVA General Information and Changes Since the BETA............................................................. 8

VMware Pulse IoT Center Components ........................................................................................ 10

Device and Software Lifecycle Management ........................................................................... 10

Hardening Windows Installation .......................................................................................... 11

Host Mapping in VMware Pulse Device Management Suite ................................................ 15

Importing Pulse IoT API CA into VMware Pulse Device Management Component ............. 15

Enforce Strong Passwords .................................................................................................... 16

Enabling IoT Support ............................................................................................................. 17

Secure Edge System/Gateway Enrollment ........................................................................... 18

Operation Analytics Module ..................................................................................................... 20

Installation ............................................................................................................................ 20

Configuration ........................................................................................................................ 20

Helix Adapter Installation ..................................................................................................... 25

VMware Pulse IoT Center Frontend Modules .......................................................................... 28

Frontend Installation - Pulse OVAs ........................................................................................... 28

OVF Parameter Configuration .............................................................................................. 28

Application Specific Common OVF Properties .................................................................. 29

Virtual Appliance Management Infrastructure (VAMI) properties .................................. 32

Passwords and passphrases .............................................................................................. 32

VMware Pulse IoT API Server.................................................................................................... 32

Prerequisites ......................................................................................................................... 33

System Services ..................................................................................................................... 33

OVF Properties ...................................................................................................................... 33

Deployment Options ......................................................................................................... 38

Post Installation .................................................................................................................... 38

Ports ...................................................................................................................................... 39

Logs and Configurations ........................................................................................................ 39

Database Backup and Restore .............................................................................................. 40

Install Pulse API OVA using vSphere Web Client UI .............................................................. 40


4 VMware, Inc

Install Pulse API OVA using CLI with the ovftool ................................................................... 43

VMware Pulse IoT Console ....................................................................................................... 44

Prerequisites ......................................................................................................................... 45

System Services ..................................................................................................................... 45

OVF Properties ...................................................................................................................... 45


Post Installation .................................................................................................................... 47

Ports ...................................................................................................................................... 48


Install - vSphere Web Client .................................................................................................. 49

Install - CLI with ovftool ........................................................................................................ 52

MQTT Broker ............................................................................................................................. 52

System Services ..................................................................................................................... 53

Prerequisites ......................................................................................................................... 53

OVF Properties ...................................................................................................................... 53


Post Installation Configuration ......................................................................................... 56

MQTT Plugins ................................................................................................................ 56

Firewall Configuration ................................................................................................... 57

Ports ...................................................................................................................................... 58


Install - vSphere Web Client .................................................................................................. 58

Install - CLI using ovftool ....................................................................................................... 62

Post Installation Configuration for Helix Adapter in vRealize Operations Manager ............ 63

Upgrade ..................................................................................................................................... 64

Pulse Components Integration Configuration .............................................................................. 65

Step 1: Login .......................................................................................................................... 65

Step 2: Password Reset ......................................................................................................... 65

Step 3: EULA .......................................................................................................................... 65

Step 4: System Configuration ............................................................................................... 65

Step 4.a: Lifecycle Management: Management Console Configurations ............................ 66

Step 4.b: Operational Analytics Configuration ..................................................................... 67

Step 4.c: VMware Identity Management Configuration (optional)...................................... 67


5 VMware, Inc

Step 4.d: SMTP Server Settings ............................................................................................. 69


6 VMware, Inc

Introduction

VMware Pulse IoT Center is a suite of VMware products that provides a complete IoT solution to onboard, manage, secure and configure the IoT edge system and connected devices. This document serves as guide for server-side installation of the VMware Pulse IoT Center.

A complete installation of the VMware Pulse IoT Center consists of the following server-side components.

• VMware Pulse Device Management Suite (Backend and Console) • vRealize Operations Manager 6.6.1 Standard with Helix Adapter Support • EMQTT Broker • VMware Pulse IoT Center Console (UI) • VMware Pulse IoT Center API Server

EMQTT broker, VMware Pulse IoT API, and the Console are distributed as separate OVAs. The OVAs are based on Ubuntu Server 14.04 (x86_64). For installation instructions about VMware Pulse Device Management Suite and vRealize Operations Manager 6.6.1 see their respective product installation documentation. The VMware Pulse Device Management Suite is essentially the VMware AirWatch mobile device management suite tuned for IoT. This version of AirWatch is limited to IoT devices alone and any other device types such as mobile devices are unsupported.

Before you Start

The information in this document is written for experienced administrators who are familiar with the following:

• Windows and Linux installation and configuration. Including the expertise to tune system, network, and firewall configuration. This includes Network Address Translation(NAT), firewall, syslog and port mapping configurations.

• Server virtualization. primarily those provided by VMWare including vSphere and vCenter. This release only supports deployments to VMware vCenter based environments though there are descriptions on deployments in VMware vCloud Director based environments like OneCloud and vCloud Air sprinkled with in this document.

• Installing and configuring database servers. Microsoft SQL Server on Windows and PostgreSQL on Linux.

• Microsoft Active Directory Services

https://resources.air-watch.com/view/nlxgxjbq92ngyyl592qc/en

https://docs.vmware.com/en/vRealize-Operations-Manager/6.6/vrealize-operations-manager-66-vapp-deploy-guide.pdf



7 VMware, Inc

The OVAs are currently built for a small and medium installation. Refer to the Pulse IoT Center Sizing Guide for the number of managed objects that are supported by a small and medium installation.

Deploy the components in the following order to address dependencies.

• VMware Pulse Device Management Suite (also called Device and Software Lifecycle Management)

• VMware vRealize Operations Manager with Helix Adapter Support • VMware Pulse IoT Center API Server • VMware Pulse IoT Center Console (UI) • EMQTT Broker

Before you deploy the VMware Pulse IoT Center components, ensure that all computing and networking resources such as VMware OneCloud or VMware vCenter are available in the deployment infrastructure.

Prerequisites

Before you install and deploy, review the following prerequisites. The prerequisites apply to the Pulse Device Management Component and vRealize Operations Manager:

• VMware Pulse Device Management Suite, AirWatch. Verify that the user already has a license to Microsoft Windows Server and Microsoft SQL Server. Neither the license nor the SQL Server installer is a part of the VMware Pulse Software distribution and is a cost that must be covered by the user. The supported SQL server versions are SQL Server 2008 R2, SQL Server 2012, or SQL Server 2014 (in 2012 compatibility mode) with Client Tools (SQL Management Studio, Reporting Services, Integration Services, SQL Server Agent, and latest service packs). Ensure the SQL Servers are 64-bit (OS and SQL Server).

• VMware Pulse Device Management Suite, AirWatch. Installation is supported only on a Windows Server 2008 R2/2012, or 2012 R2 (64-bit) with the latest service packs and recommended updates from Microsoft (http://www.update.microsoft.com). Windows Servers are not a part of the VMware Pulse distribution and the cost of the Windows Server license must be borne by the user. The user will need at least two Windows Server instances and licenses for installing the SQL Server and the other for installing the VMware Pulse Device Management Suite.

• Verify that there are SSL Certificates from trusted CAs or private CAs if you do not intend to use the certificates generated by default in every OVA. The system needs the SSL certificates in PKCS12 format with the complete certificate chain in the order of intermediate to root and that follows the signing hierarchy.

http://www.update.microsoft.com/


8 VMware, Inc

• Verify that there are valid domain names for Pulse IoT API, IoT Console Server, Pulse Device Management Sever and the EMQTT Broker. The names should reflect in the common name and SAN of the SSL certificate.

• Create an A Record and PTR record for both forward and reverse resolutions in DNS using both hostname and IP. This is mandatory as Pulse IoT involves multiple server-side components that are separately installed and must talk to each other with a full server certificate validation (both the hostname and CA cert).

• Enable “Guest OS Customization" for OneCloud or vCloud Air, on the VMs, before starting the VM. This ensures that the VM is configured with the right hostname and network settings. For vCenter environments, use the OVF properties to configure static IPs.

• Verify that vCenter access is setup with necessary storage. Verify that the network objects are pre-created and configured to deploy VMs that can talk to each other internally.

• Verify that you have access to a Bash shell. On Windows to get a near Bash like shell, Cygwin or MSYS2 can be installed and used. The shell is used to Base64 encode artifacts like certificates that need to be passed during OVA deployment with an additional base64 encoding for line and format preservation. The line and format gets affected when passed using OVF properties into vCenter especially in the case of multiline inputs like a CA certificate file.

OVA General Information and Changes Since the BETA

For customers already using the BETA, there is no migration path. A fresh install of the GA is the norm and once setup, the IoT edge systems and connected devices must be re-enrolled into the GA version. VMware recommends that this migration be done in a phased manner. From an installation perspective, there are a few other changes and improvements as listed below.

• The VMware Pulse IoT Center Console and the VMware Pulse IoT Center API Server services run as a projectice user. This is a standard Linux user with no sudo privileges. A password is not set for this account and hence only a local login is possible using sudo or su via the root user or any other user with sudo privileges created post the install by an administrator.

• The EMQTT Broker runs as a user with the name emqtt. This is a standard user with

no administrative privileges. The EMQTT Broker does not have a projectice user.

• The iceadmin user which was available in the BETA release is no longer available in the GA release. Perform all administrative tasks by using the root user account only or by using any other user with sudo privileges created post the install by an administrator. Its recommended to create an administrative user with sudo privileges and not use or share the root user.

• The GA release has separate OVAs for VMware Pulse IoT Center Console, VMware Pulse IoT Center API Server, and the EMQTT Broker instead of a single OVA as it was in the BETA release.


9 VMware, Inc

• To make the installation experience smooth, additional configuration options have been added via new OVF properties. However, you might still have to make manual configurations.

• The IoT API, IoT Console Server and the EMQTT Broker have lockout period of 20 minutes for the terminal access when credentials fail to authenticate. Hence it is advised not to share the root user credentials to avoid the same getting locked up. Instead,

create a separate user for each individual requiring administrative access for the terminal with sudo privileges.

• Certificate Revocation is supported for any externally provided certificates. The internally generated certificates by the OVAs during deployment do maintain a certificate revocation list.

VMware Pulse IoT Center Components

This section explains the installation of the VMware Pulse IoT Center components. The deployment diagram illustrates the wiring between the VMware Pulse Components that this document helps to accomplish along with data flow and the corresponding TCP port. The illustration is just an example and can vary from setup to setup.

Device and Software Lifecycle Management

The device and software lifecycle management functionality is achieved via the VMware Pulse Device Management Suite. This is the VMware AirWatch Device Management retuned for IoT and all other mainstream devices supported by AirWatch are not supported in this version.


11 VMware, Inc

Hardening Windows Installation

Before installing the Pulse MDM and database in a Windows machine, you must harden the SSL configuration to use only TLS 1.2 for all incoming and outgoing connections. Copy the following contents to a notepad on the target Windows machine and save the file with a .reg extension. Right-click to merge.

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL]

"EventLogging"=dword:00000001

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher

s]


s\AES 128/128]

"Enabled"=dword:ffffffff


s\AES 256/256]



s\DES 56/56]

"Enabled"=dword:00000000


s\NULL]



s\RC2 128/128]



s\RC2 40/128]



s\RC2 56/128]



s\RC4 128/128]



s\RC4 40/128]



s\RC4 56/128]



s\RC4 64/128]



12 VMware, Inc


s\Triple DES 168]



Suites]

[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes

]


\MD5]



\SHA]



\SHA256]



\SHA384]



\SHA512]


[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\KeyExc

hangeAlgorithms]


hangeAlgorithms\Diffie-Hellman]



hangeAlgorithms\ECDH]



hangeAlgorithms\PKCS]


[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc

ols]


ols\Multi-Protocol Unified Hello]


ols\Multi-Protocol Unified Hello\Client]


"DisabledByDefault"=dword:00000001


ols\Multi-Protocol Unified Hello\Server]




ols\PCT 1.0]


13 VMware, Inc


ols\PCT 1.0\Client]




ols\PCT 1.0\Server]




ols\SSL 2.0]


ols\SSL 2.0\Client]




ols\SSL 2.0\Server]




ols\SSL 3.0]


ols\SSL 3.0\Client]




ols\SSL 3.0\Server]




ols\TLS 1.0]


ols\TLS 1.0\Client]




ols\TLS 1.0\Server]




ols\TLS 1.1]


ols\TLS 1.1\Client]




ols\TLS 1.1\Server]




14 VMware, Inc


ols\TLS 1.2]


ols\TLS 1.2\Client]




ols\TLS 1.2\Server]



The registry settings enable only TLS 1.2 and 1.1 and disables TLS 1.0, SSLv3, and SSLv2. You can restrict support for SSL ciphers by launching the Group Policy Management Console.

Procedure Launch the Group Policy Editor in the Windows Server

1. Navigate to Computer Configuration -> Administrative Templates -> Networks -> SSL Configuration settings.

2. Double-click the SSL Cipher Suite Order and select Enabled. 3. Double-click the box below the SSL Cipher Suites and select all and copy into a text

editor such as a notepad. 4. Edit the comma separated values to remove the unwanted values and copy the resulting

value. Click Apply.

An example of a good SSL cipher list would be:

TLS_ECDH_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_ECDSA_

WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_G

CM_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TL

S_RSA_WITH_AES_256_GCM_SHA384,TLS_ECDH_RSA_WITH_AES_

128_GCM_SHA256,TLS_ECDH_ECDSA_WITH_AES_128_GCM_SHA25

6,TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,TLS_ECDHE_EC

DSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_128_GCM

_SHA256,TLS_ECDH_RSA_WITH_AES_256_CBC_SHA384,TLS_ECD

H_ECDSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_RSA_WITH_A

ES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_S

HA384,TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDH_RSA_W

ITH_AES_256_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_256_CBC_

SHA,TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA,TLS_ECDHE_ECD

SA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA


15 VMware, Inc

,TLS_ECDH_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_ECDSA

_WITH_AES_128_CBC_SHA256,TLS_ECDHE_RSA_WITH_AES_128_

CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256,T

LS_RSA_WITH_AES_128_CBC_SHA256,TLS_ECDH_RSA_WITH_AES

_128_CBC_SHA,TLS_ECDH_ECDSA_WITH_AES_128_CBC_SHA,TLS

_ECDHE_RSA_WITH_AES_128_CBC_SHA,TLS_ECDHE_ECDSA_WITH

_AES_128_CBC_SHA

The text box for entering SSL cipher suites cannot support more than 1023 characters. Note the above cipher suite list exceeds 1023 characters. Note: Once applied, you must restart the system for all the above changes to take effect.

Host Mapping in VMware Pulse Device Management Suite

VMware Pulse Device Management Suite requires connectivity to:

• VMware Pulse IoT API server to send notifications • VMware Identity Manager (if configured)

If the above servers can be reached by an internal route from the Windows VM, add an alias in the %SystemRoot%\drivers\etc\hosts file to either of the machines using the

external FQDN name to avoid a round trip. The FQDN name is important for the SSL validation to take place as each of these servers are invoked over HTTPS. Add the alias before the Pulse API is configured with the Pulse Device Management Component settings using the Settings dialog in the Pulse Console.

Importing Pulse IoT API CA into VMware Pulse Device Management Component

If the installation of Pulse IoT API is using a self-signed certificate, make sure you add the root ca certificate of the self-signed certificate in the Windows System Certificate stored under Trusted Root Certificates on the machine where VMware Pulse Device Management Component is installed. This helps the SSL validation to succeed when VMware Pulse Device Management Component makes an SSL call into the Pulse IoT API to deliver notifications. The hostname used by the VMware Pulse Device Management Component API to reach Pulse IoT API must match with the content in the actual certificate configured for the Pulse IoT API Service.

Complete the steps of Hardening Windows Installation and Host Mapping in VMware Pulse Device Management Suite before configuring the Pulse API with the Pulse Device Management Component and vRealize Operations Manager settings using the Pulse Console.


16 VMware, Inc

To import the private CA into the Windows certificate store where the Pulse Device Management Suite is installed, complete the following steps.

1. Copy the cacert from /opt/vmwpulse/certs/cacert.pem in the Pulse API VM to the Pulse Device Management Component VM (Windows VM).

2. Launch mmc.exe in the Pulse Device Management Component VM. 3. Select File > Add/Remove Snap-in. 4. From the Available snap-ins section, select Certificates and click Add. 5. Select Computer Account and select Next. 6. From the Select Computer dialog box, select Local Computer. 7. Click Finish and then OK. 8. Right-click Certificates > All Tasks under the Third-party Trusted Root Certificates

Authority to import the certificate. 9. Follow the import wizard to save the private CA certificate that was saved from the

browser

Turn off Automatic Certificate Updates If there are private certificate authorities installed in the Trust Root Certificates in Windows Server, the Windows Root Certificate Update process will clean them up on update. This cleanup removes CA certificates of the Pulse API service if the Pulse API service is hosted using self-signed certificates or certificates with private CAs that get generated during the Pulse API installation. The removal will result in Pulse Device Management Component notifications to reach Pulse API. This can be prevented by disabling the Automatic Root Update Certificate process by the group policy editor. For more information refer to this link. Alternatively, if there are constraints in disabling the Automatic Certificate Updates makes sure to add the following script to the window scheduler to run with admin rights. The script can be saved in file with .bat extension. The argument to the script should be the full file path to the CA certificate in .cer format.

Enforce Strong Passwords

echo off

title SSL Cert Check

:: See the title at the top

set cert=%1

certutil -addstore "AuthRoot" %cert%

https://technet.microsoft.com/en-us/library/cc734054(v=ws.10).aspx


17 VMware, Inc

Increase the password complexity of the Pulse Device Management Component Console with eight or more characters with a that includes alpha-numeric characters and symbols. You can enforce strong passwords at the root Organization Group (OG) that is inherited across the child OGs. To enforce strong passwords, ensure that you make the change in the root OG, and complete the following step: Procedure

• Select Settings > Admin > Console Security > Password and enter the details.

Enabling IoT Support

IoT support must be enabled in the Pulse Device Management Component as shown in the screen shot below.


18 VMware, Inc

• Select Settings > Device and Users > Advanced > IoT Support.

MQTT Integration is a mandatory configuration in the Pulse Device Management and the MQTT URL and port. This is essential for the side load package generation and the enrollment flow for the IoT edge devices.

Secure Edge System/Gateway Enrollment

From a security perspective you must allow the enrollment credentials generated on the Pulse Console to be used by one edge system/ gateway only. You can make this configuration at the root OG. The configuration is inherited across child OGs. This setting is mandatory. To configure a secure edge system/ gateway enrollment, complete the following steps: Procedure

1. From the Pulse Device Management Component Console, navigate to Settings > Devices & Users > General > Enrollment and select the Restrictions tab.


19 VMware, Inc

2. Expand Add Policy and enter the changes.

3. Enter a name in the Enrollment Restriction Policy Name field. 4. Uncheck the option Unlimited against the Device Limit Per User option. 5. Ensure that all the values are 1 in the Device Limit per User section.


20 VMware, Inc

6. Click Save in the Add/Edit Enrollment Restriction Policy dialog box and click Save again to close the Settings dialog box.

Operation Analytics Module

Installation

Install vRealize Operations Manager next. For more information see the vApp Deployment and Configuration guide.

Configuration

VMware Pulse Operational Analytics relies on vRealize Operations Manager 6.6.1 and is part of the VMware Pulse distribution. The installer is an OVA with SUSE Linux as the base operating system.




21 VMware, Inc

Refer to the vRealize Operations Manager installation guide for information about deploying this OVA release. While installing, refer to the sizing guidelines to decide on the number of CPUs, memory, and storage required. When you log into the VM, the default password for the root user is empty. Press enter and set a new password on first login. This login must take place from the terminal console where the OVA is deployed. SSH is disabled by default.

To enable SSH on vRealize Operations Manager, complete the following steps:

Procedure

1. Log in to the vRealize Operations Manager virtual machine console as root using ALT-F1. 2. Start the SSH service by running the service sshd start command 3. Run the chkconfig sshd on command to configure SSH to start automatically.

After you have deployed and powered on vRealize Operations Manager, access vRealize Operations Manager using https://<IP-address>. You are guided through the basic installation steps of vRealize Operations Manager. Select Express Installation and provide a password for the vRealize Operations Manager instance. Note: Obtain a standard license key to use vRealize Operations Manager. You must also configure vRealize Operations Manager after install.

Procedure

1. Log in to the vRealize Operations Manager after the server boots up. Select Express Installation.


22 VMware, Inc

2. Enter a username and password. The password and username you provide is used to log in to vRealize Operations Manager. Select Next.


23 VMware, Inc

3. Select Finish.

4. Log in to the vRealize Operations Manager Console with credentials used earlier Accept the EULA and click Next.


24 VMware, Inc

5. Enter the product license key and validate. Click Next.

6. Optionally, join the VMware Customer Experience program and click Next.


25 VMware, Inc

7. Click Finish.

vRealize Operations Manager generates an SSL certificate with a private CA during the deployment of the OVA. In case this certificate doesn’t have the right hostname in the Common Name part of the certificate or an SSL certificate needs to be installed from a Certificate Authority vendor follow this VMware KB article and refer to the section titled vRealize Operations Manager 6.x.

Helix Adapter Installation

Use HelixAdapter-4.4.26.pak or later. This distributed separately along with the OVAs. Complete the following steps to install the adapter.

https://kb.vmware.com/s/article/2046591


26 VMware, Inc

Procedure

1. Navigate to https://<vROPs-IP-address>/ui/index.action#/administration/solutions. 2. Click the '+' sign to add a solution. 3. Click Browse and select the PAK file you downloaded. 4. Click Upload and then click Next. Click Yes to confirm.


27 VMware, Inc

5. Accept the agreement and click Next.

6. Wait for the installation to complete and click Finish.


28 VMware, Inc

7. Verify the Helix Adapter version. The adapter must be in the data receiving state.

You must configure the Helix adapter to connect to EMQTT. For more information refer to the EMQTT section , in Post Installation Configuration for Helix Adapter in .

VMware Pulse IoT Center Frontend Modules

Frontend Installation - Pulse OVAs

The VMware Pulse contains three individual VMs running the Ubuntu 14.04 Server.

o pulseapi.ova - With VMware Pulse IoT API and PostgresSQL v9.6 pre-installed. o pulseconsole.ova - With VMware Pulse IoT Console and all the dependencies. o mqttbroker.ova - With the EMQTT broker v2.2 stable version

from http://emqtt.io

When you deploy the OVAs, you will need application specific properties for initialization. For more information about these properties refer to the next section called OVA Parameter Configuration. Deploy the OVAs in vCenter based environments only.

Install the OVAs in the following order assuming that the Pulse Device Management Component and Pulse vRealize Operations Manager are already installed.

1. Pulse IoT API 2. Pulse IoT Console 3. MQTT Broker

OVF Parameter Configuration

http://emqtt.io/


29 VMware, Inc

Deploy the OVA using vSphere and the Deploy OVF template from the vSphere UI. You can also use the OVF tool from the command line. The properties are covered in detail for each OVA.

Note that the OVF properties are used to configure the VM after the VM is powered on and the tools used to deploy the OVA do minimal or do not validate the properties. If there are any incorrect property values, it will result in starting up the system (VM), and can cause the application and system to be in an unusable state. You must pass the OVF properties as advised with in this document. If there are any errors, delete the VM and deploy it again with the correct property values.

Application Specific Common OVF Properties

Some of the OVF properties are common across OVAs and are as follows. Subsequent OVA sections will describe the property with updates specific to that OVA

Property name

Constraints on Values Description

varoot-

password An alphanumeric password of eight or more characters for the root account.

If you do not set this password or if it is less than eight characters, the default password expires. You must change the password on first login. The default password is vmware. You must ensure that the password is complex.

The root account by default is not enabled for SSH access using the password and is only allowed using key based authentication.

It is recommended that you provide a root password using this property.

One Cloud or vCloud based deployments must disable the option to change the root password. Navigate to Properties > Guest OS Customization before the VM is turned on for the first time after deployment for this property to take effect.

ssh-

public-

key

An SSH public key that must be added to the authorized keys for the root user.

After an OVA is deployed, you can access the console terminal from the vCenter console.

If an SSH connection must be established to the VM as a root user, an SSH public key of a trusted machine from where the SSH connection is made can be passed as a value to this


30 VMware, Inc

property.

This gets added to the authorized keys in the VM for the root user and an SSH connection (with no password) will be possible from the trusted machine.

You can pass only one SSH public key.

An invalid or expired root password will cause the SSH connection with no password to fail.

It is recommended that you access the root account only from trusted machines. For better auditing, you must create users with sudo privileges for server administration instead of using the root account.

No validity is performed on the key and hence you must make sure that a valid SSH key is provided for a seamless connection.

ssl-

pkcs12 Input an external SSL certificate in the PKCS12 format

encoded in base64 without line wraps.

All VM Pulse components are configured to communicate over SSL by default. This property can be used to provide an external SSL certificate in PKCS12 format.

This is useful if you need to use an SSL certificate bought from a known CA vendor or the organization has a process of generating certificates by using an internal CA.

If the SSL certificate is not provided, the OVA on installation generates an SSL certificate signed by a private CA that it generates. The generated SSL certificate will have the hostnames and IP addresses that it can discover at the time of booting up except for the local host. The private CA generated will be different for each component VM.

The PKCS12 file must contain the private key, the cert, and the entire certificate chain in the right order from intermediate to root CA. You must protect the PKCS12 file with an export


31 VMware, Inc

password.

The PKCS12 is a binary file and must be converted to a base64 format without any word wraps before being passed using an OVF property. Execute the command

cat sslchain.pfx | base64 - w

0

and copy the output as property value. The OVF properties do not accept binary values and hence the need to encode them as base64.

ssl-

pkcs12-

passwd

Password for the ssl_pkcs12 file

The password for the externally supplied PKCS12 file or for the internally generated PKCS12 file. If you do not supply a PKCS12 file, the same password will be used for the internally generated certificates as well.

This is mandatory. ssl-

cacerts List of cacerts in CER format needed by the application to connect to external servers with another level of base64 encoding

Property to facilitate adding additional cacerts to the application specific trust stores. The cacerts need to be in CER format and must be base64 encoded again. This is because during the OVA deployment the base64 line wraps in the CER are tempered by the vCenter user interface and the ovftool that makes the certs useless.

cat mycacert.pem | base64 -w 0

If more than one cacert needs to be provisioned, then they must be concatenated and then base64 encoded without line wraps using the following command. Note that that the filenames mycacert1.pem mycacert2.pem mycacert3.pem shown in the command are just examples.

cat mycacert1.pem

mycacert2.pem mycacert3.pem

| base64 -w 0

You do not have to import the cacerts if the applications in multiple OVAs are sharing the


32 VMware, Inc

same SSL certificate or are using a certificate signed by a common CA.

Virtual Appliance Management Infrastructure (VAMI) properties

There are properties within the OVA that are defined by VMware's VAMI agent related to system and network configuration and applies to vCenter deployment. vCloud or One Cloud based environments can continue to use the network configuration using the Guest OS customization.

The networking properties provided by VAMI are used to configure static IPs in vCenter environments. If you use DHCP based IPs, it is recommended that you leave all networking property values empty. If you use DHCP, it is recommended that you fix the IPs using DHCP reservation.

Since the fully qualified networking property name for these properties are slightly different for each OVA, they are covered in the sections below for each OVA.

Property Name Constraints on Values Fully Qualified Property Name

Description

vamitimezone Mandatory to leave this as Etc/UTC

vamitimezone Mandatory to leave this as Etc/UTC

Passwords and passphrases

You must remember all passwords and passphrases entered into the system. After you submit the password, it cannot be recovered. If the Linux login password is entered incorrectly five times or more, the system login has a lockout period of 20 minutes. You must also securely back up the configuration files and the Pulse API DB to restore the system. Its advised to take a backup before an upgrade of the Pulse API.

VMware Pulse IoT API Server

The Pulse IoT API Server is distributed as a standalone OVA. You must install and wire this OVA with other Pulse components to be functional. Most of the Pulse API OVA options are configured at installation time using the OVF parameters. However, you can wire with Pulse Device Management Component and Pulse vRealize Operations Manager only using the Pulse Console after both the Pulse API and Console are installed.


33 VMware, Inc

The install folder for Pulse API is at /opt/iot-api. All the contents under /opt/iot-api are owned by the projectice user and any changes to this ownership or permissions can cause the Pulse API server to fail.

Prerequisites

1. Verify that there is a domain name for the Pulse API and Console. An 'A' Record and PTR Record must be created in the DNS server.

2. Verify that the SSL certificate matches the domain name for the Pulse API. If an SSL certificate is not provided, the VM created out of the OVA will attempt to generate an SSL certificate using the domain name for the Pulse API.

3. Verify that there is a CA cert of the Pulse Device Management and vRealize Operations Manager that needs to be added to the CA list in Pulse API.

System Services

The Pulse API run as a sysvinit service as iceapi and depends on the postgresql service. There are other services required for the full functionality of the VM including the VMware agents. To get a list of the default upstart services that have started, run the following command:

service --status-all

To get a list of all sysvinit services, run the following command:

initctl list

You must run both the commands as a root user.

OVF Properties

Property Name

Constraints on Values

Description


34 VMware, Inc

api-

externalname Fully qualified domain name

The fully qualified hostname for the Pulse API. If Pulse API Server has an external hostname that is different from the internal hostname, this parameter must be set to the external hostname. This applies usually when there is a DNAT rule set from a public IP to internal IP.

If there is no external hostname for a purely intranet setup, then you can set this property to the fully qualified internal hostname. A fully qualified hostname must be reserved for this VM. The FQDN must be resolvable using a DNS lookup.

The SSL certificate must contain the external FQDN and internal FQDN if they are different. The internally generated certificate adds both the external and internal FQDN to the generated certificate.

This property is mandatory. console-


The fully qualified external hostname of the Pulse Console. This applies usually when there is a DNAT rule set from a public IP to internal IP.

If there is no external hostname, then you must set this to internal FQDN of the Pulse Console.

The SSL certificate of the Pulse Console must have both the external FQDN and internal FQDN if they are different.

This property is mandatory. db-

password Database password with a minimum length of eight characters

If the password is less than eight characters, the Pulse API installation will fail after the VM is created using the OVA.

This property is mandatory.


35 VMware, Inc

sysadmin-

password Password for the default sysadmin

user with a minimum length of eight characters

A password with a minimum length of eight characters for the default sysadmin user. If you log in as the initial user using Pulse Console, you will not have to modify this password.

If you do not supply a password or if the password is less than eight characters, the default password changeit applies for the

sysadmin user. You will be prompted to change this password when you first login.

It is recommended that you provide this password using the OVF property. Passing the property also helps you verify if the Pulse API installation has succeeded by trying to access the API documentation, which asks for a credential to login.

ssl-pkcs12 General information is provided in the section called Application Specific Common OVF Properties.

Additionally, the SSL certificate supplied is shared by both the Pulse API and the PostgreSQL DB that runs within the Pulse API.

ssl-

cacerts

General information is provided in the section called Application Specific Common OVF Properties, on ssl-cacerts.

Import the SSL cacert of the Pulse Device Management Component, vRealize Operations Manager and the syslog server to the application trust store. You can leave this property empty if the Pulse API, Pulse Device Management Component, and vRealize Operations Manager are using the same SSL certificate such as a wild card certificate or an SSL certificate sourced from a common vendor (signed by a common vendor).

Syslog ca certs are needed only when logging is enabled via the OVF properties using TCP as the protocol. The TCP translates to TCP over TLS.

The Pulse API cacert must be base64 encoded before being passed as a part of the property


36 VMware, Inc

value as depicted in the ssl-cacerts in the section Application Specific Common OVF Properties.

All the passwords accepted via the OVF properties are cleared after they have been consumed during the very first boot of the VM by the system initialization script.

The Pulse API also supports syslog integration feature where you can log into an external syslog server over TCO-TLS and UDP. The remote syslog server must have a TLS based source configured. Syslog integration must be done during OVF deployment and there exists no automated ways to do a syslog configuration post deployment. Note that UDP is without any transport layer security.

Property Name Constraints on Values

Description

log-hostname Hostname of the syslog server

Must match with the certificate on the log server. Setting this value will enable logging. Leave it empty if there is no syslog integration plan.

log-port Syslog server’s port number

The port number on which the syslog server is configured for TLS.

log-protocol Protocol This is TCP and UDP. TCP is always over TLS and plain TCP is not supported

log-facility The facility name

Values from LOCAL 0 through LOCAL 9.

The OVF properties of a Virtual Appliance Management Infrastructure (VAMI) agent for the network configuration in the case of a static IP are as follows.

Property Name


Fully Qualified Property Name Description

gateway Gateway IPv4 address

vami.VMware_Pulse_IoT_API_Service.gateway The default gateway address for this VM. You can leave this property blank if DHCP is desired.

domain Domain name

vami.VMware_Pulse_IoT_API_Service.domain The domain


37 VMware, Inc

name of this VM. You can leave this property blank if DHCP is desired.

searchpath Comma-separated list of domain search paths

vami.VMware_Pulse_IoT_API_Service.searchpath The domain search path (comma or space separated domain names) for this VM. You can leave this property blank if DHCP is desired.

DNS Comma-separated list of DNS servers

vami.VMware_Pulse_IoT_API_Service.DNS The domain name server IP addresses for this VM (comma- separated). Leave this property blank if DHCP is desired.

ip0 IPv4 address of the VM

vami.VMware_Pulse_IoT_API_Service.ip0 The IP address for this interface. You can leave this property


38 VMware, Inc

blank if DHCP is desired.

netmask0 Netmask for the interface

vami.VMware_Pulse_IoT_API_Service.netmask0 The netmask or prefix for this interface. You can leave this property blank if DHCP is desired.

Deployment Options

The Pulse API OVF provides 2 deployment options

1. Small. 2. Medium.

The deployment options are based on the number of Managed Objects the installation must support. Refer to the Pulse IoT Center Sizing Guide for the numbers.

The vSphere client provides a drop-down menu to choose the deployment option. For the ovftool use the deploymentOption option.

Post Installation

Post installation, you must complete the following configurations:

1. Modify the /etc/hosts file to include a route to Pulse Device Management

Component / Pulse Ops / vIDM. You can run a test using an nslookup call from within the shell.

2. Obtain the cacerts, /opt/vmwpulse/certs/cacerts.pem from within the Pulse API VM. The cacerts of Pulse API are needed by the Pulse Console and MQTT Broker. The MQTT Server requires that the cacerts to make calls into the PostgreSQL DB on the Pulse API server for enrollment credentials validation.

3. To manually add the Pulse Device Management Component and vRealize Operations Manager Root CA certificates to the iceapi truststore where they cannot be passed using the ssl-cacerts property. The /opt/iot-


39 VMware, Inc

api/config/truststore.jks is the truststore and the file name. Retain the default file permissions and ownership. The following commands are to be run as projectice user

keytool -importcert -file <vropsca.cer> -keystore

/opt/iot-api/config/truststore.jks -

alias "vropsapi"

keytool -importcert -file <airwatchca.cer> -

keystore /opt/iot-api/config/truststore.jks -

alias "airwatchapi"

If you access the Pulse API documentation UI from https://<<API Server

IP>>:8443/api/docs/index.html, you will be prompted for a user name and password. Log in as a sysadmin using the password supplied as the OVF property to check if the Pulse API is up and running. Note: Do not try to log in into the Pulse API Server documentation UI if no sysadmin password was given during installation using the OVF property. Login only after the Pulse Console is setup and the default sysadmin password has been modified from the IoT Console. The IoT Console configuration is described in the next section.

All manual changes to the Pulse API Configuration file or certificates will need the service to be restarted. Run the following command as root:

service iceapi restart

Ports

The Pulse API has the necessary firewalls to allow incoming connections to the following ports:

o 443 for the Pulse API server o 5432 for the PostgreSQL Database. Database access is limited to within the

subnet only. o 22 for SSH

The Pulse API by default listens on 8443. Port 443 is an internal iptables redirection to 8443. When setting a DNAT rule from the external network to the internal network use the port 443 externally as well internally.

Logs and Configurations

You can find the logs and configurations at multiple file locations.

File Description


40 VMware, Inc

/var/log/firstboot Contains a running summary when the OVA runs the first time.

/opt/iot-api/logs Contains all the Pulse API logs. /opt/iot-

api/config/application.yml Contains the Pulse API application configuration in YAML format. The YAML file is a slightly complex format and hence make modifications carefully.

/opt/iot-api/config/logback.xml Contains the logging configuration for the Pulse API.

/opt/iot-api/config/keystore.p12 Contains the SSL certificate for the Pulse API.

/opt/iot-api/config/truststore.jks The trust store containing cacerts for the PulseAPI and of those components Pulse API connects to.

/opt/iot-api/config/signing.pkcs12 Contains the signing keys used internally by the Pulse API

It is recommended that you take a backup of the configuration folder /opt/iot-api/config. Any errors to the yaml config, xml config or certificates can cause the Pulse API

service to fail to startup

Database Backup and Restore

Take a backup of the Pulse API database in Postgres frequently, and run the following commands as root:

sudo -iu projectice

pg_dump -Ft -n iot projectice > /tmp/projectice.tar logout

To restore the database, run the following command as root to stop the Pulse API:

service iceapi stop

sudo -iu projectice

pg_restore --clean --if-exists -Ft -d projectice /tmp/projectice.tar

logout

service iceapi start

To restore the DB, you must stop the MQTT server. No metrics flow will take place during this phase.

Install Pulse API OVA using vSphere Web Client UI

Assume that a resource pool is created with the name Admin which contains a vApp with the name Pulse001. If you add all the entities to a single vApp, you may have to start the vApp as a whole. This will cause problems such as not being able to copy the cacerts of the internally


41 VMware, Inc

generated certificates as they are generated after the deployment is started. Since the document assumes that the reader is familiar the procedure below only covers sections that are relevant for Pulse API

Procedure

1. Select Small or Medium as the deployment configuration for vertical scale. Appropriate vCPUs and memory are allocated. In this example, Small has been selected. Click Next.


42 VMware, Inc

2. The screen displays the application and network OVF properties. Fill in the application properties. Click Next. Note: For this specific example, an ssl certificate is copied after base64 encoding. You can run the cat iotssl.pfx | base64 -w 0 BASH and capture the output and paste it into the SSL PKCS12 file. Use the command

and replace iotssl.pfx with the path to the PKCS12 file. You can save the output to a file for repeated use across OVAs.


43 VMware, Inc

3. If a static IP is used, fill in the network properties. Leave the networking fields empty if a static pool or DHCP is used. Click Next.

4. Review the final details and click to Finish to deploy the Pulse API.

Install Pulse API OVA using CLI with the ovftool


44 VMware, Inc

Here is a sample ovftool command to start the Pulse API . Note that theSSL certs, CA certs, and SSH keys are passed from the command. The command below is just an example and is to be used as reference only.

ovftool --acceptAllEulas --noSSLVerify --machineOutput --

name=iceapi001 --datastore=vsanDatastore "--net:Network

1=FireIce" --ipAllocationPolicy=fixedPolicy --ipProtocol=IPv4

--diskMode=thin --deploymentOption=small --prop:"log-

hostname=pulseiotsl.eng.vmware.com" --prop:"log-port=6514" --

prop:"log-protocol=TCP" --prop:"log-facility=LOCAL0" "--prop:vami.ip0.VMware_Pulse_IoT_API_Service=10.32.54.111" "--

prop:vami.DNS.VMware_Pulse_IoT_API_Service=10.33.4.1,10.33.4.2"

"--prop:vami.gateway.VMware_Pulse_IoT_API_Service=10.32.54.124"

"--

prop:vami.netmask0.VMware_Pulse_IoT_API_Service=255.255.255.192"

"--

prop:vami.searchpath.VMware_Pulse_IoT_API_Service=vmware.com,eng

.vmware.com,ddns.vmware.com" "--

prop:vami.domain.VMware_Pulse_IoT_API_Service=eng.vmware.com" "-

-prop:api-externalname=iceapi001.vmwpulse.com" "--prop:console-

externalname=iceconsole001.vmwpulse.com" "--prop:db-

password=XXyyyz1" "--prop:sysadmin-password=YYYzzzz1" "--

prop:varoot-password=ZZaa235" "--prop:ssh-public-key=$(cat

~/.ssh/id_rsa.pub)" "--prop:ssl-pkcs12=$(cat ~/iotssl.pfx |

base64 -w 0)" "--prop:ssl-pkcs12-passwd=yyZZZabc1" "--prop:ssl-

cacerts=$(cat ./aw.cer ./vrops.cer | base64 -w 0)" iceapi.ova

"vi://administrator%40vsphere.local@vc-iot-

cks.eng.vmware.com/IoT_Fire_Ice/host/Pulse_IoT/Resources/Admin/P

ulse001"

VMware Pulse IoT Console

The Pulse IoT Console is distributed as a standalone OVA. You can provide most of the configuration inputs needed to configure a running ICE console instance as OVF parameters. The Pulse IoT Console binary is pre-installed at /opt/iceconsole. The

configuration for the Pulse IoT Console is available at /opt/iceconsole/server/config/seed-config.json.

Like the iceapi, the projectice user is the primary owner of /opt/iceconsole

and all its contents. Any changes to this ownership or permissions can cause the Pulse Console server to fail.


45 VMware, Inc

Prerequisites

1. Create a domain name for the Pulse Console. You must create an 'A' Record and PTR Record in the DNS server for a name to IP resolution and reverse for the Pulse Console.

2. Create an SSL certificate that matches the domain name for the Pulse Console. If an SSL certificate is not provided, the VM created from the OVA will attempt to generate one using the domain name for the Pulse Console.

3. Verify the signature of the CA certs in the Pulse API. The certificates must not be signed by a CA different from that of the SSL certificate imported into the Pulse Console.

4. Verify that there is a CA cert of the Pulse API that needs to be added to the CA list in Pulse Console.

System Services

The Pulse Console run as a sysvinit service as iceconsole and depends on the hazelcast service. There are other services required for the VM to run all the functions including the VMware agents. To get a list of the default upstart services that have started, run the following command:


To get a list of all sysvinit services, run the following command:

initctl list

You must run both the commands as a root user.

OVF Properties


Description

api-hostname Fully qualified domain name

The FQDN of the API server that the Pulse Console can use to reach out to the Pulse API. This should be the internal-hostname of the Pulse API as the Pulse Console and API are on the same network.


46 VMware, Inc

The hostname must resolve to the IP of the Pulse API server within the Pulse Console VM.

The hostname should match the Common Name(CN) or Subject Alternative Name (SAN) in the SSL certificate hosted by the Pulse Console. If not, the SSL hostname validation by the Pulse Console for all HTTPS requests into the Pulse API will fail.

This property is mandatory. console-


The fully qualified hostname of the Pulse Console that the browsers use to access the Pulse Console. You can add this property to the internally generated SSL certificate when no ssl certificate is provided via ssl-pkcs12.

This property is mandatory. ssl-pkcs12 General information is provided in the section called

Application Specific Common OVF Properties. Additionally, it is the SSL certificate for the ICE console. The common name in the certificate must match the console-externalname.

ssl-cacerts General information is provided in the section called Application Specific Common OVF Properties, on ssl-cacerts

Additionally, it is the SSL cacert of the Pulse API. If the Pulse API and Pulse Console are using the same SSL certificate such as a wild card certificate or an SSL certificate sourced from a common vendor (signed by a common vendor), then you can leave this property empty.

You must base64 encode the Pulse API cacert before you pass it as a part of the property value.

The OVF properties of the VAMI agent for network configuration in the case of static IP are as follows.

Property Name


Fully Qualified Property Name Description


vami.VMware_Pulse_IoT_Con

sole_Service.gateway The default gateway address for this VM. You can leave this property blank if DHCP is desired.

domain Domain name vami.VMware_Pulse_IoT_Con

sole_Service.domain The domain name of this VM. You can leave this


47 VMware, Inc

property blank if DHCP is desired.

searchpa

th Comma- separated list of domain search paths


sole_Service.searchpath The domain search path (comma or space separated domain names) for this VM. You can leave this property blank if DHCP is desired.

DNS Comma- separated list of DNS servers


sole_Service.DNS The domain name server IP Addresses for this VM (comma separated). You can leave this property blank if DHCP is desired.



sole_Service.ip0 The IP address for this interface. You can leave this property blank if DHCP is desired.

netmask0 Netmask for the interface


sole_Service.netmask0 The netmask or prefix for this interface. You can leave this property blank if DHCP is desired.

Deployment Options

The OVF provides 2 deployment options

1. Small. 2. Medium -


The vSphere client provides a drop-down option to select the deployment option. For the ovftool use the deploymentOption option.

Post Installation

Post installation, you must complete the following configurations:


48 VMware, Inc

1. Modify the /etc/hosts file to include a route to the Pulse API hostname if it does not get resolved to the internal IP address of Pulse API.

2. If the cacert of the Pulse API cannot not be passed using the cacerts, you can add them manually using the following command as projectice:

cat pulseapicacert.pem | tee -

a /opt/iceconsole/server/config/certificates/cacerts.p

em

You must restart the service for any further manual changes to the Pulse Console Configuration file or Run the following command as root.

service iceconsole restart

Ports

The Pulse Console has the necessary firewalls to allow incoming connections to the following ports:

o 443 for the Pulse Console server o 22 for SSH

The default Pulse Console port is 8443 Port 443 is an internal iptables redirection to 8443. When setting a DNAT rule from the external network to the internal network use the port 443 externally as well internally.


You can find the logs and configurations in the following locations:

File Description /var/log/firstboot Contains a

running summary when the OVA is run the first time.

/opt/iceconsole/logs Contains all the Pulse Console logs.

/opt/iceconsole/server/config/seed-config.json Contains the Pulse Console application


49 VMware, Inc

configuration in the JSON format. The log configuration is part of the seed-

config.json /opt/iceconsole/server/config/certificates/keystore.p12 The SSL

certificate for the Pulse Console.

/opt/iceconsole/server/config/certificates/cacerts.pem The trust store that contains cacerts including that of the Pulse API in PEM format.

Note: You must take a backup of the configuration folder /opt/iceconsole/server/config. Any errors to the json configuration file or the certificates can cause the Pulse Console to fail to startup.

Install - vSphere Web Client

Assume that a resource pool is created with the name Admin which in turn contains a vApp with the name Pulse001. You must start the vApp, if you add all the entities to a single vApp. You can encounter problems such as not being able to copy the cacerts of the internally generated certificates as they get generated after the deployment has started. Since the document assumes that the reader is familiar the procedure below only covers sections that are relevant for Pulse API.


50 VMware, Inc

Procedure

1. Select Small or Medium as the deployment configuration for vertical scale. In this example, Small has been selected. Click Next.

2. Review the application and network OVF properties and enter the application properties.


51 VMware, Inc

3. If a static IP is used, enter the network properties Leave the networking fields empty if a static pool or DHCP is used. Click Next.

4. Review the details and click Finish to deploy Pulse Console.


52 VMware, Inc

Install - CLI with ovftool

Here is a sample ovftool command to start the Pulse API from the command. Notice how SSL certs, CA certs, and SSH keys are passed from the command.

ovftool --acceptAllEulas --noSSLVerify --machineOutput --

name=iceconsole001 --datastore=vsanDatastore "--net:Network

1=FireIce" --ipAllocationPolicy=fixedPolicy --

ipProtocol=IPv4 --diskMode=thin --deploymentOption=small -

-

prop:"vami.ip0.VMware_Pulse_IoT_Console_Service=10.32.54.11

2" --

prop:"vami.DNS.VMware_Pulse_IoT_Console_Service=10.33.4.1,1

0.33.4.2" --

prop:"vami.gateway.VMware_Pulse_IoT_Console_Service=10.32.5

4.124" --

prop:"vami.netmask0.VMware_Pulse_IoT_Console_Service=255.25

5.255.192" --

prop:"vami.searchpath.VMware_Pulse_IoT_Console_Service=vmwa

re.com,eng.vmware.com,ddns.vmware.com" --

prop:"vami.domain.VMware_Pulse_IoT_Console_Service=eng.vmwa

re.com" "--prop:api-hostname=iceapi001.vmwpulse.com" "--

prop:console-externalname=iceconsole001.vmwpulse.com" "--

prop:varoot-password=ZZaa235" "--prop:ssh-public-key=$(cat

~/.ssh/id_rsa.pub)" "--prop:ssl-pkcs12=$(cat ~/iotssl.pfx |

base64 -w 0)" "--prop:ssl-pkcs12-passwd=yyZZZabc1" "--

prop:ssl-cacerts=$(cat ./pulseapica.cer | base64 -w 0)"

iceconsole.ova "vi://administrator%40vsphere.local@vc-iot-

cks.eng.vmware.com/IoT_Fire_Ice/host/Pulse_IoT/Resources/Ad

min/Pulse001"

MQTT Broker

The mqttbroker.ova installs the EMQTT broker. All install parameters required to setup up the EMQTT broker is done via OVF properties. Please follow the constraints described for each OVF property value in this section of the document. Any errors in the property can result in an unusable system. The only option then is to delete and reinstall.


53 VMware, Inc

The emqtt broker, emqttd daemon, runs as an emqtt user. You must make changes as an emqtt user for any change to the emqtt configuration using the command line or if you edit the emqttd configuration. All configuration that the emqtt uses internally are owned

by the emqtt user and any change in the ownership or file permissions can cause the emqttd daemon to stop running.

System Services

The MQTT Broker run as a sysvinit service, emqttd. There are other services required for the full functionality of the VM including the VMware agents. To get a list of the default upstart services that have started, run the following command:


To get a list of all the sysvinit services, run the following command:

initctl list

You must run both the above commands as a root user.

Prerequisites

• Create a domain name for the MQTT Broker. You must create an 'A' Record and PTR in the DNS server for a name to IP resolution and reverse.

• Create an SSL certificate that matches the domain name for the MQTT Broker. If an SSL certificate is not provided, the VM created from the OVA will attempt to generate one using the domain name for the MQTT Broker.

• Verify that there is a CA cert of the Pulse API that needs to be added to the CA list in MQTT broker.

OVF Properties


Description


54 VMware, Inc

emqtt-

externalname Fully qualified hostname of the MQTT Broker

The fully qualified domain name of the MQTT Broker. This is the hostname that the device and vRealize Operations Manager uses to connect to the MQTT Broker.

This name is used as the Common Name in the internal generated SSL certificates.

This property is mandatory. api-hostname Fully qualified

domain name The FQDN of the API server that the MQTT server can reach out on. The MQTT broker uses the PostgreSQL DB on the Pulse API to validate credential from gateways.

The hostname must match the IP of the Pulse API server.

The hostname must match the Common Name (CN) in the SSL certificate hosted by Pulse API.

This property is mandatory. db-password The database

password for the PostgreSQL DB

The database password for the PostgreSQL DB in the Pulse API.

This property is mandatory. emqtt-user emqtt user

name This is an access control list within the emqtt

daemon and is not a Linux user. The user is created post deployment and is used by vRealize Operations Manager (Helix Adapter) to connect to the MQTT Broker.

This property is mandatory. emqtt-passwd Password for

the emqtt-user

Password corresponding to the emqtt user.

This property is mandatory. emqtt-cookie Unique name

that does not conflict with other instances

The emqtt cookie has to be shared across nodes in a clustered emqtt setup.

It is recommended that you use this property. If you leave this property empty, it results in a random string. This property must be configured when you use a clustered emqtt setup.

../../../../../../display/IOT/VMware+Pulse+IoT+Center+Server+Installation+Guide+GA+-+Word


55 VMware, Inc

ssl-pkcs12 General information is provided in the section called Application Specific Common OVF Properties.

Additionally, this property is the SSL cert for the MQTT Broker that matches the emqtt-externalname with the cacert chain.

ssl-cacerts General information is provided in the section called Application Specific Common OVF Properties, on ssl-cacerts.

Additionally, this property is the SSL cacert of the Pulse API Server. If the Pulse API and EMQTT broker use the same SSL certificate such as a wild card certificate or an SSL certificate sourced from a common vendor (signed by a common vendor), then you can keep the property blank.

The pulse api cacert must be base64 encoded before being passed as a part of the property value.

The OVF properties of the Virtual Appliance Management Infrastructure (VAMI) agent for network configuration in the case of static IP are as follows:

Property Name


Fully Qualified Property Name

Description


vami.VMware_Pulse_E

MQTT_Broker_Service

.gateway

The default gateway address for this VM. You can leave this property blank if DHCP is desired.

domain domain name

vami.VMware_Pulse_E

MQTT_Broker_Service

.domain

The domain name of this VM. You can leave this property blank if DHCP is desired.

searchp

ath Comma- separated list of domain

vami.VMware_Pulse_E

MQTT_Broker_Service

.searchpath

The domain search path (comma or space separated domain names) for this VM. You can leave this property blank if DHCP is desired.


56 VMware, Inc

search paths

DNS Comma- separated list of DNS servers

vami.VMware_Pulse_E

MQTT_Broker_Service

.DNS

The domain name server IP addresses for this VM (comma separated). You can leave this property blank if DHCP is desired.


vami.VMware_Pulse_E

MQTT_Broker_Service

.ip0

The IP address for this interface. You can leave this property blank if DHCP is desired.

netmask

0 Netmask for the interface

vami.VMware_Pulse_E

MQTT_Broker_Service

.netmask0

The netmask or prefix for this interface. You can leave this property blank if DHCP is desired.

Deployment Options

The OVF provides two deployment options:

1. Small. 2. Medium.


The vSphere client provides a dropdown option to select the deployment option. For the ovftool use the –deploymentOption option.

Post Installation Configuration

MQTT Plugins

The MQTT Broker configures itself, if all the mandatory OVF properties are input correctly as specified in the OVF properties section above. The configuration is applied when the VM is started for the very first time.

Verify the installation by running the following command.

sudo -i -u emqtt emqttd_ctl plugins list


57 VMware, Inc

The output of the above command should contain the following two lines

Plugin(emq_auth_pgsql, version=2.2,

description=Authentication/ACL with PostgreSQL, active=true)

Plugin(emq_auth_username, version=2.2,

description=Authentication with Username/Password,

active=true)

If the active = true is false in the output for emq_auth_psql, start the plugin by running the command from the shell:

sudo -i -u emqtt emqttd_ctl plugins load emq_auth_pgsql

Verify that the output of the command states: Plugin emq_auth_pgsql loaded successfully.

If the active = true is empty in the output for emq_auth_psql, start the plugin by running the command from the shell:

sudo -i -u emqtt emqttd_ctl plugins load emq_auth_username

Verify that the output of the command states: Plugin emq_auth_username loaded successfully

Firewall Configuration

MQTT Broker will need to serve a high volume of connections request from IoT Gateways. To ensure the stability of the MQTT broker, a rate limiting is introduced into iptables via ufw to regulate connection requests coming into the MQTT Broker. All LIOTA packages that’s being developed should have appropriate retry logic to adapt to any connection failures. MQTT broker firewall configuration needs to be updated with IP address of vRealize Operations Manager so that it is not subject to any rate limiting restrictions. This can be done by editing the /etc/ufw/before.rules files as sudo or super user. Look for the following lines

## Uncomment the below line and substitute the placeholder <<ipaddress>> with address of VROPs for preferential connection. ## No other modifications allowed. ## -A ufw-before-input -p tcp -s <<ipaddress>> --dport 8883 -m conntrack --ctstate NEW -j ACCEPT

Delete the highlighted ## in front of the line and replace the place holder <<ipaddress>> with the IP address of vRealize Operations Manager and save the file and run the following command for the firewall rules to reload.

ufw reload


58 VMware, Inc

Other post installation configurations are limited to:

1. Modify the /etc/hosts file to include a route to the Pulse API hostname if it does not get resolved to the internal IP address of Pulse API.

2. For Further manual changes to the MQTT Broker configuration file or certificates, you must restart the service by running the service emqttd restart command as root.

The MQTT server validates all connecting gateways by validating the onboarding credentials that LIOTA sends with PostgresDB in the PulseAPI.

Ports

The internal firewall is configured to accept connections for SSH and the MQTT connections on port 8883. The other ports remain blocked. MQTT Broker has necessary firewalls to allow incoming connections to the following ports:

o 8883 for the MQTT connections over TLS o 22 for SSH

Ensure that a route exists to the Pulse API defined by the api-hostname property from the MQTT Broker. Import the cacert of the Pulse API using the ssl-cacerts property for the TLS connection to succeed.


You can view the logs and configurations at the following locations:

File Description /var/log/firstboot Contains the running summary when the OVA

runs the first time. /var/log/emqttd Contains all the MQTT Broker and Erlang

runtime logs. /etc/emqttd/emq.conf Contains all the configurations including logging

for the MQTT broker

Install - vSphere Web Client

Assume that a resource pool is created with the name Admin that contains a vApp with the name Pulse001. If you add all the entities to a single vApp, you must start the vApp as a whole.


59 VMware, Inc

This results in problems such as not being able to copy the cacerts of the internally generated certificates as they are generated after the deployment starts.

1. Select Small or Medium as the deployment configuration option for vertical scale. In this example, Small is selected. Click Next.


60 VMware, Inc

2. Enter the application properties.

In this example, an ssl certificate is copied after base64 encoding. You can do this by running the command in the shell

cat iotssl.pfx | base64 -w 0

and capturing the output and pasting it into an SSL PKCS12 file. Use the command alone and replace iotssl.pfx with the path to the PKCS12 file. Save the output to a

file for repeated use if the certificate can be used across OVAs.


61 VMware, Inc

3. Enter the network properties if static IP is used. Leave the networking fields empty if a static pool or DHCP is used. Click Next.


62 VMware, Inc

4. Review the details and click Finish to complete the deployment of the mqttbroker.

Install - CLI using ovftool

Here is a sample ovftool command to start the Pulse API from the command. Notice how the SSL certs, CA certs, and SSH keys are passed from the command.

ovftool --acceptAllEulas --noSSLVerify --machineOutput --name=mqttbroker001 -

-datastore=vsanDatastore "--net:Network 1=FireIce" --

ipAllocationPolicy=fixedPolicy --ipProtocol=IPv4 --diskMode=thin --

deploymentOption=small --

prop:"vami.ip0.VMware_Pulse_EMQTT_Broker_Service=10.32.54.112" --

prop:"vami.DNS.VMware_Pulse_EMQTT_Broker_Service=10.33.4.1,10.33.4.2" --

prop:"vami.gateway.VMware_Pulse_EMQTT_Broker_Service=10.32.54.124" --

prop:"vami.netmask0.VMware_Pulse_EMQTT_Broker_Service=255.255.255.192" --

prop:"vami.searchpath.VMware_Pulse_EMQTT_Broker_Service=vmware.com,eng.vmware

.com,ddns.vmware.com" --

prop:"vami.domain.VMware_Pulse_EMQTT_Broker_Service=eng.vmware.com" "--

prop:api-externalname=iceapi001.vmwpulse.com" "--prop:db-password=XXyyyz1" "-

-prop:emqtt-user=vmpulseiot" "--prop:emqtt-passwd=vmpulseiot" "--prop:emqtt-

externalname=iceapi001.vmwpulse.com" "--prop:varoot-password=ZZaa235" "--

prop:ssh-public-key=$(cat ~/.ssh/id_rsa.pub)" "--prop:ssl-pkcs12=$(cat


63 VMware, Inc

~/iotssl.pfx | base64 -w 0)" "--prop:ssl-pkcs12-passwd=yyZZZabc1"

mqttbroker.ova "vi://administrator%40vsphere.local@vc-iot-

cks.eng.vmware.com/IoT_Fire_Ice/host/Pulse_IoT/Resources/Admin/Pulse001"

Post Installation Configuration for Helix Adapter in vRealize Operations Manager

You must configure vRealize Operations Manager after MQTT is installed, to help the Helix Adapter reach out to the MQTT broker.

1. Enter the MQTT Broker details by editing the config.properties file in vRealize Operations Manager at /usr/lib/vmware-vcops/user/plugins/inbound/HelixAdapter/conf/config.propert

ies.

2. Place the cacert of the EMQTT Broker in the vRealize Operations Manager node at /etc/certificate/cacert.pem. Use the same user name and password as the one you created while configuring the EMQTT.

3. The MQTT Broker installed as a part of the OVA makes its CA certificate available at /etc/emqttd/certs/cacerts.pem inside the MQTT VM. Append the contents of this file to the vRealize Operations Manager CA certificate list as defined by the RootCACertificate entry in the config.properties as shown below.

MqttBroker_IP=ssl://IP-Address # MqttBroker_Port=8883 # MqttBroker_Username=Username # MqttBroker_Password=Password # RootCACertificate_Path=/etc/certificate/cacert.pem

4. Restart the vRealize Operations Manager collector by running the service vmware-vcops restart collector command:


64 VMware, Inc

Upgrade

For existing BETA customers there exists no upgrade path to the GA version. This is because of the significant changes to the secure enrollment process introduced in GA. The Pulse Console and Pulse API are now provided as ubuntu packages that can be installed using the dpkg or the apt-get command line tools.

For example, the packages are provided as iceconsole_1.1.0_all.deb, iceapi_1.1.0_all.deb for the new 1.1.0 version. Copy the packages to the Pulse

Console VM and the Pulse API VM. Use the following commands to install the packages in their respective VMs.

dpkg -i iceconsole_1.1.0_all.deb

dpkg -i iceapi_1.1.0_all.deb

This command uninstalls the existing version, such as 1.0.0, and installs the 1.1.0 version. During the uninstall, the configuration files are backed-up and the new installation version restores and applies any new changes on the same. Dpkg commands are to be executed as a super user.

Pulse Components Integration Configuration

After all the servers are deployed and wired together, complete the configurations on the Pulse API using the Pulse Console user interface. This includes credentials that the API must use to sync with the Pulse Device Management Component and vRealize Operations Manager in the backend. Pulse Console does not have an account recovery option. It is recommended that you keep your login credentials securely.

Step 1: Login

Login to the Pulse Console as a sysadmin user. The password for sysadmin is the one

passed as an OVF property, sysadmin-password, during installation. If the password constraints specified were violated, the sysadmin password defaults to vmware.

Step 2: Password Reset

This step is displayed if the sysadmin password constraints specified are violated. The sysadmin password will default to vmware. A typical password must meet the following requirements:

• The password must be at least eight characters long. • The password must have at least one uppercase letter • The password must have at least one special character ($#!@*&^) • The password must have at least one number/digit (0-9)

Step 3: EULA

Accept the licensing to proceed. If you do not accept the EULA, the user will be logged out.

Step 4: System Configuration

Set up the interaction points with the Management Console, the Operation Analytics application, VMware Identity Management application, SMTP server, and the Google MAPS API.

• System configuration is a multi-step process. • The administrator must Save and Continue at each step. • Skipping the page will not save any changes made on the screen. • As an administrator, you can save one or two configuration screens and leave the rest to

come back again and complete.


66 VMware, Inc

Step 4.a: Lifecycle Management: Management Console Configurations

The following inputs are required for the configuration of the interaction between the Pulse system and the Management Console. It can be updated later, at any stage, as applicable. All the fields are mandatory.

Option Description

Console URL The public URL of the Management Console Server.

API URL The public URL of the Management API Server.

Group ID The Organization Group ID in the management console. This is the highest level of Organization Group to which the Pulse system has access to. This is the Group ID field in the Pulse IoT Management Console.

Group Index This is the Organization Group index that VMware Pulse Device Management Suite maintains internally. You can obtain the index from the URL when you open the Organization Group page.

API Key The API enablement key from the Management Console. Navigate to Groups and Settings > All Settings > Advanced > API > REST API > Enable API Access button.

User + Password

An admin user in the Pulse Device Management Component console who is an administrator at the Organization Group level identified by Group Id.


67 VMware, Inc

The admin user must be created at the given customer Organization Group. The user must have only one role for the customer Organization Group (such as System Admin or Pulse Device Management Component Admin).

Step 4.b: Operational Analytics Configuration

Enter the configuration details for the interaction between the Pulse system and the Operational Analytics system deployment. All the fields are compulsory on this screen.

Option Description

Suite API URL The API server URL for the Operational Analytics server.

Username + Password

The basic user created on the Operational Analytics Server. This user is used for API calls and sync services in the Pulse system

Step 4.c: VMware Identity Management Configuration (optional)

VMware Identity Manager (vIDM) is used to manage users and provide Single Sign-On into other systems such as the Management Console. Enter the details:


68 VMware, Inc

Option Description

Server URL The hosting public URL of VMware Identity Manager.

Service Client ID An admin account for managing the tenant. You must create a client with Service Client privileges from the vIDM remote access screen.

Service Client Secret The secret/password for the Service Account.


69 VMware, Inc

User Access Client ID The Pulse API server also acts as an OAuth consumer. You must create a remote client with User Access Token privileges.

User Access Client Secret The user access account secret/password

SAML IDP Metadata SAML identity provider metadata that you can download from the VMware Identity Provider Console.

SAML Server Provider Signing Certificate

A certificate used for communication between Identity Provider (vIDM) and Pulse. You must generate the certificate manually and then upload it using the upload button.

Step 4.d: SMTP Server Settings

Enter SMTP settings to receive notifications when an alert occurs on the IoT Edge System or on connected devices. The SMTP server is used by the Pulse System to send out email notifications.


70 VMware, Inc

Step 4.e: Other Configurations

Select the check box to enable Google Maps. VMware Pulse uses Google Maps to display the location of the resources, if available.


71 VMware, Inc

Provide the API key for Google Maps to work. You can obtain the API key from the Google Developer Console or from Google Enterprise Licensing. You can also obtain the API key by following the steps at Google Docs: Get API Key. Customer’s must purchase the license key directly from Google. Besides the LIOTA packages must be written appropriately to get the retrieve and transmit the coordinates to be effective for the Console to show the location of a IoT edge and connected devices.

https://developers.google.com/maps/documentation/javascript/get-api-key


72 VMware, Inc

You must log off and log back in after the configuration is complete. The Pulse system reloads all the configurations and starts the background processes with the latest configuration. At this point, no other user is configured in the system. You must create some users who can log in and use the system.


73 VMware, Inc

Date post:	15-Jun-2020
Category:	Documents
Upload:	others
View:	12 times
Download:	0 times

VMware Pulse IoT Center Server Installation Guide GA - Word€¦ · VMware Pulse IoT Center Server...

Documents