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

Transcription

1

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 VMware, Inc Hillview Ave. Palo Alto, CA Copyright 2018 VMware, Inc. All rights reserved. Copyright and trademark information. VMware, Inc. 2

3 Contents 1 Introduction Prerequisites for Installing the VMWare Pulse IoT Center Client on an Edge System Installing the VMware Pulse IoT Center Client Download the VMware Pulse IoT Center Client Packages from the Customer Download Portal Upload the VMWare Pulse IoT Center Client Package to the VMWare Pulse IoT Center Server... 5 Procedure Create the VMWare Pulse IoT Center Client Sideload Package on the VMware Pulse IoT Center Server Set the IoT Configurations Create the Staging Package Download the Pulse IoT Center Client Sideload Staging Package from the VMWare Pulse IoT Center Console... 8 Procedure Creating Technician Users in the Pulse Console... 8 Procedure Install the Pulse IoT Center Client Sideload Staging Package on the Edge System... 9 Procedure Pulse IoT Center Client Command Line Utilities Supported Command Line Arguments for the Client Installer Supported Command Line Arguments for the Registration Utility Supported Command Line Arguments for the Agent Utility Pulse IoT Center Client on Dell Gateways with Ubuntu Core Prerequisites Download the VMware Pulse IOT Center Client Packages from the Customer Download Portal Upload an Agent Create Files/Actions Components Containing Liota Registration Packages Download the Pulse IoT Center Client Sideload Staging Package from the VMWare Pulse IoT Center Console Procedure Snap Generation on a Linux Host Machine Snap Installation and Device Onboarding on Dell Gateway Gateway certification VMware, Inc. 3

4 1 Introduction The VMware Pulse IoT Center Suite is an enterprise suite to onboard, manage, secure, and configure IoT edge systems and connected devices. You can also configure and view the operational efficiency of the IoT edge systems and connected devices. This document describes the agent software, the IoT center client that runs within the IoT edge system to achieve the objectives, together with the VMware Pulse IoT Center Server. This document also describes the agent installation workflow for the newly supported Ubuntu Core Platform with VMware Pulse IoT Centre Prerequisites for Installing the VMWare Pulse IoT Center Client on an Edge System Verify that the VMWare Pulse IoT Center Server is installed. Verify that the edge system has network connection. Verify that the edge system is accessible using SSH. Verify that you have root user access to the edge system to execute scripts. Verify that the edge system is running a Linux operating system and has the following programs installed: o libc o Python 2 (version or later) o libssl o libcrypto 4

5 2 Installing the VMware Pulse IoT Center Client 2.1 Download the VMware Pulse IoT Center Client Packages from the Customer Download Portal IoT edge systems can be based on different hardware types. There are different Pulse IoT center client package for these hardware types. 1. Download the ice-client-<version>.zip file on to a computer. 2. Unzip the ice-client-<version>.zip file. 3. Select the APF file based on the machine (hardware) type. Machine type x86_64 armv7l armv7a armv5tejl armv5tejl + libuclibc Client APF file ice-client-linux-x86_64-<version>.apf ice-client-linux-armv7l-<version>.apf ice-client-linux-armv7a-<version>.apf ice-client-linux-armv5-<version>.apf ice-client-linux-armv5_uclibc-<version>.apf The selected APF file is uploaded into a Pulse IoT center server to create a staging package that can be installed on IoT edge systems. 2.2 Upload the VMWare Pulse IoT Center Client Package to the VMWare Pulse IoT Center Server The system administrator uses the administrator account to log in to the device management console and configure the client packages. Procedure 1. Navigate to the device management console. Ensure that you are under the global organization group or the customer type organization group. 2. Navigate to Devices > Staging & Provisioning > Components > Agent packages. 3. Click Add AirWatch Agent. 4. Select Linux. 5. Upload a Linux VMWare Pulse IoT Center-client APF package based on your platform. 6. Click Save. VMware, Inc 5

