VMware Pulse IoT Center v1.1 Server Install Guide

Transcription

1 VMware Pulse IoT Center v1.1 Server Install Guide

2 You can find the most up-to-date technical documentation on the VMware website at: If you have comments about this documentation, submit your feedback to 3401 Hillview Ave Palo Alto, CA Copyright All rights reserved. Copyright and trademark information. 2

3 Contents Introduction... 6 Before you Start... 6 Prerequisites... 7 OVA General Information and Changes Since the 1.0 GA... 8 VMware Pulse IoT Center Components Device and Software Lifecycle Management Hardening Windows Installation Host Mapping in the 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 VMware Pulse IoT API Server Prerequisites System Services OVF Properties Post Installation Ports Logs and Configurations Database Backup and Restore Install Pulse API OVA using vsphere Web Client UI Install Pulse API OVA using CLI with the ovftool VMware Pulse IoT Console Prerequisites System Services

4 OVF Properties Post Installation Ports Logs and Configurations Install - vsphere Web Client Install - CLI with the ovftool MQTT Broker System Services Prerequisites OVF Properties Ports Logs and Configurations Install - vsphere Web Client Install - CLI using ovftool Post Installation Configuration for Helix Adapter in vrealize Operations Manager VMware Identity Manager Deployment Model Before You Begin Integrating VMware Identity Manager AirWatch Cloud Connector Setup AirWatch Cloud Messaging Setup through the AirWatch Admin Console Verify and Update the Console Site URL Export VMware Identity Manager Metadata VMware Pulse Device Management Suite Integration VMware Pulse IoT Center/VMware Identity Manager Integration Upgrade Pulse Components Integration Configuration Step 1: Login Step 2: Password Reset Step 3: EULA Step 4: System Configuration Step 4.a: Lifecycle Management Configurations Step 4.b: Operational Analytics Configuration Step 4.c: VMware Identity Manager Configurations (Optional)

5 Step 4.d: SMTP Server Settings Step 4.e: Other Configurations

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 VMware Identity Manager (Optional) EMQTT broker, VMware Pulse IoT API, and the Console are distributed as separate OVAs. The OVAs are based on Photon OS. 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 Begin 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 about deployments in VMware vcloud Director based environments like OneCloud and vcloud Air in this document. Installing and configuring database servers. Microsoft SQL Server on Windows and PostgreSQL on Linux. Microsoft Active Directory Services. The OVAs are currently built for small and medium installations. Refer to the Pulse IoT Center Sizing Guide for the number of managed objects that are supported by small and medium installations. 6

7 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. VMware Identity Manager is not distributed along with VMware Pulse IoT Center. This product must be purchased separately from VMware. As a customer, it is expected that you have already deployed and configured VMware Identity Manager, as this Pulse IoT Center documentation including the Install guide only provides information about the integration steps with VMware Identity Manager. 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 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. As a user, you will need at least two Windows Server instances and licenses. One to install the SQL Server and the other to install 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 host name 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 get 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 1.0 GA For customers already using the 1.0 GA, there is no migration path. You must install the 1.1 version of the product and once setup, the IoT edge systems and connected devices must be reenrolled into the 1.1 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. Hence, only a local login is possible using sudo or su through 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. 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. It is recommended that you create an administrative user with sudo privileges and not use or share the root user. To make the installation experience smooth, additional configuration options have been added through new OVF properties. However, you might still have to make manual configurations. 8

9 The IoT API, IoT Console Server, and the EMQTT Broker have a lockout period of 15 minutes for terminal access when credentials fail to authenticate. To avoid a scenario where the user gets locked, you are advised not to share the root user credentials. Instead, create a separate user for everyone that requires administrative access to 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

11 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 along with data flow and the corresponding TCP port. The illustration is just an example and can vary from setup to setup. Internet DMZ Intranet Windows Server Windows Server 443 Airwatch Device Services Airwatch Cloud Messaging 443 Airwatch MSSQL Database Sensor/ Actuator Sensor/ Actuator 443 IoTC Agent Liota 2001 User Sync Windows Server Airwatch Admin Console Airwatch API Service Outbound only Windows Server Airwatch Cloud Connector Active Directory/ Other Directory Services IOT Gateway SUSE Linux (Optional Component) Sensor/ Actuator 8883 VMware Identity Management Server (vidm) Photon OS Pulse Console Service Photon OS SUSE Linux Helix Adapter EMQTT Broker 8883 vrealize Operations Manager 443 Photon OS Pulse API Service Postgres Database 443

12 Device and Software Lifecycle Management The device and software lifecycle management functionality are achieved via the VMware Pulse Device Management Suite. This is the VMware AirWatch Device Management retuned for IoT. All other mainstream devices supported by AirWatch are not supported in this version. Hardening Windows Installation Before you install 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] 12

13 "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: [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] 13

14 "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] [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] 14

