VMware Pulse IoT Center Server Install Guide

Transcription

1

2 Copyright All rights reserved. Copyright and trademark information Hillview Ave Palo Alto, CA

3 Introduction... 6 Before you Start... 6 Prerequisites... 7 OVA General Information and Changes Since the BETA... 8 VMware Pulse IoT Center Components Device and Software Lifecycle Management Hardening Windows Installation Host Mapping in VMware Pulse Device Management Suite Importing Pulse IoT API CA into VMware Pulse Device Management Component Enforce Strong Passwords Enabling IoT Support Secure Edge System/Gateway Enrollment Operation Analytics Module Installation Configuration Helix Adapter Installation VMware Pulse IoT Center Frontend Modules Frontend Installation - Pulse OVAs OVF Parameter Configuration Application Specific Common OVF Properties Virtual Appliance Management Infrastructure (VAMI) properties Passwords and passphrases VMware Pulse IoT API Server Prerequisites System Services OVF Properties Deployment Options Post Installation Ports Logs and Configurations Database Backup and Restore Install Pulse API OVA using vsphere Web Client UI

4 Install Pulse API OVA using CLI with the ovftool VMware Pulse IoT Console Prerequisites System Services OVF Properties Deployment Options Post Installation Ports Logs and Configurations Install - vsphere Web Client Install - CLI with ovftool MQTT Broker System Services Prerequisites OVF Properties Deployment Options Post Installation Configuration MQTT Plugins Firewall Configuration Ports Logs and Configurations Install - vsphere Web Client Install - CLI using ovftool Post Installation Configuration for Helix Adapter in vrealize Operations Manager Upgrade Pulse Components Integration Configuration Step 1: Login Step 2: Password Reset Step 3: EULA Step 4: System Configuration Step 4.a: Lifecycle Management: Management Console Configurations Step 4.b: Operational Analytics Configuration Step 4.c: VMware Identity Management Configuration (optional)

5 Step 4.d: SMTP Server Settings

6 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 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 (x86_64). For installation instructions about VMware Pulse Device Management Suite and vrealize Operations Manager 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 6

7 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 ( 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. 7

8 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. 8

9 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. 9

10 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 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: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\aes 128/128] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\aes 256/256] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\des 56/56] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\null] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc2 128/128] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc2 40/128] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc2 56/128] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc4 128/128] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc4 40/128] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc4 56/128] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\rc4 64/128] "Enabled"=dword:

12 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher s\triple DES 168] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Cipher Suites] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes ] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes \MD5] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes \SHA] "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes \SHA256] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes \SHA384] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes \SHA512] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\KeyExc hangealgorithms] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\KeyExc hangealgorithms\diffie-hellman] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\KeyExc hangealgorithms\ecdh] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\KeyExc hangealgorithms\pkcs] "Enabled"=dword:ffffffff [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\multi-protocol Unified Hello] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\multi-protocol Unified Hello\Client] "Enabled"=dword: "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\multi-protocol Unified Hello\Server] "Enabled"=dword: "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\pct 1.0] 12

13 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\pct 1.0\Client] "Enabled"=dword: "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\pct 1.0\Server] "Enabled"=dword: "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\ssl 2.0] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\ssl 2.0\Client] "DisabledByDefault"=dword: "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\ssl 2.0\Server] "DisabledByDefault"=dword: "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\ssl 3.0] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\ssl 3.0\Client] "DisabledByDefault"=dword: "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\ssl 3.0\Server] "DisabledByDefault"=dword: "Enabled"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.0] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.0\Client] "Enabled"=dword: "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.0\Server] "Enabled"=dword: "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.1] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.1\Client] "Enabled"=dword:ffffffff "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.1\Server] "Enabled"=dword:ffffffff "DisabledByDefault"=dword:

14 [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.2] [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.2\Client] "Enabled"=dword:ffffffff "DisabledByDefault"=dword: [HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protoc ols\tls 1.2\Server] "Enabled"=dword:ffffffff "DisabledByDefault"=dword: 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 14

15 ,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. 15

16 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. echo off title SSL Cert Check :: See the title at the top set cert=%1 certutil -addstore "AuthRoot" %cert% Enforce Strong Passwords 16

17 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. 17

18 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. 18

19 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. 19

20 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 and is part of the VMware Pulse distribution. The installer is an OVA with SUSE Linux as the base operating system. 20

21 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 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. 21

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

23 3. Select Finish. 4. Log in to the vrealize Operations Manager Console with credentials used earlier Accept the EULA and click Next. 23

24 5. Enter the product license key and validate. Click Next. 6. Optionally, join the VMware Customer Experience program and click Next. 24

25 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 pak or later. This distributed separately along with the OVAs. Complete the following steps to install the adapter. 25

26 Procedure 1. Navigate to 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. 26

27 5. Accept the agreement and click Next. 6. Wait for the installation to complete and click Finish. 27

