WiDM and Zero Touch Deployment Guide WiMAX Device Manager 1.0 Service Management Platform 4.0 Mobile Device Manager 2.1 February 2010 Copyright © 2010 Motive, Inc [http://www.motive.com]. All rights reserved. Important Notice to Users No part of this document may be reproduced or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without the express permission of Motive, Inc. (“Motive”) and/or Alcatel-Lucent. This document and the related software may only be used pursuant to a Software License Agreement or other similar written agreement in place between you and either Motive or Alcatel-Lucent. Furthermore, Motive and Alcatel-Lucent expressly disclaim any and all warranties regarding the information contained in, and the products and systems described in, this document, whether express, implied, or statutory, including without limitation implied warranties of merchantability or fitness for a particular purpose. Furthermore, this document is subject to change without notice. There may exist in this document references to using this product and the systems described herein in connection with products and/or systems owned by third parties. Please note that this information is provided as a courtesy to assist you. Such references are not intended to imply the granting of a license to use such products and/or systems. Such licenses shall result only from separately executed agreements between you and the owner of such products and/or systems. Neither Motive nor Alcatel-Lucent assume any responsibility or liability for incorrect or incomplete information provided about such third-party products. Motive, the Motive logo, and any Motive product names contained herein are trademarks or registered trademarks of Motive, Inc. Alcatel-Lucent and the Alcatel-Lucent logo are registered trademarks of Alcatel-Lucent. All other company and product names mentioned herein are the trademarks or service marks of their respective owners. The products and systems described herein may be covered by the various patents that have been issued to Motive and/or Alcatel-Lucent. Disclaimers This product is intended for commercial uses. Without the prior written consent of either Motive or Alcatel-Lucent it must not be used, sold, licensed or otherwise distributed for use in any hazardous environments requiring fail-safe performance, such as in the operation of nuclear facilities, aircraft navigation or communication systems, air traffic control, direct life-support machines, or weapons systems, in which the failure of products could lead directly to death, personal injury, or severe physical or environmental damage. You hereby agree that the use, sale, license or other distribution of the products for any such application without the prior written consent of either Motive or Alcatel-Lucent, shall be entirely at your sole risk. You hereby agree to defend and hold Motive and Alcatel-Lucent harmless from any claims for loss, cost, damage, expense or liability that may arise out of or in connection with the use, sale, license or other distribution of the products in such applications. This document was originally written in English. If there is any conflict or inconsistency between the English version and any other version of a document, the English version shall prevail. PID WIDM100-widmDeploy Contents Preface .......................................................................................................................... ix Audience ....................................................................................................................... ix Conventions ................................................................................................................... ix Support and contact information ........................................................................................ x PART I 1 2 3 4 INSTALLATION AND DEPLOYMENT Previewing the Installation and Deployment ............................................................ 3 Understanding the WiDM Server ............................................................................... 5 AAA integration ........................................................................................................... 7 Understanding templates ............................................................................................... 7 Zero Touch WiMAX Activation Template ....................................................................... 8 Reviewing the solution diagram ...................................................................................... 9 Understanding the WiDM Server API and the Service Management Platform .......................... 9 Finding product documentation .................................................................................... 10 Understanding the device management servers ................................................................ 10 Understanding licenses ................................................................................................ 11 Understanding the Zero Touch WiMAX Activation Template .................................. 13 Benefits of Zero Touch activation .................................................................................. 14 Flow of events in a Zero Touch activation ....................................................................... 14 Preparing to Install the WiDM Server and the Zero Touch WiMAX Activation Template .................................................................................................................. 17 iii 5 Installing the WiMAX Server Runtime Environment .............................................. 19 Conducting the pre-installation tasks .............................................................................. 20 Defining installation path and completing initial checkpoints .......................................... 20 (Option 1 only) Using deployment-specific BEA license data ........................................... 21 Preparing for SSL configuration .................................................................................. 21 (Options 1 and 2) Creating the modeling schema ............................................................. 26 (Option 1) Installing WiMAX in its own domain ............................................................... 30 Installing the WiMAX domain and its Administration Server ............................................ 30 Installing the WiMAX Managed Server instances ........................................................... 31 Conducting the Option 1 post-installation checkpoints ................................................... 33 (Option 2) Installing WiMAX into an existing domain ....................................................... 35 Updating the existing domain and Administration Server with WiMAX .............................. 35 Updating the existing Managed Server instances with WiMAX ......................................... 37 Conducting the Option 2 post-installation checkpoints ................................................... 40 Understanding the installer.properties values .................................................................. 41 Understanding the Composite data source properties ....................................................... 51 Manually configuring SSL post-installation ...................................................................... 52 6 Deploying the WiDM Server .................................................................................... 57 Development options .................................................................................................. 58 Local system settings for faster development ................................................................ 58 Enabling server-side logging ...................................................................................... 58 Unpacking and repacking the .ear file ............................................................................ 59 Pre-configuring additional JDBC data source pools (optional) ............................................ 60 Deploying the WiDM server applications ......................................................................... 60 Conducting post-deployment tasks ................................................................................. 62 Configuring test modules for better performance ........................................................... 62 Validating the deployment ............................................................................................ 62 7 Post-installation Configuration ................................................................................ 65 Configuring environment properties ............................................................................... 66 Environment property list ......................................................................................... 67 Setting the JNDI Connection URL .................................................................................. 69 Creating a initial user in the Subscription Portal .............................................................. 70 Configuring firmware updates ....................................................................................... 70 Editing profile assignments and default values ................................................................. 71 Configuring HDM ........................................................................................................ 72 iv Installing licenses ....................................................................................................... 73 Storing your WiMAX product license ........................................................................... 73 Troubleshooting the deployment ................................................................................... 74 Data changes not reflected in the system ..................................................................... 74 Verify environment properties .................................................................................... 74 Publish configuration changes .................................................................................... 75 8 A PART II 9 10 11 (Optional) Deploying the Motive Reporting Application ......................................... 77 Understanding the reporting environment ....................................................................... 78 Confirming prerequisites for deploying Motive Reporting ................................................... 78 Configuring the domain for reporting deployment ............................................................ 80 Importing reports ....................................................................................................... 82 Deploying the reporting application ............................................................................... 83 Uninstalling WiDM Server and the Service Management Platform ........................ 87 ADMINISTRATION Product Versions and Licenses ................................................................................ 93 Checking product versions ........................................................................................... 94 Managing WiMAX licenses ........................................................................................... 94 Administering Devices ............................................................................................. 95 Accessing the subscription portal .................................................................................. 96 Administering the WiDM Server .............................................................................. 97 Logging into WebLogic Server Console ........................................................................... 98 Using the Configuration Manager .................................................................................. 98 Restarting servers ....................................................................................................... 99 Adding new managed servers ...................................................................................... 102 Deleting subscriber records ......................................................................................... 102 Configuring security ................................................................................................... 102 About security configuration .................................................................................... 102 Default security objects ........................................................................................... 103 Setting up a new user ............................................................................................. 107 v Enabling and disabling device operations by user role .................................................. 108 Using health check features ........................................................................................ 109 Lightweight health check ......................................................................................... 109 Heavyweight health check ........................................................................................ 110 If a server is down ..................................................................................................... 113 CSR responses when a server is down ........................................................................ 113 Server down scenarios ............................................................................................ 114 12 13 14 B Administering the Motive Reporting Application .................................................. 117 Logging into the Reporting Console ............................................................................. 118 Managing reporting users ........................................................................................... 118 Configuring logging for the reporting applications ........................................................... 120 Logging for the Reporting Console and related services ................................................ 121 Logging for the BIRT engine ..................................................................................... 122 Using the provided reports ......................................................................................... 125 Understanding the provided reports .......................................................................... 125 Publishing and viewing the provided reports ............................................................... 126 WiDM Server Reports ............................................................................................ 131 Maintaining the Modeling Database ...................................................................... 133 Purging snapshots and evaluated models from the schema ............................................... 134 Setting up sample purge script to run regularly .............................................................. 134 Creating Additional JDBC Data Sources ................................................................ 135 PART III 15 16 vi DATA SOURCES About Data Sources ................................................................................................ 141 AAA Data Source .................................................................................................... 143 Connection parameters .............................................................................................. 144 address ................................................................................................................. 144 username .............................................................................................................. 144 password .............................................................................................................. 144 notifyaddress ......................................................................................................... 144 Methods .................................................................................................................. 145 deleteUser ............................................................................................................ 145 disconnectDevice ................................................................................................... 145 getUser ................................................................................................................. 146 insertUser ............................................................................................................. 146 isAvailable ............................................................................................................ 147 isValidLogin .......................................................................................................... 147 registerForDeviceStatus ........................................................................................... 147 unregisterForDeviceStatus ....................................................................................... 148 updateUser ........................................................................................................... 148 17 MDM Data Source .................................................................................................. 151 Connection parameters .............................................................................................. 152 hostname .............................................................................................................. 152 username .............................................................................................................. 152 password .............................................................................................................. 153 phonenumber ........................................................................................................ 153 waitinterval ........................................................................................................... 153 Getting data ............................................................................................................. 153 Synchronous and Asynchronous method calls ................................................................ 153 Methods .................................................................................................................. 154 assignCPProfile ...................................................................................................... 154 assignImageToDevice .............................................................................................. 154 assignInitialPolicy ................................................................................................... 155 assignProfile .......................................................................................................... 155 assignProfileSync ................................................................................................... 155 deleteSubscriber .................................................................................................... 156 executeCommandScript ........................................................................................... 156 executeCommandScriptSync .................................................................................... 156 getAttributes ......................................................................................................... 157 getCachedAttributes ............................................................................................... 157 getCompatibleImagesForDevice ................................................................................ 157 getDeviceTreeForProfile .......................................................................................... 158 getFirmwareVersionForDevice .................................................................................. 158 getUpdatePathsForDeviceAndImage .......................................................................... 159 vii invokeDiscoveryForProfile ........................................................................................ 159 invokeDiscoveryForProfileSync ................................................................................. 160 isAvailable ............................................................................................................ 160 isValidPhone ......................................................................................................... 160 populateCachedAttributes ........................................................................................ 160 populateCachedAttributesSync ................................................................................. 161 rebootstrapSubscriber ............................................................................................. 161 waitForJobs ........................................................................................................... 161 PART IV 18 19 20 API REFERENCE AAA Integration ..................................................................................................... 165 Security roles for AAA integration ................................................................................ 166 WiDM to AAA Server interface .................................................................................... 166 Endpoint Event Service .............................................................................................. 167 deviceOnline ......................................................................................................... 167 deviceOffline ......................................................................................................... 168 Back Office Integration API ................................................................................... 171 Understanding back office integration ........................................................................... 172 ProvisionEndpoint operation ....................................................................................... 172 ProvisionHSD operation ............................................................................................. 172 ProvisionLock operation ............................................................................................. 174 ProvisionVOIP operation ............................................................................................ 174 ProvisioningComplete operation .................................................................................. 176 UpdateToLatestFirmware operation .............................................................................. 176 Database Schema ................................................................................................... 179 EPFIRMWARELATESTVERSION .................................................................................. 180 Glossary ..................................................................................................................... 181 Index .......................................................................................................................... 195 viii Preface WiMAX Device Manager (WiDM) is a Motive product that provides an API for providers to manage WiMAX device activation and provisioning of both TR-069 and OMA DM devices. A deployment of WiDM includes the Service Management Platform, and requires the installation of the Home Device Manager and Mobile Device Manager products. ■ Motive Service Management Platform is the software infrastructure deployment teams use to model subscriber services along with the management operations associated with devices on which the services depend. Example services include broadband, mobile, and FMC (fixed mobile convergence). The primary components of the platform are a runtime environment and several design time tools. ■ Motive Mobile Device Manager allows service providers to remotely provision, update, and manage mobile devices and services throughout the device life cycle. The product provides for single and bulk device provisioning, configuration and management, problem resolution, firmware upgrades, event management, and reporting. MDM Server uses standards-based protocols, OMA DM to communicate with the native DM client installed on mobile devices. ■ Home Device Manager allows broadband providers to remotely manage CPE (customer premises equipment), such as residential gateways, DSL modems, femtocell base stations, IP set-top boxes, and VoIP terminal adapters. Allowing for large-scale remote management of a multi-vendor CPE network, Home Device Manager offers a standardized CPE integration layer that enables providers to manage CPE that support either the Broadband Forum's TR-069 protocol or the SNMP protocol. Home Device Manager includes the Proactive Management Engine that allows policy-based automation of device configuration and management. In addition, the Service Model Northbound Interface (NBI) provides both a standardized web services interface for existing OSS infrastructure, and out-of-the box integration with Motive's Service Activation Manager, Self Service Manager, and Customer Service Manager. As a key benefit to providers, Home Device Manager enables single as well as large-scale bulk device configuration, troubleshooting, firmware upgrades, event management, user management, alarm monitoring, and reporting. Audience The WiDM and Zero Touch Deployment Guide is intended for the deployment team that is to install the Service Management Platform, Home Device Manager, Mobile Device Manager, and AAA server. Typically, the team includes an architect, database administrator (DBA), network administrator, security administrator, and application administrator. Conventions This document uses the following typographic conventions: Audience ix ■ Bold—Identifies the names of graphical user interface buttons, options, commands, fields, and labels. ■ Italic—Identifies variable placeholders such as function or method parameters representing information that must be provided by the implementation or user. Also identifies documentation titles and certain terms to emphasize meaning. ■ Monospace—Identifies ■ Monospace italic—Identifies information that you are required to type exactly as shown. This convention also identifies code and command samples, screen prompts, messages, and filenames. parameters whose actual names or values you must provide at a screen prompt or in a text field. ■ UPPERCASE—Identifies the names of keys on the keyboard. ■ In multi-line code listings, the ↲ symbol indicates that the text was wrapped for typographical reasons. Support and contact information If you encounter issues with this product, visit the Online Customer Support (OLCS) [https://support.alcatel-lucent.com] website. After registering and logging on, you can access troubleshooting information. In addition, you can contact Alcatel-Lucent Motive Support by phone, fax, or email, as follows: Toll-free phone (within U.S.) 1-866-582-3688, option 1 Outside U.S. +1 613 784 6100 (United States) Fax 1-512-339-9040 Email <support@motive.com> The Motive Product Group and its parent company, Alcatel-Lucent, are interested in feedback about your experience with this product and its documentation. If you have comments or suggestions, send email to <pubs@motive.com>. x Preface Installation and Deployment This part covers: ■ Chapter 1, “Previewing the Installation and Deployment” ■ Chapter 2, “Understanding the WiDM Server” ■ Chapter 3, “Understanding the Zero Touch WiMAX Activation Template” ■ Chapter 4, “Preparing to Install the WiDM Server and the Zero Touch WiMAX Activation Template” ■ Chapter 5, “Installing the WiMAX Server Runtime Environment” ■ Chapter 6, “Deploying the WiDM Server” ■ Chapter 7, “Post-installation Configuration” ■ Chapter 8, “(Optional) Deploying the Motive Reporting Application” ■ Appendix A, “Uninstalling WiDM Server and the Service Management Platform” 1 Previewing the Installation and Deployment 3 This chapter provides a summary of the steps required to deploy the Mobile Service Management Solution. The process consists of several main parts, including: 1. Understanding the Mobile Service Management Solution. 2. Installing the applicable device management products, Mobile Device Manager and/or Home Device Manager. 3. Installing the WiDM Server and the Zero Touch WiMAX Activation Template along with the Service Management Platform. 4. Customizing the WiDM models. Understand the WiDM Server and the Zero Touch WiMAX Activation Template Review the solution diagrams. Understand the Service Management Platform. Understand the device management servers. Understand the Zero Touch Template. Install the device management servers Install Mobile Device Manager according to the instructions in the MDM Server Deployment Guide. Install Home Device Manager according to the instructions in the Home Device Manager Deployment Guide. Install the WiDM Server and the Service Management Platform Install the WiDM server according to the instructions in Chapter 4, “Preparing to Install the WiDM Server and the Zero Touch WiMAX Activation Template” on page 17. Perform post-install configuration, deploy, and test Perform initial configuration as described in Chapter 7, “Post-installation Configuration” on page 65. Pre-configure additional JDBC data source pools (optional). Deploy the WiDM Server. Conduct the post-deployment tasks. Validate the deployment. See “Validating the deployment” on page 62 4 Previewing the Installation and Deployment 2 Understanding the WiDM Server This chapter covers: ■ ■ ■ ■ ■ ■ ■ AAA integration Understanding templates Reviewing the solution diagram Understanding the WiDM Server API and the Service Management Platform Finding product documentation Understanding the device management servers Understanding licenses 5 The WiDM Server is the deployment of integrated Motive products that enable providers to manage CPE and mobile devices via WiMAX technology. WiMAX is a technology designed for delivering last-mile wireless broadband access, as an alternative to wired transmission medium such as cable and DSL. Its high bandwidth and range makes it appropriate for delivering high speed internet and rich multimedia applications such as VoIP (voice over IP) , IPTV (Internet Protocol Television), mobile TV, and gaming. The WiDM Server is an API for a virtual server system, allowing customer systems to manage devices that use different protocols and even devices which are offline. The WiDM Server includes the following Motive products: ■ The Service Management Platform. ■ Mobile Device Manager ■ Home Device Manager You may also purchase one or more templates along with the WiDM Server. 6 Understanding the WiDM Server WiMAX Device Manager overview diagram SMP Device Operation API WDM NBI (Device Normalization) Device Operations Model Home Device Manager (HDM) HDM Integration Mobile Device Manager (MDM) MDM Integration WiMAX Integration Logic (WIL) “Device Bootstrapped” Model “Provisioning Complete” Model Schema WIL “New Device” Model Web Service Listening for Events from the AAA Web Service Listening to Back Office Events AAA integration The WiDM Server includes support for integrating with a AAA server. The server includes integration code for the ALU 8950 AAA server, and interface definitions which make it possible to integrate with other AAA servers. For more information, see Chapter 16, “AAA Data Source” on page 143. Understanding templates When you purchase the WiDM Server, you typically also purchase one or more templates, which tie the various products together with content. AAA integration 7 A template includes predefined workflows, service models, business rules, integration adapters and intuitive user interfaces designed to solve a specific business problem. Templates run on the Service Management Platform and use the device managers (Mobile Device Manager and Home Device Manager) to access devices. One template can be purchased for the WiDM Server: the Zero Touch WiMAX Activation Template. Zero Touch WiMAX Activation Template The Zero Touch Template simplifies the subscriber activation process. It allows the creation of flexible workflows which update the firmware on devices upon discovery of the device on the network. It also enables dynamic provisioning of multiple types of services onto the device. A Zero Touch workflow can provision a device without any interaction with the subscriber. The only exceptions are retail devices (that are not preprovisioned) where the subscriber should enter service details through a subscription portal. For more information on the Zero Touch WiMAX Activation Template, see Chapter 3, “Understanding the Zero Touch WiMAX Activation Template” on page 13. 8 Understanding the WiDM Server Reviewing the solution diagram WiMAX Device Manager solution diagram Back Office Subscription Portal PCMCIA Adapter WiDM Server Provisioning Server USB adapter Service Management Platform Embedded WiMAX chipset WiMAX Service Management OLTP Databases OMA-DM protocol Fixed WiMAX CPE OMA-DM engine Content Servers Firewall Firewall Web Proxy Servers Firewall Firewall Handset AAA Servers Network Operator Consoles MDM TR-069 engine Web Proxy Servers HDM TR-069 protocol External Networks DMZ Carrier Infrastructure Trusted Network Understanding the WiDM Server API and the Service Management Platform WiDM Server API. The WiDM server API (application programming interface) is an API for a virtual server system, built on Motive Product Group’s Service Management Platform (SMP), using industry standard technologies such as Java, XML, HTTP, SSL, and J2EE. WiDM server allows service providers to use the same API to contact widely varying devices, managed by different Motive products and responding to different protocols. Applications that use the WiDM API do not need to know whether the target device responds to the TR-069 or OMA-DM (device management) protocol. The system uses models built in the Service Management Platform to delivers instructions to the appropriate device server for each request, Home Device Manager for TR-069 devices and Mobile Device Manager for OMA DM devices. Reviewing the solution diagram 9 The WiDM Server runs on Managed Server instances in the MotiveSMP domain. The domain is an installation of the Service Management Platform. Service Management Platform. The Service Management Platform is a software infrastructure for modeling subscriber services along with the management operations associated with devices on which the services depend. Example services include broadband, mobile, and FMC (fixed mobile convergence). The platform includes a runtime environment and several design time tools. ■ The runtime environment hosts services and applications on a WebLogic Server domain with an Administration Server and a cluster of Managed Servers. Based on the service content deployed, the Managed Servers communicate with device management servers and indirectly with subscriber devices. The runtime environment includes the Discovery service, the Analysis service, the Action interface, and web services. ■ The design time tools include Model Builder, Overlay Builder, and Configuration Manager, as well as a data source adapter framework and data sources. These tools enable service providers to develop deployment-specific content based on supported services and devices. The resulting content is in the form of various models, overlays, and test modules. Finding product documentation Product documentation comes with the WiDM server on the product CD, as PDF files and as help files in console applications. Understanding the device management servers The WiDM server depends on device management servers to communicate with and manage devices. Mobile Device Manager. Motive Product Group product that allows service providers to remotely provision, update, and manage mobile devices and services throughout the device life cycle. The product provides for individual and bulk device configuration, problem resolution, firmware upgrades, event management, user management, and reporting. Mobile Device Manager uses the OMA DM protocol, to communicate with the native DM and DS clients installed on mobile devices. Home Device Manager. Motive Product Group product that allows broadband providers to remotely manage CPE devices that support the TR-069 and SNMP (Simple Network Management Protocol) protocols. Functionality includes policy-based tools to automate device configuration and management, ability to perform single as well as large-scale bulk device configuration, troubleshooting, firmware upgrades, event management, user management, communications logging, and reporting. The Home Device Manager can be integrated with an existing OSS infrastructure and with Motive Product Group’s Service Activation Manager, Self-Service Manager, and Customer Service Manager. 10 Understanding the WiDM Server Understanding licenses After you install the WiDM Server, you must store appropriate licenses for the items you have purchased, using the Configuration Manager application to store the licenses in the database. The following components of the WiDM Server require licenses: ■ WiDM Server ■ Zero Touch WiMAX Activation Template In addition, you must install a license for the Service Management Platform. For licenses for other prerequisites (MDM, HDM) consult the documentation for the appropriate product. To install licenses, see “Installing licenses” on page 73. Understanding licenses 11 12 Understanding the WiDM Server 3 Understanding the Zero Touch WiMAX Activation Template This chapter covers: ■ ■ Benefits of Zero Touch activation Flow of events in a Zero Touch activation 13 The Zero Touch WiMAX Activation Template is an option for the WiDM Server which provides the ability to provision devices without any end-user interaction. You must purchase the WiDM Server in order to purchase the Zero Touch WiMAX Activation Template. The Zero Touch Template simplifies the subscriber activation process. It allows the creation of flexible workflows which update the firmware on devices upon discovery of the device on the network. It also enables dynamic provisioning of multiple types of services onto the device. A Zero Touch workflow can provision a device without any interaction with the subscriber. The only exceptions are retail devices (that are not preprovisioned) where the subscriber should enter service details through a subscription portal. The Zero Touch WiMAX Activation Template is installed with the WiDM Server, but is controlled by a separate license. To make the Zero Touch features available in your deployment, install the WiDM Server and then install the license for the template. ■ For installation instructions, see Chapter 4, “Preparing to Install the WiDM Server and the Zero Touch WiMAX Activation Template” on page 17. ■ For more information on licenses and how to install them, see “Understanding licenses” on page 11. Benefits of Zero Touch activation The Zero Touch WiMAX Activation Template offers the following benefits: ■ Simplified subscriber activation process that updates firmware and configuration settings on the device upon discovery of the device on the network. ■ Flexible workflow enables dynamic provisioning of multiple types of services onto the device. ■ Service Normalization allows the operator to manage services such as VoIP (voice over IP) consistently. Flow of events in a Zero Touch activation The following diagram shows the flow of events when a Zero Touch activation occurs. 14 Understanding the Zero Touch WiMAX Activation Template Zero touch activation flow of events Flow of events in a Zero Touch activation 15 16 Understanding the Zero Touch WiMAX Activation Template Preparing to Install the WiDM Server and the Zero Touch WiMAX Activation Template 4 17 Installing the WiDM Server and the Zero Touch WiMAX Activation Template involves installing required prerequisites, and then installing the WiDM Server and the Service Management Platform. The Zero Touch WiMAX Activation Template, if purchased, is installed with the WiDM Server, and enabled by a separate license. To install the WiDM Server prerequisites 1. Install Mobile Device Manager version 2.1 according to the instructions in the MDM Server Deployment Guide. 2. Install Home Device Manager version 3.0.0 according to the instructions in the Home Device Manager Deployment Guide. Also install the HDM 3.0.2 patch and the HDM 3.0.2.4 hotfix. 3. Configure the HDMEventListener to allow HDM to send notifications to the WiDM Server when a device is activated (bootstrapped). This involves configuring the reference Web Service Notification Plug-in as described below: a. Copy ala-nbi-notification-plugins.jar, axis.jar, and wsdl4j-1.5.1.jar to all servers in the cluster, or to a network path that all servers can reach. b. In the HDM Server Configuration Console, set the following properties: Web Service Notification Plug-in Properties Property Value nbi.notification.plugin.reference. deviceactivationnotification.urls http://WiDM Load Balancer Hostname:WiDM Load Balancer Clear Port/ HDMEventListener/NotificationEventService?WSDL nbi.notification.sender.plugin.name com.alcatel.hdm.nbi.notification.plugin.ReferenceWebservicesPlugin nbi.notification.sender.plugin.url URL path to each of the jar files from the previous step. For example, if the files were placed in /opt/hdm/lib, use: jar:file:////opt/hdm/lib/ ala-nbi-notification-plugins.jar!/;jar:file:////opt/hdm/ lib/axis.jar!/;jar:file:////opt/hdm/lib/wsdl4j-1.5.1.jar!/ For more information on configuring the event listener, see “Understanding NBI web service notifications” in the Home Device Manager Programming Guide. 4. Install WiDM and the Service Management Platform. To install the platform, see Chapter 5, “Installing the WiMAX Server Runtime Environment” on page 19. 18 Preparing to Install the WiDM Server and the Zero Touch WiMAX Activation Template 5 Installing the WiMAX Server Runtime Environment This chapter covers: ■ ■ ■ ■ ■ ■ ■ Conducting the pre-installation tasks (Options 1 and 2) Creating the modeling schema (Option 1) Installing WiMAX in its own domain (Option 2) Installing WiMAX into an existing domain Understanding the installer.properties values Understanding the Composite data source properties Manually configuring SSL post-installation 19 Conducting the pre-installation tasks Defining installation path and completing initial checkpoints To answer questions to guide installation process 1. Which if any of the following data sources will your deployment use? AquaLogic Composite If not already installed, use the corresponding product documentation to install the data source software before continuing. That way, you will have and can apply the configuration values for the applicable data sources upon installing the WiMAX runtime environment. 2. In which one of the following will you install the WiMAX runtime environment? Option 1: Its own WebLogic Server domain (MotiveSMP). In this case, continue with “To conduct checkpoints on the Solaris hosts” on page 20. Or Option 2: An existing WebLogic Server domain such as the MotiveDomain for a deployment of the Motive Product Group's Self Service Portal. Important The existing domain is not a candidate for the WiMAX installation unless it is installed with Oracle BEA WebLogic Server 9.2 on Solaris. Also, the domain may not include an architecture and/or configuration suited for running WiMAX. As a result, Option 2 requires additional quality and performance testing before moving into production. To conduct checkpoints on the Solaris hosts Conduct these checkpoints on each Solaris host, including the hosts for the Modeling Database, Administration Server, and each Managed Server. 1. In the product release notes, review the system requirements to confirm your hosts comply with the corresponding minimum hardware and software requirements. 2. The following conditions are met: Is time-synchronized with all other hosts in the deployment. If unsynchronized, the post-installation deployment can fail. 20 Installing the WiMAX Server Runtime Environment For multicasting considerations, Troubleshooting Multicast Configuration [http://e-docs.bea.com/wls/docs92/ cluster/multicast_configuration.html] has been reviewed carefully. The runtime environment depends on multicast JMS messages which pass information to the Managed Servers. (Option 1 only) Using deployment-specific BEA license data BEA license files are provided with the WiMAX in the WiMAX_solaris.zip file. If preferable for an Option 1 installation, complete the following procedure to use specific BEA license data. To replace provided BEA license files with deployment-specific files 1. Copy the WiMAX_solaris.zip file from the product CD into a network share available to the hosts on which you will install the runtime environment. 2. In the WiMAX_solaris.zip file, replace the provided license files (license.bea and weblogic.jar) with your versions of the files that are named the same way. In the applicable procedures, extract the updated WiMAX_solaris.zip file to the staging directories on the hosts slated for the Administration Server and Managed Servers. This way each BEA WebLogic installation will use the deployment-specific license information. Preparing for SSL configuration Important In an Option 2 scenario, it is likely that the existing domain is already configured for SSL. If not, you can configure SSL manually after installing the runtime environment into the existing domain. In that case, skip this section, complete “(Options 1 and 2) Creating the modeling schema” on page 26 followed by “(Option 2) Installing WiMAX into an existing domain” on page 35, and then use the instructions in “Manually configuring SSL post-installation” on page 52. To configure the Administration Server, Node Manager, and Managed Servers to use production certificates during the installation, it is recommended that you create or obtain two keystores before you install the platform. The installer configures the BEA WebLogic application server with the Custom Identity And Custom Trust option. This requires two JKS-type keystores: the Trust Keystore and the Identity Keystore. The Trust Keystore contains the certificates of trusted certificate authorities. The Identity Keystore has the private key and the corresponding certificate issued by the certificate authority. All the chains associated with the certificate also need to be in the identity keystore. The installer requires that the keystores meet the following standards: ■ The alias value for the private key and corresponding certificate must be sslkey. ■ The store password for the Identity and Trust Keystores must be the same. However, the private key password can and should be different. (Option 1 only) Using deployment-specific BEA license data 21 Preparing for SSL Configuration 1. Create the Identity and Trust Keystores. See “Creating production SSL Certificates” on page 22 for instructions on creating the keystores. Completing the procedure allows you to use the runtime environment installer to auto-configure SSL when installing the Administration Server and the Managed Server instances. If preferable, configure SSL manually after installing the platform; see “Manually configuring SSL post-installation” on page 52. 2. Before installing the Administration Server and the Managed Server instances, copy the Identity and Trust keystore files to a directory on the hosts slated for the components. 3. Open the /data/staging/wimax/installer.properties file, set the following properties in the file, and then save the file: SSL-related Variables useCustomKeystoresForSSL Set to yes to configure the SSL with custom identity and trust keystores. If useCustomKeystoresForSSL=no, the associated values that follow are not applied. customIdentKeystoreFile Specify the full directory path up to and including the name of the identity keystore file on the host. customTrustKeystoreFile Specify the full directory path up to and including the name of the trust keystore file on the host. customKeystorePassPhrase Specify the password configured for both the identity and trust keystores. customPrivateKeyPassPhrase Specify the password configured for the identity keystore. Creating production SSL Certificates Use this procedure to create certificates before installing the runtime environment. The procedure covers: ■ Generating the private and public key pair. ■ Generating a certificate signing request (CSR) for submission to the CA. ■ Procuring a single SSL certificate. Important This SSL configuration process requires configuring all hosts in the domain to use the same certificate. ■ Importing the Certificate Authority (CA) intermediate and root certificates into the identity and trust keystores. 22 Installing the WiMAX Server Runtime Environment ■ Importing the procured SSL certificate into the identity keystore. ■ Retaining the keystore files, keystore password, and private key password for application during the platform installation on the hosts slated for the domain. To procure and pre-configure the production SSL certificate Choose any Solaris host from which to conduct the following steps. 1. Create the identity keystore file and a private key: keytool -genkey -keyalg RSA -keysize 1024 -alias sslkey \ -dname "CN=sslhost.mycompany.com, OU=Test, O=GlobeCom, L=Austin, ST=Texas, C=US" ↲ \ -keystore /path_to/IdentKeystore.jks [-storepass password] [-keypass password] where: ■ The values for the -keyalg and -keysize fields depend on the certificate requirements for the deployment. ■ The alias field value must be set to sslkey. ■ The dname fields and valid values for them are dictated by the CA. ■ sslhostname.mycompany.com is the DNS name for the load balancer to which to issue the certificate. ■ GlobeCom and the geographical values appropriately represent the company procuring the certificate. ■ /path_to/ is the path to the directory in which to create the IdentKeystore.jks file. ■ The instances of password define the passwords for the keystore and private key, which should be different. It is optional to include the password definitions. If preferable, do not include them on the command line, and the tool prompts to define the passwords. Record the password values in a safe place because you need to re-use the passwords several times. 2. Back up the IdentKeystore.jks file: cd /path_to/IdentKeystore.jks cp IdentKeystore.jks IdentKeystore.backup In the following steps if the keystore becomes unusable, this backup comes in handy so that restarting at the beginning of this procedure is unnecessary. 3. Generate the certificate signing request (CSR) for submission to the Certificate Authority (CA): keytool -certreq -keyalg RSA -alias sslkey -sigalg MD5WithRSA \ -keystore /path_to/IdentKeystore.jks \ [-storepass password] [-keypass password] -file /path_to/request.csr where: Preparing for SSL configuration 23 4. ■ The value for the -keyalg matches that specified on the command line in Step 1. ■ The alias field value must be sslkey. ■ The first instance of /path_to/ is the path to the directory in which the IdentKeystore.jks file is stored. The file was created in Step 1. ■ The password instances are the corresponding keystore and private key values defined in Step 1. Optionally, do not include the password switches in the command line, and the tool prompts for the passwords. ■ The second instance of /path_to/ is the path to the directory in which to create the CSR. Use the CSR generated in Step 3 to procure a single certificate from a trusted certificate authority (CA) such as VeriSign Inc. The certificate must meet the following requirements: 5. ■ Is an SSL server certificate. ■ Is issued to the DNS name for the applicable load balancer (that is, the DNS name you defined for the keystore files). Acquire the following certificates: ■ The CA intermediate certificate. ■ The CA root certificate. ■ The procured certificate. In response to submitting the CSR, typically the CA emails you the procured certificate; however, typically you have to acquire the applicable intermediate and root certificates from the CA's Web site. 6. In the same directory on the host, store the certificate strings into separate files: a. Copy the CA intermediate certificate into a file named intermediateca.pem. b. Copy the CA root certificate into a file named rootca.pem. c. Copy the procured certificate into a file named newcert.pem. Important Ensure there are no carriage returns in the .pem files. 7. Validate the .pem files by running the following commands: keytool -printcert -file rootca.pem keytool -printcert -file intermediateca.pem keytool -printcert -file newcert.pem After executing each of the above commands, a content summary for the corresponding certificate appears in output. 8. Store the root CA certificate in the trust keystore, and then store it in the identity keystore: 24 Installing the WiMAX Server Runtime Environment keytool -import -alias ca -file /path_to/rootca.pem \ -keystore /path_to/TrustKeystore.jks \ [-storepass password] keytool -import -alias ca -file /path_to/rootca.pem \ -keystore /path_to/IdentKeystore.jks \ [-storepass password] where password in each command must be the same as the -storepass value defined for the identity keystore in Step 1. The passwords for the identity and trust keystores must be the same. Optionally, do not include the password on the command lines, and the tool prompts for the password. 9. Store the intermediate CA certificate in the trust keystore, and then store it in the identity keystore: keytool -import -alias intermediateca -file /path_to/intermediateca.pem \ -keystore /path_to/TrustKeystore.jks \ [-storepass password] keytool -import -alias intermediateca -file /path_to/intermediateca.pem \ -keystore /path_to/IdentKeystore.jks \ [-storepass password] where password in each command must be the same as the -storepass value defined for the identity keystore in Step 1. The passwords for the identity and trust keystores must be the same. Optionally, do not include the password on the command lines, and the tool prompts for the password. 10. Store the procured certificate in the identity keystore only (that is, not also in the trust keystore): keytool -import -alias sslkey -file /path_to/newcert.pem \ -keystore /path_to/IdentKeystore.jks \ -storepass password -keypass password where: 11. ■ The alias field must be sslkey. ■ The -storepass and -keypass password instances are the corresponding values defined in Step 1. Validate that the certificates were added to the keystores: keytool -list -keystore IdentKeystore.jks keytool -list -keystore TrustKeystore.jks In executing each of the above commands, the tool prompts for the keystore password. After entering the keystore password, an entry for each certificate in the keystore appears in output. Keystore list command Output should include entries for these certificates IdentKeystore.jks Intermediate CA Root CA Procured TrustKeystore.jks Intermediate CA Preparing for SSL configuration 25 Keystore list command Output should include entries for these certificates Root CA 12. To prepare for the platform installations, make backup copies of the IdentKeystore.jks and files in an offline and secure location. For example, burn them to a CD. TrustKeystore.jks 13. For security reasons, remove the original certificate keystores and other files from this Solaris host. (Options 1 and 2) Creating the modeling schema The runtime environment stores models and overlays in the modeling schema. Regardless of the installation option you choose (either Option 1 or Option 2), you need to conduct the following procedure to create the schema before continuing. To create the modeling schema 1. Confirm the following: All hosts were checked for minimum compliance with hardware and software requirements according to the “To conduct checkpoints on the Solaris hosts” on page 20 procedure. An Oracle database instance, in which to create the modeling schema, is available. For the database instance, you know the database administrator (DBA) account credentials. The applicable Oracle client is installed on the Administration Server host. The host is the host slated for the Administration Server (for Option 1 installations) or the host on which the Administration Server is installed in an existing domain (for Option 2 installations). Note For version requirements, see the product release notes. It is recommended to keep the Oracle client and server installations at the same version. A local net service configuration to the database instance is created in the $ORACLE_HOME/network/admin/tnsnames.ora file on the Administration Server host. The configuration entry looks similar to this: 26 Installing the WiMAX Server Runtime Environment ORCL10g = (DESCRIPTION = (ADDRESS_LIST = (ADDRESS = (PROTOCOL = TCP)(HOST = your.database.host.com)(PORT = 1521)) ) (CONNECT_DATA = (SERVICE_NAME = your_service_name) ) ) Connection from the Administration Server host to the database instance has been validated. For example, issue the following command to confirm that. sqlplus dba_user/dba_user_password@net_service_name 2. On the Administration Server host, complete the following steps as the root user: a. Create a staging directory from which to create the modeling schema. For example: mkdir /data/staging/wimax b. 3. From the product CD, unzip the content of the WiMAX_solaris.zip into the staging directory created in Step 2.a. Define the properties for your modeling schema: a. In a text editor, open the installer.properties file from the staging directory (created in Step 2.a). b. In the installer.properties file, define the following properties with corresponding values for your modeling schema. For guidance, see “Understanding the installer.properties values” on page 41. modeling.db.servername modeling.db.sid modeling.db.username and modeling.db.password1 modeling.db.port modeling.db.size modeling.db.drop_existing_db c. 2 Save the changes to the installer.properties file. 1 If the credentials are for an existing schema owner in the specified database instance, the installDB.sh script creates the schema in that user's tablespaces. If the user does not yet exist, the installDB.sh script creates the schema owner, its tablespaces, and then the modeling schema in the user's tablespaces. Important Before applying the credentials for an existing user, double-check that the modeling schema and existing tablespaces do not include conflicting table names. 2 Specify whether to drop an existing modeling schema owner. If you change the value from N to Y, the script first drops any user with the credentials specified in modeling.db.username and modeling.db.password, and then recreates the owner using the same credentials. If the user does not exist in the specified database instance, apply the default value (N). (Options 1 and 2) Creating the modeling schema 27 4. Ensure that the ORACLE_HOME and JAVA_HOME environment variables are set with JAVA_HOME/bin in the path for the root user. For example: export ORACLE_HOME=/opt/oracle/product/10.2.0.1 export JAVA_HOME=/usr/java where /opt/oracle/product/10.2.0.1 and /usr/java are the directory paths to the respective software on the host. 5. If you enabled broadcasting, the installation script needs additional database access, and you must execute some SQL commands. About broadcasting. Broadcasting sends the data for one subscriber to multiple runtime environment users. If your deployment has subscribers assigned to specific users, so that other users never need the same data, leave broadcasting disabled (the default). But if more than one user may need to view a subscriber's data, broadcasting allows a single fetch of the data to satisfy multiple requests. Configuring broadcasting. You can enable/disable broadcasting by editing the parp.xml file (in the APP-INF/lib/application-config.jar file within the WiMAX.ear). The parp-config element within the file has a broadcast attribute whose value can be false, true, or automatic. When it is false (the default), the system never broadcasts; when true, the system always broadcasts; and when automatic, the system uses some database tracking to only broadcast when multiple users are working with the same customer. Preparing database access when broadcasting is used. When broadcasting is set to true or automatic, the installation script needs additional access to run successfully. The following SQL command grants access to the dbms_lock package to public, so that the installation script can use it after it creates the appropriate user. In an SQL console, execute this command (while logged in as the SYS user): grant execute on dbms_lock to public; then execute AutomaticBroadcastProcedures.sql (found in the staging directory). 6. To create the modeling tablespaces and schema owner, run the following commands: cd /data/staging/wimax ./installDB.sh -U dba_user -P dba_user_password -q path_to_sqlplus \ [-d data_file_location -i index_file_location -l lob_file_location] where: ■ ■ ■ 28 Any switch value defined on the command line takes precedence over a corresponding value defined in the installer.properties file. If a required property value is not defined in the installer.properties file or the command line, the script returns the usage message. /data/staging/wimax is the staging directory created in Step 2.a. dba_user and dba_user_password specify the credentials for the Database Administrator (DBA) account. Installing the WiMAX Server Runtime Environment For security reasons, it is recommended to specify these credentials on the command line instead of including them in the installer.properties file; that is why the associated properties are not mentioned in Step 3.b. ■ -q path_to_sqlplus specifies the path to Oracle client on the Administration Server host. For example: /opt/oracle/product/10.2.0.1/bin/sqlplus Confirming connection with the database from this host (by executing sqlplus dba_user/dba_user_password@net_service_name) indicates that the Oracle client is set in the path, which makes it unnecessary to specify this value. ■ [optional switches] ❐ -d data_file_location Specifies the path to the directory in which to store data files on the database host. ❐ -i index_file_location Specifies the path to the directory in which to store index files on the database host. ❐ -l lob_file_location Specifies the path to the directory in which to store the blob and clob files on the database host. For any of these properties unspecified both in the installer.properties file and on the command line that runs the installDB.sh script, the process implements the default location for the respective files. Upon success, the following appears in output: Done! 7. If unsuccessful, do the following: a. Review the content in the following log files in the staging directory (/data/staging/wimax): ■ ■ b. create.log and populate.log, which are created upon running installDB.sh. loadDBContent.log, which is created upon running installDB.sh when a product extends the platform database scripts to add product-specific content to the database. Validate that you can connect to the database instance: sqlplus dba_user/dba_user_password@net_service_name c. Repeat this procedure. After creating the modeling schema, continue with the applicable installation process: (Options 1 and 2) Creating the modeling schema 29 ■ “(Option 1) Installing WiMAX in its own domain” on page 30 Or ■ “(Option 2) Installing WiMAX into an existing domain” on page 35 (Option 1) Installing WiMAX in its own domain With Option 1, you create a WebLogic Server domain of the name MotiveSMP. In addition, you install an Administration Server and one or more Managed Servers, depending on the deployment requirements. In completing “To answer questions to guide installation process” on page 20, you decided whether to use Option 1 or Option 2, whichever applicable. To use Option 2 instead, see “(Option 2) Installing WiMAX into an existing domain” on page 35. Installing the WiMAX domain and its Administration Server Complete the following procedure to create the domain and install the Administration Server. To install the WiMAX domain and its Administration Server on a Solaris host Important Conduct the following steps as the root user on the host slated for the Administration Server. 1. Configure the properties significant for installing your MotiveSMP and its Administration Server: a. In a text editor, open the /data/staging/wimax/installer.properties file. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. b. In the installer.properties file, set the appropriate values using the following checklist. In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. Properties: MotiveSMP and its Administration Server ■ Domain. adminServerHost weblogicUsername weblogicPassword multicastPort multicastAddress ■ SSL. If you created keystore files, set useCustomKeystoresForSSL=yes, and then configure associated SSL properties with the corresponding values. customIdentKeystoreFile 30 Installing the WiMAX Server Runtime Environment customTrustKeystoreFile customKeystorePassPhrase customPrivateKeyPassPhrase ■ AquaLogic data source. If configuring the platform to use the data source, set the properties in the “Aqualogic DataSource” section with corresponding values. ■ Composite data source. If configuring the platform to use the data source, add the associated properties to the installer.properties file with values for your installation according to the instructions in “Understanding the Composite data source properties” on page 51. ■ Administration Server port numbers. If the default port numbers are in use on the Administration Server host (7001 and 9001), set adminListenPort=7001 and adminSslListenPort=9001) with values for available ports instead. Important Do not uncomment and set the #adminAdministrativePort=9002 property. A domain-wide administrative port is not supported in a MotiveSMP. ■ Other considerations. If necessary for the deployment, change the default values for the modeling.db.pool_initial=50, modeling.db.pool_max=1000, and modeling.db.statement_cache_size=500 properties along with any default values in the “JMS settings,” “WorkManager settings,” and “Allowed thread times” sections. c. Save the changes to the installer.properties file. In the following step, issue the initDomain.sh command to create the MotiveSMP and install the Administration Server in the domain based on values specified in the installer.properties file. 2. Run the domain installer: cd /data/staging/wimax ./initDomain.sh A success message appears in output. 3. If unsuccessful and you have trouble re-running initDomain.sh, identify any problems logged in the /data/staging/wimax/server_install.log file. As a last resort, conduct the product uninstallation procedure, and then re-attempt the installation. Installing the WiMAX Managed Server instances In this section, complete the applicable procedure to install each Managed Server instance planned: ■ “To install a Managed Server instance on the Administration Server host” on page 32 ■ “To install a Managed Server instance on a standalone Solaris host” on page 32 Installing the WiMAX Managed Server instances 31 To install a Managed Server instance on the Administration Server host Important It is critical: 1. ■ To complete “To install the WiMAX domain and its Administration Server on a Solaris host” on page 30 before installing the first Managed Server instance. ■ To conduct the following steps as the root user. Configure the properties significant for installing a Managed Server instance: a. In a text editor, open the /data/staging/wimax/installer.properties file. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. b. In the installer.properties file, set the appropriate values using the following checklist. In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. Properties checklist: Managed Server Managed Server port numbers. If the default port numbers are in use on the host (8001, 8002, and 5556), set managedServerListenPort=8001, managedServerSslListenPort=8002, and nodeManagerPort=5556 with values for available ports instead. SSL. If you created keystore files for SSL, double-check that the properties in the “Custom Keystore Information” section are set based on where the keystore files are located and with valid credentials. c. Save the changes to the installer.properties file. In the following step, issue the addManagedServer.sh command to install a Managed Server instance based on values specified in the installer.properties file. 2. Run the Managed Server installer: cd /data/staging/wimax ./addManagedServer.sh A success message appears in output. To install a Managed Server instance on a standalone Solaris host A standalone Solaris host refers to a host that does not include the Administration Server installation. Important It is critical: 32 ■ To complete “To install the WiMAX domain and its Administration Server on a Solaris host” on page 30 before installing the first Managed Server instance. ■ To conduct the following steps as the root user. Installing the WiMAX Server Runtime Environment 1. Copy the staging directory (/data/staging/wimax) from the Administration Server host onto the host slated for this Managed Server instance. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. 2. If configuring SSL, copy the keystore files from the Administration Server into the applicable directory on the Managed Server host (if they are not already in the copied staging directory). See “Preparing for SSL configuration” on page 21. 3. Configure the properties significant for installing a Managed Server instance: a. In a text editor, open the /data/staging/wimax/installer.properties file. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. b. In the installer.properties file, set the appropriate values using the following checklist. In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. Properties checklist: Managed Server Managed Server port numbers. If the default port numbers are in use on the host (8001, 8002, and 5556), set managedServerListenPort=8001, managedServerSslListenPort=8002, and nodeManagerPort=5556 with values for available ports instead. SSL. If you created keystore files for SSL, double-check that the properties in the “Custom Keystore Information” section are set based on where the keystore files are located and with valid credentials. c. Save the changes to the installer.properties file. In the following step, issue the addManagedServer.sh command to install a Managed Server instance based on values specified in the installer.properties file. 4. Run the Managed Server installer: cd /data/staging/wimax ./addManagedServer.sh A success message appears in output. Conducting the Option 1 post-installation checkpoints After installing the Administration Server and each instance of the Managed Server, complete the checkpoints in the following procedure. To complete the WiMAX post-installation checkpoints (option 1) Note If you are unable to confirm the results documented in one of the following steps, skip to the last step. Conducting the Option 1 post-installation checkpoints 33 1. Log into the WebLogic Server Administration Console: Logging into the WebLogic Server Administration Console URL https://adminhost.mycompany.com:9001/console User credentials a Either the credentials for the primary administrative user for the WebLogic Server domain in which the product is running or another WebLogic account created for your use. a where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port configured for the Administration Server. If an Option 2 installation, the port is the domain-wide administration port for the Administration Server (for example, 9002). 2. Verify the Server instances by doing the following from the Domain Structure menu on left: a. Under MotiveSMP, expand the Environment node, and then select Servers. The Summary of Servers page appears on right. b. c. In the Name column, confirm the following: ■ AdminServer(admin) appears in the first row. ■ Each Managed Server instance has a row with SMPCluster in the Cluster column and its appropriate port number specified. Under the Environment node, expand the Clusters node. The Summary of Clusters page appears on right. d. In the Name column, confirm that SMPCluster appears, and then click SMPCluster. The Settings for SMPCluster page appears on right. e. On the Settings for SMPCluster page, click the Servers tab. f. In the Name column, confirm that there is a row for each Managed Server instance. 3. Use the BEA MulticastTest utility (as described in the BEA documentation) to test your configuration, and then make any needed configuration changes. For guidance, see Troubleshooting Multicast Configuration [http:// e-docs.bea.com/wls/docs92/cluster/multicast_configuration.html]. 4. In completing each of the steps above and yielding the expected results, you are done with this procedure. If not, there is a problem with the installation. In that case, uninstall the platform components, and then re-install them. 34 Installing the WiMAX Server Runtime Environment After completing the checkpoints, you are ready to continue with deploying the applications. (Option 2) Installing WiMAX into an existing domain With Option 2, you install the WiMAX into an existing WebLogic Server domain by updating that domain's Administration Server and each of its Managed Servers. Important The existing domain is not a candidate for the WiMAX installation unless it is installed with Oracle BEA WebLogic Server 9.2 on Solaris. Also, the domain may not include an architecture and/or configuration suited for running WiMAX. As a result, Option 2 requires additional quality and performance testing before moving into production. In completing “To answer questions to guide installation process” on page 20, you decided whether to use Option 1 or Option 2, whichever applicable. To use Option 1 instead, see “(Option 1) Installing WiMAX in its own domain” on page 30. Updating the existing domain and Administration Server with WiMAX To update the Administration Server in an existing domain to include the WiMAX Important Conduct the following steps as root on the Administration Server host in the existing domain slated for the WiMAX. 1. Take a backup image of the Administration Server host. 2. Configure the properties significant for updating the Administration Server: a. In a text editor, open the /data/staging/wimax/installer.properties file. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. b. In the installer.properties file, set the appropriate values using the following checklist. In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. Properties checklist: update existing domain and its Administration Server Administration Server name. Replace the property value with the exact name configured for the Administration Server in the existing domain. In a Motive Self Service Portal deployment, the default name format is AdminServer_ADMINISTRATIVE_PORT, where ADMINISTRATIVE_PORT is the domain-wide administration port configured for the Administration Server (for example, AdminServer_9002). Define existing domain and Administration Server. Set updateExistingDomain=yes, and then define the following properties with values that reflect the corresponding configurations for the domain and its Administration Server. (Option 2) Installing WiMAX into an existing domain 35 domainName beaHome domainDir javaHome adminListenPort adminSslListenPort adminAdministrativePort adminServerHost adminServerName weblogicUsername weblogicPassword clusterName multicastPort multicastAddress SSL. If the existing domain is configured for SSL, set useCustomKeystoresForSSL=yes, and then configure the associated SSL properties with the corresponding values: customIdentKeystoreFile customTrustKeystoreFile customKeystorePassPhrase customPrivateKeyPassPhrase AquaLogic data source. If configuring the platform to use the data source, set the properties in the “Aqualogic DataSource” section with corresponding values. Composite data source. If configuring the platform to use the data source, add the associated properties to the installer.properties file with values for your installation according to the instructions in “Understanding the Composite data source properties” on page 51. Other considerations. If necessary for the deployment, change the default values for the modeling.db.pool_initial=50, modeling.db.pool_max=1000, and modeling.db.statement_cache_size=500 properties along with any default values in the “JMS settings,” “WorkManager settings,” and “Allowed thread times” sections. c. Save the changes to the installer.properties file. In the following step, issue the initDomain.sh command to update the existing domain and its Administration Server based on values specified in the installer.properties file. 3. Run the domain installer: cd /data/staging/wimax ./initDomain.sh A success message appears in output. 36 Installing the WiMAX Server Runtime Environment 4. If unsuccessful and you have trouble re-running initDomain.sh, identify any problems logged in the file. If problems persist, see the product documentation for the existing domain. /data/staging/wimax/server_install.log Updating the existing Managed Server instances with WiMAX In this section, complete the applicable procedure to update each Managed Server instance: ■ “To update a Managed Server instance on the Administration Server host” on page 37 ■ “To update a Managed Server instance on a standalone Solaris host” on page 38 To update a Managed Server instance on the Administration Server host Important It is critical: ■ To complete “To update the Administration Server in an existing domain to include the WiMAX” on page 35 before updating a Managed Server instance. ■ To conduct the following steps as the root user from the staging directory on the host. 1. Now that the Administration Server is updated to include the WiMAX, take a second backup image of the Administration Server host. 2. Configure the applicable properties to define the Managed Server on the Administration Server host (that is, the instance slated for the platform installation): a. In a text editor, open the /data/staging/wimax/installer.properties file. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. b. In the installer.properties file, set the appropriate values using the following checklist. In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. Properties checklist: update Managed Server Managed Server name. Uncomment the managedServerName property, and then replace its value with the exact name configured for the Managed Server instance in the existing domain. In a Motive Self Service Portal deployment, the default name format is server_sslPort, where: ■ server is the short name for the host on which the Managed Server is installed. ■ sslPort is the SSL port configured for the Managed Server. JMS Server name. Uncomment the managedJmsServerName property, and then replace its value with the exact name configured for the JMS Server on the Managed Server instance in the existing Updating the existing Managed Server instances with WiMAX 37 domain. In a Motive Self Service Portal deployment, the default name format is JMSServer_server_sslPort, where: ■ server is the short name for the host on which the Managed Server is installed. ■ sslPort is the SSL port configured for the Managed Server. Managed Server port numbers. If the default port numbers are in use on the host (8001, 8002, and 5556), set managedServerListenPort=8001, managedServerSslListenPort=8002, and nodeManagerPort=5556 with values for available ports instead. SSL. If the existing domain is configured for SSL, set useCustomKeystoresForSSL=yes, and then configure the associated SSL properties with the corresponding values: customIdentKeystoreFile customTrustKeystoreFile customKeystorePassPhrase customPrivateKeyPassPhrase c. Save the changes to the installer.properties file. In the following step, issue the addManagedServer.sh command to update a Managed Server instance on the Administration Server host based on values specified in the installer.properties file. 3. Run the Managed Server installer: cd /data/staging/wimax ./addManagedServer.sh A success message appears in output. To update a Managed Server instance on a standalone Solaris host A standalone Solaris host refers to a host that does not include the Administration Server installation. Important It is critical: ■ To complete “To update the Administration Server in an existing domain to include the WiMAX” on page 35 before updating a Managed Server instance. ■ To conduct the following steps as the root user from the staging directory on the host. 1. Take a backup image of the Managed Server host. 2. Copy the staging directory (/data/staging/wimax) from the Administration Server host onto the host slated for this Managed Server instance. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. 38 Installing the WiMAX Server Runtime Environment 3. Configure the applicable properties to define the Managed Server instance installed on the standalone host (that is, the instance slated for the platform installation): a. In a text editor, open the /data/staging/wimax/installer.properties file. The staging directory was created in Step 2.a of “To create the modeling schema” on page 26. b. In the installer.properties file, set the appropriate values using the following checklist. In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. Properties checklist: update Managed Server Managed Server name. Uncomment the managedServerName property, and then replace its value with the exact name configured for the Managed Server instance in the existing domain. In a Motive Self Service Portal deployment, the default name format is server_sslPort, where: ■ server is the short name for the host on which the Managed Server is installed. ■ sslPort is the SSL port configured for the Managed Server. JMS Server name. Uncomment the managedJmsServerName property, and then replace its value with the exact name configured for the JMS Server on the Managed Server instance in the existing domain. In a Motive Self Service Portal deployment, the default name format is JMSServer_server_sslPort, where: ■ server is the short name for the host on which the Managed Server is installed. ■ sslPort is the SSL port configured for the Managed Server. Managed Server port numbers. If the default port numbers are in use on the host (8001, 8002, and 5556), set managedServerListenPort=8001, managedServerSslListenPort=8002, and nodeManagerPort=5556 with values for available ports instead. SSL. If the existing domain is configured for SSL, set useCustomKeystoresForSSL=yes, and then configure the associated SSL properties with the corresponding values: customIdentKeystoreFile customTrustKeystoreFile customKeystorePassPhrase customPrivateKeyPassPhrase c. Save the changes to the installer.properties file. In the following step, issue the addManagedServer.sh command to update a Managed Server instance based on values specified in the installer.properties file. Updating the existing Managed Server instances with WiMAX 39 4. Run the Managed Server installer: cd /data/staging/wimax ./addManagedServer.sh A success message appears in output. Conducting the Option 2 post-installation checkpoints After updating the Administration Server and each instance of the Managed Server with the WiMAX, complete the following procedure. To complete the WiMAX post-installation checkpoints (option 2) Note If you are unable to confirm the results documented in one of the following steps, skip to the last step. 1. Log into the WebLogic Server Administration Console: Logging into the WebLogic Server Administration Console URL https://adminhost.mycompany.com:9001/console User credentials a Either the credentials for the primary administrative user for the WebLogic Server domain in which the product is running or another WebLogic account created for your use. a where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port configured for the Administration Server. If an Option 2 installation, the port is the domain-wide administration port for the Administration Server (for example, 9002). Verify that the platform's JMS module is added to the existing domain from the Domain Structure menu on left: 2. a. Expand the Services node. b. Under Services, expand the Messaging node, and then click the JMS Modules link. The JMS Modules page appears on right. c. 3. In the JMS Modules table, confirm that there is a row with SMPJMSModule. In completing each of the steps above and yielding the expected results, you are done with this procedure. After completing the checkpoints, you are ready to continue with deploying the applications. 40 Installing the WiMAX Server Runtime Environment Understanding the installer.properties values In running installDB.sh, initDomain.sh, and addManagedServer.sh, the processes apply the relevant property values set in the installer.properties file. Note that any supported switches included on the installDB.sh command line override corresponding values set in the installer.properties file. Domain appName=WiMAX Do not change the default value (WiMAX). domainName=MotiveSMP Option 1. Do not change the default value (MotiveSMP). Option 2. Specify the name of the WebLogic Server domain in which to install the platform. For example, the domain name for a Motive Self Service Portal deployment is MotiveDomain. beaHome=/usr/local/bea Option 1. Specify the path to the directory in which to install BEA. Option 2. Specify the path to the directory in which the existing domain's BEA installation is located. For example:/opt/motive #domainDir=user_projects/domains Option 1. Uncomment to specify a different directory in the BEA home directory (set in beaHome property) in which to create the MotiveSMP. For example, the full directory path to the platform domain is /usr/local/bea/user_projects/domains/MotiveSMP with the following property settings applied: beaHome=/usr/local/bea #domainDir=/user_projects/domains Option 2. Uncomment and specify the path to the directory in which the existing domain is located. For example:/domains #licenseFilePath Option 1 only. Leave the property unspecified to use the BEA license files that the platform installer provides. Alternatively, have the installer use a set of license files (license.bea and weblogic.jar) that you provide by specifying the path to the directory in which they are located (for example, /usr/local/mylicenses). updateExistingDomain=no Option 1. Do not change the default value (no). Option 2. Change the default value to yes. In this case, you must also set the following properties with the corresponding values for the domain in which to install the platform: Understanding the installer.properties values 41 domainName beaHome domainDir javaHome adminListenPort adminSslListenPort adminAdministrativePort adminServerName weblogicUsername weblogicPassword clusterName managedServerName managedJmsServerName useCustomKeystoresForSSL customIdentKeystoreFile customTrustKeystoreFile customKeystorePassPhrase customPrivateKeyPassPhrase #javaHome Option 2 only. If installing into a domain that depends on a non-standard version of the BEA JDK, uncomment and specify the path to the directory in which the Java JDK is installed. For example, set javaHome=/opt/motive/jdk150_12 if: ■ ■ /opt/motive is directory in which the existing domain is installed /opt/motive/jdk150_12 is directory in which the existing domain's JDK is installed. #domainCredential=Motive Options 1 and 2. If your deployment requires communication between the WebLogic Server domain in which you are installing WiMAX and one or more other domains referred to as remote domains, uncomment and set this property to a unique string. The domainCredential property value serves as the common credential with which the applicable domains use to establish trust (for example, Motive). In turn and for each remote domain in which to establish trust, uncomment and configure the following set of properties. Important After running the initDomain.sh script with remote domain settings, all servers in the remote domain must be restarted. In addition, it is important to understand the following: 42 ■ The remote domain property settings cause the resetting of any credential that is set to the same value as that set with the domainCredential property. ■ The remoteDomain.<name>.adminServerPort property must be set for the clear port configured for the Administration Server in the remote domain. Currently, you cannot use the WiMAX installer to automatically configure trust for domains in which the domain-wide administrative port is enabled. For example, that is the case for Motive's Home Device Manager and High Speed Data products. Installing the WiMAX Server Runtime Environment #remoteDomain.<name>.adminLogin=weblogic and #remoteDomain.<name>.adminPassword=weblogic Options 1 and 2. Uncomment and replace <name> with the exact domain name for the remote domain (a WebLogic Server domain). Then, replace the property values (weblogic) with the credentials for the remote domain's primary administrative account. For example: remoteDomain.CSCDomain.adminLogin=cscadmin and remoteDomain.CSCDomain.adminPassword=password #remoteDomain.<name>.adminServerHost=localhost Options 1 and 2. Uncomment and replace <name> with the exact domain name for the remote domain (a WebLogic Server domain). Then, replace localhost with the fully qualified address of the Administration Server host for the remote domain. For example: remoteDomain.CSCDomain.adminServerHost=admin.mycompany.com #remoteDomain.<name>.adminServerPort=7001 Options 1 and 2. Uncomment and replace <name> with the exact domain name for the remote domain (a WebLogic Server domain). If different, replace 7001 with the clear port number configured for the Administration Server for the remote domain. For example: remoteDomain.CSCDomain.adminServerPort=7001 Administration Server adminServerHost Option 1. Specify the fully qualified address of the Administration Server host for the MotiveSMP. For example: admin.mycompany.com Option 2. Specify the fully qualified address of the Administration Server host for the domain in which you are installing the platform. For example: admin.mycompany.com #adminListenAddress Options 1 and 2. If necessary for your deployment, uncomment and specify a listen address for the Administration Server that you are installing (Option 1) or updating (Option 2). If not set, the server listens to anything mapped to the host (IP, machine, machine.domain.com, etc.) adminListenPort=7001 Option 1. Specify the clear port number for the Administration Server. If the default port number (7001) is in use on the Administration Server host, change the value; otherwise, leave this setting unchanged. Option 2. Specify the clear port number configured for the Administration Server in the existing domain. adminSslListenPort=9001 Option 1. Specify the SSL port number for the Administration Server. If the default port number (9001) is in use on the Administration Server host, change the value; otherwise, leave the setting unchanged. Option 2. Specify the SSL port number configured for the Administration Server in the existing domain. Administration Server 43 #adminAdministrativePort=9002 Option 1. Do not uncomment this value. The domain-wide administrative port is not supported in a MotiveSMP. Option 2. Uncomment the #adminAdministrativePort=9002, and then change the default port number (9002) if the Administration Server for the existing domain is configured to use a different port for domain-wide administration. adminServerName=AdminServer Option 1. Do not change the default value (AdminServer). Option 2 . Replace the property value with the exact name configured for the Administration Server in the existing domain. In a Motive Self Service Portal deployment, the default name format is AdminServer_ADMINISTRATIVE_PORT, where ADMINISTRATIVE_PORT is the domain-wide administration port configured for the Administration Server (for example, AdminServer_9002). and weblogicPassword=weblogic Option 1. For installing a MotiveSMP and its Administration Server, change the default credentials (weblogic for both the user name and password) to create unique credentials for the platform's primary administrative account. If installing a Managed Server instance, specify the user name and password originally applied during the MotiveSMP and Administration Server installation. weblogicUsername=weblogic Option 2. domain. Specify the credentials (user name and password) of the primary administrative account for the existing Cluster The multicast address and port are used for the servers to communicate within the domain's cluster. The multicast address and port must be reserved exclusively for communication among the servers in the cluster within the IP subnet holding the cluster (or within the LAN if multicast packets are forwarded between subnets). The same address and port must be used by all servers in the cluster. and multicastAddress=237.0.0.101 Specify an available port number and IP address for multicasting in the MotiveSMP. The multicastAddress property must be set within a range from 224.0.0.1 to 239.255.255.255. The default address is: 237.0.0.1 multicastPort Option 1. If the address/port pair implemented are already in use, the platform installations are likely to fail. If the address/port pair is changed after installation and that pair is already in use by another network application or system, the Managed Servers in the SMPCluster cannot communicate with each other. This causes the cluster not to function correctly. Option 2. Specify the port number and IP address configured for multicasting in the existing domain. clusterName=SMPCluster Option 1. 44 Do not change the default value (SMPCluster). Installing the WiMAX Server Runtime Environment Option 2. Specify the name of the cluster in the domain in which you are installing the platform. For example, the cluster name in a Motive Self Service Portal deployment is MotiveCluster, which is part of the MotiveDomain. defaultLoadAlgorithm=round-robin-affinity Options 1 and 2. Do not change this value. clusterAddress Options 1 and 2. Specify the fully qualified address for a host that fronts the Managed Servers in the SMPCluster. If unspecified, the installer applies the address for the Administration Server (set in adminServerHost). Node Manager (Managed Server installations/updates only) #nodeManagerListenAddress If necessary for your deployment, uncomment and specify a node manager listen address for the Managed Server instance that you are installing (Option 1) or updating (Option 2). nodeManagerPort=5556 Option 1. Specify the node manager port number to configure for the Managed Server instance you are installing. If the default port number (5556) is in use on the host, change the default value; otherwise, leave it unchanged. Option 2. Specify the node manager port that is configured for the Managed Server instance that you are updating with the platform in an existing domain. Managed Server #managedServerName=server_8002 Option 2 only. Uncomment the managedServerName property, and then replace its value with the exact name configured for the Managed Server instance in the existing domain. In a Motive Self Service Portal deployment, the default name format is server_sslPort, where: ■ server is the short name for the host on which the Managed Server is installed. ■ sslPort is the SSL port configured for the Managed Server. #managedServerListenAddress=machine.domain.com Options 1 and 2. If necessary for your deployment, uncomment and specify a listen address for the Managed Server instance that you are installing (Option 1) or updating (Option 2). If not set, the server listens to anything mapped to the host (IP, machine, machine.domain.com, etc.) managedServerListenPort=8001 Option 1. Specify the clear port number to configure for the Managed Server. If the default port number (8001) is in use on the host, change the value; otherwise, leave it unchanged. Node Manager (Managed Server installations/updates only) 45 Option 2. Specify the clear port number that is configured for the Managed Server instance in the existing domain. managedServerSslListenPort=8002 Option 1. Specify the SSL port number to configure for the Managed Server. If the default port number (8002) is in use on the host, change the value; otherwise, leave it unchanged. Option 2. Specify the SSL port number that is configured for the Managed Server instance in the existing domain. #managedJmsServerName=JMSServer_server_8002 Option 2 only. Uncomment the managedJmsServerName property, and then replace its value with the exact name configured for the JMS Server on the Managed Server instance in the existing domain. In a Motive Self Service Portal deployment, the default name format is JMSServer_server_sslPort, where: ■ server is the short name for the host on which the Managed Server is installed. ■ sslPort is the SSL port configured for the Managed Server. ear.path=WiMAX.ear Options 1 and 2. Do not change the default value. Custom Keystore useCustomKeystoresForSSL=no Option 1. Keep the default value (no) if not using custom keystores for the MotiveSMP hosts. Otherwise, set useCustomKeystoresForSSL=yes, and then configure the Associated SSL keystore properties on page 46. For more guidance, see “Preparing for SSL configuration” on page 21. Option 2. Keep the default value (no) if existing domain slated for the platform is not configured to use keystores. Otherwise, set useCustomKeystoresForSSL=yes, and then configure the Associated SSL keystore properties on page 46. Associated SSL keystore properties customIdentKeystoreFile Specify the full directory path up to and including the name of the identity keystore file on the host. customTrustKeystoreFile Specify the full directory path up to and including the name of the trust keystore file on the host. customKeystorePassPhrase Specify the password configured for both the identity and trust keystores. customPrivateKeyPassPhrase Specify the password configured for the identity keystore. 46 Installing the WiMAX Server Runtime Environment JMS settings (applied for Administration Server installation/update only) jms.default.timetolive=600000 Options 1 and 2. Do not change the default value. Work Manager Settings (applied for Administration Server installation/update only) Options 1 and 2. As needed, configure the minimum and maximum thread counts for the platform's PARP and discovery Work Manager. parp.workmanager.max=1000 If needed, change the default value for the maximum thread count for PARP (1000). parp.workmanager.min=100 If needed, change the default value for the minimum thread count for PARP(100). discovery.workmanager.max=1000 If needed, change the default value for the maximum thread count for discovery (1000). discovery.workmanager.min=50 If needed, change the default value for the minimum thread count for the discovery. and discovery.workmanager.jndi Do not change the default values. parp.workmanager.jndi Options 1 and 2. Allowed thread times (applied for Administration Server installation/update only) #motive.instrumentation.timeout Options 1 and 2. If needed, uncomment to specify the number of milliseconds to elapse before a model discovery process times out. Otherwise, leave the property unspecified to apply no timeout. #weblogic.stuckthreadmaxtime=600 Options 1 and 2. Specify the number of seconds to elapse before the server reports a WebLogic thread as stuck. If unspecified, the installation or update process applies the default value (600 seconds). If needed, uncomment the motive.instrumentation.timeout property and change its default value. Properties for Oracle modeling database modeling.db.servername Options 1 and 2. Specify the fully qualified address of the host on which the Oracle database instance is installed. For example: db.mycompany.com JMS settings (applied for Administration Server installation/update only) 47 modeling.db.sid Options 1 and 2. Specify the net service name set up for connection between the Administration Server host and the database instance. When using local naming, the value is defined in the Oracle client's tnsnames.ora file. and modeling.db.password Options 1 and 2. Specify the account credentials (user name and password) for the modeling schema owner. If the credentials are for an existing schema owner in the specified database instance, the installDB.sh script creates the schema in that user's tablespaces. If the user does not yet exist, the installDB.sh script creates the schema owner, its tablespaces, and then the modeling schema in the user's tablespaces. modeling.db.username Important Before applying the credentials for an existing user, double-check that the modeling schema and existing tablespaces do not include conflicting table names. In issuing a initDomain.sh or addManagedServer.sh command, the created account credentials are applied for access to the modeling schema. modeling.db.port=1521 Options 1 and 2. Specify the port number for communication between the Administration Server host and the database instance. The default port number is: 1521 modeling.db.poolName=Oracle JDBC Connection Pool, modeling.db.jndiName=jdbc/Modeling, and modeling.db.driver=oracle.jdbc.OracleDriver Options 1 and 2. Do not change the default values for these properties. modeling.db.pool_initial=50, modeling.db.pool_max=1000, modeling.db.statement_cache_size=500 Options 1 and 2. and As needed, change any of the default values to apply for your modeling schema and deployment. Only for Modeling Schema Creation and modeling.db.dbausername (only applied with installDB.sh commands) Options 1 and 2. Specify the DBA account credentials (user name and password) for the database instance in which you are creating the modeling schema. It is recommended to leave these empty in the installer.properties file and to instead include the corresponding parameters on the command line as a part of completing Step 6 of “To create the modeling schema” on page 26. modeling.db.dbausername modeling.db.sqlpluspath Options 1 and 2. Specify the absolute path to the Oracle client on the database host. For example: /opt/oracle/product/10.2.0.1/bin/sqlplus Confirming connection with the database from this host (by executing sqlplus dba_user/dba_user_password@net_service_name) indicates that the Oracle client is set in the path, which makes it unnecessary to specify this value. 48 Installing the WiMAX Server Runtime Environment modeling.db.size Options 1 and 2. Specify SMALL, MEDIUM, LARGE, or XLARGE to determine the size of the tablespaces that the database script is to create for the modeling schema. If unspecified both in the installer.properties file and on the command line that runs the installDB.sh script, the process implements the default size (SMALL). modeling.db.datafile (data files), modeling.db.indexfile (index files), and modeling.db.lobfile (blob and clob files) Options 1 and 2. Specify the path to the directories in which to store the respective database files on the database host. For any of these properties unspecified both in the installer.properties file and on the command line that runs the installDB.sh script, the process implements the default location for the respective files. (only applied with installDB.sh commands) Options 1 and 2. Specify whether to drop an existing modeling schema owner. If you change the value from N to Y, the script first drops any user with the credentials specified in modeling.db.username and modeling.db.password, and then recreates the owner using the same credentials. If the user does not exist in the specified database instance, apply the default value (N). modeling.db.drop_existing_db=N AquaLogic (applied for Administration Server installation or update only) Properties for configuring the platform to use an installed AquaLogic data source. and #aqualogicClientJar=ldjdbc.jar If deployment is to use the AquaLogic data source, uncomment both the aqualogic.db.jndiName and aqualogicClientJar properties. #aqualogic.db.jndiName=jdbc/AqualogicDataSource Options 1— and 2. ■ #aqualogic.db.jndiName=jdbc/AqualogicDataSource Uncomment, but do not change the default value. ■ #aqualogicClientJar=ldjdbc.jar Uncomment and replace the default value to include the directory path up to and including the ldjdbc.jar file based on where it is located and if it is not located in the directory from which you are running the platform installation. By default, find a copy of the file in an AquaLogic installation in this directory: /usr/local/bea/aldsp_3.0/lib aqualogic.db.servername=localhost Options 1 and 2. Specify the fully qualified address for the host on which the AquaLogic Server application is installed (for example: aqualogichost.mycompany.com). The applied value forms part of the AquaLogic URL, which has the following format: jdbc:dsp@localhost:port and aqualogic.db.password=weblogic Specify the account credentials (user name and password) for the AquaLogic Server application. aqualogic.db.username=weblogic Options 1 and 2. AquaLogic (applied for Administration Server installation or update only) 49 aqualogic.db.port=7001 Options 1 and 2. Specify the clear port number configured for the AquaLogic Server. The default value is 7001. The applied value forms part of the AquaLogic URL, which has the following format: jdbc:dsp@localhost:port aqualogic.db.dataspace=XYZ Options 1 and 2. Replace XYZ with the corresponding <DATASPACE> name for the AquaLogic configuration. aqualogic.db.poolName=aqualogic_DS_Pool (pool names cannot include spaces) and aqualogic.db.driver=com.bea.dsp.jdbc.driver.DSPJDBCDriver Options 1 and 2. Change the respective default values (for the database pool and Java class name for the driver) if other values apply for the AquaLogic Server. aqualogic.db.pool_initial=50 Options 1 and 2. If needed, change the default value to configure the initial connection pool size (50). aqualogic.db.pool_max=1000 Options 1 and 2. If needed, change the default value to configure the size of the statement cache (500). The statement cache stores recently-used SQL statements for faster queries. aqualogic.db.statement_cache_size=500 Options 1 and 2. If needed, change the default value to configure the size of the statement cache (500). The statement cache stores recently-used SQL statements for faster queries. Credential for AquaLogic and platform domain If in different domains, the AquaLogic Server and WiMAX must share a domain credential value. Either set the credential manually using the WebLogic Server Administration Console for each domain or uncomment and set the domainCredential property in the Domain section of the installer.properties file. In turn, set the following properties for the remote domain in which AquaLogic is installed. Important After configuring the domain-sharing credential manually or by uncommenting and specifying values for the following properties, you must restart all servers for the changes to take effect. and #remoteDomain.aldsp.adminPassword=weblogic Options 1 and 2. Uncomment and specify the primary administrative account credentials (user name and password) for the domain in which the AquaLogic Server is installed. #remoteDomain.aldsp.adminLogin=weblogic #remoteDomain.aldsp.adminServerHost=localhost Options 1 and 2. Uncomment and this specify the fully qualified host address for the Administration Server for the domain in which the AquaLogic Server is installed. #remoteDomain.aldsp.adminServerPort=7001 Options 1 and 2. Uncomment and specify the clear port configured for the Administration Server for the domain in which the AquaLogic Server is installed. 50 Installing the WiMAX Server Runtime Environment Understanding the Composite data source properties If your deployment is to use an installed Composite data source, add the applicable properties from the following list to the installer.properties file in advance of conducting procedures for Option 1 and 2 platform installations. compositeClientJar=csjdbc.jar Options 1 and 2. Specify the directory path up to and including the client driver file name csjdbc.jar based on where the data source client is located on the Administration Server host. composite.db.servername=localhost Options 1 and 2. Specify the fully qualified address for the host on which the Composite Server is installed (for example, composite.mycompany.com). The applied value forms part of the Composite URL: jdbc:compositesw:dbapi@localhost:port?domain=domain&dataSource=datasource and composite.db.password Options 1 and 2. Specify the primary account credentials (user name and password) for the WebLogic domain in which Composite is installed. composite.db.username composite.db.datasource Options 1 and 2. Specify the <DATASPACE> name for the Composite configuration. The applied value forms part of the Composite URL: jdbc:compositesw:dbapi@localhost:port?domain=domain&dataSource=datasource composite.db.domain=composite Options 1 and 2. If Composite is installed in a domain named something other than composite, replace composite with the applicable name. The applied value forms part of the Composite URL: jdbc:compositesw:dbapi@localhost:port?domain=domain&dataSource=datasource composite.db.port=9401 Options 1 and 2. port number. If Composite is configured with a different port from 9401, replace 9401 with the applicable The applied value forms part of the Composite URL: jdbc:compositesw:dbapi@localhost:port?domain=domain&dataSource=datasource composite.db.poolName=Composite_DS_Pool Options 1 and 2. If Composite is configured with a pool name other than Composite DS Pool, replace with the applicable pool name. Composite_DS_Pool The applied value forms part of the Composite URL: Understanding the Composite data source properties 51 jdbc:compositesw:dbapi@localhost:port?domain=domain&dataSource=datasource and composite.db.driver Do not change the default values for these properties. composite.db.jndiName=jdbc/CompositeDataSource Options 1 and 2. (optional) composite.db.pool_initial Options 1 and 2. If unspecified, the installer applies the default value to configure the initial connection pool size (1). If needed, specify the composite.db.pool_initial property with a different number for the initial pool size. (optional) composite.db.pool_max Options 1 and 2. If unspecified, the installer applies the default value to configure the maximum connection pool size (100). If needed, specify the composite.db.pool_max property with a different number for the maximum connection pool size. (optional) composite.db.statement_cache_size= Options 1 and 2. If unspecified, the installer applies the default value to configure the size of the statement cache (10). The statement cache stores recently-used SQL statements for faster queries. If needed, specify the composite.db.statement_cache_size= property with a different number for the statement cache. Manually configuring SSL post-installation If you decide to add custom keystores after you have installed the platform, use the following procedure to configure them. To replace the existing certificate with a new production certificate 1. Complete “To procure and pre-configure the production SSL certificate” on page 23 to create your keystores, IdentKeystore.jks and TrustKeystore.jks. 2. Copy the new keystores to all hosts including those on which the Administration Server and each Managed Server is installed. For example, they can be copied to the install directory. 3. Log in to the WebLogic Server console and stop all Managed Servers, using the controls on the Environment->Servers->Control tab. 4. For each Managed Server, kill the node manager process. a. Determine the process ID number by searching through the list of processes for lines that contain java: ps –ef | grep java Look for a process like this one: /usr/local/bea/jdk150_06/bin/java –client –Xms32m –Xmx200m XX:MaxPermSize=128m 52 Installing the WiMAX Server Runtime Environment b. After you determine the process ID number, issue a kill command: kill <pid> 5. On each host with a Managed Server instance, configure the Node Manager to use the new production certificates by adding the following to the end of the nodemanager.properties file, located in the directory <beaHome>/weblogic92/common/nodemanager : KeyStores=CustomIdentityAndCustomTrust CustomIdentityAlias=sslkey CustomIdentityKeyStoreFileName=<identity_key_store_file> CustomIdentityKeyStorePassPhrase=<keystore_password> CustomIdentityKeyStoreType=JKS CustomIdentityPrivateKeyPassPhrase=<private_key_password> where ■ <identity_key_store_file> is the full path and name to the identity keystore file on the Managed Server ■ <keystore_password> is the keystore password used to create the keystore ■ <private_key_password> is the private key password used to the create the keystore The node manager encrypts the password values in the file at startup. Note <beaHome> refers to the value of beaHome that is set in the installer.properties file. 6. Configure SSL for each server from the WebLogic Server Administration Console. a. Select Environment->Servers b. In the Change Center box on left, click Lock & Edit. c. For each server in the list including the Administration Server: i. Select the Configuration tab, then the Keystores subtab. ii. In the Keystores list box, select Custom Identity and Custom Trust. Then set these values: ■ Custom Identity Keystore: <the full pathname for the identity keystore file on the Managed Server> ■ Custom Identity Keystore Type: JKS ■ Custom Identity Keystore Passphrase: <keystore_password> ■ Confirm Custom Identity Keystore Passphrase: <keystore_password> ■ Custom Trust Keystore: <the full pathname for the trust keystore file on the Managed Server> ■ Custom Trust Keystore Type: JKS Manually configuring SSL post-installation 53 ■ Custom Trust Keystore Passphrase: <keystore_password> ■ Confirm Custom Trust Keystore Passphrase: <keystore_password> iii. Click the Save button iv. Select the SSL subtab. In the Identity and Trust Locations list box, select Keystores. Then set these values: v. ■ Private Key Alias: sslkey ■ Private Key Passphrase: <private_key_password> ■ Confirm Private Key Passphrase: <private_key_password> Click the Save button After keystore and private key values are configured for each server, click the Activate Changes button. 7. Stop the Administration Server from the WebLogic console using the controls on the Environment->Servers->Control tab. 8. Start the Administration Server: a. From the Administration Server host, run the following commands as root: cd <beaHome>/user_projects/domains/MotiveSMP/bin ./startWebLogic.sh The script prompts you for the credentials for the WebLogic user. b. Type the credentials for the user configured during the product installation (that is, the values for weblogicUsername and weblogicPassword originally set in the installer.properties file). c. Once the following confirmation appears, in output press CTRL+Z: <Server state changed to RUNNING> <Server started in RUNNING mode> d. Run the following command: bg 9. Start the Node Manager on each Managed Server: cd <beaHome>/weblogic92/server/bin ./startNodeManager.sh <hostname> <port> where <hostname> is the host machine name and <port> is the nodeManagerPort value from the installer.properties file 54 Installing the WiMAX Server Runtime Environment 10. From the WebLogic console, start all Managed Servers, using the controls on the Environment->Servers->ServerName->Control tab. Confirm the status for each Managed Server is TASK_COMPLETE and state is RUNNING. Manually configuring SSL post-installation 55 56 Installing the WiMAX Server Runtime Environment 6 Deploying the WiDM Server This chapter covers: ■ ■ ■ ■ ■ ■ Development options Unpacking and repacking the .ear file Pre-configuring additional JDBC data source pools (optional) Deploying the WiDM server applications Conducting post-deployment tasks Validating the deployment 57 Development options Use the topics in this section when configuring a machine for use in developing the system. Local system settings for faster development The system pre-caches all the models and overlays at application startup. This can slow down development. To turn it off: Turning off caching and precompiling 1. To turn off model caching, edit the file ConfigurationManager/WEB-INF/web.xml, commenting out the following lines: <listener> <listener-class>motive.serviceview.ModelingFacadeContextListener</listener-class> </listener> 2. To turn off precompiling of the Configuration Manager JSP files, edit the file ConfigurationManager/WEB-INF/weblogic.xml, changing the precompile value to false, as shown below: <jsp-param> <param-name>precompile</param-name> <param-value>false</param-value> </jsp-param> Enabling server-side logging The system uses log4j for server-side logging. You can enable logging by editing the log4j.properties files in the file. application-config.jar Note If you have not already done so, unpack the WiMAX.ear file as described in “Unpacking and repacking the .ear file” on page 59 before making the changes below. Repackage the application when the following changes are complete, unless you have additional changes to make. The following classes are useful classes to log: ■ MDM Datasource: motive.datasource.mdm ■ Oracle Datasource: motive.datasource.oracle ■ User-entered Javascript logging in models: motive.utilities.javascript.JavascriptLogger 58 Deploying the WiDM Server Log file location. On the server, log files can be found in the folder /usr/local/bea/user_projects/domains/MotiveCSC/servers/servername/logs/ servername.out in the and servername.log files. Configuring rolling logs. By default, when log files reach 2GB, log messages are no longer written. Configuring log4j to use a RollingFileAppender allows log4j to “roll” the log file when it reaches a certain size. To configure log4j to do this, set the following properties in the log4j.properties file: log4j.rootLogger=WARN, A2 log4j.appender.A2.File=/usr/local/bea/logs/motive.log log4j.appender.A2.MaxFileSize=100MB log4j.appender.A2.MaxBackupIndex=500 Unpacking and repacking the .ear file In the following procedure you decompress the files in the WiMAX.ear file so that you can change the individual files that make up the .ear. To unpack the application 1. From the Administration Server host, extract the WiMAX.ear file to a development location. The .ear file is located in the staging directory you created for the platform installation files on the Administration Server host: /data/staging/wimax 2. Extract the csc.war file from the WiMAX.ear file. You can now edit the files contained in the csc.war file to change the reference application. To repack the application 1. Compress the WiMAX.ear tree into a new .ear file. 2. In the staging directory you created for the platform installation files on the Administration Server host, replace the WiMAX.ear file with the updated WiMAX.ear file: /data/staging/wimax Important The configured .ear file must be in the same staging directory that contains the deploy.sh file. In Step 1 of “To deploy the WiDM server applications” on page 61, you run deploy.sh to deploy the applications. 3. Redeploy the application as described in “To deploy the WiDM server applications” on page 61. Unpacking and repacking the .ear file 59 Pre-configuring additional JDBC data source pools (optional) Optionally, complete this procedure to pre-configure additional data source pools for the SMPCluster. To pre-configure additional JDBC data source pools Important If not creating additional data source pools for the SMPCluster, skip this procedure. If more pools become necessary post-deployment, use the instructions in Appendix B, “Creating Additional JDBC Data Sources” on page 135. 1. On the Administration Server, open the following file in a text editor: /data/staging/wimax/installer.properties 2. In the installer.properties file, paste a copy of the following block for each pool you want to add: #========================================= #Properties for X JDBC pool #========================================= # VALUES MUST BE SET: <poolnameX>.db.servername= <poolnameX>.db.sid= <poolnameX>.db.username= <poolnameX>.db.password= <poolnameX>.db.port= <poolnameX>.db.poolName= <poolnameX>.db.jndiName= <poolnameX>.db.driver=oracle.jdbc.OracleDriver 3. In each of the pasted blocks, do the following, and then save the changes to the installer.properties file. a. Replace each instance of <poolnameX> with the desired name for the pool. b. For each of the properties, specify a valid value after the equal sign (=). The additional connection pools configured are created when you execute deploy.sh according to Step 1 of “To deploy the WiDM server applications” on page 61. Deploying the WiDM server applications After completing the required pre-deployment tasks, deploy the applications that make up the server with this procedure. 60 Deploying the WiDM Server To deploy the WiDM server applications Complete the following steps as the root user: 1. As the root user, run the following commands: cd /data/staging/wimax deploy.sh where /data/staging/wimax is the staging directory you created for the platform installation files on the Administration Server host. After the deployment script finishes without error, continue with the next step. 2. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 3. Start all the Managed Servers in the SMPCluster: a. Expand the Environment node, select the Clusters node, and then select the SMPCluster link. The Summary of Clusters > SMPCluster page appears. b. On the Summary of Clusters > SMPCluster page, click the Control tab. c. Select the check box for each Managed Server instance, and then click the Start button. A confirmation appears. d. Click the Yes button. e. Refresh the page until Running appears for each instance in the State column. Deploying the WiDM server applications 61 Conducting post-deployment tasks In this section, complete the tasks that apply to your deployment. Configuring test modules for better performance You can improve the performance of the system by changing settings in the test modules so that the test modules do not store results. To do this, use the Configuration Manager to edit each test module. In the Properties tab, change the setting for the Save Result property to No. For more information, see “Using the Configuration Manager” on page 98. Validating the deployment To validate the deployment 1. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. Verify the standard users and roles by doing the following from the Domain Structure menu on left: 2. a. Under MotiveSMP, click Security Realms. The Summary of Security Realms page appears on right. b. 62 In the Name column, click myrealm. Deploying the WiDM Server The Settings for myrealm page appears. c. On the Settings for myrealm page, click the Users and Groups tab. d. On the Users tab, confirm that the following Motive-specific user accounts appear: ■ configuser ■ consoleuser ■ webserviceuser ■ servicepolicyuser Another listed user, the weblogic user, is the primary WebLogic Server domain administrative user. The account credentials were created based on the weblogicUsername=weblogic and weblogicUsername=weblogic weblogicPassword=weblogic properties set in the installer.properties file used during the Administration Server installation. e. On the Groups tab, confirm that the following Motive-specific groups appear: ■ SV_Console ■ SV_ConfigurationManager ■ SV_User ■ SMP_ServicePolicy ■ SV_Tier1 ■ SV_Tier2 ■ SV_NOC ■ SV_Admin ■ SV_GetTestGroups ■ SV_ExecutePARPRequest Note The installation script assigns the user “consoleuser” to the SV_Console group to give it access to the Customer Service Console. For information on setting up new users, see “Setting up a new user” on page 107 Validating the deployment 63 64 Deploying the WiDM Server 7 Post-installation Configuration This chapter covers: ■ ■ ■ ■ ■ ■ ■ ■ Configuring environment properties Setting the JNDI Connection URL Creating a initial user in the Subscription Portal Configuring firmware updates Editing profile assignments and default values Configuring HDM Installing licenses Troubleshooting the deployment 65 After installing the WiDM server and the Service Management Platform, perform the tasks described in this section to complete the initial configuration of the system. Configuring environment properties In the following procedure, specify appropriate environment property values for your WiDM Server deployment in the Configuration Manager application. At a minimum, you must edit the following properties: ■ MDM.username The default value is sspadmin. ■ MDM.password The default value is motivemdm. ■ ■ MDM.Hostname WiDM.username The default value is webserviceuser. ■ WiDM.password The default value is webserviceuser. ■ ■ WiDM.Hostname TENANT The default value is wimax. Use the name created in MDM for the WiMAX operator. ■ AAA.user For a default installation, use provis_ws. ■ AAA.password The default value is motive. ■ ■ AAA.URL WiMAXWorker.Realm For a default installation use wimax. 66 Post-installation Configuration ■ ■ MDMRootCertificateFile FirmwareAssign.Timeout For a default installation use 300. To configure environment properties 1. Open the following URL in a browser: http://<mgdhost>.mycompany.com:8001/config where ■ mgdhost.mycompany.com is the address of the host on which a Managed Server instance is installed. ■ 8001 is the Managed Server clear port. and log in in using appropriate credentials. The default username and password for the application is configuser/configuser. 2. On the left in the Configuration Manager, click Environment Properties. The system displays a list of properties. For descriptions of the properties, see “Environment property list” on page 67. 3. As applicable for your deployment, edit the environment property values from the previous step, and then click the Save Changes button. 4. Publish the new content to the server: a. In the upper-right corner, click the Publish To Server button. b. In the Description field, type: Adding CSC environment properties c. Click the Publish button. 5. On the left, click Reset Cache, and then click the Clear Cache button. 6. Restart all servers in the SMPCluster before continuing. Applying the CSC_ResourceServlet_HOST, CSC_ResourceServlet_PATH properties requires a restart; other property changes do not. Environment property list This list shows the environment properties used by the reference implementation. Additional properties can be defined by the end user or added by Motive Services. In general, these properties all need to be defined for your WiDM deployment to work properly. AAA.URL. The URL of the AAA server provisioning service. For example: Environment property list 67 http://135.140.160.57:9080/axis2/services/ProvisioningService AAA.Username. Username for logging into the AAA server provisioning service. The default value is provis_ws. AAA.Password. Password for logging into the AAA server provisioning service. The default value is motive. MDM.Hostname. Specifies the host name and port for the MDM Server. Note The system determines whether the server is available based on the existence of the MDM.Hostname property, so you can disable the server by setting this property to an empty string. MDM.Username and MDM.Password. Specifies the primary account credentials for the MDM Server. HDM.Hostname. The hostname of the HDM server. Use a fully-qualified name (including the http:// prefix) and a port number, if needed. For example: http://myhdmserver.mycompanyname.com:80 HDM.Username. The nbiexws.Username. HDM.Password. username to use on the HDM server. Must match the HDM server configuration property The password for the supplied username. HDM.CertificateFile. HDM.ResultTimeout. The location of a valid certificate file for authenticating to the HDM server. A timeout, expressed in milliseconds, for the system to use when waiting for a result from an HDM server. TENANT. Specifies the tenant name for the deployment. The default value is wimax. WiDM.Username. Username for logging into the WiDM Server. Used by provisioning endpoint operations when calling the EndpointOperation service. WiDM.Password. Password for logging into the WiDM Server. Used by provisioning endpoint operations when calling the EndpointOperation service. WiDM.Hostname. Specifies the host name and port for the WiDM Server. Used by provisioning endpoint operations when calling the EndpointOperation service. MDMRootCertificateFile. The path to the root certificate authority file. This is used when provisioning a deviced for HSD, which needs access to a root certificate authority file. WiMAXWorker.Realm. Specifies the realm required to update the user information in the device and AAA server. The realm value provides a namespace for user names, allowing the system to distinguish between users from different operators. 68 Post-installation Configuration FirmwareAssign.Timeout. Sets the timeout period for firmware operations performed through MDM or HDM, in seconds. Setting the JNDI Connection URL To set the JNDI connection URL 1. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 2. In the Domain Structure box on the left, select Services->Messaging->JMS Modules. 3. In the main pane, under JMS Modules, click MDMJMSModule. 4. In the Summary of Resources table, click on MDMServer. 5. Click the Lock & Edit button at the top left. 6. Edit the JND Connection URL field, setting the value to the MDM hostname and port number, using the t3 protocol: t3://<mdmhostname>:<mdmport> 7. Click the Save button. 8. Click the Release Configuration button at the top left. Setting the JNDI Connection URL 69 Creating a initial user in the Subscription Portal Before you can assign profiles, you must create a user for the WiMAX device's MAC ID. Use the reference portal interface to create an initial user. To create an initial user in the subscription portal 1. Open the reference portal. Open the following URL in a browser: http://<mgdhost>.mycompany.com:8001/sp where ■ mgdhost.mycompany.com is the address of the host on which a Managed Server instance is installed. ■ 8001 is the Managed Server clear port. The system displays the Congratulations page. 2. Click the Start button. The system displays the Enter Customer Information page. 3. Enter data in the fields. Enter values for the First Name, Last Name, Account Number, and Device Identifier. For the Device Identifier field, use the MAC ID of your device. 4. Click the Next button. The system displays the Available Services page. 5. Select High Speed Data or VoIP, then click the Next button. The system displays the Provision Device page. 6. Click the Finish button. Note Do not select the Provision My Device Now option. Configuring firmware updates To configure firmware updates, add items to the WiDM database as described in the following procedure. You must configure at least one firmware update to test the system. 70 Post-installation Configuration To configure a firmware update 1. Add the manufacturer and model to the database, if entries for them do not already exist. For the manufacturer, add an entry to the EPMANUFACTURER table. For the model, add an entry to the EPMODEL table. 2. Add a row for the firmware update in the table EPFIRMWARELATESTVERSION. In the ManufacturerID and ModelID columns, use the IDs for the relevant items from the EPMANUFACTURER and EPMODEL tables. In the PlatformID column, use an ID from the EPPLATFORM table. Note By default, there is a row in the EPPLATFORM table with a platform named undefined. You can use that platform value if needed. If there are no entries in the table, create one and use the value undefined in the PLATFORM and VERSION columns. In the IMAGE_EXTERNAL_ID column, provide the target image ID. Editing profile assignments and default values The default values and the profiles that are assigned by the system during Zero Touch activation are stored in the ProvisionEndpoint model, in its HSDData component. The following procedure describes how to change values in the model and make sure the changes are published. Editing the ProvisionEndpoint model 1. In the Model Builder application, open the ProvisionEndpoint model. For information on using Model Builder, see the Model Builder Help. Model Builder is an application you install on your local machine and use to edit models that are then published to the database. 2. In the ProvisionEndpoint model, select the HSDData component. Edit properties in the component as needed. The component includes the following properties: ■ OperatorName ■ H-NSP-ID ■ CAPL_Select_Policy ■ CAPL_Entries Editing profile assignments and default values 71 ■ RAPL_Select_Policy ■ RAPL_Entries ■ PrimarySubscriptionName ■ PrimarySubscriptionActivated ■ Channel_Plan ■ Root_CA 3. Save the ProvisionEndpoint model in Model Builder. 4. Publish the changes using the Configuration Manager. a. Open the following URL in a browser: http://<mgdhost>.mycompany.com:8001/config where ■ mgdhost.mycompany.com is the address of the host on which a Managed Server instance is installed. ■ 8001 is the Managed Server clear port. and log in in using appropriate credentials. The default username and password for the application is configuser/configuser. b. At the upper right of the Configuration Manager window, click the Publish To Server button. Configuring HDM After installing the WiDM server, perform the following steps to set up HDM. To set up HDM after you install the WiDM server and the SMP 1. Copy the .jar files from the HDM release's Integrations\NBI Notification Plugin\lib directory to a directory on the HDM server. 2. Create the following properties using the Server Configuration Console. 72 ■ nbi.notification.plugin.reference.deviceactivationnotification.urls = http://<widm_server_hostname:port>/HDMEventListener/NotificationEventService?WSDL ■ nbi.notification.sender.plugin.name = com.alcatel.hdm.nbi.notification.plugin.ReferenceWebservicesPlugin ■ nbi.notification.sender.plugin.url = jar:file:/<path>/ala-nbi-notificationplugins.jar!/;jar:file:<path_to_staging_directory_on_HDM_server>/axis.jar!/;jar:file:/ <path_to_staging_directory_on_HDM_server>/wsdl4j-1.5.1.jar!/ Post-installation Configuration 3. Log in to hdm using the nbi_user and change the default password. Make sure that password is set in the widm configuration properties Installing licenses The WiDM server uses the Service Management Platform license management scheme. After you install the WiDM server, you must store the licenses for the options you have purchased, using the Configuration Manager application. In addition to licenses required by the Service Management Platform, the following WiDM server components require licenses: ■ WiDM Server ■ Zero Touch WiMAX Activation Template For more information on licenses, see “Understanding licenses” on page 11. To store licenses, see “Storing your WiMAX product license” on page 73. Storing your WiMAX product license Until the WiMAX license is stored, the product is not licensed for use. To store your WiMAX product license 1. From Alcatel-Lucent's Motive Product Group, acquire a valid product license for WiMAX. Typically, the license string is provided in a text file. For example: license.txt 2. Log into the Configuration Manager: Logging into the Configuration Manager URL http://mgdhost.mycompany.com:8001/config Or https://mgdhost.mycompany.com:8002/config User credentials a configuser/configuser The configuser account was created during WiMAX installation. Until reset, the password is the same as the user name. a where: ■ mgdhost.mycompany.com is the address of a load balancer that fronts the cluster of Managed Servers or the host on which a Managed Server instance is installed. Installing licenses 73 ■ 8001 is the clear port. ■ 8002 is the SSL port. An Invalid license page is displayed. Upon each login, the page displays until a valid license is stored. 3. Click OK. 4. On left, click Application Administration. The Application Administration page is displayed with the Application Properties tab in focus. 5. In the License text box, paste a copy of the license string that you acquired in Step 1. 6. Click the Save Changes button. 7. In the upper-right corner, click the Publish to Server button to make the configuration active. Troubleshooting the deployment Use the topics in this section for ideas on how to solve problems with a deployment. Data changes not reflected in the system If you make a change and you do not see the results of your change, try resetting the cache using the Reset Cache option. The cache must be reset after you perform any of the following actions: ■ Change a model or overlay ■ Change the database, by executing a stored procedure ■ Change an environment property Verify environment properties To view environment properties, log in to the Configuration Manager. Select Environment Properties. 74 Post-installation Configuration Publish configuration changes Configuration changes require publishing. This notifies all the objects using configuration information that they should repopulate their internal caches. After you upload a new configuration, be sure to make it the active configuration and publish your changes. Note also that publishing from the Configuration Manager hosted on any server in your cluster updates all servers in the cluster. Publish configuration changes 75 76 Post-installation Configuration 8 (Optional) Deploying the Motive Reporting Application This chapter covers: ■ ■ ■ ■ ■ Understanding the reporting environment Confirming prerequisites for deploying Motive Reporting Configuring the domain for reporting deployment Importing reports Deploying the reporting application 77 Understanding the reporting environment Reporting comprises several components and utilities: ■ A reporting schema that is added to the modeling schema during a WiMAX product installation or upgrade. ■ A BEA WebLogic enterprise application (.ear file) containing EJBs and web applications that implement the report management and viewing functionality. Data to drive these reports is derived from a combination of the reporting database schema and the product-specific database schema. To use Reporting to generate reports for WiMAX products, install the system in the WebLogic Server domain that is running the server runtime environment for the product according to the following sections. Confirming prerequisites for deploying Motive Reporting Before deploying the reporting solution, it is critical to confirm the prerequisites by completing the following procedure. To confirm prerequisites for deploying Motive Reporting 1. Verify that the following are true: The minimum software and hardware are installed for reporting. See the system requirements in the product release notes. The WiMAX product against which to yield reporting is installed. Important By default, the WiMAX product installation loads the reporting schema into the modeling schema. The Motive Reporting application is hosted in the same BEA WebLogic server domain as WiMAX. However, it does not need to be deployed to every Managed Server in the cluster; typically, it is deployed only to one. The Managed Server on which Motive Reporting is deployed does not need to have the core application deployed to it (WiMAX.ear), although it functions properly if the .ear is deployed there. When saving report output to Microsoft Word, PowerPoint or Excel formats, Microsoft Office 2003 or later must be installed to view the result. This is because the output is generated using Microsoft Office XML format, which can be read only by Microsoft Office 2003 or later. 2. Use a schema browser tool to confirm the following: 78 ■ New database tables: REPORT, REPORT_ETL_LOG, REPORT_ETL_TASK, and REPORT_GROUP ■ New database views having the name RPT_* (Optional) Deploying the Motive Reporting Application 3. ■ New database sequences having the name REPORT* ■ New package (stored procedure) named REPORTS_UTIL. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 4. In the Domain Structure box on the left, click Environment->Servers. 5. Stop each of the Managed Servers slated for a deployment of Motive Reporting. For guidance, see the applicable step in “To stop all MotiveSMP servers” on page 99. 6. In the Change Center box on left, click Lock & Edit. 7. For each Managed Server instance slated for a deployment of Motive Reporting, configure the server startup: a. In the main pane, click the name of the Managed Server. b. Click the Configuration tab, and then click the Server Start subtab (on far right). c. In the Arguments field, add one or both of the following arguments if they are not already set. Note that arguments start with the hyphen (-) and are separated with a space character. -Djava.awt.headless=true -Dmotive.appServerName=managedServerName where managedServerName is the name configured for the Managed Server (for example, S_hostname) d. Click the Save button. 8. In upper-left corner under Change Center, click the Activate Changes button. 9. Start the Managed Servers that you stopped in Step 5 and configured in Step 7. For guidance, see the applicable step in “To start all MotiveSMP servers” on page 100. Confirming prerequisites for deploying Motive Reporting 79 10. Continue by following instructions in “Configuring the domain for reporting deployment” on page 80. Configuring the domain for reporting deployment The first step in deploying the reporting solution is to configure the WebLogic Server domain in which the WiMAX product is running. To configure the applicable WebLogic Server domain for reporting Important The Administration Server must be running to complete this procedure. 1. Confirm that the database properties are set correctly: a. From the staging directory in which the WiMAX_solaris.zip file for the WiMAX product was extracted, open the installer.properties file in a text editor. For example: cd /data/staging/wimax vi installer.properties b. Verify that the following properties are set to corresponding values for the WebLogic Server domain in which the WiMAX product is running: domainName beaHome javaHome adminServerHost adminListenPort adminSslListenPort adminAdministrativePort weblogicUsername weblogicPassword clusterName In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. c. Verify that the following properties are set to corresponding values for modeling schema of the running WiMAX product: modeling.db.servername modeling.db.sid modeling.db.username and modeling.db.password modeling.db.port In addition, see “Understanding the installer.properties values” on page 41 for per property guidance. 80 (Optional) Deploying the Motive Reporting Application 2. From the WiMAX staging directory, change to the Reporting directory, and then run the reporting script, as follows: cd /data/staging/wimax/Reporting ./setupSMPReporting.sh Upon completing successfully, the following appears in output: Domain has been configured for reporting 3. Run an SQL script . Connect to the database and execute the SQL script widmreports-core.view.sql. For example: >sqlplus username/password@dbservicename SQL>@widmreports-core.view.sql When the script completes, check the log for any errors. 4. Create a new data source. a. Log into the WebLogic Server Console: i. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. ii. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. b. Click the Lock & Edit button at the top left. c. In the Domain Structure box, select Services->JDBC->Data Sources to display the Summary of JDBC Data Sources page. In the main pane, click the New button. d. On the JDBC Data Source Properties page, enter or select the following information: Name MotiveWiDMReportingJDBCPool JNDI NameDatabase Type motive/jdbc/MotiveWiDMDataSource Configuring the domain for reporting deployment 81 Database Type Oracle Database Driver Oracle's Driver(Thin) Versions:9.0.1,9.2.0,10 Then click the Next button. The system displays the Transaction Options page. e. Select transaction options. ■ Click the Supports Global Transactions check box. ■ Select the Emulate Two-Phase Commit radio button. After selecting these options, click the Next button. The system displays the Connection Properties page. f. Enter values for connection properties. Database Name Enter the net service name (for example, WiDMDB). Host Name Enter the database machine name. Port Enter the database port. The default value is 1521. Database User Name Enter the WiDM application user name (for example, WiDM_ADMIN Password and Confirm Password Enter the password for the database user name. Then click the Next button. The system displays the Test Database Connection page. g. Click the Test Configuration button. h. Click Finish and Activate Changes. Importing reports Use the procedure in this section to import the WiDM reports found in the WiDM\Reporting\Reports directory in your distribution. To load a new or revised report into the Reporting Console, use the Import button on the Manage tab. A report to be imported consists of a .zip format file containing: ■ A .rptdesign file (a report definition XML document) 82 (Optional) Deploying the Motive Reporting Application ■ A .properties file (localizable strings in Java properties file format) For information about these files, see the BIRT documentation [http://www.eclipse.org/birt/phoenix/]. BIRT (Business Intelligence and Reporting Tools) is the Eclipse-based open-source reporting system used to design and create these reports. Note A .zip file that is being imported must not contain more than one .rptdesign file. Additionally, the file name for this .rptdesign file must not have already been used in the context of another report that was previously imported into the system. If the system detects such a condition, it displays an error message indicating the group and display name of that pre-existing report. To import a report 1. From the Manage tab, click Import. The Import Report dialog box is displayed. 2. Click the Browse button next to the Report .zip file field. The Choose file dialog box is displayed. 3. Navigate to and select the .zip file for the report to be imported, and then click Open. 4. Optionally, from the Select a group for the report list, click a report group under which to put the new report. If no report groups have been created, this list is not activated. 5. In the Report Name field, type a name for the report. 6. Optionally, in the Description field, type a description of the report. 7. Click Import. The report is imported. If the report name does not appear immediately in the list on the Manage page, check to see if the report group with which it is associated is selected in the Show Group list, and select it if it is not. Deploying the reporting application To deploy the reporting application 1. Log into the WebLogic Server Administration Console: Deploying the reporting application 83 Logging into the WebLogic Server Administration Console URL https://adminhost.mycompany.com:9001/console User credentials a Either the credentials for the primary administrative user for the WebLogic Server domain in which the product is running or another WebLogic account created for your use. a where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port configured for the Administration Server. If an Option 2 installation, the port is the domain-wide administration port for the Administration Server (for example, 9002). 2. Confirm that each instance of the Managed Server is running: a. On left under Domain Structure, expand Environment, and then click Servers. On right, the Summary of Servers page appears. b. In the table within the State column, confirm that Running appears for each Managed Server. If one or more is not running, restart those instances before continuing. You may need to restart the applicable Node Managers before restarting the Managed Server instances. For guidance, see the applicable steps in “To start all MotiveSMP servers” on page 100. 3. From the WebLogic Server Administration Console, deploy the Motive Reporting application: a. In the Change Center box on left, click Lock & Edit. b. On left under Domain Structure, click Deployments. On right, the Summary of Deployments page appears. c. Under the Deployments table, click the Install button. The Install Application Assistant page appears. 84 d. Next to Location, click the Administration Server host link, navigate to the WiMAX staging directory (for example, /data/staging/wimax), select the smp-reports.ear file, and then click the Next button. e. Select the Install this deployment as an application option, and then click the Next button. f. Select the check box for the applicable cluster, make the applicable selections either to deploy to all servers in the cluster or only to one or more specific server instances, and then click the Next button. g. Optionally, change the default name for the reporting application in the Name field. h. Review the deployment settings, and then click the Finish button. (Optional) Deploying the Motive Reporting Application i. In upper-left corner under Change Center, click the Activate Changes button. j. After the WebLogic Server Administration Console refreshes, continue by refreshing it manually until confirming in the Deployments table that State shows Prepared. k. In the Deployments table, select the check box for the reporting application; then, click the Start button and select Start servicing all requests. A confirmation prompt appears. l. Click Yes. m. Before continuing, ensure the State in the Deployments table shows Active. This may take several minutes, and the confirmation process requires refreshing the WebLogic Server Administration Console page to see any changes. 4. Verify that the Reporting Console is up and running: a. Log into the Reporting Console: Logging into the Reporting Console URL http://myhost.mycompany.com:8001/report-console/ Or, for secure access: https://myhost.mycompany.com:8002/report-console/ User credentials a reportuser/reportuser The reportuser account was created during Motive Reporting installation. Until reset, the password is the same as the user name. a where: ■ mgdhost.mycompany.com is the address of a Managed Server host on which the Motive Reporting application is deployed. ■ 8001 is the clear port. ■ 8002 is the SSL port. b. In the Reporting Console, verify that the following tabs are accessible: View, Manage, and ETL Admin. Once ready to begin using reporting, refer to Chapter 12, “Administering the Motive Reporting Application” on page 117 and in particular the “Managing reporting users” on page 118 section for setting up accounts. In turn, provide the reporting users with login information, and then point them to the following resources: ■ Chapter 13, “WiDM Server Reports” on page 131 Deploying the reporting application 85 ■ 86 (Optional) Deploying the Motive Reporting Application A Uninstalling WiDM Server and the Service Management Platform 87 To manually uninstall WiDM Server and the Service Management Platform from a Solaris host 1. Before uninstalling on the Solaris host: ■ Back up the data in the Service Management Platform OLTP database. ■ Take a backup image of the Motive host. Note If planning to reinstall components after removing some or all of them, it is important to have the backups of the database and all local files and directories. That way, if necessary, you can restore the backup data. 2. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 3. From the WebLogic Server Console, stop all the Managed Servers in the SMPCluster: a. Expand the Environment node, click Clusters, and then select SMPCluster link. The Home > Summary of Clusters > SMPCluster page appears. b. On the Home > Summary of Clusters > SMPCluster page, click the Control tab. c. Select the check box for each Managed Server instance, click the Shutdown drop-down button, and then select Force Shutdown Now. A confirmation appears. d. 88 Click the Yes button. Uninstalling WiDM Server and the Service Management Platform The shutdown process can takes a few minutes, depending on the number of Managed Server instances and other factors. e. 4. In the WebLogic Server Console, refresh the Home > Summary of Clusters > SMPCluster page; then, confirm that SHUTDOWN appears in the State column for each Managed Server instance. From the WebLogic Server Console, stop the Administration Server: a. Expand the Environment node, click Servers, and then select the AdminServer (admin) link. The Summary of Servers > AdminServer page appears. b. On the Summary of Servers > AdminServer page, click the Control tab. c. In the Server Status table (on bottom of page), select the check box for AdminServer (admin), click the Shutdown drop-down button, and then select Force Shutdown Now. A confirmation appears. d. Click the Yes button. A message about shutting down the Administration Server appears. e. 5. Refresh the page to confirm the Administration Server is shut down. On each host in the MotiveSMP domain, do the following: a. Identify any processes that are still running: ps -ef | grep bea b. 6. For each process still running, use the kill -9 command and associated process ID to stop the process. Remove the home installation directory: cd /usr/local rm -r bea 7. On the Administration Server and each Managed Server host, remove the following scripts: a. Remove the link to the Administration Server control script: rm -f /etc/init.d/sv_wlnmd b. Remove the Solaris startup script: rm -f /etc/rc3.d/S98sv_wlnmd c. Remove the Solaris stop script: rm -f /etc/rc3.d/K98sv_wlnmd 89 90 Uninstalling WiDM Server and the Service Management Platform Administration This part covers: ■ Chapter 9, “Product Versions and Licenses” ■ Chapter 10, “Administering Devices” ■ Chapter 11, “Administering the WiDM Server” ■ Chapter 12, “Administering the Motive Reporting Application” ■ Chapter 13, “WiDM Server Reports” ■ Chapter 14, “Maintaining the Modeling Database” ■ Appendix B, “Creating Additional JDBC Data Sources” 9 Product Versions and Licenses This chapter covers: ■ ■ Checking product versions Managing WiMAX licenses 93 Checking product versions For versions of the WiDM Server, Zero Touch for WiMAX template, or the Service Management Platform versions, see the VERSION_INFO table in the database. Managing WiMAX licenses A deployment-specific WiMAX license is validated for two major components in the platform, the Configuration Manager and the model/overlay processor (PARP). Until storing a valid license in the modeling schema, your product is not licensed. For instructions, see “To store your WiMAX product license” on page 73. 94 Product Versions and Licenses 10 Administering Devices This chapter covers: ■ Accessing the subscription portal 95 The topics in this chapter provide information for administering WiMAX devices. Accessing the subscription portal The subscription portal allows end users to register devices and provision them. The WiDM server comes with a reference subscription portal. To access the subscription portal • 96 Open the following URL in a browser: http://<mgdhost>.mycompany.com:8001/sp where ■ mgdhost.mycompany.com is the address of the host on which a Managed Server instance is installed. ■ 8001 is the Managed Server clear port. Administering Devices 11 Administering the WiDM Server This chapter covers: ■ ■ ■ ■ ■ ■ ■ ■ Logging into WebLogic Server Console Using the Configuration Manager Restarting servers Adding new managed servers Deleting subscriber records Configuring security Using health check features If a server is down 97 Logging into WebLogic Server Console To log in to the WebLogic Server Console: • Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. Using the Configuration Manager The Configuration Manager is a web console application that allows you to set environment properties, configure mappings between test modules and model/overlay pairs, and create test module groups. To access the Configuration Manager: Open the following URL in a browser: http://<mgdhost>.mycompany.com:8001/config where ■ mgdhost.mycompany.com is the address of the host on which a Managed Server instance is installed. ■ 8001 is the Managed Server clear port. and log in in using appropriate credentials. The default username and password for the application is configuser/configuser. For more information on using the Configuration Manager, see the Configuration Manager Help. 98 Administering the WiDM Server Restarting servers In some cases, server administration requires a restart of all servers in the MotiveSMP domain. The process requires stopping the server types in a particular order, and then starting them in a particular order. Use the following procedures to stop and start all servers: ■ “To stop all MotiveSMP servers” on page 99 ■ “To start all MotiveSMP servers” on page 100 To stop all MotiveSMP servers 1. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 2. From the WebLogic Server Console, stop all the Managed Servers in the SMPCluster: a. Expand the Environment node, click Clusters, and then select SMPCluster link. The Home > Summary of Clusters > SMPCluster page appears. b. On the Home > Summary of Clusters > SMPCluster page, click the Control tab. c. Select the check box for each Managed Server instance, click the Shutdown drop-down button, and then select Force Shutdown Now. A confirmation appears. d. Click the Yes button. Restarting servers 99 The shutdown process can takes a few minutes, depending on the number of Managed Server instances and other factors. e. 3. In the WebLogic Server Console, refresh the Home > Summary of Clusters > SMPCluster page; then, confirm that SHUTDOWN appears in the State column for each Managed Server instance. From the WebLogic Server Console, stop the Administration Server: a. Expand the Environment node, click Servers, and then select the AdminServer (admin) link. The Summary of Servers > AdminServer page appears. b. On the Summary of Servers > AdminServer page, click the Control tab. c. In the Server Status table (on bottom of page), select the check box for AdminServer (admin), click the Shutdown drop-down button, and then select Force Shutdown Now. A confirmation appears. d. Click the Yes button. A message about shutting down the Administration Server appears. e. 4. Refresh the page to confirm the Administration Server is shut down. On each host in the MotiveSMP domain, do the following: a. Identify any processes that are still running: ps -ef | grep bea b. For each process still running, use the kill -9 command and associated process ID to stop the process. To start all MotiveSMP servers 1. Start the Administration Server: • From the Administration Server host, run the following commands: cd <beaHome>/user_projects/domains/<YourDomain>/bin ./startWebLogic.sh & In output, the following confirmation should appear: <Server state changed to RUNNING> <Server started in RUNNING mode> 2. Log into the WebLogic Server Console: a. 100 Go to the following URL: Administering the WiDM Server https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 3. Start the Node Manager processes by completing the following steps for each Managed Server instance: a. On the Managed Server host, run the following commands: cd /usr/local/bea/weblogic92/server/bin ./startNodeManager.sh & In output, the following confirmation should appear: <Data Time> <INFO> <Secure socket listener started on port 5556> where 5556 is the Node Manager port on this host. b. 4. After the confirmation appears, press ENTER, and then exit the shell formally (for example, with an exit command) without closing the window first. Start all the Managed Servers in the SMPCluster: a. Expand the Environment node, select the Clusters node, and then select the SMPCluster link. The Summary of Clusters > SMPCluster page appears. b. On the Summary of Clusters > SMPCluster page, click the Control tab. c. Select the check box for each Managed Server instance, and then click the Start button. A confirmation appears. d. Click the Yes button. e. Refresh the page until Running appears for each instance in the State column. Restarting servers 101 Adding new managed servers If you add a new managed server to the system, you must perform the following steps to ensure that the Motive Reporting console can display reports for the system: ■ Run the setup_weblogic.sh script (provided with MotiveReporting). For details, see the Motive Reporting Deployment Guide. ■ If you did not deploy Motive Reporting to the cluster, then you must also manually deploy Motive Reporting to the new managed server if you want it to be deployed there. Deleting subscriber records To remove subscribers from the system, delete them from the DVSUBSCRIBER table using any database tool. Referential integrity constraints in the database cause the rest of the data related to the subscriber to cascade delete. Configuring security You configure the applications and operations that a user can access by setting up groups, users, and roles in the WebLogic Server Console, and then mapping actions to user roles in Configuration Manager. About security configuration To control which applications and operations a user can access, you must configure users, groups, and roles using the WebLogic Server Console and the Configuration Manager, as follows: ■ You create users, groups, and roles within WebLogic Server Console, and assign users and roles to groups within it. ■ Roles provide access to specific applications and operations. ■ To give a particular user a particular role, assign the user to a group that has the role. You cannot assign roles directly to users. If necessary, create a group and assign the role to it, then assign the user to the group. ■ A user can be a member of several groups, and acquires the roles of all of the groups he is a member of. ■ Certain default roles control access to the web applications. Predefined groups exist to allow you to assign these roles to users. ❐ 102 To grant access to the Customer Service Console, assign a user to the SV_Console group, which has the SV_Console role. Administering the WiDM Server ■ ❐ To grant access to the Configuration Manager, assign a user to the SV_ConfigurationManager group, which has the SV_ConfigurationManager role. ❐ These roles are the minimum roles required to use the applications. Other roles may be required to enable specific operations. You control which operations a user can access by mapping roles to operations in the Configuration Manager: ❐ A role that you want to use to discriminate amongst operations must first be listed in the Application Roles field on the Application Properties tab of the Application Administration section of the Configuration Manager. ❐ To discriminate amongst different users, create additional roles in the WebLogic Server Console and assign them to groups (and assign the relevant users to the groups). Then map actions to the roles as described in “Enabling and disabling device operations by user role” on page 108. ❐ To enable/disable certain Customer Service Console operations for all users, use the default SV_User role. Default security objects This section provides a reference to the default users, groups, and roles provided with the system and shows how they are configured to provide access to test modules. Users Each of the default users is assigned group memberships which provide specific permissions to the user. Each group corresponds to a role, which provides specific permissions in the system. For more information on roles, see “Roles and Groups” on page 104. Note The default users have passwords that are the same as their usernames; the password for configuser is configuser. Change these passwords during deployment. Default users User Group memberships configuser SV_ConfigurationManager consoleuser SV_Console, SV_User, SV_Admin, Globecom webserviceuser SV_GetTestGroups, SV_ExecutePARPRequest, EndpointService servicepolicyuser SMP_ServicePolicy Default security objects 103 Roles and Groups The WebLogic Server Console assigns roles through groups, so to assign a user a role, you must make the user a member of a group that has that role. In the default configuration, a group of the same name as each role exists, and is assigned that role, to make it simple to assign individual roles to users. Through the Configuration Manager, several of the roles are assigned to multiple test modules, providing permission to execute them. You can use the Configuration Manager to edit which roles can access which test modules. For more information on the test modules and the roles that are initially assigned to them, see “Test modules” on page 105. Default roles Role Group Provides permission to SV_Console SV_Console Access the Customer Service Console SV_ConfigurationManager SV_ConfigurationManager Access the Configuration Manager SV_User SV_User Access CSC operations. SV_Tier1 SV_Tier1 SV_Tier2 SV_Tier2 SV_NOC SV_NOC SV_Admin SV_Admin Initially, all of these roles are assigned to all of the test modules....so despite name differences like "User" and "Admin", they provide the same access. You can edit the test modules in Configuration Manager to create roles with more limited access, by deleting a role from every test module that you want to prevent it from accessing. SV_GetTestGroups SV_GetTestGroups Use the GetTestGroups web service SV_EndpointService SV_EndpointService Use the EndpointService web service SV_ExecutePARPRequest SV_ExecutePARPRequest Use the ExecuteParpRequest web service SV_HealthCheck SV_HealthCheck Run the HealthCheck SMP_ServicePolicy SMP_ServicePolicy Run service policies Globecom Globecom Use default tenant Globecom and view its data. This is the default tenant role; you must create similar roles for each tenant in the system. 104 Administering the WiDM Server Test modules The following table shows which roles are assigned to each test module. If a user has any of the listed roles, the user can execute the test module. In the initial configuration, most test modules are assigned all of the example user roles (SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User). If you want to limit user access to certain test modules (and thereby limit access to CSC operations), you can make one of the roles more specific: ■ Select a role (such as SV_Tier1) and remove it from certain test modules. Use the Configuration Manager to remove the role from all the test modules you do not want that role to be able to execute. ■ Select a username and make sure it has the more specific role's group (SV_Tier1) and none of the other groups that would grant access to test modules (SV_Admin, SV_NOC, SV_Tier2, SV_User). Inspect any other groups that the user is a member of, recalling that if the user has any of the roles associated with a test module, then the user can execute that test module. A few test modules are assigned the SV_Console role. This is intended to confer the right to use basic CSC functionality, so any user of the CSC must be a member of the SV_Console group, and the core test modules, which have the SV_Console role, must retain that role for the application to work properly. If you remove the SV_Console role from any of these test modules, users will experience problems using the CSC. Default test modules Test Module Default Roles AppAvailable SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User AppInstall SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User BookmarkGet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User BookmarkProvision SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User BookmarkSet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User Carriers SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User Complete Configuration SV_Console DeviceInfo SV_Console DeviceStatus SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User EmailGet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User EmailProvision SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User EmailSet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User EnableClientSMS SV_Console FileManager SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User Default security objects 105 Default test modules (continued) Test Module Default Roles FMCSendSMS SMP_ServicePolicy FMCService SV_Console HDMSubscriberAdd SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User HDMSubscriberRemove SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User HDMWiFiGet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User HDMWiFiSet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User HealthCheck SV_HealthCheck Lock SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MDSAvailableBackups SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MDSBackup SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MDSBootstrap SV_Console MDSCarriers SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MDSRestore SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MMSGet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MMSProvision none MMSSet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MobileDeviceAdd SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MobileDeviceBootstrap SV_Console MobileDeviceDelete SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MobileDeviceReBootstrap SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User MobileService SV_Console NAPCPProv SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User NAPGet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User NAPProvision SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User NAPSet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User ProcessList SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User Reboot SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User RemoteControl SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User ServiceAdd SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User 106 Administering the WiDM Server Default test modules (continued) Test Module Default Roles SMS SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User SubscriberAdd SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User SubscriberInitialization SV_Console TestConnection SV_Console Unlock SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User WiFiGet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User WiFiProvision SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User WiFiSet SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User Wipe SV_Admin, SV_NOC, SV_Tier1, SV_Tier2, SV_User Setting up a new user To configure a new user for the system, determine the applications and operations the user should be able to access, configure the user's group memberships in the WebLogic Server Console, then add the new user as a CSR to the CSC database. Setting up a new user 1. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. Setting up a new user 107 2. Within WebLogic Server Console, create the user. a. From the Domain Structure box, select Security Realms b. From the table, select myrealm c. Select the Users and Groups tab. d. Click the New button. e. Fill out the User Properties form and click the OK button. Note The user name must be 15 characters or less. 3. Assign the user to relevant groups. For example: ■ To grant access to the Customer Service Console, assign a user to the SV_Console group, which has the SV_Console role. ■ To grant access to the Configuration Manager, assign a user to the SV_ConfigurationManager group, which has the SV_ConfigurationManager role. ■ To grant the ability to run service policies, assign a user to the SMP_ServicePolicy group. ■ To grant the ability to use the NBI web services (the executePARPRequest and getTestGroups services), assign the user to the SV_ExecutePARPRequest group. ■ To grant access to a particular tenant's customer data, assign the user to at least one tenant group. ■ Add any other appropriate groups. For example, the SV_User group is the default group for configuring access to Customer Service Console operations for CSRs. Enabling and disabling device operations by user role You control which operations a user can access by mapping roles to actions in the Configuration Manager. ■ To enable/disable operations for a single user, first create a role for that one user in the Weblogic Administration Console, assign the role to a group, and assign the user to that group. Then configure the operations assigned to the role using the procedure below. ■ To enable/disable operations for a class of users, determine the relevant role by inspecting the roles assigned to groups in WebLogic Server Console. For example, the SV_User role is provided for controlling which Customer Service Console operations are available to all CSC users. This role is intended to be assigned to all CSRs. 108 Administering the WiDM Server To enable a role for use with actions • Add the role to the comma-separated list in the Application Roles field on the Application Properties tab of the Application Administration section of the Configuration Manager. To enable/disable an operation for a user role 1. In Configuration Manager, select Test Module Administration. 2. Select the test module named for the operation you want to enable/disable, then click the Edit button. For example, to enable e-mail provisioning, select the EmailProvision test module. 3. Select the User Roles tab. 4. Add or remove the user's role in the Role Name list. ■ To enable the user to use the operation, add the user's role to the list by selecting it in the Available Roles list, then clicking the right arrow button to move it to the Assigned Roles list. ■ To prevent the user from using the operation, remove the user's role from the Assigned Roles list by selecting it and then clicking the left arrow button. Using health check features The system includes two monitoring tools: health checks that you can perform to determine the status of the system. ■ Lightweight. fashion. ■ Heavyweight. The heavyweight health check executes a synthetic transaction using the SMP model/overlay web service. Through the model/overlay infrastructure, the test can be extended to check additional operations. The lightweight health check is a quick operational test that can be accessed frequently in heartbeat Lightweight health check The lightweight health check provides a quick operational test. You can set up scripts to access the health check frequently to get a system heartbeat. To access the health check, use the following URL: http://<server>:<port>/config/HealthCheck.hc?mode=lightweight When you access the URL, the system returns the following results: ■ A header variable named healthcheckstatus with a value of success or failure. You can use this header to programmatically determine the success or failure of the health check. Using health check features 109 ■ If the health check succeeds, it returns the following XML: <?xml version="1.0" encoding="UTF-8" ?> <lightweightresponse> <p>Succesfully tested connection to modeling database</p> <b>TestResult: OK</b> </lightweightresponse> ■ If the health check fails, it returns the following XML: <?xml version=\"1.0\" encoding=\"UTF-8\" ?> "); <HealthCheckFailure><b>TestResult: Failure</b> <p>Failure connecting to modeling ↲ database</p> </HealthCheckFailure> A success result means the following: ■ The WebLogic Server Console is running and operational. ■ The console application is deployed and running. ■ The JNDI reference to JDBC/Modeling is present. ■ The system was able to get a working database connection (tested via a query to the DUAL table). It also implies that: ■ The WebLogic application server is available for use by the SMP and console applications. ■ The database used by the models and web services is set up and operational. Heavyweight health check The heavyweight health check runs a transaction using the SMP model/overlay web service. Because it uses the model/overlay infrastructure, the test can be extended to check additional operations. For example, you can use this feature to check back-end systems, such as to verify that specific databases are running. Also, by running a full model/overlay pair, the test is a more complete test than the lightweight health check. To access the health check • Access the following URL: http://<server>:<port>/config/HealthCheck.hc?mode=heavyweight Note You can add a optional timeout parameter, to cause the request to time out after the specified number of seconds (add &timeout=40000 to time out after 4000 second). The default value is 120 (2 minutes). Any timeout value specified on the URL overrides the default, which is set via an application property (see “Configuring the heavyweight health check” on page 111). 110 Administering the WiDM Server When you access the URL, the system returns an HTML page and a header variable: ■ The header variable, named healthcheckstatus, has a value of success or failure. You can use this header to programmatically determine the success or failure of the health check. The value of the variable is determined by whether the result code bHealthCheckSucceeded returns true or false. ■ The returned HTML has the following characteristics: ❐ It includes a box with a simple status message (“The HealthCheck succeeded.” or “The HealthCheck failed.” ❐ If there are Discovery or Evaluation error messages, they are displayed below the status message. ❐ If there are no errors, it displays the properties returned by the Health Check below the status message. The returned HTML is formatted via an XSL file. To select which XSL file to use to format the HTML, or to set the timeout, see “Configuring the heavyweight health check” on page 111. Implications of a successful heavyweight health check When the heavyweight health check succeeds, it indicates the following about the managed server on which it is run: ■ The WebLogic application server is available for use by the SMP layer and console application. ■ The SMP layer is operational, including models and overlays being executable. ■ The Weblogic JMS configuration is correct and functioning properly If the out of box content is being used, then a successful health check also indicates that the modeling database is operational and reachable. Configuring the heavyweight health check You can use two Application Properties in the Configuration Manager to configure the health check. See “Using the Configuration Manager” on page 98 for instructions on accessing the Configuration Manager. Health Check Timeout (healthCheckTimeout). Sets the amound of time in seconds that the system waits for a health check to complete before returning a timeout error. If you access the URL with a timeout parameter (as described in “Heavyweight health check” on page 110), the parameter's value overrides the application property. Health Check XSL (healthCheckXSL). The path to the XSL file to be used to format the XML returned by the health check, converting it to HTML for display purposes. The default value for this property points to the default XSL file provided with the system, HealthCheckDisplay.xsl. This value can be specified either as complete URL (including http:// or https://) or a relative path for an XSL file within the Configuration Manager application. (If http:// is used, the resource must not require authentication.) Heavyweight health check 111 Note If healthCheckXSL is not defined, or the system cannot load the specified file, the system returns the raw XML returned by the health check. If you want to process the XML with your own code, delete the healthCheckXSL property. The returned XML is described in “XML returned by the heavyweight health check” on page 112. Understanding and/or modifying the default heavyweight health check The out-of-box heavyweight health check runs a test module named HealthCheck which computes the number of models in the system and returns that value as a property. The test module runs a model and overlay named HealthCheck. The overlay is of the HealthCheck type and returns the following values: bHealthCheckSucceeded (Boolean) . Returns true if the overlay author determines the system to be healthy. healthDescription (String) . Description of the HealthCheck status. DetailedInformation (Map) . Detailed information about the health status in the form of name/value pairs. A test module to be used with the heavyweight health check must fulfill the following conditions: ■ Have the name “HealthCheck”. ■ Have the SV_ConfigurationManager (the role that grants access to resources in the Configuration Manager web application). XML returned by the heavyweight health check The health check can return XML of the following types: ■ Standard execution result XML. The following is an example of a successful run. If the bHealthCheckSucceeded value is false, however, or if OverlayErrors are returned, the default XSL reports this as a failure. <?xml version="1.0" encoding="UTF-8" ?> <PARPResponse> <OverlayExecutionResult ↲ overlayID="HealthCheck" cached="0" executeDateUTC="February 26, 2008 4:32:39 PM GMT" ↲ overlayType="HealthCheck"> <ExecutionResultXML> <OverlayResults> <Result name=↲ "bHealthCheckSucceeded"> <ResultValue name="bHealthCheckSucceeded"> <value type="string">true</value> </ResultValue> <ResultActions /> </Result> <Result name="DetailedInformation"> <ResultValue name="DetailedInformation" type="map"> <PropertyResult name="Number of ↲ Models"> <value type="string">79</value> </PropertyResult> 112 Administering the WiDM Server </ResultValue> <ResultActions /> </Result> <Result name="healthDescription"> <ResultValue name="healthDescription"> <value type="string">HealthCheckOverlay working correctly</value> </ResultValue> <ResultActions /> </Result> </OverlayResults> <OverlayActions /> <OverlayErrors type="EVALUATION" /> <OverlayErrors type="DISCOVERY" /> </ExecutionResultXML> </OverlayExecutionResult> </PARPResponse> ■ Fatal exception XML, indicating the test module could not be run. <?xml version="1.0" encoding="UTF-8" ?> <PARPResponse> <RequestError errorID=↲ "INSUFFICIENT_ACCESS_RIGHTS" code="102" requestTypeID="ExecuteModel:executeOverlay"> <ErrorText>Current user does not have sufficient access rights to perform the ↲ requested operation.</ErrorText> <RequestBody version="1"> <ExecuteModel modelID="HealthCheck" /> </RequestBody> </RequestError> </PARPResponse> ■ Timeout error. <?xml version=\"1.0\" encoding=\"UTF-8\" ?> "); <HealthCheckFailure><b>TestResult: Failure</b> <p> Timed out executing HealthCheck ↲ test module</p> </HealthCheckFailure> If a server is down This section describes how the system responds when one of the servers in the system goes down. This section assumes that the system is composed of multiple CSC and MDM managed servers (organized as clusters and accessed through load balancers) as well as multiple tunnel servers (the recommended configuration). CSR responses when a server is down In general, from the CSR's point of view, there is no issue when a server goes down unless the CSR has already connected to the server (if a server goes down before a CSR connects to it, the load balancer directs requests to other servers and the CSR does not notice any outage). If a server goes down after the CSR connects to it, the CSC may return connection errors or display a blank page. In such cases the CSR should respond as follows: If a server is down 113 ■ Repeat the failing action and/or try a different action. ■ If that fails, the CSR should log out or close the browser window, then log back in. ■ If that fails, the CSR should notify an administrator. Server down scenarios In the scenarios described below, the current server is the one most recently selected for the CSR by the load balancer. CSR action Problem CSR has logged in, but no operation is currently pending Current CSC Managed Server goes down before an The next time the CSR attempts operation is requested an operation, the CSC displays a connection error and asks the CSR to close the browser and log in again, at which point the system connects to a different server and resumes operation. CSR has logged in and started an Current CSC Managed Server goes down during operation, but operation has not the operation yet completed Result The operation that is in progress does not complete. If the CSR selects a different operation, the system asks the CSR to log in again, then displays a blank page. Action: The CSR must close the browser and then log in again. CSR has logged in, but no operation is currently pending Current MDM Managed Server goes down before The next operation the CSR an operation is requested attempts fails over to a different MDM server seamlessly; no error is displayed and the operation completes without issue. CSR has logged in and started an Current MDM Managed Server goes down during The system displays an error operation, but operation has not the operation similar to this one: “An error yet completed occurred while performing the operation.” Action: The CSR should repeat the operation, or close the browser window and log in again. The operation is restarted by a different MDM server. When the downed server is restarted, it 114 Administering the WiDM Server CSR action Problem Result does not attempt to complete unfinished operations. A series of MDM bulk device Current MDM Managed Server goes down during The incomplete operations are handed off to another available management operations has been the series MDM server. started CSR has initiated an operation which communicates with a tunnel server Current tunnel server goes down after connection When a tunnel server goes down made after a CSR has connected to it (whether or not the tunnel server has returned any information to the CSR), the next operation that the CSR performs triggers the test connection flow and the operation continues after the flow is completed. Behind the scenes, the system has connected the CSR to a different available tunnel server. For example, if the CSR uses the file manager operation to view folders on the mobile device, and the tunnel server goes down, the CSR does not notice this until he attempts to change or refresh the view (actions that require new data from the device). At that point, the system starts the test connection flow. If the tunnel server goes down while the CSR is using the Remote Control feature, the remote control applet returns a Java I/O exception. Any CSR action WebLogic Administration Server goes down The loss of the administration server has no effect on CSC operations; the managed servers continue to function. However, server administration must be done via command line until the administration server is restarted. Server down scenarios 115 116 Administering the WiDM Server 12 Administering the Motive Reporting Application This chapter covers: ■ ■ ■ ■ Logging into the Reporting Console Managing reporting users Configuring logging for the reporting applications Using the provided reports 117 Logging into the Reporting Console The Reporting Console is the user interface that enables you to view, print, import, and export reports and manage groups of reports. After the Reporting application is deployed, you can log into the console. For guidance, use the information in the following table: Logging into the Reporting Console URL http://myhost.mycompany.com:8001/report-console/ Or, for secure access: https://myhost.mycompany.com:8002/report-console/ User credentials a reportuser/reportuser The reportuser account was created during Motive Reporting installation. Until reset, the password is the same as the user name. a where: ■ mgdhost.mycompany.com is the address of a Managed Server host on which the Motive Reporting application is deployed. ■ 8001 is the clear port. ■ 8002 is the SSL port. Managing reporting users Reporting user management is conducted through the applicable Security Realms interfaces in the WebLogic Server Administration Console. In general, it is recommended to create additional users and/or groups first, and then to associate the applicable reporting roles to the new groups. The role association grants group members particular reporting privileges. For example, you may want to create a group that has report reading privileges (conferred by the UI_REPORT_READ role) and no other privileges. For information about the default roles, groups, and users for reporting, see the following tables: Default roles added with Motive Reporting application Role Required Permissions UI_ETLADMIN_EXECUTE Refresh ETL report data. UI_ETLADMIN_READ View ETL reports. 118 Administering the Motive Reporting Application Default roles added with Motive Reporting application (continued) Role Required Permissions UI_REPORT_DELETE Delete reports. UI_REPORT_EDIT Import reports and manage report groups. UI_REPORT_EXPORT Download report .zip files. UI_REPORT_READ View reports and report groups. Default group/role associations added with Motive Reporting application Group Associated rolesa SV_ReportManager Each of the Motive Reporting roles, including: UI_ETLADMIN_EXECUTE UI_ETLADMIN_READ UI_REPORT_DELETE UI_REPORT_EDIT UI_REPORT_EXPORT UI_REPORT_READ a For descriptions, see “Default roles added with Motive Reporting application” on page 118. Default user/group associations added with Motive Reporting application User Associated groups reportuser SV_ReportManager For detailed instructions on user management, see the resources referenced in the following. Configuring roles To view role associations through the WebLogic Server Administration Console, navigate to domainName->Security Realms->myrealm->Roles and Policies->Global Roles->Roles. For complete guidance on configuring role associations in the WebLogic Server Administration Console, see the related topics in Oracle BEA's 9.2 version of Administration Console Online Help: ■ Manage Security Roles [http://e-docs.bea.com/wls/docs92/ConsoleHelp/taskhelp/security/ManageSecurityRoles.html ] ■ Modify Groups [http://edocs.bea.com/wls/docs92/ConsoleHelp/taskhelp/security/ModifyGroups.html] Configuring roles 119 Configuring groups To view and modify group configuration, log into the WebLogic Server Administration Console and navigate to domainName->Security Realms->myrealm->Users and Groups->Groups. For complete guidance on configuring groups, see Modify Groups [http://edocs.bea.com/wls/docs92/ConsoleHelp/taskhelp/security/ModifyGroups.html] in Oracle BEA's 9.2 version of Administration Console Online Help. Configuring users To view user configuration from the WebLogic Server Administration Console, navigate to domainName->Security Realms->myrealm->Users and Groups->Users. For complete guidance on configuring users, see Modify Users [http://edocs.bea.com/wls/docs92/ConsoleHelp/taskhelp/security/ModifyUsers.html] in Oracle BEA's 9.2 version of Administration Console Online Help. Configuring logging for the reporting applications This section describes how to configure log levels and locate log files for the reporting application. Important Do not turn up log levels globally across the cluster of Managed Servers. Enable log levels only for the server on which Motive Reporting is deployed. Turning on verbose log levels may affect performance and should be done only in consultation with your Reporting representative and application administrators. Unless otherwise noted, valid values for log properties from most verbose to least are: DEBUG or ALL, INFO, WARN, and OFF ERROR, FATAL, Supported log levels ALL or DEBUG Writes all trace messages to the applicable log file, including debugging, informational, warning, error, and critical failure messages. Debug messages are intended to provide detailed information about events useful for debugging an application. INFO Writes informational, warning, error, and critical failure messages to the applicable log file. Info messages are intended to summarize the status of the application. WARN Writes warning, error, and critical failure messages to the applicable log file. Warn messages are intended to document potentially harmful events. 120 Administering the Motive Reporting Application ERROR Writes error and critical failure messages to the applicable log file. Error messages are intended to document events that are problematic yet may allow an application to continue running. FATAL Writes only critical failure messages to the applicable log file. Fatal messages are intended to document events that cause the application to stop running. OFF Turn offs the writing of all log messages, regardless of the level of messages. Logging for the Reporting Console and related services To adjust the log level for a server To adjust the log level (turning logging on or off) for the Reporting Console, edit the Server Start arguments in the WebLogic Server Administration Console for each Managed Server that is running the console to specify a log level and log file location, as described below. 1. Log into the WebLogic Server Administration Console: Logging into the WebLogic Server Administration Console URL https://adminhost.mycompany.com:9001/console User credentials a Either the credentials for the primary administrative user for the WebLogic Server domain in which the product is running or another WebLogic account created for your use. a where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port configured for the Administration Server. If an Option 2 installation, the port is the domain-wide administration port for the Administration Server (for example, 9002). 2. In the Change Center box on left, click Lock & Edit. 3. On the left, select Environment->Servers. 4. Select the server name. The Configuration tab is selected by default. 5. Click the Server Start subtab. 6. In the Arguments field, add the following values: Logging for the Reporting Console and related services 121 -Dmotive.service.reports.logLevel=loglevel -Dmotive.reports.logLevel=loglevel -Dweblogic.Stdout="/usr/local/bea/logs/managedServerName.stdout.log" -Dweblogic.Stderr="/usr/local/bea/logs/managed_server_name.stderr.log" where ■ ■ ■ loglevel is one of the log levels described in Supported log levels on page 120. By default, the logging level for the Reporting Console is WARN. /usr/local/bea is the BEA_HOME directory in which WiMAX is installed. managedServerName is the name of the Managed Server on which Motive Reporting is deployed. The arguments affect logging written from EJBs, report-console, and other Motive components to the specified files in the BEA_HOME/logs directory. 7. In upper-left corner under Change Center, click the Activate Changes button. 8. Stop and restart the Managed Servers on which the Reporting Console is deployed. ■ ■ For Option 1 installations, see: ❐ “To stop all MotiveSMP servers” on page 99 ❐ “To start all MotiveSMP servers” on page 100 For Option 2 installations, see the product documentation associated with the existing domain in which WiMAX is installed. Logging for the BIRT engine You can also log event information from the third-party BIRT [http://www.eclipse.org/birt] engine. report-viewer.war/WEB-INF/web.xml To configure the logging level for the BIRT engine (report viewer) 1. From the Administration Server host, extract the report-viewer.war/WEB-INF/web.xml file from the smp-reports.ear file. For example: cd /data/staging/wimax jar -xf smp-reports.ear report-viewer.war jar -xf report-viewer.war WEB-INF/web.xml where /data/staging/wimax is the staging directory in which the WiMAX_solaris.zip was extracted. 2. 122 Configure the log level: Administering the Motive Reporting Application a. Using a text editor, open the WEB-INF/web.xml file, and then locate the following source: <!-- Report engine log level --> <context-param> <param-name>BIRT_VIEWER_LOG_LEVEL</param-name> <param-value>WARNING</param-value> </context-param> b. In the param-value element, change the log level currently set to a more or less verbose level as applicable. Unless otherwise changed, the log level is set to WARNING by default. BIRT Engine log levels From least verbose to most, the supported log levels are: OFF Turn offs the writing of all log messages, regardless of the level of messages. SEVERE Writes only severe messages to the applicable log file. Severe messages are intended to document events that prevent normal program execution. WARNING Writes severe and warning messages to the applicable log file. Warning messages are intended to document events that are potentially problematic. INFO Writes informational, warning, severe messages to the applicable log file. Info messages are intended to summarize significant events. CONFIG Writes configuration, informational, warning, severe messages to the applicable log file. Config messages are intended to summarize static configuration information that may help in debugging issues with particular configurations. FINE, FINER, and FINEST Writes detailed tracing messages in addition to configuration, informational, warning, severe messages to the applicable log file. The fine, finer, and finest messages are intended for extremely detailed tracing of BIRT engine events with FINEST being the most verbose of the three levels. c. 3. Save the changes to the WEB-INF/web.xml file. Re-package the report-viewer.war file to include the updated WEB-INF/web.xml file; then, re-package the smp-reports.ear file to include the updated report-viewer.war file. For example: jar -uf report-viewer.war WEB-INF/web.xml jar -uf smp-reports.ear report-viewer.war 4. To implement the changes, continue with the “To re-deploy the reporting application” on page 124 procedure. Logging for the BIRT engine 123 To re-deploy the reporting application 1. Log into the WebLogic Server Administration Console: Logging into the WebLogic Server Administration Console URL https://adminhost.mycompany.com:9001/console User credentials a Either the credentials for the primary administrative user for the WebLogic Server domain in which the product is running or another WebLogic account created for your use. a where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port configured for the Administration Server. If an Option 2 installation, the port is the domain-wide administration port for the Administration Server (for example, 9002). 2. In the Domain Structure box on left, click Deployments. The system displays the Summary of Deployments page. 3. In the Deployments table, select the check box next to the reporting application. 4. Click Stop->When work completes, and then click the Yes button. 5. Before continuing, ensure the State in the Deployments table shows Prepared. This may take several minutes, and the confirmation process requires refreshing the WebLogic Server Administration Console page to see any changes. If the process appears to hang, click Stop->Force Stop now. 6. In the Change Center box on left, click Lock & Edit. 7. In the Deployments table, select the check box next to the reporting application. 8. Click the Update button. 9. Verify the path to the application smp-reports.ear file. If you need to change it, click the Change Path button. 10. Click the Next button. 11. Click Finish. 12. In upper-left corner under Change Center, click the Activate Changes button. 13. In the Deployments table, select the check box for the reporting application; then, click the Start button and select Start servicing all requests. 124 Administering the Motive Reporting Application A confirmation prompt appears. 14. Click Yes. 15. Before continuing, ensure the State in the Deployments table shows Active. This may take several minutes, and the confirmation process requires refreshing the WebLogic Server Administration Console page to see any changes. Using the provided reports Understanding the provided reports In the following table, review information about each of the WiMAX-provided reports. Reports provided with WiMAX Report name Description Sorted by... Cases per Account Lists how many CSR contacts Account number (cases) have occurred for each account number; use the report to track which account numbers require the most service. casesPerAccount.zip Case Length Minimum, maximum and average case length within the CSC for each CSR. caseLength.zip Cases per CSR The number of cases per CSR CSR name casesPerCSR.zip Actions Taken by Type Lists each CSC operation and Action name shows how many times each one occurred (as well as how often the operations succeeded or failed). Covers Gets, Sets, Provision, Security operations, Backup, Restore, Application Installations. actionsTakenByType.zip Action Duration For each CSC operation, Action name shows the average length of the operation, as well as actionsDuration.zip CSR name Filename Using the provided reports 125 Reports provided with WiMAX (continued) Report name Description Sorted by... Filename averaging successes and failures. Reports the number of Execution Date endpoint operations executed during a given time period. Operation Execution operationExecution.zip Publishing and viewing the provided reports You need a report group in which to publish a report. As a result, create a group for the WiMAX reports if one is not yet created. In turn, conduct “To publish a provided report” on page 127, and then “To view a provided report” on page 128. To create a report group 1. Log into the Reporting Console: Logging into the Reporting Console URL http://myhost.mycompany.com:8001/report-console/ Or, for secure access: https://myhost.mycompany.com:8002/report-console/ User credentials a reportuser/reportuser The reportuser account was created during Motive Reporting installation. Until reset, the password is the same as the user name. a where: ■ mgdhost.mycompany.com is the address of a Managed Server host on which the Motive Reporting application is deployed. ■ 8001 is the clear port. ■ 8002 is the SSL port. 2. In the Reporting Console, click Manage Reports. 3. At the bottom of the page, click Manage Groups. The Manage Report Groups window is displayed. 4. 126 In Group Name, type a name for your group such as WiMAX Reports, and then click Add. Administering the Motive Reporting Application 5. Click Close. To publish a provided report 1. Log into the Reporting Console: Logging into the Reporting Console URL http://myhost.mycompany.com:8001/report-console/ Or, for secure access: https://myhost.mycompany.com:8002/report-console/ User credentials a reportuser/reportuser The reportuser account was created during Motive Reporting installation. Until reset, the password is the same as the user name. a where: ■ mgdhost.mycompany.com is the address of a Managed Server host on which the Motive Reporting application is deployed. ■ 8001 is the clear port. ■ 8002 is the SSL port. 2. From the Manage tab, click Import at the bottom of the page. The Import Report window is displayed. 3. Click the Browse button. The Choose file window is displayed. 4. Navigate to the .zip file for the provided report on the product CD, and then click Open: path_to_CD/Reporting/Reports/reportName.zip where reportName is the name of the provided report that you want to publish (for example, operationExecution.zip) For more information, see “Understanding the provided reports” on page 125. 5. From the Select a group for the report list, select your report group. To create one, see “To create a report group” on page 126. 6. In the Name field, type a name for the report (for example, Operation Executions) 7. In Description, optionally type a description for the report. Publishing and viewing the provided reports 127 8. Click Import. Note The system detects an attempt to re-publish a published report.zip file using a different name. In this case, a message is displayed indicating the report has been published. A report.zip file must contain a .rptdesign file, which contains metadata that defines the report. The system identifies a published report instance by the name of the .rptdesign file. To view a provided report 1. Log into the Reporting Console: Logging into the Reporting Console URL http://myhost.mycompany.com:8001/report-console/ Or, for secure access: https://myhost.mycompany.com:8002/report-console/ User credentials a reportuser/reportuser The reportuser account was created during Motive Reporting installation. Until reset, the password is the same as the user name. a where: ■ mgdhost.mycompany.com is the address of a Managed Server host on which the Motive Reporting application is deployed. ■ 8001 is the clear port. ■ 8002 is the SSL port. 2. From the View tab, click the name of a published report. Note After deploying the reporting application, the first time a report is rendered the BIRT engine requires initialization. The process may require several seconds. Subsequent report viewing should happen more quickly. 3. If a Parameter window appears, type or select values based on which you want to generate the report, and then click OK. The BIRT Report Viewer is displayed with the report data. From the viewer icons on the top of the page, you can re-run the report with different parameter values, export the report data, export the full report to a different format, and print the report. 128 Administering the Motive Reporting Application For complete details on how to use the console and report viewer, click the Help link in the upper-right corner of the . Publishing and viewing the provided reports 129 130 Administering the Motive Reporting Application 13 WiDM Server Reports 131 The WiDM Server uses the Motive Reporting system to generate reports. The following solution-specific reports are provided with the system. Reports provided with the WiDM Server Report name Description Input fields Sorted by... Filename Device Tracking Displays the operations Start Date, End Report performed on devices, Date as a transaction history sorted by device MAC address, over a supplied timeframe. MAC Address, DeviceTrackingReport.zip Date Zero Touch Display the number of Start Date, End Activation Report activations in a supplied Date timeframe. n/a Zero Touch Activation Details Report Manufacturer, ZeroTouchActivationDetails Model, MAC Report.zip Address, Date 132 Lists the devices that Start Date, End have been activated via Date Zero Touch activation. WiDM Server Reports ZeroTouchActivationReport.zip 14 Maintaining the Modeling Database This chapter covers: ■ ■ Purging snapshots and evaluated models from the schema Setting up sample purge script to run regularly 133 Database contingency planning and implementation including daily backups are typically the responsibility of your site DBA. As a result, details on backing up the database are not covered here; however, the DBA and other interested parties should review this section to learn about the purge script for removing unneeded data from the modeling schema. Purging snapshots and evaluated models from the schema Conduct the following procedure to perform a one-time purge using the sample script on the Administration Server host: /usr/local/bea/user_domains/MotiveCSC/samples/dbScripts/purge.sh To run a one-time purge of snapshots and evaluated models from the schema • From the Administration Server host, run the sample script: cd /usr/local/bea/user_domains/MotiveCSC/samples/dbScripts purge.sh -m motive_user -M motive_password -s service_name [-h hours_old ↲ -q path_to_sqlplus] where: ■ motive_user and motive_password are the account credentials for the modeling schema owner created when you installed the Service Management Platform. ■ service_name is the net service name set up for connection between the Administration Server host and the database instance. ■ hours_old determines which records to purge based on comparing the record's time stamp with that of the current date and time. If this value is set to 24, the script purges all snapshot and evaluated model records that were created 24 or more hours ago. If unspecified, the script applies the default value of 48 hours. ■ path_to_sqlplus is the full path to the Oracle client on the host. If sqlplus is in the path, you do not need to include this switch. Setting up sample purge script to run regularly On your modeling database host, you may want to set up an automated cron job to run the sample purge script on a regular basis. For information about the sample script (/usr/local/bea/user_domains/MotiveCSC/samples/dbScripts/purge.sh), see “Purging snapshots and evaluated models from the schema” on page 134. See also Intro to cron [http://www.unixgeeks.org/security/newbie/ unix/cron-1.html] from the UNIX Geeks site [http://www.unixgeeks.org/]. 134 Maintaining the Modeling Database B Creating Additional JDBC Data Sources 135 Post-deployment, it is possible to use the WebLogic Server Console (or the configureDatasource.py) script to add one or more JDBC data source pools to the SMPCluster. The script was extracted in the staging directory originally created to create the modeling schema. To use the WebLogic Server Console to create additional JDBC data sources 1. Log into the WebLogic Server Console: a. Go to the following URL: https://adminhost.mycompany.com:9001/console where: ■ adminhost.mycompany.com is the address of the host on which the Administration Server is installed. ■ 9001 is the SSL port of the Administration Server. The login page appears. b. To log in, type the credentials for WebLogic account, and then click Sign In. The account was created based on values set for the weblogicUsername and weblogicPassword properties when installing the Administration Server. If default values were applied, the user name and password are both weblogic. 2. From the WebLogic Server Console, complete the procedure in Create JDBC data sources [http:// download.oracle.com/docs/cd/E13222_01/wls/docs92/ConsoleHelp/taskhelp/jdbc/jdbc_datasources/ CreateDataSources.html] from the WebLogic Server 9.2 documentation site. To use the configureDatasource.py to create one or more additional JDBC data sources 1. From the WebLogic Server Console, stop all the Managed Servers in the SMPCluster: a. Expand the Environment node, click Clusters, and then select SMPCluster link. The Home > Summary of Clusters > SMPCluster page appears. b. On the Home > Summary of Clusters > SMPCluster page, click the Control tab. c. Select the check box for each Managed Server instance, click the Shutdown drop-down button, and then select Force Shutdown Now. A confirmation appears. d. Click the Yes button. The shutdown process can takes a few minutes, depending on the number of Managed Server instances and other factors. 136 Creating Additional JDBC Data Sources e. In the WebLogic Server Console, refresh the Home > Summary of Clusters > SMPCluster page; then, confirm that SHUTDOWN appears in the State column for each Managed Server instance. 2. From “To pre-configure additional JDBC data source pools” on page 60, complete Step 1, Step 2, and Step 3. 3. Run the following command for each of the pools you added: cd /data/staging/wimax runScript.sh configureDatasource.py <poolnameX> where <poolnameX> is the name of one of the pool blocks defined in the installer.properties file. 4. Start all the Managed Servers in the SMPCluster: a. Expand the Environment node, select the Clusters node, and then select the SMPCluster link. The Summary of Clusters > SMPCluster page appears. b. On the Summary of Clusters > SMPCluster page, click the Control tab. c. Select the check box for each Managed Server instance, and then click the Start button. A confirmation appears. d. Click the Yes button. e. Refresh the page until Running appears for each instance in the State column. 137 138 Creating Additional JDBC Data Sources Data Sources This part covers: ■ Chapter 15, “About Data Sources” ■ Chapter 16, “AAA Data Source” ■ Chapter 17, “MDM Data Source” 15 About Data Sources 141 A data source is a software component of the Service Management Platform (SMP) that abstracts communication with outside resources to make authoring models easier. Data source documentation can be found in several documents: ■ Documentation for the AAA data source is found in this document; see Chapter 16, “AAA Data Source” on page 143. ■ Documentation for the MDM data source is found in this document; see Chapter 17, “MDM Data Source” on page 151. ■ Documentation for the HDM data source is found in a separate document, the Home Device Manager Data Source API Reference Guide. ■ Other data sources, as well as general information about accessing and using data sources, are found in Service Management Platform (SMP) Data Sources API Guide. 142 About Data Sources 16 AAA Data Source This chapter covers: ■ ■ Connection parameters Methods 143 The AAA data source provides an API to a AAA server that exposes the server's functionality for notifying other systems of device online/offline status. The data source makes that functionality easy to access from the modeling tools. The AAA data source supports the following general functions: ■ Registering a system so that the AAA server sends it device status for a specific device. ■ Unregistering a system for notifications for a specific fevice. ■ Disconnecting a device Connection parameters The AAA data source will require the following connection parameters to be set up in the Service Management Platform (SMP) using the Modeling tools. address The URL address of the AAA server to be communicated with. It must start with either http:// or https://. For example: http://aaaservers.mycompany.com:7003 username Describes the username to be used to connect to the AAA server. The user that is supplied must have appropriate privileges on the AAA server to execute any desired actions. password Specifies the password for the above user. For example: password notifyaddress The URL that the AAA server should use when sending notification messages. It must start with either http:// or https://. For example: http://aaaservers.mycompany.com:7003. 144 AAA Data Source Methods deleteUser String deleteuserName(String realm, String userName) Deletes a user from the AAA server. Parameters. realm - Tenant or operator name, used to distinguish two users with the same userName (or when the same user/device uses two different operators). userName - A string that specifies a username on the AAA server. Note In a WiDM deployment, the name is typically the MAC address of a device. Returns. Returns DetailedResult, a wrapper object that contains the following: result_code ■ ■ 1 - Success 2 - Failure result_text - An integer whose value defines the results of the call: - A human-readable explanation of the result code. It may be the empty string. disconnectDevice String registerForDeviceStatus(String macAddress, String disconnectReason) This method directs the AAA server to start the network exit procedure for the specified device. Parameters. macAddress disconnect_reason Returns. ■ - A string that describes why the device is being disconnected, used for logging. Returns DetailedResult, a wrapper object that contains the following: result_code ■ - The MAC address of the device to be disconnected. 1 - Success 2 - Failure result_text - An integer whose value defines the results of the call: - A human-readable explanation of the result code. It may be the empty string. Methods 145 getUser ProvisioningUser getUser(String userName, String realm) This method returns details of the AAA user associated with supplied userName and realm values. Note In a WiDM deployment, each AAA user represents a single device, so the returned information includes details about a specific device (when the device has been successfully provisioned). Parameters. realm - Tenant or operator name, used to distinguish two users with the same userName (or when the same user/device uses two different operators). userName - A string that specifies a username on the AAA server. Note In a WiDM deployment, the name is typically the MAC address of a device. Returns. auth_type, Returns an object of the type ProvisioningUser, containing details such as user_name, user_realm, and password. insertUser String insertUser(String realm, String userName, String password) Adds a user to the AAA server. Note In a WiDM deployment, the MAC address of the device is supplied as the userName, and adding the user to the AAA server completes the Zero Touch provisioning of the device. Parameters. realm - Tenant or operator name, used to distinguish two users with the same userName (or when the same user/device uses two different operators). userName - A string that specifies a username on the AAA server. Note In a WiDM deployment, the name is typically the MAC address of a device. password Returns. - Password for the supplied username. Returns DetailedResult, a wrapper object that contains the following: result_code 146 - An integer whose value defines the results of the call: AAA Data Source ■ ■ 1 - Success 2 - Failure result_text - A human-readable explanation of the result code. It may be the empty string. isAvailable String isAvailable(String address) Determines whether the AAA server is available. Parameters. Returns. address - The AAA server to be contacted. Returns a Boolean indicating whether or not the server is available. isValidLogin String isValidLogin() Determines whether the values supplied in the connection parameters represent a valid login as authenticated by the AAA server. Parameters. Returns. None (uses connection parameters). Returns a Boolean indicating whether or not the login is valid. registerForDeviceStatus String registerForDeviceStatus(String macAddress) Registers the caller to receive notification events for a specific device from the AAA server. A provisioning server should call this method to receive the current IP address of the device. The AAA server responds immediately by calling the registered servers' deviceOnline or deviceOffline method, as appropriate, to indicate the device status. The AAA server also calls the appropriate deviceOnline or deviceOffline method (see “Endpoint Event Service” on page 167) whenever the device's status changes, until the registered server calls the unregisterForDeviceStatus method. A server can call this method multiple times for the same device; each call causes the AAA server to call deviceOnline() or deviceOffline(). Parameters. Returns. macAddress - The MAC address of the device to be disconnected. Returns DetailedResult, a wrapper object that contains the following: isAvailable 147 result_code ■ ■ 1 - Success 2 - Failure result_text - An integer whose value defines the results of the call: - A human-readable explanation of the result code. It may be the empty string. unregisterForDeviceStatus String unregisterForDeviceStatus(String macAddress) Tells the AAA server to stop sending notifications for the specified device to the calling system. If the caller has not previously registered for status for the specified device, the AAA server ignores the call. Parameters. Returns. ■ - The MAC address of the device to be disconnected. Returns DetailedResult, a wrapper object that contains the following: result_code ■ macAddress 1 - Success 2 - Failure result_text - An integer whose value defines the results of the call: - A human-readable explanation of the result code. It may be the empty string. updateUser String updateUser(String provisioningUser, String userName) Updates a user entry in the AAA server. Parameters. userName provisioningUser - a reference to a ProvisioningUser object. - A string that specifies a username on the AAA server. Note In a WiDM deployment, the name is typically the MAC address of a device. Returns. Returns DetailedResult, a wrapper object that contains the following: result_code ■ 1 148 - An integer whose value defines the results of the call: - Success AAA Data Source ■ 2 - Failure result_text - A human-readable explanation of the result code. It may be the empty string. updateUser 149 150 AAA Data Source 17 MDM Data Source This chapter covers: ■ ■ ■ ■ Connection parameters Getting data Synchronous and Asynchronous method calls Methods 151 The MDM data source provides an API to a Mobile Device Manager server, which handles communication with mobile devices using the OMA DM standard. The OMA DM standard defines a protocol for reading and writing to a tree of data nodes on the device. By writing new data to nodes, one can configure the mobile device for a variety of behaviors. Although the standard defines how to read and write from data trees, the structure of the tree varies from one device type to another. For this reason, the MDM product defines profiles for various features. A profile maps a feature set (expressed as a set of attributes, or field values) to the appropriate nodes for a specific device type. The MDM data source supports the following general functions: ■ Getting and setting arbitrary data from a device's node tree, using the specific nodes for the device type. ■ Getting and setting attributes, using a profile to map the attributes to device-specific nodes. ■ Asynchronous and synchronous methods for getting and setting data (see “Synchronous and Asynchronous method calls” on page 153). ■ Deleting subscribers. ■ Running low-level commands on the device. Connection parameters The MDM data source will require the following connection parameters to be set up in the Service Management Platform (SMP) using the Modeling tools. hostname Describes the hostname of the MDM server or the load balancer that sits in front of the MDM servers. It must start with either http:// or https://. For example: http://mdmservers.mycompany.com:7003 username Describes the username to be used to connect to the MDM server. The user that is supplied must have appropriate privileges on the MDM server to execute any desired actions (this is typically provided by using a user who has the MDMAdmin role, which conveys access to all functions). 152 MDM Data Source password Specifies the password for the above user. For example: password phonenumber Specifies the phone number or other identifier, such as subscriber ID, for a subscriber. Use the identifier that is relevant for the server you are contacting. waitinterval Optional. No longer used. Getting data You have two options for getting data from the MDM data source. You can use a method that directly returns the desired data but blocks until all data gathering is complete (“getAttributes” on page 157), or you can use a two-step process where you can operate asynchronously: 1. Ask the MDM server to update the data in the database, or “discover” the data, by calling a discovery method (“invokeDiscoveryForProfile” on page 159, “invokeDiscoveryForProfileSync” on page 160). 2. Get the data from the database using the “getCachedAttributes” on page 157 method. Synchronous and Asynchronous method calls Some methods for this data source have two variations, a synchronous method, whose method name ends in “Sync”, and an asynchronous method. ■ Synchronous methods make calls and wait for the results to be delivered, returning data as described in the individual method descriptions. They return a String indicating the operation's result (“done”, “error”, or “timeout”). ■ The asynchronous methods make calls to the MDM API, then return a job ID. You should then use the job ID to call the method “waitForJobs” on page 161. This allows you to execute several asynchronous methods, then call waitForJobs with several job IDs; the waitForJobs method returns when all of the jobs have completed. password 153 Methods assignCPProfile String assignCPProfile(String profileName, Map inputMap, String pinNumber, String pinNumber,↲ String signature, String externalCarrierId, String imei, String imsi, String ↲ manufacturer, String model) This method assigns a profile to a device using the CP protocol. Assigning a profile assigns the values listed in the profile to the corresponding nodes on the device. Using a profile allows the MDM server to handle node differences across devices. Although the node location for an e-mail username may differ from device to device, if the correct profile is used the system assigns the value to the correct location. If the supplied device does not already exist in the database, then you must supply the imei, imsi, manufacturer, and model parameters, and the system adds the device to the MDM database and then assigns the values from the profile. Parameters. inputMap profileName - a string indicating the name of the profile to assign. - Map of values to apply to the attributes specified in the profile. pinNumber - The PIN number to be supplied by the user to authenticate the operation on the device. - A String indicating the type of OMA security to be used for this operation (NONE, NETWPIN, USERPIN, or USERNETWPIN). signature externalCarrierId - The tenant for the device. imei - The device's IMEI value. Optional; used only when adding a new device. imsi - The device's IMSI value. Optional; used only when adding a new device. manufacturer model - The device's manufacturer. Optional; used only when adding a new device. - The device's model. Optional; used only when adding a new device. Returns. Returns a String indicating the operation's result (“done”, “error”, or “timeout”). assignImageToDevice String assignImageToDevice(String newImage, String oldImage, String timeout,) Assigns a firmware image to a device (launching a job on the MDM server to upgrade the device's firmware from one image to another). 154 MDM Data Source Parameters. oldImage timeout newImage - The ID of the new image to assign to the device. - The ID of device's last image. - The time (in milliseconds) that the system waits for a response before returning a timeout error. Returns. Returns the return value of the assign image job it launched on the server, which is either the string “done” if the method completed successfully, or an error code. assignInitialPolicy String assignInitialPolicy(String profileName, Boolean isCPEProfile, String inputMap, ↲ String pinNumber, String timeout) Deprecated. Assigns an initial policy to Nokia devices. Use MDM workflow for this purpose instead. assignProfile String assignProfile (String profileName, Boolean isCPEProfile, String inputMap, String ↲ pinNumber) An asynchronous method to assign the values provided in the inputMap parameter to the data nodes specified by a profile. This is an asynchronous method which, when called, returns a job ID immediately. Use the job ID (along with job IDs from other method calls) to call the method “waitForJobs” on page 161 method to await the completion of several methods. Parameters. profileName isCPEProfile - Boolean value that is true if the profile is a CP profile. inputMap - a string indicating the name of the profile to assign. - Map of values to apply to the attributes specified in the profile. pinNumber - The PIN number to be supplied by the user to authenticate the operation on the device. Returns. Returns a String indicating the job ID of the job assigned to execute the method. Call the “waitForJobs” on page 161 method to complete the process. assignProfileSync String assignProfileSync(String profileName, Boolean isCPEProfile, String inputMap, String ↲ pinNumber, String timeout) The synchronous version of the method “assignProfile” on page 155. assignInitialPolicy 155 Parameters. profileName isCPEProfile - Boolean value that is true if the profile is a CP profile. - a string indicating the name of the profile to assign. - Map of values to apply to the attributes specified in the profile. inputMap pinNumber - The PIN number to be supplied by the user to authenticate the operation on the device. - The time (in milliseconds) that the system waits for a response before returning a timeout error. timeout Returns. Returns a String indicating the operation's result (“done”, “error”, or “timeout”). deleteSubscriber String deleteSubscriber() This method deletes the current subscriber. Parameters. None. No parameters are required because the subscriber ID is supplied as one of the connection parameters for the data source (in the phoneNumber parameter). Returns. Returns an empty string. executeCommandScript String executeCommandScript(String script) Sends a script (of low-level device management operations) to the MDM server to be executed. Scripts typically reference specific nodes and are thus specific to particular device models. This is an asynchronous method which, when called, returns a job ID immediately. Use the job ID (along with job IDs from other method calls) to call the method “waitForJobs” on page 161 method to await the completion of several methods. Parameters. script - String that consists of a series of low-level MDM device commands. Returns. Returns a String indicating the job ID of the job assigned to execute the method. Call the “waitForJobs” on page 161 method to complete the process. executeCommandScriptSync Boolean 156 executeCommandScriptSync(String MDM Data Source script, String timeout) The synchronous version of the method “executeCommandScript” on page 156, this version waits until the command script completes before returning. Parameters. script - String that consists of a series of low-level MDM device commands. - The time (in milliseconds) that the system waits for a response before returning a timeout error. timeout Returns. Returns a String indicating the operation's result (“done”, “error”, or “timeout”). getAttributes Map getAttributes(String nodeList, String timeout) This method is a convenience method which both populates the database with the node values taken from nodes specified by a nodeList, and then returns the data. Specify nodes using the device-specific node paths. For other options for retrieving data, see “Getting data” on page 153. Parameters. nodeList - List of nodes to get from the device. - The time (in milliseconds) that the system waits for a response before returning a timeout error. timeout Returns. Returns a Map containing the nodes and their values. getCachedAttributes String getCachedAttributes(String attributeNodeName) This method retrieves attribute values from the MDM database. It does not contact the device; it instead retrieves the last values stored in the database. To refresh those values before getting them, use a discovery or populate method before executing this method. For other options for retrieving data, see “Getting data” on page 153. Parameters. Returns. attributeNodeName - The name of the attribute node to be retrieved. Returns a Map containing the nodes and their values. getCompatibleImagesForDevice List getCompatibleImagesForDevice() getAttributes 157 Queries the MDM server for firmware images that are compatible with the current device. Parameters. None. No parameters are required because the subscriber ID is supplied as one of the connection parameters for the data source (in the phoneNumber parameter). Returns. ■ ■ ■ ■ id Returns a List of Maps. Each map contains the following information for each compatible firmware update: - The imageExternalId of the firmware update. manufacturer model - The device manufacturer for the firmware update. - The device model for the firmware update. singleStepUpdate - A Boolean indicating whether or not the firmware update occurs in a single step. getDeviceTreeForProfile List getDeviceTreeForProfile(String profile_template) This method retrieves nodes from the database. Before executing this method, execute one of the discovery methods (“invokeDiscoveryForProfile” on page 159, “invokeDiscoveryForProfileSync” on page 160) to update the database with the latest nodes. This method retrieves all the nodes specified in a profile, using the profile to determine which of the device type's nodes match desired attributes. For other options for retrieving data, see “Getting data” on page 153. Parameters. Returns. profile_template - The name of the profile template whose device tree is to be retrieved. Returns a List of nodes. getFirmwareVersionForDevice List getFirmwareVersionForDevice() This method returns the firmware version currently installed on the device. For other options for retrieving data, see “Getting data” on page 153. Parameters. None. No parameters are required because the subscriber ID is supplied as one of the connection parameters for the data source (in the phoneNumber parameter). Returns. If the device has been activated and is an active device for a subscriber, then the method returns a String containing the version of the currently installed firmware; otherwise, returns an empty String. 158 MDM Data Source getUpdatePathsForDeviceAndImage List getUpdatePathsForDeviceAndImage(String image) Gets the shortest update path (least number of update steps) for a given device firmware image. The update path is packaged as a List of Maps, where each Map represents a step in the update path. Each update step Map object contains the following properties: ■ ■ ■ ■ ■ ■ ■ ■ id - A unique identifier for the update step. manufacturer model - The device manufacturer for the firmware update. - The device model for the firmware update. singleStepUpdate fromExternalId fromId - The external image id of the firmware version this update goes from. - The id of the firmware version this update goes from. toExternalId toId - Whether or not the firmware update occurs in a single step. - The external image id of the firmware version this update goes to. - The id of the firmware version this update goes to. Parameters. Returns. image - The device firmware image to get the update paths for. A List of maps representing the shortest update path for a given device firmware image. invokeDiscoveryForProfile String invokeDiscoveryForProfile(String profile_template) This method collects node data from the device using the information in a profile to map attribute nodes to device nodes. The returned data is stored in the database, to be retrieved using one of the get methods. For other options for retrieving data, see “Getting data” on page 153. This is an asynchronous method which, when called, returns a job ID immediately. Use the job ID (along with job IDs from other method calls) to call the method “waitForJobs” on page 161 method to await the completion of several methods. Parameters. profile_template - The name of the profile template whose device tree is to be retrieved. Returns. Returns a String indicating the job ID of the job assigned to execute the method. Call the “waitForJobs” on page 161 method to complete the process. getUpdatePathsForDeviceAndImage 159 invokeDiscoveryForProfileSync String invokeDiscoveryForProfileSync(String ,) The synchronous version of the method “invokeDiscoveryForProfile” on page 159. Parameters. profile_template - The name of the profile template whose device tree is to be retrieved. - The time (in milliseconds) that the system waits for a response before returning a timeout error. timeout Returns. Returns a String indicating the operation's result (“done”, “error”, or “timeout”). isAvailable Boolean isAvailable(String hostname,) Internal method used by modeling infrastructure. Determines whether a specific server's hostname is defined. Parameters. Returns. hostname - The hostname of the server to check. Returns a Boolean which is true if the hostname is a non-empty string. isValidPhone Boolean isValidPhone() Internal method used by modeling infrastructure. populateCachedAttributes String populateCachedAttributes(String nodeList) Not recommended; use a discovery method instead (such as “invokeDiscoveryForProfile” on page 159 or “invokeDiscoveryForProfileSync” on page 160). This method updates the MDM database by contacting the device and getting the values of the OMA DM nodes provided in the nodeList. After using this method or its synchonous equivalent, “populateCachedAttributesSync” on page 161, execute one of the data source's get methods to get the values from the database. This is an asynchronous method which, when called, returns a job ID immediately. Use the job ID (along with job IDs from other method calls) to call the method “waitForJobs” on page 161 method to await the completion of several methods. 160 MDM Data Source For other options for retrieving data, see “Getting data” on page 153. Parameters. nodeList - List of nodes to get from the device. Returns. Returns a String indicating the job ID of the job assigned to execute the method. Call the “waitForJobs” on page 161 method to complete the process. populateCachedAttributesSync String populateCachedAttributesSync(String nodelist, String timeout) Not recommended; use a discovery method instead (such as “invokeDiscoveryForProfile” on page 159 or “invokeDiscoveryForProfileSync” on page 160). The synchronous version of the method “populateCachedAttributesSync” on page 161, this one waits until the attributes are in the database and returns the values of the nodes. For other options for retrieving data, see “Getting data” on page 153. Parameters. nodeList - List of nodes to get from the device. - The time (in milliseconds) that the system waits for a response before returning a timeout error. timeout Returns. Returns a String indicating the operation's result (“done”, “error”, or “timeout”). rebootstrapSubscriber String rebootstrapSubscriber(String pin, String imsi, String timeout) Executes a rebootstrap operation on the subscriber device identified by the supplied parameters, resending the last bootstrap package sent to the device. Parameters. pin - - The device's IMSI value. imsi timeout Returns. - The time (in milliseconds) that the system waits for a response before returning a timeout error. Returns a String indicating the operation's result (“done”, “error”, or “timeout”). waitForJobs Map waitForJobs(String jobidlist, String timeout) populateCachedAttributesSync 161 Call the waitForJobs method to have your model wait for more than one job to complete. This method is used to avoid having one operation block your whole process. Parameters. timeout Returns. 162 jobidlist - A list of job IDs. - The time (in milliseconds) that the system waits for a response before returning a timeout error. Returns a Map of job IDs and result strings (“done”, “error”, or “timeout”). MDM Data Source API Reference This part covers: ■ Chapter 18, “AAA Integration” ■ Chapter 19, “Back Office Integration API” ■ Chapter 20, “Database Schema” 18 AAA Integration This chapter covers: ■ ■ ■ Security roles for AAA integration WiDM to AAA Server interface Endpoint Event Service 165 When a new device contacts the AAA server, the AAA server sends a New Device Event to the WiDM server by calling the EndPointEventService's deviceOnline method. The New Device event, after being parsed by the EndPointEventService, triggers the execution of the New Device model, which performs the following tasks: ■ Updates the endpoint entry for the new device in the Endpoint table, via the EndpointManager datasource. ■ Contacts the MDM server via its web services, to bootstrap the device. Security roles for AAA integration The AAA server must be configured to use an appropriate user in order to call the EndpointEventService: ■ The user must exist in the MotiveSMP domain. ■ The user must have the EndpointService role. WiDM to AAA Server interface The following diagram illustrates how the AAA server communicates with the WiDM Server through the WiDM Server's southbound interface, provided by the EndpointEventService. 166 AAA Integration WiDM to AAA server interface WiMAX Integration Layer Datasource HDM Datasource WiDM MDM SBI Device Online AAA Unprovisioned Device Endpoint Event Service The AAA server communicates with the WiDM Server through the Endpoint Event Service. The Endpoint Event Service provides methods that allow the AAA server to notify registered systems when a device enters the network. deviceOnline String deviceOnline(String device_id, String device_id_type, String device_ip_address, ↲ KeyValuePair attributes, Boolean new_device) To be called by the AAA server to notify systems registered via the registerForDeviceStatus() method in the AAA data source. The AAA server calls deviceOnline() when a system registers with the AAA server and thereafter whenever the device's status changes, until the system unregisters. For information on registering a system for these notifications, see “registerForDeviceStatus” on page 147. Endpoint Event Service 167 Parameters. device_id - The ID of the device to be acted on. The type of the value depends on what your deployment is using for device IDs, and is specified by the next parameter. device_id_type ■ MAC - A string that defines the type of the supplied ID. Valid values include: Address. Note This is the only type used by the WiDM system. ■ ■ ■ ESN - An electronic serial number. MEID - A mobile equipment identifier number. IMEI- An International Mobile Equipment Identity number. device_ip_address - A string that indicates the current IP address of the device. attributes - A set of key/value pairs to define attributes of the device. new_device - A Boolean value that is true if the device is a new device. Returns. Returns DeviceResponse, a wrapper object that contains the following: result_code ■ ■ 1 - Success 2 - Failure result_text - An integer to define the results of the call. - A human-readable explanation of the result code. It may be the empty string. deviceOffline String deviceOffline(String device_id, String device_id_type, String device_ip_address, ↲ KeyValuePair attributes) To be called by the AAA server to notify systems registered via the registerForDeviceStatus() method in the AAA datasource. The AAA server calls deviceOffline() when a system registers with the AAA server and thereafter whenever the device's status changes, until the system unregisters. For information on registering a system for these notifications, see “registerForDeviceStatus” on page 147. Parameters. device_id - The ID of the device to be acted on. The type of the value depends on what your deployment is using for device IDs, and is specified by the next parameter. 168 AAA Integration device_id_type ■ MAC - A string that defines the type of the supplied ID. Valid values include: Address. Note This is the only type used by the WiDM system. ■ ■ ■ ESN - An electronic serial number. MEID - A mobile equipment identifier number. IMEI- An International Mobile Equipment Identity number. device_ip_address attributes Returns. - A set of key/value pairs to define attributes of the device. Returns DeviceResponse, a wrapper object that contains the following: result_code ■ ■ - A string that indicates the current IP address of the device. 1 - Success 2 - Failure result_text - An integer to define the results of the call. - A human-readable explanation of the result code. It may be the empty string. deviceOffline 169 170 AAA Integration 19 Back Office Integration API This chapter covers: ■ ■ ■ ■ ■ ■ ■ Understanding back office integration ProvisionEndpoint operation ProvisionHSD operation ProvisionLock operation ProvisionVOIP operation ProvisioningComplete operation UpdateToLatestFirmware operation 171 The operations described in this chapter are used by the Zero Touch flow. They are triggered by the system when calls from the AAA server indicate that a new device has entered service. Understanding back office integration On a successful bootstrap of an OMA-DM device, the WiDM server gets a trigger from the MDM server if the device is OMA-DM based. (For a TR-069-based device, WiDM gets the trigger from HDM.) ■ The entry point for provisioning a new device is ProvisionEndpoint (described in “ProvisionEndpoint operation” on page 172). ■ In the default configuration, when the WiDM server successfully finishes bootstrapping a device, it calls a method (bootstrap_Complete) which calls the operations in this chapter to provision the device. These flows can be modified depending on customer requirements. The operations in this chapter are endpoint operations which can be called through the Endpoint Operations Web Service and the Endpoint Operations Data Source. Instructions for calling endpoint operations can be found in the Service Management Platform (SMP) Programming Guide, which includes a section on an example Java client. ProvisionEndpoint operation This is the operation called initially when provisioning a device. It draws information from the model you configure in “Editing profile assignments and default values” on page 71. Data Sources. User Roles. Inputs. HDM, MDM and Endpoint. SV_User This operation has no inputs. ProvisionHSD operation The Provision HSD operation is responsible for configuring a WiMAX device for High Speed Data service. It is called by the Zero Touch WiMAX Activation Template. The calling entity must pass in all the data to be configured on the device, but the caller does not need to know whether the device was bootstrapped using the TR-069 or the OMA/DM protocol. After calling this operation, the calling entity should call the ProvisioningComplete operation to notify the AAA server that provisioning is done. 172 Back Office Integration API This operation determines which protocol was used to bootstrap the device (by retrieving that information from the WiDM database) and then uses it to call the appropriate HDM or MDM web services to provision the device. This operation configures operator data, H-NSP ID, CAPL and RAPL data, Channel Plans and Subscriber information. When this operation is completed, the device has enough data to surf the internet; the system then runs the ProvisioningComplete operation to create the user in the AAA server. See “ProvisioningComplete operation” on page 176. Data Sources. User Roles. Inputs. ■ ■ HDM, MDM and Endpoint. SV_User The operation requires the following inputs: - The unique ID value for the endpoign to be targeted by the operation. To get this value, call the getEndpointOperations method and give it the MAC address of the desired device.. This call takes MAC address. EndpointDescriptor.uniqueID InputMap.inputs - the operaton webservice takes a HashMap with all the inputs. ProvisionHSD expects the following keys in the inputs hashmap: ❐ OperatorName - A human-readable name of the operator of the HSD service. ❐ H-NSP-ID - Home Network Service Provider Identifier. Usually it is globally unique; but does not have to be for smaller local deployments. It is specified in “WiMAX Forum Network Architecture (Stage3); Release 1 Version 1.2 or higher.” ❐ CAPL_Select_Policy - NAP Selection Policy. The value should be an integer from 0 to 3, indicating the following choices: ❐ ● 0 - Reserved ● 1 - Strict Policy ● 2 - Partially Flexible Policy ● 3 - Fully Flexible Policy CAPL_Entries - A list of hash maps. Each hash map has the following two keys: ● NAP-ID - Value for this key is Network Access Provider id. ● Priority - Value for this key is priority and can be from 1 to 254. ❐ RAPL_Select_Policy - Visitor NSP Selection Policy. It takes the same integer values 0 to 3 as the CAPL_Select_Policy. ❐ RAPL_Entries - A list of hash maps with the same keys as CAPL_Entries. ❐ PrimarySubscriptionName - Human readable name; must be unique for the operator. This name will be set on the device. ProvisionHSD operation 173 ❐ PrimarySubscriptionActivated - Flag to indicate that provisioning phase is complete. Value must be true or false. ProvisionLock operation This operation is reserved for future use; it is not used in the current implementation. Data Sources. User Roles. HDM, MDM and Endpoint. SV_User Inputs. EndpointDescriptor.uniqueID - The unique ID value for the endpoign to be targeted by the operation. To get this value, call the getEndpointOperations method and give it the MAC address of the desired device.. This call takes MAC address. ProvisionVOIP operation The ProvisionVOIP operation is responsible for configuring a WiMAX device for voice over IP service. It is called by the Back Office Zero Touch template. When a new device enters the network, after it is bootstrapped, the back office will be notified and given the opportunity to provision the device. One of the services that can be provisioned is VOIP. This involves configuring the CPE device to interact with the VOIP service provided, either directly or indirectly, by the WiMAX operator. At this time only TR-69 devices are supported for VOIP provisioning, according to the object model defined in TR-104(which is an extension to TR-69). Because strict adherence to this object model varies from device to device, it is necessary for the the Provision VOIP Model to be modified in the field to adjust for differences in device implementations. The HDM SMP datasource is utilized to perform SetParameterValue functions on the device to actually configure the settings on the device. The calling entity must pass in all the data to be configured on the device, but the caller does not need to know whether the device was bootstrapped using the TR-069 or the OMA/DM protocol. After calling this operation, the calling entity should call the ProvisioningComplete operation to notify the AAA server that provisioning is done. This operation determines which protocol was used to bootstrap the device (by retrieving that information from the WiDM database) and then uses it to call the appropriate HDM or MDM web services to provision the device. When this operation is completed, the device has enough data to surf the internet; the system then runs the ProvisioningComplete operation to create the user in the AAA server. See “ProvisioningComplete operation” on page 176. Data Sources. User Roles. HDM, MDM and Endpoint. SV_User Inputs. 174 Back Office Integration API ■ ■ - The unique ID value for the endpoign to be targeted by the operation. To get this value, call the getEndpointOperations method and give it the MAC address of the desired device.. This call takes MAC address. EndpointDescriptor.uniqueID InputMap.inputs - the operaton webservice takes a HashMap with all the inputs. ProvisionVOIP expects the following keys in the inputs hashmap: Key Corresponding TR-104 Property Profile Name .VoiceService.{i}.VoiceProfile.{i}.Name Signaling Protocol .VoiceService.{i}.VoiceProfile.{i}.SignalingProtocol Max Sessions .VoiceService.{i}.VoiceProfile.{i}.MaxSessions DTMF Method .VoiceService.{i}.VoiceProfile.{i}.DTMFMethod DTMF Method G711 .VoiceService.{i}.VoiceProfile.{i}.DTMFMethodG711 Region .VoiceService.{i}.VoiceProfile.{i}.Region STUN Enable .VoiceService.{i}.VoiceProfile.{i}.STUNEnable STUN Server .VoiceService.{i}.VoiceProfile.{i}.STUNServer Fax Passthrough .VoiceService.{i}.VoiceProfile.{i}.FaxPassThrough Modem Passthrough .VoiceService.{i}.VoiceProfile.{i}.ModemPassThrough RTP Local Port Min .VoiceService.{i}.VoiceProfile.{i}.RTP.LocalPortMin RTP Local Port Max .VoiceService.{i}.VoiceProfile.{i}.RTP.LocalPortMax RTP DSCP Mark .VoiceService.{i}.VoiceProfile.{i}.RTP.DSCPMark RTP Telephone Event Payload Type .VoiceService.{i}.VoiceProfile.{i}.RTP.TelephoneEventPayloadType SIP Server Address .VoiceService.{i}.VoiceProfile.{i}.SIP.ProxyServer SIP Server Port .VoiceService.{i}.VoiceProfile.{i}.SIP.ProxyServerPort SIP Server Transport .VoiceService.{i}.VoiceProfile.{i}.SIP.ProxyServerTransport SIP Registrar Server Address .VoiceService.{i}.VoiceProfile.{i}.SIP.RegistrarServer SIP Registrar Server Port .VoiceService.{i}.VoiceProfile.{i}.SIP.RegistrarServerPort SIP Registrar Server Transport .VoiceService.{i}.VoiceProfile.{i}.SIP.RegistrarServerTransport SIP User Agent Domain .VoiceService.{i}.VoiceProfile.{i}.SIP.UserAgentDomain SIP User Agent Port .VoiceService.{i}.VoiceProfile.{i}.SIP.UserAgentPort SIP User Agent Transport .VoiceService.{i}.VoiceProfile.{i}.SIP.UserAgentTransport SIP Outbound Proxy .VoiceService.{i}.VoiceProfile.{i}.SIP.OutboundProxy SIP Outbound Proxy Port .VoiceService.{i}.VoiceProfile.{i}.SIP.OutboundProxyPort SIP Organization .VoiceService.{i}.VoiceProfile.{i}.SIP.Organization ProvisionVOIP operation 175 SIP Registration Period .VoiceService.{i}.VoiceProfile.{i}.SIP.RegistrationPeriod SIP Register Expires .VoiceService.{i}.VoiceProfile.{i}.SIP.RegisterExpires SIP Register Retry Interval .VoiceService.{i}.VoiceProfile.{i}.SIP.RegisterRetryInterval SIP Use Codec Priority In SDP Response .VoiceService.{i}.VoiceProfile.{i}.SIP.UseCodecPriorityInSDPResponse Line Entries .VoiceService{i}.VoiceProfile.{i}.Line.{i}. ProvisioningComplete operation This operation is called by the Zero Touch template to notify the AAA server that provisioning has happened, and to create the user in the AAA server. Data Sources. User Roles. HDM, MDM and Endpoint. SV_User Inputs. EndpointDescriptor.uniqueID - The unique ID value for the endpoign to be targeted by the operation. To get this value, call the getEndpointOperations method and give it the MAC address of the desired device.. This call takes MAC address. UpdateToLatestFirmware operation This operation is used to update a device to the latest firmware version. It performs the following tasks: ■ Determines the latest required firmware version for the device, and whether it is available. ■ Checks the latest required version against the current device version, and decide whether the device needs an update. ■ If the device needs an update and the update is available, determines the path for the update, and performs the update. If the supplied device does not already exist in the database, then the operation returns an error (logged in the WiDM log on the server). For information on the logs, see “Enabling server-side logging” on page 58. Data Sources. User Roles. MDM and Endpoint. SV_User Inputs. ■ - The unique ID value for the endpoign to be targeted by the operation. To get this value, call the getEndpointOperations method and give it the MAC address of the desired device.. This call takes MAC address. EndpointDescriptor.uniqueID 176 Back Office Integration API ■ InputMap.inputs - the operaton webservice takes a HashMap with all the inputs. UpdateToLatestFirmware operation 177 178 Back Office Integration API 20 Database Schema This chapter covers: ■ EPFIRMWARELATESTVERSION 179 The WiDM Server uses the Service Management Platform database with one additional table. The added table is described below. For information on the other tables in the database, see the Service Management Platform Data Dictionary. EPFIRMWARELATESTVERSION Stores version information for endpoints. EPFIRMWARELATESTVERSION # Column name ID (PK) Description Description: System-generated primary key. 1 Format: NUMBER(19) NOT NULL MANUFACTURERID Description: Foreign key to the EPMANUFACTURER table. 2 Format: NUMBER(19) NOT NULL MODELID Description: Foreign key to the EPMODEL table. 3 Format: NUMBER(19) NOT NULL PLATFORMID Description: Foreign key to the EPPLATFORM table. 4 Format: NUMBER(19) NOT NULL IMAGE_EXTERNAL_ID Description: A reference to an MDM firmware image. Format: NUMBER(19) NOT NULL 180 Database Schema Glossary 802.11 802.11 refers to a family of standards for WLAN (wireless local area network) communication developed by the IEEE [http://www.ieee.com/portal/index.jsp]. Commonly referred to as Wi-Fi, 802.11 includes 802.11a, 802.11b, and 802.11g. ■ ■ ■ 802.11a provides up to 54 Mbps on the 5 GHz band with a range of 60 feet. 802.11b provides 11 Mbps in the 2.4 GHz band with a range of 300 feet and is backward-compatible with 802.11. 802.11g, provides 54 Mbps on the 2.4 GHz band with a range of 300 feet, and is interoperable with 802.11b. AAA server A server which provides authentication, authorization and accounting services for an organization. Other servers use the AAA server to determine whether to grant a user or client access, and what privileges to allow the client/user. Administration Server Single-instance server that provides a contact point for the Managed Server instances and system administration tools in the WebLogic Server domain. See also Managed Server. API (application programming interface) The set of methods, classes, and fields written for an operating system or application. Programmers use the API to make requests of the operating system or another application. Compare with CLI and GUI. application A client or server program that performs specific tasks. assisted service Type of service in which a CSR assists a subscriber with problem resolution. Auto-configuration Server (ACS) The protocol server component installed on each Managed Server. The ACS processes messages to and from devices in subscriber environments. It handles all device communication from the protocol tier in a distributed domain deployment and from the application tier in a standard deployment. TR-069 devices send the ACS Inform messages regularly, receive commands called from the ACS, and respond to the ACS with results. The ACS can send TR-069 devices unsolicited messages (connection requests) requesting them to initiate a new session with the server. By contrast, SNMP devices and the ACS use a push model to interact: The ACS sends requests to SNMP devices, and the devices respond. Unlike TR-069 devices, SNMP devices do not continually send Inform messages to the ACS, and an Inform message is not required to run actions from the action queue on them. 181 Bastion Web Server Standard web server software such as Sun One Web Server or Apache. Optionally, Bastion Web Server packages are installed on hosts in the DMZ to receive and redirect incoming subscriber system requests to application servers. Boot Inform message On devices that support the TR-069 protocol, a message that is sent whenever the CPE is booted up or reset. The message does not provide information about how long the CPE has been attached to the current network environment, or whether or not the CPE has ever been activated. Bootstrap Inform message On devices that support the TR-069 protocol, a message that is sent the first time the device is installed, after the device is factory reset, or after the device's management server URL has been changed. Whenever a device contacts the Home Device Manager server with this message, the HDM server evaluates the activation status of the device. If the device uses the Bootstrap Server during activation, and the Auto-configuration Server (ACS) URL has been changed on the device to contact the Device Management (DM) Server, HDM waits for the device to send a Bootstrap Inform message indicating that the ACS URL was changed, and then HDM activates the device. If the device does not use the Bootstrap Server during activation, HDM immediately activates the device. Bootstrap Inform messages are sent continuously until Home Device Manager successfully acknowledges and processes them. If a device is activated already, a Bootstrap Inform message deactivates the device, and the device must go through the activation process again. HDM treats this as a factory reset. Bootstrap Server Type of Managed Server, in the HDMCluster or HDMDistributedCluster, that not fully-provisioned CPE communicate with initially. After authenticating, CPE in the “walled garden” are redirected to a Device Management (DM) Server. Bootstrap Servers authenticate incoming CPE requests with a default user name and password for the associated device type. If the Bootstrap Server is configured for pass-through authentication, CPE can authenticate without credentials. The Bootstrap Server is also referred to as the Walled Garden Server. Compare to Device Management (DM) Server. bootstrapping The process of configuring a device or mobile handset such that it can establish a management session with a secure management server. cable modem Customer premises equipment (CPE) device that transmits data through a coaxial cable television network rather than phone lines, as with a conventional modem. Cable modems generally transmit data faster than conventional modems. An advantage of a cable modem is that the user does not have to dial up for network access because the computer is connected continuously. carrier A provider of phone services for mobile devices. A carrier may have multiple tenants. A tenant may only have one carrier per type (MDM or MDS). If neither MDM nor MDS is used in a deployment, then tenants do not need to be linked to carriers. 182 Glossary CLI (command-line interface) A user interface to an operating system or an application in which the user types commands using a special command language. Compare with API and GUI. client A caller application that communicates with the SMP. For example, clients send operation invocation requests for a named endpoint operation to SMP's Endpoint Operations API. A CSR application deployed on the same WebLogic Server domain as the SMP can be written to use the API methods directly, while a northbound interface installed outside of the domain can use the API's web service to call the methods. Configuration Manager Browser-based interface that customer teams use to control the CSR experience within the applicable problem resolution application. In the Configuration Manager Console, a user sets up test modules that define a group of applicable tests; creates security groups to control CSR access, and sets properties to affect general behavior of the CSR application. Connection Request Inform message On devices that support the TR-069 protocol, an Inform message that occurs based on a request (ConnectionRequestURL method call) from the Auto-configuration Server (ACS) . Connection Request Proxy Server Web server that passes connection requests from the Auto-configuration Server (ACS) to a TR-069 device. In turn, the device sends an Inform message to the ACS. See also TCP Connection Request Proxy Server, UDP (User Datagram Protocol) Connection Request Proxy Server. CP (client provisioning) Initial over-the-air configuration of mobile devices through SMS messaging as defined by OMA CP. CPE (customer premises equipment) Rented or purchased equipment that is physically located at the residence or office of a subscriber. Examples include cable or DSL modem, residential gateways, IP set-top boxes, VoIP terminal adapters, and femtocell base stations. CPE WAN Management protocol (CWMP) An industry standard for WAN-side configuration and management of devices such as gateways and modems. The CWMP, also referred to as TR-069, provides a framework for communication between CPEs and Auto-configuration Servers (ACSs) such as the ACS in Home Device Manager. The framework includes a mechanism for secure auto-configuration of a CPE and incorporates other CPE management functions. TR-069 establishes rules for how a CPE device communicates with and is managed by a remote management system. CSR (customer support representative) A person who provides subscribers assisted service. CSRs use Motive software to diagnose and resolve service issues while communicating with subscribers. CSRs are sometimes referred to as analysts or agents. 183 Customer Service Console Browser-based interface that CSRs use to resolve service issues on behalf of mobile, broadband service, and/or FMC (fixed mobile convergence) subscribers. For each applicable subscriber service, there are one or more associated devices. Per device, the Customer Service Console provides CSRs with a bootstrapping workflow in the case that the device is not activated with the applicable management server; device details including a device diagram; a list of available operations to initiate on the device such as that for a firmware upgrade or resetting a non-optimal setting; and device history lookup. The Managed Servers of the Service Management Platform host the Customer Service Console. Customer Service Manager Motive product that helps CSRs (customer support representative) pinpoint the cause of and resolution for service issues on behalf of high-speed data subscribers. The product gathers service data referred to as telemetry from multiple sources to present CSRs with a complete representation of a service as it exists in a subscriber’s environment. Also, the product presents CSRs the results of a comparison between the subscriber information and managed settings that “model” the optimal working state. The overall process empowers CSRs to automatically perform root cause analysis and to drive rapid and accurate resolution. Device Management (DM) Server Type of Managed Server, in the HDMCluster or HDMDistributedCluster, that communicates with CPEs configured for activation. The DM Server instances run policies on the CPE to complete the activation process. On an ongoing basis, they implement policies on CPEs to keep them updated. Authenticating to a DM Server requires strict authentication including the device-specific credentials. The DM Server is also referred to as the Public Server. Compare to Bootstrap Server. Diagnostic Complete Inform message On devices that support the TR-069 protocol, an Inform message that occurs to re-establish connection to the server after completing a diagnostic test initiated by the Auto-configuration Server (ACS). distributed domain deployment Home Device Manager architecture that includes two distinct WebLogic Server domains, the HDMDistributedDomain in the DMZ and the HDMDomain in the trusted network. The domains each include a cluster of application servers. In a distributed domain deployment, the initial CPE communication redirects from the application servers in DMZ to the ones in the trusted network. Compare to standard deployment. DM (device management) Management of device configuration, updates, and other managed objects of mobile devices as defined by OMA (Open Mobile Alliance). Generically, DM refers to all methods and activities associated with mobile device management. 184 Glossary DS Server The application server component of Mobile Device Manager that enables backing up and restoring data on mobile handsets. DSL (digital subscriber line) A technology that provides high-bandwidth Internet connections to homes and small businesses over ordinary copper telephone lines. DSL can carry both data and voice signals. endpoint An individual device or system targeted for some sort of management. The management may include retrieving data from, configuring an update on, or running other specific functions on individual endpoints. Examples of endpoints are subscriber hardware such as a mobile phone or DSL modem and any other individual systems such as an operator OSS. endpoint operation A data configuration stored in the SMP Repository. The configuration defines the manner in which SMP is to handle a client request for executing the corresponding operation. The operation is the function or group of procedures that the applicable manager instructs a given endpoint to execute on itself. Deployment teams configure an endpoint operation through the Configuration Manager after developing the associated operation implementation. Endpoint Operations API A web service API that allows exposing normalized operations for execution on individual endpoints. With a normalized operation, the client does not need to expose the full APIs of the applicable managers or to invoke multiple managers. In general, the API is used to do the following: determine whether a named endpoint operation is available for a given endpoint; validate the client's request based on the configuration of the corresponding endpoint operation; and to pass the client's validated request to the test module that implements the operation invocation. FMC (fixed mobile convergence) Fixed and mobile telephony service from a single phone with the handset configured to switch between mobile and Wi-Fi (Wireless Fidelity) networks. For example, British Telecom offers an FMC service called BT Fusion [http:// www.btbusinessshop.com/icat/btfusion_hub]. foreign key A column or columns that uniquely identify a record in another database table by referring to its primary key. GUI (graphical user interface) The GUI contains graphical elements such as buttons and menus that users click or execute through keyboard commands to interface with an operating system or application. Compare with API and CLI. HDMCluster The n number of Managed Servers in the application tier. The software and functionality on each Managed Server in the HDMCluster is identical, and the number of instances depends on the load the deployment must support. 185 HDMDistributedCluster The n number of Managed Servers in the protocol tier. The software and functionality on each Managed Server in the HDMDistributedCluster is identical, and the number of instances depends on the load the deployment must support. HDMDistributedDomain A WebLogic Server domain created by the protocol tier installer. The HDMDistributedDomain is made up of an Administration Server and the Managed Servers in the protocol tier. It is optional to install the Managed Servers into a cluster (HDMDistributedCluster). HDMDomain A WebLogic Server domain created by the application tier installer. The HDMDomain is made up of an Administration Server and the HDMCluster. Home Device Manager Product that allows broadband providers to remotely manage CPE that support the TR-069 and SNMP (Simple Network Management Protocol) protocols. Functionality includes policy-based tools to automate device configuration and management, ability to perform single as well as large-scale bulk device configuration, troubleshooting, firmware upgrades, event management, user management, communications logging, reporting, device alarm management, and device alarm monitoring. The Home Device Manager can be integrated with an existing OSS infrastructure and with Motive’s Service Activation Manager, Self-Service Manager, and Customer Service Manager. Inform message A message sent from a TR-069 device to establish communications with the Auto-configuration Server (ACS). This message serves to initiate the set of transactions requested and to communicate the limitations of the device with regard to message encoding. See also Bootstrap Inform message, Boot Inform message, Diagnostic Complete Inform message, Connection Request Inform message, Periodic Inform message, Scheduled Inform message, Transfer Complete Inform message, Value Change Inform message. IPTV (Internet Protocol Television) A system for distributing video signals using internet protocols, typically in conjunction with an internet connection. See also set-top box (STB). LAN (local area network) A network of interconnected computers and other devices within a relatively small geographic area. The computers on a LAN can interact with each other. Managed Server Server instance that runs identical applications to its peer instances in a WebLogic Server domain. See also Administration Server. ManagementServerURL URL for a CPE device to connect to an Auto-configuration Server (ACS) server using the CPE WAN management protocol (TR-69). 186 Glossary manager Software application that communicates with and manages a set of endpoints such as computers, mobile devices, broadband devices, or other systems such as CRMs and application middleware. Examples of managers include Home Device Manager (HDM) and Mobile Device Manager (MDM). MDM Server The IP-based over-the-air server component of Mobile Device Manager. The Mobile Device Management Servers provide the core functionality to send configuration settings and firmware updates to mobile handsets. The servers support OMA-based CP and DM specifications. Mobile Device Manager Motive product that allows service providers to remotely provision, update, and manage mobile devices and services throughout the device life cycle. The product provides for individual and bulk device configuration, problem resolution, firmware upgrades, event management, user management, and reporting. Mobile Device Manager includes two primary components, the MDM Server and the DS Server. Both use standards-based protocols, OMA DM and OMA DS, to communicate with the native DM and DS clients installed on mobile devices. model A model is an abstract representation that defines an application configuration, which is the IT infrastructure (including hardware and software components, relationships and dependencies) of a mission-critical application or business process. Models establish general information about an application configuration and provide a reusable structure on which many business operations can be performed. Model Builder Model Builder is a Motive desktop application which enables you to create models that capture the hardware and software components and dependencies of the IT infrastructure of a mission-critical application or business process. Models created in Model Builder are consumed by Overlay Builder users and by Motive model-based web application users (who use models and overlays to resolve application environment issues). Motive Mobility Solution A deployment of integrated Motive products that enable providers to manage subscriber service and associated devices. The solution includes the Service Management Platform, Customer Service Console, and Mobile Device Manager and/or Home Device Manager. net service name For an Oracle client, an alias to the connect descriptor (host name, port number, and service name or SID) for a database. The mapping of the net service name to the connect descriptor may be stored in the Oracle tnsnames.ora file or in a centralized directory. Use the Oracle Net Configuration Assistant or the Oracle Net Manager installed with the Oracle client to configure net service names. See also service name. OMA (Open Mobile Alliance) Organization that develops open specifications designed to facilitate interoperability in the mobile industry based on market requirements. For more information, see the OMA [http://www.openmobilealliance.org] site. 187 operation implementation The model, overlay, and test module created for executing the operation for a given endpoint operation. After validating a client request based on the configuration of the applicable endpoint operation, SMP executes the operation implementation. optimal setting A collection of optimal values for a particular service. For example, the Globecom tenant has a Globecom Email optimal setting, which defines the optimal values for the Email service for that tenant. Option 1 An installation option for the Service Management Platform in which you create a WebLogic Server domain for the platform. The process involves creating the domain and its Administration Server and one or more Managed Servers. Option 2 An installation option for the Service Management Platform in which you install the platform into an existing WebLogic Server domain. The process involves updating the existing domain's Administration Server and Managed Servers with the platform. OS (operating system) Software designed to control the hardware of a general-purpose computer or other device. Computers must have an operating system to run other programs. Operating systems perform basic tasks such as recognizing input from the keyboard, sending output to the display screen, keeping track of files and directories on the disk, and controlling peripheral devices (disk drives and printers). overlay An overlay evaluates a snapshot (a representation of the state of an application environment at a given time) using a set of checks (conditions about a business issue) that determine the cause of problems and configuration issues for a particular application environment. The overlay then enables users of Motive model-based web applications to apply actions that address those issues. An overlay is built on top of an application model that defines the hardware and software components, relationships, and dependencies of an application configuration. Each overlay consists of one or more checks that evaluate an application issue. Each check is associated with one or more actions that work to address the issue. Overlays help users determine if the current configuration of an environment is conforming to the specifications outlined in the policy. Overlay Builder Overlay Builder is a Motive desktop application which enables you to create overlays that help users address issues within their application environment. Overlays are available within the Motive model-based web applications to users who support application environments. PARP (Pluggable Asynchronous Request Processor) A workload management component that handles client requests within the Service Management Platform (SMP). PARP is accessed either through the SMP Java APIs or associated web services. 188 Glossary Periodic Inform message On devices that support the TR-069 protocol, an Inform message that occurs based on a periodic inform interval configured for the CPE device. For example, a device may be configured to send a message to an Auto-configuration Server (ACS) once every 24 hours. policy A rule that defines a set of conditions (such as selection criteria or device groups) and associated actions. If a device meets these conditions, then the specified actions for that rule are run on the device. Within Home Device Manager, policies are used to manage devices. A policy continues to run against targeted devices unless it expires or reaches a failure threshold or retry count configured in the policy. Policies run only on devices that are currently enabled and not locked by an operator for manual operation. primary key One or more columns that, taken together, uniquely identify a record in a database table. See also foreign key. protocol tier The Home Device Manager application servers installed in the DMZ of a distributed domain deployment. The protocol tier is dedicated to handling incoming communication from CPE; its servers make up the HDMDistributedDomain with an Administration Server and one or more Managed Servers. When the protocol tier Managed Servers are clustered (optional), they are members of the HDMDistributedCluster. The applicable protocol Managed Server uses RMI over IIOP to load balance and direct CPE communication to an available Managed Server in the application tier. Unlike the application tier servers, the protocol tier servers do not communicate with the Home Device Manager OLTP database. Compare to application tier. See also Web proxy tier. Public Server See Device Management (DM) Server. report group A collection of related reports organized under a report group name. Scheduled Inform message On devices that support the TR-069 protocol, a one-time Inform message that occurs based on a request (M ScheduleInform method call) from the Auto-configuration Server (ACS). Self Service Manager Motive product that automates problem diagnosis, resolution, and service management capabilities across each of the primary support channels—electronic, phone, and email. With Motive software, subscribers can easily self-manage their IP-based services without engaging a CSR (customer support representative) or requiring a technician visit. self-service Type of service in which a subscriber uses Motive software to resolve a problem without interacting with a CSR. 189 service In the Customer Service Console, a service is a set of features. In the database, it is a feature in the system, for which you can define optimal settings in the database. For example, Email. Service Activation Manager Motive product that automates service activation for broadband subscribers. The Service Activation Manager software enables subscribers to turn up high-speed data and IP-based services without having to call a customer service representative (CSR) or request an onsite technician visit. The software can offer and fulfill IP-based services during activation events and increase adoption rates for existing and new services. Motive configures all necessary elements of an IP-based service through multiple fulfillment models, including web-only (or “CD-less”), CD-only, or a combination CD and web solution. Service Management Platform (SMP) The Motive Product Group software infrastructure for modeling services along with the management operations associated with endpoints on which the services depend. Example services include broadband, mobile, and FMC (fixed mobile convergence). In particular, operators use SMP to execute single endpoint operations (retrieve/configure) and to run end-to-end service diagnostic tests and automated actions for a given service subscription. The Service Management Platform includes a server runtime environment and several design-time tools. The server runtime environment is installed on a WebLogic Server domain with an Administration Server and a cluster of Managed Servers. The WebLogic Server domain is either a standalone domain for SMP or an existing domain on which one or more products run in addition to SMP. Depending on the solution and deployment, the Managed Servers may communicate with one or more data source servers such as device management servers referred to as managers and/or AquaLogic, MySQL, and Composite. The design-time tools include Model Builder, Overlay Builder, and Configuration Manager. These tools enable your team to author deployment-specific content based on supported services and endpoints. The resulting content is in the form of various models, overlays, and test modules, including those created for operation implementations. The builders are installed on the content author's desktop while the Configuration Manager is deployed on the Managed Servers in the server runtime environment. The Managed Servers also host SMP's Endpoint Operations, NBIService, and Policy web services. service name The name of an Oracle database as defined on the database host. On an Oracle client, a net service name maps to a service name, host name, port number, and protocol for a database. How this mapping is achieved depends on the naming method being used, but often the information is stored in the tnsnames.ora and configured using the Oracle Net Configuration Assistant or the Oracle Net Manager. set-top box (STB) A CPE (customer premises equipment) device for converting and displaying data from an IP network to a standard frequency (channel number) for display on a standard analog television set. See also IPTV (Internet Protocol Television). SMP Repository An operational database for storage and maintenance of the operation implementations and corresponding endpoint operations. The Endpoint Operations API gathers information from the SMP Repository in response to client requests. 190 Glossary SNMP (Simple Network Management Protocol) The protocol that governs network management and the monitoring of network devices and their functions. SNMP is not limited to TCP/IP networks. standard deployment The Home Device Manager architecture that includes a single WebLogic Server domain in the trusted network. The domain (HDMDomain) includes an Administration Server and a cluster of application servers (HDMCluster). Typically, the standard deployment also includes one or more Bastion Web Servers in a DMZ. A Bastion Web Server redirects device communication from the DMZ to the trusted network. Compare to distributed domain deployment. STUN (Simple Traversal of User Datagram Protocol (UDP) Through Network Address Translators (NATs)) Server An Internet-facing server that implements the STUN protocol to set up UDP communication with a device behind a NAT in the subscriber environment. The STUN Server creates the binding by informing a device (STUN client) of the type of NAT with which it is associated, along with the public IP address and port number for the NAT. The binding enables the Auto-configuration Server (ACS) to send connection requests for Inform messages to the STUN client through a UDP (User Datagram Protocol) Connection Request Proxy Server. subscriber In industry usage, an individual who pays for Internet access or other services from a provider. In Motive usage, an end-user who uses Motive software as a result of purchasing services from a provider. TCP Connection Request Proxy Server A Connection Request Proxy Server that passes connection requests from the Auto-configuration Server (ACS) to a TR-069 WAN-connected device. In turn, the device sends an Inform message to the ACS. telemetry Diagnostic data gathered from a subscriber system or backend system. For example, the amount of disk space is telemetry collected from the subscriber system, and outage status is telemetry collected from a backend system. Telemetry is the primary data source used to solve problems in the self-service and assisted service models. tenant A tenant is a subset of a carrier with its own optimal settings. For example, a single phone service carrier might want to apply different settings for customers in different companies, so it would set up a tenant for each country. test module A configuration that a client or an SMP API runs to execute a particular overlay and the model on which it is built. The test module defines the configuration that determines the manner in which the modeling process is executed. Deployment teams configure a test module through the Configuration Manager after having developed the associated model and overlay. TR-069 The CWMP protocol defined by the Broadband Forum. See the Broadband Forum [http://www.broadband-forum.org/] for the TR-069 report that documents the protocol. 191 TR-111 An extension of the Broadband Forum's TR-069 protocol for remotely managing devices connected to LANs through NATs. Examples of such devices include VoIP phones, media set-top boxes, and gaming systems. See the Broadband Forum [http://www.broadband-forum.org/] for the TR-111 report that documents the extension. Transfer Complete Inform message On devices that support the TR-069 protocol, an Inform message that occurs when a previously requested download or upload (successful, or unsuccessful) completes. UDP (User Datagram Protocol) Connection Request Proxy Server A Connection Request Proxy Server that implements the UDP protocol to pass connection requests from the Auto-configuration Server (ACS) to a TR-111 device. In turn, the device sends an Inform message to the ACS. The communication is possible as a result of the binding that a STUN Server creates on the device. Value Change Inform message On devices that support the TR-069 protocol, an Inform message that occurs based on a change to one of the parameter values included in the Inform message. The values included in the Inform message are described in the Broadband Forum TR-069 protocol specification. VoIP (voice over IP) IP telephony that enables making telephone calls through the Internet. WAN (wide area network) A computer network that spans a relatively large geographical area. Typically, a WAN consists of two or more local area networks (LANs). Web proxy tier Collective reference to any Bastion Web Servers and Connection Request Proxy Servers in a DMZ of a Home Device Manager deployment. See also protocol tier. WebLogic Administration Server See Administration Server. WebLogic Managed Server See Managed Server. WebLogic Server domain A logically related group of WebLogic Servers for management as a unit. The domain always includes a WebLogic Administration Server and additional WebLogic Server instances called Managed Servers. Wi-Fi (Wireless Fidelity) High-frequency WLAN. Wi-Fi is specified in the 802.11b specification from the IEEE [http://www.ieee.com] and is part of a series of wireless specifications together with 802.11, 802.11a, 802.11b, and 802.11g. All four standards use the Ethernet protocol and CSMA/CA (carrier sense multiple access with collision avoidance) for path sharing. 192 Glossary WiDM server A Motive product providing WiMAX device management via virtual server which uses the Service Management Platform to allow web service calls for WiMAX devices to be delivered to appropriate device manager products such as the Mobile Device Manager or Home Device Manager. WiMAX A fast wireless communications technology designed to enable the delivery of last-mile broadband access, and intended to serve as an alternative to cable or DSL . WLAN (wireless local area network) A LAN that sends and receives data through radio, infrared optical signals, or other technology. WLANs do not require a physical connection between the wireless device and the hub. zero-touch activation An activation scenario in which the device is provisioned without interaction from the end user, using data taken from the carrier's database of service plan information. 193 194 Glossary Index Symbols C .zip files, 82 AAA data source about, 144 connection parameters, 144 methods, 145 AAA server about, 7 data source, 144 environment properties, 66 integration, 166 security roles, 166 administration additional JDBC data sources, 136 deleting subscriber records, 102 maintaining modeling database, 134 purging snapshots and evaluated models, 134 restarting servers, 99 setting up sample purge script to run regularly, 134 Administration Server configuration properties, 43 application properties, 111 AquaLogic data source Administration Server, 31, 36 configuration properties, 49 defining installation path, 20 assignCPProfile method, MDM data source, 154 assignImageToDevice method, MDM data source, 154 assignInitialPolicy method, MDM data source, 155 assignProfile method, MDM data source, 155 assignProfileSync method, MDM data source, 155 caching, 58 cluster properties, 44 Composite data source Administration Server, 31, 36 configuration properties, 51 defining installation path, 20 configuration Administration Server, 43 allowed thread times, 47 applications for, 98 AquaLogic data source, 49 cluster, 44 Configuration Manager, 98 custom keystores, 46 domain, 41 existing domain, 41 heavyweight health check, 111 installer.properties file, 41 JMS settings, 47 Managed Server, 45 modeling schema, 47 Node Manager, 45 performance, 62 security, 102 SSL, 21 Tenant Management Console, 98 work manager settings, 47 conventions documentation, ix Customer Service Console deploying, 58 development, 58 B D BEA license, 21 BEA WebLogic (see WebLogic) BIRT logging, 122 data sources AquaLogic, 20, 31, 36, 49 Composite, 20, 31, 36, 51 deleteSubscriber method, MDM data source, 156 A 195 deleteUser method, AAA data source, 145 deployment, 67 configuring environment properties, 66 Customer Service Console, 58 enable/disable device operations, 108 pre-configure additional data sources, 60 prerequisites for Motive Reporting application, 78 preview, 4 troubleshooting, 74 unpacking reference application, 59 validating, 62 WiDM Server applications, 60 device management servers understanding, 10 device operations enable/disable, by user role, 108 deviceOffline method, MDM data source, 168 deviceOnline method, MDM data source, 167 diagrams, 9 disconnectDevice method, AAA data source, 145 H health check about, 109 heavyweight about, 110 configuring, 111 modifying, 112 XML output, 112 lightweight, 109 Home Device Manager, 10 configuration, 72 I ID E environment properties configuring, 66 list, 67 troubleshooting, 74 EPFIRMWARELATESTVERSION ID, 180 IMAGE_EXTERNAL_ID, 180 MANUFACTURERID, 180 MODELID, 180 PLATFORMID, 180 executeCommandScript method, MDM data source, 156 executeCommandScriptSync method, MDM data source, 156 existing domain (see Option 1 installation) F firmware updates, 70 G getAttributes method, MDM data source, 157 getCachedAttributes method, MDM data source, 157 getCompatibleImagesForDevice method, MDM data source, 157 196 getDeviceTreeForProfile method, MDM data source, 158 getFirmwareVersionForDevice method, MDM data source, 158 getUpdatePathsForDeviceAndImage method, MDM data source, 159 getUser method, AAA data source, 146 Index EPFIRMWARELATESTVERSION, 180 IMAGE_EXTERNAL_ID EPFIRMWARELATESTVERSION, 180 importing reports, 82 insertUser method, AAA data source, 146 installation BEA license, 21 creating modeling schema, 26 keystores, 21, 22 Managed Server instances, 31 Option 1 checkpoints, 33 Option 2 checkpoints, 40 post-installation configuration, 66 pre-installation checkpoints, 20 prerequisites for Motive Reporting application, 78 preview, 4 SSL configuration, 21, 22 understanding the installer.properties file, 41 uninstalling, 88 updating existing domain and Administration Server, 35 updating existing Managed Servers, 37 WiMAX domain and Administration Server, 30 WiMAX runtime environment, 20 installer.properties file, 41 invokeDiscoveryForProfile method, MDM data source, 159 invokeDiscoveryForProfileSync method, MDM data source, 160 isAvailable method, AAA data source, 147 isAvailable method, MDM data source, 160 isValidLogin method, AAA data source, 147 isValidPhone method, MDM data source, 160 J JDBC data sources, 60, 136 JMS configuration properties, 47 JNDI connection URL, 69 K keystores, 21, 22 L Licensing about, 11 installing, 73 loading reports, 82 logging BIRT engine, 122 reporting console, 121 server-side, 58 services, 121 logging on to the reporting console, 118 M Managed Server configuration properties, 45 managed servers, 102 MANUFACTURERID EPFIRMWARELATESTVERSION, 180 MDM data source about, 152 connection parameters, 152 getting data, 153 methods, 154 sync methods explained, 153 Mobile Device Manager, 10 MODELID EPFIRMWARELATESTVERSION, 180 modeling schema configuration properties, 47 creating, 26 N Node Manager configuration properties, 45 stopping, 101 O Option 1 installation checkpoints, 33 creating modeling schema, 26 introduction, 30 Option 2 installation checkpoints, 40 creating modeling schema, 26 introduction, 35 Oracle database JDBC data source pools, 60 P PLATFORMID EPFIRMWARELATESTVERSION, 180 populateCachedAttributes method, MDM data source, 160 populateCachedAttributesSync method, MDM data source, 161 post-installation, 66, 69, 70, 72, 73 precompiling, 58 product versions, 94 ProvisionEndpoint operation, 172 ProvisionHSD operation, 172 ProvisioningComplete operation, 176 ProvisionLock operation, 174 ProvisionVOIP operation, 174 purging snapshots and evaluated models, 134 R rebootstrapSubscriber method, MDM data source, 161 registerForDeviceStatus method, AAA data source, 147 reporting console logging, 121 logon, 118 reports importing, 82 runtime environment installing, 20 197 S V Schema reference, 180 EPFIRMWARELATESTVERSION, 180 security configuration, 102 default objects, 103 groups, 104 roles, 104 setting up a new user, 107 test modules, 105 users, 103 security roles, 166 servers, 99, 113 Service Management Platform understanding, 9 solution diagrams, 9 SSL configuration, 21, 22, 46 starting servers, 100 stopping servers, 99 Subscription Portal, 70 versions checking product versions, 94 T templates, 7 test modules performance, 62 security, 105 thread times allowed, 47 troubleshooting, 74, 109, 113 U UI_ETLADMIN_EXECUTE, 118 UI_ETLADMIN_READ, 118 UI_REPORT_DELETE, 119 UI_REPORT_EDIT, 119 UI_REPORT_EXPORT, 119 UI_REPORT_READ, 119 uninstalling, 88 unregisterForDeviceStatus method, AAA data source, 148 UpdateToLatestFirmware operation, 176 updateUser method, AAA data source, 148 users adding new, 107 security, 103 198 Index W waitForJobs method, MDM data source, 161 WebLogic adding new managed servers, 102 logging into the console, 98 WiDM server understanding, 6, 9 WiMAX.ear confirming prerequisites for deploying Motive Reporting, 78 work manager configuration, 47