6 2.3 Create the VMWare Pulse IoT Center Client Sideload Package on the VMware Pulse IoT Center Server The system administrator uses the administrator account to log in to the device management console, set the configuration, and create sideload packages Set the IoT Configurations 1. From the device management console, navigate to Devices > Devices Settings > Devices & Users > Advanced > IoT Support. 2. Ensure that you are grouped under the intended customer type organization group. 3. Enable IoT Support. 4. In the MQTT Integration section, enter a URL with the MQTT broker hostname and update the port number for the client connection. In the API Integration section, enter a URL with an API host name. 5. You can enable or disable certificate revocation. 6. Click Save. Create the Components that Need to be Part of the Sideload Package Prerequisites 1. Ensure that you have the root CA certificates of the servers to which the gateway communicates. This is mandatory. 2. Ensure that you have the Liota user package that performs registration of the gateway to Pulse. This is mandatory. 3. Ensure that you have all the files required to be installed in the gateway as a prerequisite. This is optional. 4. Ensure that you know the commands or actions required to be executed on the gateway. This is optional. Create Profile Components that Contain a CA certificate 1. From the device management console, navigate to Devices > Staging & Provisioning > Components > Profiles. Ensure that you are under the intended organization group. 2. Click the Add Profile button. 3. Select Linux. 4. In the General section, enter a name and select Staging or Both as the profile scope. 5. Click Credentials in the left pane. 6. Click Configure and upload the root CA certificate of the server such as, MQTT broker, AirWatch, or AWCM and API. 7. Click Save. The profile you created is listed on the Profiles page. Similarly, you can create more profiles using the root CA certificate of other servers with which the ice-client communicates, such as AirWatch or AWCM. VMware, Inc. 6

7 If all the servers with which the ice-client communicates has a common root CA, then only one profile is required. If different servers have a different root CA, then different profiles must be created using each root CA certificate. Create Files/Actions Components Containing Liota Registration Packages 1. From the device management console, navigate to Devices > Staging & Provisioning > Components > Files/Actions. Click Add Files/Actions. 2. Select Linux. 3. In the Files section, click the Add Files button and upload the Liota user package required for registration of the gateways: iotcc_mqtt.py general_edge_system.py 4. Click Save. 5. Provide the download path on the gateway for all the Liota user package files as /opt/liota-packages/. 6. Click Save. The files or action components created and that contain the Liota registration package, are listed. Sometimes, you might have to carry out pre-registration activities such as executing a few commands to install a software. In such cases, it is helpful if you create additional files/action components to perform the required operations. Create Files/Action Components that Contain a Pre-Registration Setup (Optional) 1. From the device management console, navigate to Devices > Staging & Provisioning > Components > Files/Actions. Click Add Files/Actions. 2. Select Linux. 3. In the Files section, select Add Files and select the files that must be downloaded to the gateway. 4. Click Save. The files are displayed. 5. Provide the download path on the gateway for each uploaded file. 6. Click Save. The added files are listed. 7. In the Manifest section, click the Add section. 8. Select Actions To Perform. 9. Provide the required details based on the selected action. 10. Click Save. The added actions are listed. You can add other files or actions by following the steps described above Create the Staging Package When you create the staging package, the previously uploaded ice-client and required components for registrations must be added. Create the Staging Package by Adding the Required Components 1. From the device management console, navigate to Devices > Staging & Provisioning > Staging. 2. Click Add Staging. VMware, Inc. 7

8 3. Select Linux. 4. In the General section, complete the following: i. Enter a name and description for the staging package. ii. Select the intended organization group for this staging package. iii. Select an appropriate ice-client package version for the agent. 5. In the Manifest section, click Add. 6. From Actions to Perform, select Install Profile. 7. In the textbox corresponding to Profile, type/select the profile created for Airwatch. Repeat the steps from Step 5 to add mqtt and API profiles. 8. Select Install Files/Actions. 9. For Files/Actions, select the previously created Files/Actions that contains Liota user packages files. 10. From Actions to Perform, select Install Files/Actions. 11. Select any previously created Files/Actions that must be installed as a prerequisite. 12. Click Save. The staging package that was created is listed on the staging page. 2.4 Download the Pulse IoT Center Client Sideload Staging Package from the VMWare Pulse IoT Center Console Procedure 1. From the device management console, navigate to Devices > Staging & Provisioning > Staging. 2. Double-click the sideload staging button on the right side of the intended sideload package. 3. Ensure that the correct organization group is displayed. 4. Ensure that the universal flag is not selected. 5. Enter a passphrase for the sideload package. 6. Click Download. A sideload staging package file called SideLoadStaging_<string based on package name, version, organization group>.tar.gz is downloaded. 2.5 Creating Technician Users in the Pulse Console Enrollment users do not need to be generated manually for each gateway registration in VMware Pulse IoT Centre 1.1. However, there can be some designated technician user(s) created in Pulse Console, who can initiate multiple gateway registrations. The process authenticates the technician user against a new server endpoint (enrollment service) and retrieves a system generated unique username and password for use on the gateway. The gateway then proceeds to use the retrieved user name and password for enrollment purposes. Procedure 1. Login to the pulse console as sysadmin/pulse admin. 2. Navigate to the Admin tab and create a user using the following steps: i. Click Create Admin VMware, Inc. 8