15 [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: [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 15

16 SA_WITH_AES_256_CBC_SHA,TLS_RSA_WITH_AES_256_CBC_SHA,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 that the above cipher suite list exceeds 1023 characters. Note: After applying the SSL cipher, you must restart the system for the changes to take effect. Host Mapping in the 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 host name 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 Error! Reference source not found. and Error! Reference source not fo und. before configuring the Pulse API with the Pulse Device Management Component and vrealize Operations Manager settings using the Pulse Console. 16

17 To import the private CA into the Windows certificate store where the Pulse Device Management Suite is installed, complete the following steps. Procedure 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 the Pulse Device Management Component notifications reaching the Pulse API. You can prevent this 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, ensure that you add the following script to the window scheduler to run with admin rights. The script can be saved in a file with a.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% 17

18 Enforcing Strong Passwords Increase the password complexity of the Pulse Device Management Component Console with eight or more characters 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 18

19 IoT support must be enabled in the Pulse Device Management Component as shown in the screen shot. 1. Navigate to Groups and Settings under the Global OG -> All Settings -> Device and Users > Advanced > IoT Support. MQTT Integration and Pulse IOT API Integration is a mandatory configuration in the Pulse Device Management. Provide the Pulse API URL, MQTT URL, and port details. 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

20 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

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

22 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 systemctl start sshd 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. 22

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

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

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

26 7. Click Finish. vrealize Operations Manager generates an SSL certificate with a private CA during the deployment of the OVA. If this certificate does not have the right hostname in the Common Name section of the certificate or an SSL certificate needs to be installed from a Certificate Authority vendor, refer to the VMware KB article for more information. Helix Adapter Installation Use Helix Adapter pak or later. Helix Adapter is distributed separately along with the OVAs. Complete the following steps to install the adapter. Procedure 26

27 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. 5. Accept the agreement and click Next. 27

28 6. Wait for the installation to complete and click Finish. 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 section called Post Installation Configuration for Helix Adapter. VMware Pulse IoT Center Frontend Modules Frontend Installation - Pulse OVAs The VMware Pulse contains three appliances based on VMware Photon OS. 28

29 o o o pulseapi.ova - With VMware Pulse IoT API and PostgresSQL pre-installed. pulseconsole.ova - With VMware Pulse IoT Console and all the dependencies. mqttbroker.ova - With the EMQTT broker from When you deploy the OVAs, you 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 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 within 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 Constraints on Values An alphanumeric password of eight or more characters for the root account. 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. 29

30 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. sshpublickey An SSH public key that must be added to the authorized keys for the root user. 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 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. 30

31 sslpkcs12 ssl- pkcs12- passwd Input an external SSL certificate in the PKCS12 format encoded in base64 without line wraps. Password for the ssl_pkcs12 file 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 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 following command cat sslchain.pfx base64 - w 0 and copy the output as a 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. 31

32 sslcacerts 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 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. 32

33 Property Name vamitimezone Constraints on Values Mandatory to leave this as Etc/UTC Fully Qualified Property Name vamitimezone 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 three times or more, the system login has a lockout period of 15 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 during installation 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. 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 System Services 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. The Pulse API runs as a systemd service as iceapi and depends on the postgresql service. There are other services required for the full functionality of the VM including 33

34 the VMware agents. To get a list of the default upstart services that have started, run the following command: systemctl list-units --type=service --state=running or systemctl list-unit-files --type=service To get a list of all systemd services, run the following command: ls /etc/systemd/system/*.wants You must run both the commands as a root user. OVF Properties Property Name Constraints on Values apiexternalname Fully qualified domain name Description The fully qualified hostname for the Pulse API. If the 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. 34

35 consoleexternalname Fully qualified domain name 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 sysadminpassword ssl-pkcs12 Database password with a minimum length of eight characters Password for the default sysadmin user 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. 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. 35

36 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 value as depicted in the ssl-cacerts in the section Application Specific Common OVF Properties. Root password that is used for login through ssh into the VM. 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 TCP over TLS. The remote syslog server must have a TLS based source configured. Syslog integration must have been done during OVF deployment. There is no automated way to carry out a syslog configuration post deployment. sslcacerts varootpassword Property Name loghostname Constraints on Values Hostname of the syslog server Description Must match with the certificate on the log server. Setting this value will enable logging. The supported syslog protocol is TCP over TLS. 36

37 log-port Syslog server s port number The facility name Leave this field empty if there is no syslog integration plan. The port number on which the syslog server is configured for TLS. 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 searchpa th DNS ip0 Constraint s on Values Gateway IPv4 address Domain name logfacility Commaseparated list of domain search paths Commaseparated list of DNS servers IPv4 address of the VM netmask0 Netmask for the interface Fully Qualified Property Name vami.vmware_pulse_iot_api _Service.gateway vami.vmware_pulse_iot_api _Service.domain vami.vmware_pulse_iot_api _Service.searchpath vami.vmware_pulse_iot_api _Service.DNS vami.vmware_pulse_iot_api _Service.ip0 vami.vmware_pulse_iot_api _Service.netmask0 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. The domain name server IP addresses for this VM (comma- separated). 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. 37

38 Deployment Options The vsphere client provides a drop-down menu to choose the deployment option. For the ovftool use the deploymentoption option. 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. 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 management component/ VMware Identity Manager. 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 make calls to the PostgreSQL DB on the Pulse API server for enrollment credentials validation. 3. If the cacert of the Pulse API cannot be passed using the ssl-cacerts property, then you can manually add the Pulse Device Management Component and vrealize Operations Manager Root CA certificates to the iceapi truststore. The path to the iceapi truststore is /opt/iotapi/config/truststore.jks. Retain the default file permissions and ownership. The following commands are to be run as a 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. 38

39 Ports 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: systemctl restart iceapi 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 /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 Pulse API and of those 39

40 components that the 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: systemctl stop iceapi sudo -iu projectice pg_restore --clean --if-exists -Ft -d projectice /tmp/projectice.tar logout sudo systemctl start iceapi 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 that 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 generated certificates as they are generated after the deployment is started. Since the document assumes that you are familiar with vsphere, the procedure explained below covers only those sections that are relevant to the Pulse API. Procedure 40

41 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. 2. The screen displays the application and network OVF properties. Fill in the application properties. Click Next. 41

42 Note: For this specific example, an ssl certificate is copied after base64 encoding. You can run the following command: 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. 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. 42

43 4. Review the final details and click to Finish to deploy the Pulse API. Install Pulse API OVA using CLI with the ovftool Here is a sample ovftool command to start the Pulse API. Note that the SSL certs, CA certs, and SSH keys are passed from the command. The command below is an example and is to be used as a 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-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 43

44 ~/.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 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. Prerequisites System Services 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 the Pulse Console. The Pulse Console runs a systemd 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: systemctl list-units --type=service --state=running or 44

45 systemctl list-unit-files --type=service To get a list of all systemd services, run the following command: ls /etc/systemd/system/*.wants 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 internal-hostname of the Pulse API as the Pulse Console and API are on the same network. consoleexternalname ssl-pkcs12 ssl-cacerts Fully qualified domain name The hostname must resolve to the IP of the Pulse API server within the Pulse Console VM. The hostname must 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. 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 console-externalname. General information is provided in the section called Application Specific Common OVF Properties, on sslcacerts. 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 45

46 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 searchp ath DNS ip0 netmask 0 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 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. 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 vsphere client provides a drop-down option to select the deployment option. For the ovftool use the deploymentoption option. The OVF provides 2 deployment options 1. Small 46

47 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. Post Installation Ports Post installation, you must complete the following configurations: 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 the 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. systemctl restart iceconsole 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 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 Description Contains a running summary when 47

48 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 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 starts. Since the document assumes that you are familiar with vsphere, the procedure explained below, covers only sections that are relevant to the Pulse API. 48

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

50 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 the Pulse Console. 50

51 Install - CLI with the 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 the EMQTT broker are carried out via the OVF properties. 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. 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. 51

52 System Services The MQTT Broker runs as a systemd 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: systemctl list-units --type=service --state=running or systemctl list-unit-files --type=service To get a list of all the systemd services, run the following command: ls /etc/systemd/system/*.wants You must run both the above commands as a root user. Prerequisites OVF Properties 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. Property Name emqttexternalname Constraints on Values Fully qualified hostname of the MQTT Broker Description 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. 52

53 api-hostname db-password emqtt-user emqtt-passwd emqtt-cookie ssl-pkcs12 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 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 must 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. 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. 53

54 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 Constraints on Values gateway Gateway IPv4 address Fully Qualified Property Name vami.vmware_pulse_em QTT_Broker_Service.g ateway domain domain name vami.vmware_pulse_em QTT_Broker_Service.d omain searchp ath DNS Commaseparated list of domain search paths Commaseparated list vami.vmware_pulse_em QTT_Broker_Service.s earchpath vami.vmware_pulse_em QTT_Broker_Service.D NS Desc ripti on 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. The domain name server IP addresses for this 54

55 ip0 netmask 0 of DNS servers IPv4 address of the VM Netmask for the interface vami.vmware_pulse_em QTT_Broker_Service.i p0 vami.vmware_pulse_em QTT_Broker_Service.n etmask0 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 vsphere client provides a drop-down option to select the deployment option. For the ovftool use the deploymentoption option. 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. Post Installation Configuration MQTT Plugins The MQTT Broker configures itself, if all the mandatory OVF properties are entered correctly as specified in the OVF properties section above. The configuration is applied when the VM starts for the very first time. Verify the installation by running the following command: sudo -i -u emqtt emqttd_ctl plugins list The output of the above command should contain the following two lines: 55

56 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 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 connection requests 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 are being developed should have appropriate retry logic to adapt to any connection failures. The MQTT broker firewall configuration must be updated with the IP address of vrealize Operations Manager so that it is not subject to any rate limiting restrictions. You can do this 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 56

57 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 resolve to the internal IP address of the Pulse API. 2. For further manual changes to the MQTT Broker configuration file or certificates, you must restart the service by running the systemctl restart emqttd 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 a 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. 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. 57

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

59 In this example, an ssl certificate is copied after base64 encoding. You can do this by running the following command in the shell: cat iotssl.pfx base64 -w 0 Capture the output and paste 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. 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. 59

60 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 ~/iotssl.pfx base64 -w 0)" "--prop:ssl-pkcs12-passwd=yyzzzabc1" mqttbroker.ova "vi://administrator%40vsphere.local@vc-iotcks.eng.vmware.com/iot_fire_ice/host/pulse_iot/resources/admin/pulse001" Post Installation Configuration for Helix Adapter in vrealize Operations Manager 60

61 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. VMware Identity Manager VMware Identity Manager provides identity management service, which simplifies business mobility with an included identity provider (IDP) or helps to integrate with existing on-premises identity providers to provide seamless user experience and powerful conditional access controls to single sign on to any applications present in its catalogue. VMware Identity Manager empowers employees to get productive quickly with a self-service app store while providing IT a central place to manage user provisioning and access policy with enterprise-class directory integration, identity federation, and user analytics expected from the leader of hybrid cloud infrastructure. Refer to the VMware Identity Manager documentation for more information. 61

62 Deployment Model Before You Begin Integrating VMware Identity Manager Before you start integrating pulse device management with the VMware Identity Manager you must complete following steps: 1. AirWatch Cloud Connector Setup 2. AirWatch cloud messaging setup through the AirWatch Admin console 3. Verify and update the console site URL 4. Export the VMware Identity Manager SAML metadata 62

63 AirWatch Cloud Connector Setup Note: Configure the AirWatch Cloud Connector by enabling it in the AirWatch admin console at a global level. You can read through the AirWatch Cloud Connector and AirWatch Cloud Messaging setup only if required. Procedure 1. Login to the Pulse Device Management console. 2. Navigate to Groups & Settings from Global OG -> All Settings -> System -> Enterprise Integration -> Cloud Connector. 3. Select the Enable Cloud Connector and Enable Auto Update check boxes to enable AirWatch Cloud Connector and display the General tab and then Save. This will generate certificates for the ACC and AirWatch server. Certificates are generated for both and displayed under ACC and AirWatch certificates in the Advanced tab. 4. Select Download Cloud Connector Installer located near the bottom of screen of the General tab. 5. Enter a password for the AirWatch Cloud Connector certificate in the fields. The password is needed later when you run the AirWatch Cloud Connector installer and must enter the certificate password. It should be same as the AirWatch console password. 6. Select Download and save the Cloud Connector x.x Installer.exe. 7. Login remotely to the AirWatch machine and copy the Cloud Connector x.x Installer.exe to the AirWatch system. 8. Open the installer on the ACC server. When the Welcome screen appears, select Next and enter the password that you used to download the cloud connector. 63

64 AirWatch Cloud Messaging Setup through the AirWatch Admin Console Procedure Navigate to the Groups and Settings under the Global OG -> All Settings -> System -> Advanced -> Site URL s. Scroll down to the AirWatch Cloud Messaging section and enter the AirWatch Cloud Messaging details that you might have configured. If the test connection is successful, click Save. Verify and Update the Console Site URL Procedure 64

65 1. From the AirWatch admin console, navigate to Groups & Settings -> All Settings. Select Global System Advanced Site URLs. 2. Click the Override button and verify if the Console URL contains the word AirWatch as a path parameter in the console URL. Example of the console URL: console server URL>>/AirWatch If the console URL does not match the above pattern, then modify the Console URL and append /AirWatch to it and Save. Export VMware Identity Manager Metadata Procedure 1. Login to the Administrator console of the VMware Identity Manager server and click Catalog tab Webapps. 65

66 2. On the web apps catalog page click Settings. 3. Right click the Identity Provider (IdP) metadata and save it to your local drive for future use. VMware Pulse Device Management Suite Integration You configure settings in the AirWatch admin console to communicate with VMware Identity Manager before you configure AirWatch settings in the VMware Identity Manager admin console. To integrate AirWatch and VMware Identity Manager, the following prerequisites must be followed. 66

67 Prerequisites 1. Verify that the organization group in AirWatch for which VMware Identity Manager is configured, is of the type Customer. 2. Verify that a REST API admin key for communication with the VMware Identity Manager service and a REST enrollment user API key for AirWatch Cloud Connector password authentication are created at the same organization group where VMware Identity Manager is configured. 3. Verify that the API admin account settings and the admin authentication certificate from AirWatch are added to the AirWatch settings in the VMware Identity Manager admin console. 4. Verify that the Active Directory user accounts are set up at the same organization group where VMware Identity Manager is configured. The following are set up in the AirWatch admin console. 1. A REST admin API key for communication with the VMware Identity Manager service. 2. An API Admin account for VMware Identity Manager and the admin auth certificate that is exported from AirWatch and added to the AirWatch settings in VMware Identity Manager. 3. A REST enrolled user API key used for the AirWatch Cloud Connector password authentication. Create an Organization Group Procedure 67

68 1. Navigate to Global -> Groups -> Organization Groups -> Organization Group Details. 2. Select the Add Child Organization Group and enter the necessary details and Save. The organization group should be of the type Customer. Create an AirWatch Administrator in that Organization Group Procedure 68

69 1. Navigate to Accounts -> Administrator -> List View -> Add -> Add Admin. Select Basic Enter the required fields to create an AirWatch administrator. 69

70 2. Click the Roles tab and assign the AirWatch Administrator role to the OG that you created for the VMware Identity Manager integration. After you create the administrator, you can see it in the list view by following the path Accounts -> Administrators -> List View. Active Directory Configuration Note: If the Getting Started page is not displayed when you first login, enter the following getting started URL in any browser. Procedure 1. Login to the newly created OG with the admin user you created. 70

71 2. Accept the EULA and set the security pin and recovery answer if asked. 3. In the Getting Started page, click Start Wizard under Workspace ONE. This will take you to the Workspace ONE Setup page. 4. Click Configure against the ACC Connector/Active Directory section. 5. Click Configure. This will take you to the Deployment Info dialog box. 71

72 6. Select No for the option Are you going to be using SAML for Authentication? 7. Click Next. This will take you to the Server Settings dialog box. 8. Enter your Active Directory services information. 9. Click Next. This will take you to the Users & Groups Settings dialog box. 72

73 If the Active directory setup is correct, when you click Next, the auto detect in the Server Settings page must be successful and the fields must be filled automatically. Auto-detect is a successful message with a green tick mark in the screen shot. 10. Click Test Connection. 11. On successful test connection, click Next. 12. Select the desired option in the Users & Group Settings. In this example we Yes has been selected for all the options. 13. Click Next. This will take you to Directory Setup Complete dialog box. 73

74 14. Select Yes or No for the option, I would like to enable Directory Services as a method of authentication for enrollment. In this example No has been selected. 15. Click Finish. Note: After you click Finish, in the next page, you can either create the directory users and groups as you require, or you can click Close. Closing the window will take you the Active Directory Settings page. 16. Click Close again. VMware Identity Manager Settings in the Getting Started Page Procedure 74

75 1. Click Configure against the VMware Identity Manager Settings. 2. Enter the VMware Identity Manager tenant URL, user name, and password. 3. Click Test Connection. If the test connection is successful, the Continue button is enabled. 75

76 4. Select Yes for the option: Do you want to use AirWatch to authenticate users? 5. Click Save. Note: Steps 4 and 5 are important and essential for SSO. 6. Select VMware Identity Manager by navigating to All Settings -> System -> Enterprise Integration -> VMware Identity Manager. If all the VMware Identity Manager settings are successful, then you will find details of the VMware Identity Manager server that you configured. A directory name against the Directory field in the VMware Identity Manager settings page is also visible. 76

77 Procedure Validate the Integration of AirWatch Directories in the VMware Identity Manager Console To validate if the VMware Identity Manager integration is successful, complete the following steps: 1. Navigate to the VMware Identity Manager configuration page by following the path Groups & Settings (of the integrated Organization Group). All settings -> Enterprise Integration -> VMware Identity Manager. 2. Under the Server subsection of VMware Identity Manager, note the name used in the text box of the directory. 77

78 3. Login to the VMware Identity Manager and click Directories under the Identity & Access Management section in the Administrative Console. 4. The directory name in step 2 must be same as the name in step 3. Provision the Pulse Device Management Suite to VMware Identity Manager Once you confirm that the integration of VMware Identity Manager Settings are correct from the above steps, then provision the Pulse Device Management Suite to the VMware Identity Manager. Procedure 1. Navigate to Directory services of the Customer level organization group that is integrated with the VMware Identity Manager by following the path Accounts -> Administrators -> Administrator Settings -> Directory Services. Scroll down the page and click Start Setup Wizard. 78

79 2. Click Configure in the Directory Services dialog box. This will take you to the Deployment Info section. 3. Select Yes, for the option Are you going to be using SAML for Authentication? 4. Enable SAML for Both. 5. Select Yes for the option Would you like to configure your LDAP Integration? 6. Click Next. This will take you to the Server Settings section 7. Enter the Active Directory details and click Next. 79

80 8. Click Test Connection. 9. On successful test connection, click Next. This will take you to Users and Group Settings. 10. Select the desired option in the Users and Group Settings. In this example Yes has been selected for all the options. 80

81 11. Click Next. This will take you to the Directory Setup Complete section. 12. Select Yes or No for the option, I would like to enable Directory Services as a method of authentication for enrollment. 13. Click Next. This will take you to the Select the Identity Provider section. 81

82 14. Select VMware Identity Manager and click Next. This will take you to Upload IdP file section. 15. Upload the IdP metadata xml that you downloaded from the VMware Identity Manager and click Next. Refer to the section Export VMware Identity Manager Metadata to export the identity provider metadata. Click Next. This will take you to the Verify Settings section. 82

83 16. Verify the SAML settings and modify the Request and Response sections as required. 17. Click Next. This will take you to the Finish Section. Note: The request and response binding type should be of the type POST. 18. Select both the apps and click Finish. This will provision the apps to the instance of VMware Identity Manager that you have configured in the above steps. 19. Login to the VMware Identity Manager Administrator console and click Catalog. You will find the AirWatch apps displayed in the catalog. 83

84 20. Click the AirWatch Admin application and then click the Assign tab in the configuration page 21. Search the users or groups that need to be entitled for this application. 22. Click Save. In this example, All USERS are added as the entitlement. Rest API Key Creation The REST Admin API access and enrolled users access must be enabled in the AirWatch admin console to integrate VMware Identity Manager with AirWatch. Procedure 84

85 1. In the AirWatch admin console, select Groups & Settings -> All Settings -> System -> Advanced -> API -> Rest API. 2. In the General tab, click Add to generate the API key to be used in the VMware Identity Manager service. The account type should be Admin with a unique service name. 3. To generate the enrollment user API key, click Add again. 4. In the Account Type drop-down menu, select Enrollment User. Provide a unique service name. 5. Copy the two API keys and save the keys to a file. 6. Click Save. Certificate Creation for the AirWatch Administrator Set up certificate authentication in the AirWatch admin console. For REST API certificate based authentication, a user level certificate is generated from the AirWatch admin console and the certificate used is a self-signed AirWatch certificate that is generated from the AirWatch admin root cert. Procedure 1. From the AirWatch admin console, select the Accounts -> Administrators -> List View. 2. Select the pencil icon against the admin user that you had used to login, to create the certificate. 3. Click the API tab and select Certificates against the Authentication option. 4. Enter the certificate password. 85

86 5. Click Generate Client Certificate. 6. Click Save to create the client certificate. Export the AirWatch Administrator Client Certificate 7. From the AirWatch admin console, select Accounts -> Administrators -> List View. 8. Select the pencil icon against the admin user that you had used to login, to export the certificate. 9. Click the API tab. The certificates page displays information about the certificate. 10. Enter the same password you had set in the Certificate Password text box to generate the client certificate. 11. Click Export Client Certificate and Save the file. This will export the certificate as a p12 file type. Save the file to your local drive. Setting up AirWatch in VMware Identity Manager Procedure 86

87 1. From the VMware Identity Manager administrator console, navigate to Identity and Access Management tab -> Setup -> AirWatch. 2. Enter the AirWatch integration settings for the following fields: Field AirWatch API URL AirWatch API Certificate Certificate Password AirWatch Admin API Key AirWatch Enrolled User API Key AirWatch Group ID Comments Enter the AirWatch URL. Upload the p12certificate file used to make API calls. Enter the certificate password that you had used to create the admin certificate. Enter the admin API key value. Enter the enrolled user API key value. Enter the AirWatch group ID of the organization group for which the admin API key and certificate was generated. 87

88 3. Click Save. 4. Enable the option Unified Catalog to merge apps set up in the AirWatch catalog to the unified catalog. Even though the Enable radio button is selected, you must first select Disable and Save and then again, select Enable and Save. 5. Enable the option Compliance Check to verify that the AirWatch managed devices adhere to AirWatch compliance policies. Even though the Enable radio button is selected, you must first select Disable and Save and then again, select Enable and Save. 6. Enable the option User Password Authentication through AirWatch. Even though the Enable radio button is selected, you must first select Disable and Save and then again, select Enable and Save. 7. Enable the option User External Access Token Authentication through AirWatch. Even though the Enable radio is selected, you must first select Disable and Save and then again, select Enable and Save. Create the Built-in Identity Provider in VMware Identity Manager Note: If a built-in identity provider is already present, skip to the next section to edit the built in IdP. 88

89 Procedure 1. Login to the Administrator console of the VMware Identity Manager instance. 2. Navigate to Identity and Access Management -> Identity Providers -> Add Identity Provider -> Create Built in IDP. 3. Enter a name for the Identity Provider. 4. Select the new directory you had created in the Directory Services Configuration and validate the directory that you had created in the previous step. 5. Select the ALL Ranges check box for the network. 6. Select and enable the following Authentication Methods. AirWatch External Access Token 89

90 Password (AirWatch Connector) Device Compliance (with AirWatch) Password (Local Directory) 7. Click Add. 8. After you have added the new Identity Provider you can validate all the required fields that you had configured while creating the built-in IdP by navigating to Identity & Access Management -> Manage -> Identity Providers List view. Edit the Built in Identity Provider if Present, in VMware Identity Manager Procedure 1. Login to the Administrator console of the VMware Identity Manager instance. 2. Navigate to Identity and Access Management -> Identity Providers and click the Built-in IDP that is present. 90

91 3. Select the new directory that you created in the Directory Services Configuration and validate the directory you created in the previous step. 4. Select the ALL Ranges check box as the Network option. 5. For Authentication Methods, select and enable the following: AirWatch External Access Token Password (AirWatch Connector) Device Compliance (with AirWatch) Password (Local Directory) 6. Click Save. 91

92 Enable JIT (Just in Time) Enrollment User Creation 1. Login to the Administrator Console of VMware Identity Manager and navigate to Identity and Access Management and select the authentication methods. 2. Click the pencil icon against the Password (AirWatch connector) to configure. 92

93 3. Ensure that the JIT enable option is selected and click Save. Create the Default Access Policy Set in VMware Identity Manager If there is a default access policy rule, ensure that it has at least two policy rules where the configuration values are the same as that of the values mentioned in the steps below. Otherwise, you can edit and modify it as per the guidelines given below. If the default policy set does not exist, or if you want to create your own access policy set, then complete the following steps. 93

94 1. Login to the Administrator console of the VMware Identity Manager instance and select Identity and Access Management -> Policies -> Add Policy. 2. Enter a name for the policy. 3. Enter a description for the policy. 4. Click Next to configure the first policy. 5. Click Add Policy Rule. 6. In the Policy Rule Configuration tab, enter the following details and Save. Configuration If a User s Network Range is If you are trying to access content from then perform this action then the user may authenticate using Values Select ALL RANGES. Select Workspace ONE App. Select Authenticate using. Select Password (AirWatch Connector). 94

95 If preceding Authentication Method fails or is not applicable Re-Authenticate after Select Password (Local Directory). Select 2160 hours. 7. Click Add Policy Rule again to configure the second rule. 8. In the Policy Rule Configuration tab, enter the following details: Configuration If a User's Network Range is If you are trying to access content from then perform this action then the user may authenticate using If preceding Authentication Method fails or is not applicable Re-Authenticate after Values Select ALL RANGES. Select Web Browser. Select Authenticate using. Select Password (AirWatch Connector). Select Password (Local Directory). Select 8 hours. 9. Click Save. 95

96 VMware Pulse IoT Center/VMware Identity Manager Integration To integrate VMware Pulse IoT Center API server with VMware Identity Manager, complete the following steps 1. Download the VMware Identity Manager metadata xml. 2. Create VMware Identity Manager OAuth API keys in the VMware Identity Manager server. 3. Configure the details in the VMware Pulse IoT Center. 4. Add the VMware Pulse IoT Center API server to the VMware Identity Manager as an application. Download the VMware Identity Manager IDP metadata xml Complete the steps mentioned in the section called Export VMware Identity Manager metadata. Create VMware Identity Manager OAuth Keys in VMware Identity Manager Procedure 1. From the VMware Identity Manager admin console, navigate to Catalog -> Settings. 2. Click Create Client from the Remote App Access menu. Create the Service Client Token 96

97 3. Select Access Type as the Service Client Token from the drop-down menu. 4. Enter the details as given in the following table: Parameter Client Id Advanced Tab Refresh Token Generate Secret key Values Enter any name (the name should start with alphabets only). Click the right arrow icon to expand the view. Uncheck the option. Click Generate Secret Key under the Shared Secret parameter. 97

98 Token Type Select Bearer. As per the requirement (in the example, 6 Access Token TTL hours is selected). As per the requirement (in the example, 1 Refresh Token TTL month is selected). As per the requirement (in the example, 4 days Idle Time TTL is selected). 5. Click Add. Save the Generate Shared secret key and Service Client ID for future use. Create User Access Token 6. Click Create Client from the Remote App Access menu. 7. Select Access Type as the User Access Token from the drop-down menu 8. Enter the details as given in the following table. 98

99 Parameter Client ID Application Redirect URI Scope Advanced Tab Generate Secret key Refresh Token Token Type Access Token TTL Refresh Token TTL Values Enter any name (the name should start with alphabets only) Select Identity Manager. Enter the following URL: <Server host>:<port>/api/saml/identity/default/validate Select Profile, User, and OpenID. Click the right arrow icon to expand the view. Click Generate Secret Key under Shared Secret parameter. Select this option. Select Bearer. As per the requirement (in the example, 6 hours is selected). As per the requirement (in the example, 1 month is selected). Idle Time TTL As per the requirement (in the example, 4 days is selected). 9. Click Add. Save the Generate Shared secret key and Service Client ID for future use. Configure the Details in the VMware Pulse IoT Center To integrate VMware Pulse IoT center with VMware Identity Manager please refer to the section called VMware Identity Configuration in the Pulse Console Configuration. Add the Pulse IoT Center API Server to VMware Identity Manager Acquire the API access token Procedure 1. To access or use any API you must acquire the API access token. Use the following API to acquire the token. curl -X GET --header 'Accept: application/json' --header 'Authorization: Basic xxxxxxxxxx=' ' ault/acquire' 99

100 Fetch the Service provider SAML metadata 2. You must provide the Service provider xml to use in the VMware Identity Manager server to register VMware Pulse IoT Center API server as an application in VMware Identity Manager. In this case, the Service Provider is the VMware Pulse IoT Center API server. Use the following API of the VMware Pulse IoT Center to get the Service Provider metadata. curl -X GET --header Accept: text/xml --header Authorization: Bearer xxxxxxxxx' ' Authorization header is Bearer xxxxxxx where xxxxxx is the token that you got from Step 1. {tenant}: Enter the tenant code without curly braces in the API. This API provides the service provider metadata in text/xml format as a HTTP response. Copy the xml and save it for future use. Add the Pulse IoT Center as a Webapp in VMware Identity Manager 3. Login to the Administrator console of the VMware Identity Manager server and click Catalog -> Web Apps. 4. From the Web App Catalog screen of VMware Identity Manager, click New. This will take you to the Definition section of the New SaaS Application. 100

101 5. Enter the name of the application and click Next. This will take you to the Configuration section of the New SaaS application. 6. From the Configuration tab, enter SAML 2.0 as the authentication type. Select URL/XML as the Configuration. 7. Paste the metadata information that you have fetched from the service provider SAML metadata. Scroll down to the Configuration section of the New SaaS Application page. 101

102 8. Turn on Sign Response and Sign Assertion. 9. Encrypt Assertion and Include Assertion Signature options are left to the discretion of the admin. Scroll down to Custom Attribute Mapping subsection in the Configuration section of the New SaaS Application page. 10. In the Configuration tab for Custom Attribute Mappings, add five rows and enter the following attribute mappings and click Next. This will take you to the Access Policy section of the New SaaS Application. Name Format Value UserName Basic ${user.username} FirstName Basic ${user.firstname} LastName Basic ${user.lastname} Phone Basic ${user.phone} Basic ${user. } 102

103 11. Select the access policy that you created as a new access policy in VMware Identity Manager and click Next. This will take you to the Summary section of the New SaaS Application. 12. From the Summary tab, verify the app settings in the Summary page. 13. Click Save & Assign. This will take you to the Assign page to assign entitlements for the application. 103

104 14. From the Entitlement page or Assign page, search for and add the Users/Groups to access this web application. In this example All Users has been added as the entitlement. You can now access the VMware Identity Manager catalog and see the application listed in Catalog -> Web Apps. 104

105 Upgrade For existing customers, there is no upgrade path from older releases to this release. This is because the appliance has moved from Ubuntu to VMware Photon OS. The Pulse API, Pulse Console, and Pulse MQTT broker are now provided as Photon OVAs. The upgrades will be provided as an ISO file (for Offline upgrade) or as a ZIP file (for Online upgrade). You must extract contents from the ZIP file to the update repository on the production server, and must update the production server with updated repository details in the currently running appliances. The production server is an HTTP server and must be set up by customers. It must be reachable from the appliances. For detailed instructions on remote repository, see the Publishing an Update section in VMware Studio Developer Guide available here. For the ISO file, you must mount it in the currently running appliances and update the repository address path to point the CDROM path. Open a terminal to the appliance of interest and follow these steps: Procedure 1. Edit /opt/vmware/var/lib/vami/update/provider/providerdeploy.xml and update the repositoryaddress value by replacing the URL. For ZIP file extraction, point repositoryaddress to the update repository on the production server( For ISO file mount, update it to cdrom:// 2. Run the following command to restart the CIM broker (if the update repository details were modified in the previous step): /etc/init.d/vami-sfcb restart 3. Run this command to check for update availability: /opt/vmware/bin/vamicli update --check 4. Run the following command to install the update. /opt/vmware/bin/vamicli update --install latest 105

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

107 As an administrator, you can save one or two configuration screens and leave the rest to come back again and complete Step 4.a: Lifecycle Management 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 The public URL of the Management Console Server. URL 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 the Group ID. 107

108 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 in this page. Options 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 Manager Configurations (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. 108