28 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 Server. o o o pulseapi.ova - With VMware Pulse IoT API and PostgresSQL v9.6 pre-installed. pulseconsole.ova - With VMware Pulse IoT Console and all the dependencies. mqttbroker.ova - With the EMQTT broker v2.2 stable version from 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 28

29 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 varootpassword sshpublickey Constraints on Values An alphanumeric password of eight or more characters for the root account. An SSH public key that must be added to the authorized keys for the root user. Description 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. 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 29

30 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. sslpkcs12 Input an external SSL certificate in the PKCS12 format encoded in base64 without line wraps. No validity is performed on the key and hence you must make sure that a valid SSH key is provided for a seamless connection. 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 30

31 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 ssl- pkcs12- passwd sslcacerts Password for the ssl_pkcs12 file List of cacerts in CER format needed by the application to connect to external servers with another level of base64 encoding and copy the output as property value. The OVF properties do not accept binary values and hence the need to encode them as base64. 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. 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 31

32 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 vamitimezone Mandatory to leave vamitimezone this as Etc/UTC Description 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. 32

33 The install folder for Pulse API is at /opt/iot-api. All the contents under /opt/iotapi 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 33

34 apiexternalname 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. consoleexternalname Fully qualified domain name This property is mandatory. 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. dbpassword Database password with a minimum length of eight characters The SSL certificate of the Pulse Console must have both the external FQDN and internal FQDN if they are different. This property is mandatory. 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. 34

35 ssl-pkcs12 sysadminpassword sslcacerts 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. 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. 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 35

36 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 log-hostname Hostname of the syslog server log-port Syslog server s port number log-protocol Protocol log-facility The facility name Description 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. The port number on which the syslog server is configured for TLS. This is TCP and UDP. TCP is always over TLS and plain TCP is not supported 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 gateway domain Constraints on Values Gateway IPv4 address Domain name Fully Qualified Property Name vami.vmware_pulse_iot_api_service.gateway vami.vmware_pulse_iot_api_service.domain Description The default gateway address for this VM. You can leave this property blank if DHCP is desired. The domain 36

37 searchpath Commaseparated list of domain search paths DNS ip0 Commaseparated list of DNS servers IPv4 address of the VM name of this VM. You can leave this property blank if DHCP is desired. 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. vami.vmware_pulse_iot_api_service.dns The domain name server IP addresses for this VM (commaseparated). Leave this property blank if DHCP is desired. vami.vmware_pulse_iot_api_service.ip0 The IP address for this interface. You can leave this property 37

38 netmask0 Netmask for the interface vami.vmware_pulse_iot_api_service.netmask0 blank if DHCP is desired. 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- 38

39 Ports 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 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 The Pulse API has the necessary firewalls to allow incoming connections to the following ports: o o o 443 for the Pulse API server 5432 for the PostgreSQL Database. Database access is limited to within the subnet only. 22 for SSH The Pulse API by default listens on Port 443 is an internal iptables redirection to 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 39

40 /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/iotapi/config/application.yml configuration in YAML format. The Contains the Pulse API application 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/iotapi/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 40

41 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. 41

42 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. 42

43 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 43

44 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:"loghostname=pulseiotsl.eng.vmware.com" --prop:"log-port=6514" -- prop:"log-protocol=tcp" --prop:"log-facility=local0" "-- prop:vami.ip0.vmware_pulse_iot_api_service= " "-- prop:vami.dns.vmware_pulse_iot_api_service= , " "--prop:vami.gateway.vmware_pulse_iot_api_service= " "-- prop:vami.netmask0.vmware_pulse_iot_api_service= " "-- 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:consoleexternalname=iceconsole001.vmwpulse.com" "--prop:dbpassword=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:sslcacerts=$(cat./aw.cer./vrops.cer base64 -w 0)" iceapi.ova "vi://administrator%40vsphere.local@vc-iotcks.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. 44

45 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: 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 api-hostname Fully qualified domain name Description The FQDN of the API server that the Pulse Console can use to reach out to the Pulse API. This should be the internalhostname of the Pulse API as the Pulse Console and API are on the same network. 45

46 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. consoleexternalname ssl-pkcs12 ssl-cacerts Fully qualified domain name This property is mandatory. 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. 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 consoleexternalname. 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 gateway Constraints on Values Gateway IPv4 address Fully Qualified Property Name vami.vmware_pulse_iot_con sole_service.gateway domain Domain name vami.vmware_pulse_iot_con sole_service.domain Description The default gateway address for this VM. You can leave this property blank if DHCP is desired. The domain name of this VM. You can leave this 46