9 ii. Enter the details in the Create User dialog box, and click Save. By default, the role will be Alert Admin. Follow these steps to change the role to a that of a technician: 3. Click Edit icon corresponding to the user created in Step In the Update Role dialog box, from the Role Name drop-down menu, select Technician and click Save. 5. Login to the console using the user credentials of the technician and change the password. 6. Read and accept the EULA. If you do not accept the EULA, you cannot carry out enrollments. The account is activated. You will be logged out of the console without further access to the Pulse console through this technician user. The credentials of the technician user are used by API s Enrollment Service to generate enrollment users for the enrollment of the gateway. 2.6 Install the Pulse IoT Center Client Sideload Staging Package on the Edge System Procedure 1. On the edge system gateway, copy the sideload staging package file to the file system such as the /tmp/ directory over SSH or by using a USB drive. 2. Extract the sideload staging package into the /tmp/ directory. For example, $ tar xvzf SideLoadStaging_iceclientx86demo_xyz.tar.gz -C /tmp/ 3. Ensure that the ice-client installer under /tmp/agent has execute permissions. For example, $ chmod +x /tmp/agent/ice-client-linux-x86_ sh 4. Execute the ice-client installer present under /tmp/agent/ with root privileges. a. In a non-interactive mode with passphrase, technician user name, and password. For example, $ sudo /tmp/agent/ice-client-linux-x86_ sh -passphrase enroll -user <technician-username> -password <technician-password> Note: When you pass arguments, you can use single quotes to escape special characters (like $ and #) that could be a part of the password string. b. In an interactive mode: i. Execute the installer. For example, $ sudo /tmp/agent/ice-client-linux- x86_ sh ii. Enter the passphrase when prompted. The passphrase must be the same as the one you provided when the sideload package was downloaded. iii. Execute the iotcc utility. For example, $ sudo /opt/ice-client/iotcc iv. Enter the user ID and password of the technician when prompted. VMware, Inc. 9

10 After you run the script, on successful registration, onboarding credentials are generated along with the name of the edge system and the UUID. After successful installation and registration, the IoT edge system is listed in the Pulse Console. VMware, Inc. 10

11 3 Pulse IoT Center Client Command Line Utilities 3.1 Supported Command Line Arguments for the Client Installer Command line argument --enroll N/A Continue with registration/enrollment after installation. -passphrase -user -password Value Description Comments Passphrase String Identifier in GUID format Password String Should be the same passphrase provided during download of the staging package. Give Technician username. Give Technician user password. If not supplied, the iotcc registration script must be executed. You are prompted to enter the details if the command line argument is not entered. Applicable if enroll is You are prompted to enter the details if the command line argument is not entered. Applicable if enroll is -connectiontimeout Numeric value -connectionretries Numeric value Timeout value for connection with the MQTT broker server. Number of connection retries with the MQTT broker server. You are prompted to enter the details if the command line argument is not entered. Applicable if enroll is used Applicable if enroll is This value must be same as the number of retries used in the Liota user packages. -requesttimeout Numeric value Timeout value for request sent to the server. Applicable if enroll is VMware, Inc. 11

12 -requestretries Numeric value Number of request retries to the server. Applicable if enroll is -properties String The string should be a key:value pair separated by comma. <key1>:<value1>,<key2>:<value2>, This value must be the same as the number of retries used in the Liota user packages. These properties will be set for both edge systems and connected devices. No space character allowed in the key/value. -gateway-name Name String Name of the edge system. The supplied name is available for a Liota package in the registry (registry.get( gateway_name )) if the package has a dependency on the credentials package. dependencies = ["credentials"] -path Directory Installation path for the client. Experimental path --keep-logs N/A Preserve the client logs on uninstall. Experimental --start-liota-as-root N/A Execute liotad with root user privileges. Experimental 3.2 Supported Command Line Arguments for the Registration Utility If you have not completed registration as part of installation (--enroll is not used), the registration utility /opt/ice-client/iotcc must be executed for registering the gateway. Command line argument Value Description Comments VMware, Inc. 12

13 -user -password Identifier in GUID format Password string Give Technician username. Give Technician user password. Applicable if enroll is You are prompted to enter the details if the command line argument is not entered. Applicable if enroll is You are prompted to enter the details if the command line argument is not entered. -connectiontimeoutnumeric value -connectionretries Numeric value Timeout value for connection with the MQTT Applicable if enroll is broker server. Number of connection retries with the MQTT Applicable if enroll is broker server. -requesttimeout -requestretries Numeric value Numeric value This value must be same as the number of retries used in the Liota user packages. Timeout value for request sent to the server. Applicable if enroll is Number of request retries to the server. Applicable if enroll is This value must be the same as the number of retries used in the Liota user packages -properties String The string should be a key:value pair separated by comma. <key1>:<value1>,<key2>:<value2>, These properties are set for both edge system and connected devices. No space character is allowed in the key/value. VMware, Inc. 13

14 -gateway-name Name String Name of the edge system. The supplied name is available for a Liota package in the registry (registry.get( gateway_name ) if the package has a dependency on the credentials package. dependencies = ["credentials"] --start-liota-as-root N/A Execute liotad with root user privileges. Experimental 3.3 Supported Command Line Arguments for the Agent Utility. You can use the agent utility (/opt/ice-client/agent) to manage the IoT Center Client. Command line argument stop start Description Stops the client processes. Starts the client processes. Comments restart unenroll Restarts the client processes. De-registers the edge system from the Pulse. Might be followed by an uninstallation of the client based on the response received from Pulse. uninstall Uninstalls the client. Removes the client files. VMware, Inc. 14

15 4 Pulse IoT Center Client on Dell Gateways with Ubuntu Core Prerequisites 1. Verify that you have a Linux host machine with a snap craft tool installed (apt-get install snap craft for Ubuntu hosts). 2. Verify that the host machine has Internet access to download dependencies while generating snap. 3. Verify that you have a Linux host machine because Dell Gateway with Ubuntu Core does not have a snap craft tool which is required for snap generation. 4. On Dell (5000 and 3000) gateways, the snapd package running in the background updates patches from Canonical. This might break agent compatibility due to auto updates to the system, and might affect agent functionality. See section Gateway certification to verify the snapd and core versions that are being used for Dell gateway certification. 4.2 Download the VMware Pulse IOT Center Client Packages from the Customer Download Portal. IoT edge systems can be based on different types of hardware. There are different Pulse IoT center client packages for different types of hardware. Select the ice-client-snapbin-x86 APF file for Ubuntu Core. Upload an Agent 1. Download the ice-client-<version>.zip file on to a computer. 2. Unzip the ice-client-<version>.zip file. 3. Confirm that the snapbin APF file for Ubuntu Core platform is present. Machine Type Client APF File x86_64 ice-client-snapbin-x86_<version>.apf 4. Navigate to the device management console. Ensure that you are under the global organization group or the customer type organization group. 5. Navigate to Devices > Staging & Provisioning > Components > Agent packages. 6. Click Add AirWatch Agent. 7. Select Linux. 8. Upload the ice-client-snapbin-x86_<version>.apf. 9. Click Save. VMware, Inc. 15

16 Create Files/Actions Components Containing Liota Registration Packages 1. From the device management console, navigate to Devices > Staging & Provisioning > Components > Files/Actions. Click Add Files/Actions. 2. Select Linux. 3. In the Files section, click the Add Files button and upload the Liota user package required for registration of the gateways: iotcc_mqtt.py general_edge_system.py Note: The two packages are mandatory for enrolling a gateway or edge-system. 4. Click Save. 5. Provide %SNAP_DATA%/liota-packages as the download path on the gateway for all the Liota user package files. Note: Download all the other staging packages to one of the writable areas of the SNAP. In the download path, while creating staging files/actions, the path should start with one of the following macros. %SNAP_DATA% %SNAP_COMMON% %SNAP_USER_DATA% %SNAP_USER_COMMON% %HOME% 6. Click Save. The files or action components that are created and that contain the Liota registration package are listed. Optionally, you might have to perform a pre-registration setup such as executing some commands to install a software. In such cases, you can create additional files/action components to perform the required operations. 4.3 Download the Pulse IoT Center Client Sideload Staging Package from the VMWare Pulse IoT Center Console Procedure 1. From the device management console, navigate to Devices > Staging & Provisioning > Staging. 2. Click Add Staging and then on Linux and enter the values. 3. From Agent drop-down menu, select the latest agent you have uploaded and click Manifest. a. Click Add > Install Profile. Select the valid MQTT Cert and click Save. b. Click Add > Install Profile. Select a valid AirWatch cert and click Save. c. Click Add > Install Profile. Select the valid API cert and click Save. d. Click Add > Install Files/Actions. Select the Files and Actions created in the previous steps and click Save. VMware, Inc. 16

17 e. Double-click the sideload staging button on the right side of the intended sideload package. 4. Ensure that the organization group shown is correct. 5. Ensure that the universal flag is not selected. 6. Enter a passphrase for the sideload package. 7. Click Download A sideload staging package file called SideLoadStaging_<string based on package name, version, organization group>.tar.gz is downloaded Snap Generation on a Linux Host Machine 1. Copy the sideload package that was downloaded to your local machine, to the home directory of the Linux host machine. 2. After the SideLoadStaging package is copied to your Linux host machine, extract the contents using the following command: tar -xvzf SideLoadStaging_string based on package name_ version_organization group.tar.gz 3. To extract client binaries, navigate to the extracted agent directory and run the following embedded shell: sudo./ice-client-snapbin-x86_64-apf_version.sh 4. The following client binaries are extracted: build-snap.sh ice-client-binaries Under the ice-client-binaries folder, you will see the following file: snapcraft.yaml This file can be used to add any additional interfaces/dependencies that are required by the client snap. Interfaces allow snaps to communicate or share resources according to the protocol established by the interface. Before generating the snap, you can edit this file if anything else is required. A detailed list of interfaces available on Ubuntu core platform, can be found here. In snapcraft.yaml, under the plugs section, add the required interfaces. The following interfaces are required for the Pulse client: network, network-bind process-control, system-observe mount-observe log-observe snapd-control For more information about interfaces and the snapcraft.yaml file, go through the following links: VMware, Inc. 17

18 1. To generate a snap, run the build-snap script that was extracted under the agent folder using the following command: sudo./build-snap.sh This will generate an ice-client snap package along with the script connectinterfaces which contains a list of interfaces to which you can connect. Verify that the ice-client snap is generated successfully without any errors. 2. The following file is created under the /agent/packages directory: connect-interfaces ice-client_apf_version_amd64.snap Snap Installation and Device Onboarding on Dell Gateway 1. Copy the packages directory from the Linux host machine to the gateway home of Ubuntu core Dell on which the ice-client snap is installed and enrollment is triggered. scp -r packages/ user@<dell_gateway_ip>:~/ Note: You can use any SSH client you prefer, to copy the packages from a Linux host machine to an Ubuntu core machine. 2. Login to the Dell gateway and navigate to the packages directory. The following files are available under this directory: connect-interfaces ice-client_apf.version_amd64.snap 3. To install ice-client snap on the Dell gateway, run the following commands: sudo snap install ice-client_apf.version_amd64.snap - dangerous You must use - - dangerous option because the locally generated snap will not have signatures unlike snaps from the store. Verify that the ice-client snap is installed successfully without any errors. 4. To connect to additional interfaces that are required for the ice-client snap, run the connect-interfaces script. Before you connect, modify the permission of the connect-interfaces script as given below and then execute the script. chmod 775 connect-interfaces sudo./connect-interfaces If the script runs successfully, all the required interfaces will be connected. 5. Next, onboard a device by running the following script: sudo ice-client.register -passphrase <staging-passphrase> -user <userid> -password <userpasswd> Passphrase: The passphrase provided during the SideLoadPackage generation on the Airwatch Console. User: The user ID of the technician that was created for that specific organizations group. Password: The password of the technician. 6. Registration should be successful and error free. Generating onboard credentials... Onboard userid : 7fbcf7f3-a e-938a-fdd475958a17 Liotad started Edge System Name : girish_demo1b9m4b02 VMware, Inc. 18

19 UUID : d96d2fa9-0fb ac cb8ff8c Registration successful Note: If registration fails with errors, verify the logs at /var/snap/iceclient/common/logs/ice-client and /var/snap/iceclient/common/logs/liota/ Gateway certification Gateway certifications for both Dell (5000 and 3000) Gateways is performed using the following snap and core versions: $ snap version snap snapd series 16 kernel generic $ snap list core Name Version Rev Tracking Developer Notes core stable canonical core VMware, Inc. 19