47 searchpa th DNS ip0 netmask0 Commaseparated list of domain search paths Commaseparated list of DNS servers IPv4 address of the VM Netmask for the interface vami.vmware_pulse_iot_con sole_service.searchpath vami.vmware_pulse_iot_con sole_service.dns vami.vmware_pulse_iot_con sole_service.ip0 vami.vmware_pulse_iot_con sole_service.netmask0 property blank if DHCP is desired. The domain search path (comma or space separated domain names) for this VM. You can leave this property blank if DHCP is desired. The domain name server IP Addresses for this VM (comma separated). You can leave this property blank if DHCP is desired. The IP address for this interface. You can leave this property blank if DHCP is desired. 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 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 option to select the deployment option. For the ovftool use the deploymentoption option. Post Installation Post installation, you must complete the following configurations: 47

48 Ports 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 The Pulse Console has the necessary firewalls to allow incoming connections to the following ports: o o 443 for the Pulse Console server 22 for SSH The default Pulse Console port is 8443 Port 443 is an internal iptables redirection to 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 in the following locations: File /var/log/firstboot /opt/iceconsole/logs /opt/iceconsole/server/config/seed-config.json Description Contains a running summary when the OVA is run the first time. Contains all the Pulse Console logs. Contains the Pulse Console application 48

49 configuration in the JSON format. The log configuration is part of the seedconfig.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. 49

50 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. 50

51 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. 51

52 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= " -- prop:"vami.dns.vmware_pulse_iot_console_service= , " -- prop:"vami.gateway.vmware_pulse_iot_console_service= " -- prop:"vami.netmask0.vmware_pulse_iot_console_service= " -- 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-iotcks.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. 52

53 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: service --status-all 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 Property Name Constraints on Values Description 53

54 emqttexternalname api-hostname db-password emqtt-user emqtt-passwd emqtt-cookie Fully qualified hostname of the MQTT Broker Fully qualified domain name The database password for the PostgreSQL DB emqtt user name Password for the emqttuser Unique name that does not conflict with other instances 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. 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. The database password for the PostgreSQL DB in the Pulse API. This property is mandatory. 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. Password corresponding to the emqtt user. This property is mandatory. 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. 54

55 ssl-pkcs12 ssl-cacerts 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 emqttexternalname with the cacert chain. 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 Constra ints on Values gateway Gatewa y IPv4 address domain searchp ath domain name Comma - separat ed list of domain Fully Qualified Property Name vami.vmware_pulse_e MQTT_Broker_Service.gateway vami.vmware_pulse_e MQTT_Broker_Service.domain vami.vmware_pulse_e MQTT_Broker_Service.searchpath Description The default gateway address for this VM. You can leave this property blank if DHCP is desired. The domain name of this VM. You can leave this property blank if DHCP is desired. The domain search path (comma or space separated domain names) for this VM. You can leave this property blank if DHCP is desired. 55

56 DNS ip0 netmask 0 search paths Comma - separat ed list of DNS servers IPv4 address of the VM Netmas k for the interfac e vami.vmware_pulse_e MQTT_Broker_Service.DNS vami.vmware_pulse_e MQTT_Broker_Service.ip0 vami.vmware_pulse_e MQTT_Broker_Service.netmask0 The domain name server IP addresses for this VM (comma separated). You can leave this property blank if DHCP is desired. The IP address for this interface. You can leave this property blank if DHCP is desired. 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 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 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 56

57 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 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 57

58 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 The other ports remain blocked. MQTT Broker has necessary firewalls to allow incoming connections to the following ports: o o 8883 for the MQTT connections over TLS 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. Logs and Configurations You can view the logs and configurations at the following locations: File /var/log/firstboot /var/log/emqttd /etc/emqttd/emq.conf Description Contains the running summary when the OVA runs the first time. Contains all the MQTT Broker and Erlang runtime logs. 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. 58

59 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. 59

60 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. 60

61 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. 61

62 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=mqttbroker datastore=vsandatastore "--net:network 1=FireIce" -- ipallocationpolicy=fixedpolicy --ipprotocol=ipv4 --diskmode=thin -- deploymentoption=small -- prop:"vami.ip0.vmware_pulse_emqtt_broker_service= " -- prop:"vami.dns.vmware_pulse_emqtt_broker_service= , " -- prop:"vami.gateway.vmware_pulse_emqtt_broker_service= " -- prop:"vami.netmask0.vmware_pulse_emqtt_broker_service= " -- 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:emqttexternalname=iceapi001.vmwpulse.com" "--prop:varoot-password=zzaa235" "-- prop:ssh-public-key=$(cat ~/.ssh/id_rsa.pub)" "--prop:ssl-pkcs12=$(cat 62

63 ~/iotssl.pfx base64 -w 0)" "--prop:ssl-pkcs12-passwd=yyzzzabc1" mqttbroker.ova 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/vmwarevcops/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 vmwarevcops restart collector command: 63

64 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 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 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. 64

65 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 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. 66

67 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 Suite API URL Username + Password Description The API server URL for the Operational Analytics server. 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: 67