ibm rma userguide

Remote Management Agent

User's GuideVersion 2 Release 6

GC30-4106-10

��

NoteBefore using this information and the product it supports, be sure to read the general information under “Notices” on page257.

August 2010

This edition applies to Version 2 Release 6 of the licensed program IBM Remote Management Agent (programnumber 5639-FF1) and to all subsequent releases and modifications until otherwise indicated in new editions.

This edition replaces GC30-4106-09.

Current versions of Retail Store Solutions documentation are available on the IBM Retail Store Solutions Web site atwww.ibm.com/solutions/retail/store/support. Click Publications.

A form for reader's comments is also provided at the back of this publication. If the form has been removed, addressyour comments to:

IBM CorporationRetail Store Solutions Information DevelopmentDepartment ZBDAPO Box 12195Research Triangle Park, North Carolina 27709 USA

When you send information to IBM, you grant IBM a nonexclusive right to use or distribute whatever information yousupply in any way it believes appropriate without incurring any obligation to you.

© Copyright IBM Corporation 2004, 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

|

||

|

||

||

|||||

||

http://www.ibm.com/solutions/retail/store/support

Contents

Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix

Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

About this guide . . . . . . . . . . . . . . . . . . . . . . . . xvWho should read this guide . . . . . . . . . . . . . . . . . . . . xvHow this guide is organized . . . . . . . . . . . . . . . . . . . . xvConventions used in this guide . . . . . . . . . . . . . . . . . . . xviRelated publications . . . . . . . . . . . . . . . . . . . . . . . xviProviding feedback . . . . . . . . . . . . . . . . . . . . . . . xvii

Summary of changes . . . . . . . . . . . . . . . . . . . . . . xixWeb-only update of GC30-4106-09 . . . . . . . . . . . . . . . . . xixWeb-only update of GC30-4106-08 . . . . . . . . . . . . . . . . . xixWeb-only update of GC30-4106-07 . . . . . . . . . . . . . . . . . xixWeb-only update of GC30-4106-06 . . . . . . . . . . . . . . . . . xixWeb-only update of GC30-4106-05 . . . . . . . . . . . . . . . . . xxWeb-only update of GC30-4106-04 . . . . . . . . . . . . . . . . . xx

Part 1. Introducing IBM Remote Management Agent . . . . . . . . . . . . . . 1

Chapter 1. Retail systems management . . . . . . . . . . . . . . . 3The need for systems management. . . . . . . . . . . . . . . . . . 3The importance of standards . . . . . . . . . . . . . . . . . . . . 4Management solutions . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. RMA Overview . . . . . . . . . . . . . . . . . . . . . 5Power management . . . . . . . . . . . . . . . . . . . . . . . 5Events Management . . . . . . . . . . . . . . . . . . . . . . . 5Software distribution . . . . . . . . . . . . . . . . . . . . . . . 5Inventory and Asset tracking . . . . . . . . . . . . . . . . . . . . 6Monitoring Retail Systems . . . . . . . . . . . . . . . . . . . . . 6Diagnostic data capture . . . . . . . . . . . . . . . . . . . . . . 6Retail peripheral management . . . . . . . . . . . . . . . . . . . . 6File transfer . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 3. Infrastructure components . . . . . . . . . . . . . . . . 7

Chapter 4. Deployment scenarios. . . . . . . . . . . . . . . . . . 9Small enterprise scenario . . . . . . . . . . . . . . . . . . . . . 10Medium enterprise scenario . . . . . . . . . . . . . . . . . . . . 11Large enterprise scenario . . . . . . . . . . . . . . . . . . . . . 11

Part 2. Installing and using the IBM Remote Management Agent . . . . . . . . 13

Chapter 5. RMA Requirements . . . . . . . . . . . . . . . . . . 17Hardware requirements . . . . . . . . . . . . . . . . . . . . . . 17Software requirements . . . . . . . . . . . . . . . . . . . . . . 17

Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Supported operating systems . . . . . . . . . . . . . . . . . . 17IBM Director . . . . . . . . . . . . . . . . . . . . . . . . . 18Installation roles . . . . . . . . . . . . . . . . . . . . . . . 18

© Copyright IBM Corp. 2004, 2010 iii

||

Network Configuration Requirements . . . . . . . . . . . . . . . . 18

Chapter 6. Understanding RMA Security . . . . . . . . . . . . . . 19Master Agent Security Modes . . . . . . . . . . . . . . . . . . . 19

Installation and upgrades . . . . . . . . . . . . . . . . . . . . 19Security groups. . . . . . . . . . . . . . . . . . . . . . . . 19

General Agent Security . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 7. Installing the Remote Management General Agent and MasterAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Interactive installation on Windows . . . . . . . . . . . . . . . . . 21Installation procedure . . . . . . . . . . . . . . . . . . . . . 21

Interactive installation on Linux . . . . . . . . . . . . . . . . . . . 27Linux prerequisites . . . . . . . . . . . . . . . . . . . . . . 27Small Footprint CIM Broker . . . . . . . . . . . . . . . . . . . 27Installation procedure . . . . . . . . . . . . . . . . . . . . . 29

Silent installation of the Remote Management Agent on Windows . . . . . . 304690 OS installation . . . . . . . . . . . . . . . . . . . . . . . 30Updating RMA . . . . . . . . . . . . . . . . . . . . . . . . . 30

Package import. . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 8. Installing Retail Extensions for IBM Director . . . . . . . . 33Interactive installation for Windows . . . . . . . . . . . . . . . . . 33Interactive installation for Linux . . . . . . . . . . . . . . . . . . . 34Silent installation of the Retail Extensions for IBM Director for Windows and

Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 9. Uninstalling IBM Remote Management Agent . . . . . . . . 37Interactive uninstallation for Windows . . . . . . . . . . . . . . . . 37Silent uninstallation for Windows . . . . . . . . . . . . . . . . . . 38Uninstallation for Linux . . . . . . . . . . . . . . . . . . . . . . 39Uninstallation result . . . . . . . . . . . . . . . . . . . . . . . 39Retail Extensions for IBM Director uninstallation notes . . . . . . . . . . 39

Chapter 10. Agent configuration . . . . . . . . . . . . . . . . . . 41Directory structure. . . . . . . . . . . . . . . . . . . . . . . . 41

Agent configuration file . . . . . . . . . . . . . . . . . . . . . 41Security configuration . . . . . . . . . . . . . . . . . . . . . 43SSL configuration . . . . . . . . . . . . . . . . . . . . . . . 44Updating SSL certificates . . . . . . . . . . . . . . . . . . . . 45Agent class path and environment . . . . . . . . . . . . . . . . . 46Logging configuration . . . . . . . . . . . . . . . . . . . . . 47Agent startup sequence . . . . . . . . . . . . . . . . . . . . 50Agent roles . . . . . . . . . . . . . . . . . . . . . . . . . 52Agent Windows event log integration . . . . . . . . . . . . . . . . 52

Chapter 11. Using Retail Extensions for IBM Director . . . . . . . . . 59IBM Director Console . . . . . . . . . . . . . . . . . . . . . . 60

Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Managed Objects . . . . . . . . . . . . . . . . . . . . . . . 62Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 67Discovery Preferences panel . . . . . . . . . . . . . . . . . . . 67Starting Discovery. . . . . . . . . . . . . . . . . . . . . . . 71

Store Authorization Management task . . . . . . . . . . . . . . . . 72Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

iv RMA V2R6 User's Guide

||||||||||

Inventory collection . . . . . . . . . . . . . . . . . . . . . . 74Viewing inventory . . . . . . . . . . . . . . . . . . . . . . . 74

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Event log . . . . . . . . . . . . . . . . . . . . . . . . . . 75Event action plans . . . . . . . . . . . . . . . . . . . . . . 75

Software distribution . . . . . . . . . . . . . . . . . . . . . . . 78RMA Software Package Editor . . . . . . . . . . . . . . . . . . 79Editing a software package . . . . . . . . . . . . . . . . . . . 80RMA Software Distribution 4690 Command Wizard . . . . . . . . . . 87Software package subtasks . . . . . . . . . . . . . . . . . . . 93

RMA File Transfer task . . . . . . . . . . . . . . . . . . . . . . 95Task invocation . . . . . . . . . . . . . . . . . . . . . . . . 95

JMX Browser task. . . . . . . . . . . . . . . . . . . . . . . . 95JMX tree panel . . . . . . . . . . . . . . . . . . . . . . . . 96Instance panel . . . . . . . . . . . . . . . . . . . . . . . . 97Method Execution dialog . . . . . . . . . . . . . . . . . . . . 99

Adjusting the handler and logger levels using JMX Browser . . . . . . . . 102Resource Monitors . . . . . . . . . . . . . . . . . . . . . . . 103

Creating a Threshold Monitor . . . . . . . . . . . . . . . . . . 104Creating a Recording Monitor . . . . . . . . . . . . . . . . . . 108

User-Defined Monitors . . . . . . . . . . . . . . . . . . . . . . 110Importing threshold plan files . . . . . . . . . . . . . . . . . . . 113Retail Peripheral Management . . . . . . . . . . . . . . . . . . . 113

Retail Peripheral Management Console . . . . . . . . . . . . . . 114Data Capture Policy Manager task . . . . . . . . . . . . . . . . . 117

Data Capture Policy Manager . . . . . . . . . . . . . . . . . . 118Data Capture Policies . . . . . . . . . . . . . . . . . . . . . 131Status Frame for Data Capture Policies . . . . . . . . . . . . . . 134

Power management . . . . . . . . . . . . . . . . . . . . . . 138

Chapter 12. Troubleshooting . . . . . . . . . . . . . . . . . . . 143Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

RMA Agents . . . . . . . . . . . . . . . . . . . . . . . . 143Agent JVM Diagnostics . . . . . . . . . . . . . . . . . . . . 143IBM Director . . . . . . . . . . . . . . . . . . . . . . . . 144

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 146

Part 3. Objectives and architecture . . . . . . . . . . . . . . . . . . . . . 147

Chapter 13. Architecture overview and objectives . . . . . . . . . . 149IBM Remote Management Agent disciplines. . . . . . . . . . . . . . 149Java Management Extensions . . . . . . . . . . . . . . . . . . . 149Mid-level management . . . . . . . . . . . . . . . . . . . . . 150Management model. . . . . . . . . . . . . . . . . . . . . . . 151

Chapter 14. Understanding the architecture . . . . . . . . . . . . . 153RMA Component. . . . . . . . . . . . . . . . . . . . . . . . 153

General Agent. . . . . . . . . . . . . . . . . . . . . . . . 153Master Agent . . . . . . . . . . . . . . . . . . . . . . . . 153

Component's relationship and roles . . . . . . . . . . . . . . . . . 154Agent discovery and health checking . . . . . . . . . . . . . . . . 154

MgmtMasterHealthMBean . . . . . . . . . . . . . . . . . . . 154MgmtClientHealthMBean . . . . . . . . . . . . . . . . . . . . 154Agent application roles . . . . . . . . . . . . . . . . . . . . 155

Embedded Agent (General Agent) . . . . . . . . . . . . . . . . . 156Proxy ObjectNames . . . . . . . . . . . . . . . . . . . . . 157

Contents v

||||

JMX Browser Changes for Local Mode Embedded Agents . . . . . . . 158RMA event infrastructure . . . . . . . . . . . . . . . . . . . . . 159

RMA events (RtlNotifications) . . . . . . . . . . . . . . . . . . 160EventControlMBean . . . . . . . . . . . . . . . . . . . . . 161NotificationProcessor . . . . . . . . . . . . . . . . . . . . . 162MgmtNotificationControlMBean . . . . . . . . . . . . . . . . . 162

Logging configuration and forwarding . . . . . . . . . . . . . . . . 162Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . 163CIM Implementation . . . . . . . . . . . . . . . . . . . . . . 163

CIM Adapter MBean . . . . . . . . . . . . . . . . . . . . . 164CIMEventMapper interface . . . . . . . . . . . . . . . . . . . 165CIM configuration . . . . . . . . . . . . . . . . . . . . . . 167

File Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 168FileTransferConnection . . . . . . . . . . . . . . . . . . . . 169Managing file transfer implementations . . . . . . . . . . . . . . 170Storage . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Monitor policy . . . . . . . . . . . . . . . . . . . . . . . . . 171RMA Software Distribution . . . . . . . . . . . . . . . . . . . . 172

RMA Package Distributor MBean. . . . . . . . . . . . . . . . . 174Software Distribution Policy . . . . . . . . . . . . . . . . . . . 178

Diagnostic Data Capture . . . . . . . . . . . . . . . . . . . . . 184DataCaptureMBean. . . . . . . . . . . . . . . . . . . . . . 185DataCaptureMBeanSupport . . . . . . . . . . . . . . . . . . . 187Data Capture Policy . . . . . . . . . . . . . . . . . . . . . 188RMADataCaptureMBean . . . . . . . . . . . . . . . . . . . . 189DataCaptureManagerMBean . . . . . . . . . . . . . . . . . . 189

Part 4. Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195

Chapter 15. Development environment . . . . . . . . . . . . . . . 197Setting up the development environment . . . . . . . . . . . . . . . 197

Chapter 16. Programming examples . . . . . . . . . . . . . . . . 199Working With Files . . . . . . . . . . . . . . . . . . . . . . . 199Writing and registering your own MBeans . . . . . . . . . . . . . . 199

Exposing a management interface . . . . . . . . . . . . . . . . 199MBean Object Naming . . . . . . . . . . . . . . . . . . . . 200MBean registration . . . . . . . . . . . . . . . . . . . . . . 202Distributing the MBean classes . . . . . . . . . . . . . . . . . 204

Making a Remote JMX Connection to the Master Agent . . . . . . . . . 204Accessing MBean instrumentation . . . . . . . . . . . . . . . . 208Retrieving Store Events (Notifications) . . . . . . . . . . . . . . . 210

Using the FileTransferConnection interface . . . . . . . . . . . . . . 214Common properties. . . . . . . . . . . . . . . . . . . . . . 215Transfer types. . . . . . . . . . . . . . . . . . . . . . . . 216Transfer progress . . . . . . . . . . . . . . . . . . . . . . 217

Managing monitor policies . . . . . . . . . . . . . . . . . . . . 218MonitorPolicy object . . . . . . . . . . . . . . . . . . . . . 218MonitorPolicyAction object . . . . . . . . . . . . . . . . . . . 218

Managing data capture policies . . . . . . . . . . . . . . . . . . 219Creating, Adding, and Activating a Capture Policy . . . . . . . . . . 219Receiving Capture Completion Notifications . . . . . . . . . . . . . 221Querying Invocation History . . . . . . . . . . . . . . . . . . . 221Terminating and Deleting a Data Capture Policy . . . . . . . . . . . 222

Managing software distribution policies . . . . . . . . . . . . . . . 222Registering draft policies . . . . . . . . . . . . . . . . . . . . 223

vi RMA V2R6 User's Guide

||

State and progress notifications . . . . . . . . . . . . . . . . . 224Activating a draft policy . . . . . . . . . . . . . . . . . . . . 225Policy invocation history and status . . . . . . . . . . . . . . . . 225Terminating and deleting a Policy. . . . . . . . . . . . . . . . . 226

SystemStateManager . . . . . . . . . . . . . . . . . . . . . . 227SystemStateChangeListener and SystemStateChange Notifications . . . . 227SystemStateHandler . . . . . . . . . . . . . . . . . . . . . 227

Coding best practices . . . . . . . . . . . . . . . . . . . . . . 228Using error logging . . . . . . . . . . . . . . . . . . . . . . 228Controlling error log output . . . . . . . . . . . . . . . . . . . 229Error log entry contents . . . . . . . . . . . . . . . . . . . . 230

Appendix A. Javadoc pdf file . . . . . . . . . . . . . . . . . . 231

Appendix B. Inventory tables . . . . . . . . . . . . . . . . . . 233

Appendix C. UPOS Inventory Table Definitions . . . . . . . . . . . 235General Properties Table . . . . . . . . . . . . . . . . . . . . . 235Device Capabilities Tables . . . . . . . . . . . . . . . . . . . . 235Device Properties Tables . . . . . . . . . . . . . . . . . . . . . 242

Appendix D. JMX Browser Plug-Ins . . . . . . . . . . . . . . . . 249Create a JMX Monitor Policy . . . . . . . . . . . . . . . . . . . 249Monitor Policy Wizard . . . . . . . . . . . . . . . . . . . . . . 249

Counter Monitor advanced options . . . . . . . . . . . . . . . . 251Gauge Monitor advanced options. . . . . . . . . . . . . . . . . 251String Monitor advanced options . . . . . . . . . . . . . . . . . 252Boolean Monitor advanced options . . . . . . . . . . . . . . . . 253Apply Monitor Policy dialog . . . . . . . . . . . . . . . . . . . 254

Monitor Manager plug-in . . . . . . . . . . . . . . . . . . . . . 255Policies tab . . . . . . . . . . . . . . . . . . . . . . . . . 255Applied Policies tab. . . . . . . . . . . . . . . . . . . . . . 256

Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 257Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 257

Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

Contents vii

viii RMA V2R6 User's Guide

Figures

1. RMA infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72. Small enterprise deployment scenario . . . . . . . . . . . . . . . . . . . . . . . 103. Medium enterprise deployment scenario . . . . . . . . . . . . . . . . . . . . . . 114. Lock icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205. IBM Remote Management Agent components for a Windows installation . . . . . . . . . . 226. Network interface panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237. Security mode panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248. Summary panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259. Post installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

10. Summary information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3411. Remove installation directory dialog . . . . . . . . . . . . . . . . . . . . . . . . 3712. Remove user directory dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 3813. Java logging hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4714. Sample Windows Application event . . . . . . . . . . . . . . . . . . . . . . . . 5715. Sample Windows Application event viewed in IBM Director . . . . . . . . . . . . . . . 5816. IBM Director Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6017. Dynamic group editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6218. Display System Attributes panel . . . . . . . . . . . . . . . . . . . . . . . . . 6519. Discovery Preferences panel . . . . . . . . . . . . . . . . . . . . . . . . . . 6720. Define Master Agent Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 6821. Store Authorization Management task window . . . . . . . . . . . . . . . . . . . . 7222. Store Authorization Management credentials dialog . . . . . . . . . . . . . . . . . . 7323. Select Client Authentication Key File . . . . . . . . . . . . . . . . . . . . . . . 7324. Inventory collection panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . 7425. Viewing inventory browser . . . . . . . . . . . . . . . . . . . . . . . . . . . 7526. Simple Event Filter Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . 7627. Event filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7728. Newly created Event Action Plan appears in the Tasks frame . . . . . . . . . . . . . . 7729. RMA Software Distribution task . . . . . . . . . . . . . . . . . . . . . . . . . 8030. Install Package Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8131. Operating system settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 8232. RMA Software Distribution File Selection panel . . . . . . . . . . . . . . . . . . . . 8333. Package Commands dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 8434. RMA Software Distribution Add Program dialog. . . . . . . . . . . . . . . . . . . . 8435. RMA Software Distribution progress panel . . . . . . . . . . . . . . . . . . . . . 8636. Software package subtasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 8737. 4690 Package Commands dialog . . . . . . . . . . . . . . . . . . . . . . . . . 8738. 4690 Package Commands dialog . . . . . . . . . . . . . . . . . . . . . . . . . 8839. 4690 Create Command dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 8940. 4690 Create Command (manually) dialog . . . . . . . . . . . . . . . . . . . . . . 8941. Re-IPL dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9042. Re-IPL window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9043. Custom ASM Package dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 9144. ASM product state dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9145. Product options dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9246. Editing a command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9247. Import RMA Software Distribution Package dialog. . . . . . . . . . . . . . . . . . . 9448. Export RMA Software Distribution Package dialog. . . . . . . . . . . . . . . . . . . 9449. JMX tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9650. Properties tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9751. Set Value dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9852. Methods tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9853. Unsupported Method dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

© Copyright IBM Corp. 2004, 2010 ix

||

54. Method Execution dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 10055. Saved JMX Method task . . . . . . . . . . . . . . . . . . . . . . . . . . . 10156. Handler levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10257. Logger levels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10358. Resource Monitor task . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10459. Selecting Disk Utilization resource . . . . . . . . . . . . . . . . . . . . . . . . 10460. Selecting Individual Threshold . . . . . . . . . . . . . . . . . . . . . . . . . 10561. Threshold configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10662. Example Threshold Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 10763. All Available Thresholds view . . . . . . . . . . . . . . . . . . . . . . . . . . 10864. Selecting Use Disk Space resource . . . . . . . . . . . . . . . . . . . . . . . 10865. Selecting Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10966. Creating a new record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10967. Example Recording Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 11068. All Available Recordings view . . . . . . . . . . . . . . . . . . . . . . . . . . 11069. JMX Browser task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11170. Selecting Add User-Defined Resource Monitor . . . . . . . . . . . . . . . . . . . 11271. Creating a new user-defined resource monitor . . . . . . . . . . . . . . . . . . . 11272. User-defined Monitors view . . . . . . . . . . . . . . . . . . . . . . . . . . 11373. Retail Peripheral Management Console (MSR selected) . . . . . . . . . . . . . . . . 11474. Retail Peripheral Management Console (using Group by Model) . . . . . . . . . . . . . 11775. Peripheral Inventory Query Browser for POS Printer . . . . . . . . . . . . . . . . . 11776. Data Capture Policy Manager task . . . . . . . . . . . . . . . . . . . . . . . . 11877. Data Capture Policy Manager frame . . . . . . . . . . . . . . . . . . . . . . . 11978. Data Capture Policy Manager File Menu. . . . . . . . . . . . . . . . . . . . . . 12079. Data Capture Policy Manager File-Close Dialog . . . . . . . . . . . . . . . . . . . 12080. Capture Policy Manager Help Menu . . . . . . . . . . . . . . . . . . . . . . . 12181. Data Capture Policy Manager Policy Group Dialog . . . . . . . . . . . . . . . . . . 12282. Data Capture Policy Group Context Menu . . . . . . . . . . . . . . . . . . . . . 12283. Data Capture Policy Create/Rename Dialog . . . . . . . . . . . . . . . . . . . . 12384. Data Capture Policy Context Menu. . . . . . . . . . . . . . . . . . . . . . . . 12485. Data Capture All Policies Group Context Menu . . . . . . . . . . . . . . . . . . . 12586. Data Capture Policy Manager Export Dialog . . . . . . . . . . . . . . . . . . . . 12687. Data Capture Policy Manager Import Dialog . . . . . . . . . . . . . . . . . . . . 12788. Data Capture Policy Manager Find Dialog . . . . . . . . . . . . . . . . . . . . . 12789. Data Capture Device Type right-click context menu. . . . . . . . . . . . . . . . . . 12890. Data Capture Policy List Folder right-click Context Menu. . . . . . . . . . . . . . . . 12891. Data Capture Implementation Group right-click context menu . . . . . . . . . . . . . . 13092. Data Capture Implementation Creation Dialog. . . . . . . . . . . . . . . . . . . . 13093. Data Capture Implementation right-click Context Menu . . . . . . . . . . . . . . . . 13194. IBM Director Console with Policy Subtasks . . . . . . . . . . . . . . . . . . . . . 13295. IBM Director Console with associated Policy Subtasks . . . . . . . . . . . . . . . . 13396. Policy Subtask Association right-click Context Menu . . . . . . . . . . . . . . . . . 13497. Policy Invocation Status Dialog . . . . . . . . . . . . . . . . . . . . . . . . . 13598. Policy Invocation Status Dialog - Loading Message. . . . . . . . . . . . . . . . . . 13599. Policy Invocation Status Dialog - Refresh . . . . . . . . . . . . . . . . . . . . . 136

100. Policy Invocation Status Dialog - Dialog Context Menu . . . . . . . . . . . . . . . . 137101. Policy Invocation Status frame - Transferring Message . . . . . . . . . . . . . . . . 138102. Power management shutdown and restart selections . . . . . . . . . . . . . . . . . 139103. Power management power on selections . . . . . . . . . . . . . . . . . . . . . 139104. Power management job example . . . . . . . . . . . . . . . . . . . . . . . . 140105. TWGRas.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145106. Mid-level management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150107. Embedded Agent model (Prior to V2R6) . . . . . . . . . . . . . . . . . . . . . . 156108. (V2R6 or later) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157109. Proxy Objectnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

x RMA V2R6 User's Guide

||||||

110. Event infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160111. CIM proxy MBeans for component names . . . . . . . . . . . . . . . . . . . . . 165112. File transfer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169113. Software distribution overview . . . . . . . . . . . . . . . . . . . . . . . . . 173114. RMA Package Distribution overview . . . . . . . . . . . . . . . . . . . . . . . 174115. Software policy distribution. . . . . . . . . . . . . . . . . . . . . . . . . . . 180116. Data capture processing . . . . . . . . . . . . . . . . . . . . . . . . . . . 186117. Data capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188118. DataCaptureManagerMBean . . . . . . . . . . . . . . . . . . . . . . . . . . 190119. Create Monitor menu option from the Instance panel . . . . . . . . . . . . . . . . . 249120. Monitor Policy Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250121. Counter Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . 251122. Gauge Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . . 252123. String Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . . 253124. Boolean Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . 254125. Apply Monitor Policy frame. . . . . . . . . . . . . . . . . . . . . . . . . . . 255126. Policies tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256127. Applied Policies tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Figures xi

xii RMA V2R6 User's Guide

Tables

1. Configuration subdirectory descriptions. . . . . . . . . . . . . . . . . . . . . . . 412. Agent properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413. RMI properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424. Event properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425. Event fetching properties (Master Agent only) . . . . . . . . . . . . . . . . . . . . 436. Data capture properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437. Java logging levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488. Configurable logging parameters . . . . . . . . . . . . . . . . . . . . . . . . . 499. XML definition of the agent configuration file for Windows event log integration . . . . . . . . 53

10. Mapping Windows event log definitions to RMA Notifications. . . . . . . . . . . . . . . 5611. Event type to severity mapping . . . . . . . . . . . . . . . . . . . . . . . . . 5612. Managed Object groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6113. Retail devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6314. Device states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6415. Import file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7016. Severity mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7817. Package general information . . . . . . . . . . . . . . . . . . . . . . . . . . 8018. RMA File Transfer task invocation support . . . . . . . . . . . . . . . . . . . . . 9519. Device types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11520. Power management support by Agent type . . . . . . . . . . . . . . . . . . . . . 14021. Common symptoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14622. IBM Remote Management Agent managed disciplines . . . . . . . . . . . . . . . . 14923. Logging MBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16324. Managing file transfer implementations . . . . . . . . . . . . . . . . . . . . . . 17025. Methods used for managing implementations . . . . . . . . . . . . . . . . . . . . 17026. Required properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17527. Valid platform names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17528. Valid system states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17529. SoftwarePolicy:Component tag attributes . . . . . . . . . . . . . . . . . . . . . 18230. SoftwarePolicy:Exec tag attributes . . . . . . . . . . . . . . . . . . . . . . . . 18331. Policy XML variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18432. javax.management.Notification fields . . . . . . . . . . . . . . . . . . . . . . . 18633. Common properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21534. RMA File Streaming Properties . . . . . . . . . . . . . . . . . . . . . . . . . 21535. FTPConnection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 21536. FTPSConnection properties . . . . . . . . . . . . . . . . . . . . . . . . . . 21637. Logging level functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22838. Log levels with sample log entries . . . . . . . . . . . . . . . . . . . . . . . . 22939. Inventory tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23340. General properties table. . . . . . . . . . . . . . . . . . . . . . . . . . . . 23541. Cash Changer Device Capabilities Table. . . . . . . . . . . . . . . . . . . . . . 23542. Cash Drawer Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 23643. Coin Dispenser Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . 23644. Check Scanner Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . 23645. Fiscal Printer Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 23746. Hard Totals Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . 23747. Line Display Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 23848. MSR Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . 23849. MICR Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . 23950. PIN Pad Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 23951. POS Keyboard Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . 23952. POS Power Device Capabilities Table. . . . . . . . . . . . . . . . . . . . . . . 23953. Scale Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . 240

© Copyright IBM Corp. 2004, 2010 xiii

54. Tone Indicator Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 24055. POS Printer General Device Capabilities Table . . . . . . . . . . . . . . . . . . . 24056. POS Printer Journal Station Capabilities Table . . . . . . . . . . . . . . . . . . . 24157. POS Printer Receipt Station Capabilities Table . . . . . . . . . . . . . . . . . . . 24158. POS Printer Slip Station Capabilities Table . . . . . . . . . . . . . . . . . . . . . 24259. Cash Changer Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 24260. Cash Drawer Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . 24361. Check Scanner Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 24362. Coin Dispenser Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 24363. Fiscal Printer Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . 24364. Line Display Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 24365. Hard Totals Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 24466. Keylock Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . . . 24467. MSR Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . . . . 24468. PIN Pad Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . . 24469. POS Keyboard Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 24570. POS Power Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 24571. Scale Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . . . 24572. POS Printer Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 24573. POS Printer Journal Station Properties Table . . . . . . . . . . . . . . . . . . . . 24574. POS Printer Receipt Station Properties Table . . . . . . . . . . . . . . . . . . . . 24675. POS Printer Slip Station Properties Table . . . . . . . . . . . . . . . . . . . . . 24676. Retail Display Properties Table . . . . . . . . . . . . . . . . . . . . . . . . . 247

xiv RMA V2R6 User's Guide

About this guide

This guide contains information to help you install, use, and configure the IBMRemote Management Agent (RMA) software product.

Who should read this guideThis guide is intended for programming personnel who are responsible for installing,using, troubleshooting, and configuring the IBM Remote Management Agent.

To plan and install system management facilities, a working knowledge of the Javaprogramming language and the Java Management Extensions (JMX) standard isrecommended.

How this guide is organizedThis guide consists of four parts:

v Part 1, “Introducing IBM Remote Management Agent,” on page 1 introduces theIBM Remote Management Agent and describes the needs for remotemanagement along with the benefits that RMA can provide. This section alsodiscusses common general deployment strategies.

– Chapter 1, “Retail systems management,” on page 3 explains the growingneed for system management because of the increasing number of devicesused throughout the retail environment.

– Chapter 2, “RMA Overview,” on page 5 explains how RMA provides supportfor the activities and disciplines that comprise system management.

– Chapter 3, “Infrastructure components,” on page 7 defines how RMA servesas a gateway to all store resources.

– Chapter 4, “Deployment scenarios,” on page 9 gives an overview of how RMAis deployed in enterprises of varying size and complexity.

v Part 2, “Installing and using the IBM Remote Management Agent,” on page 13describes how to install and use the RMA agents and the Retail Extensions forIBM® Director. It also provides examples on performing common managementtasks, such as monitoring and software distribution.

– Chapter 5, “RMA Requirements,” on page 17 list the requirements forinstalling the Remote Management Agent.

– Chapter 6, “Understanding RMA Security,” on page 19 discusses the twosecurity modes for Master Agents.

– Chapter 7, “Installing the Remote Management General Agent and MasterAgent,” on page 21 describes how to install the Remote Management GeneralAgent and Master Agent.

– Chapter 8, “Installing Retail Extensions for IBM Director,” on page 33describes the Retail Extensions for IBM Director.

– Chapter 9, “Uninstalling IBM Remote Management Agent,” on page 37describes the procedure for uninstalling the Remote Management Agent.

– Chapter 10, “Agent configuration,” on page 41 describes configurationprocesses to perform after installation is complete.

– Chapter 11, “Using Retail Extensions for IBM Director,” on page 59 providesinformation on how to use the Retail Extensions for IBM Director.

– Chapter 12, “Troubleshooting,” on page 143 describes some commonproblems and solutions.

© Copyright IBM Corp. 2004, 2010 xv

v Part 3, “Objectives and architecture,” on page 147 describes the architecture ofthe RMA agents in order to provide the necessary background information forwriting management applications using the RMA programming interfaces.

– Chapter 13, “Architecture overview and objectives,” on page 149 contains ahigh-level overview of the objectives and architecture of the RemoteManagement Agent.

– Chapter 14, “Understanding the architecture,” on page 153 presents a moredetailed discussion of the Remote Management Agent architecture.

v Part 4, “Programming,” on page 195 describes how to use the RMA programminginterfaces to extend RMA with your own Java Managed Beans (MBeans) or towrite management applications that manage store resources.

– Chapter 15, “Development environment,” on page 197 discusses thedevelopment environment.

– Chapter 16, “Programming examples,” on page 199 gives specificexplanations and examples of programming with the IBM RemoteManagement Agent Application Programming Interface (API).

v Part 5 contains the appendixes, including reference to the Javadoc.pdf file, atable of inventory information that IBM Director provides and which RMA supportsby device type.

– Appendix A, “Javadoc pdf file,” on page 231 provides information on using theRMAJavadoc.pdf file.

– Appendix B, “Inventory tables,” on page 233 provides a list of inventoryinformation that IBM Director provides and supports, based on the devicetype.

– Appendix C, “UPOS Inventory Table Definitions,” on page 235 includes thetables that are defined for the Unified Point of Service (UPOS) inventory.

– Appendix D, “JMX Browser Plug-Ins,” on page 249 provide legacy proceduresfor creating the JMX monitors (pre-V2R3).

v “Notices” on page 257 contains important notices and trademark information.

Conventions used in this guideThe following conventions are used throughout this document:

environment variablesThis document uses percent signs (%VAR%) to designate environmentvariables in Windows, and it uses $VAR to designate environment variablesin Linux.. Follow the appropriate format for your operating system.

Related publicationsThe following IBM publications provide additional information on using the IBMRemote Management Agent. You can download these publications from the IBMRetail Store Solutions Web site at www.ibm.com/solutions/retail/store/support.

v IBM 4690 OS User's Guide, G362-0542

v IBM 4690 OS Programming Guide, G362-0545

v IBM 4690 OS Communications Programming Reference, G362-0544

v Store Integrator User's Guide, SC30-4085

v Store Integrator Programming Guide, SC30-4084

v Store Integrator Graphical User Interface Programming Guide, GC30-4121

v Data Integration Facility User's Guide, GC30-4077

xvi RMA V2R6 User's Guide

v Unified Point of Sale (UPOS) publications at http://www-1.ibm.com/support/search.wss?rs=219&q=PUBUPOS.

v IBM Director publications at http://publib.boulder.ibm.com/infocenter/eserver/v1r2/index.jsp?topic=/diricinfo_all/diricinfoparent.html.

Providing feedbackYour feedback is important in helping IBM provide accurate and high-qualityinformation.

To provide feedback:

v Go to http://www.ibm.com/solutions/retail/store. Click Support, then clickPublications. Click the publication comments within the introductory text.Provide the requested information and your comments. Be sure to include thename and form number of the document in the [Publication ID] field.

v You can mail your comments to:IBM Corporation Retail Store SolutionsInformation Development Department ZBDAP.O. Box 12195 Research Triangle Park,North Carolina 27709 USA

Be sure to include the name and form number of the document.

If applicable, include a reference to the specific location of the text (for example, thepage or table number) on which you are commenting.

Between major revisions of this document, there might be minor technical updates.The latest version of this document is available on the Retail Store Solutions Website at www.ibm.com/solutions/retail/store/support/publications/.

About this guide xvii

http://www-1.ibm.com/support/search.wss?rs=219&q=PUBUPOS

http://www-1.ibm.com/support/search.wss?rs=219&q=PUBUPOS

http://publib.boulder.ibm.com/infocenter/eserver/v1r2/index.jsp?topic=/diricinfo_all/diricinfoparent.html

http://publib.boulder.ibm.com/infocenter/eserver/v1r2/index.jsp?topic=/diricinfo_all/diricinfoparent.html

xviii RMA V2R6 User's Guide

Summary of changes

Web-only update of GC30-4106-09This update documents the changes to the IBM Remote Management Agent guidesince the previous version of this publication:

v RMA security function enhancement

v Publishing custom event types

v New RPM pacakage (sblim-cmpi-smbios)

v Embedded Agents function

v Mbean registration

All changes related to this version are marked with a bar ( | ) revision code.

Web-only update of GC30-4106-08This update documents the following changes to the IBM Remote ManagementAgent since the previous version of this publication:

v Support for remote file operations

v Integration with the Windows Event Log Service

v Support for Windows 7

v Support for Java 6

v Hostname resolution for discovering Master Agents (DHCP support for MasterAgents)

v Performance and serviceability improvements

v Improved system inventory coverage

All changes related to this version are marked with bars ( | ).


v Network Configuration Requirements

v Updating SSL Certificates

v Table updates

v Figure updates

All changes related to this version are marked with bars ( | ).


v Master Agent Security Modes

v Windows Hotfix (QFE) Information Added to Inventory

v Suspend support on Windows

v New supported platforms for IBM Director: IBM Director Server 5.20.3, WindowsServer 2003 x64

© Copyright IBM Corp. 2004, 2010 xix

|

||

|

|

|

|

|

|

v New supported platforms for General Agent: POSReady 2009, SUSE LinuxEnvironment Desktop (SLED) 11

v New supported platforms for Master Agent: POSReady 2009, SLED 11

v Unified POS 1.12 Support

v UPOS Common Information Model (CIM) Event Support for Linux (SLED 11)


v Power management support

v Support for running on a 4690 Operating System (OS) V6 controller


v CIM Event Support

v Monitor integration with IBM Director

v Memory logging (serviceability enhancement)

xx RMA V2R6 User's Guide

Part 1. Introducing IBM Remote Management Agent

Chapter 1. Retail systems management . . . . . . . . . . . . . . . 3The need for systems management. . . . . . . . . . . . . . . . . . 3The importance of standards . . . . . . . . . . . . . . . . . . . . 4Management solutions . . . . . . . . . . . . . . . . . . . . . . 4

Chapter 2. RMA Overview . . . . . . . . . . . . . . . . . . . . . 5Power management . . . . . . . . . . . . . . . . . . . . . . . 5Events Management . . . . . . . . . . . . . . . . . . . . . . . 5Software distribution . . . . . . . . . . . . . . . . . . . . . . . 5Inventory and Asset tracking . . . . . . . . . . . . . . . . . . . . 6Monitoring Retail Systems . . . . . . . . . . . . . . . . . . . . . 6Diagnostic data capture . . . . . . . . . . . . . . . . . . . . . . 6Retail peripheral management . . . . . . . . . . . . . . . . . . . . 6File transfer . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Chapter 3. Infrastructure components . . . . . . . . . . . . . . . . 7

Chapter 4. Deployment scenarios. . . . . . . . . . . . . . . . . . 9Small enterprise scenario . . . . . . . . . . . . . . . . . . . . . 10Medium enterprise scenario . . . . . . . . . . . . . . . . . . . . 11Large enterprise scenario . . . . . . . . . . . . . . . . . . . . . 11

© Copyright IBM Corp. 2004, 2010 1

2 RMA V2R6 User's Guide

Chapter 1. Retail systems management

The retail landscape is quickly changing. Retail systems once included thepoint-of-sale (POS) device used at the end of the shopping experience. Now, retailsystems includes new devices that present the customer with technology at everystep of the in-store experience. A wide range of devices—including handheldcustomer units, attendant facing units, wireless cart-mounted devices, self-servicekiosks, informational kiosks, digital displays, radio-frequency identification (RFID)devices—has introduced several unique needs.

There is a need for extensive, seamless, and complete integration with the rest ofthe infrastructure, including elements that are located within the store, as well asthose at the enterprise. It is imperative that these devices remain in service andfunction as intended. When devices do fail, the failures must be detected andpromptly corrected, or the failures be predicted before they occur. This presents astrong need for manageability.

The need for systems managementSystems management can be thought of as the ability to control, configure, update,and monitor a device (in real time when possible) from outside of the device. Anoperator or an application can monitor and maintain the health of a device with thisfunctionality, taking corrective action when needed. This management is aimed atkeeping the device in service, which is especially important in the retail spacebecause fully functional devices means additional sales tools are in front of thecustomer.

Systems management is usually thought of as covering some portion or all of thefollowing disciplines:

power managementThe ability to remotely manage the power states of POS systems. Properuse of this feature can reduce energy consumption and operational costs.

event managementIndications of immediate and potential problems, thresholds met, or generalstatus information. Can be used in triggering both manual and automatedcorrective actions.

operational control and monitoringProvides control of the device or elements of the device's operation.Applications can "watch" defined elements in a device forapplication-defined trigger points.

performance monitoring and managementOverseeing and managing the use of system resources to best manageperformance. Information can be used for system- and network-resourceplanning.

software distributionSoftware and firmware updates; installation and uninstallation of function ondevices.

asset tracking and inventoryAsset tracking for both hardware and software, which can be extremelyimportant to business functions within an organization. Asset and inventorytracking is required for use by software distribution tools, and is helpful inunderstanding and planning fixes.


configuration managementThe ability to view and replicate configuration settings for any device in theenterprise. Configuration management also offers the ability to remotelyconfigure or alter the configuration of a device or software element on adevice.

All of these functional disciplines, working together, form a comprehensivemanagement solution. Although it is not necessary for a particular managementapplication to support all of these disciplines, it is imperative that the device beingmanaged supports them in a consistent, open, and well-understood way.

The importance of standardsThe key to enabling all of the disciplines of system management is manageabilitystandards. The retailer needs devices that are manageable, and these devicesneed to be compatible with the other devices in their IT space. It would not belogical for device manageability to be inconsistent with or unusable by thesystems-management application software that the retailer has chosen for itsenterprise. Personnel who are defining manageability for new devices must fullyunderstand the device that they are trying to manage and the space in which thedevice is intended to operate. This personnel must have knowledge of any existingmanagement standards and schemas for that space.

Management solutionsWhen creating a complete management solution, several components are required.IBM Retail Store Solutions supports customers ranging from the small and mediumbusiness (SMB) to the large enterprise, and provides two complete solutions; eachfitting a different segment. The SMB solution is based around IBM Director, and thesolution for large enterprises is built around the power and expansiveness of IBMTivoli® applications.

The Remote Management Agent is the common component in both solutions. WithRMA, you can start with a smaller and less expensive installation based on IBMDirector. When the need for more capacity arises, you can easily move to a fullTivoli solution without changing the agent infrastructure in the store, which is RMA.

You should consider such factors as your environmental needs and what type offunctions you need to deploy. For example, how many devices do you need tomanage? Do you need to manage them centrally from one tool? Can you divideyour enterprise into regions? Who needs to have access to individual managementtools? Do you already have an enterprise management tool, and can it beintegrated?

All of these questions will help you and your service team better understand how toconfigure a solution that best fits your needs. The most important thing toremember when examining a systems management solution is that there is not onesolution. Everyone's needs and wants are different, and the key is to providesolutions that address all of them.


Chapter 2. RMA Overview

IBM Remote Management Agent, along with other IBM retail solutions such as IBMDirector, is the backbone of the IBM Retail System Management system that helpsyou view, track, and control your retail hardware and software environment. WithIBM Remote Management Agent, you can manage your store or enterprise retailoperations from a single console. Designed specifically to support your retailenvironment, IBM Remote Management Agent includes the following key functions:

v Power management of POS systems and operating systems

v Event management to track device and system performance

v Software distribution system that automatically distributes software and devicedriver updates

v Asset tracking and inventory management of hardware and software systems

v System monitoring of device performance, availability, and utilization

Even though this guide focuses primarily on using IBM Director to manage retailinfrastructure from the enterprise, you can use other management applications toconnect with the RMA Master Agent and manage the resources in each store,including custom management applications written using Java ManagementExtensions (JMX) and the RMA programming interfaces.

This chapter explains how RMA provides support for the management disciplinesdiscussed in Chapter 1, “Retail systems management,” on page 3.

Power managementRMA provides support for managing the power states of POS systems in yourenterprise. This includes the ability to remotely shut down, suspend, reboot, andpower on (using Wake On LAN®). These operations can be invoked and scheduledfrom IBM Director.

Events ManagementHardware and software resources in the store generate notification events, whichthe RMA agent receives and forwards to each higher-level tier, up to the enterprise.RMA V2R6 and later provides integration with the Windows Event Log Service.Windows Event Log Service enables Windows event logs to read, converted toRMA events, and forwarded to other applications.

The IBM Director Server retrieves RMA events from the RMA Master Agent in eachstore, where they can be viewed and filtered from the IBM Director Console.

Additionally, the event action plan facilities of IBM Director provide the ability to takeproactive actions in response to specific events.

Software distributionRMA provides support for the distribution of generic software packages (consistingof files, or a set of commands, or both). RMA defines a standard package formatand facilities for deploying packages to multiple clients on various platforms in thestore from the Master Agent.


||||||

|

|

||

|

|

RMA software packages can be built, imported, and exported using IBM Director,where they can then be deployed to clients in multiple stores simultaneously.

Inventory and Asset trackingJMX MBeans, registered on all RMA agents, provide access to all instrumentationon each store device. Instrumentation for each store device can be accessed on theRMA Master Agent.

You can use IBM Director to retrieve and store collections of hardware- andsoftware-inventory information, including retail-specific information for peripherals.This information is stored in the IBM Director database, and it can be monitored orqueried (even when not connected to the RMA Master Agents).

Monitoring Retail SystemsRMA supports active monitoring of store resources, with the ability to definethresholds and record values. Monitor policies can be registered with each RMAMaster Agent to apply a monitor to one or more devices in the store.

Clients that are running RMA can also be monitored using the IBM Directormonitoring interface, where retail-specific monitors, as well as the default IBMDirector monitors, can be created.

Diagnostic data captureRMA provides infrastructure for performing diagnostic data captures, where files canbe gathered when errors occur. After they are collected, the capture files areautomatically transferred to each store's Master Agent, and from there can betransferred to the enterprise for diagnosis.

The Retail Extensions for IBM Director provide a user interface for creating andmanaging RMA data-capture policies.

Retail peripheral managementThe RMA agents include JMX MBeans that provide access to UPOS peripheralinstrumentation.

You can use the Retail Peripheral Management tasks in IBM Director to monitorretail peripherals and collect inventory.

File transferRMA supports the ability to perform file operations remotely.

You can use the RMA File Transfer task in IBM Director to browse the file systemand to perform file operations on devices that are running the RMA agent, includingsending, receiving and viewing files.


Chapter 3. Infrastructure components

RMA serves as a gateway to all store resources. At the enterprise level, there arenumerous integration possibilities for enterprise management, as Figure 1illustrates:

IBM Director, enterprise management tools based on JMX, and custommanagement applications written to the RMA APIs can all connect to the MasterAgent to manage store resources. These are the components that make up theRMA infrastructure in the store, and they comprise an IBM Director deployment atthe enterprise:

RMA General AgentForms the client portion of the RMA infrastructure, running on each POSclient device.

RMA Master AgentRuns in each store that aggregates all resources in the store. The MasterAgent is the single point of access to all store resources from theenterprise. There should be only one Master Agent per store, which willautomatically connect to all in-store devices running the RMA GeneralAgent.

Store

MasterAgent

GeneralAgent

GeneralAgent

IBM DirectorServer

CustomApplication

WebSphereRemote Server

Figure 1. RMA infrastructure


IBM Director ServerCommunicates with one or more in-store Master Agents to provide aconsolidated view of many stores.

IBM Director ConsoleConnects to the IBM Director Server to provide a user interface formanaging the IT infrastructure, including retail devices. The IBM DirectorConsole can be run on the Director Server system or any other system onthe enterprise network.

Retail Extensions for IBM DirectorMust be installed on all IBM Director Servers and IBM Director Consoleswhere retail management is to be performed.


Chapter 4. Deployment scenarios

You should consider the following factors when estimating the capacity andperformance on an IBM Director Server:

v The memory and processor on the system.

v The number of stores (Master Agents) in the enterprise.

v The number of end points (General Agents) per store.

v The location of the IBM Director database. Is it running on the same system asIBM Director Server?

v The amount of management being performed on IBM servers and othernon-retail hardware.

As the number of devices grows, more IBM Director Servers are required, as isdepicted in the scenarios in this section.


Small enterprise scenarioAn enterprise with a small number of stores and devices can use one IBM DirectorServer, connecting to all store Master Agents.

IBM Director Server

Store

MasterAgent

GeneralAgent

GeneralAgent

Store

MasterAgent

GeneralAgent

GeneralAgent

Figure 2. Small enterprise deployment scenario


Medium enterprise scenarioAs the number of managed clients exceeds the capacity of a single IBM DirectorServer, the enterprise should be logically divided into regions, each with its ownIBM Director Servers. Managing the stores in each region requires logging in to theIBM Director Server for that region. You should leave some room in the IBMDirector Server in each region for future growth.

Large enterprise scenarioWhen the number of IBM Director Servers becomes hard to manage, a largeenterprise solution, like WebSphere® Remote Server plus Tivoli Enterprise Console(TEC), IBM Tivoli Monitoring (ITM), and Tivoli Provisioning Manager (TPM) might benecessary.

IBM Director Server

Store Store Store

IBM Director Server

Store Store Store

Figure 3. Medium enterprise deployment scenario

Chapter 4. Deployment scenarios 11

Part 2. Installing and using the IBM Remote ManagementAgent

Chapter 5. RMA Requirements . . . . . . . . . . . . . . . . . . 17Hardware requirements . . . . . . . . . . . . . . . . . . . . . . 17Software requirements . . . . . . . . . . . . . . . . . . . . . . 17

Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17Supported operating systems . . . . . . . . . . . . . . . . . . 17IBM Director . . . . . . . . . . . . . . . . . . . . . . . . . 18Installation roles . . . . . . . . . . . . . . . . . . . . . . . 18Network Configuration Requirements . . . . . . . . . . . . . . . . 18

Chapter 6. Understanding RMA Security . . . . . . . . . . . . . . 19Master Agent Security Modes . . . . . . . . . . . . . . . . . . . 19

Installation and upgrades . . . . . . . . . . . . . . . . . . . . 19Security groups. . . . . . . . . . . . . . . . . . . . . . . . 19

Windows . . . . . . . . . . . . . . . . . . . . . . . . . 19Linux . . . . . . . . . . . . . . . . . . . . . . . . . . 194690 OS . . . . . . . . . . . . . . . . . . . . . . . . . 20IBM Director . . . . . . . . . . . . . . . . . . . . . . . . 20

General Agent Security . . . . . . . . . . . . . . . . . . . . . . 20

Chapter 7. Installing the Remote Management General Agent and MasterAgent . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Interactive installation on Windows . . . . . . . . . . . . . . . . . 21Installation procedure . . . . . . . . . . . . . . . . . . . . . 21

Windows post installation . . . . . . . . . . . . . . . . . . . 26Interactive installation on Linux . . . . . . . . . . . . . . . . . . . 27

Linux prerequisites . . . . . . . . . . . . . . . . . . . . . . 27Small Footprint CIM Broker . . . . . . . . . . . . . . . . . . . 27

SFCB installation . . . . . . . . . . . . . . . . . . . . . . 27SFCB configuration . . . . . . . . . . . . . . . . . . . . . 28Starting SFCB on startup . . . . . . . . . . . . . . . . . . . 29

Installation procedure . . . . . . . . . . . . . . . . . . . . . 29Post installation. . . . . . . . . . . . . . . . . . . . . . . 29

Silent installation of the Remote Management Agent on Windows . . . . . . 304690 OS installation . . . . . . . . . . . . . . . . . . . . . . . 30Updating RMA . . . . . . . . . . . . . . . . . . . . . . . . . 30

Package import. . . . . . . . . . . . . . . . . . . . . . . . 31

Chapter 8. Installing Retail Extensions for IBM Director . . . . . . . . 33Interactive installation for Windows . . . . . . . . . . . . . . . . . 33Interactive installation for Linux . . . . . . . . . . . . . . . . . . . 34Silent installation of the Retail Extensions for IBM Director for Windows and

Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Chapter 9. Uninstalling IBM Remote Management Agent . . . . . . . . 37Interactive uninstallation for Windows . . . . . . . . . . . . . . . . 37Silent uninstallation for Windows . . . . . . . . . . . . . . . . . . 38Uninstallation for Linux . . . . . . . . . . . . . . . . . . . . . . 39Uninstallation result . . . . . . . . . . . . . . . . . . . . . . . 39Retail Extensions for IBM Director uninstallation notes . . . . . . . . . . 39

Chapter 10. Agent configuration . . . . . . . . . . . . . . . . . . 41Directory structure. . . . . . . . . . . . . . . . . . . . . . . . 41


||||||||||||||||||

Agent configuration file . . . . . . . . . . . . . . . . . . . . . 41Security configuration . . . . . . . . . . . . . . . . . . . . . 43SSL configuration . . . . . . . . . . . . . . . . . . . . . . . 44Updating SSL certificates . . . . . . . . . . . . . . . . . . . . 45Agent class path and environment . . . . . . . . . . . . . . . . . 46

Java class path. . . . . . . . . . . . . . . . . . . . . . . 46Windows PATH . . . . . . . . . . . . . . . . . . . . . . . 47

Logging configuration . . . . . . . . . . . . . . . . . . . . . 47Logging levels . . . . . . . . . . . . . . . . . . . . . . . 48RMA logging configuration file changes . . . . . . . . . . . . . . 49

Agent startup sequence . . . . . . . . . . . . . . . . . . . . 50MgmtAgentStartupMBean . . . . . . . . . . . . . . . . . . . 51Agent configuration . . . . . . . . . . . . . . . . . . . . . 51

Agent roles . . . . . . . . . . . . . . . . . . . . . . . . . 52Agent Windows event log integration . . . . . . . . . . . . . . . . 52

Agent configuration file . . . . . . . . . . . . . . . . . . . . 52Event qualifiers . . . . . . . . . . . . . . . . . . . . . . . 53Configuration file format . . . . . . . . . . . . . . . . . . . 53Event mapping . . . . . . . . . . . . . . . . . . . . . . . 56Example forwarded event . . . . . . . . . . . . . . . . . . . 57

Chapter 11. Using Retail Extensions for IBM Director . . . . . . . . . 59IBM Director Console . . . . . . . . . . . . . . . . . . . . . . 60

Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 60Managed Object groups . . . . . . . . . . . . . . . . . . . 60Dynamic groups . . . . . . . . . . . . . . . . . . . . . . 62

Managed Objects . . . . . . . . . . . . . . . . . . . . . . . 62Managed Object types . . . . . . . . . . . . . . . . . . . . 63Managed Object states . . . . . . . . . . . . . . . . . . . . 64Managed Object attributes. . . . . . . . . . . . . . . . . . . 64Associations . . . . . . . . . . . . . . . . . . . . . . . . 65

Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 65Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Discovery Preferences panel . . . . . . . . . . . . . . . . . . . 67Adding a Master Agent . . . . . . . . . . . . . . . . . . . . 67Editing a Master Agent . . . . . . . . . . . . . . . . . . . . 69Removing a Master Agent . . . . . . . . . . . . . . . . . . . 69Importing a list of Master Agents . . . . . . . . . . . . . . . . 69Exporting a list of Master Agents . . . . . . . . . . . . . . . . 71

Starting Discovery. . . . . . . . . . . . . . . . . . . . . . . 71Store Authorization Management task . . . . . . . . . . . . . . . . 72Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . 74

Inventory collection . . . . . . . . . . . . . . . . . . . . . . 74Viewing inventory . . . . . . . . . . . . . . . . . . . . . . . 74

Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75Event log . . . . . . . . . . . . . . . . . . . . . . . . . . 75Event action plans . . . . . . . . . . . . . . . . . . . . . . 75

Creating an action event plan . . . . . . . . . . . . . . . . . 75Publishing custom event types . . . . . . . . . . . . . . . . . 78Severity mapping . . . . . . . . . . . . . . . . . . . . . . 78

Software distribution . . . . . . . . . . . . . . . . . . . . . . . 78RMA Software Package Editor . . . . . . . . . . . . . . . . . . 79Editing a software package . . . . . . . . . . . . . . . . . . . 80

Package Wizard general information . . . . . . . . . . . . . . . 80Operating system settings . . . . . . . . . . . . . . . . . . . 81Package creation and saving progress . . . . . . . . . . . . . . 85


||

RMA Software Distribution 4690 Command Wizard . . . . . . . . . . 87Adding new commands . . . . . . . . . . . . . . . . . . . . 88Editing Commands . . . . . . . . . . . . . . . . . . . . . 92Importing Commands . . . . . . . . . . . . . . . . . . . . 93

Software package subtasks . . . . . . . . . . . . . . . . . . . 93Edit package. . . . . . . . . . . . . . . . . . . . . . . . 93Rename package . . . . . . . . . . . . . . . . . . . . . . 93Delete package. . . . . . . . . . . . . . . . . . . . . . . 93Import package. . . . . . . . . . . . . . . . . . . . . . . 93Export package. . . . . . . . . . . . . . . . . . . . . . . 94Deploying a package. . . . . . . . . . . . . . . . . . . . . 94

RMA File Transfer task . . . . . . . . . . . . . . . . . . . . . . 95Task invocation . . . . . . . . . . . . . . . . . . . . . . . . 95

JMX Browser task. . . . . . . . . . . . . . . . . . . . . . . . 95JMX tree panel . . . . . . . . . . . . . . . . . . . . . . . . 96Instance panel . . . . . . . . . . . . . . . . . . . . . . . . 97

Properties. . . . . . . . . . . . . . . . . . . . . . . . . 97Methods . . . . . . . . . . . . . . . . . . . . . . . . . 98

Method Execution dialog . . . . . . . . . . . . . . . . . . . . 99Adjusting the handler and logger levels using JMX Browser . . . . . . . . 102Resource Monitors . . . . . . . . . . . . . . . . . . . . . . . 103

Creating a Threshold Monitor . . . . . . . . . . . . . . . . . . 104Creating a Recording Monitor . . . . . . . . . . . . . . . . . . 108

User-Defined Monitors . . . . . . . . . . . . . . . . . . . . . . 110Importing threshold plan files . . . . . . . . . . . . . . . . . . . 113Retail Peripheral Management . . . . . . . . . . . . . . . . . . . 113

Retail Peripheral Management Console . . . . . . . . . . . . . . 114Data Capture Policy Manager task . . . . . . . . . . . . . . . . . 117

Data Capture Policy Manager . . . . . . . . . . . . . . . . . . 118Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . 119Policies Pane (Left Pane) . . . . . . . . . . . . . . . . . . 121Device Types Pane (Center Pane) . . . . . . . . . . . . . . . 129Data Capture Implementations Pane (Right Pane) . . . . . . . . . 129

Data Capture Policies . . . . . . . . . . . . . . . . . . . . . 131Associating Data Capture Policies . . . . . . . . . . . . . . . 132Viewing Associated Data Capture Policies . . . . . . . . . . . . 132Manipulating Associated Data Capture Policies . . . . . . . . . . 133

Status Frame for Data Capture Policies . . . . . . . . . . . . . . 134Viewing Capture History for a Policy . . . . . . . . . . . . . . 135Refreshing the Displayed Capture History . . . . . . . . . . . . 135Deleting from a Capture History . . . . . . . . . . . . . . . . 136Retrieving the Capture Bundle for a RMA Data Capture Policy Invocation 137

Power management . . . . . . . . . . . . . . . . . . . . . . 138

Chapter 12. Troubleshooting . . . . . . . . . . . . . . . . . . . 143Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

RMA Agents . . . . . . . . . . . . . . . . . . . . . . . . 143Agent JVM Diagnostics . . . . . . . . . . . . . . . . . . . . 143IBM Director . . . . . . . . . . . . . . . . . . . . . . . . 144

Director Event Configuration . . . . . . . . . . . . . . . . . 144RAS Logging . . . . . . . . . . . . . . . . . . . . . . . 144JVM Diagnostics . . . . . . . . . . . . . . . . . . . . . . 145

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 146

Part 2. Installing and using the IBM Remote Management Agent 15

Chapter 5. RMA Requirements

This section describes the hardware and software requirements for running the IBMRemote Management Agent.

Hardware requirementsThe Master Agent runs on the in-store processor. The in-store processor is aMicrosoft Windows, Linux, or 4690 V6 Enhanced system that runs the IBM RemoteManagement Agent service and provides a point of interface for enterpriseapplications or other in-store applications. The in-store processor should have aminimum 1 GHz processor with 1 GB of RAM. The Master Agent Service requiresapproximately 80 MB of memory without any extensions or connected GeneralAgents. Memory usage will increase as extensions are added, connections aremade, and policies are applied.

The General Agent runs as an embedded agent in a Java virtual machine (JVM), asa system service on a 4690 controller, or on a Windows or Linux system. TheMaster Agent and General Agent services cannot be installed on the samecomputer. The General Agent Service requires approximately 70 MB of virtualmemory when running in a Windows environment and 40 MB of virtual memorywhen running in a Linux environment.

On 4690 operating systems, additional memory is required for each terminal thatthe controller supports.

Software requirementsThis section describes the software requirements for the IBM Remote ManagementAgent.

JavaThe IBM Remote Management Agent installs its own IBM Java 6 RuntimeEnvironment (JRE) software. It does not require a JRE to be installed before RMAinstallation.

Supported operating systemsThe IBM Remote Management Agent, Version 2 Release 6 must be installed onone of the following operating systems:

v IBM 4690 OS V6R2

v SUSE Linux Enterprise Desktop (SLED) 11

v SUSE Linux Enterprise Point Of Service (SLEPOS) 11

v SUSE Linux Enterprise Server (SLES) 11

v Windows 2003 Server with Service Pack (SP) 2

v Windows 7 Professional

v Windows Embedded POSReady 2009

v Windows Vista Business with SP 1

v Windows XP Professional with SP 3

The IBM Remote Management Master Agent V2R6 supports communication withprevious levels of the General Agent running on the following platforms:


||||||

v 4690 OS V6 with RMA V2R4

v Windows Embedded Point of Service (WePOS) Preload V1.1

The Retail Extensions for IBM Director support communication with previous levelsof the Master Agent running on the following platforms:

v 4690 OS V6 with RMA V2R4

v IBM Retail Environment for SUSE Linux (IRES) 2.1.5 with RMA V2R3

IBM DirectorThe Retail Extensions for IBM Director for IBM Remote Management Agent V2R6require IBM Director 5.20.3 Service Update 3 on the following platforms:



v Windows 2003 Server

v Windows 2003 Server x64

Installation rolesThe IBM Remote Management Agent can be installed as a Master Agent or as aGeneral Agent. Chapter 7, “Installing the Remote Management General Agent andMaster Agent,” on page 21 only describes the installation of the General AgentService or Master Agent Service components. Starting a General Agentprogrammatically within an application JVM is discussed in “Embedded Agentregistration” on page 202.

Network Configuration RequirementsThe IBM Remote Management Agent uses the following network ports. Thisinformation can be used for enterprise network configuration:

v 10149: Serialized Object Exchange/Stream (SOXS) Communication betweenManagement Applications (IBM Director) and a Master Agent.

v 10150: Java RMI (Remote Method Invocation) Communication betweenManagement Applications (the IBM Director) and a Master Agent.

Note: Due to the design of RMI, opening up port 10150 alone on a firewall willnot work. Remote connections made to a Master Agent through a firewallcan only use SOXS.

v 10151: Java RMI (Remote Method Invocation) Communication between MasterAgents and General Agents inside the store.

Note: Due to the design of RMI, opening up port 10150 alone on a firewall willnot work. To allow connections to be made to systems running Windows,an exception is automatically added for the RMA agent executable(rmsvc-ga.exe or rmsvc-ma.exe) during installation.

v 10190: RMA File Streaming

v 31200: UDP port used on Master Agents and General Agents for discovery. Themulticast address used is 225.6.29.63


||||||

Chapter 6. Understanding RMA Security

RMA V2R5 introduced security enhancements to improve Master Agent andGeneral Agent security. The security changes to the Master Agent improved theauthentication method used by management applications to access the MasterAgent. The General Agent security enhancements prevents unauthorized access toGeneral Agents within a store.

Master Agent Security ModesThe RMA V2R5 Master Agent can run in one of two security modes, each usingone of the two forms of authentication: enhanced security mode or standardsecurity mode. When running in enhanced security mode, all incoming JMXconnections requires a valid username and password.

Installation and upgradesThe RMA installation prompts the user to select a security mode during a freshinstallation of the RMA Master Agent or an upgrade of a Master Agent from a priorversion of RMA.

The security mode can be changed after installation from mode to mode bychanging the security configuration file on the Master Agent system (see “Securityconfiguration” on page 43).

Security groups

Enhanced authentication not only validates a given username and password, butalso verifies that the user is a member of a specific system group. The groupmembership requirements on each platform are described below.

Note: When upgrading the Master Agent to secure mode using RMA SoftwareDistribution, a valid Windows username and password is required to connectafter the updated Master Agent starts in secure mode. You should have anAdministrator username and password (Windows) or the root password(Linux) before you upgrade. Depending on the system environment, it alsomight be necessary for you to pre-configure some security groups.

WindowsDuring installation of a Master Agent on Windows, a Windows local group calledRMAAdmin is created for RMA authentication. During authentication, the suppliedusername is checked for membership in this group, and the username andpassword are verified. During installation, the local Administrators group of thesystem is added to the RMAAdmin group. You can modify the contents of theRMAAdmin group to contain other local or domain user accounts and groups.

LinuxIf it does not already exist, a group called rmaadmin is created for RMAauthentication during installation of a Master Agent on Linux. During authentication,the supplied username is checked for membership in this group, and the usernameand password are verified. The root user is added as the only member of thisgroup during installation. You can modify the contents of the rmaadmin group tocontain other user accounts.


|

|||||

|

||||

|

|||

|||

|

|||

||||||

|||||||

|||||||

4690 OSTo use RMA enhanced security mode for a Master Agent running on 4690 V6R2,enable 4690 Enhanced Security in System Configuration -> System Security ->Enhanced Security.

A User ID also must be configured in the Enhanced Security -> AuthorizationManager with User Defined Attribute #8 enabled. This user allows the IBMDirector Server to authenticate with the 4690 Master Agent. Refer to the 4690 OSpublications listed in “Related publications” on page xvi for more details.

IBM DirectorWhen IBM Director connects to a Master Agent that is running in enhanced securitymode, a username and password is required to authenticate with that store. MasterAgents that require authentication are denoted with a lock icon:

Authenticating with the Master Agent using the Store Authorization task will removethe lock icon, discover the managed objects in the store, and allow them to interact.See “Store Authorization Management task” on page 72 for more information onworking with secured Master Agents in IBM Director.

General Agent SecurityThe General Agent is secured by creating an exclusive relationship between theMaster Agent and General Agent. After the Master Agent connects to a GeneralAgent, only that Master Agent can connect to that General Agent going forward.With this authentication method, a key exchange is performed between the MasterAgent and General Agent. Each General Agent is installed with a default key thatestablishes a relationship between that General agent and the first Master Agent itdiscovers.

Once discovered, a key pair is exchanged between the Master Agent and GeneralAgent to use as a basis for authentication. If a Master Agent is lost, then all of thekeys for the General Agents are also lost, and reinstalling the Master Agent doesnot work. To prevent the keys from being lost, you should back up the key storefiles so they can be restored on the new machine. You can do this manually byregularly backing up the %SI_HOME%\user\rma\security\keys_ma.dat file on theMaster Agent. You can also back up the Master Agent keys from the enterpriseusing the Store Authorization Management task in IBM Director. Using the StoreAuthorization Management task, the backup operation can be scheduled or invokedimmediately.

If you are unable to restore the keys on the Master Agent, the keys on eachGeneral Agent should be restored to the default key. You can restore the key bydeleting the %SI_HOME%\user\rma\security\keys_ga.dat file on each GeneralAgent, and restarting the General Agent service.

Figure 4. Lock icon


||||

||||

|||||

||||

|

|||||||

||||||||||

||||

Chapter 7. Installing the Remote Management General Agentand Master Agent

The IBM Remote Management Agent is delivered on a single CD, which includesthe Remote Management General Agent, Master Agent, and the Retail Extensionsfor IBM Director. Before attempting to install the Remote Management Agentsoftware, read all the installation instructions in this chapter.

The level of the Master Agent must always be at the same level or later than thoseon any client to avoid unpredictable results. Therefore, it is important to alwaysupgrade the Master Agent in a store before updating the General Agents.

The Retail Extensions must also be at the same level or later as the Master Agentsto which it is connected. Therefore, you should upgrade the Retail Extensions forIBM Director before upgrading the Master Agents.

The installation software uses InstallShield MultiPlatform on Windows, and a RedHat Package Manager (RPM) package on Linux. To install the RemoteManagement Agent code, follow the procedure described in “Interactive installationon Windows,” “Interactive installation on Linux” on page 27, or “Silent installation ofthe Remote Management Agent on Windows” on page 30 sections.

Interactive installation on WindowsThe following sections describe IBM Remote Management Agent installation andpost-installation procedures for a Windows system.

Installation procedureTo install RMA on Windows, perform the following steps:

1. Log on with Administrator authority.

2. Insert the installation CD into the CD drive.

3. To run the installation program, open a command prompt window and issuethe D:\windows\rma\setup.exe command, where D is the CD drive.

4. On the Welcome to the InstallShield Wizard for Remote Management Agent forIBM Remote Management Agent panel, click Next.

5. On the Software License Agreement panel, select I accept the terms in thelicense agreement. Installation cannot continue until you read and agree tothe license terms. Click Next.

Note: Steps 6-9 are for fresh installations only. If RMA is already installed onthe system, then proceed to Step 10 on page 24.

6. The default installation directory is displayed. To use the default, click Next tocontinue. Otherwise, click Browse to select a different directory, and then clickNext.

Note: If Store Integrator (SI) is installed on the system, then install RMA tothat file location.


7. A list of agent types is displayed, as shown in Figure 5. Select the radio buttonfor the agent that you want to install and click Next.

8. For Master Agent installation only: Enter your Store ID and click Next.

Note: The Store ID cannot contain the comma (,), equals (=), colon (:),quotation ('), asterisk (*), pipe (|), or question mark (?) characters.

Figure 5. IBM Remote Management Agent components for a Windows installation


9. A drop-down list of network interface selections is displayed.

v For a General Agent, select the network interface that is on the same IPsubnet as the store's Master Agent and click Next.

v For a Master Agent, choose the interface that is exposed externally to themanagement applications, such as IBM Director, and click Next.

Figure 6. Network interface panel

Chapter 7. Installing the Remote Management General Agent and Master Agent 23

10. For Master Agent installation only: Select a security mode option and clickNext.

Figure 7. Security mode panel


11. A summary panel (Figure 8) is displayed with the information pertaining to theinstallation. If any of the information is not correct, click Back to return to aprevious panel and change your selection. When all selections are correct,click Next.

12. The installation process takes several minutes. When the process is complete,click Next.

13. You can choose to reboot now or later. Click Finish to complete the installationprocess.

All products in the Store Integrator family are installed in terms of components.Each component is installed into its own directory <COMPONENT>xxxxxxx under theroot directory, where xxxxxxx stands for the version number.

The RMA component is installed with the Remote Management Agent. The directoryis created under the installation root directory.

A maximum of two versions of each component can be on the system: the currentversion and a backup version that can be reactivated if the current version does notwork as expected.

(This is similar to the 4690 OS Apply Software Maintenance Process.) Reactivationof the backup version is done by uninstalling the current version, which changes allenvironment variables to point to the backup version's directories.

Note: When an agent is migrated from a previous version, certain configurationand data files in the %SI_HOME%\user\rma directory could be migrated tonew formats. As a result, going back to the previous version can causeunpredictable results and is unsupported.

Figure 8. Summary panel


Windows post installationFollowing the completion of the installation process, you are required to rebootbefore the new installation will take effect. Upon restart, the IBM RemoteManagement Agent Service starts running. There is an entry for the IBM RemoteManagement Agent Service in the Windows Services Applet from the Control Panel.

Note: If a Master Agent running in enhanced security mode was installed, you canmake custom changes to the RMAAdmin security group. For more informationabout group membership when running in enhanced security mode, see“Security groups” on page 19.

Figure 9. Post installation window


Interactive installation on LinuxYou can install the IBM Remote Management Agent on a Linux system. The RMAagent is installed and upgraded via an RPM package. On the installation CD, thereare two RPM files; one for a Master Agent, the other for a General Agent.

Linux prerequisitesRMA relies on access to Common Information Model (CIM) information on eachsystem to perform certain functions. Without CIM information, limited systeminformation is available to RMA, and as a result some functionality is not present oris only available in a limited fashion. The following lists the features that are notavailable or that are limited without CIM information:

v No retail peripheral management is available, including peripheral inventory,monitoring, and events.

v The amount of inventory information collected is severely reduced.

v The number of attributes that you can monitor is severely reduced.

The following RMA functionality is still available without access to CIM information:

v Software Distribution

v Agent Discovery

v Power Management

v Data Capture

v Events (Except for UPOS peripheral events)

v Monitoring (severely limited)

v Inventory (severely limited)

Small Footprint CIM BrokerOn SUSE Linux Enterprise, CIM information is provided by Small Footprint CIMBroker (SFCB). This section describes how to install and configure SFCB on aSUSE Linux Enterprise system.

SFCB installationThe following RPM packages, included in the SLED distribution, provide SFCBsupport on a SUSE Linux Enterprise system:

v sblim-sfcb

Note: If you want to use UPOS Peripheral Management on a supported Linuxsystem, the minimum SFCB version is sblim-sfcb-1.3.2-18.10.1. You candownload this package from Novell.

v sblim-sfcc

v cim-schema

v cmpi-bindings-pywbem

v cmpi-provider-register

v libRaTools0

v libsblim-cmpiutil1

v sblim-cim-client2

v sblim-cmpi-base

v sblim-cmpi-dhcp

v sblim-cmpi-fsvol


v sblim-cmpi-network

v sblim-cmpi-nfsv3

v sblim-cmpi-nfsv4

v sblim-cmpi-params

v sblim-cmpi-smbios

v sblim-cmpi-sysfs

v sblim-indication_helper

v sblim-wbemcli

There are multiple ways to install the SFCB packages. You can install all of therequired packages using the graphical user interface with the following procedure:

1. Click Computer -> Install Software.

2. Click Groups -> Switch to Patterns.

3. Click the Web-Based Enterprise Management Pattern.

4. Install at least the following packages:

v sblim-sfcb

v sblim-sfcc

v cim-schema

v cmpi-provider-register

5. Click Patterns -> Switch back to Groups.

6. Select All and search on sblim.

7. Install the following packages:

v libRaTools0

v libsblim-cmpiutil1

v sblim-cim-client2

v sblim-cmpi-base

v sblim-cmpi-dhcp

v sblim-cmpi-fsvol

v sblim-cmpi-network

v sblim-cmpi-nfsv3

v sblim-cmpi-nfsv4

v sblim-cmpi-params

v sblim-cmpi-sysfs

v sblim-indication_helper

v sblim-wbemcli

Refer to SUSE documentation for other installation methods.

SFCB configurationAfter SFCB is installed, it must be configured to use unauthenticated HypertextTransfer Protocol (HTTP) for RMA.

1. Open /etc/sfcb/sfcb.cfg in a text editor (such as vi).

2. Set enableHttp: to true.

3. Set doBasicAuth to false.

4. Set provProcs: to 40.

5. Save the file and start or restart sfcb with the /etc/init.d/sfcb [start | restart]command.


|

Starting SFCB on startupSFCB must be configured to start when the system starts, but before the RMAservice. To configure SFCB to run on startup, enable the sfcb service to start in theappropriate run levels. One way to enable this is through YaST:

1. Open YaST -> System -> System Services (Runlevel).

2. Select sfcb and click Enable.

3. Click Expert Mode.

4. Select SFCB and check the run levels in which SFCB should start (3 and/or 5).

5. Click OK.

6. Click Yes on the Now the changes to runlevels will be saved dialog.

For additional ways to configure SFCB to run on startup, refer to SUSEdocumentation.

Installation procedureThe following instructions describe how to manually upgrade and install RMA onLinux.

To upgrade an RMA Agent from a previous version on a Linux system, performthese steps:

1. Log in as root.

2. Insert the installation CD.

3. Make sure the CD is mounted. If the CD is not mounted, mount it using themount command. For example, issuing the mount /dev/cdrom /media/cdromcommand as root mounts the CD-ROM to the /media/cdrom directory.

4. Stop the running Agent by issuing one of these commands:

v Master Agent: /etc/init.d/rmsvc-ma stop

v General Agent: /etc/init.d/rmsvc-ga stop

5. Change to the /media/cdrom/linux/rma directory.

6. Upgrade the RMA Agent by issuing one of these commands:

v Master Agent: rpm -Uvh posIBM_RMA-MA-x.y-zzzz.i586.rpm

v General Agent: rpm -Uvh posIBM_RMA-GA-x.y-zzzz.i586.rpm

To install an RMA Agent onto a Linux system, perform these steps:

1. Log in as root.

2. Insert the installation CD.

3. Make sure the CD is mounted. If the CD is not mounted, mount it using themount command. For example, issuing the mount /dev/cdrom /media/cdromcommand as root mounts the CD-ROM to the directory /media/cdrom.

4. Change to the /media/cdrom/linux/rma directory.

5. Install the RMA Agent by invoking one of the following commands:

v Master Agent: rpm -Uvh posIBM_RMA-MA-x.y-zzzz.i586.rpm

v General Agent: rpm -Uvh posIBM_RMA-GA-x.y-zzzz.i586.rpm

Post installationDuring the installation process, the Remote Management Agent Service will beinstalled. There is a SysInit shell script for running the Service in the /etc/init.ddirectory, rmsvc-ga (General Agent) or rmsvc-ma (Master Agent). This script hasthe following parameters (status, start, stop and restart).


Fresh installations only: Before running either of the agents for the first time onLinux, the rma-config script must be run in order for required configuration valuesto be stored. The script is found in the $RMA_HOME directory, where$RMA_HOME is the path to the currently installed RMA level (/opt/ibm/StoreIntegrator/RMA261xxxx).

Without any arguments, the script is interactive and will prompt for each piece ofinformation. The script can be run silently by supplying each configuration value onthe command line. The following options are available:

-n Network interface

-s (Master Agent only) Store ID

-u (Master Agent only) Security mode; valid values are enhanced and standard

The following example supplies the value eth1 for the network interface option andmyStoreId for the store ID:/opt/ibm/StoreIntegrator/RMA261xxxx/rma-config -n eth1 -s myStoreID -u enhanced

Note: The myStoreId string cannot contain any of the characters comma (,), equals(=), colon (:), quotation ('), asterisk (*), pipe (|), or question mark (?).

To supply new values for the configuration properties, the script can be ran any timefollowing installation. After running the script, the RMA agent must be restarted forthe changes to be reflected.

Note: If a Master Agent was installed running in enhanced security mode, customchanges to the rmaadmin security group can be made. For more informationabout group membership when running in enhanced security mode, see“Security groups” on page 19.

Silent installation of the Remote Management Agent on WindowsFor silent installation, perform the following procedure:


2. Insert the installation CD into the CD drive.

3. See the installation section of the sample response file on the CD(windows\responseW.txt) to prepare your own response file.

4. Change to the Windows directory.

5. Issue the silent.bat <full path to response file> command.

4690 OS installationRefer to the 4690 Planning, Installation, and Configuration Guide for moreinformation on enabling this option.

Updating RMAUsing RMA Software Distribution in IBM Director, you can upgrade the RMA agents.Package files located directly on the installation CD can be imported into IBMDirector, creating RMA Software packages that can then be deployed to allWindows and Linux systems running RMA. As of 4690 OS V6, RMA is included inthe base 4690 OS. You must upgrade 4690 OS in order to upgrade RMA.


For more information about the RMA Software Distribution task, see “Softwaredistribution” on page 78.

Package importTo upgrade RMA, use one of the package files located in the dirpkgs directory onthe RMA installation CD:

RMA_GeneralAgent_x.y.zzzz_Win32.rsdpUpgrades the General Agent running on a Windows system.

RMA_MasterAgent_EnhancedSecurity_x.y.zzzz_Win32.rsdpUpgrades the Master Agent running on a Windows system and enablesenhanced security mode.

RMA_MasterAgent_StandardSecurity_x.y.zzzz_Win32.rsdpUpgrades the Master Agent running on a Windows system and enablesstandard security mode.

RMA_x.y.zzzz_Linux.rsdpUpgrades the General Agent or Master Agent running on a Linux system.

Notes:

1. Once an agent has been migrated from a previous version, certain configurationand data files in the %SI_HOME%\user\rma directory are migrated to newformats. As a result, going back to the previous version can cause unpredictableresults.

2. When updating the Master Agent using RMA Software Distribution in IBMDirector, there are two packages on the installation CD to upgrade RMA. Onepackage upgrades the Master Agent and enables enhanced security mode, theother upgrades the Master Agent and enables standard security mode.


Chapter 8. Installing Retail Extensions for IBM Director

The IBM Remote Management Agent is delivered on a single CD, and includes theRetail Extensions for IBM Director. The CD is used for installation on Windows- orLinux-based IBM Director systems. The Retail Extensions for IBM Director providethe additional functionality to support the management of retail devices and must beinstalled on all IBM Director Servers and Consoles.

Note: Read all of the instructions carefully before attempting to install the RetailExtensions for IBM Director software.

The installation software uses InstallShield MultiPlatform. To install the RetailExtensions for IBM Director code, follow the procedures described in one of thefollowing sections:

v “Interactive installation for Windows”

v “Interactive installation for Linux” on page 34

v “Silent installation of the Retail Extensions for IBM Director for Windows andLinux” on page 35

Interactive installation for WindowsYou can install the Retail Extensions for IBM Director on a Windows 2003 Serversystem that is currently running IBM Director 5.20.3 Service Update 3.

Retail Extensions for IBM Director support the following languages:

v English

v French

v German

v Japanese

v Korean

v Simplified Chinese

v Spanish

v Traditional Chinese

Note: The RMA User's Guide is supported in English only.

To begin installing on Windows, perform the following steps:


2. Insert the Installation CD into the CD drive.

3. To run the installation program, open a command prompt window and issue theD:\windows\rma4itd\setup.exe command, where D is the CD drive.

4. On the Welcome to the InstallShield Wizard for Retail Extensions for IBMDirector panel, click Next.

5. On the Software License Agreement panel, select I accept the terms in thelicense agreement. Installation cannot continue until you read and agree to theterms. Click Next.

6. If you are upgrading from RMA Extensions for IBM Director V2R3 or earlier, apanel appears that informs you that the UPOS peripheral inventory information


will be removed during installation due to database table format changes. Afterthe upgrade completes, inventory information will be restored after the firstinventory collection.

7. A summary panel is displayed with the information pertaining to the installation.The installation software accesses your system to determine the location of theIBM Director application and sets this up as the installation location. Thesoftware must be installed in the same location that the IBM Director is installed;therefore, you cannot change this location. When you are ready to proceed withthe installation, click Next.

8. The installation process takes several minutes top complete. When the processis complete, click Finish.

Note: If the IBM Director Server is running, the server is stopped so that theextensions can be installed. If the server is stopped by the installationprogram, it is then restarted when the installation is complete.

Interactive installation for LinuxYou can install the Retail Extensions for IBM Director on a Linux system thatcurrently is running IBM Director 5.20.3 Service Update 3.

To begin installing on Linux, perform the following steps:

1. Log on as root.


3. Run the installation program.

v If the CD is mounted, run /media/cdrom/linux/rma4itd/setup.bin.

v If the CD is not mounted, mount it using the mount command and then run/media/cdrom/linux/rma4itd/setup.bin.

Figure 10. Summary information


For example, issuing the mount /dev/cdrom/ /media/cdrom command as rootmounts the CD-ROM to the directory /media/cdrom.

Note: InstallShield searches for the location of the installed JRE on the system.If the JRE is not in the default location, this search might take a longtime. If you know the location of the JRE, you can bypass the search byissuing the /media/cdrom/linux/rma4itd/setup.bin -is:javahome jrepathcommand to run the installation program, where jrepath is the path to theIBM JRE directory.

4. Click Next on the Welcome to the InstallShield Wizard for Retail Extensions forIBM Director panel.

5. On the Software License Agreement panel, select I accept the terms in thelicense agreement. Installation cannot continue until you read and agree to thelicense terms. Click Next.

6. If you are upgrading from RMA Extensions for IBM Director V2R3 or earlier, apanel is displayed to notify you that the UPOS peripheral inventory informationwill be removed during installation due to database table format changes. Afterthe upgrade has completed, inventory information will be restored after the firstinventory collection.

7. A summary panel is displayed with the information pertaining to the installation.The installation software accesses your system to determine the location of theIBM Director application and sets this location for the install. The software mustbe installed in the same location that IBM Director is installed; therefore, youcannot change this location. When you are ready to proceed with theinstallation, click Next.

8. The installation takes several minutes. When the process is complete, clickFinish.

Note: If the IBM Director Server is running, the server is stopped so that theextensions can be installed. If the server is stopped by the installationprogram, it is restarted when the installation is complete.

Silent installation of the Retail Extensions for IBM Director forWindows and Linux

For silent installation, perform the following procedure:

1. Log on with Administrator authority (Windows) or as root (Linux).


3. Refer to the installation section of the sample response file on the CD and tothe response.txt file to prepare your own response file.

4. Change to the component directory that is under the correct platform directory.For example, if installing on Windows, switch to the windows\rma4itd directory.

5. Issue one of the following commands:

v Windows: silent.bat path_to_response_file

v Linux: ./silent path_to_response_file

Chapter 8. Installing Retail Extensions for IBM Director 35

Chapter 9. Uninstalling IBM Remote Management Agent

This section explains how to uninstall the IBM Remote Management Agent.

Interactive uninstallation for WindowsThis section describes the procedure for interactively uninstalling the RemoteManagement Agent on Windows.

1. Log on as Administrator.

2. Run the %SI_HOME%\uninstrma.bat program to uninstall RMA.

3. InstallShield searches for a JRE and then displays the Uninstaller panel. ClickNext.

4. If this is the last level of RMA that you are removing from the system, you havethe option to delete the RMA installation directory. A panel (Figure 11) promptswhether you want to delete the installation directory and all of its contents:

Attention: If StoreIntegrator is also installed in the RMA installation directory,then you should not delete this directory.

Figure 11. Remove installation directory dialog


5. If this is the last level of RMA that you are removing from the system and youdid not select the option to delete the RMA installation directory, you have theoption to delete the RMA configuration directory, %SI_HOME%\user\rma. Thefollowing panel is displayed, which prompts if you want to delete theconfiguration directory and all of its contents:

6. The Uninstaller panel displays summary information. Click Next.

7. The Uninstaller panel displays the status of the uninstallation operation. RMA isremoved and environment variables are updated as needed.

8. An Uninstaller summary panel is displayed, which confirms if the uninstallationwas successful. Click Next.

9. Choose to reboot now or later. Click Finish to complete the uninstall process.

After uninstalling RMA from a Windows system, you need to reboot so thatenvironment variables can be updated.

Silent uninstallation for WindowsThis section describes the procedure for silently uninstalling the IBM RemoteManagement Agent on Windows.

1. Log on as Administrator.

2. Refer to the uninstallation section of the sample response file on the installationCD and use it to prepare your own response file.

3. Run the %SI_HOME%\uninstrma.bat -silentyour_response_file_path_and_name program to uninstall.

4. After uninstalling RMA from a Windows system, you will need to reboot so thatenvironment variables can be updated.

Figure 12. Remove user directory dialog


Uninstallation for LinuxThis section describes the procedure for interactively uninstalling the RemoteManagement Agent on Linux. When uninstalling the V2R6 agent RPMs on Linux,the /opt/ibm/StoreIntegrator/user/rma directory might be deleted. The deletion istriggered by the existence of the /opt/ibm/StoreIntegrator/user/rma/DoNotDelete file.When the /opt/ibm/StoreIntegrator/user/rma/DoNotDeleteexists, the user directory isnot deleted during uninstallation. By default, the /opt/ibm/StoreIntegrator/user/rmafile will always be included during installation, even if it was previously deleted.Therefore, you must delete the /opt/ibm/StoreIntegrator/user/rma/DoNotDeletefilebefore each uninstallation in order for the directory be deleted.

1. Log on as root.

2. Stop the running agent by issuing one of these commands:

v /etc/init.d/rmsvc-ma stop

v /etc/init.d/rmsvc-ga stop

3. Issue one of these commands to uninstall RMA:

v RMA Master Agent: rpm -e posIBM_RMA-MA-x.y-zzzz

v RMA General Agent: rpm -e posIBM_RMA-GA-x.y-zzzz

4. RPM will remove RMA and update any configuration files to their previous state.

Uninstallation resultAfter uninstalling RMA for Linux:

v The installation or root installation directory %SI_HOME% remains.

v The %SI_HOME%/silogs folder remains.

v The Remote Management Agent Service is removed.

v The uninstallation script under the root directory is not deleted.

v The environment variables are updated or removed.

v On Windows, all RMA license files remain on the system. These are the licensefile directories on each platform:

– Windows: %SI_HOME%\RMA_license

– Linux: /opt/ibm/StoreIntegrator/RMA_license

v The RMA configuration directory (%SI_HOME%\user\rma) is not deleted as aresult of uninstallation when rolling back to a previously installed level. When youare installing only one level of RMA on the system, removal is optional duringuninstallation.

Note: The RMA configuration directory contains all data and configuration files forRMA. Removal of this folder deletes all of these files, regardless of how orwhen they were created.

Retail Extensions for IBM Director uninstallation notesInstalling the Retail Extensions for IBM Director results in IBM Director creating newpersistent objects within its persistent storage mechanism. These objects are tieddirectly back to the classes that created them to allow the objects to be recreatedwhenever the IBM Director Server is restarted.

Uninstalling only the extensions will cause the IBM Director Servers to crash on arestart because of its persistent storage link to the software used by the extensions.Therefore, an uninstallation executable is not provided for the Retail Extensions for

Chapter 9. Uninstalling IBM Remote Management Agent 39

the IBM Director component. If removal is required, the only option is to uninstallIBM Director, remove the IBM Director installation folder (to clear out the RetailExtensions files), and reinstall IBM Director.

This is also true when you are updating to a new version of the extensions.Because there are new classes in the new code that will get persisted, theextensions cannot be uninstalled to go back to the previous level after the RetailExtensions for IBM Director are updated to a new version and the server isrestarted.


Chapter 10. Agent configuration

This section explains how to configure the General Agent or Master Agent afterinstallation is complete. See “Discovery” on page 67 for information on how toconfigure the Retail Extensions for IBM Director.

Directory structureThe configuration files and extensions for the installed RMA agents are in the%SI_HOME%/user/rma directory. Under this directory is a set of subdirectories(listed in Table 1), each containing configuration, data, or extension files.

Table 1. Configuration subdirectory descriptions

Subdirectory Description

/ext Directory that is searched during agent startup for additional Javaarchive (JAR) files to be added to the agent class path. This directoryshould be used to extend the agent class path.

/classes Directory that is added to the agent class path that contains propertiesfiles that are accessed by the agent.

/config Directory that contains configuration data for RMA MBeans.

/update Directory containing program files and scripts for updating RMA.

/data Directory containing stored data.

/security Directory containing Secure Sockets Layer (SSL) keystores.

Agent configuration fileThe RMA agents store configuration as properties in a file in the following location:

v Windows: %SI_HOME%\user\rma\simgmt.pro

v Linux: /opt/ibm/StoreIntegrator/user/rma/simgmt.pro

v 4690 Classic: M:\rma\user\rma\simgmt.pro

v 4690 Enhanced: F:\rma\user\rma\simgmt.pro

The MgmtAgentConfigurationMBean provides a management interface to this set ofconfigurations. The following tables describe the properties in this file. Everyproperty is not required, and therefore all properties might not be present in the file.

Table 2. Agent properties

Agent property and description

com.ibm.retail.si.mgmt.power.wol.port

(Master Agent) Property that specifies the port used to issue a Wake on LAN request. Avalue of 0 means to use a port issued by the underlying operating system.

com.ibm.retail.si.mgmt.storeId

(Master Agent) The store ID. On 4690 OS, this value is populated automatically with thesystem's configured store number.

com.ibm.retail.si.mgmt.remote.interface

Name of the interface (such as eth0) that is used for management (General Agent) or isexposed to management applications (Master Agent).


Table 2. Agent properties (continued)

Agent property and description

com.ibm.retail.si.mgmt.generalagent.protocol

(General Agent) Name of the protocol to use for the General Agent's JMXConnectorServer(rmi or soxs). This rarely needs to be changed.

com.ibm.retail.si.mgmt.remote.rmi.socket.timeout

Property for specifying the socket read timeout (in milliseconds [ms]) for connections madeto the agent's Remote Method Invocation (RMI) JMXConnectorServer.

com.ibm.retail.si.mgmt.remote.rmi.socket.connect.timeout

Property for specifying the socket connect timeout (in ms) for connections made to theagent's RMI JMXConnectorServer.

com.ibm.retail.si.mgmt.generalagent.discovery.ttl

(General Agent) Time to live (TTL) value to use for RMA Discovery Multicast Packets(default is 1). When General Agents are on a different subnet than the Master Agent, thisvalue must be configured.

Table 3. RMI properties

RMI property and description

rmi.timeout

Value for the sun.rmi.transport.connectionTimeout system property. The value of thisproperty represents the period (in ms) in which RMI socket connections can reside in an"unused" state before the RMI runtime will let those connections be freed (closed).

rmi.leaseValue

Value for the java.rmi.dgc.leaseValue system property. The value of this propertyrepresents the lease duration (in ms) granted to other virtual machines (VMs) that holdremote references to objects that have been exported by this VM. Clients usually renew alease when it is 50% expired, so a short value will increase network traffic and risk laterenewals in exchange for reduced latency in calls to Unreferenced.

rmi.checkInterval

Value for the sun.rmi.dgc.checkInterval system property. The value of this propertyrepresents (in ms) how often the RMI runtime checks for expired Distributed GarbageCollection (DGC) leases. This value should not be less than 30 000.

Table 4. Event properties

Event property and description

com.ibm.retail.si.mgmt.eventcontrol.storeandforward

Indicates whether store and forward is enabled for events. Valid values are true (default) orfalse.

com.ibm.retail.si.mgmt.eventcontrol.storeandforward.maxevents

The maximum number of events that are stored before the persistence store beginsdiscarding events (default is 200000).

com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffersizethreshold

The number of events that are buffered (default is 1000).


Table 4. Event properties (continued)

Event property and description

com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffertimeoutthreshold

The time threshold for the in-memory event buffers (in ms). After this amount of time passeswithout any events being fetched, the memory buffer is flushed to disk.

com.ibm.retail.si.mgmt.eventcontrol.storeandforward.eventExpirationTimeout

The maximum number of days before the event buffer, and the entire set of persistedevents, will be deleted for a Master Agent (MA). When checked, if the earliest persistedevent for an MA is older than this number of days, the entire event collection is deleted.

com.ibm.retail.si.mgmt.eventcontrol.storeandforward.eventExpirationCleanupFrequency

The number of hours between checks for expired events.

Table 5. Event fetching properties (Master Agent only)

Event fetching property and description

com.ibm.retail.si.mgmt.notifications.fetchMaxEvents

Parameter for the maximum number of events fetched per remote call (the default is 25).

com.ibm.retail.si.mgmt.notifications.memoryQueueCapacity

Parameter for the maximum number of events held in the NotificationProcessor's incomingevent queue before it will begin to buffer events to disk (the default is 1000).

Table 6. Data capture properties

Data capture property and description

com.ibm.retail.si.mgmt.capture.historyDeletionThreshold

The time threshold, in days, for how long a data capture policy invocation will remain inprogress before being terminated and cleaned up (the default is 1).

com.ibm.retail.si.mgmt.capture.initXferRetryPeriod

Parameter for the initial timeout period (in ms) for transferring data capture files over thenetwork. After the initial timeout, file transfer will retry at increasing intervals up to themaxXferRetryPeriod (the default is 15000).

com.ibm.retail.si.mgmt.capture.maxXferRetryPeriod

Parameter for the maximum timeout period (in ms) for transferring data capture files overthe network (the default is 600000).

Security configurationThe security configuration file is called security.properties. This file is located indirectory %SI_HOME%\user\rma\security.

There are three properties in the security configuration. The first is the securitymode, which is either standard or enhanced. Standard mode security is the onlymode available on RMA V2R4 and earlier; however, standard mode security is stillsupported on later versions. Enhanced mode security requires a username andpassword to unlock access to a Master Agent.

Chapter 10. Agent configuration 43

The second and third properties are related to enhanced security. TheConnectionKeyLifetime property defines the lifetime of the authenticationpublic/private key pair. The RenewKeysPercentOfLifetime property defines thepercentage of the lifetime that passes before the Master Agent generates a keyexpiration warning event. The key pair is renewed automatically when the IBMDirector server receives the expiration warning event. The following example showsthe default contents of the security.properties file:# Property file for RMA security settings.

# Property to define security mode. Possible values are ’standard’ or ’enhanced’.# Default for missing property value is enhanced.com.ibm.retail.si.mgmt.security.mode=enhanced

# Property for lifetime of authentication keys. Default for# missing property value is 17 days.ConnectionKeyLifetime=17

# Property indicating percentage of the lifetime for when key expiration warning# event is generated. The event triggers automatic key renewal. Default for# invalid or missing property value is 75%.RenewKeysPercentOfLifetime=75%

SSL configurationThe use of Secure Sockets Layer (SSL) to create sockets is controlled by thessl.properties file located in the following directories:

v Windows: %SI_HOME%\user\rma\classes

v Linux: /opt/ibm/StoreIntegrator/user/rma/classes

v 4690 Classic: M:\rma\user\rma\classes

v 4690 Enhanced: F:\rma\user\rma\classes

v IBM Director: %DIRECTOR_HOME%/classes, where %DIRECTOR_HOME% isthe installation directory for IBM Director. By default, this directory is C:\ProgramFiles\IBM\Director on Windows and /opt/ibm/director on Linux.

Components that use this functionality create an instance of the RMASocketFactorywith a configuration alias. Depending on the SSL configuration, the sockets createdcan be secure or non-secure. The ssl.properties file contains documentation on theproperties and how to configure the configuration aliases.

There are two primary aliases in the file, which are SSL and NOSSL. In mostinstances, setting other application aliases to one of these files will work. However,other aliases that use different configuration parameters can be created and used.

The components that rely on the SSL configuration are RMI/SOXS, File Streaming,and FTPS. The SSL configuration controls whether sockets are SSL enabled whenmaking remote JMX connections using RMI. The RMA alias determines the use ofSSL for connections between a Master Agent and a General Agent. The RMAMA aliasdetermines the use of SSL for connections between any management application(including IBM Director) and the Master Agent. When the RMA or RMAMA aliases areset to NOSSL, authentication for remote JMX connections is disabled.

RMA File Streaming also makes use of the RMASocketFactory. So that streamingoperations are secure, file streaming sockets are always created using the SSLalias.

It is important that the keystore on each client have the necessary certificates fromeach FTPS server with which it will communicate. This can be achieved either by


adding the server's certificate and certifier certificate to the installed keystore andtruststore, or by having the configuration use a different keystore and truststore thathave these certificates.

The management of the installed keystores is performed using the keytool programinstalled with the JRE. Among the functionality that this tool provides is the ability toview, add, and delete certificates from a keystore.

If the keystore used with the SSL alias is changed from the default, then the newkeystore must contain a certificate to be used by RMA for remote JMXauthentication. The new certificate must be inserted under the alias rsscert.

Updating SSL certificatesRMA uses SSL sockets for communication so that data is encrypted whentransmitted. The certificates used for SSL are also used by RMA to authenticateconnections between IBM Director servers and Master Agents running in standardsecurity mode. Master Agents running in enhanced security mode do not usecertificates for authentication. A default set of certificates is installed with eachsystem, providing an initial level of security. Replacing the default certificates with acustom generated set of certificates will provide an increased level of security. Thecertificates must match on all systems across the enterprise network; from IBMDirector, to the Master Agent, to the General Agents. The certificate updates mustbe made on each system at once throughout the enterprise, otherwise connectivitywill not be established to all systems.

Note: If Store Integrator (SI) is also used on systems in the network, thecertificates used by SI must be the same as those used by RMA.

The following steps outline creation of a new key store and trust store with a newcertificate on a windows system.

1. From a command window, change to the %RMA_HOME%\jre\bin directory.

2. Generate a new key store with a single key by running:

v keytool -genkey -alias rss -keyalg RSA -validity 365 -keystore_MyKeys_ -storepass _MyPass_

v Answer prompts appropriately. When prompted to "Enter key password for<rss>:", press Enter.

Note: The command above creates a certificate that will be valid for 365 days.

3. Export the certificate to a temporary file by running:

v keytool -export -alias rss -keystore _MyKeys_ -rfc -file _MyKeys_.cer-storepass _MyPass_

4. Generate a new trust store based on the previously-created key by running:

v keytool -import -alias rsscert -file _MyKeys_.cer -keystore _MyStor_-storepass _MyPass_

v When prompted to "Trust this certificate? [no]:", type 'Yes' and press Enter.

5. Delete the _MyKeys_.cer file.

In the example above, _MyKeys_ represents the name key store file, _MyStor_represents the name of the trust store file and _MyPass_ represents the passwordfor these files. Appropriate values should be used in practice.


The key store and trust store files with the new certificate must be put on eachsystem in the enterprise network. The ssl.properties file on each managed systemin the enterprise network must also be updated with the new filenames andpassword.

The property keys in the ssl.properties file that should be updated with the fullyqualified path to the _MyKeys_ file are:

v SSL.ServerKeyFileName

v SSL.KeyFileName

Note: On 4690 Enhanced, use a relative path. The base for the relative path isF:/rma

The password _MyPass_ should be the value for these properties:

v SSL.ServerKeyPassword

v SSL.KeyPassword

The property keys in the ssl.properties file that should be updated with the fullyqualified path to the _MyStor_ file are:

v SSL.ServerTrustFileName

v SSL.TrustFileName

Note: On 4690 Enhanced, use a relative path. The base for the relative path isF:/rma

The password _MyPass_ should be the value for these properties:

v SSL.ServerTrustPassword

v SSL.TrustPassword

Note: When the value _MyPass_ is put in ssl.properties, remove the suffix"_encrypted" from the property key. The password will be automaticallyencrypted when the agent restarts and the "_encrypted" suffix will also beadded to the property key.

Agent class path and environmentThe environment and class path that the RMA agent uses are set during agentstartup. RMA provides extension points for adding additional entries to the agentclass path or PATH (Windows) that the agent uses.

Java class pathTo add additional JAR files to the agent class path, copy them to the%SI_HOME%\user\rma\ext directory. During agent startup they are added to theend of the agent's class path. When a level of RMA is uninstalled, these JAR filesare not removed. On 4690 V6 and later, the RMA agent classpath is extended bysetting the %RMACPEXT% user logical file name.

The %SI_HOME%\user\rma\classes directory is of the agent's class path. Javaresources that can be searched for in the class path such as properties files can beplaced in this directory. JAR files can also be extracted into this directory, but it isnot recommended.


Windows PATHThe agent service constructs its own PATH during startup. This PATH includes aminimal set of directories required to run the agent. To extend this path, define asystem environment variable called RMA_PATH_EXT. The value of this variable will beadded to the end of the agent PATH.

Logging configurationRMA uses the Commons-Logging API for logging, and the Java loggingimplementation. RMA supplies the Java Development Kit (JDK) loggingconfiguration in a file in the following locations:

v Windows: %RMA_HOME%\mgmt_log.pro

v Linux: /opt/ibm/StoreIntegrator/RMA261xxxx /mgmt_log.pro

v 4690 Classic: M:\rma\lib\mgmt_log.pro

v 4690 Enhanced: F:\rma\lib\mgmt_log.pro

To change logging levels or other settings, edit this file and restart the agent. Auser-provided logging configuration file can also be modified to override logginglevels in the base logging file. The name and location for the user configuration fileis %SI_HOME%\user\rma\ext\user_log.pro. If you make logging-level changes forRMA extensions or overrides to the supplied levels in this file, the user loggingconfiguration is preserved when an agent install is upgraded.

As of V2R3, RMA uses a memory logging configuration to buffer high-level loggingmessages in memory and only push them to disk when a more serious erroroccurs. This change greatly increases the serviceability of RMA but does changehow RMA logging is configured. To understand the changes to loggingconfiguration, one must first understand how Java logging works.

Java logging is organized in a layered hierarchy that systematically filters andcontrols the output that is passed down to the next lower layer. The following imagefrom java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html diagrams thishierarchy.

There are two main areas of the configuration where logging levels are adjusted.One of these is at the handler and the other is at the logger. In RMA, the handlersare com.ibm.retail.si.mgmt.logging.RMALogHandler, which handles memorylogging, and java.util.logging.FileHandler, which handles regular disk logging.As seen in Figure 13, the handler is the last layer before logging is written to disk.Thus, the .level parameter that is configured on the handler will be the finaldetermining factor for what is written to disk. In a similar fashion, the .levelparameter of the logger will determine what is passed down to the handler. Bydefault, the java.util.logging.FileHandler.level is set to INFO and thecom.ibm.retail.si.mgmt.logging.RMALogHandler.level is set to ALL. This default

Figure 13. Java logging hierarchy


http://java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html

only does regular INFO, WARNING, and SEVERE logging on the FileHandler, butdoes all configured logging on the RMALogHandler.

Note: The user-provided logging configuration file only overrides the two RMAhandler filters and any logging filter (those properties with the .levelparameter). The user-provided logging configuration is applied after theRMA-supplied logging configuration. You must restart the agent for anupdated user logging configuration to be applied.

Logging levelsAs seen Figure 13 on page 47, filtering is done at each level of the hierarchy. Thus,in order to collect all of the needed data in the RMALogHandler, ready to be pushedto disk on a trigger, the logger (com.ibm.retail.si.mgmt.level) must be configuredto FINE. FINE level logging should be sufficient for diagnosing problemsencountered in a production environment. FINEST level logging provides a muchmore granular logging view not necessary outside of a development or labenvironment.

The Commons-Logging implementation provides six levels of logging: FATAL,ERROR, WARN, INFO, DEBUG, and TRACE. The FATAL level is not used by RMA.Table 7 describes the type of data we log at each level and how theCommons-Logging levels translate into Java logging levels of SEVERE, WARNING,INFO, FINE, and FINEST, accordingly.

Note: The Java logging levels are used when setting up the logging configurationfiles.

Table 7. Java logging levels

Java logging level (Commons-Logginglevel) Description

SEVERE (ERROR)

This is the default configured push level forRMA memory logging.Note: Push level will trigger on that leveland above (for example, SEVERE wouldalso trigger on a FATAL error).

Critical errors that warrant the writing of thememory buffer to disk and collection of otherproblem determination data.

When a SEVERE error has occurred, RMAwill most likely not be functioning properly.

WARNING (WARN) Serious errors that indicate that some area ofRMA has malfunctioned but is notthreatening the overall operation of RMA.Also, these errors could indicate a seriouserror in a component of the system on whichRMA depends.

When a WARNING error has occurred, RMAmight have timed out on some operation orconnection or might have had an operationfail that should have completed normally.

INFO (INFO) Informational messages that show thenormal program flow.

This level of logging provides a non-detailedsummary of the program flow for RMA.


Table 7. Java logging levels (continued)

Java logging level (Commons-Logginglevel) Description

FINE (DEBUG)

This is the default configured logging levelfor RMA memory logging.

Debug level of logging used for determiningthe cause of more serious errors byevaluating the events leading up to the error.

This level of logging should be sufficient forproblem determination in a productionenvironment.

FINEST (TRACE) Trace level of logging used for determiningthe cause of more serious errors byevaluating the events leading up to the error.

This level of logging should only be used forproblem determination in a developmentenvironment. FINEST logging provides anoverly granular output of low-level data.

The level of both the handlers and the loggers can be changed dynamically usingthe JMX Browser as described in “Adjusting the handler and logger levels usingJMX Browser” on page 102. Modifications to handler and logger levels with the JMXBrowser, however, are only in effect until the agent is restarted. To permanentlymodify the handler and logger levels, use the user-provided logging configurationfile at %SI_HOME%\user\rma\ext\user_log.pro.

RMA logging configuration file changesThe RMA logging configuration file (mgmt_log.pro) has a specific subsection todefine the properties for the memory logger. Also, the logging control is centered onthe logging handlers, so the com.ibm.retail.si.mgmt.level is set to FINE bydefault.

Table 8. Configurable logging parameters

Property Description

com.ibm.retail.si.mgmt.logging.RMALogHandler.pattern Pattern (file name and path) used for the outputmemory logging fileDefault: %SI_HOME%/silogs/simgmt_m

com.ibm.retail.si.mgmt.logging.RMALogHandler.limit File size limit in bytes (size of file before wrapping tonext file)Default: 5000000Minimum: 1Maximum: ? (disk-dependent)

com.ibm.retail.si.mgmt.logging.RMALogHandler.count File count limit (number of files to write before purgingoldest file)Default: 10Minimum: 1Maximum: ? (disk-dependent)

com.ibm.retail.si.mgmt.logging.RMALogHandler.formatter Default logging output formatter (file that formatslogging data; in almost all cases leave this as thedefault)Default:com.ibm.retail.si.mgmt.logging.RMALogFormatter


Table 8. Configurable logging parameters (continued)

Property Description

com.ibm.retail.si.mgmt.logging.RMALogHandler.level Logging output level (defined using Java logginglevels)Default: ALLValid values: OFF, SEVERE, WARNING,

INFO, FINE, FINER, FINEST, ALL

com.ibm.retail.si.mgmt.logging.RMALogHandler.size Number of log records to keep in memory buffer(15000 records was approximately 4.5 MB in testing)Default: 15000Minimum: 1Maximum: ? (memory-dependent)

com.ibm.retail.si.mgmt.logging.RMALogHandler.push Trigger level at which to write logs (defined usingJava logging levels)Default: WARNINGValid values: OFF, SEVERE, WARNINGNote: Settings of INFO, FINE, FINER, FINEST, andALL will default to WARNING.

Agent startup sequenceThe installed Master Agent and General Agents each run in their own JVMs assystem services, and have their own set of MBeans that are instantiated uponstartup. Management agents and other applications might need to change thestartup sequence to add their own MBeans and register their ownNotificationListeners.


MgmtAgentStartupMBeanEach management agent service exposes an interface, the AgentStartupMBean, inorder to facilitate adding to or removing from the agent startup sequence. It has thefollowing characteristics:

v Maintains its configuration in an XML file that is read and processed when theMBean is registered. It contains both of the following lists:

– List of MBeans to create during startup, including class name and object name

– List of NotificationListeners to add during startup

v Changes made to the configuration can be persisted through calls to operationson this MBean.

v Process other XML files that contain additional MBeans to create.

Agent configurationThis MBean processes an XML configuration file named AgentStartupConfig_1.xml.This configuration file contains all of the MBeans to instantiate at startup (after thedefault startup sequence has been processed), and all NotificationListeners toregister. The following code is an example XML configuration:<AgentStartupConfig>

<MBeans><MBean classname="foo.pkg.mbeans.Hello"objectName="masteragent:SIFComponent=MyComp,Id-1234"/><MBean classname="foo.pkg.other.mbeans.Bye"objectName="masteragent:SIFComponent=MyComp,Id=4567">

<MBeanArg type="int">5</MBeanArg><MBeanArg type="string">ABC</MBeanArg></MBean></MBeans>

<NotificationListeners><NotificationListener

listener="masteragent:SIFComponent=MyComp,Id=1234"mbean="masteragent:SIFMBean=true,SIFComponent=MGMT,Id=NotificationControl"/>

</NotificationListeners></AgentStartupConfig>

Each of the MBean elements under MBeans represent an MBean to be createdduring startup. Each NotificationListener element under NotificationListenersrepresents a NotificationListener to be added after all MBeans have beencreated. Only MBeans can be added as listeners to other MBeans, not Java objectsthat implement NotificationListener.

To extend the agent startup sequence, all that is required is to create or edit anXML file in one of the following directories and restart the Agent Service:

v Windows: %SI_HOME%\user\rma\config\startup

v Linux: /opt/ibm/StoreIntegrator/user/rma/config/startup

v 4690 Classic: M:\rma\user\rma\config\startup

v 4690 Enhanced: F:\rma\user\rma\config\startup

Additionally, the configuration can be changed using the MBean interface. (Foradditional information, refer to the RMAJavadoc.pdf file that is associated with thisuser guide.)


Agent rolesAgent roles enable sets of descriptive information to be provided about the deviceon which the agent is running. This information gives an additional set of criteria foridentifying groups of agents in addition to platforms, which is useful in applyingstorewide policies.

Information from the agent roles takes the form of a role name and an associatedmodel. By default, the RMA agent comes installed with one of two roles, RMA-GAor RMA-MA, and an associated model RMA-V2. Upon starting the agent on IBMhardware not running 4690 OS, the system's four-character machine type is addedas a role and its three-character machine model is added as a model. For example,a system with the model and type 4800-741 results in a role being created named"4800" with an associated model named "741."

The agent role information is kept in the agent_roles.xml file in the%SI_HOME%/user/rma/config/roles directory. In order to add additional roles, XMLfiles containing information about the new roles need to be added to the%SI_HOME%/user/rma/config/roles/ext directory. The files in this directory are readat agent startup and have their information added to the master configuration beforebeing deleted. The following code is an example of an extension file for adding therole MyApp with associated model MyApp-V1.<?xml version="1.0" ?><AgentConfig>

<Roles><Role name="MyApp">

<Model>MyApp-V1</Model></Role>

</Roles></AgentConfig>

Agent Windows event log integration

Windows provides an Event Log Service to record application, security, and systemevents. You can view these event logs on the system using the Windows EventViewer, and you can use them to monitor information about the hardware, software,and system components, as well as security events on a local or remote computer.You can also use the event log entries to identify and diagnose the source ofsystem problems or to predict potential problems.

Events that are added to the Windows event logs can be read by the RMA Masteror General Agent, converted to an RMA (JMX) Notification, and forwarded to otherapplications. For example, a management application like IBM Director canconsume these events. You can also configure filters to determine which events areforwarded by RMA. By default, no events are forwarded.

Note: Event processing takes up system resources as well as network bandwidth,so you should only configure events to flow up through RMA that are trulypertinent at the enterprise.

Agent configuration fileAt startup, the RMA service looks in the %SI_HOME%/user/rma/config/events folderfor a configuration file named Win32EventLogConfig.xml. This file contains thefiltering and mapping information that determines which events are propagated. Italso allows you to configure the severity of error event mappings. This file must beconfigured on every agent system that is going to forward Windows event log


events. After the desired configuration file is set up on a single system, you can useRMA Software Distribution to forward the updated configuration file to othersystems.

Event qualifiersAll events in RMA use a dotted notation called event qualifiers to identify a generalevent category that is used to filter events on IBM Director and to build event actionplans. The qualifiers for Windows events piped from the log have this format:WindowsEventLog.LogType.EventSource.EventCategory

Note: The first event qualifier is always the string WindowsEventLog.

LogTypeThe log type from which the event originates (Application, System, orSecurity).

EventSourceThe name of the event source, as defined by the application that sourcesthe event. Any period (.) character in the event source name is replaced byan underscore (_) character.

EventCategoryThe name of the event category, as defined by the application that sourcesthe event. If no category is specified, there will not be a fourth qualifier. Ifthis qualifier contains a period, each half is treated as a qualifier, so thatyou can subdivide the categories for further granularity.

For example, a message from the Windows system event log has the followingqualifier:WindowsEventLog.System.Dhcp

A message from an external application might appear as follows:WindowsEventLog.Application.MyRetailApp.Printer

Configuration file formatThe configuration file format is XML to allow the specification of the qualifiers andthe severity for those event log entries that match. Windows allows specialcharacters to be included in the source and category names that cannot be used ina qualifier, so XML provides a format to allow these to be identified. Table 9 showsthe tags and attributes supported by the configuration file.

Table 9. XML definition of the agent configuration file for Windows event log integration

XML tag Attributes

WindowsEventLog Top level container (no attributes)

ApplicationLog Container to define filter entries from the application log (noattributes)

SecurityLog Container to define filter entries from the security log (no attributes)

SystemLog Container to define filter entries from the system log (no attributes)


Table 9. XML definition of the agent configuration file for Windows event logintegration (continued)

XML tag Attributes

Filter Entry Definition of an entry in the filter configuration.

sourcename(Required) A case-sensitive string that contains the sourcename of the event to match.Note: You can use an asterisk to create a global entry(including all ERROR entries in the log).

level (Optional) A comma-separated string that identifies thelevel of events to include (global). Valid values are OFF,INFO, WARNING, ERROR, SUCCESS AUDIT, and FAILURE AUDIT.

errorseverity(Optional) A string that identifies the error mapping to usefor error events (global).

Category Definition of the category to match in the filter along with the sourcename.

Notes:

1. Either ID or name must be specified.

2. The category tag is ignored if a wildcard is specified in the FilterEntry. In other words, you can only specify categories onspecific filter entries.

id The numeric identifier of the category of the event tomatch.

name A string that contains the category name of the event tomatch (which was loaded from the category resourcebundle).

qualifierThe text string to use as the fourth level of the notificationto be sent for matching events.

level (Required) A comma-separated string that identifies thelevel of events to include. Valid values are OFF, INFO,WARNING, ERROR, SUCCESS AUDIT, and FAILURE AUDIT.

errorseverity(Optional) A string that identifies the error mapping to usefor error events.

Example layout:<WindowsEventLog version="1">

<ApplicationLog><FilterEntry sourcename="appname" [level="xxx,yyy"] [errorseverity="zzz"] >

<Category id="#" qualifier="cccccc" level="xxx,yyy" /><Category name="aaaaa" qualifier="bbbbb" level="xxx" [errorseverity="zzz"]/>

</FilterEntry>...

</ApplicationLog><SecurityLog>

...</SecurityLog><SystemLog>

...</SystemLog>

</WindowsEventLog>


The top level container is always the WindowsEventLog tag. It contains one or moreof the following tags, each of which will only appear once: ApplicationLog,SecurityLog, and SystemLog. These container tags scope the filter entries for thatspecific log type. Those tags will contain one or more FilterEntry tags.

FilterEntry tags define the criteria used to determine if a log entry should becreated in RMA Notification. A filter entry must include a source name. Specifyingthe level on this entry indicates the level to be applied for the handling of all events,regardless of category. If different criteria are required based on the category, theninclude additional tags to indicate the category name and the level to use for thatspecific category.

Specifying the level attribute indicates the severity level(s) of the events to bepropagated through RMA. Its comma-separated list contains an entry for each levelto be included by this mapping. The valid values for this attribute are OFF, INFO,WARNING, ERROR, SUCCESS AUDIT, and FAILURE AUDIT:

v A value of ERROR indicates that Error-level events will create an RtlNotification inRMA.

v A value of WARNING indicates that Warning-level events will create anRtlNotification in RMA.

v A value of INFO indicates that Information-level events will create anRtlNotification in RMA.

v If SUCCESS AUDIT is included in the string, then those events will create anRtlNotification in RMA.

v If FAILURE AUDIT is included in the string, then those events will create anRtlNotification in RMA.

v A value of OFF indicates that none of the events that match that criteria will createan RtlNotification in RMA (the event long entry is excluded from creating anRtlNotification). Note that OFF should be the only member of the string when it isspecified.

The default mapping of event severities is to map an error type Windows event toan RtlErrorNotification event, which is a Minor severity in the IBM Director log. Youcan use the optional errorseverity attribute on either of these tags. However, it willoverride the default mapping to allow higher-severity notifications to occur. Thisvalue is either FATAL, CRITICAL, or MINOR.

Example filter:<WindowsEventLog>

<ApplicationLog><FilterEntry sourcename="MyRetailApp" level="ERROR" />

<Category id="1" qualifier="Printer" level="WARNING,ERROR" errorseverity="CRITICAL" /></FilterEntry>

</ApplicationLog></WindowsEventLog>

This partial file indicates that events logged to the Windows Application event log,with an event source of MyRetailApp (for any category) that are ERROR type eventswill be forwarded to RMA. Events that have an event source of MyRetailApp and anevent category of Printer that are Warning- or Error-type events are also forwarded(note that ERROR was already covered in the global category). Therefore, allError-type events are mapped to the RMA Minor error severity except for PrinterWarning- or Error-type events, which are mapped to the RMA Critical error severity.


Event mappingTable 10 shows the mapping between a Windows event log record and an RMANotification.

Note: RMA supplies the Event Category and Event Message values that arereturned by the resource bundle lookup for an event source, as defined bythe CategoryMessageFile and EventMessageFile registry keys. Refer toMicrosoft documentation for more details.

Table 10. Mapping Windows event log definitions to RMA Notifications

Windows event log record field RMA Notification field

TimeGenerated TimeStamp

LogTypeSourceNameEventCategory

EventQualifiers

EventType NotificationType

Strings MessageText

Data UserData

ComputerNameDeviceID of the GA that originates the log

OriginatingDevice

The Event Type is mapped using the scheme in Table 11. Note that the RMANotification type is the go between bridging the Windows event log event type tothe IBM Director severity, which is why the configuration parameter is expressed interms of the IBM Director severity level.

Table 11. Event type to severity mapping

Windows event type RMA Notification typeIBM Directorseverity

Information Success Audit RtlInformationNotification Harmless

Warning RtlWarningNotification Warning

ErrorFailure Audit

Varies based on configuration settings:MINOR = RtlErrorNotificationCRITICAL = RtlAlertNotificationFATAL = RtlCriticalNotification

MinorCriticalFatal


Example forwarded eventFigure 14 is the properties view of a sample Windows Application event:

Figure 14. Sample Windows Application event


This Windows Application event was converted to an RtlNotification andforwarded by RMA; and it shows up as follows in the IBM Director event log for thesystem that originated the event:

Figure 15. Sample Windows Application event viewed in IBM Director


Chapter 11. Using Retail Extensions for IBM Director

Retail Extensions for IBM Director provides the following features:

v File system browsing and file transfer to and from retail devices

v Remote power management of one or more retail devices

v Full monitor integration with IBM Director for POS systems and peripherals,including the ability to record and graph values

v Rich user interface (UI) solution supporting the retail environment

v Single-store or multi-store level management views

v Device information displayed by store or device type

v Inventory information for one or more retail devices in addition to the peripheralsattached to those devices

v Event viewing and handling, including alert action plans tied to events andconditions

v Software distribution to one or more retail devices

v Data capture configuration and viewing

v A browser to view JMX information from devices that support JMX


IBM Director ConsoleThe IBM Director Console provides a main application window that displays allmanageable enterprise systems in a logical manner. The window, as shown inFigure 16, is divided into three sections: Groups, Managed Objects, and Tasks.

GroupsThe Groups panel is the leftmost pane of the console window. It displays a listcontaining objects that represent specific filters. These filters define the criteria usedto determine if a managed object should be included. When a group (filter) isselected, the Managed Object panel displays all systems that meet the criteria ofthe selected filter.

Managed Object groupsA default group (filter) is added automatically for each unique Managed Object type(device type) that is discovered. Selecting this group changes the Managed Objectpane to display all of the objects of that specific device type.

Retail Extensions for IBM Director adds a new group folder and places all of theretail-specific groups under that folder. It also creates a number of hardware-specificdynamic groups that uses the model type and number information in the RetailStore Information table to determine membership. Table 12 on page 61 shows thenew groups.

Figure 16. IBM Director Console


Table 12. Managed Object groups

Icon Group name Description

Anyplace Kiosk Clients Includes all kiosk models, regardless ofplatform

IBM SurePOS 100 Clients Includes all Model 4613s, regardless ofplatform

IBM SurePOS 300 Clients Includes all Model 4810, 4910s,regardless of platform

IBM SurePOS 500 Clients Includes all Model 4840, 4851, 4846,4940, 4951, and 4852s, regardless ofplatform

IBM SurePOS 700 Clients Includes all Model 4800s, regardless ofplatform

Chapter 11. Using Retail Extensions for IBM Director 61

Dynamic groupsAdditional dynamic groups can be created using IBM Director's Dynamic GroupEditor (Figure 17). To start the editor, right-click in the Groups panel and select NewDynamic from the menu displayed. A Retail Store Information table is includedunder the Available Criteria tree, which lets you include retail-specific information inthe filter criteria. To use this information, select Console > New Group > DynamicGroup > Console > Hardware > Settings > Retail Store Information. A list of theattributes that are available for selection is displayed.

Managed ObjectsThe Managed Objects panel is the middle pane of the console window. It displays alist containing the representation of all devices that match the current filter selectedin the Groups panel. It can display the matching devices in a number of selectableways.

Each entry in the middle panel represents a device in the retail space managedthrough RMA. These devices can be the target of specific management actions,such as events, software distribution, and inventory collection.

Figure 17. Dynamic group editor


Managed Object typesThere are many types of devices in the retail space and each of them isrepresented on the management console using a unique icon to help distinguishthem. The following table lists the icon, name, and description of retail devices.

Table 13. Retail devices

Icon Managed Object type Description

JMX Device A general JMX instrumented device(non-RMA device)

Retail System A device that uses RMA instrumentation

Retail Master System An object representing an RMA devicethat is a Master Agent

IRES Branch Server An object representing an IRES BranchServer (always a Master Agent)

4690 Master Agent An object representing a Master Agentrunning on 4690 OS

4690 Controller An object representing a General Agentrunning on a 4690 Controller

4690 Terminal An object representing a 4690Point-of-Sale Terminal

Self-Checkout BOSS An object representing a Self-CheckoutBack Office Server System

Self-Checkout Lane An object representing a Self-CheckoutLane

Anyplace Kiosk An object representing an AnyplaceKiosk system

Windows POS System An object representing a WindowsPoint-of-Sale device

Linux POS System An object representing a LinuxPoint-of-Sale device


Managed Object statesThe management console icons indicate the state of the device, as shown in thefollowing table.

Table 14. Device states

Icon State

Online

Offline

Offline because the Master Agent is offline

Unknown state

Offline error

Offline and Locked. For a master agent, this indicates that the authorizationcredentials have not been provided to allow this store to be managed. For ageneral agent, this indicates the system is already managed by another masteragent (as a different managed object) and cannot be managed by a second one.

Managed Object attributesEach managed object has attributes that uniquely describe something about thatdevice. These attributes include information about the device and about the MasterAgent to which they are connected. The attributes for a managed object can bedisplayed by right-clicking the object and selecting Open. A Display SystemAttributes window is displayed, which is similar to Figure 18 on page 65.


AssociationsWhile the filter controls the members displayed in the center panel, associationscontrol the relationships between those members and how they are displayed. TheStore Association is included for Retail Systems and listed under the Associationsmenu. When selected, it changes the view and displays the retail devices based ontheir relationships to each other and to the store of which they are a member. Toselect this association, right-click in the middle panel of the IBM Director Console(Figure 16 on page 60), then click Associations to display the cascaded menu.Find and select Store Association in the menu.

A new folder is displayed for each store that is managed. Opening that folderpresents all of the managed objects representing the devices managed by theMaster Agent for that store.

TasksThe Tasks panel is the rightmost pane of the console window (Figure 16 on page60). It displays a list of objects that represent specific tasks that can be performed,either by themselves or on a managed object. These tasks cover a wide range offunction, which might be targeted or run stand-alone, and limited to specific types ofmanaged objects.

Figure 18. Display System Attributes panel


The following tasks are specific to Retail Systems:

JMX Browser taskUsed to view the JMX information, classes, attributes and methods fordevices that support JMX. It is described in detail in “JMX Browser task” onpage 95.

RMA Software Distribution taskUsed to create and manage software distribution packages for delivery toRetail-Managed Objects. Also used to reconcile the differences betweenIBM Retail software distribution packages and IBM Director softwaredistribution packages. It is described in detail in “RMA Software Distribution”on page 172.

Retail Peripheral Management taskUsed to target tasks specifically for systems that support certain peripheraldevices. It is described in detail in “Retail Peripheral Management” on page113.

Data Capture Policy Manager taskUsed to create, edit, delete, apply, and invoke new data capture policies onRMA Master Agent systems. It is described in detail in “Data Capture PolicyManager task” on page 117.

Store Authorization Management taskUsed to supply credentials for making connections to locked Master Agentsas well as the ability to backup and restore the authentication keys used bythe Master Agent to connect to General Agents within the store. It isdescribed in detail in “Store Authorization Management task” on page 72.

RMA File Transfer taskUsed to browse the file system and to perform file transfer operations on aretail device.


DiscoveryAfter IBM Director is initialized, managed objects are added for managementthrough a process called discovery. Retail Managed Objects are added to theconsole by running Discovery for JMX Devices.

Discovery Preferences panelThe configuration for discovery in IBM Director is defined through the DiscoveryPreferences panel (see Figure 19). To open the Discovery Preferences panel:

v Select Options > Discovery Preferences from the menu.

v Select the Retail Store Devices tab in order to configure the discovery of retaildevices.

The Discovery Preferences panel includes a list of the Master Agents (one perstore) that are managed by this IBM Director Server. A unique name is provided foreach store definition, along with the information needed to connect to this MasterAgent. An IP address or hostname (for Master Agents using DHCP) must bespecified to make the connection to the agent. Click the Connection Log button todisplay a dialog with detailed information about the most recent connection attemptsfor that entry.

Adding a Master AgentTo add a Master Agent, click Add under the List of Store Master Agents table asshown in Figure 19. The Define Master Agent panel (Figure 20 on page 68) isdisplayed.

Figure 19. Discovery Preferences panel


1. Provide an Entry Name, which is a unique label for each set of storeinformation entered.

2. Select to use name resolution (DNS) or a static IP address when initiating aconnection to the Master Agent.

Note: If a hostname is used, ensure that the hostname resolves to the correctIP address for the Master Agent.

3. Select the connection protocol to use for this store. The default protocolselection is Automatic Detection.

Automatic Detection will automatically choose to use SOXS or RMI, as needed,for the connection to the in-store Master Agent. You can also manually selectSOXS or RMI if a store requires a specific connection protocol or special portnumber.

For example, a manual configuration is required when connecting to a storenetwork that has port redirection configured on the in-store router. In this case,the most likely configuration would be to select SOXS and the appropriate portnumber on the configured routing device. Note that in this example, theconfigured connection IP address should be that of the routing device that isproviding connectivity to the store. Forwarding should be configured to direct theappropriate traffic to the in-store Master Agent.

Another example where manual configuration might be useful is whenconnecting to a store network that has network address translation (NAT)configured on the in-store router. In this case, the configuration should bemanually selected with SOXS and the appropriate port number based on

Figure 20. Define Master Agent Panel


whether port redirection is configured. The SOXS protocol will connect to adevice behind a NAT router; RMI does not offer this function.

Note: SOXS is only supported on RMA V2R4 and later agents.

4. Select the event filter to use for this store. This indicates which events areforwarded up to the IBM Director Server from the Master Agent, and this isdetermined based on the event type. The default is for only Fatal, Critical, andMinor events to be forwarded.

5. Click OK when all of the information has been entered. The new store will beadded to the table displayed.

6. Click OK on the Discovery Preferences dialog to save the modified discoverypreferences information.

Editing a Master AgentTo edit a Master Agent:

1. Select the entry for the store that you want to edit from the table displayed andclick Edit under the List of Store Master Agents table.

2. The Define Master Agent dialog is again shown, but displays the current valuesfor the edited store already filled in. Modify the values as needed and click OKwhen ready.

3. Click OK on the Discovery Preferences dialog to save the modified discoverypreferences information.

Note: If you make changes to the connection protocol settings, they do not takeeffect until the next time that the store connection to Director is lost andreconnected. To force the connection to immediately be re-established,select Force Immediate Protocol Change before you click OK.

Note: Changing connection information (IP address or hostname) for a MasterAgent that has already been discovered and managed causes the previouslydefined connection to be terminated. Any managed objects created usingthat connection should be manually deleted before running discovery againwith the new connection information, to avoid confusion with multiplemanaged objects using the same name but different connection parameters.

Removing a Master AgentTo remove a Master Agent:

1. Select the entries for the stores that you want to remove from the tabledisplayed and click Remove under the List of Store Master Agents table. ARemove Master Agent confirmation dialog displays, prompting you with the listof managed objects to be removed.

2. Click OK to remove those Master Agents from the table.

3. Click OK on the Discovery Preferences dialog to save the changed table.

Note: Removing a Master Agent that has already been discovered and managedcauses the corresponding connection to be terminated. Any managed objectscreated using that connection must be manually deleted.

Importing a list of Master AgentsTo import a list of Master Agents:

1. Click Import under the List of Store Master Agents table.

2. Select the path and file name of a correctly formatted import file to use.

3. Click OK to import the Master Agents defined in that file into the table.


The import file is a properties file, and the correct format is defined in the followingtable.

Table 15. Import file format

Key Value

MACount The number of Master Agents defined in this file

Storename.n The label for store entry number n

MAUseForCnx.n Indicates whether to use name resolution (to support MasterAgents configured to use DHCP) or the IP address toconnect to the Master Agent. These are the valid values:

HOSTNAMEIf HOSTNAME is specified, MasterHostname.n musthave a value.

IPADDRESSIf IPADDRESSis specified, MasterIPAddress.n musthave a value.

MasterHostname.n The host name of the Master Agent for store n

MasterIPAddress.n The IP Address of the Master Agent for store n

MasterPort.n The port number of the Master Agent for store n

MAEventFilter.n Bit flag value indicating which levels of events to forward toIBM Director from the Master Agent for store n. These arethe valid values:

0x0003 = Fatal Only0x000F = Fatal & Critical0x001F = Fatal, Critical, & Minor0x007F = Fatal, Critical, Minor & Warning0x03FF = Fatal, Critical, Minor, Warning & Harmless0x07FF = All

MAProtocol.n The protocol used when connecting to the Master Agent forstore n. These are the valid values:

v AUTO (Default)

v RMI

v SOXS

Example:# Sample Import properties file containing connection information# for the Master Agent of 3 stores.MACount=3Storename.1=Chicago 123MAUseForCnx.1=HOSTNAMEMasterHostname.1=ShopOurStore.chicago.ibm.comMasterIPAddress.1=MasterPort.1=10150Storename.2=Houston 456MAUseForCnx.2=HOSTNAMEMasterHostname.2=ShopOurStore.houston.ibm.comMasterIPAddress.2=MasterPort.2=10150MAEventFilter.2=0x000FStorename.3=New York 789MAUseForCnx.3=IPADDRESS


MasterHostname.3=MasterIPAddress.3=10.1.1.130MasterPort.3=10150MAProtocol.3=RMI

Exporting a list of Master AgentsTo export a list of Master Agents:

1. Select the Master Agent definitions to export from the List of Store MasterAgents table.

2. Click Export under the List of Store Master Agents table to bring up the ExportMaster Agent List dialog.

3. Select the path and enter the file name of the export file to create.

4. Click OK to export the definitions of the Master Agents selected.

The format of the file that is created is described in “Importing a list of MasterAgents” on page 69.

Starting DiscoveryThe Discovery task is started from the console by clicking the toolbar button on thefar left of the toolbar panel. A discovery engine does a search using criteriaspecified for the systems to be added, and creates managed objects for each of thedevices that meet the engine's criteria. For retail, these are systems that implementRMA. To discover Retail-Managed Objects only, click the down-arrow of the toolbarbutton and then select JMX Devices from the list.

For retail, the discovery engine creates a connection to each of the Master Agentsystems defined in the Discovery Preferences Retail Store Devices tab. All of aretail store's devices are managed using RMA, with the Master Agent serving as themain point of control. IBM Director connects to each Master Agent, learns about thedevices that are being managed, and creates a managed object in IBM Director torepresent each device known to the Master Agent. The name of each managedobject is the device ID and includes the unique store ID in parentheses next to thedevice ID to provide an almost unique name. The only exception is when multipleRMA agents are running on the same system.

If the Master Agent was installed with enhanced security enabled, then the storemanaged object that is discovered for that store is initially in the offline state anddisplays a lock icon next to it. This icon indicates to the user that IBM Director iscurrently not authorized to manage that device (and store). The user must use theStore Authorization Management task and provide the username and password forthe store, to authorize this IBM Director server to manage that store. Once thecorrect authorization has been established, the lock icon will disappear from thestore managed object and all of the managed systems for that store will appear withtheir current state.

RMA General Agents only support connections to a single Master Agent. Theyinitially start with a default authorization key that is known by all master agents.When a Master Agent connection is made using the default key, a new keyexchange takes place between the General Agent and Master Agent to create aunique authorization key that is only known by the two systems. After this point, noadditional Master Agents will be able to connect to the General Agent using thedefault key. If a new connection attempt is made, the General Agent will appear asoffline and 'locked' on the IBM Director Console for the additional Master Agentconnection. The Store Authorization Management task allows these connection keys


to be backed up and restored in case the Master Agent system needs to bereplaced. You should regularly backup the keys on a Master Agent, especially whennew General Agent systems are added.

Store Authorization Management taskMaster Agents running in enhanced security mode are discovered with a lock iconnext to the managed object icon, which indicates that authorization has not yetbeen provided for this managed object and therefore this system cannot bemanaged. The Store Authorization Management task allows you to unlock theMaster Agent and manage the security of your connection to each store.

Invoking the task displays a window that allows the user to specify the usernameand password that must be used to authorize the IBM Director server tocommunicate with the Master Agent system in that store. The task displays all ofthe targeted systems in the table, allowing you to work with the authorization of onestore or multiple stores at the same time. This task is used to manage theauthorizations to Master Agents that have been secured ( installed with theenhanced security option selected). This task is also used to manage the keysbetween the master agents and their general agents. There are additional subtasksavailable to allow you to backup the keys assigned to the general agents from themaster agent, and to restore the keys from a backed up version to the masteragent.

You can select one or more of the targeted systems listed in the table in the StoreAuthorization task and choose the Manage Store Authorization menu option. Thislaunches the Store Authorization Management credentials dialog and allows theuser to enter the username and password that must be used to authorize IBMDirector to manage that store. This username must exist on the system and mustbe a member of the security group (varies based on OS). You can use this dialog toenter the username and password for the initial authorization of a new store or toupdate the authorization information for an existing store.

Figure 21. Store Authorization Management task window


The authorization request is sent when you press the OK button on the dialog, andthen the status information is updated in the table based on the results of therequest. The keys assigned to the general agents by the master agent can bebacked up on the IBM Director server in case a problem requires the master agentto be reinstalled or replaced. Select one or more of the targeted systems listed inthe table in the Store Authorization task and choose the Backup ClientAuthentication Keys menu option. This will launch the scheduler dialog, allowingyou to choose to execute the backup now, schedule it for another time, or scheduleperiodically. The keys are stored on the IBM Director server in thedata\rma\authmgmt folder in the install location. The filename is composed of thestore name, the device name of the master agent and an encoded timestamp. Upto two versions of the backup file will exist. The timestamp is encoded in thefilename with the format yyyyMMddHHmmss. For example, the filenameRtlAuth_Store001_MyStoreServer20090630142311.ckb would contain the backupfor a store named Store001 and the master agent with the device nameMyStoreServer taken on June 30, 2009 at 2:23:11 pm.

Restoring the keys is also done from the Store Authorization task window. Selectthe master agent system that you want to restore the keys for, and choose theRestore Client Authentication Keys menu option. This launches a file dialogallowing you to select the file to use to restore the keys from. Select the file to usefor the restore and hit OK to restore those keys to the selected master agent.

Figure 22. Store Authorization Management credentials dialog

Figure 23. Select Client Authentication Key File


InventoryThe IBM Director Console provides an inventory task that for collecting theinventory information for a managed object and storing it in a database table. Thisinformation can be viewed at any time, even when the system is offline, and can beused to define the criteria for managed object filters (groups).

Inventory collectionInventory collection requests are forwarded down to each targeted General Agent,and the results are returned as an event.

Note: If the connections has been down for some time and a backlog of eventsexist, then the results of an inventory collection might be delayed.

The inventory collection that is performed on Retail Systems uses the MBeaninformation that has been gathered by the General Agent for a specific device.When the Retail Extensions for IBM Director receives the new inventory systemevent, it maps that information to the existing IBM Director inventory databasetables.

To start the collection, right-click the device on which you want to perform thecollection, and select Collect Inventory from the menu. To start collecting on multipledevices at once, first select all of the devices from the list, then right-click one of theselected devices, and select Collect Inventory from the menu.

The Inventory Service window is displayed to inform you of the status of yourinventory requests. When the inventory has been completed on the device, thestatus column is updated to reflect the current status.

Viewing inventoryAfter the inventory information has been collected, you can view the information fora device or group of devices by selecting the devices and right-clicking over them,and then selecting View Inventory from the menu.

The Available Queries tree displays a hierarchy of categories. The lowest level ofeach branch represents one of IBM Director's Inventory database tables. Selectingit displays the results of a database query using the selected branch to define thecriteria of the query and contents of that database table in the right-hand panel (thequery results panel).

Figure 24. Inventory collection panel


EventsThe IBM Director Console provides two tasks for managing events. The first is anevent log that you can use to view all of the events that have been received for asystem or group of systems. The second task is event action plans.

Event logThe Event Log displays all of the events for the selected systems. RMA uses astore and forward methodology so that events that occur when a device or store isdisconnected can be sent when the device or store is reconnected. These retailnotifications are mapped into IBM Director events, and the date and time are set towhen the event occurred.

Event action plansThe real power of events comes in supporting the configuration of actions to beautomatically taken when a specific event or set of events occur. IBM Directorprovides support for events to be grouped into families and to provide several levelsof qualifiers. The Retail Extensions for IBM Director forward the RtlNotificationsand MonitorNotifications received from RMA and convert them into IBM DirectorEvents. After they are received, the event's family and qualifiers are published to beused within Director's Event Action Plan Builder.

Creating an action event planThe following steps demonstrate how to create an event action plan to monitorconditions on a Self-Checkout Lane and to page somebody when a specific eventoccurs.

Figure 25. Viewing inventory browser


1. Open the Event Action Plan Builder by double-clicking the Event Action Plantask icon in the Tasks panel of the IBM Director Console.

2. Right-click in the white space to bring up a context menu in the Event Filterspanel, and select New > Simple Event Filter from the menu.

a. From the Simple Event Filter Builder window, click the Event Type tab, andclear the Any check box. This displays the tree panel to the right.

b. Expand the JMX branch of the tree and select the check boxes for JMX,Monitor, Error and Gauge as shown in Figure 26. This creates a filter thatcauses an action to occur when either a JMX.Monitor.Error event is received(any error) or a JMX.Monitor.Gauge event is received (High or Low). Formore information on adding a custom, predefined set of event types to thetree, see the “Publishing custom event types” on page 78

c. Save this event filter by clicking Save As. Provide a unique name for thisfilter (in the example we chose JMX Monitor Changes) and click OK.

3. Right-click the Send an Alphanumeric Page (via TAP) item in the Actionspanel of the Event Action Plan Builder and select Customize.

a. Select the serial port that the dialing software will use to find the modemthrough which the paging message is sent.

b. Enter the phone number of the paging network in the next entry field.Include any area codes and special number required to access the localphone network.

c. Enter the pager ID or PIN of the person you are attempting to page.

d. Enter the information to be displayed on the pager in the Message to Sendentry field. Remember that event data substitution can be used to customizethe message based on the event that has occurred. The pager message islimited to 256 characters. Click on the Help tab for more details.

e. Optionally, include any special characters required to initialize the modem.

Figure 26. Simple Event Filter Builder


||||||

f. Save this event action by clicking the Save As icon on the toolbar. Provide aunique name for this pager action (in the example we chose "PageSysAdmin") and click OK.

4. Finally, create the new event action plan by bringing up the context menu in theEvent Action Plans panel of the Event Action Plan Builder and select New >Event Action Plan. Enter a unique name for the event action plan (in thisexample Self-checkout Plan was chosen) and click OK.

a. Select the JMX Monitor Changes event filter created earlier in the middlepanel and then right-click the action plan created above and select the AddEvent Filter menu choice. This will add the selected filter to the plan.

b. Select the Page SysAdmin action created earlier in the right-hand paneland then right-click the newly added filter in the Event Action Plan panel andselect the Add Action menu choice. This will add the selected action to thisfilter in the plan, as shown in Figure 27.

c. Look at the main console and you will see the new Event Action Plan listedunder the Event Action Plans task, as seen in Figure 28. Drag the eventaction plan on the main console to one or more Managed Objects to applythat plan to the Managed Object or Objects.

Figure 27. Event filter

Figure 28. Newly created Event Action Plan appears in the Tasks frame


Publishing custom event typesIf you create a custom event types, they must be published with the IBM DirectorServer before they can appear in the Event Action Plan Wizard. To publish thecustom event type, create an XML file and place it in the Director\proddata\rmadirectory. There is no restriction on the number of files you can create and there isno formal naming convention. However, each file you create must have an .xml fileextension.

The general format of the xml file is to define a <publishlist> element for eachevent type, with several <publishevent> types inside. Each nested <evtqualifier>element provides an event qualifier, which is listed in order. The following exampledefines two event types: MyApplication.Device.Error andMyApplication.Device.Update

<?xml version="1.0"?><publishlist>

<publishevent family="MyApplication"><evtqualifier index="1" id="Device" /><evtqualifier index="2" id="Error" />

</publishevent><publishevent family="MyApplication">

<evtqualifier index="1" id="Device" /><evtqualifier index="2" id="Update" />

</publishevent></publishlist>

After you create an XML file, you need to restart the IBM Director Server torecognize any changes.

Severity mappingIBM Director event-severity levels are different than those provided in RMA. Thefollowing table shows the mapping between RMA event-severity levels and IBMDirector levels.

Table 16. Severity mapping

RMA severity IBM Director severity

RtlCriticalNotification Fatal

RtlEmergencyNotification Critical

RtlAlertNotification Critical

RtlErrorNotification Minor

RtlWarningNotification Warning

RtlNoticeNotification Warning

RtlInformationNotification Harmless

RtlDebugNotification Harmless

RtlTracePointNotification Harmless

RtlConsumerNotification Unknown

Software distributionThe IBM Director Console provides the capability to create software distributionpackages that can be installed on managed systems, and to schedule thosepackages for delivery and installation on those systems. Due to differences in thebase IBM Director software-distribution packages, the RMA Software Distribution


|||||||

|||||

|||||||||||

||

task has been created to use IBM Director's underlying distribution frameworkalongside the new features needed for RMA. This section describes both of these inmore detail as they relate to retail.

A user can use the RMA Software Distribution task to maintain and distributesoftware packages in retail stores. To provide this functionality, the RMA SoftwareDistribution task performs the following subtasks:

v Create a new install package.

v Create a new uninstallation package.

v Edit existing installation and uninstallation packages.

v Rename existing installation and uninstallation packages.

v Delete existing installation and uninstallation packages.

v Distribute existing installation and uninstallation packages.

v Export installation and uninstallation packages.

v Import installation and uninstallation packages.

All of the RMA Software Distribution subtasks are contained in the parent SWD taskin the task panel on the right side of the console. You can initiate any of thesubtasks by right-clicking the package. The only subtask that cannot be performedusing double or single clicks is the distribution of the packages. This is explained inthe “Software distribution” on page 78 section.

Before deploying RMA Software packages to RMA V2 agents, a one-timeconfiguration step must be performed on each Master Agent.

RMA Software Package EditorAn additional package distribution task, the RMA Software Distribution task, allowssoftware packages to be created specifically for retail-managed objects. To run theRMA Software Distribution Package Wizard, which is used in the creation andediting of RMA software packages, right-click the RMA Software Distribution taskin the Task panel and select either Create Install Package or Create UninstallPackage from the menu. By double clicking the RMA Software Distribution task,the subtask Create Install Package will be run automatically.


Editing a software packageThe RMA Software Distribution Package Wizard edits a software package using ageneric flow regardless of whether you are creating a new package or editing anexisting package. On each panel, required data is gathered for the RMA softwaredistribution framework to complete from start to finish. The information collectedrelates to both the general distribution settings and to individual operating systemsdata and commands.

Package Wizard general informationThis portion of the RMA Software Distribution Package Wizard prompts you for thegeneral information pertaining to the package: a name and a description for thepackage. Along with these fields, you select the target operating systems on whichthis package will be used, in addition to the state the system must be in for thepackage to be deployed. When ready, click Next to continue to the operatingsystem settings panels.

Table 17. Package general information

Field Description

Package Name This is the name of the package. The package nameis presented under the RMA Software Distribution taskso that you can differentiate amongst savedpackages.

Package Description This description is used as a comment field to remindyou of the intent of this package.

Figure 29. RMA Software Distribution task


Table 17. Package general information (continued)

Field Description

Target OS Specifies all the operating systems for which thispackage is targeted. An RMA Agent will not be able touse this package without this information. Thisinformation is also used later in the wizard so that youcan use unique files and commands.

Target State Specifies what the agent's system state is to be inorder for this package to be deployed. For moreinformation, see “SystemStateManager” on page 227.

Operating system settingsThe purpose of this section of the wizard is to set up the package on each of theoperating systems, independent of one another. Each operating system mightrequire different commands and files to be used during the deployment process.Each operating system has its own page in the wizard for completing thesesettings. If three operating systems were chosen, then three pages are displayedfor you to complete. On each of these pages the operating system is indicatedabove the collection fields.

Figure 30. Install Package Wizard


Destination directory: This is the location on the target system for this operatingsystem where all needed files will be placed before you run the commands. If thedirectory already exists, be sure that the RMA agents have access to the specifiedlocation.

Files: When creating packages, files might be needed to perform specialoperations or for installing new programs. You can use the wizard to add files to thepackage by clicking Files on the right-hand side of the wizard, which opens a dialogthat shows all of the drives currently connected to the local system. Here you canselect the files to be placed into the package, either from the local system or thesystem on which the IBM Director Servers is running.

To place files into the package, navigate through the system tree on the left,highlight the selected file or directory, and click the forward arrow (top arrow buttonin the panel). By default, the file dialog does not recursively go through all childdirectories and add the files to the package. To do this, select the IncludeSubfolders check box below the file tree on the left side. Another option to addfiles to the package is to save the full path information of the files being added tothe package. By default, when selecting files, the file dialog does not save the fullpath information.

The list on the right side of the dialog shows how the files are placed in thedestination directory that is defined in the operating systems page of the wizard. If afile or directory needs to be removed, highlight it and click the left arrow (bottomarrow button on the panel).

Figure 31. Operating system settings


Executable commands: This portion of the wizard is used to gather informationfor all the commands to be invoked during the package installation. The displayedinterface for entering command information will vary depending on the targetplatform. Information for each platform is presented below.

To enter commands, click Commands. This button displays a dialog that shows atable of the current list of commands that will be invoked during the packagedistribution.

Figure 32. RMA Software Distribution File Selection panel


Listed for each command are:

v The command path

v The commands arguments

v The expected return code

v The type of command

v The path to a file on the client from which the return code should be read(Optional)

v The path to a log file on the client to read after invoking the command (Optional)

Adding Commands for Non-4690 Packages: To add a command, click Add. Thisbutton displays a dialog box in which you can enter the path, arguments, returncode, return code file, and command log (shown in Figure 34).

Figure 33. Package Commands dialog

Figure 34. RMA Software Distribution Add Program dialog


When finished, click OK to save the new command. The new command is placedinto the table at the top.

To remove a command from the package, highlight the command in the table andclick Remove. If you would like to edit a command in the table, just double-click onthe row to open the command entry dialog. You will be in edit mode, so anychanges you make will override the table selection that you double-clicked. ClickCancel to cancel any changes that you have made.

Adding Commands for 4690 Packages: When you are adding a command for a4690 OS package, a wizard is displayed that guides you through the process ofcreating the command. See “RMA Software Distribution 4690 Command Wizard” onpage 87 for information on creating commands with this wizard.

Post-distribution action: This combination of radio buttons is used to determinewhat the package will do when all files have been transferred and all the givencommands have been performed. See Figure 31 on page 82. The choices are: DoNothing, Restart Computer, or Restart Computer with Return File. If youchoose Restart Computer with Return File, two text fields at the bottom of thepage appear for you to enter the expected return code and the return code file.When all fields are filled in, click Next.

Package creation and saving progressThis page in the wizard shows the progress of the package saving process afterclicking Finish. For packages containing many files or large files, thepackage-saving process might take a long time because all packages are savedonto the IBM Director Server so that users can access the packages from any IBMDirector Console.


The progress panel shows you the current step and its progress, in addition to theoverall progress.

When the wizard finishes creating the package and transferring the files, thepackage is ready to use. A dialog notifies you that the package has beensuccessfully saved. Click OK to close the wizard and the new package is displayedunder the IBM Director Tasks list as shown in Figure 36 on page 87.

Figure 35. RMA Software Distribution progress panel


RMA Software Distribution 4690 Command WizardThis section describes how to use the 4690 Command Wizard to add 4690commands to an RMA Software Distribution package. This wizard displays custompanels for certain 4690 system commands that obtain the required information forthat command in a user-friendly manner. To enter commands, click Commands onthe platform package options dialog. This button displays a dialog that shows atable of the current list of commands that will be invoked during the packagedistribution.

Figure 36. Software package subtasks

Figure 37. 4690 Package Commands dialog


Adding new commandsTo add a new command, click Add from the command list dialog, which will launchthe 4690 Command Wizard (Figure 38). The wizard begins with a list of availablecommands.

The following is a list of the 4690 commands. To begin the creation of a command,select one of the commands from the list and click Next.

v Invoke Batch File

v Supply command information manually

v Re-IPL (ADXCS20L)

v Apply Software Maintenance (ADXCST0L)

Invoke batch file: When you select Invoke Batch File from the command list,Figure 39 on page 89 is displayed to enter the BAT file path, arguments, returncode, return code file, and command log:

Figure 38. 4690 Package Commands dialog


After you supply the command information, click Finish to complete the command.The command then appears in the command list dialog.

Supply Command Information Manually: When you select Supply commandinformation manually from the command list, this dialog appears for obtaining thecommand path, arguments, return code, return code file, and command log:

After you supply the command information, click Finish to complete the command.The command then appears in the command list dialog.

Re-IPL (ADXCS20L): The ADXCS20L command provides the ability to rebootterminals or controllers in a store environment. When you select Re-IPL(ADXCS20L) from the command list, Figure 41 on page 90 dialog is displayed:

Figure 39. 4690 Create Command dialog

Figure 40. 4690 Create Command (manually) dialog


After you select one of the command options, click Finish to complete thecommand. The command is displayed in the command list dialog.

Apply Software Maintenance (ADXCST0L): The Apply Software Maintenancecommand performs operations on one or more 4690 ASM packages. When youselect Apply Software Maintenance (ADXCST0L) from the command list,Figure 42 dialog is displayed:

From this panel, select each product that will be affected by the command and addthem to the list on the right. To add a product, select the product name from the list

Figure 41. Re-IPL dialog

Figure 42. Re-IPL window


on the left and click Add to add it to the list on the right. To remove a package fromthe list on the right, select the product name and click Remove.

To supply information for a product that is not in the list, select the product namedCustom ASM Package and click Add.

You will be prompted for information about the package's product control file, whichuniquely identifies the package. After you supply the fifth and seventh characters ofthe package's product control file name, click OK and the package is added as aselected product into the list on the right.

After you select one or more products, click Next to proceed.

Figure 44 dialog opens with a table for each package that you selected in theprevious dialog, along with a drop-down list of ASM states. For each product in thetable, select the desired target ASM state; then click Next to proceed. The finalpanel displayed is Figure 45 on page 92, which list the additional command options:

Figure 43. Custom ASM Package dialog

Figure 44. ASM product state dialog


After you select command options, click Finish to complete the command. Thecommand then appears in the command list dialog.

Editing CommandsAfter you create a command with the 4690 Command Wizard, you can edit acommand by double-clicking the command in the command list table, which opensthe command entry dialog. Because you are editing the command, any changesyou make will override the table selection that you double-clicked.

Click Cancel to cancel any changes that you have made, or click OK to save yourchanges.

Figure 45. Product options dialog

Figure 46. Editing a command


Importing CommandsWhen you are creating a command for the 4690 platform, the commands from anexisting Remote Command Processor (RCP) command file can be imported into thepackage. To import a list of commands, click Import on the command list dialog. Afile dialog is displayed where you can select the command file to import. Thecommand file might be on the server or on the local console. There must be onecommand per line in the file in order for the commands to import correctly. Onceimported, the commands appear in the command list dialog and can be edited.

Software package subtasksYou can use the RMA Software Distribution task to perform multiple actions on anexisting software package. These actions are grouped into subtasks, called thePackage Subtasks.

Edit packageFrom the Task panel of the IBM Director Console, right-click the package to accessthe package subtask menu. Click the Edit Package menu item to activate thesubtask that opens the Package Wizard that is used to edit the selected package.The wizard used to edit the package is the same wizard that was used to create thepackage. For more information on the Package Wizard, see “Package Wizardgeneral information” on page 80.

Rename packageFrom the Task panel of the IBM Director Console, right-click the package to accessthe package subtask menu. Click the Rename Package menu item to activate thesubtask that opens a dialog for the new name of the package to be entered. Whenthe new name of the package has been entered, click OK to save the new name.

Delete packageFrom the Task panel of the IBM Director Console, right-click the package to accessthe package subtask menu. Select the Delete Package menu item to activate thesubtask that opens a dialog to confirm that you want to delete the selectedpackage. Click Yes to delete the package.

Import packageFrom the task panel of the Director Console, right-click the RMA SoftwareDistribution task and select Import Package. The following dialog is displayed foryou to enter or select the location and name of the file from which to import theRMA software distribution package.


Export packageFrom the task panel of the Director Console, right-click the package to access thepackage subtask menu. Click Export Package. The following dialog is displayed foryou to enter or select the location and name of the file from which to export theRMA software distribution package.

Deploying a packageAll packages that have been created or imported onto the server are distributed thesame as IBM Director software distribution packages. Drag the package from thetask pane over to the system (or systems) in the Managed Objects pane and followthe instructions for deployment that appears in the scheduler panel that displayswhen the package is dropped.

Note: 4690 Software Distribution packages can only be deployed to 4690 V6 orlater agents that appear in the 4690 Maintenance Capable group. This groupcontains all master controllers and all lone controllers in a single controller

Figure 47. Import RMA Software Distribution Package dialog

Figure 48. Export RMA Software Distribution Package dialog


setup. Refer to the 4690 publications for information on invoking commandson a non-master controller from the master controller.

When a software package is deployed to a store, it is retained at that store for 120days. Therefore, subsequent deployments of the package to systems at that storeare not required to be retransmitted from the Director server to the store. Eachdeployment resets the 120 day timer. Additionally, if a network problem occurs andthe entire software package is not transferred, then the next time that package isdeployed, only the remaining portion of the package that was not transferred will besent.

These features reduce the amount of data transferred between the Director serverand agents in the stores. In addition, subsequent deployments of the softwarepackage complete in a shorter amount of time, increasing the efficiency of softwaredistribution.

RMA File Transfer taskThe RMA File Transfer task provides support for file transfer operations onretail-managed objects. The user interface is similar to the IBM Director FileTransfer task but with some of the functionality removed. Those accustomed tousing the IBM Director File Transfer task should find the RMA File Transfer taskeasy to use. Refer to the IBM Director publications for further information on theIBM Director File Transfer task.

Task invocationYou can only invoke the RMA File Transfer task on a single retail-managed object.You can invoke the task on a Windows or Linux Master Agent that is running RMAV2R4 or later. On 4690, you can only invoke the task on a Master Agent that isrunning 4690 V6R2 or later. General Agent support depends upon the RMA versionof the Master Agent: the Master Agent must be V2R6 or later. Table 18 summarizesthis support:

Table 18. RMA File Transfer task invocation support

Target managedobject type Platform

Required RMAversion

Required MasterAgent RMA version

Master Agent Windows V2R4 or later n/a

Master Agent Linux V2R4 or later n/a

Master Agent 4690 V6R2 V2R6 n/a

General Agent Windows V2R4 or later V2R6 or later

General Agent Linux V2R4 or later V2R6 or later

General Agent4690 V6R2(controller only)

V2R6 V2R6 or later

Note: 4690 OS support is limited to 4690 OS V6R2 only.

JMX Browser taskRetail Extensions for IBM Director includes a task on the Tasks panel specifically forviewing information at the JMX level (the underlying protocol). The JMX Browsersupports viewing information retrieved using the JMX API from devices that supportJMX. You can interact with any managed object that inherits from


JMXDeviceManagedObject from within the JMX Browser. To run the JMX Browser,drag the JMX Browser task to a Retail-Managed Object.

JMX tree panelThe JMX Browser opens with a tree view of JMX objects for the systems youselected. Expand the object tree to view categories, instance groupings, andinstances for the specific system.

Each type of tree node is represented by a different icon to help differentiatebetween the various pieces. Here is a mapping of the type of nodes:

Category

These tree nodes represent the categories of JMX objects. All childrennodes can be more categories, instance collections, or instances.

Collection

Collections contain one or more JMX instances. The instances do not showup as child nodes in the tree. Instead, they are selectable in the Instancepanel on the right side.

Instance

Figure 49. JMX tree


Instance nodes represent JMX instances. When an instance is selected, theInstance panel loads the data from that instance. Unlike a collection, thereis no need to select an instance in the Instance panel.

When navigating through the JMX tree, each category has a small square to theright of the icon to expand or collapse the view, showing inner categories,collections, and instances. To view the information for a specific JMX instance, clickthe JMX instance in the tree, and its information will be displayed in the JMXInstance panel on the right side of the browser. If you select a collection ofinstances, look for the selectable instances in the top section of the JMX Instancepanel.

Instance panelThis panel shows the property and method information pertaining to the selectedJMX instance. In the case that a JMX Collection is selected in the Tree panel, theInstance panel will show a list of available instances at the top. When one of theshown instances is selected, the Property and Method information will be populatedaccordingly in the bottom half of the panel.

Properties

The list of properties belonging to the JMX instance is selected in the Instancepanel. All of the readable properties are displayed here, showing each property'sname, type, value, and whether it is modifiable. The property can be determined tobe modifiable if the lock in the Modifiable column is set to unlocked. If a property ismodifiable, the property can be modified by either double-clicking on the property'srow in the table, or by right-clicking and selecting Set Value. It is also possible thata property that is modifiable cannot be modified using the JMX Browser. Someproperty types are not supported by the base JMX Browser but might be enhancedso that the unsupported properties become supported.

When you choose a property to be modified, a dialog is displayed for you. Thecurrent value of the property is set in the dialog as an initial value. Some propertytypes can be set to a null value. This option should only be used by those whounderstand how the property is being used and how a null value will affectoperations of the selected JMX instance.

Figure 50. Properties tab


Click Save to save the current setup of the property for future execution on this orany other JMX instance of the same class on any device. When you click Save, adialog appears that prompts you to enter the description for the task it will create.The name can be anything you want, as long as it does not match an existingsaved task. These saved tasks are found under the JMX Browser task and can bestarted by dragging the task to the target device.

Methods

Click the Methods tab to display a list of methods belonging to the JMX instance.The Methods panel shows the name, inputs, and return values for each methodshown in the method table. All the methods listed can be run by eitherdouble-clicking on the row the method belongs to in the table, or by right-clickingthe row and selecting Execute. Even though all methods are executable, not all theparameters contained in the methods are supported by the JMX Browser. When amethod is chosen for execution and contains a parameter that is unsupported by

Figure 51. Set Value dialog

Figure 52. Methods tab


the JMX Browser, you are informed by a dialog.

Method Execution dialogThis dialog is used to run the selected JMX Method. At the top of the MethodExecution dialog, information about the selected JMX instance is displayed alongwith the name of the selected method. In the middle of the dialog is the inputsection, containing all the parameters that must be set in order for the method torun properly. Each parameter is placed in its own row in the section, providing aclear view of each parameter's name, type, and current value. The name of eachparameter is specified by the JMX instance.

The values for the parameter can be set by clicking the button to the right of theparameters, which displays a dialog similar to that used to set the values forproperties in the properties panel. All the same operations can be performed on thevalue of the parameter as are available for setting the value of a JMX instanceproperty. When finished setting the value of the parameter, click OK to save thevalue.

Figure 53. Unsupported Method dialog


After all parameters have been filled in, the method is ready to be run or saved.When running a method, the JMX Browser sends the data to the JMX instance andthe instance runs the method. After the method has been run, a new section isdisplayed at the bottom of the Execution Method Dialog to display the output results(return value) or an exception if the execution failed.

Click Save to save the current setup of the method for future execution on this orany other JMX instance of the same class on any device. When you click Save, adialog appears that prompts you to enter the description for the task it will create.The name can be anything you want, as long as it does not match an existingsaved task. These saved tasks are found under the JMX Browser task and can bestarted by dragging the task to the target device.

Figure 54. Method Execution dialog


Figure 55. Saved JMX Method task


Adjusting the handler and logger levels using JMX BrowserIt is possible to adjust the logging handler and logger levels on the fly using theJMX Browser in IBM Director. The following images identify where this can be donefor the new RMALogHandler and the logger levels:

Figure 56. Handler levels


Resource MonitorsThe IBM Director Console provides a Resource Monitors task for setting thresholdsor recording monitorable attributes for a managed object. RMA V2R3 and laterManaged Objects are supported for this task. This section provides an example ofhow to create both a threshold monitor and a recording monitor. Further detailsabout the Resource Monitors task can be found in the documentation for IBMDirector. For releases prior to V2R3, see Appendix D, “JMX Browser Plug-Ins,” onpage 249.

Figure 57. Logger levels


Creating a Threshold MonitorThis section provides an example of how to create a threshold monitor. At thecompletion of the steps in this section, a threshold monitor for Hard Disk utilizationwill be active on the RMA agent that you selected.

1. From the Director Console, start the Resource Monitors task targeted to a RetailClient with Windows managed object.

2. From the Resource Monitors task, select and drag the Disk Utilization attributefrom the Available Resources pane to the Selected Resources pane. At thispoint, the value for disk utilization will appear and will be updated every fewseconds.

Figure 58. Resource Monitor task

Figure 59. Selecting Disk Utilization resource


3. In the Selected Resources pane, right-click the value for Disk Utilization andselect Individual Threshold. This action will start the System Threshold dialogfor this attribute.

4. Enter a meaningful name and description for your monitor and configure theother fields as appropriate. For this example:

Figure 60. Selecting Individual Threshold


Name A user defined name for the monitor.

DescriptionA user defined description for the monitor.

Enable to generate eventsSelecting this box will cause the agent to generate events whenthresholds are exceeded.

Generate events on value changeSelecting this box will cause an event to be generated every time themonitored attribute changes value. When this box is checked, the valueof the minimum duration field will be ignored.

Maximum queued eventsFor retail systems, this box has no meaning as RMA provides its ownmethod of storing and forwarding events.

Minimum DurationThis field defines how long the attribute must stay in a given threshold

Figure 61. Threshold configuration


before an event will be generated. A value of 0 in this field will cause anevent to be generated immediately when a threshold is reached.

Resend DelayThis field indicates how long the system should wait before sendingadditional events when a threshold persists for a long period of time. Avalue of 0 in this field will cause only one event to be generated foreach time a threshold is reached.

Above or Equal/Below or EqualThese fields will differ based on the type of monitor (String or Gauge)and should be configured appropriately for the situation.

5. When you are finished configuring the monitor, press OK to complete andactivate it. This will register the monitor with the in-store Master Agent for thesystem that you selected and then activate the monitor on the selected system.All work for this monitor will be handled on the selected system in the store. Theonly interaction between the Director Server and that system will be when thesystem generates an event based on the monitor created. In the ResourceMonitors task frame, there is now an icon next to the attribute which indicatesthat it has an active threshold monitor.

6. To view all created threshold monitors, select View > View All Thresholds fromthe main menu. You can edit or delete created thresholds from this view.

Figure 62. Example Threshold Monitor


Creating a Recording MonitorThis section provides an example of how to create a recording monitor. At thecompletion of the steps defined in this section, a recording monitor for Hard Diskused space will be active on the RMA agent that you selected.

1. From the Director Console, start the Resource Monitors task targeted to a RetailClient with Windows managed object (see Figure 58 on page 104).

2. From the Resource Monitors task, select and drag the Used Disk Spaceattribute from Available Resources pane to the Selected Resources pane.

3. In the Selected Resources pane, right-click the value for Used Disk Space andselect Record. This action will start the Resource Monitor Recording dialog forthis attribute.

Figure 63. All Available Thresholds view

Figure 64. Selecting Use Disk Space resource


4. To create a new recording for this attribute, select File > New from the mainmenu.

5. Enter a meaningful name for the recording in the Description field, and select avalue for the Duration field.

6. When finished, click OK to complete and start the recording. The recording workfor this monitor will be handled on the selected system in the store. Theinteraction between the Director Server and that system will be a polling cyclefor the Director Server to gather the recorded data from the system.

Note: This polling cycle will use network bandwidth gathering the data.Recording is an expensive operation that should only be utilized whennecessary to diagnose a problem.

7. In the Resource Monitors task frame, there is now an icon next to the attributethat indicates that it has an active recording monitor.

Figure 65. Selecting Record

Figure 66. Creating a new record


8. To view all created recording monitors, select View > View All Recordings fromthe main menu. Recordings that you create can be graphed, exported, deleted,or stopped from this view.

Attention: To reduce network and processor load and to minimize the risk ofproblems when restarting the Director Server, you must manually stop or delete allactive recordings before restarting the server. Leaving a recording in progressacross a Director Server restart can lead to unpredictable results.

User-Defined MonitorsFrom the JMX Browser task it is possible to define a new, monitorable attributebased on many of the MBean attributes that are provided. The newly definedmonitors are displayed in the Resource Monitors task in a User Defined Monitorsfolder, and you can use them in the same manner as the predefined monitors forthresholds or recordings.

This section provides an example of how to add a user-defined monitor to theResource Monitors task using the JMX Browser. At the completion of the steps

Figure 67. Example Recording Monitor

Figure 68. All Available Recordings view


defined in this section, a user-defined monitor for the thread count in the RMAagent JVM will be active on the RMA agent that you selected.

1. From the Director Console, start the JMX Browser task targeted to a RetailClient with Windows managed object.

2. Right-click the ThreadCount attribute from the JAVA-Threading MBean in theJMX Browser and select Add User-Defined Resource Monitor.

Figure 69. JMX Browser task


3. Enter a meaningful name in the Monitor Name field and select either StringMonitor or Gauge Monitor, if the option is available. Use a String Monitor todefine specific text values that will trigger events; use a Gauge Monitor to definehigh and low numerical ranges to trigger the events.

4. When you are finished, click OK to complete. The user-defined monitor is nowavailable in the Resource Monitors task.

Figure 70. Selecting Add User-Defined Resource Monitor

Figure 71. Creating a new user-defined resource monitor


5. From the Director Console, start the Resource Monitors task targeted to a RetailClient with Windows managed object.

6. In the Available Resources pane, under the User-defined Monitors folder, theuser-defined monitor is now available.

Importing threshold plan filesOnce you have created a set of thresholds to be monitored, it can be saved as athreshold plan file that you can import onto a server. This is useful forbackup/restore scenarios as well as for distributing monitors across multiple IBMDirector servers.

To import a threshold plan file:

1. From the main IBM Director Console, right-click the Resource Monitors task andselect Import Plan from File, to bring up the Import Threshold Plan from Filedialog.

2. Select the path and filename of a threshold plan file that was previouslyexported.

3. Click OK to load that file and bring up the Import Plan from File dialog.

4. Select the plan or plans to import from the displayed table.

5. Click Action > Create New Task on the main menu bar.

The plan is created and appears in the main IBM Director Console window as asubtask under the Resource Monitors task.

Retail Peripheral ManagementRetail Peripheral Management is a task to help users manage the peripheralsattached to their retail systems. One of the key components of this new task is anew management console for peripherals, so that certain common tasks can betargeted specifically for the peripherals, making it easier to perform the specifiedtask.

Note: Peripheral information is only available if the following has occurred:

1. The peripheral devices must be using drivers that implement the Unified PointOf Sale (UPOS) Specification, Version 1.9.5 or later.

Figure 72. User-defined Monitors view


2. The devices were opened (or opened, claimed, and enabled) by an applicationrunning on the system at the time inventory was collected.

3. An inventory collection was previously performed on the systems with thedevices to manage.

Retail Peripheral Management ConsoleThe Retail Peripheral Management Console provides a platform so that a user canperform tasks targeted for systems that have specific peripheral devices. This newtask frame for managing peripherals provides you with an interface to select thedevice type to work with, display which systems support this device type, andpresent a list of tasks that can be performed on that device.

The main of the console has a tri-split window and uses the same paradigm as themain IBM Director Console. The leftmost pane is a tree view that displays ahierarchy whose leaf nodes are device types. The center pane contains the list ofsystems that have devices that match the selected device type in the left pane (aselection in the left pane will filter the list in the center pane). The rightmost paneshows the list of available tasks that can be performed on the device (or devices)on the selected system (or systems). The tasks are started in the same manner asother IBM Director tasks, through both context menu and dragging.

The Retail Peripheral Management task can be invoked on a target set of systemsor can be started untargeted. If started untargeted, device operations are scoped toinclude all Retail-Managed Objects. In the targeted case, device operations includethe subset of Retail-Managed Objects from the original target list.

In the figure above, the peripheral type of MSR was selected. The center panel'scontent will change to display all of the retail systems that have an MSR device.The IBM Director Database information is used to determine whether a retailsystem has the selected peripheral device. The information in the database isaccurate based on the last inventory collection request for each retail system.

Figure 73. Retail Peripheral Management Console (MSR selected)


The Peripheral Types panel will display the following device types:

Table 19. Device types

Icon Peripheral Type Description

POS Printer An object representing a Point-of-Sale printer (forexample, a 4610)

Cash Drawer An object representing a cash drawer peripheral

POS Keyboard An object representing a Point-of-Sale keyboard

Line Display An object representing a 2x20 (or similar) display

Fiscal Printer An object representing a fiscal printer (a printer thatalso maintains physical records of a transaction)

Check Scanner An object representing a device that scans checks

Scanner An object representing a bar code scanning device

Key Lock An object representing a key lock device

MICR An object representing a Magnetic Ink CharacterRecognition reader device

MSR An object representing a magnetic stripe reader device

Scale An object representing a scale

Motion Sensor An object representing a motion sensing device

Tone Indicator An object representing a device that can produce atone

Hard Totals An object representing a device that securely storesand maintains a list of transaction informationinternally (this is typically some kind of flash memorydevice)

PIN Pad An object representing a PIN pad device

POS Power An object representing a power backup device (UPS)


Table 19. Device types (continued)

Icon Peripheral Type Description

Cash Changer An object representing a device that provides change(feed a dollar bill in and get back quarters)

Coin Dispenser An object representing a coin dispensing device (themachine that gives out the change at a cash register)

Retail Display An object representing a retail display device (touchand non-touch)

The Systems with Peripheral panel will support the following menu functions:

Find Find the named system in the window.

View Change the view displayed in this panel.

Group byGroups the devices displayed for the selected device type using certaincriteria. The choices are:

None No grouping is used.

Model Use the model information for grouping.

ManufacturerUse the manufacturer information for grouping.

Firmware LevelUse the firmware level for grouping.

Note: If data for the selected grouping criteria is not available, a generic folder willbe added to group all devices that do not have that data. For example,selecting the Group by Model choice with the POS Printer peripheral typeselected would change the view to as shown:


Invoking the inventory task from the Retail Peripheral Management Console willstart a custom Inventory Query Browser. Use this window to select which inventorytable to display for the specified peripheral type in the left-hand pane, and theinventory results display in a table on the right.

Data Capture Policy Manager taskIBM Retail Extensions for IBM Director includes a task to the Tasks panel to handledata capture operations from RMA Agents. This task, the Data Capture PolicyManager task, is used to maintain and deploy RMA Data Capture Policies to eachretail store. Use this task to create a new Data Capture Policy and perform thefollowing operations on the newly created policy:

v Edit Data Capture Policies created by the Data Capture Policy Manager

v Delete Data Capture Policies

v Import and export Data Capture Policies

v Organize and group Data Capture Policies

Figure 74. Retail Peripheral Management Console (using Group by Model)

Figure 75. Peripheral Inventory Query Browser for POS Printer


v Apply Data Capture Policies to RMA Master Agents

v Invoke associated Data Capture Policies

v View Invocation Status of associated/invoked Data Capture Policies

v Transfer Data Capture Bundles for completed invocations of Data CapturePolicies to the IBM Director Server

Note: This task does not support Data Capture Policies created outside of IBMdirector.

The Data Capture Policy Manager task in the tasks pane is used to managecreation, deletion, and editing of Data Capture Policies. All created Data CapturePolicies are represented as subtasks of the Data Capture Policy Manager task.These policies can then be associated with RMA Master Agent systems to createand activate the Data Capture Policies. After Data Capture Policies are associated,a Data Capture Invocation Status frame can be started from the association tocontrol and view details of the invocation and transfer of the Data Capture. Each ofthese areas is explained in detail below. Also, for more information about the RMAData Capture infrastructure, see “Diagnostic Data Capture” on page 184.

Data Capture Policy ManagerData Capture policies contain configuration information about how to collect datathrough the different Data Capture MBeans exposed in the managed environment.These policies can be associated to specific Managed Objects, to specify when andhow these Managed Objects will collect the captures.

The Data Capture Policy Manager frame is started in one of three ways, as shownbelow.

Figure 76. Data Capture Policy Manager task


Note: If you are opening the Data Capture Policy Manager for the first time, itimportant that you drag the Data Capture Policy Manager to the MasterAgent. If you do not drag it to the Master Agent, the Data CaptureImplementations area is empty (meaning there are no implementationsdisplayed on the right-hand side of the Data Capture Policy Manager).Similarly, if you have recently discovered a new managed object thatincludes its own custom data capture implementation (or if you have recentlyadded a new data capture implementation to an already-discoveredmanaged object), it is important that you drag the Data Capture PolicyManager to the Master Agent. Otherwise, the new implementation will bemissing from the Data Capture Policy Manager.

1. By dragging one to many Master Agent Managed Objects to the Data CapturePolicy Manager task.

Note: This is the only way to add new implementations to the GUI.

2. By double-clicking on the Data Capture Policy Manager task.

Note: This will not add any new implementations to the GUI.

3. By right-clicking the Data Capture Policy Manager task and selecting Open.

Note: This will not add any new implementations to the GUI.

The frame contains a menu bar and is split in three different panes.

Menu BarThe menu bar contains two menus: File and Help.

File MenuThe File Menu (see Figure 78 on page 120) has multiple options:

Figure 77. Data Capture Policy Manager frame


New > New PolicyThe New Policy option will create a new Data Capture policy in theAll Data Capture Policies Group. This is described in the PoliciesPane section that follows.

New > New Policy GroupThe New Policy Group option will create a new Data Capture policygroup. This is described in the Policies Pane section below.

Import > ImportThe Import option provides the functionality to import created DataCapture policies from a file, so that they can be restored. This isdescribed in the Importing Policies from File section below.

Export > ExportThe Export option provides the functionality to export created DataCapture policies to a file, so that they can be saved, moved fromone IBM Director Server to another or both. This is described in theExporting Policies to File section below.

Close The Close option closes the Data Capture Policy Manager Frame.When this option is selected, a validation of the created/existingpolicies will be done and a dialog box will appear if any are foundto be invalid. This validation is only that the policies are complete,not that the given mappings will work (This will not detect if aWindows Specific Data Capture Implementation was added under aLinux Terminal. You can use any mapping, even those that mightresult in errors when trying to invoke the Data Capture Policieslater.)

Figure 78. Data Capture Policy Manager File Menu

Figure 79. Data Capture Policy Manager File-Close Dialog


Help MenuThe Help Menu provides access to the help for the Data Capture PolicyManager Frame.

Policies Pane (Left Pane)The leftmost pane shows the existing policies in a tree view component. Thepolicies are persistent objects in IBM Director and the Data Capture Policy Managerframe will display all Data Capture policies regardless of which specific MasterAgent Managed Objects were dragged to the Data Capture Policy Manager task.There will be policy groups to help you manage policies. The All Policies group willalways be present and will contain All Policies, regardless of what other group theyare in.

Under each group will be Data Capture Policies. Policies can be in one to manygroups, but will always be displayed in the All Policies Group. Under each policy,there will be two folders; one for the trigger list and one for the capture list. Undereach folder, there will be device types (that is, Retail Systems), and under eachtype will be all of the different Data Capture Implementations associated to thattype.

v All Policies Group

– Policy 1...

– Policy 2, etc...

v Policy Group 1

– Policy 1

- Capture List

v Device Type x

– Implementation 1


v Device Type y


- Trigger List

v Device Type z


– Policy 2, etc...

v Policy Group 2, etc...

Creating a Data Capture Policy Group: To create a new Data Capture PolicyGroup, open the File Menu and choose the New > New Policy Group option. This

Figure 80. Capture Policy Manager Help Menu


will open a dialog box that will prompt for the name of the policy group. The policygroup will then be added to the Data Capture Policies Tree. Also, a Task Group willbe created under the Data Capture Policy Manager task to match this group.

Renaming a Data Capture Policy Group: To rename a Data Capture PolicyGroup, right-click a Data Capture Policy Group and select the Rename option. Thiswill open a dialog box that will prompt for the name of the Policy group. The policygroup will then be renamed in the tree and the subtask group will be renamed.

Deleting a Data Capture Policy Group: To delete a Data Capture Policy Group,right-click a Data Capture Policy Group and select the Delete option. This will opena dialog box that will prompt for confirmation. Choose Yes to delete the object and

Figure 81. Data Capture Policy Manager Policy Group Dialog

Figure 82. Data Capture Policy Group Context Menu


all of its sub-objects in the tree, or choose No to cancel. If Yes is chosen, the PolicyGroup will be removed and its Data Capture Policy Manager subtask group will bedeleted.

Creating a Data Capture Policy: To create a new Data Capture policy, right-clicka Data Capture policy group folder and choose the New Policy option. This willopen a dialog box that will prompt for the name of the policy. The policy will then beadded to the selected Policy Group and the All Policies Group. Also, a subtask forassociation of this policy will be created under the Data Capture Policy Managertask in the main IBM Director Console frame in an appropriate task group to matchthe Policy Group Folder.

Renaming a Data Capture Policy: To rename an existing Data Capture policy,right-click an existing policy in the tree and choose the Rename option. This willopen a dialog box that will prompt for the new name of the policy (this is the samedialog box as when a new policy is created).

Figure 83. Data Capture Policy Create/Rename Dialog


Deleting a Data Capture Policy: To delete a Policy from the Policy Tree,right-click the Policy and choose the Delete option. This will open a dialog box thatwill prompt for confirmation. Choose Yes to delete the object and all of itssub-objects in the tree, or choose No to cancel. If Yes is chosen, the Policy will beremoved from any Policy Groups it is in and the All Policies Group and its DataCapture Policy Manager subtask will be deleted. This will remove it from anyManaged Objects with which it was associated.

To delete all Policies under a Policy Group, right-click the Policy Group and choosethe Delete All Policies option. This will open a dialog box that will prompt forconfirmation. Choose Yes to delete all Policies in the Policy Group, or choose No tocancel. If Yes is chosen, all the Policies will be removed from this Policy Group inaddition to the All Policies Group and their Data Capture Policy Manager subtaskswill be deleted.

Moving a Data Capture Policy to a Policy Group: To move a Data CapturePolicy to a different Policy Group, select the Data Capture Policy and drag it to aPolicy Group. A Policy can be in many groups simultaneously.

Removing a Data Capture Policy from a Policy Group: To remove a Policyfrom a Policy Group, right-click the Policy and choose the Remove option. This willopen a dialog box that will prompt for confirmation. Choose Yes to remove theobject and all of its sub-objects in the tree, or choose No to cancel. If Yes ischosen, the Policy will be removed. (This is not an option in the All Policies Group)

To remove all Policies under a Policy Group, right-click the Policy Group andchoose the Remove All Policies option. This will open a dialog box that will promptfor confirmation. Choose Yes to remove all Policies in the Policy Group, or chooseNo to cancel. If Yes is chosen, all the Policies will be removed from this Policy

Figure 84. Data Capture Policy Context Menu


Group. (This is not an option in the All Policies Group.)

Exporting Policies to File: To export a single Data Capture Policy to file,right-click the Data Capture Policy and choose the Export Policy option. This willopen an export dialog that will prompt for the filename and location. The locationcan be either on the IBM Director Console or Server.

To export all Data Capture Policies in a Policy Group to file, right-click the DataCapture Policy Group and choose the Export All Policies option. This will open anexport dialog that will prompt for the filename and location. The location can beeither on the IBM Director Console or Server.

To export all Data Capture Policies to file, select Export Menu from the File Menuand choose the Export option. This will open an export dialog that will prompt forthe filename and location. The location can be either on the IBM Director Consoleor Server.

Figure 85. Data Capture All Policies Group Context Menu


Importing Policies from File: There are two ways to import Data CapturePolicies from file.

The first way is to select Import Menu from the File Menu and choose the Importoption. This will open an import dialog that will prompt for the filename and location.The location can be either on the IBM Director Console or Server. This will createall policies from the import file in the All Policies Group.

The second way is to right-click a Data Capture Policy Group and choose theImport option. This will open an import dialog that will prompt for the filename andlocation. The location can be either on the IBM Director Console or Server. This willcreate all policies from the import file in the selected group and the All PoliciesGroup.

These conditions apply to importing policies:

v If any current policies on the system have a name that matches a policy name inthe import, it will fail.

v If any current implementations on the system have a name that matches animplementation in the import policies, the data in the implementations will becross examined and the import will fail if they do not match.

Figure 86. Data Capture Policy Manager Export Dialog


Finding a Data Capture Policy in the Tree: To find a Data Capture Policy in theData Capture Policies Tree, right-click in the white space in the tree and choose theFind option. This will open a find dialog that will prompt for the name to find. Thiswill search the All Policies Group for this Data Capture Policy and select it.

A second way to find a Data Capture Policy in the Data Capture Policies Tree is toright-click a Policy Group and choose the Find option. This will open a find dialogthat will prompt for the name to find. This will search the selected Policy Group forthis Data Capture Policy and select it.

Adding Device Types to a Policy: To add Device Types to a policy, select theDevice Type or Device Types from the Device Types Pane (Center Pane) and dragthem to the Policies Pane (Left Pane). They can be dropped onto a Trigger ListFolder, a Capture List Folder, a Policy, or a Policy Group Folder. If they are droppedon a List Folder, then they will be added to that list. If they are dropped on a Policyor Policy Group, a confirmation dialog will appear confirming that you want to addthem to all List Folders under that element.

Removing Device Types from a Policy: To remove a Device Type from thePolicy Tree, right-click the Device Type and choose the Remove option. This willopen a dialog box that will prompt for confirmation. Choose Yes to remove the

Figure 87. Data Capture Policy Manager Import Dialog

Figure 88. Data Capture Policy Manager Find Dialog


object and all of its sub-objects in the tree, or choose No to cancel. If Yes ischosen, the Device Type will be removed from its List Folder.

To remove all Device Types under a List Folder, right-click the List Folder andchoose the Remove All Device Types option. This will open a dialog box that willprompt for confirmation. Choose Yes to delete all Device Types in the List Folder, orchoose No to cancel. If Yes is chosen, all the Device Types will be removed fromthis List Folder.

Figure 89. Data Capture Device Type right-click context menu

Figure 90. Data Capture Policy List Folder right-click Context Menu


Adding Data Capture Implementations to a Policy: To add Data CaptureImplementations to a policy, select Data Capture Implementation from the DataCapture Implementations Pane (Right Pane) and drag it to the Policies Pane (LeftPane). They can be dropped onto a Device Type, a Trigger List Folder or CaptureList Folder, a Policy, or a Policy Group Folder. If they are dropped on a DeviceType, they will be added under that Device Type. If they are dropped on a ListFolder, a Policy, or a Policy Group, a confirmation will appear confirming that youwant to add them to all Device Types in that element.

Removing Data Capture Implementations from a Policy: To remove a DataCapture Implementation from the Policy Tree, right-click Data CaptureImplementation and choose the Remove option. This will open a dialog box thatwill prompt for confirmation. Choose Yes to remove the object, or choose No tocancel. If Yes is chosen, the Data Capture Implementation will be removed from itsDevice Type.

To remove all Data Capture Implementations under a Device Type, right-click theDevice Type and choose the Remove All Implementations option. This will open adialog box that will prompt for confirmation. Choose Yes to remove all Data CaptureImplementations for the Device Type, or choose No to cancel. If Yes is chosen, allthe Data Capture Implementations will be removed for this Device Type.

Device Types Pane (Center Pane)The center pane shows the current retail device types that are supported. The treeof Device Types is built when the Data Capture Policy Manager frame is startedand will not be refreshed until the frame is closed and re-opened. The pane will notaccept an object being dropped into it and will not respond to right-click actions.You can select several of its objects so that one or more of them can be dragged tothe Policies Pane (Left Pane).

Data Capture Implementations Pane (Right Pane)The rightmost pane shows the applicable Data Capture Implementations. This treeis built in two steps. Step one is to populate the Data Capture ImplementationGroups from the targeted Master Agents. The groups are built when the DataCapture Policy Manager frame is opened. In the event that any of the chosenMaster Agents are offline, the Data Capture Policy Manager frame will still open, butwill only create new Implementation Groups based on the data from the onlineMaster Agents. This pane will not accept any object being dropped into it.

Before dragging any elements from this pane to the Data Capture Polices Tree (LeftPane), customized instances of the Data Capture Implementation Groups must becreated. This process will use populated metadata from the Data CaptureImplementation Group that was retrieved from the Master Agent when the Groupwas created. If the selected Group does not have any metadata, or the metadata isblank, the custom implementation takes no parameters and will only prompt for aname to be entered.

Creating a Data Capture Implementation: To create a new Data CaptureImplementation, right-click a Data Capture Implementation Group and choose theNew option. This will open a dialog box that will prompt for all input data based onthe metadata supplied. Enter all data and select OK to complete, or choose Cancelto cancel. If OK is chosen, the Data Capture Implementation will be created for thisImplementation Group. If Cancel is chosen, nothing will be done.


Editing a Data Capture Implementation: To edit an existing Data CaptureImplementation, right-click the Data Capture Implementation and choose the Editoption. This will open the same dialog box as the create did, but pre-populated withexisting inputs.

Figure 91. Data Capture Implementation Group right-click context menu

Figure 92. Data Capture Implementation Creation Dialog


Deleting a Data Capture Implementation: To delete an Implementation from theImplementation Tree, right-click the Implementation and choose the Delete option.This will open a dialog box that will prompt for confirmation. Choose Yes to deletethe object, or choose No to cancel. If Yes is chosen, the Implementation will beremoved from its Implementation Group and all Data Capture Policies to which ithas been added.

To delete all Implementations under an Implementation Group, right-click theImplementation Group and choose the Delete All Implementations option. This willopen a dialog box that will prompt for confirmation. Choose Yes to delete allImplementations in the Implementation Group, or choose No to cancel. If Yes ischosen, all the Implementations will be removed from this Implementation Groupand all the Data Capture Policies to which they had been added.

Data Capture PoliciesData Capture policies contain configuration information about how to collect datathrough the different Data Capture MBeans exposed in the managed environment.For each policy there is a subtask under the Data Capture Policy Manager task.These subtasks can be associated to specific RMA Master Agents, to specify whenand how these Managed Objects will collect the captures.

Figure 93. Data Capture Implementation right-click Context Menu


Associating Data Capture PoliciesTo associate a Policy Manager Subtask with a RMA Master Agent, simply drag thesubtask to the RMA Master Agent, or drag one or many RMA Master Agents to thesubtask. This will associate the Policy Manager Subtask with the chosen RMAMaster Agents and create and activate the corresponding Data Capture Policies onthe chosen RMA Master Agents.

Viewing Associated Data Capture PoliciesTo view associated Policy Manager Subtasks in the Managed Object (Center) Panelin the IBM Director Console, right-click the Associations menu and choose the DataCapture Policies option.

Figure 94. IBM Director Console with Policy Subtasks


Manipulating Associated Data Capture PoliciesThe ability to manually invoke Policy Manager Subtasks will be accessible by wayof a right-click context menu from the association. This menu will display theseoptions:

v Invoke Policy(s) Now

v View Policy Invocation History

v Remove Policy Association(s)

Figure 95. IBM Director Console with associated Policy Subtasks


Removing Policy Associations: The Remove option will remove the associationof the Policy Manager subtask from the RMA Master Agent and terminate andremove the Data Capture Policy on the RMA Master Agent.

Invoking Associated Policy Manager Subtasks: To invoke a policy or policies,select them and right-click to open the context menu. From the context menu,choose the Invoke Policy(s) Now option. This will invoke the selected policies onthe RMA Master Agent systems they are associated with. After the invocationcommands are sent to all applicable RMA Master Agent systems, the PolicyInvocation Status frame will be displayed for the selected policies as described in“Status Frame for Data Capture Policies.”

Status Frame for Data Capture PoliciesTo view the status of a policy or policies, select them and right-click to open thecontext menu. From the context menu, choose View Policy Invocation History.(Also, this can be accessed by double-clicking on any policy association.) This willdisplay the Policy Invocation Status Frame that will provide a view of the currentCapture History status for each selected policy.

Figure 96. Policy Subtask Association right-click Context Menu


Viewing Capture History for a PolicyTo view a RMA Data Capture History, select a policy from the left pane of thedialog. This loads the Capture History for the policy from the RMA Master Agentsystem with which it is associated. During the loading process a status messagewill be displayed at the bottom of the frame. After loading is completed, the rightpane of the dialog will be populated with the Capture History information.

Refreshing the Displayed Capture HistoryThis dialog provides a refresh option from the View Menu to refresh the currentlydisplayed Capture History as shown in Figure 99 on page 136. Also, each time a

Figure 97. Policy Invocation Status Dialog

Figure 98. Policy Invocation Status Dialog - Loading Message


different policy is selected, the RMA Master Agent for that policy is queried forCapture History so that the information displayed will be as up to date as possible.Unfortunately, it is not possible to provide real-time updating to this frame since thedata must be retrieved through a remote call to an RMA Master Agent. It is for thisreason that the refreshing of Capture History data will work as described above.

Deleting from a Capture HistoryOver time, many Invocation Records can build up for a Data Capture Policy. In alarge or busy environment, users might want to clean up Invocation Records for agiven Policy. Use the Data Capture Invocation Status dialog to delete InvocationRecords from RMA by right-clicking the Invocation Record and selecting the Deleteinvocation_record_name option.

Note: This option will not be available until the invocation has completed allcaptures.

This prompts the user on whether to delete the record based on the IBM DirectorConsole Prompting Preferences: Ask for confirmation before deleting anynonrecoverable item (Options > Console Preferences > PromptingPreferences).

Figure 99. Policy Invocation Status Dialog - Refresh


If the answer is Yes to the confirmation message, a command will be sent to theRMA Master Agent to delete the selected invocation record. While the delete is inprogress a message will display. When deletion completes, the Capture History forthe selected policy will automatically refresh.

Retrieving the Capture Bundle for a RMA Data Capture PolicyInvocationAfter a policy invocation completes, a Capture Bundle is created on the RMAMaster Agent that contains all of the files captured. Use the Data CaptureInvocation Status dialog to retrieve the Capture Bundle from RMA by right-clickingthe Invocation Record and selecting the Transfer Capture Bundle option.

Note: This option will not be available until the invocation has completed allcaptures.

The transfer moves the Capture Bundle file from the RMA Master Agent into thedata\rma\capture directory in the IBM Director installation directory on the IBMDirector Server using RMA File Streaming.

The default path is c:\Program Files\IBM\Director\data\rma\capture on a Windowsinstallation and /opt/IBM/Director/data/rma/capture on a Linux installation. While thetransfer is in progress, the status bar at the bottom of the Data Capture InvocationStatus frame will be updated.

Figure 100. Policy Invocation Status Dialog - Dialog Context Menu


Note: For large data capture bundles, the progress message might reset to Readyprior to completion of the transfer.

When the transfer completes, a confirmation dialog box will confirm that the transferwas either successful, or that an error occurred. The file name of the data capturebundle is displayed when the transfer succeeds, which will be similar in name tothis example:alyzee_RetailWindows_Feb022010_160744.zip

Note: Capture bundle files use the following naming convention:filename_Monddyyyy_mmhhss.zip (for example,myserver_MyPolicy_Feb152010_191608.zip). The mmhhss (hours, minutes,and seconds) portion of the filename is in Greenwich Mean Time (GMT).

Power managementThe IBM Director console provides a power management interface for its managedobjects. This interface allows RMA-managed objects to Shutdown and Power Off,Suspend, Restart, and Power On (Wake On LAN).

To utilize power management, right-click on one or more managed objects andselect an option from the power management group in the context menu.

Figure 101. Policy Invocation Status frame - Transferring Message


From here, the power management request is invoked like any other Director task.This means that the request can be executed now or scheduled to run later. Afterthe job has been created or scheduled, an entry will appear under the managedobject. To see this entry, the display of jobs must be enabled under theAssociations menu in the Director Console.

Figure 102. Power management shutdown and restart selections

Figure 103. Power management power on selections


The options available from the power management task menu will be differentbased on both the type of the managed object and its current state (online oroffline). Table 20 outlines the supported options.

Note: Power management is only supported on RMA V2R4 and later agents.

Table 20. Power management support by Agent type

AgentShutdown andPower Off1 Restart1 Suspend1, 6

Power On2, 3, 6

(Wake on LAN)

Linux GeneralAgent, LinuxKiosk GeneralAgent

Yes Yes No Yes

WindowsGeneral Agent,Windows KioskGeneral Agent,SCS Lane

Yes Yes Yes4 Yes

Master Agent,SCS Boss, 4690Controller MasterAgent

No

(If the in-storeMaster Agent ispowered off, allcommunicationis lost with theother agents inthe store.)

Yes No No

(Wake on LANpackets are sentfrom the MasterAgent to otherdevices in thestore. TheMaster Agentmust be onlinefor this to work.)

4690 ControllerGeneral Agent

Yes Yes No No

Figure 104. Power management job example


Table 20. Power management support by Agent type (continued)

AgentShutdown andPower Off1 Restart1 Suspend1, 6

Power On2, 3, 6

(Wake on LAN)

4690 ClassicTerminal

Yes5 Yes5 Yes5 No

4690 EnhancedTerminal

Yes5 Yes5 Yes5 Yes

Notes:

1. Shutdown and Power Off, Restart, and Suspend are available when themanaged object is online.

2. Power On (Wake on LAN) is available when the managed object is offline orsuspended.

3. Power On (Wake on LAN) functionality requires that system BIOS and networksettings are configured properly to support Wake On LAN.

4. Suspend functionality requires that system BIOS and network settings areconfigured properly to support Wake On LAN. The system hardware must beable to support the suspend function.

5. Refer to the 4690 publications for the situations in which power management issupported on a terminal.

6. Due to the continual network communication between a Master Agent andGeneral Agent in an RMA environment, the network card on a General Agentmust be configured to only allow management stations to bring the computerout of standby or to only Wake on Magic Packets, for Suspend and Wake OnLAN to work properly.


Chapter 12. Troubleshooting

This section helps you find information about troubleshooting problems with the IBMRemote Management Agent or the Retail Extensions for IBM Director.

LogsLog data is produced for the Master Agent, General Agent, and Retail Extensionsfor IBM Director.

RMA AgentsThe logs for the Remote Management Agent are written to the following locationsdepending on the operating system. If the product is installed on the defaultlocation, then the location of the silogs directory is as follows:

v Windows: %SI_HOME%\silogs

v Linux: /opt/ibm/StoreIntegrator/silogs

v 4690 Classic: M:\rma\logs

v 4690 Enhanced: F:\rma\logs

The log files are named simgmt.X, with simgmt.0 being the most recent file. Thememory log files are named simgmt_m.X, with simgmt_m.0 being the most recentfile. The RMA Agents use Java logging. The logging configuration file,mgmt_log.pro, is in the %RMA_HOME% directory. If the product is installed in thedefault location, then the location of the %RMA_HOME% directory is as follows:

v Windows: C:\Program Files\IBM\StoreIntegrator\RMA261xxxx

v Linux: /opt/ibm/StoreIntegrator/RMA261xxxx

v 4690 Classic: M:\rma\lib

v 4690 Enhanced: F:\rma\lib

The mgmt_log.pro file is a modified copy of the default Java logging.properties file.For detailed information on how to modify this file, see “Logging configuration” onpage 47.

Additionally, the RMA Agents have the output from the standard out and standarderror streams redirected to files, rma.stdout and rma.stderr, in the silogs directory.

Agent JVM DiagnosticsThe MgmtJVMEnvironment MBean in each agent exposes instrumentation for theJava virtual machine that the agent is running in. This information can be helpful indiagnosing problems in the agent JVM. Also of the MBean interface are twomethods, javaDump() and heapDump(), which produce core dumps and heap dumpsfrom the agent JVM. The javaDump() method produces a Java core text file and theheapDump() method produces heap snapshot files with the .phd extension. Thesefiles get created in the following directory:

v Windows: %RMA_HOME%\

v Linux: /opt/ibm/StoreIntegrator/RMA261xxxx /

v 4690 Classic: M:\adxetc\java2\core\

v 4690 Enhanced: F:\adxetc\java\core\


IBM DirectorThe Retail Extensions for IBM Director use IBM Director Logging (RAS Logging) toprovide log information. You should only enable logging for IBM Director when tryingto debug a problem. Enabling logging can result in a significant performancedegradation.

Note: You can troubleshoot connection issues between IBM Director Server andspecific Master Agents by clicking Connection Log on the Retail StoreDevices tab of the Discovery Preferences window.

This information assumes that IBM Director is installed into its default location onWindows (C:\Program Files\IBM\Director). The files or directories referenced in thissection will reside in the same subdirectories when IBM Director is installed to adifferent location.

Director Event ConfigurationThe Retail Extensions for IBM Director provide a configuration option to tune therate at which the extensions provide events to IBM Director. The default rate is 900events per minute, and it can be changed by specifying theRMA.event.handler.events.per.minute property in the Director installation path inthe \data\TWGServer.prop file. This value will balance the amount of eventsbuffered to disk versus those buffered in memory. The rate can be raised orlowered to control the amount of memory that the Director Servers process uses.

RAS LoggingThe Retail Extensions for IBM Director use the IBM Director logging API. Theinformation provided is designed to enable log collection and the enablement oftracing for Retail Extensions. For detailed information about troubleshooting IBMDirector, refer to the IBM Director documentation.

Log Collection: The easiest way to obtain the logs is to use the rasdump utilityto dump the logs, and to redirect the log output to a file. From the IBM Director logdirectory, run the rasdump program and redirect the output to a file. This exampleshows the command that redirects the logs to the file raslog.txt:

rasdump > raslog.txt

High Log Collection: : When high logging is enabled in the TWGRas.propertiesfile, it is necessary to run the rasdump command as follows in order to see the fulllog:

rasdump -high > raslog.txt

Settings: To change the logging level for the Retail Extensions for IBM Director,the file twgras.properties must be edited to turn on tracing for the set of IBMDirector Components. This file is in the data directory for IBM Director. After editing,the IBM Director Server must be restarted in order for the changes to take effect.


The following line in the file determines the logging level:

twg.ras.comps=0x00000000802C2B17

The hex codes in that example represent the combination of the hex codes for thedifferent components. The following components should be enabled when logging isneeded. Note that a value of -1 for twg.ras.comps will enable tracing for allcomponents, including many not listed here.

v Console: 0x0000000000000001

v Database: 0x0000000000000002

v Core Engine: 0x0000000000000004

v Inventory: 0x0000000000000010

v File Transfer: 0x0000000000000100

v Monitors: 0x0000000000000200

v Scheduler: 0x0000000000000800

v Task activation/deactivation: 0x0000000000002000

v Software Distribution: 0x0000000000040000

v Utility classes: 0x0000000000080000

v User administration: 0x0000000000200000

v Extra bits for OEM components (RMA): 0x0000000080000000

v SOXS Protocol (rarely needed): 0x0000000400000000

The following line in the file determines the maximum size of the logging file:

twg.ras.size=16384

The 16384 in this example limits the file to 16384 KB.

Note: Increase this size to at least 65536 (64 MB) when you enable high logging tocapture a set of logging data.

JVM DiagnosticsIBM Director provides a command line interface for invoking tasks, using the dircliprogram. This interface can be used for producing Java core dumps or Java heapsnapshots of the IBM Director Server JVM to help diagnose problems. To produce aJava core dump, issue the dircli dumpjava command. To produce a heap dump,issue the dircli dumpheap command. Java core text files and heap snapshot files(.phd) are produced in the Director\classes directory.

Figure 105. TWGRas.properties file

Chapter 12. Troubleshooting 145

TroubleshootingUse Table 21 to determine the action to take due to symptoms of commonproblems.

Table 21. Common symptoms

Problem or symptom Solution

RMA devices do notdisplay in the IBM DirectorConsole.

1. Check Discovery Preferences and verify settings for MasterAgent are correct.

2. Check the Connection Log for the Master Agent's entry inthe Retail Discovery Preferences panel.

3. Verify that there is an active network connection betweenthe Master Agent and the IBM Director Servers.

4. Check the configured network interface in simgmt.pro onthe Master Agent.

5. Check the General Agent logs to see if there were errorsstarting the General Agent.

6. Check the Master Agent logs to see if there were errorsmaking a connection to the General Agent.

7. Verify that RMA discovery multicast packets are being sentbetween the computer running the General Agent and thecomputer running the Master Agent.

General Agent devices notdiscovered or offline onIBM Director Console

1. Check firewall settings on Master Agent.

2. Check firewall settings on missing General Agents.

3. If your General Agents are on a different subnet than yourMaster Agent, verify that the TimeToLive parameter is setaccordingly in simgmt.pro on each General Agent.

On Windows the RMAAgent service is notstarted or returns an errormessage when starting.

Check the Windows Application and System logs in theWindows Event Viewer for detailed error messages.


Part 3. Objectives and architecture

Chapter 13. Architecture overview and objectives . . . . . . . . . . 149IBM Remote Management Agent disciplines. . . . . . . . . . . . . . 149Java Management Extensions . . . . . . . . . . . . . . . . . . . 149Mid-level management . . . . . . . . . . . . . . . . . . . . . 150Management model. . . . . . . . . . . . . . . . . . . . . . . 151

Chapter 14. Understanding the architecture . . . . . . . . . . . . . 153RMA Component. . . . . . . . . . . . . . . . . . . . . . . . 153

General Agent. . . . . . . . . . . . . . . . . . . . . . . . 153Embedded Agent . . . . . . . . . . . . . . . . . . . . . 153

Master Agent . . . . . . . . . . . . . . . . . . . . . . . . 153Component's relationship and roles . . . . . . . . . . . . . . . . . 154Agent discovery and health checking . . . . . . . . . . . . . . . . 154

MgmtMasterHealthMBean . . . . . . . . . . . . . . . . . . . 154MgmtClientHealthMBean . . . . . . . . . . . . . . . . . . . . 154Agent application roles . . . . . . . . . . . . . . . . . . . . 155

Embedded Agent (General Agent) . . . . . . . . . . . . . . . . . 156Proxy ObjectNames . . . . . . . . . . . . . . . . . . . . . 157

Events . . . . . . . . . . . . . . . . . . . . . . . . . 158JMX Browser Changes for Local Mode Embedded Agents . . . . . . . 158

Existing Managed Objects . . . . . . . . . . . . . . . . . . 158RMA event infrastructure . . . . . . . . . . . . . . . . . . . . . 159

RMA events (RtlNotifications) . . . . . . . . . . . . . . . . . . 160EventControlMBean . . . . . . . . . . . . . . . . . . . . . 161

Client configuration . . . . . . . . . . . . . . . . . . . . . 162NotificationProcessor . . . . . . . . . . . . . . . . . . . . . 162MgmtNotificationControlMBean . . . . . . . . . . . . . . . . . 162

Logging configuration and forwarding . . . . . . . . . . . . . . . . 162Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . 163CIM Implementation . . . . . . . . . . . . . . . . . . . . . . 163

CIM Adapter MBean . . . . . . . . . . . . . . . . . . . . . 164CIMEventMapper interface . . . . . . . . . . . . . . . . . . . 165

Default extrinsic event registrations . . . . . . . . . . . . . . . 166UPOS indications . . . . . . . . . . . . . . . . . . . . . 166RSS_SpNumericSensorAlert indications . . . . . . . . . . . . . 166MSStorageDriver_FailurePredictEvent indications. . . . . . . . . . 166

CIM configuration . . . . . . . . . . . . . . . . . . . . . . 167File Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 168

FileTransferConnection . . . . . . . . . . . . . . . . . . . . 169Managing file transfer implementations . . . . . . . . . . . . . . 170Storage . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Monitor policy . . . . . . . . . . . . . . . . . . . . . . . . . 171RMA Software Distribution . . . . . . . . . . . . . . . . . . . . 172

RMA Package Distributor MBean. . . . . . . . . . . . . . . . . 174Package JAR file format . . . . . . . . . . . . . . . . . . . 175Getting package files to the Master Agent . . . . . . . . . . . . 175Package staging . . . . . . . . . . . . . . . . . . . . . . 176

Software Distribution Policy . . . . . . . . . . . . . . . . . . . 178Software Policy XML file structure . . . . . . . . . . . . . . . 180Policy XML variables . . . . . . . . . . . . . . . . . . . . 184

Diagnostic Data Capture . . . . . . . . . . . . . . . . . . . . . 184DataCaptureMBean. . . . . . . . . . . . . . . . . . . . . . 185

Capturing Data . . . . . . . . . . . . . . . . . . . . . . 185


||

||||||||||

Capture Processing. . . . . . . . . . . . . . . . . . . . . 186DataCaptureMBeanSupport . . . . . . . . . . . . . . . . . . . 187Data Capture Policy . . . . . . . . . . . . . . . . . . . . . 188RMADataCaptureMBean . . . . . . . . . . . . . . . . . . . . 189DataCaptureManagerMBean . . . . . . . . . . . . . . . . . . 189

DataCapturePolicy class . . . . . . . . . . . . . . . . . . . 190Capture policy application . . . . . . . . . . . . . . . . . . 191Capture bundle directory . . . . . . . . . . . . . . . . . . . 191Policy invocation . . . . . . . . . . . . . . . . . . . . . . 192Post Capture File Transfer and Processing . . . . . . . . . . . . 192Retries and Maintaining Capture History Information. . . . . . . . . 193


Chapter 13. Architecture overview and objectives

The goals of the IBM Remote Management Agent architecture are to:

v Provide a single-store or multi-store view for management.

v Use an open, standards-based instrumentation model.

v Maintain strict isolation between components and management tools, so that allmanagement applications behave in a consistent manner.

v Expose device and application instrumentation.

IBM Remote Management Agent disciplinesIBM Remote Management Agent supports the disciplines described in Table 22.

Table 22. IBM Remote Management Agent managed disciplines

Configuration Provides support for local and remote configuration of managed software andhardware components.

Inventory Provides support for local and remote inventory reporting of both software andhardware components. For software components, the inventory informationtypically includes product description, product manufacturer, and product versioninformation (including maintenance levels).

Event notification and forwarding Hardware and software components can generate notification events that aremonitored by IBM Remote Management Agent applications. The events caninclude normal operational or error information. The architecture presents amulti-tiered framework for collecting and filtering events at the store level foraccess by an enterprise system management application.

Remote operations Component MBeans within the IBM Remote Management Agent can providevarious remote operations.

Software distribution Provides support for the automated installation or uninstallation of softwarepackages.

Monitoring Provides support for the monitoring of MBean attribute values with notificationevents being generated when monitoring conditions occur.

Power management Provides support for remotely controlling the power states of store systems.

Data capture Provides support for performing diagnostic data captures, along with store-widepolicies to transfer capture files and invoke captures on other components.

File transfer Provides support for performing file operations remotely, including the ability tosend, receive, and view files.

Java Management ExtensionsThe IBM Remote Management Agent architecture is based on Java ManagementExtensions (JMX). The JMX Specification describes a general managementframework for any Java (or even non-Java) program. It is a multi-tier architecturethat includes an instrumentation layer, MBeans, an agent layer, MBeanServer, anda management layer. MBeans are Java objects that expose a managementinterface for a managed resource.

All MBeans within a Java virtual machine are registered with an object repositorycalled an MBeanServer. The MBeanServer provides access to each MBean'sattributes and operations, and it handles the sending of notifications (events).


MBeans become useful for the IBM Remote Management Agent when theirinterfaces are exported so that they can be accessed by remote managementapplications. Refer to the latest Java Management Extensions (JMX) Specification(java.sun.com/products/JavaManagement/) to obtain complete information about theJMX framework. JMX is used both internally and externally to implement thedisciplines discussed above.

Mid-level managementThe IBM Remote Management Agent uses a mid-level manager or proxy approachto isolate the management tools from the infrastructure and to treat the store as thepoint of management control. It does this by acting as a proxy for all of theresources (JMX MBeans) in the store. This single store, single agent view becomesthe interface for all outside management actions. Collectively, this environment isreferred to as the Remote Management Agent. It introduces a new point ofcollection and control in the store that becomes the focus of all outsidemanagement actions, and is responsible for executing all management actions.Figure 106 is a diagram of the mid-level manager environment.

Figure 106 shows how the IBM Remote Management Agent is modeled using themid-level manager approach. All instrumentation exposed on the managed deviceshas a single implementation model and is provided by the vendor of the devicebeing managed, not by the management application vendor. The agents providedby management tool vendors are neatly contained above the mid-level manager(Master Agent) and have equal access to the system.

Figure 106. Mid-level management


http://java.sun.com/products/JavaManagement/

Management modelThe IBM Remote Management Agent model is broken down into well defined roles,with well defined relationships among them. The goal to make it easier fordevelopers of non-IBM software and users who want to build upon the availablesoftware to know where in the model their component fits, and what theirresponsibilities are in building that component. All IBM Remote Management Agentcode falls into one of the following four roles, and must adhere to the definedresponsibilities for that role:

1. Management General Agent (sub-agent):

v Runs in every component that makes up the store environment.

v Defines manageable attributes and functional entry points, as needed, andexposes them for use within the environment.

v Defines and issues notifications.

2. Management Agent API (Master Agent):

v Provides the implementation for communications between the managementsub-agents and management agent(s).

v Exposes a collective management interface representing all managementsub-agents for use by all management agents and management applications.

v Manages filtering and forwarding of notifications to Management Agents andManagement Applications.

v Provides a point of implementation and control for store-wide policy (such assoftware distribution and monitor control).

3. Management Agent (optional):

v Uses the Management Agent API for interacting with managementsub-agents.

v Central point of contact and communication proxy for its correspondingmanagement application.

v Single presence of the management vendors toolset in the IBM RemoteManagement Agent environment.

v Provided by Tivoli, ThinkVantage, or another provider.

4. Management Application:

v Located in the enterprise or the store.

v Provided by Tivoli, ThinkVantage, or others.

v Enables access (either automated or operator driven) to the IBM RemoteManagement Agent functions (MBeans).

v An example is IBM Director plus RMA Extensions.

Chapter 13. Architecture overview and objectives 151

Chapter 14. Understanding the architecture

The IBM Remote Management Agent implementation is based entirely on JavaManagement Extensions (JMX), which is the management and instrumentationstandard for Java. JMX is defined by JSR-003, and deals only with managementissues within the context of a single JVM. Each agent running within the IBMRemote Management Agent environment is built upon a single JMX agent(MBeanServer) and on instantiated resources registered with the agent calledMBeans.

To complete the IBM Remote Management Agent infrastructure hierarchy, someadditional remote connectivity support is required. This support provides thecommunications bridge between each of the management roles previouslydiscussed. The standard that defines the remote interfaces for accessing a JMXAgent, JSR-160, provides this remote connectivity support.

The following sections describe the primary components of the IBM RemoteManagement Agent infrastructure.

RMA ComponentTwo primary components make up the JMX infrastructure for the IBM RemoteManagement Agent environment: the General Agent and the Master Agent. Both arerequired by the IBM Remote Management Agent to manage the store. Their rolesare distinguished by the MBeans that are attached to them, with the General Agentreceiving MBeans designed for the client, and the Master Agent receiving thoserequired for control of the store.

General AgentThe General Agent is designed for use within all endpoint devices within the storenetwork. Examples include the POS controllers and terminals, Mobile Tablets forRetail, and kiosks. The General Agent, by default, includes MBeans to handle clientdiscovery, provide JVM information, and handle the configuration and forwarding forlogging. It can be instantiated from inside an application JVM as an embeddedagent, or run as a service in its own JVM.

Embedded AgentEmbedded Agents are General Agents that get instantiated within an applicationJVM. With RMA V2R6, embedded agents include a local or remote embeddedagents, as discussed in “Embedded Agent (General Agent)” on page 156.

Master AgentThe Master Agent is the single point of access for all store resources. It is based onthe same functionality as the General Agent, and devices that it runs on can bemanaged. To manage the rest of the devices in the store, the Master Agent has anadditional set of MBeans loaded at agent startup. This set of MBeans includesthose MBeans for managing the proxy relationships with General Agents runningwithin the store. Additionally, there are policy MBeans managing softwaredistribution, monitors, and notifications.


||||||

||

||||

Component's relationship and rolesThe role of the Master Agent is to discover the General Agents that exist within theenvironment, to create proxy MBeans for MBeans that exist on those GeneralAgents, and to control all interactions among them. By doing this, a single view ofall MBeans in the environment are presented at the Master Agent, giving themanagement application a single point of control for the entire environment.

Note: Only one Master Agent can manage a given General Agent. The first MasterAgent to discover a General Agent will be the only agent that is allowed toconnect to that General Agent.

This functional hierarchy becomes more important for disciplines that require somedistributed policy control, such as software distribution or device monitoring.Components responsible for managing a discipline on the Master Agent interactwith the appropriate General Agent MBeans to carry out an operation based onnotifications emitted when devices are online or offline.

Agent discovery and health checkingThe Master Agent component provides discovery of general agents within the store,and monitors their continued health and status. This function provides a simplediscovery and health checking mechanism that is both reliable and inexpensive inthe store environment. This function group triggers the creation and deletion ofdevice information on the Master Agent. These triggers, in the form of JMXNotifications, can be used by other management applications to triggermanagement functions, like inventory.

Implementing this function requires two MBean interfaces: MgmtClientHealthMBeanand MgmtMasterHealthMBean. The MgmtClientHealthMBean interface, implemented asthe General Agent, provides a simple periodic heartbeat containing agentinformation. The MgmtMasterHealthMBean interface, implemented as the MasterAgent, listens for client heartbeats, emits notifications when agents are discoveredor go offline, and maintains information about each discovered agent. It alsoregisters to listen for JMXConnectionNotifications from the JSR-160implementation.

MgmtMasterHealthMBeanThe MgmtMasterHealthMBean is located at one place in the store: the Master Agentrunning on the in-store processor. This component is responsible for:

v Listening for periodic heartbeats from agents running within the store.

v Maintaining information about each discovered agent.

v Controlling the emission of AgentLostNotifications.

v Triggering the construction and tearing down of connections betweenmanagement agents.

Note: Other functions on the Master Agent are driven by these notifications, suchas pending software distributions, application of monitors, and any otherspecific response that might be required by management applications.

MgmtClientHealthMBeanThis entity is located within each General Agent running within the store, and isresponsible for the following:

v Collecting agent information for use in the agent discovery protocol


v Issuing periodic discovery frames for consumption by the MgmtMasterHealthMBean

The Remote Management Agent utilizes a simple discovery/heartbeat mechanismfor determining the status of General Agents on the network. This mechanism iscomprised of two components, where the MgmtClientHealthMBean is located withinthe General Agent and is responsible for generating a heartbeat at regular,configurable intervals. The second component is the MgmtMasterHealthMBean, whichis located in the Master Agent. Its job is to listen for the heartbeats generated bythe General Agents, and use that to decide whether the heartbeat represents a newdevice or an existing healthy one. However, if the Master Agent misses aconfigurable number of heartbeat frames (as defined on the client, and carried in itsheartbeat frame), then the device is considered to be offline by the Master Agent.The RMA Master Agent generates two different Notifications, one for a GeneralAgent coming on-line, and one for a General Agent going off-line. Thesenotifications are used internally by the Master Agent to control the creation andremoval of proxied MBeans at the Master Agent that control the visibility of thoseMBeans in the complete Remote Management Agent environment. Since these areJMX Notifications, they can be used by Management Applications using the RemoteManagement Agent, or by other local MBeans as the applications requires. Forexample, an application that is attempting to track store assets.

This discovery mechanism is implemented using Multicast User Datagram Protocol(UDP) frames. UDP was chosen for its simplicity, as well as its limited requirementson the system and network. Generating these discovery frames requires very littleof the system, and consumes almost no network bandwidth. Since this mechanismis based on Multicast traffic, there are trade-offs. While it presents limited demandson the system and network, it does require some forethought when configuring thenetwork. Multicast traffic is confined to a single IP subnet and therefore is an assetfor this discovery mechanism because it always remains localized to the subnet,and consequently the store. If the store contains only a single subnet, there are nospecial considerations to setting up the network. However, if the store containsmore than one subnet, and devices exist on those multiple subnets that need to bediscovered as the Remote Management Agent's domain, then the routers betweenthose subnets must be configured to pass the discovery multicast traffic. Also, theTime to Live (com.ibm.retail.si.mgmt.generalagent.discovery.ttl) parametermust be configured accordingly on each RMA General Agent in the simgmt.pro file.For purposes of configuration, the Discovery mechanism employed in the RemoteManagement Agent uses the following addressing information:

v Multicast Address: 225.6.29.63

v Port: 31200

The MgmtMasterHealthMBean uses an algorithm that determines the arrival of adiscovery frame from an agent, indicates it is available, and causes a missedinterval counter to be reset. If a configured number of discovery frames are missed,based on the interval configured for their transmission, then the agent is consideredoff-line.

Agent application rolesDuring agent startup, each General and Master agent automatically detects itsdevice type, indicating the platform (for example, Windows XP, Linux, or 4690). Thisinformation, along with the agent's device ID, is kept with the device information foreach agent (com.ibm.retail.si.mgmt.MgmtDeviceInfo). It is also useful in applyingpolicies to agents running in the store, where policies can be applied to all agentsbased on device type. However, device type alone might not always provide enoughflexibility to apply policies to a specific set of devices.

Chapter 14. Understanding the architecture 155

To help provide more criteria for applying policies, agents have the ability to haveone or more application roles assigned to them. These roles indicate whichapplications and which versions of those applications are running on the system.Roles and model numbers are specified with an XML file and read by the RMAMaster or General Agent, and are exposed as agent attributes, just like device IDand device type. The MgmtMasterHealthMBean and MgmtClientHealthMBeans(Discovery) contain an attribute for their roles. Additionally, a getModels() methodexists to get the model numbers for a role. The role and model information for allagents is kept on the Master Agent in the RemoteServerPoolMBean.

Additional information about Agent roles and their configuration can be found in“Agent roles” on page 52.

Embedded Agent (General Agent)Embedded Agents are General Agents that can be instantiated within an applicationJVM. Prior to RMA V2R6, embedded agents and RMA Service agents werediscovered by a store Master Agent in the same manner. The Master Agent made aseparate JMX connection to each General Agent, regardless of the type. Eachagent was treated as a separate device by the Master Agent, and in IBM Directoreach agent appeared as a separate managed object. Figure 107 illustrates anEmbedded Agent model prior to RMA V2R6:.

The design for embedded agents was changed in RMA V2R6 to include twoembedded agent modes: local or remote. A remote mode embedded agent isdiscovered as a separate management object with its own JMX connection, whichis the design for RMA V2R6 or earlier. Local mode embedded agents arediscovered locally by an instance of the RMA Service agent. The embedded agent'sinstrumentation is accessible through the JMX Connection to the RMA ServiceAgent, through MBean proxies. As a result, the embedded agent's instrumentationis accessible only when an RMA Service agent is running and has discovered theagent. Figure 108 on page 157 illustrates an Embedded Agent model for RMA

Figure 107. Embedded Agent model (Prior to V2R6)


|

|||

|

||||||||

|||||||||

V2R6 or later releases:

In addition to specifying the agent mode (local or remote) when creating anembedded agent, an optional agent ID can be supplied to identify the JVM orapplication the agent is running in. This agent ID will be seen inside the JMXBrowser in the IBM Director.

Proxy ObjectNamesThe ObjectNames for embedded agent proxy MBeans conforms to a set ofconventions in order to make the names unique, and in order to be able to easilylocate MBeans registered with each embedded agent. In addition to the deviceIdand systemId keys already added to MBean ObjectNames, an additional agentIdkey is added to each proxy ObjectName. Non proxy MBeans registered with theservice agent will not have the agentId key:

Figure 108. (V2R6 or later)


|

|||

||

||||

|

|||||||

EventsWhen running in local mode, events sent by any embedded MBean are received bythe service agent, where they are forwarded to the RMA event infrastructure fordelivery up to a Master Agent. When the RMA Service agent is not connected to anembedded agent, events sent from within the embedded agent are not stored forlater delivery to the service agent. However, once events are received by theservice agent, they are stored and forwarded if the service agent is not connectedto a Master Agent.

JMX Browser Changes for Local Mode Embedded AgentsThe JMX Browser in V2R6 and later provides functionality to separate and easilybrowse the MBeans from each RMA agent (embedded or service) on a system.Each agent is represented with its own level in the JMX Browser tree. The RMAService agent is always present (even for older managed objects), and will have itsinstrumentation listed under RMA Service, which is always listed first. Anyembedded agents are listed under a node with the Embedded Agent: title, alongwith its agent ID.

Existing Managed ObjectsCustomers who have discovered older embedded agents have multiple IBMDirector managed objects for those agents, which all have the same name. Aftermaking changes to use local mode embedded agents, those managed objects willstay offline permanently (unless the embedded agent is run in remote mode). Theolder managed objects are not automatically removed. You will need to manuallydelete the objects.

Figure 109. Proxy Objectnames


|

||||

||||||||

|

|||||||

|||||||

RMA event infrastructureThe RMA event infrastructure provides access to all events emitted in the store. Oneach agent, all events sent by agent MBeans are received and processed by anEventControlMBean. The manner in which events are processed depends onwhether the store and forward feature is enabled. If store and forward is disabled,then events are simply re-emitted with no guarantee of delivery. Use caution whendisabling store and forward, as all events that take place on agent startup before aremote connection has been established will be lost. This can also prevent softwaredistribution tasks that cause an agent to reboot from completing successfully on theIBM Director Server. When store and forward is enabled, events are delivered toeach remote connection. When not connected, the events are buffered andperiodically persisted. RMA also takes over the transport of the events from JMXwhen store and forward is enabled, because JMX does not provide guaranteeddelivery.

On the Master Agent, events emitted from all General Agent EventControlMBeansand Master Agent MBeans are received by the NotificationProcessor andforwarded to the MgmtNotificationControlMBean, where they are processed andre-emitted for listening management applications. An EventControlMBean also existson the Master Agent, so that Management applications can receive events from allagents in the store from one location. Figure 110 on page 160 outlines the RMAEvent Infrastructure.


RMA events (RtlNotifications)RMA provides its own event classes in order to provide additional informationspecific to RMA, and to provide each event with a severity. The base class for allRMA events is RtlNotification. Each subclass defines a different event severity.The following are the RMA event classes in order of severity:

v com.ibm.retail.si.mgmt.notifications.RtlCriticalNotification

v com.ibm.retail.si.mgmt.notifications.RtlEmergencyNotification

Figure 110. Event infrastructure


v com.ibm.retail.si.mgmt.notifications.RtlAlertNotification

v com.ibm.retail.si.mgmt.notifications.RtlErrorNotification

v com.ibm.retail.si.mgmt.notifications.RtlWarningNotification

v com.ibm.retail.si.mgmt.notifications.RtlNoticeNotification

v com.ibm.retail.si.mgmt.notifications.RtlInformationNotification

v com.ibm.retail.si.mgmt.notifications.RtlDebugNotification

v com.ibm.retail.si.mgmt.notifications.RtlTracePointNotification

v com.ibm.retail.si.mgmt.notifications.RtlConsumerNotification

Besides providing an inherent severity through their type, RtlNotificationsubclasses provide additional information that base JMX Notifications do not. Anexample of this is translation information for the event message. A resource bundleclass, message key, and message parameters (passed to MessageFormat) can beset on each RtlNotification and can be used wherever events are displayed.

RtlNotification also supports the concept of event qualifiers, which is a set ofordered strings intended to describe the type of event. The idea is for each string togo from general to specific, describing the event in a hierarchical manner. A stringarray of event qualifiers can be set on each RtlNotification. The setting of eventqualifiers is optional. A default array ("Retail," "base") is set on eachRtlNotification by default.

When events are transmitted, the RMA event infrastructure updates a field in eachRtlNotification that has a MgmtDeviceInfo object corresponding to the agent thatsent the event. The MgmtDeviceInfo can be accessed from thegetOriginatingDevice() method. The Store ID in each MgmtDeviceInfo instance willbe null until it is received by a Master Agent.

Like JMX Notifications, an object can be supplied to the notification as user data. Itis important to use objects whose types can be resolved in all Java virtualmachines. Otherwise, RMA will be unable to deserialize event objects as they aretransferred between agents. Strings, Java primitive wrapper types (Integer, Double,Long, and so forth), and collections of these types are viable options. Also, theRtlNotification subclasses should not be further subclassed, for this samereason.

EventControlMBeanThe EventControlMBean forms the client portion of the RMA event infrastructure. Itacts as a central point of control and access for all events emitted on the RMAAgent. On the General Agent, this MBean adds itself to all MBeans that emitevents. On the Master Agent, this MBean adds itself as a listener to theMgmtNotificationControlMBean. Upon receiving an event, it either re-emits it orbuffers the event, based its connectivity status of the remote connection, (MasterAgent or Management Application), and whether store and forward is enabled.Whenever a connection is closed, lost, or does not exist, events are buffered in theorder in which they were emitted. The buffer is periodically persisted so that it canbe restored at the point in which it left off whenever the agent is restarted. Whiledisconnected, events continue to be buffered, across one or more restarts of theagent. When the remote connection is re-established, events in the buffer beginbeing emitted, starting with the earliest event and continuing until the buffer hasbeen emptied.


Client configurationDue to the possible resource constraints (memory, disk space), participation inevent store and forwarding is configurable, as is the number of events that arebuffered per remote connection. The configuration for store and forwarding is donein the RMA configuration properties file, simgmt.pro. These properties are describedfurther in “Agent configuration file” on page 41:

These properties can be changed by editing the simgmt.pro file, or through theMgmtAgentConfigurationMBean, with which you can modify the simgmt.pro file.

By default, an embedded General Agent does not support store and forwarding.The installed RMA Agent Services will, by default, participate in event store andforwarding, and will buffer 200 000 events. At an average event size of 500 bytes,this equates to roughly 100 MB of disk storage.

NotificationProcessorThe NotificationProcessor acts as a central collection point for all events. Ithandles the fetching and delivery of all events from each remote agent. By callingthe addEventFetcher() method, a remote JMX Connection to a RMA Agent getsregistered with the RMA Agent. This registration begins the flow of events from theRMA Agent to the NotificationProcessor. A separate thread is created to makeremote calls to the agent to fetch groups of events.

As events are fetched they are enqueued until they can be delivered. An overflowfile is used to store incoming events when the memory queue size reaches aconfigurable threshold. The memory queue size, and other configuration parametersfor event fetching are described in Table 5 on page 43.

As each event is delivered, it is forwarded to registered listeners through itssupporting listener interface (NotificationProcessorListener). On the MasterAgent, this listener interface is implemented by the MgmtNotificationControlMBeanto receive all store notifications.

MgmtNotificationControlMBeanThe MgmtNotificationControlMBean, running on the Master Agent, provides a singlepoint of access to a management application for all store events. By adding aNotificationListener to this MBean, all store events can be accessed by amanagement application in real time as they are emitted. It works by registeringwith the NotificationProcessor, receiving all Notifications from any General Agentor Master Agent MBean, performing some additional processing on them, andretransmitting them.

Logging configuration and forwardingThis set of MBeans performs logging level configuration that provides the ability toremotely make non-persistent changes to logging levels. Restarting the agent JVMcauses the logging levels to revert to their persistent values.

com.ibm.retail.si.mgmt.eventcontrol.storeandforward=truecom.ibm.retail.si.mgmt.eventcontrol.storeandforward.maxevents=200000com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffersizethreshold=1000com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffertimethreshold=3000000com.ibm.retail.si.mgmt.eventcontrol.storeandforward.eventExpirationTimeout=7com.ibm.retail.si.mgmt.eventcontrol.storeandforward.eventExpirationCleanupFrequency=1


||||

The MgmtLoggingCtrlMBean controls the creation of all logging MBeans during agentstartup. Based on the logging packages detected, the appropriate logging andremote logging MBeans are created. Table 23 is a summary of the logging MBeansthat can be created.

Table 23. Logging MBeans

MBean Name and ObjectName ID Description

MgmtLoggingCtrlMBean MBean started on all agents that sets up remote loggingMBeans and internal logging MBeans for all applicable logtypes. The default remote logging level is OFF.

Log4JLoggerMBean(Id=Log4JLoggers)

MBean used to dynamically change the Log4J logging level(TRACE,DEBUG,etc) for any logger in the hierarchy.Instantiated if the system detects Log4J.

JDKLoggerMBean(Id=JDKLoggers)

MBean used to dynamically change the JDK logging level(FINEST,FINE,etc) for any logger in the hierarchy.Instantiated if the system detects JDK Logging,

JDKHandlerMBean(Id=JDKHandlers)

MBean for dynamically changing the JDK logging level forany of the JDK logging handlers.

InventoryThe function of inventory is to collect data about both hardware and softwarecomponents that comprise the system as a whole. It is the collection of specificattribute information from the agent infrastructure. As such, the function of collectinginventory is different than providing the correct information for collection. Theprocess of collection is best left to the management application vendors. However,the requirements to define a base level of inventory to be made available to thoseapplications are discussed in the following paragraph.

Given that each software and hardware component can be represented by MBeans,the best approach for introducing inventory data is to define Java Interfaces thatsupport the retrieval of this information. This lets the inventory collection be addedto the MBean that is most appropriate. The consumer of the inventory data, namelymanagement agents and applications, can search out the predefined interfacesusing normal JMX interactions. The IBM Remote Management Agent API definestwo MBean interfaces for software and hardware inventory,MgmtSoftwareInventoryMBean and MgmtHardwareInventoryMBean. These interfacedefinitions are based on the work done by the Distributed Management Task Force(DMTF) for both Desktop Management Interface (DMI) and Common InformationModel (CIM). This information is consistent with that used by the Tivoli managementsoftware as well.

CIM ImplementationCIM is a schema used to model the elements that comprise a completemanageable system. As a standard, it is owned and maintained by the DMTF and iswidely adopted as the mechanism to use when modeling and exposing componentsfor management. For example, all variants of Microsoft Windows since NT 4.0 haveused an interface known as Windows Management Infrastructure (WMI), animplementation of the CIM model, as their internal and external managementinstrumentation model.


CIM also supports events, otherwise known as indications. There are two types ofindications: intrinsic indications and extrinsic indications. Intrinsic indications aresent when a CIM object is created or deleted. Extrinsic indications are eventsemitted by the provider for a CIM class, such as a state change or an alert for apiece of hardware.

CIM Adapter MBean

RMA infrastructure contains a CIM/JMX Adapter, or CIMAdapterMBean, used totranslate managed objects from CIM into JMX. Specifically, this MBean createsproxy MBeans for objects surfaced by the system's CIM Object Manager (CIMOM).The CIMAdapterMBean also registers with the CIMOM for extrinsic indications,creating and emitting RtlNotifications from the indications received.

The CIM implementations currently supported are the Windows WMIimplementation and the Pegasus implementation on IRES. On unsupported CIMimplementations, the CIMAdapterMBean is instantiated but does not create any proxyMBeans (the active attribute is false). Indications are only supported on WMI.

Note: The CIMAdapterMBean has a property called NativeTraceEnabled to turn ondebug tracing for CIM. This property is only applicable for the Windowsplatform.

The CIMAdapterMBean works by creating proxy MBeans for CIM instances whoseclass name exists in the class filter in a CIM namespace. Adding a class name to thefilter not only creates proxies for CIM instances of that class, but for all of itssubclasses as well. Likewise, removing a class name from the class filter removesall proxy MBeans created for that class and all of its subclasses. The MBean iscreated with a default set of namespace configurations that can be modifiedprogrammatically or from the JMX Browser from within IBM Director.

All CIM proxy MBeans are categorized under the component name CIM in the JMXBrowser as shown in Figure 111 on page 165.


CIMEventMapper interfaceThe CIMAdapterMBean receives indications from the CIMOM in the form ofjavax.wbem.cim.CIMInstance objects. CIM indications are CIM instancesthemselves, so their structure is defined in a MOF file. Because each event typehas a different structure and meaning, the corresponding JMX Notifications will alsobe different. The easiest way to convert CIMInstances into JMX Notifications isthrough Java code, with an instance of thecom.ibm.retail.si.mgmt.cim.CIMEventMapper interface. The association betweenthe CIM indication class and the CIMEventMapper implementation is made in the CIMadapter configuration XML file, %SI_HOME%\user\rma\config\CIMConfig.xml.

The CIMEventMapper interface's createCIMNotification() method performs theconversion by returning an RtlNotification object from the supplied CIMInstanceobject. The details of how RtlNotifications are created, their severity, and formatare left up to each CIMEventMapper implementation.

The CIMEventMapper interface requires that implementations process eachCIMInstance and create an RtlNotification from it. The severity of the Notificationis determined by the type of RtlNotification class instantiated (that is,RtlInformationNotification, RtlWarningNotification, RtlErrorNotification, andso forth). For each event, the implementation can set:

v The event qualifiers

v Translation information

v Optional user data field (of type object) that is of every JMX Notification

Figure 111. CIM proxy MBeans for component names


Note: When setting the user data field, it is important to use types that areguaranteed to be in the class path of all JVMs that could receive the event(General Agent, Master Agent, IBM Director, or any other managementapplication that interacts with the Master Agent).

Default extrinsic event registrationsDefault installation on Windows and Linux adds one extrinsic event registration:

v UPOS_SysMgmtEvent: Indications emitted by UPOS peripherals

Default installation on Windows adds two additional extrinsic event registrations:

v RSS_SpNumericSensorAlert: State change indications emitted by the serviceprocessors on IBM POS systems

v MSStorageDriver_FailurePredictEvent: Predictive failure indications for SMARThard drives (WMI only)

UPOS indicationsUPOS_SysMgmtEvent indications are emitted by the UPOS drivers for retailperipherals. The indications emitted originate from all UPOS Status Update Events.Refer to the UnifiedPOS specification for detailed information on all UPOSindications.

The CIMEventMapper instance for UPOS indications iscom.ibm.retail.si.mgmt.cim.upos.UPOSEventMapper. This class, shipped with RMA,will create RtlNotifications from instances of UPOS_SysMgmtEvent. TheRtlNotifications are created based on the information in two separate propertiesfiles: UPOSEventQualifiers.properties and UPOSEventSeverities.properties.UPOSEventQualifiers.properties lists the events that are supported by RMA,mapping the UPOS device type and event type codes to the RMA event qualifiersfor that event. UPOSEventSeverities.properties maps each set of event qualifiers toa severity, which will be the severity of the event created. The initial versions ofthese files installed by RMA support the 1.10 version of the UPOS specification.Both files are installed into %SI_HOME%\user\rma\config\cim and managed by theUPOSEventConfigMBean.

The UPOSEventConfigMBean is registered by the UPOSEventMapper in order to managethe severities and event types. The exposed attributes are the event qualifiernames, with the values being the severity constant value for that type of event(ALERT, CRITICAL, DEBUG, EMERGENCY, ERROR, INFO, NOTICE, OFF,TRACE, WARN, all defined as constants in class UPOSEventConfig). Also includedare methods for adding and removing event types. All changes made through theMBean take effect immediately and are persisted.

RSS_SpNumericSensorAlert indicationsRSS_SpNumericSensorAlert indications are emitted by the service processors in IBMPOS systems. The indications are emitted when the service processor changesstates, of which there are two: OK and Critical. The following summarizes the eventqualifiers and severities for each type of event:

v Retail.hw.serviceprocessor.sensor.numeric.state.critical (Alert)

v Retail.hw.serviceprocessor.sensor.numeric.state.ok (Info)

MSStorageDriver_FailurePredictEvent indicationsMSStorageDriver_FailurePredictEvent indications are emitted on Windows systemsthat have SMART (Self-Monitoring, Analysis and Reporting Technology) enabled


drives. The indications warn of a possible failure in the future. All indications resultin an Alert level RtlNotification with the qualifiersRetail.hw.storage.failure.predict.

CIM configurationThe CIM Adapter configuration is stored in an XML file, %SI_HOME%\user\rma\config\cim\CIMConfig.xml. Versions of RMA prior to V2R2 stored their CIMconfiguration in the agent properties file, %SI_HOME%\user\rma\simgmt.pro. Uponupgrading, those configuration settings are migrated. When RMA is installed freshor when the configuration XML file does not exist, it will be created with defaultvalues. The following is an example:

The top level element, CIMConfig, has one attribute, eventPollingInterval. Thevalue of this attribute represents the number of seconds between polling requestsfor CIM lifecycle events.

Underneath the CIMConfig element is a CIMNamespaceConfig element, whichcontains the configuration for each CIM namespace the CIM Adapter connects to.Each namespace configuration element has a section for the namespace class filter.There is a ClassFilterElement for each class in the filter, which represents a classfrom which the CIM Adapter will query and create CIM Proxy MBeans. ThelifeCycleEvents attribute determines whether an attempt is made to register toreceive lifecycle events for that class.

Note: Polling for lifecycle events can be a processor-intensive action, and youshould only enable it for CIM Classes whose instances are expected tochange after the system starts (that is, peripheral devices).

<CIMConfig eventPollingInterval="30"><namespace="root\cimv2">

<EventConfiguration><EventRegistration cimClass="UPOS_SysMgmtEvent"

mappingClass="com.ibm.retail.si.mgmt.cim.upos.UPOSEventMapper"/><EventRegistration cimClass= RSS_SpNumericSensorAlertmappingClass= com.ibm.retail.si.mgmt.cim.RSSSensorDriverEventMapper /></EventConfiguration><ClassFilter>

<ClassFilterElement lifeCycleEvents="true">Win32_BaseBoard</ClassFilterElement><ClassFilterElement lifeCycleEvents="true">Win32_BIOS</ClassFilterElement><ClassFilterElement lifeCycleEvents="true">Win32_CacheMemory</ClassFilterElement><ClassFilterElement lifeCycleEvents="false">Win32_LogicalDisk</ClassFilterElement>

...and so forth

</ClassFilter></NamespaceConfig><NamespaceConfig namespace="root\wmi">

<EventConfiguration><EventRegistration cimClass="MSStorageDriver_FailurePredictEvent"mappingClass="com.ibm.retail.si.mgmt.cim.upos.MSStorage_FailurePredictEventMapper"/>

</EventConfiguration><ClassFilter>

<ClassFilterElement lifeCycleEvents="false">MS_SmBios</ClassFilterElement>

...and so forth

</ClassFilter></NamespaceConfig>

</CIMConfig>


Use methods in the CIMAdapterMBean interface to edit the class filter of the XMLconfiguration. These are the methods:

v addClassToFilter(NameSpace,Class)

v removeClassFromFilter(NameSpace,Class)

v setClassFilter(NameSpace,String[])

The methods that do not take a namespace argument no longer exist.

The CIM Adapter registers to listen for extrinsic indications based on itsconfiguration information. Each extrinsic indication CIM event class listed in theconfiguration has a corresponding CIMEventMapper class, used when creatingRtlNotifications. The configuration XML for each namespace can contain anEventConfiguration element, which can contain one or more EventRegistrationsub-elements. The EventRegistration elements require a CIM Event class, for thetype of events for which to listen, and the fully qualified classname of aCIMEventMapper class, to be used for creating RtlNotifications from the CIMEvents.

Use methods in the CIMAdapterMBean interface to edit event registrations. Themethods are:

v addExtrinsicEventRegistration(Namespace, Event Class, CIMEventMapperClass)

v removeExtrinsicEventRegistration(Namespace, Event Class)

Note: The configuration XML file should not be changed while the agent is running,because it is possible that the changes will get overwritten by the agent. Thisfile can be edited when the agent is not running, or through theCIMAdapterMBean interface. Changes made through the MBean interfacewill not only be dynamic, but will also be persisted.

File TransferTo support the transfer and consolidation of data from client devices, RMA includesa file transfer interface. You can use this functionality to initiate file transferoperations to and from the agent, so that, in the case of diagnostic captures,captured data can be consolidated into one location following a completed capture.Instances of the FileTransferConnection interface provide the file transferfunctionality. RMA includes an implementation of this interface,RMAFileTransferConnection, for performing file transfer operations. For transfers toand from agents running RMA V2, implementations exist for FTP and FTPS (FTPover SSL). The following diagram illustrates how the file transfer interface fits intothe RMA architecture:


FileTransferConnectionThis interface is implemented by all file transfer implementations, with the intent forit to be FTP-like, having put() and get() methods that define a session-oriented,synchronous transfer. Each connection has a connection ID (type long), which isreally a system timestamp of when it was created. This connection ID serves as akey for identifying the connection with the FileTransferManager.

RMAFileTransferConnection is the primary implementation of the file transferinterface used to transfer files to agents running RMA over a secure, authenticatedconnection on port 10190. The server portion of the protocol, running on both theMaster and General agent, always binds using a socket created from aRMASocketFactory instance. The "SSL" alias is supplied so that an SSL socket isalways returned, regardless of how the MA connects to GAs or how the MA'sJMXConnectorServer is bound. Connections are authenticated based on the samemethod that authenticates the JMX Connections between the systems.

Further details about making both an authenticated remote JMX Connection to anRMA Agent and a file transfer connection to an RMA agent is described in “Usingthe FileTransferConnection interface” on page 214.

Figure 112. File transfer interface


FileTransferExceptionException class for file transfer. Thrown by each implementation when anerror occurs. An included error code field is set by the throwing component.

FileTransferManagerThis singleton creates and manages all file transfer connections. Whenevera file transfer needs to be performed by the FileTransferMBean or any othercode in the JVM, the connect() method is called on this object, returning aninstance of FileTransferConnection. The FileTransferManager keeps areference to all connections made, and periodically cleans up all staleconnections. This class also manages the supported file transferimplementations on each device. In addition to the default implementations,additional implementations of the FileTransferConnection interface can beregistered with the manager and used. During startup, the managerattempts to load via reflection the registered class for each implementation.This configuration for all file transfer implementations is stored in theagent's MgmtAgentConfiguration.

FileTransferMBeanThis mean also provides a management interface for theFileTransferManager, where the set of file transfer implementations can bemanaged. Implementation classnames can be added or removed, and thelist of supported implementations is exposed as an attribute. TheFileTransferMBean is included as of the default set of RMA MBeans, and isinstantiated on both the General and Master Agents.

Managing file transfer implementationsThe FileTransferManager maintains a registry of active file transferimplementations. Each implementation is identified by a name (FTP), which ismapped to an implementation class(com.ibm.retail.si.mgmt.xfer.ftp.FTPConnection). You can use this mapping tobe add and remove different implementations, as well as to substitute differentimplementations of the same protocol. Most importantly, you inform otherapplications of which mechanisms are supported and active. An attempt is made toload each implementation class name during startup (by way of Class.forName()).Each implementation class that cannot be loaded is considered inactive and will berejected when an attempt is made to use it. The registered and activeimplementations are exposed as attributes in the FileTransferMBean:

Table 24. Managing file transfer implementations

Attribute name Description

registeredImplementations Names of all registered implementations (suchas FTP, FTPS, STREAM)

activeImplementations Names of all registered implementations thatwere successfully loaded during startup (such asFTP, FTPS assuming STREAM could not beloaded)

The following methods are used for managing implementations:

Table 25. Methods used for managing implementations

Method name Description

addImplementation(Name,ClassName) Adds an implementation (such as FTP)com.ibm.retail.si.mgmt.xfer.ftp.FTPConnection


Table 25. Methods used for managing implementations (continued)

Method name Description

removeImplementation(Name) Removes an implementation (such as FTP)

getImplementationClass(Name) Returns the class name of the implementationname supplied (such as FTP) returnscom.ibm.retail.si.mgmt.xfer.ftp.FTPConnection

StorageEach implementation and its class are stored as properties in theMgmtAgentConfiguration. Each implementation is assigned a number, prefixed witha common name, and its additional properties following the number:com.ibm.retail.si.mgmt.xfer.impl.1.name=FTPcom.ibm.retail.si.mgmt.xfer.impl.1.class=com.ibm.retail.

si.mgmt.xfer.ftp.FTPConnectioncom.ibm.retail.si.mgmt.xfer.impl.2.name=FTPScom.ibm.retail.si.mgmt.xfer.impl.2.class=com.ibm.retail.

si.mgmt.xfer.ftps.FTPSConnection

Monitor policyJMX enables the construction and control of distributed monitors, defined inpackage javax.management.monitor, each of which watches a given attribute on anMBean at a specified interval. When the value meets a defined condition, themonitor issues a MonitorNotification to the managing infrastructure. At the MasterAgent, monitor notifications are wrapped in a RtlMonitorNotification andre-emitted. JMX includes four monitor types:

v CounterMonitor: monitors numeric attribute values that only increase

v GaugeMonitor: monitors numeric attributes based on high and low thresholds

v StringMonitor: matches string attribute values

v BooleanMonitor: matches boolean attribute values

Each has its own capabilities and uses.

Setting up these monitors is an inherent of JMX, but After they are created, they arenot persisted. They must be recreated each time the General Agent (MBeanServer)is restarted. The mechanism provided by the IBM Remote Management Agent forautomatically creating JMX monitors upon General Agent startup is through monitorpolicies, managed by the MonitorManagerMBean on the Master Agent. Its job is tocreate MonitorMBeans on General Agents based on registered policies. Informationcontained within the policy includes:

v Information on which MBeans to monitor

v Which attribute on that MBean to monitor

v Information specific to the type of MonitorMBean being applied (such as thestringToCompare attribute of a StringMonitor)

v How the policy should be applied

Policies can be applied to a single agent, all agents running on a single device, orall agents running on all devices of a specific device type.

The management of monitor policies can be performed programmatically or fromthe Resource Monitors task within IBM Director.


RMA Software DistributionThe creation of a software package occurs within the IBM Director Console, usingthe RMA Software Distribution task to create an installation package. This wizardguides you through the creation process, having you choose the files for thepackage and enter the following information:

v Target platforms for the package

v Target system state

v Target directory for each platform

v Commands to execute for each platform

When the package wizard creates the package, it creates a single JAR file thathouses all of the package files, policy XML information, and deployment information.The structure of the files contained in this file conforms to that required by theRMASWPackageDistributorMBean. When the package is deployed to a set of devicesby IBM Director, this file will be sent to the Master Agent in each target device'sstore and processed by the RMASWPackageDistributorMBean. This MBean sits on topof the RMA Software Policy Manager and automates the creation of device softwarepolicies within a store. The following diagram shows RMA software distribution, endto end:


The following sections explain each portion of the RMA Software Distributioninfrastructure. The first section, “RMA Package Distributor MBean” on page 174,explains the format of RMA package JAR files and how to deploy them byinterfacing with the RMASWPackageDistributorMBean. The section that follows,“Software Distribution Policy” on page 178, summarizes how the RMA Master Agent

Figure 113. Software distribution overview


Policy Manager invokes policies onto clients and explains in detail the format of thepolicy XML file, with the goal of being able to create policy XML files for newlycreated package JAR files.

RMA Package Distributor MBeanEven though this package file format is used by the Retail Extensions for IBMDirector to deploy software packages to devices, it also can be used by othermanagement applications to deploy software to stores. TheRMASWPackageDistributorMBean automates the creation of software policies byunpacking and processing package JAR files the comply with a specific set ofconventions. Even though this package file format is used by the Retail Extensionsfor IBM Director to deploy software packages to devices, it also can be used byother management applications to deploy software to stores.

This section explains the conventions used by the RMASWPackageDistributorMBeanand how it can be used to easily deploy a software package to multiple clients. Thefollowing diagram presents an overview of the RMASWPackageDistributorMBean.

Figure 114. RMA Package Distribution overview


Package JAR file formatThe JAR file processed by the RMA Package Distributor MBean contains all of thefiles and information required to deploy a package to a set of devices in a store. Itmust follow these guidelines:

v There must be a file in the root called policy.xml.

v There must be a file in the root called deployment.properties.

v All other files are package files in the directory structure on the target directoryon each client.

The policy.xml file is the software policy XML file that is sent to all clients. Thereshould be sections for each target platform. If a section is missing for a platform,the policy fails on the client when it is run.

The deployment.properties file contains deployment information that is used increating device software policies on each Master Agent. The following table listseach property that must be in this file.

Table 26. Required properties

Property Value

package_destinations A comma separated list of<Platform>=<Target Dir> pairs, enclosed incurly braces {}. Backslashes should bereplaced with forward slashes. Example:{Windows=C:/temp,Linux=/tmp/pkg}

package_target_state Name of the system state each client shouldchange to upon running the policy. Example:SW_MAINT. For more information, refer toChapter 16, “Programming examples,” onpage 199.

Table 27. Valid platform names

Valid platform names (From com.ibm.retail.si.mgmt.swdist.SWDClientConst):

Windows Windows platforms

Linux Linux platforms

4690 IBM 4690OS

General General purpose, applies to any platform

Table 28. Valid system states

Valid system stats (From com.ibm.retail.si.mgmt.swdist.SystemStateManager):

NOOP (Does nothing) SW_MAINT DATA_MAINT

OS_UPDATE DRIVER_MAINT DIAGS

Getting package files to the Master AgentYou can use any method to transfer the package file to each Master Agent system.All that matters when staging the package using the RMA Package DistributorMBean is that the full path to the file, as it exists on the Master Agent, is known andcan be supplied when requesting to stage the package. Using any of the filetransfer implementations is a way for transferring package JAR files to the Master


Agent. Information on using the RMA file transfer interface is described inChapter 16, “Programming examples,” on page 199.

Package stagingWhen a package file has been created and exists on the Master Agent system, thepackage can be staged and deployed to all target devices using theRMASWPackageDistributorMBean. Using the MBean,(com.ibm.retail.si.mgmt.swdist.pkgdist.RMAPackageDistributorMBean), to deploya package process involves two steps:

1. Staging the package, which involves preparing the package files and creatingRMA Software policies for each target device

2. Activating the RMA Software policies created for each target device

To stage a package, call the unpackAndStagePackage() method. This methodrequires the following information be supplied as parameters:

v A unique String identifier for the package distribution (referred to as a job ID)

v The full path to the package JAR file, as it exists locally on the Master Agent

v A String array of device IDs, each being a destination device for the package

v An array of integer deviceTypes (as obtained from MgmtDeviceInfo), eachcorresponding to the device type of each device in the array of device IDs

Using this information, this method submits a request for the package to be stagedasynchronously, and it returns immediately. The staging is performedasynchronously because of the time required to stage a package. If the call weresynchronous and were being made over a remote JMX Connection, the socketmaking the call could time out with a large package.

The staging process follows these steps:

1. The JAR file is first opened and a check is made to see if the files policy.xmland deployment.properties exist. If one of them does not, then the staging fails.

2. All package files are extracted to a temporary directory (java.io.tmpdir).

3. The deployment.properties file is read.

4. A SWPolicy is created and registered for each device.

5. The extracted files are transferred via FTP to the server using the configuredFTP information. (For RMA V2 Agents only)

6. Each device's SWPolicy is activated.

The description of each device policy conforms to the following pattern:RMAPKG_<JobID>_<DeviceID>. This naming convention distinguishes policiescreated by this MBean from others not automatically created, and provides amethod for obtaining information about the policy once activated (such as statusnotifications). If applicable, a directory is created on the FTP server for the packagefiles that make up the job being staged. The path of this directory is<FTPRoot>/<JobID>.

If any error occurs at any time during the staging process (expected orunexpected), the extracted JAR file tree and the FTP server are cleaned up,assuming that a connection can be made at that time.

As each step in the staging process completes, aSWPkgDistStagingProgressNotification is sent. Each notification contains fields forthe job ID and message data (a resource bundle key and substitution parameters)to describe the step that just completed.


Package staging requests are processed serially from a queue. As each isprocessed, a status object (PackageStatusXML) is kept that contains the stagingstatus for all devices. The PackageStatusXML contains a DevicePackageStatusXMLobject for each staged device. Each of these objects contains:

v Device ID

v Policy ID of the policy created (Will be -1 for errors)

v Error message key (Defined in RMASWPackageDistributorConstants)

v A list of error message parameters

For each error message key in RMASWPackageDistributorConstants, there will be acorresponding resource bundle key incom.ibm.retail.si.mgmt.itd.server.swd.RetailSWDResources to use for displayinga message in the IBM Director Console. The error message parameters are to besupplied as parameters to the MessageFormat class.

When package staging has completed, the PackageStatusXML object contains aDevicePackageStatusXML object for each staged device. This information istransformed into an XML String, which is supplied along with the job ID to aSWPkgDistStagingStatusNotification to be sent to all listening managementapplications. The XML message is the Notification's user data. The followingexample is a status XML String:<StagedPackage>

<StagedDevice deviceId="dev1" policyId="1234"></StagedDevice><StagedDevice deviceId="dev2" policyId="-1">

<ErrMsg msgKey="devPolicyRegErr"><ErrMsgData>Illegal Value: dev2</ErrMsgData>

</ErrMsg></StagedDevice>

</StagedPackage>

The XML String supplied in the status notification should be parsed using thePackageStatusXMLParser class. The following code sample is an example of itsusage:// Parse XML replytry {

StringReader reader = new StringReader(xmlReply);PackageStatusXMLParser parser = new PackageStatusXMLParser();PackageStatusXML status=(PackageStatusXML) parser.parseFromXMLSrc(reader);DevicePackageStatusXML[] devStatusXmls=status.getAllDeviceStatus();

} catch (SAXException e3) {// Handle} catch (IOException e3) {// Handle}

It is important that the caller has notification listeners in place, whether the listenersare added to the MgmtNotificationControlMBean, NotificationProcessor, or theRMAPackageDistributorMBean directly. Otherwise, the response from the packagestaging will not be received, and the status from the deployment will never beobtained.

When each device policy has been activated, status information from clients isrelayed in the same way for all RMA Software Policies, usingMgmtSWPDeviceStateNotifications. Thus, just as it is important to be registered forevents prior to staging a package, it is important to be registered for policy statusevents prior to policy activation.


Software Distribution PolicyThe Remote Management Agent infrastructure defines a mechanism for performingsoftware distributions to devices in the store. It is comprised of two components,one component on the General Agent that is signaled by the component on theMaster Agent to apply a policy to the General Agent device. When it applies thepolicy, the General Agent component performs the steps contained in an XML file.Like the MonitorManager, the Master Agent component interacts with these GeneralAgent MBeans based on defined distribution policies resident at and controlled bythe Master Agent.

The functionality provided by the Remote Management Agent software policyframework is a simple triggered pull of defined software policies to devices within astore network. A software policy is defined as an entity that provides software(packages, updates, patches, and so forth) on client devices. Among the informationit contains is when the policy should be applied, the devices to which it should beapplied, and the location of the policy XML file.

The policy XML file contains information about resource files that must be obtainedto support the software policy, as well as the commands for one or more deviceplatforms. A client retrieves this pre-assembled XML file, along with the otherresource files that are identified for distribution. Because the client knows theplatform on which it is running, it can process information specific to its platformfrom the policy XML file and run the software policy. The following is a simpleexample policy XML file:


The software policy XML file Installation portion simply creates a new directoryon a Linux or Windows client, reboots the device through a generic rebootmechanism, and subsequently creates another directory after rebooting. In thisexample, each executable portion of the software policy XML file looks similar forboth platforms, but in practice each device requires instructions with differentsyntax, and possibly a different process to achieve the end result. More detail onthe construction of software policy XML files is provided in “Software Policy XML filestructure” on page 180. In this example, only the Windows based clients retrieveresource files.

The process of applying a software policy to the devices in the store network is tofirst create such a software policy. The software policy XML file must be createdseparately and made available to the Remote Management Agent software policyframework. The software policy entry must include the name of the software policyXML file and file transfer information. This information varies based on the filetransfer implementation used. When the software policy is activated and is ready torun, it then becomes the job of the SWPolicyMasterMBean to signal all client devicesimpacted by the software policy either immediately or when these devices comeonline. The MgmtSWPolicyClientMBean present on a device impacted by a softwarepolicy receives the notifying signal from the master, pulls down the appropriate

<SoftwarePolicy:SoftwarePolicy xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.pc.ibm.com/ibm/si/mgmt /com/ibm/retail/si/mgmt/swdist/SWPolicyXMLSchema.xsd" xmlns:SoftwarePolicy="http://www.pc.ibm.com/ibm/si/mgmt">

<SoftwarePolicy:SWPolicyDescriptor policyID="007"><SoftwarePolicy:Description>TEST - Test Policy RMA</SoftwarePolicy:Description>

</SoftwarePolicy:SWPolicyDescriptor>



<SoftwarePolicy:SWPolicyTarget targetOS="Linux" >

<SoftwarePolicy:SWPolicyResourceFiles ><SoftwarePolicy:Component filename="multisuite.jar"/>

</SoftwarePolicy:SWPolicyResourceFiles>

<SoftwarePolicy:Installation><SoftwarePolicy:Exec executable="mkdir /PRE_REBOOT" expectedRC="0"/><SoftwarePolicy:Reboot/><SoftwarePolicy:Exec executable="mkdir /POST_REBOOT" expectedRC="0"/>

</SoftwarePolicy:Installation>

</SoftwarePolicy:SWPolicyTarget>

<SoftwarePolicy:SWPolicyTarget targetOS="Windows" >

<SoftwarePolicy:SWPolicyResourceFiles ><SoftwarePolicy:Component filename="instructions.txt"/>


<SoftwarePolicy:Installation><SoftwarePolicy:Exec executable="cmd.exe" expectedRC="0">

<SoftwarePolicy:ExecArg value="/C"/><SoftwarePolicy:ExecArg value="mkdir c:\PRE_REBOOT"/>

</SoftwarePolicy:Exec><SoftwarePolicy:Reboot/><SoftwarePolicy:Exec executable="cmd.exe" expectedRC="0">

<SoftwarePolicy:ExecArg value="/C"/><SoftwarePolicy:ExecArg value="mkdir c:\POST_REBOOT"/>

</SoftwarePolicy:Exec></SoftwarePolicy:Installation>

software policy XML file, and invokes the software policy based on instructions forits platform. As a policy is being activated, it emitsMgmtSWPDeviceStateNotifications to relay status information to the Master Agent.

Additional functionality (for example, the verification of package dependencies) isoutside the scope of software policies and is left up to the users of the softwarepolicy management framework or the installation executable files. Figure 115illustrates the software policy distribution process at a high level.

Software Policy XML file structureThe creation of a software policy is accomplished by interacting with the softwaredistribution MBeans on the Master Agent, and by creating a software policy XML filewith the instructions a client must use to apply the policy. Both of these actions areautomated by the RMA Software Distribution task in the IBM Director Console. A

Figure 115. Software policy distribution


guide for the values that are valid in the creation of such an XML file can bedetermined from the XML schema for software policy XML files.

Outer tags and attributes: The outer tags and attributes that define a softwarepolicy XML file are:<SoftwarePolicy:SoftwarePolicy

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xsi:schemaLocation="http://www.pc.ibm.com/ibm/si/mgmt/com/ibm/retail/si/mgmt/swdist/SWPolicyXMLSchema.xsd"xmlns:SoftwarePolicy="http://www.pc.ibm.com/ibm/si/mgmt">

..{software policy content}..

</SoftwarePolicy:SoftwarePolicy>

The namespace is defined as SoftwarePolicy by the xmlns:SoftwarePolicyattribute. The use of namespace becomes clear as the rest of the software policyXML file is outlined in this section. The expected location of the XML schema that isused to validate the software policy XML file is given in the xsi:schemaLocationattribute. Copy this text exactly to begin creation of a software policy XML file. Apredominant number of XML parse errors are associated with an inappropriatelydeclared root tag.

Note: The namespace must be included before all element tags used within asoftware policy XML file, but it is not required before the attributes of anyparticular tag. The discussion in this section includes the namespace in alltags where it is necessary.

Software policy content: The elements and attributes of the software policycontent provide a general description of the software policy, outline the resourcefiles needed for installation, and describe what types of actions are to be taken bythe software policy for each platform.

Each software policy must contain a descriptor. This is accomplished by includingthe following element tags within the outer software policy tags:<SoftwarePolicy:SWPolicyDescriptor>

<SoftwarePolicy:Description> Base Lab Testing Policy for RMAPackage</SoftwarePolicy:Description>

</SoftwarePolicy:SWPolicyDescriptor>

The first element within the policy, enclosed inside theSoftwarePolicy:SWPolicyDescriptor tag, contains a text description of the policy.

Each platform affected by the policy is represented by the inclusion of aSWPolicyTarget tag as follows:<SoftwarePolicy:SWPolicyTarget targetOS="Windows">

..{software policy target device content}..

</SoftwarePolicy:SWPolicyTarget>

The SoftwarePolicy:SWPolicyTarget tag must follow the descriptor tag. ThetargetOS attribute tag specifies the platform of the target device. A value of Windowsis supported by Windows 2003, Windows XP, and Windows Vista Business devices.A value of Linux is supported by all Linux devices. General is a value used forgeneral purpose, and is not targeted for a specific platform. TheSoftwarePolicy:SWPolicyTarget tag is required.


Software policy content can be made very general or very specific. For example, asoftware policy that would apply a similar action to a large number of differentplatforms would have several target elements each specifying how the action wouldbe accomplished for each platform.

Note: Only a single occurrence of a SWPolicyTarget element should be enteredinto the software policy XML file for each platform.

Software policy target device content: The target device tags contain two typesof elements: the resource files to be transferred and a set of commands to beinvoked.

The element tags that declare resource files that will be used with a target devicesoftware policy action are specified as follows:<SoftwarePolicy:SWPolicyResourceFiles>

<SoftwarePolicy:Component filename="resfile1.txt" size="11"><SoftwarePolicy:Component filename="resfile2.txt" size="11">


The SoftwarePolicy:SWPolicyResourceFiles tag declares the resource files to bedownloaded when running a policy. Only one of these tags is required per devicetarget. This tag is optional if resource files are not required to invoke the softwarepolicy on that target. The preceding example declares resource files resfile1.txt, andresfile2.txt.

When present, the SoftwarePolicy:SWPolicyResourceFiles tag can contain zero ormore SoftwarePolicy:Component elements representing resource files that are to bedownloaded. This tag has attributes that declare the filename and file size in bytes.The tags are described in Table 29.

Table 29. SoftwarePolicy:Component tag attributes

Attribute Description Values Dependence

filename The name of the file. Anyacceptable string filename.

Any string value Required

size The size of the file in bytes. Thetag value is not used, but a valuemust be present. You can enter 0.

Any integer value Optional

The SoftwarePolicy:Installation tag is used to declare elements within thedevice target element representing the installation steps of a software policy. Anexample of this element is as follows:<SoftwarePolicy:Installation>

<SoftwarePolicy:Exec executable="echo Beginning Policy Execution"expectedRC="0">

<SoftwarePolicy:Exec executable "mkdir /TEST" expectedRC="0"/></SoftwarePolicy:Exec><SoftwarePolicy:Exec executable "mkdir /TEST1" expectedRC="0"/>

<SoftwarePolicy:Exec executable="echo Completed Policy Execution"expectedRC="0">

</SoftwarePolicy:Installation>

The SoftwarePolicy:Installation tag can contain several other element tags. Anindividual instruction in a software policy is declared with the SoftwarePolicy:Exectag. This tag can contain up to four attributes as defined in Table 30 on page 183.


Table 30. SoftwarePolicy:Exec tag attributes

Attribute Description Values Dependence

executable The text for an instruction step that runs onthe device target operating system. Anyexecutable instruction is acceptable. Spacesare allowed. Quotes can be included in theinstruction provided to preserve spaces.

A string value - Anyexecutable instruction isacceptable. Spaces areallowed. Quotes can beincluded in the instructionprovided to preservespaces. Use XML "&quot"or "&#34" within theattribute quotation markdelimiters for the attributevalue. A quoted stringmight not work on alloperating systems.

Required

expectedRC The expected text value that is returned in theerror stream from performing the instructionstep. Spaces are allowed.

Any string value Required

rcFile This attribute is used to specify a file in whichthe return code for an executable instructionis to be returned. This attribute is used if aninstruction implements a reboot or restarts theRMA service. The software policy developermust insure that the file is created andpopulated with the return code for properexecution of the software policy. There can beno spaces in the string unless it is quoted(use XML """ or """) within theattribute quotation mark.

Any string value Not required

failureLog The path to a log file that is read after thecommand is invoked. Each line from the file isappended as a standard out message.

Any string value Not required

When creating software packages, it is common to want to invoke scripts, .bat files,and operating system commands. Most of the time these commands need to beinvoked using the client operating system's shell interpreter in order to be invokedcorrectly. The following lists the syntax for invoking shell command or scripts onvarious platforms:

v Windows: cmd.exe /C <program or command>

v Linux: /<path>/<program or command>

v 4690: command.286 -C <program or command>

Note: Software distribution commands on 4690 are invoked using the 4690Remote Command Processor (RCP). Thus, the syntax of the commandsin the policy must be the same as when the commands are invoked usingRCP.

On Linux, a properly formatted, executable shell script can be entered as a validcommand.

Important: Always test package commands before deploying.

The arguments for an instruction represented by the SoftwarePolicy:Exec tag canbe declared using nested argument element tags of the form,SoftwarePolicy:ExecArg.


Note: The argument element tag is not mandatory (for example, an instruction thathas no arguments or when the entire instruction and its arguments are withinthe executable attribute of the Exec tag).

SoftwarePolicy:ExecArg tags have a single attribute identified by the attribute tag,value. This tag can be any string that represents an argument to an instruction. Ifthere are spaces within the argument, then an XML """ special character mustbe included on both sides of the text that is within the attribute quotation delimiters(see the example above).

Note: Not all operating systems parse quoted shell input in this manner, so thesoftware policy developer must be aware of the operating system capabilitiesand limitations when developing the software policy.

A generic system reboot tag, SoftwarePolicy:Reboot, is included for convenience.When this tag is encountered, the target device is restarted. If a software policydeveloper desires specific behavior during a reboot, it is possible to use theSoftwarePolicy:Exec tag to specify an actual reboot command for the target deviceoperating system with appropriate arguments.

Creation of the software policy XML file provides a client payload that directs theclient in the action of the software policy. The target device instructions rely on thedevice operating system to support shell command invocation with appropriateprivileges to accomplish the operations requested by the software policy. Theprocess of selecting the instructions (or developing new ones) that include asoftware policy is beyond the scope of this design.

Policy XML variablesIn order to make policy XML files more flexible and general-purpose, the policy XMLfile supports variables that will have concrete values substituted when supplied. Inthe policy XML file, the variables are specified using the format:${variable name}

To substitute an environment variable value, use:${env.VAR_NAME}

If there is no value for a variable, no value is substituted, and the policy willprobably fail. The following table shows defined variables:

Table 31. Policy XML variables

Variable name Value supplied

client.target.path The destination directory on the client for policy files, supplied withthe policy.

rma.data.dir The path to the RMA Configuration Directory (%SI_HOME%\user\RMA)

Diagnostic Data CaptureRMA supports diagnostic data capture through the use of the DataCaptureMBeaninterface. All implementations of this interface gather component information andcollect it into a single file. These components are brought together at the store levelwith Data Capture policy. Capture policy facilitates the transfer of capture data to acentral location and the optional invocation of captures on other components.


DataCaptureMBeanThe DataCaptureMBean interface is implemented by all MBeans that can collectdiagnostic data. Captures can be triggered manually by the MBean interface, orautomatically when there is a system detected error. How and where errors aredetected is up to the implementer. Errors could be detected internally by theDataCaptureMBean implementation or detected in another MBean. If detected inanother MBean, possible methods of initiating the capture include Notificationsreceived by the DataCaptureMBean, callbacks to registered event listeners, or adirect call to the DataCaptureMBean.

By registering an implementation of this MBean with the RMA General Agent, theMBean can participate in the store-wide data capture facilities provided by RMA.

The RMA API provides a default implementation of the DataCaptureMBean interface,DataCaptureMBeanSupport. This abstract class handles additional functionality suchas request queueing and running captures in a separate Thread. It also handles thegeneration of unique capture identifiers. It is recommended that this class beextended instead of implementing the DataCaptureMBean interface directly.

Capturing DataA capture is performed by calling the capture() method on the DataCaptureMBean. Ittakes as arguments a constant indicating the capture type and a String array ofimplementation specific parameters. Each implementation determines the formatand purpose of these parameters. An in-progress capture can be aborted by callingthe abortCapture() method.

The capture type is a constant that indicates whether the capture is being manuallytriggered (SOLICITED_TYPE) or performed as the result of a system detected error(UNSOLICITED_TYPE). This capture type is used by the Master Agent to triggerother policy based actions in response to either type of capture.

The return value from the capture() method is a capture ID String. This unique IDis used to refer to the capture in other query and control methods on the MBean.

When a capture is performed, the implementing MBean must do two things:

1. Capture any applicable data and store that data in one or more files (or anyother form) on the local file system.

2. Emit a DataCaptureNotification with the appropriate information about thecapture. The Notification should contain (in addition to that information alreadydefined by RMA RtlNotifications):

v The unique capture ID that is used by management applications in referringto the capture. It is returned from the call to the capture() method.

v The capture type, as described above

v Whether the capture was successful (SUCCESS or FAILED)

v The captured files information (fully qualified paths to capture files on theagent device). Files could be supplied for successful or unsuccessfulcaptures.

v If an error occurred during the capture, an error message indicating thereason for the failure.

The DataCaptureNotification instance created will have the following values forthe fields defined by javax.management.Notification:


Table 32. javax.management.Notification fields

Field Value

Message A String of the form: "Capture completed, Id: <ID> + Result: <RESULT>"

UserData A String[] of files from the capture (size 0 for none, not null)

Source The ObjectName of the DataCaptureMBean instance, which might be thesame MBean that emits the DataCaptureNotification

Note: It is important to note that captures can take place over extended periods oftime. Thus it is important that calls to the capture() method should not blockfor a long period of time. Although it is not required, captures takingextended periods of time should be run in a separate Thread. This problemcan be avoided by extending the DataCaptureMBeanSupport class.

Capture ProcessingThe issuing of a DataCaptureNotification is a means for indicating that a capturehas completed to the Master Agent and to any management application.Management applications can listen for DataCaptureNotifications and performapplication specific processing after captures have completed. A typical response tothe completion of a data capture is to transfer the files from the agent computer to acentral location. The RMA General Agent supports data retrieval through theFileTransferMBean. Figure 116 illustrates this process:

See “File Transfer” on page 168 for more details.

Figure 116. Data capture processing


The Master Agent includes a component that defines a policy based mechanism forperforming a set of actions such as file streaming transfer of capture files to acentral location in response to completed captures. The details of this componentare in “DataCapturePolicy class” on page 190.

DataCaptureMBeanSupportThe DataCaptureMBeanSupport class is an abstract class that provides a defaultimplementation of the DataCaptureMBean interface. It handles much of the overheadfor a capture, so that the implementer can focus on the details of capturing data.Among the features that this abstract class provides are:

v Extends NotificationBroadcasterSupport for sending Notifications.

v Maintains the status of captures (Completed versus In Progress)

v Queues capture() method calls

v Invokes capture() method calls in a separate Thread

v Generates unique capture identifiers.

Upon receiving a call to capture(), the DataCaptureMBeanSupport creates a uniqueidentifier for the capture and invokes it in a separate Thread. Subclasses implementthe protected performCapture() method to perform the actual capture. Passed withit is an instance of the interface DataCaptureRequest. This object containsinformation about the capture and its result. The performCapture() method shouldmodify the instance passed in with capture file names and/or error messages beforecompleting.

After the capture completes, the protected captureCompleted() method is called, towhich it passes the DataCaptureRequest instance returned from performCapture().This method handles post capture processing, which by default is to send aDataCaptureNotification based on the information in the DataCaptureRequest.Subclasses can override this method to perform their own post capture processingalong with a call to the super class to send the DataCaptureNotification.

When a call to abortCapture() is made, the Thread for a capture is ended. Afterending capture execution, a call is made to the captureAborted() method. Like thecaptureCompleted() method, this method is provided as a hook for subclasses toperform any processing after the capture has been aborted. The defaultimplementation of this method sends an unsuccessful DataCaptureNotificationwith an error message indicating that the capture was aborted, and with the capturefilenames in the DataCaptureRequest at that time.

Because this class ensures capture method calls are non-blocking, it isrecommended that this class be used when creating a DataCaptureMBeanimplementation.

Figure 117 on page 188 illustrates this process:

v Steps 1 and 2: A system error is detected and a capture performed, writingdiagnostic data to files on disk. The system error could be an application error, orany error that can be reported to RMA.

v Step 3: The DataCaptureNotification emitted by the General Agent flows to theMaster Agent.

v Step 4: In response to the DataCaptureNotification, the Master Agent makes afile transfer connection to the General Agent, to transfer the captured files. Afterbeing transferred, the captured files are compressed into a capture bundle, whichis stored on the Master Agent.


v Step 5: The capture bundle is retrieved from the Master Agent by a ManagementApplication that is running at the enterprise.

Data Capture PolicyThe DataCaptureMBean interface serves as the interface for data capture in the RMAinfrastructure. Any management application can communicate directly with aninstance of this MBean and perform a diagnostic data capture. However, in practice,most captures will not take place by themselves, but in a group. It might bedesirable for a completed capture on one component to initiate captures on one ormore other components on the same device.

Additionally, management applications are required to listen for notifications ofcompleted captures and transfer the diagnostic data from all devices. Instead ofmanagement applications having to perform post-capture processing and managechains of capture dependencies, the RMA Master agent provides a centralized,policy based component for performing these tasks called theDataCaptureManagerMBean. The purpose of this component is to:

v Transfer capture files from completed captures to a central location

v Initiate captures on DataCaptureMBean instances, either manually, or automaticallyin response to a completed unsolicited capture

Figure 117. Data capture


A DataCapturePolicy, registered with the DataCaptureManagerMBean running on theMaster Agent, defines the list of capture MBeans and details needed for performingthe captures and transferring files.

RMADataCaptureMBeanRMA includes an implementation of the DataCaptureMBean interface, theRMADataCaptureMBean, which captures useful problem determination data from anRMA agent. RMA memory logging triggers the RMADataCaptureMBean to capture datawhen a problem occurs. The RMADataCaptureMBean captures the following data wheninvoked:

v Logs

– rma.stderr

– rma.stdout

– RMA CIM tracing (rmacimtrc.log)

– The regular logging file(s) specified by the base FileHandler pattern in thelogging configuration file (default is simgmt.*)

– The memory logging file(s) specified by the RMALogHandler pattern in thelogging configuration file (default is simgmt_m.*)

v Data

– Triggers a Java core dump and then captures the javacore* file.

– Captures the latest heapdump* file, provided it was written recently (in the last10 minutes).

DataCaptureManagerMBeanAt the center of the capture infrastructure is the DataCaptureManagerMBean, whichmanages data capture policies and listens for DataCaptureNotifications emitted byDataCaptureMBeans running in the store (including the Master Agent). The receipt ofthese notifications triggers file transfers of captured data and captures on otherDataCaptureMBeans running on devices in the store. Figure 118 on page 190illustrates this process. In this diagram, there is an capture policy active on theMaster Agent. An unsolicited capture occurs on LaneX, resulting in the Lanesending a Data Capture Notification of type UNSOLICITED (1). When thenotification is received by the Master Agent, the manager will detect that the captureapplies to the active policy, resulting in the transfer of the Lane's capture files (2)and the invocation of a solicited capture on the controller CC (3). Since CC is in thepolicy's capture list, any unsolicited capture by a Lane will result in a solicitedcapture on CC. When the solicited capture completes on CC (by emitting aDataCaptureNotification of type SOLICITED (4)), its files are transferred to theMaster Agent (5) and a capture bundle file will be created containing the capturefiles from both LaneX and CC.


DataCapturePolicy classA DataCapturePolicy object is a container object used by the DataCaptureManagerto store policy configuration information. Instances of this object are registered withthe DataCapturePolicyRegistryMBean, and then activated. Once activated, theDataCaptureManagerMBean will register NotificationListeners with MBeans listed inthe policy to receive DataCaptureNotifications. These notifications will initiate filetransfers on completed captures as well as captures on the otherDataCaptureMBeans defined in the policy.

A DataCapturePolicy object consists of:

v A user supplied description for the policy

v A unique system generated identifier for the policy

v Trigger List: A list of any number of <device,MBean> or device <type,MBean>pairs. The list defines the MBeans and devices whose unsolicited captures willinitiate solicited captures on the MBeans and devices in the capture list.

v Capture List: A list of any number of <device,MBean> or <device,MBean> pairs.The list defines the MBeans and devices that will have solicited captures invokedwhen an unsolicited capture occurs on a device in the trigger list.

v Capture Timeout: This value defines a time window, in minutes, in which allcaptures must be completed. The timeout period starts when the unsolicitednotification is received or the first capture is triggered. After the time windowexpires, the capture sequence will time out and will go inactive. The minimumvalue is 1.

Figure 118. DataCaptureManagerMBean


The configuration for all data capture policies is kept in an XML file,DataCapturePolicies.xml, on the Master Agent, under the directory%SI_HOME%\user\rma\config\capture on Windows and $SI_HOME/user/rma/config/capture on Linux. DataCapturePolicyExample.xml gives an example listing of thisfile.

Capture policy applicationData Capture policies use two lists, a trigger list, and a capture list. Each trigger listcontains pairings of MBean IDs with a device ID or device type. The pairings in thislist are used to determine when captures from arriving DataCaptureNotificationsresult in solicited captures on the MBeans in the capture list. Each policy's capturelist also contains a list of these mappings, which is used to compile a list of agentsto invoke solicited captures. Use the pairings between MBean and device, as theyare used in the trigger and capture lists, to target different agents.

The pairings that make up each list are instances of eitherDeviceCapturePolicyApplication or DeviceTypeCapturePolicyApplication. Eachtakes as parameters the MBean ID and information for that type of application(device ID or device type information). These classes also take an optional set ofcapture parameters passed to the DataCaptureMBean when invoked by way of asolicited capture. The following examples shows an single device application for theGenericLogCaptureMBean, whose parameters, the names of the files to capture wheninvoked, are listed as nested elements:<DeviceCapturePolicyApplication mbeanId="GenericLogCapture" deviceId="CC">

<CaptureParams><CaptureParam>C:\silogs\CC.0<CaptureParam><CaptureParam>C:\silogs\CC.1<CaptureParam><CaptureParam>C:\silogs\CC.2<CaptureParam>

<CaptureParam></DeviceTypeCapturePolicyApplication>

An example of the trigger list/capture list concept comes from the policy depicted inFigure 118 on page 190. The desired behavior of the policy is to initiate a solicitedcapture on a capture MBean "GenericLogCapture running on 4690 controller CC inresponse to an unsolicited capture from a Self Checkout Lane MBeanSCSDataCapture. To create this policy, you would supply a new policy with thefollowing information:

v Trigger List: A PolicyApplicationList with oneDeviceTypeCapturePolicyApplication, pairing the SCSDataCaptureMBean with theSCS-Lane Role.

v Capture List: A PolicyApplicationList with oneDeviceCapturePolicyApplication, pairing "GenericLogCapture" with the deviceID "CC".

Capture bundle directoryCapture file processing is performed by an instance of CaptureFileProcessor. Itsjob is to create a bundle ZIP file from the files that comprise a completed captureinvocation, and to delete those capture files after the bundle has been created. Acompleted capture invocation is one in which all captures have completed(successfully or unsuccessfully) and their files transferred (if any). Capture bundlesare stored in a location given by the CaptureBundleDirectory attribute on theDataCaptureManagerMBean. This value would be used by a management application(RMA Data Capture task in IBM Director) to check for and retrieve completedcaptures. The default path on the Master Agent to where capture bundle files arestored is as follows:

v Windows: C:\Program Files\IBM\StoreIntegrator\user\rma\data\capture\completed


v Linux: /opt/ibm/StoreIntegrator/user/rma/data/capture/completed

v 4690 Enhanced: F:\rma\user\rma\data\capture\completed

Note: Capture bundle files use the following naming convention:filename_Monddyyyy_mmhhss.zip (for example,myserver_MyPolicy_Feb152010_191608.zip). The mmhhss (hours, minutes,and seconds) portion of the filename is in Greenwich Mean Time (GMT).

Policy invocationWhen a policy is triggered on an agent (either manually or by the arrival of anunsolicted capture event), a CapturePolicyInvocationPlan is created to determinewhich captures to invoke. A CapturePolicyInvocationPlan object takes a policy'scapture list, a policy's trigger list (optional), and a list of all online agents andreturns a list of <MBean, Agent> pairs that represent captures to invoke. The pairsrepresent an aggregation because it is possible that an agent could be affected bymore than one policy application (device type applications in particular).

Note: If an agent is not online at the time the policy is invoked, then it will not getinvoked later under that invocation.

The applicable MBeans defined in the policy that are online at that time will havecaptures initiated (by way of the DataCaptureMBean interface's capture(String,long) method). The String is the type of capture (solicited or unsolicited), and thelong is the capture timeout. While these captures are taking place, the policy will bein a blocked state, where the MBeans defined in the policy will not be triggeredagain on that agent until the policy completes successfully or unsuccessfully. This isto keep all captures for the policy into a single contained unit, and to prevent abacklog of captures.

Policies will always act independently of one another. In other words, if an MBean isdefined in another active policy, it will be called to capture even though it might bein the middle of a capture from another policy. The DataCaptureMBean will provide abase implementation, DataCaptureMBeanSupport, that handles the execution ofcaptures in a separate Thread.

If an agent shuts down during the middle of a capture or file transfer(MBeanServerNotification.UNREGISTRATION notifications received by theDataCaptureManager for an MBean), a synchronization process will occur duringstartup that will resume file transfers.

Post Capture File Transfer and ProcessingThe arrival of a DataCaptureNotification triggers a two stage process oftransferring the capture files from the clients to the Master Agent and bundling all ofthe capture files and logs into a single .ZIP file. The bundles will be available formanagement applications to read and transfer to an enterprise location.

Capture File Transfer: When a DataCaptureNotification is received by theDataCaptureManager (solicited or unsolicited), a request is submitted to transfer thecapture files to the Master Agent. The DataCaptureNotification contains a list ofthe capture file names (fully qualified) as they exist on the client. The format of thefile path in the notification does not matter, since they are passed back to the clientduring the file transfer.

The transfer will be performed using each device's FileTransferMBean using theRMA File Streaming implementation. File streaming, added in V2R2, is the only wayto easily move client files to a specific location on the Master Agent. As a result,


FTP and FTPS will no longer be supported as valid transfer implementations fordata capture. The support of V2 agents is discussed later.

The client's capture files are transferred to the location %SI_HOME%/user/rma/data/capture/xfer/. When files are transferred to the MA, subdirectories get created underthe transfer root for the capture files. The directory structure that is created for thefiles is of the form:DIRECTOR_SERVER_HOSTNAME_POLICY_NAME/FORMATTED_INVOCATION_START/AGENT_ID/MBEAN_ID

An example directory structure from a Director Server named MyServer, with apolicy name of MyPolicy, with an invocation start of March 15, 2010, at 15:30:32,which ran on Lane1.10151 and Lane2.10151, using the RMALogCaptureimplementation would be:

%SI_HOME%/user/rma/data/capture/xfer/MyServer_MyPolicy/Mar152010_153032/Lane1.10151/RMALogCapture%SI_HOME%/user/rma/data/capture/xfer/MyServer_MyPolicy/Mar152010_153032/Lane2.10151/RMALogCapture

The capture bundle ZIP file contains the transferred capture files as well as an XMLhistory log (history.xml) located in the root of the bundle ZIP file. This log containsall of the history information for that invocation, and it can be parsed and used by amanagement application. The log is in the same format as that stored on theMaster Agent, except that it is a single capture history and has only one invocation.But because it is in the same format, you can use the DataCaptureHistoryParserclass to parse it.

Retries and Maintaining Capture History InformationIt is quite possible that the transfer of capture files will not succeed on the first tryafter the completion notification has been received. The Master Agent should retryas many times as possible in order to transfer the capture files.

It is also important that the capture history information on the Master Agent bemaintained, since the Master Agent cannot be notified asynchronously of allpossible external actions that would require the information to be updated. Forexample, a capture file on a client could get deleted by some external process oruser. Only by going back to the client and synchronizing will the Master Agent knowand respond. This section describes how both of these functions are handled.

File Transfer Error Handling and Retries: The transfer directory, the location onthe Master Agent where capture files are transferred, is a staging directory, or atemporary storage location. As each capture file is transferred from the client, thecapture history updated to reflect the fact that it has been transferred. Only whenthe bundle zip file has been created successfully with all capture files will thetransfer directory for the invocation be deleted. Until then, the capture files willremain. This means that a transfer error does not fail a capture, it only delays thecompletion of it.

Capture History Cleanup: History cleanup and synchronization is neededbecause it is not guaranteed that all invocations will complete. One possiblescenario is that an agent goes down during the middle of the transfer of capturefiles and never comes back up. Without cleanup, this capture history would remainforever or until the policy was terminated.

To handle history maintenance, a synchronization is performed when each captureMBean is discovered. Synchronization is a two stage process. One is comparingthe current Master Agent information with that of the client, and the other iscomparing the info the client has with that of the Master Agent.


Calling getCaptureFiles(captureId), a method in the Data Capture MBeaninterface, will return the most up to date capture file information for a capture fromthe client. This method will check for the existence of the files on the client machineand will return only those that still exist. The Master Agent will update its history andstatus information based on what is returned, removing file names that no longerexist on the client that have not been transferred.

Additionally, a cleanupHistory() method is run every hour(HISTORY_CLEANUP_FREQUENCY), using the same timer for transfer retries.The method goes through all capture histories, completing captures that are olderthan a threshold value, the persisted attribute HistoryThresholdDays (default is 1day). The history cleanup operation involves only processing on the Master Agentside. It does not involve contacting each client for updated capture statusinformation, which would result in network traffic. Capture status information isobtained from the client only once, when the client is discovered.


Part 4. Programming

Chapter 15. Development environment . . . . . . . . . . . . . . . 197Setting up the development environment . . . . . . . . . . . . . . . 197

Chapter 16. Programming examples . . . . . . . . . . . . . . . . 199Working With Files . . . . . . . . . . . . . . . . . . . . . . . 199Writing and registering your own MBeans . . . . . . . . . . . . . . 199

Exposing a management interface . . . . . . . . . . . . . . . . 199MBean Object Naming . . . . . . . . . . . . . . . . . . . . 200MBean registration . . . . . . . . . . . . . . . . . . . . . . 202

Embedded Agent registration . . . . . . . . . . . . . . . . . 202General Agent service registration . . . . . . . . . . . . . . . 203Creating An Embedded General Agent. . . . . . . . . . . . . . 203Embedded Agent Configuration . . . . . . . . . . . . . . . . 203Embedded Agent Communcation . . . . . . . . . . . . . . . . 204

Distributing the MBean classes . . . . . . . . . . . . . . . . . 204Making a Remote JMX Connection to the Master Agent . . . . . . . . . 204

Accessing MBean instrumentation . . . . . . . . . . . . . . . . 208Accessing General Agent MBeans from the Master Agent. . . . . . . 208Locating Agent MBeans . . . . . . . . . . . . . . . . . . . 209

Retrieving Store Events (Notifications) . . . . . . . . . . . . . . . 210Adding Notification Listeners . . . . . . . . . . . . . . . . . 210Using the Notification Processor . . . . . . . . . . . . . . . . 211

Using the FileTransferConnection interface . . . . . . . . . . . . . . 214Common properties. . . . . . . . . . . . . . . . . . . . . . 215

RMAFileTransferConnection properties . . . . . . . . . . . . . 215FTPConnection properties . . . . . . . . . . . . . . . . . . 215FTPSConnection properties . . . . . . . . . . . . . . . . . . 216

Transfer types. . . . . . . . . . . . . . . . . . . . . . . . 216Transfer progress . . . . . . . . . . . . . . . . . . . . . . 217

Managing monitor policies . . . . . . . . . . . . . . . . . . . . 218MonitorPolicy object . . . . . . . . . . . . . . . . . . . . . 218MonitorPolicyAction object . . . . . . . . . . . . . . . . . . . 218

Managing data capture policies . . . . . . . . . . . . . . . . . . 219Creating, Adding, and Activating a Capture Policy . . . . . . . . . . 219Receiving Capture Completion Notifications . . . . . . . . . . . . . 221Querying Invocation History . . . . . . . . . . . . . . . . . . . 221

CapturePolicyInvocationRecords . . . . . . . . . . . . . . . . 221CaptureAgentRecords . . . . . . . . . . . . . . . . . . . . 221CaptureInstanceRecords . . . . . . . . . . . . . . . . . . . 221

Terminating and Deleting a Data Capture Policy . . . . . . . . . . . 222Managing software distribution policies . . . . . . . . . . . . . . . 222

Registering draft policies . . . . . . . . . . . . . . . . . . . . 223State and progress notifications . . . . . . . . . . . . . . . . . 224Activating a draft policy . . . . . . . . . . . . . . . . . . . . 225Policy invocation history and status . . . . . . . . . . . . . . . . 225Terminating and deleting a Policy. . . . . . . . . . . . . . . . . 226

SystemStateManager . . . . . . . . . . . . . . . . . . . . . . 227SystemStateChangeListener and SystemStateChange Notifications . . . . 227SystemStateHandler . . . . . . . . . . . . . . . . . . . . . 227

Coding best practices . . . . . . . . . . . . . . . . . . . . . . 228Using error logging . . . . . . . . . . . . . . . . . . . . . . 228

Logging levels. . . . . . . . . . . . . . . . . . . . . . . 228Logging APIs . . . . . . . . . . . . . . . . . . . . . . . 229


||

||||||

Controlling error log output . . . . . . . . . . . . . . . . . . . 229Error log entry contents . . . . . . . . . . . . . . . . . . . . 230


Chapter 15. Development environment

One of the advantages of Remote Management Agent's use of Java is the flexibilityof the development environment. Programming tasks can be performed on anysystem that has a text editor and the Java Development Kit (JDK). This sectionexplains how you set up your environment for writing MBeans.

Setting up the development environmentTo create MBeans for the Remote Management Agent, you need the correct level ofthe Java Development Kit (JDK) loaded on your development system. The correctlevel of the JDK required can be downloaded the IBM JDK fromwww.ibm.com/developerworks/java.

For the purposes of building and compiling MBean classes and managementapplications, you can use the IBM Java 6 compiler. When running managementapplications, you can use an IBM Java 6 JRE. When creating extension MBeans tobe registered with the RMA agent, however, you must pay attention to the JREversion of the target platform. All RMA Agents run with the IBM Java 6 JRE onWindows, Linux, or 4690 Enhanced. The RMA Agent on 4690 Classic runs with the1.4.2 IBM JRE.

Since JMX is not included with Java 1.4, a JMX implementation must be added tothe class path when running inside a 1.4 JVM. Additionally, the .class files need tobe compiler option -target 1.4. The supported JMX implementation for 1.4 IBMJRE's is MX4J, which comes in the form of two JAR files, mx4j.jar and mx4j_rmt.jar,included in the 4690 Classic installation of RMA in the M:\rma\lib directory, and alsoincluded with Store Integrator.

The class path should be set as follows:SET CLASSPATH=%RMA_HOME%\rma.jar;

%RMA_HOME%\api4690.jar%RMA_HOME%\simgmt.jar;%RMA_HOME%\siwbem.jar;%RMA_HOME%\commons-logging.jar;%RMA_HOME%\rma-inst.jar;%RMA_HOME%\siutil.jar;%RMA_HOME%\jlog.jar;%RMA_HOME%\ITLMToolkit.jar;%RMA_HOME%\soxs.jar;%RMA_HOME%\sibeep.jar;%SI_HOME%\user\rma\classes;%RMA_CP_EXT%

Note: To extend the class path, you can change the value of the systemenvironment variable %RMA_CP_EXT%.

When starting your application, you also need these additional parameters:-Dorg.apache.commons.logging.Log=org.apache.commons.logging.impl.SimpleLog-Dcom.ibm.retail.si.mgmt.config.dir="%SI_HOME%\user\rma"

Note: On 4690, either of the following values should be supplied for-Dcom.ibm.retail.si.mgmt.config.dir:

v 4690 Classic: M:\rma\user\rma

v 4690 Enhanced: F:\rma\user\rma


http://www.ibm.com/developerworks/java

As a convenience, there are scripts that start Java with the RMA class path:

v Windows: %RMA_HOME%\bin\rmaJava.bat

v Linux: %RMA_HOME%/bin/rmaJava.sh

Each takes as arguments the Java program name and all program arguments. Forexample, to run the fictitious Java program com.test.MyTest with the RMA classpath on Windows, issue the rmaJava.bat com.test.MyTest command.


Chapter 16. Programming examples

This section describes details of programming with IBM Remote ManagementAgent. Typical programming tasks include:

v Writing and registering MBeans

v Receiving store events

v Transferring files

v Managing store-wide policies for JMX Monitors, data capture, and softwaredistribution

Working With FilesWorking with certain file types in Java on 4690 OS V6 and later requires the use ofnon-standard Java APIs ( the File4690 class). As a result, extension MBeansrunning on 4690 OS V6 and later require the use of different file APIs than otherplatforms. To prevent users from having to make the determination of which file APIto use, the RMA API includes a class, RMAFile, that automatically makes thisdetermination.

The RMAFile class does not extend java.io.File, but it does provide the sameinterface. It also provides methods for creating implementation-specific InputStream,OutputStream, and RandomAccessFile objects. The determination as to when to useRMAFile should be made based on the target platforms on which the extensionMBeans will run. If it is known that an extension will not be run on a 4690 OS, thenregular Java APIs can be used when working with files. Otherwise, the RMAFileclass provides a platform neutral option for file access.

Writing and registering your own MBeansEnabling application components to be managed has numerous benefits, especiallyin a store environment with numerous, distributed stores. The ability to expose andmonitor application attributes, manage application configurations, and forwardapplication events to the enterprise can all provide time and cost savings for your ITstaff. This section describes how to instrument application components with MBeansusing JMX. The steps involved in performing this task include:

Exposing a management interfaceDefine the MBean interface and implementation for the managed resource.

MBean object namingDefine a unique and structured name for the MBean within themanagement infrastructure. This enables a remote management applicationto individually search and access each MBean within the store.

MBean registrationRegister the MBean with the JMX MBeanServer. This exposes the MBeanfor external access.

Distributing the MBean classesInstall the Java class files associated with the MBean into the correctplaces within the management infrastructure.

Exposing a management interfaceMaking a resource manageable involves the creation of an MBean for thatresource. The JMX specification defines multiple types of MBeans, in addition to the


standard MBean, including dynamic, model, and open MBeans. Even though eachis implemented differently and some have additional features for added flexibility,they all expose a management interface for a managed resource. The standardMBean is the simplest type of MBean to implement, requiring only that themanaged resource MyClass implements the Java interface MyClassMBean. Thisexample uses a simple standard MBean called SampleMBean, which exposes aread/write String attribute, Attribute1, and a read-only boolean attribute, BoolAttr.An operation called operation1 is also exposed. operation1 takes a single Stringparameter and returns an int. The SampleMBean interface is the MBean interfacethat is implemented by the managed resource Sample.SampleMBean:

public interface SampleMBean {

public String getAttribute1();

public void setAttribute1( String attr1Val );

public boolean isBoolAttr();

public int operation1( String param );}

MBean Object NamingWithin the scope of a JMX managed system, an MBean does not derive its uniqueidentity from the instance itself, as this cannot be viewed across multiple JVMs, butfrom a unique characteristic of an MBean: its ObjectName. An MBean ObjectName isa collection of commas separated by Key=value pairs.

For example:"Domain:name=name,foo=one,bar=two,more=three"

JMX does not provide guidance or rules for the application of these names. That isleft to the MBean provider. In order to provide some organization of MBeans withinthe IBM Remote Management Agent management infrastructure, some rules andconventions should be applied when naming MBeans.

The value in ObjectNames is in deriving contextual usage from them. Specifically, anapplication that consumes these MBeans can benefit from having a knownstructured format with specific content. This is the case for the IBM RemoteManagement Agent, as it provides context and a structured space that eliminatesthe possibility of naming collisions. The ObjectNameFactory class, described below,creates or reformats ObjectNames in order to comply with RMA Object Namingconventions.

The name space specified by this infrastructure is segmented into three parts:

1. System-wide identification

2. Component identification

3. Device content (component/application specific data)

System-wide identificationThese system-wide identification elements are always obtainable from theGeneral/Master Agent, using the single instance of ObjectNameFactoryprovided in the Remote Management API. Using the createObjectNamemethods of this class, it is possible to build a name that is consistent withthe object naming conventions described in this document where theseelements are automatically added.


Remote Management MBean identifierThis identifies an MBean as being related to Remote ManagementMBean identifier. Syntax: SIFMBean=true.

Store ID(RMA V2R4 and earlier) This is retrieved from the Master/GeneralAgent relationship, and is unique to a given store. It is only appliedto proxied MBeans on the Master Agent. It is a configured elementon the Master Agent. Syntax: StoreID=x.

Device IDThis is an automatically generated element of all agents, and isunique to each physical device within the store. This value defaultsto the device's host name and then to an integer representing thedevice's IP address. For 4690 terminals, it is <controller id>.<terminal number>, and for controllers, just <controller id>.Syntax: DeviceID=x.

System IDThis is an automatically generated element of all agents, and isunique to each agent running in the store. The system ID takes theform: <deviceId>.<mgmtPort>, where mgmtPort is the agent'smanagement port. Syntax: SystemId=<deviceId>.<mgmtPort>.

Agent IDThis element is exposed automatically on each embedded agentMBean proxy. It is used to identify all of the MBeans on a particularembedded General Agent. Its value is derived from the embeddedagent ID supplied during the creation of an embedded GeneralAgent.

Component identification

Component nameUnique identification for a functional component (Required). In thecase of the IBM Remote Management Agent components, there isa list of reserved component names. Syntax: SIFComponent=xyz.

Device major versionThe major version of the component being represented (optional).Syntax: DMajorVer=x.

Device minor versionThe minor version of the component being represented (optional).Syntax: DMinorVer=x.

Device content (component/application specific data)

Type Identifier (optional):Value used to denote the type of the MBean. A common type valuecan be useful for grouping multiple instances of the same MBean(each with a different ID value). For example, all Data CaptureMBeans have a SIFType=DataCapture.

Unique identifierUniquely identifies the MBean within the component and type(required). For MBeans where only one instance exists in thesystem, this is the MBean type (such as SessionManager). ForMBean types that can have multiple instances, add a tag to thetype (such as Session.200). Syntax: Id=<Id>.

Chapter 16. Programming examples 201

||||||

There are no requirements for the domain portion of the ObjectName, since it issometimes externally controlled. It is recommended that the default domain of theMBeanServer be used. The SIFMBean Identifier key is used to identify RemoteManagement MBeans.

Putting all of the pieces together, a component builds a base ObjectName by firstconstructing the component specific portion and then acquiring the system-wideinformation from the from the agent's ObjectNameFactory instance. Prior to V2R2,the ObjectNameFactory was a singleton (There is still a singleton, but its use isdeprecated). The MgmtAgent interface now provides an ObjectNameFactory for theagent. The following example illustrates how to create an ObjectName using theObjectNameFactory:

import javax.management.MBeanServer;import javax.management.MalformedObjectNameException;import javax.management.ObjectName;

import com.ibm.retail.si.mgmt.MgmtAgent;import com.ibm.retail.si.mgmt.MgmtAgentFactory;import com.ibm.retail.si.mgmt.ObjectNameFactory;

MgmtAgent generalAgent = MgmtAgentFactory.getGeneralAgent();MBeanServer mbs = generalAgent.getMBeanServer();ObjectNameFactory namer = generalAgent.getObjectNameFactory();

ObjectName newName = new ObjectName( mbs.getDefaultDomain() + ":type=Sample" );try{

newName = namer.createObjectName(newName, "sample1", "AEF", null, null );} catch (MalformedObjectNameException err){...}

The result is an ObjectName that looks similar to the following example:generalagent:SIFMBean=true,StoreID=1,DeviceID=1,SystemId=1.10151,SIFComponent=AEF,type=Sample,id=sample1

MBean registrationRegistration of MBeans depends on whether the General Agent is running as anembedded agent or as the installed service.

Embedded Agent registrationAll MBeans are Java objects until they are exposed through the JMX MBeanServerthrough the registerMBean or createMBean methods. Each MgmtAgent instancecreates and manages an MBeanServer through which MBeans can be added to theIBM Remote Management Agent infrastructure. The following is an example of howto obtain the MBeanServer and register an instance of the SampleMBean :

import javax.management.MBeanServer;import javax.management.ObjectName;

import com.ibm.retail.si.mgmt.MgmtAgent;import com.ibm.retail.si.mgmt.MgmtAgentFactory;import com.ibm.retail.si.mgmt.MgmtException;import com.ibm.retail.si.mgmt.ObjectNameFactory;

MgmtAgent agent = null;MBeanServer mbs = null;synchronized( MgmtAgentFactory.class ) {

try {agent = MgmtAgentFactory.getCurrentMgmtAgent();mbs = agent.getMBeanServer();

ObjectName newName = new ObjectName( mbs.getDefaultDomain() + ":type=Sample" );ObjectNameFactory namer = agent.getObjectNameFactory();newName = namer.createObjectName(newName, "sample1", "AEF", null, null );


||

|

Sample resource = new Sample();mbs.registerMBean( resource, newName );

}catch ( MgmtException me ) { ... }

}

General Agent service registrationTo add MBeans and Notification Listeners to the startup sequence of the installedAgent service. For more information see “Agent startup sequence” on page 50.

Creating An Embedded General AgentMgmtAgentFactory.createEmbeddedGeneralAgent(Properties) is a factory methodintroduced with V2R6 to create embedded agents. The Properties object suppliedas an argument provides all the configuration options, which are described below infurther detail. This factory method replaces the factory method used prior to RMAV2R6, MgmtAgentFactory.getGeneralAgent(). If the getGeneralAgent() method iscalled, an embedded agent running in remote mode will be created and started.The following code sample shows how to use the factory method:

try{

Properties agentProps = new Properties();agentProps.put( MgmtConst.CONFIG_PROP_E_AGENT_ID, agentId );agentProps.put( MgmtConst.CONFIG_PROP_E_AGENT_MODE, MgmtConst.EMBEDDED_AGENT_MODE_LOCAL );

MgmtAgent agent = MgmtAgentFactory.createEmbeddedGeneralAgent( agentProps );MBeanServer mbs = agent.getMBeanServer();//... register MBeans, etc

}catch ( MgmtException me ){

//}

When using RMA V2R6 or later jar files for embedded agents, you will need tomake sure you include soxs.jar and sibeep.jar in their classpath for yourapplications.

Embedded Agent ConfigurationA Properties object supplied for the factory method provides all the configurationoptions needed to create the agent. The property values are in the following form:com.ibm.retail.si.mgmt.generalagent.embedded.agentMode=[local|remote]com.ibm.retail.si.mgmt.generalagent.embedded.agentId=[AGENTID]com.ibm.retail.si.mgmt.generalagent.embedded.port=port

The caller of the factory method determines the mode the agent should run. If noagent mode is supplied, remote mode is the default. Local mode is therecommended mode for embedded agents not running within 4690 Terminals, as itwill prevent multiple agent objects for a single system from being discovered anddisplayed on the IBM Director console. Any Java applications running in a 4690terminal should supply remote mode because the RMA Service agent does not runthere. If the embedded agent runs in local mode, it will never get discoveredbecause there is not a real agent to discover it.

The agent ID parameter uniquely identifies the agent among other embeddedagents on the system, and is used by the RMA service agent to separate theMBeans from different embedded agents. Strings that identify the applicationrunning in the JVM are recommended. The intention is for the agent ID not tochange, and should be compiled into the code that starts the agent. If an agent ID


||||||||

||||||||||||||

|||

|||

|||

||||||||

|||||

parameter is not supplied for local mode embedded agent, a random agent ID willbe generated as deviceId random#. If an agent ID parameter is not supplied for aremote mode embedded agent, the generated device ID is deviceId -“embedded".Otherwise, the remote mode embedded agent will have a device ID of deviceId -agentId.

Embedded Agent CommuncationThe local mode embedded agents and the service agent communicate using theloopback address (127.0.0.1) in order to keep all communications local to the box.Since all communications are local and local only, the sockets will be non-SSL andthe connections are unauthenticated. When the embedded agent is running inremote mode, the connection stills needs to be encrypted and authenticated. As aresult, separate SSL configuration, rma-ea-ssl.properties, is used by remote modeembedded agents. This configuration is based on the StoreIntegrator AEFBundleclass so it can be overridden. The default is to use a properties file and separateSSL keystore, which is included inside simgmt.jar.

Distributing the MBean classesApplications get their MBean classes into the class path of the Master or GeneralAgent by copying JAR files into the \ext directory under the RMA configurationdirectory. During startup, JAR files found in this directory are added to the Agent'sclass path.

On 4690 V6, the JAR files are added to the RMA classpath by adding the paths tothe RMACPEXT user logical filename.

Making a Remote JMX Connection to the Master AgentThis section describes the interaction with specific Master Agent MBeans. Tointeract with the Master Agent MBeanServer in any way, a remoteMBeanServerConnection is required. The JSR-160 specification defines theinterfaces for remote JMX connectivity. The RMA Master Agent supports two remoteJMX implementations: the RMI (Remote Method Invocation) JMX Connector, andthe IBM proprietary SOXS (Serialized Object Exchange/Stream) JMX Connector.For V2R4 and later agents, the recommended protocol to use is SOXS, althoughRMI will still be available. Connections to Master Agents prior to V2R4 should onlyuse RMI. The following is an example of a class that creates and manages aJMXConnector instance for obtaining a remote MBeanServerConnection to a MasterAgent:

Notes:

1. Some lines of code are split over multiple lines to fit on the page.

2. This code can also be used to connect to the general agent with some minormodifications. First, the port used is 10151. Second, general agents only run aRMI JMXConnectorServer, so connecting using SOXS is not supported. Finally,the JNDI naming convention is /jndi/hostname.10151, where hostname shouldbe the actual host name of the system where the general agent is running. Youcan get the host name in Java with these lines of code:InetAddress localMachine = java.net.InetAddress.getLocalHost();System.out.println("Hostname of local machine: " + localMachine.getHostName());

3. General Agents do not support the enhanced security mode, only the standardsecurity mode that uses certificate-based authentication.

4. The SOXS Connector requires a RMASocketFactory instance to be supplied viathe SoxsConnector.CLIENT_SOCKET_FACTORY property. The SSL configurationsupplied to the RMASocketFactory must match the configuration (SSL/NOSSL)


|||||

||||||||||

used on the Master Agent, or else the connection will fail. See “SSLconfiguration” on page 44 for further information.

package com.ibm.retail;

import java.io.IOException;import java.net.InetAddress;import java.net.MalformedURLException;import java.net.UnknownHostException;import java.util.HashMap;import java.util.Map;

import javax.management.AttributeNotFoundException;import javax.management.InstanceNotFoundException;import javax.management.MBeanException;import javax.management.MBeanServerConnection;import javax.management.ObjectName;import javax.management.ReflectionException;import javax.management.remote.JMXConnector;import javax.management.remote.JMXConnectorFactory;import javax.management.remote.JMXServiceURL;import javax.naming.Context;

import mx4j.remote.soxs.SoxsConnector;

import com.ibm.retail.si.mgmt.MgmtConst;import com.ibm.retail.si.mgmt.MgmtDeviceInfo;import com.ibm.retail.si.mgmt.MgmtMasterHealthMBean;import com.ibm.retail.si.mgmt.masteragent.MasterAgent;import com.ibm.retail.si.mgmt.masteragent.auth.MasterAgentCredentialEncoder;import com.ibm.retail.si.mgmt.remote.DefaultRMACredentialEncoder;import com.ibm.retail.si.mgmt.remote.RMACredentialEncoder;import com.ibm.retail.si.mgmt.remote.RMAJMXCredentials;import com.ibm.retail.si.mgmt.remote.RMASocketFactory;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class MasterAgentConnectionHelper {

public static final int CONNECTOR_SOXS = 1;public static final int CONNECTOR_RMI = 2;

private boolean isEnhancedSecurity = true;private String masterAgentIP = null;private String connectionId = null;private JMXConnector connector = null;private MBeanServerConnection agentConnection = null;private MgmtDeviceInfo agentDeviceInfo = null;private int connectionType = -1;

public MasterAgentConnectionHelper(String agentIp, int connectionType) {this.masterAgentIP = agentIp;this.connectionType = connectionType;

}

/*** Returns the connection Id from the JMXConnector*/

public String getConnectionId() {if(connectionId == null) {

try {connectionId = connector.getConnectionId();

} catch (IOException e) {// Error

}}return connectionId;


}

/*** Returns the agent information for the connected Master Agent*/

public MgmtDeviceInfo getMasterAgentDeviceInfo() {return agentDeviceInfo;

}

/*** Closes the JMX Connector, if one exists*/

public void closeAgentConnection() {if(connector != null) {

try {connector.close();

} catch (IOException e) {// Ignore

}agentConnection = null;connectionId = null;agentDeviceInfo = null;

}}

/*** Obtains the MBeanServerConnection to the agent*/

public MBeanServerConnection getAgentConnection() {if(agentConnection == null) {

createAgentConnection();}return agentConnection;

}

private void createAgentConnection() {try {

InetAddress remoteHost = InetAddress.getByName( masterAgentIP );

// Create credentials based on the type of authenticationObject credentials = null;if( isEnhancedSecurity ){// Enhanced security, uses a username and passwordMasterAgentCredentialEncoder encoder = new MasterAgentCredentialEncoder();RMAJMXCredentials credentialInfo =RMAJMXCredentials.createMasterAgentUsernamePWCredentials( "username", "password" );

credentials = encoder.encodeCredentials( credentialInfo );}else{// Standard securityRMACredentialEncoder encoder = new DefaultRMACredentialEncoder();RMAJMXCredentials credentialInfo = new RMAJMXCredentials(MgmtConst.AGENT_VERSION_CURRENT,remoteHost.getAddress(), remoteHost.getAddress());

encoder.encodeCredentials(credentialInfo);}

Map properties = new HashMap();properties.put( JMXConnector.CREDENTIALS, credentials );

JMXServiceURL serviceUrl = null;// Populate the properties with connector specific dataif( connectionType == CONNECTOR_RMI ){


properties.put( Context.INITIAL_CONTEXT_FACTORY,"com.sun.jndi.rmi.registry.RegistryContextFactory" );

properties.put( Context.PROVIDER_URL, "rmi://" +remoteHost.getHostAddress() + ":" + MgmtConst.MA_MGMT_PORT );

serviceUrl = new JMXServiceURL( MgmtConst.MGMT_PROTOCOL_RMI, remoteHost.getHostAddress(),MgmtConst.MA_MGMT_PORT, MasterAgent.MASTER_AGENT_JNDI_NAME );

}else if ( connectionType == CONNECTOR_SOXS ){

properties.put( JMXConnectorFactory.PROTOCOL_PROVIDER_PACKAGES, "mx4j.remote" );properties.put( SoxsConnector.CLIENT_SOCKET_FACTORY,

new RMASocketFactory( MgmtConst.SSL_CONFIG_ALIAS_RMA_MA, -1, -1 ) );serviceUrl = new JMXServiceURL( MgmtConst.MGMT_PROTOCOL_SOXS,

remoteHost.getHostAddress(), MgmtConst.MA_MGMT_PORT_SOXS );}

// Create JMX Connector with the required informationconnector = JMXConnectorFactory.newJMXConnector( serviceUrl, properties );connector.connect( properties );

agentConnection = connector.getMBeanServerConnection();

// Obtain the Master Agent’s device informationinitAgentDeviceInfo();

// Register the JMX Connection Id and the local IP Address{

if( agentDeviceInfo.getAgentVersion() <= MgmtConst.AGENT_VERSION_V2R5 )}registerConnectionAndIp();

} catch (UnknownHostException e) {// ...

} catch (MalformedURLException e) {// ...

} catch (IOException e) {// ...

} catch (Exception e) {// ...

}}

/*** Queries the Discovery MBean on the Master Agent for its* agent information, a MgmtDeviceInfo instance*/

private void initAgentDeviceInfo() {ObjectName discoveryName = MgmtUtils.getObjectName(agentConnection,

MgmtMasterHealthMBean.OBJECT_NAME_ID);if(discoveryName == null) {

// Error} else {

try {agentDeviceInfo = (MgmtDeviceInfo) agentConnection.getAttribute(discoveryName, "DeviceInfo");

} catch (AttributeNotFoundException e) {// ...

} catch (InstanceNotFoundException e) {// ...

} catch (MBeanException e) {// ...

} catch (ReflectionException e) {// ...


}}


}

/*** Registers the JMX Connection Id and the local IP address with the Master Agent,* so that there will be an entry for the address in the agent’s AgentAuthList.* This allows RMAFileTransferConnections to be made*/

private void registerConnectionAndIp() {ObjectName discoveryName = MgmtUtils.getObjectName(agentConnection,

MgmtMasterHealthMBean.OBJECT_NAME_ID);if(discoveryName == null) {

// Error} else {

try {InetAddress remoteAddress = InetAddress.getLocalHost();agentConnection.invoke(discoveryName, "addConnectionAndAddress", new Object[]

{getConnectionId(), remoteAddress.getHostAddress()},new String[]{String.class.getName(), String.class.getName()});

} catch (InstanceNotFoundException e) {// ...

} catch (MBeanException e) {// ...

} catch (ReflectionException e) {// ...


}}

}}

Accessing MBean instrumentation

As discussed in the RMA architecture, the Master Agent is a mid-level manager thatprovides access to store resources from a single, centralized location. With anMBeanServerConnection to the Master Agent, you can access the MBeaninstrumentation from the Master Agent or from any General Agent in the store thatthe Master Agent discovers. The instrumentation that can be accessed falls into oneof two categories:

v Instrumentation local to the Master Agent itself

v Instrumentation from each General Agent in the store

The following sections describe how to programmatically access both forms ofMBean instrumentation.

Accessing General Agent MBeans from the Master Agent

The APIs and procedures for accessing store instrumentation changed with RMAV2R5. This section provides an explanation of how to access store MBeans in RMAV2R5 and earlier. In the case of RMA V2R5, an example for using the new APIs isprovided.

V2R4 and earlier: On Master Agents running RMA V2R4 and earlier, proxyMBeans are registered on the Master Agent for every MBean on each GeneralAgent. You can locate a General Agent MBean by using the query methods on theMBeanServerConnection interface, such as queryNames(). Using the queriedObjectName and the MBeanServerConnection, you can get and set attributes (usinggetAttribute() and setAttrbute()) and you can invoke methods (using invoke()).


V2R5 and later: Instead of having to query for proxy MBeans and access themdirectly through the MBeanServerConnection, you can perform all MBeanoperations on store agents by the methods provided in the ProxyManagerMBean. Allaccessor methods require the system ID of the agent on which the operation is tobe performed, as well as a query ObjectName for finding the MBean(s) on which toperform the operation (for example, the getAttribute() method).

The following code is an example of how to invoke the search method on allMBeans with an MBean ID of Test on agent test.10151, with a string argument offoo, and a primitive integer argument of 5:


import javax.management.MBeanServerConnection;import javax.management.MBeanServerInvocationHandler;import javax.management.ObjectName;

import com.ibm.retail.si.mgmt.masteragent.ProxyManagerMBean;

public class ProxyExample{

public static void main( String[] args ){

MBeanServerConnection mbs = /* get MBeanServerConnection to the Master Agent */

ObjectName proxyMgrName = com.ibm.retail.si.mgmt.util.MgmtUtils.getObjectName(mbs,ProxyManagerMBean.OBJECT_NAME_ID);

ProxyManagerMBean proxyMgr = (ProxyManagerMBean) MBeanServerInvocationHandler.newProxyInstance(mbs, proxyMgrName, ProxyManagerMBean.class, false);

// Create query ObjectName to find all target MBeansObjectName queryName = new ObjectName( "*:*,Id=Test" );

ObjectName[] objectNames = (ObjectName[]) proxyMgr.queryNames( "test.10151", queryName, null ).toArray( new ObjectName[0] );

if( objectNames.length > 0 ){ObjectName mbeanName = names[0];

// Parameters for the search methodObject[] methodParms = { "foo", new Integer(5) };String[] methodParamTypes = { String.class.getName(), Integer.TYPE.getName() };

// Make call to the proxy managerObject retVal = proxyMgr.invokeMethod( "test.10151", queryName, "search",

methodParms, methodParamTypes );}

}}

Locating Agent MBeansIf you have an MBeanServerConnection object (that is, you are connected to theMaster or a General Agent), you can query for the fully-qualified object names ofany MBean that is registered locally on that agent. For example, consider a customMBean that is started based on the following XML in the %SI_HOME%\user\rma\config\startup folder:


<AgentStartupConfig><MBeans><MBean className="com.ibm.retail.si.mgmt.samples.MyCustomBean"

objectName="generalagent:SIFComponent=MyComp,Id=MyIdentifier"/></MBeans></AgentStartupConfig>

The object name of this MBean can be queried using the MBeanServerConnectionobject. For example:

MBeanServerConnection mbs = /* get connection to the agent */

ObjectName name = com.ibm.retail.si.mgmt.util.MgmtUtils.getObjectName(mbs,"MyIdentifier");System.out.print( "MBean object name = " + name + "\n" );

MyCustomBeanMBean proxy = (MyCustomBeanMBean)MBeanServerInvocationHandler.newProxyInstance(mbs, name, MyCustomBeanMBean.class, false);

proxy.doSomething( "hello" ); // this is custom method on my custom MBean

Retrieving Store Events (Notifications)The remote JMX specification, JSR-160, provides the ability to registerNotificationListener objects for receiving Notifications through remote JMXconnections. However, any events sent when not connected are not buffered forwhen the connection is re-established. Since guaranteed event delivery is notprovided by remote JMX, RMA provides a store and forward feature for events,explained Chapter 14, “Understanding the architecture,” on page 153. This featureis implemented on top of JMX, with RMA providing an additional means for eventtransport.

Depending on the requirements of a management application, this feature might ormight not be required. As a result, there are two ways of accessing events emittedby agents in the store:

v Adding Notification Listeners

v Using the NotificationProcessor

The use of Notification Listeners should suffice for most management applications.Besides being simpler to use, this method uses less resources on the MasterAgent. Use of the NotificationProcessor starts extra threads for event transportand delivery, creates separate memory buffers on the Master Agent for each remoteJMX connection, sets up a temporary storage locations on the Master Agent foreach remote JMX connection, and uses disk space on the client side to temporarilystore events that overflow from the memory capacity being reached. While thespeed of event transport using both methods is basically the same, the use of theNotificationProcessor uses additional threads and storage not required by remoteJMX alone.

Adding Notification ListenersThe easiest and simplest option for receiving events from a particular MBean is toadd a NotificationListener directly to that MBean. When events from all agents inthe store are required, then adding a single listener to theMgmtNotificationControlMBean is the best option. TheMgmtNotificationControlMBean is a central collection point on the Master Agent forJMX notifications emitted by each General Agent. The MBean re-sends all of thenotifications that it receives after processing them, adding information about theoriginating agent. It is from this MBean that the Master Agent's EventControlMBeanreceives its events. The following is an example of adding a NotificationListenerto the MgmtNotificationControlMBean. It relies on the MasterAgentConnectionHelperclass outlined in the section “Making a Remote JMX Connection to the Master


Agent” on page 204.

The method MgmtUtils.getObjectName() is a convenience way for finding anMBean's ObjectName based on the value of the ID field. This code simply obtainsthe ObjectName of the MgmtNotificationControlMBean, and then calls the methodMBeanServerConnection.addNotificationListener() to add aNotificationListener instance to receive events from the MBean.

Using the Notification ProcessorThe NotificationProcessor is a object (not an MBean) on the MA and the DirectorServer that acts as a central collection point for all events. It handles the fetchingand delivery of all events from each remote agent's EventControlMBean. By callingthe addEventFetcher() method, a remote JMX Connection to an RMA agent getsregistered. This registration begins the flow of events from the RMA Agent to theNotificationProcessor by starting a separate thread make remote calls to fetchgroups of events. As each event is delivered, it is forwarded to registered listenersthrough the NotificationProcessor's supporting listener interface(NotificationProcessorListener).

Note: Some lines of code are split over two lines to fit on the page.


import java.io.IOException;

import javax.management.InstanceNotFoundException;import javax.management.MBeanServerConnection;import javax.management.Notification;import javax.management.NotificationListener;import javax.management.ObjectName;

import com.ibm.retail.si.mgmt.notifications.MgmtNotificationControlMBean;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class EventExample {

public void example() {MasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

// Create handler for eventsNotificationListener myListener = new MyListener();

// Query for ObjectName of the target MBeanObjectName mgmtNotCtrlName = MgmtUtils.getObjectName(agentConnection, MgmtNotificationControlMBean.OBJECT_NAME_ID);

if(mgmtNotCtrlName == null) {// Error

} else {// MBean found, add the listenertry {

agentConnection.addNotificationListener(mgmtNotCtrlName, myListener, null, null);} catch (InstanceNotFoundException e) {

// MBean not found} catch (IOException e) {

// Error making remote call}

}}

class MyListener implements NotificationListener {public void handleNotification(Notification notification, Object handback) {

// Do something with the Notification}

}}



import java.net.InetAddress;import java.util.LinkedList;import java.util.List;

import javax.management.MBeanServerConnection;import javax.management.Notification;import javax.management.ObjectName;

import com.ibm.retail.si.mgmt.MgmtDeviceInfo;import com.ibm.retail.si.mgmt.MgmtException;import com.ibm.retail.si.mgmt.eventcontrol.EventControlMBean;import com.ibm.retail.si.mgmt.notifications.NotificationProcessor;import com.ibm.retail.si.mgmt.notifications.NotificationProcessorData;import com.ibm.retail.si.mgmt.notifications.NotificationProcessorListener;import com.ibm.retail.si.mgmt.util.DiskOverflowStorage;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class NotProcExample {

public void example() {MasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

// Parameters for the NotificationProcessor (default values)int fetchSize = Integer.parseInt(NotificationProcessor.DEFAULT_EVENT_FETCH_MAX_EVENTS);int fetchTimeout = Integer.parseInt(NotificationProcessor.DEFAULT_EVENT_FETCH_CALL_TIMEOUT);int memQueueCapacity = Integer.parseInt(NotificationProcessor.DEFAULT_EVENT_QUEUE_MEMORY_CAPACITY);

// Storage object for event sequence numbersNotificationProcessorData notProcData = new MyNotificationProcessorData();

// Storage object for overflowed eventsDiskOverflowStorage diskOverflowStorage = new MyDiskOverflowStorage();

// Use the local host name as the identifier for ourselves to the MAString localHostName = InetAddress.getLocalHost().getHostAddress();

NotificationProcessor notProc = null;try {

// Initialize the NotificationProcessornotProc = new NotificationProcessor(fetchSize, fetchTimeout, memQueueCapacity, notProcData,

diskOverflowStorage);

// Add for fetched events listener, with no filterMyNotificationProcessorListener listener = new MyNotificationProcessorListener();notProc.addNotificationProcessorListener(listener, null);

// Start the NotificationProcessornotProc.start();

// Query for ObjectName of the target Event Control MBeanObjectName eventCtrlName = MgmtUtils.getObjectName(agentConnection, EventControlMBean.OBJECT_NAME_ID);

if(eventCtrlName == null) {// Error

} else {/** MBean found, register connection. After registration, events will begin being fetched and

delivered to our listener.** Parameters:* -The ObjectName of the EventControlMBean* -The MBeanServerConnection to the Master Agent* -The Master Agent’s agent information* -Our host name as an identifier for ourselves* -The connection Id of our remote JMX Connection*/

notProc.addEventFetcher(eventCtrlName, agentConnection, connectionHelper.getMasterAgentDeviceInfo(),localHostName, connectionHelper.getConnectionId());

}} catch (Exception e){}

}

class MyNotificationProcessorData implements NotificationProcessorData {/*** @see com.ibm.retail.si.mgmt.notifications.NotificationProcessorData#getLastEventSequenceNumber

(com.ibm.retail.si.mgmt.MgmtDeviceInfo)*/

public long getLastEventSequenceNumber(MgmtDeviceInfo device) {// Get agent’s sequence numberreturn 0;

}


/*** @see com.ibm.retail.si.mgmt.notifications.NotificationProcessorData#persistLastEventSequenceNumber

(com.ibm.retail.si.mgmt.MgmtDeviceInfo, long)*/

public void persistLastEventSequenceNumber(MgmtDeviceInfo device, long seqNo) throws MgmtException {// Save and store sequence number

}} class MyNotificationProcessorListener implements NotificationProcessorListener {

/*** @see com.ibm.retail.si.mgmt.notifications.NotificationProcessorListener#receiveNotification

(javax.management.Notification, com.ibm.retail.si.mgmt.MgmtDeviceInfo)*/

public void receiveNotification(Notification notification, MgmtDeviceInfo origDevice) {// Do something with notification

}

/*** @see com.ibm.retail.si.mgmt.notifications.NotificationProcessorListener#receiveNotifications

(javax.management.Notification[], com.ibm.retail.si.mgmt.MgmtDeviceInfo)*/

public void receiveNotifications(Notification[] notifications, MgmtDeviceInfo origDevice) {for(int i=0; i < notifications.length; i++) {

receiveNotification(notifications[i], origDevice);}

}}

class MyDiskOverflowStorage implements DiskOverflowStorage {/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#closeOverflowStorage()*/

public void closeOverflowStorage() {// close files, etc

}

/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#getFilePath()*/

public String getFilePath() {// Return path to storage filereturn null;

}/**

* @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#insertDataBlock(byte[])*/

public void insertDataBlock(byte[] data) throws MgmtException {// store data

}

/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#isEmpty()*/

public boolean isEmpty() {// True if we have event datareturn false;

}

/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#recreateStorage()*/

public DiskOverflowStorage recreateStorage() throws MgmtException {// Delete the file and recreatereturn null;

}

/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#restoreMemoryQueue()*/

public List restoreMemoryQueue() throws MgmtException {// Read memory contents from diskreturn new LinkedList();

}

/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#retrieveDataBlock()*/

public byte[] retrieveDataBlock() throws MgmtException {// Retrieve the next block of event datareturn null;

}

/*** @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#saveMemoryQueue(java.util.List)*/


Using the FileTransferConnection interfaceRMA includes a generic file transfer interface for use by the different underlyingimplementations. This interface is described in “File Transfer” on page 168. Thissection explains how code inside an agent JVM can use the FileTransferManagerand an implementation of FileTransferConnection interface to create a connectionand transfer files. The following code sample performs these tasks:


import java.util.Properties;

import com.ibm.retail.si.mgmt.xfer.FileTransferConnection;import com.ibm.retail.si.mgmt.xfer.FileTransferException;import com.ibm.retail.si.mgmt.xfer.FileTransferManager;import com.ibm.retail.si.mgmt.xfer.ftp.FTPConnection;import com.ibm.retail.si.mgmt.xfer.stream.RMAFileTransferConnection;

public class FileTransferExample {

public void example() {// Obtain file transfer managerFileTransferManager xferMgr = FileTransferManager.instance();

// Create connection properties for RMA File StreamingProperties xferProps = new Properties();xferProps.put(RMAFileTransferConnection.CONFIG_PROP_IMPL,RMAFileTransferConnection.CONFIG_IMPL_NAME);xferProps.put(RMAFileTransferConnection.CONFIG_PROP_HOSTNAME, "myhost.mydomain.com");

byte[] credentials = null;if (isEnhancedSecurity){// Enhanced security, uses a username and passwordMasterAgentCredentialEncoder encoder = new MasterAgentCredentialEncoder();RMAJMXCredentials credentialInfo =RMAJMXCredentials.createMasterAgentUsernamePWCredentials( "username", "password" );credentials = encoder.encodeCredentials(credentialInfo);}else{// Standard securityRMACredentialEncoder encoder = new DefaultRMACredentialEncoder();RMAJMXCredentials credentialInfo = new RMAJMXCredentials( MgmtConst.AGENT_VERSION_CURRENT,remoteHost.getAddress(), remoteHost.getAddress());credentials = encoder.encodeCredentials(credentialInfo);}xferProps.put( RMAFileTransferConnection.CONFIG_CREDENTIALS, credentials );

long connectionId = -1;try {

// Create and obtain connectionconnectionId = xferMgr.createConnection(xferProps);FileTransferConnection xferConn = xferMgr.getConnection(connectionId);

public void saveMemoryQueue(List memQueue) throws MgmtException {// Save the memory queue contents to a file

}}

}/**

* @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#saveMemoryQueue(java.util.List)*/

public void saveMemoryQueue(List memQueue) throws MgmtException {// Save the memory queue contents to a file

}}

}


// Retrieve filexferConn.get("C:\\localfile.dat", "C:\\remotefile.dat");

// Other file transfer operations....} catch (FileTransferException fte) {

// Handle} finally {

// Release connectionif(connectionId != -1) {

xferMgr.disconnect(connectionId);}

}}

}

As is previously described, the singleton FileTransferManager acts a source for allFileTransferConnections inside an agent JVM. Calling the createConnection()method on the FileTransferManager creates a FileTransferConnection instance tobe used for transferring files. It returns a connection ID that uniquely identifies theconnection. The method takes a Properties object as an argument that supplies theinformation needed to create the connection. The following common properties arerequired, and are used to determine which file transfer implementation will beinstantiated. Each implementation has its own required properties specific to thatimplementation that are used to initialize and connect the instance. The exampleabove uses RMA File Streaming, so it will require values for the common propertiesin addition top for those specific to RMA File Streaming.

Common propertiesTable 33. Common properties

Name Description

com.ibm.retail.si.mgmt.xfer.impl (Required) Identifier for theimplementation, such as STREAM (RMAFile Streaming), FTP, or FTPS

RMAFileTransferConnection propertiesTable 34. RMA File Streaming Properties

Name Description

com.ibm.retail.si.mgmt.xfer.stream.hostname (Required) Host name or IP Addressto connect to

com.ibm.retail.si.mgmt.xfer.stream.port (Optional) Overrides the port toconnect to. Defaults to 10190

com.ibm.retail.si.mgmt.xfer.stream.credentials (Required) A byte array of encodedcredential information. The credentialformat is the same as for makingJMX connections to that agent

FTPConnection propertiesTable 35. FTPConnection properties

Name Description

com.ibm.retail.si.mgmt.xfer.ftp.username (Required) FTP Username

com.ibm.retail.si.mgmt.xfer.ftp.password (Required) FTP Password

com.ibm.retail.si.mgmt.xfer.ftp.hostname (Required) FTP Server host name or IP


Table 35. FTPConnection properties (continued)

Name Description

com.ibm.retail.si.mgmt.xfer.ftp.port (Optional) Override the default port of 21

FTPSConnection propertiesTable 36. FTPSConnection properties

Name Description

com.ibm.retail.si.mgmt.xfer.ftp.username (Required) FTP Username

com.ibm.retail.si.mgmt.xfer.ftp.password (Required) FTP Password

com.ibm.retail.si.mgmt.xfer.ftp.hostname (Required) FTP Server host name or IP

com.ibm.retail.si.mgmt.xfer.ftp.port (Optional) Override the default port of 21

Use the instance and disconnect():FileTransferManager xferMgr = null;try {xferMgr = FileTransferManager.getInstance();

Properties xferProps = new Properties();xferProps.put(FileTransferConnection.CONFIG_PROP_IMPL,

FTPConnection.CONFIG_IMPL_NAME);xferProps.put(FTPConnection.CONFIG_PROP_USERNAME,"user");xferProps.put(FTPConnection.CONFIG_PROP_PASSWORD,"pass");xferProps.put(FTPConnection.CONFIG_PROP_HOSTNAME,

"myhost.mydomain.com");

long connectionId = xferMgr.createConnection(xferProps);FileTransferConnection xferConn =

xferMgr.getConnection(xferProps);

xferConn.cd("/home/user");xferConn.get("remotefile.dat", "C:\localfile.dat");xferMgr.disconnect(connectionId);} catch (FileTransferException fte) {// Handle}

When the FileTransferConnection instance has been obtained, it can be used toperform file transfer operations. After the instance is no longer needed, thedisconnect() method should be called. This method cleanly disconnects and willunregister the connection from the FileTransferManager. Even if this method is notcalled, a Timer in the FileTransferManager periodically checks each connection andwill eventually disconnect it.

Transfer typesThe FileTransferConnection interface supports both blocking and non-blockingforms of transfers, corresponding to the put() and get() methods and theputAsync() and getAsync() methods, respectively. The difference between the twotypes is that calls to put() and get() block until the transfer completes. Calls toputAsync() and getAsync() return after the transfer successfully begins and wait inthe background for the transfer to complete. A callback object implementing theFileTransferEventListener interface is required when making asynchronous calls.When the transfer completes, either successfully or unsuccessfully, a call is madeto the transferCompleted() method of the callback object to signal completion.


An argument to the handleTransferEvent() method is a FileTransferProgressobject. This object will contain the following information:

v Whether the transfer was successful (true or false)

v The last reply code from the File Transfer server

v The connection ID

v The name of the local file transferred

v The name of the remote file transferred

v The number of bytes currently transferred

Asynchronous calls made from the FileTransferMBean will take theFileTransferProgress object and construct either aFileTransferProgressNotification or a FileTransferCompletionNotification.

Note: When invoking operations on this MBean over a remote JMX connection,socket timeouts could occur when the operations take a large amount oftime. In particular, invoking the operations such as put() and get() on largefiles could take a long period of time, possibly resulting in a socket timeouton the remote JMX call. For transfers that take a large amount of time, anasynchronous call can be made to ensure that the remote call will not timeout.

When making asynchronous putAsync() and getAsync() calls, a check is made tosee if the connection is busy transferring a file or sending another command. If theconnection is busy, then the request will not be made. This is done to ensure thatremote JMX calls do not block when waiting for a lock on the connection. TheisBusy() method provides non-synchronized access to the busy status of aconnection.

Transfer progressThe asynchronous putAsync() and getAsync() calls also support the ability fortransfer progress to be reported by percentage increments via callbacks. A typicaluse for these notifications would be in a management application to implement aprogress bar. Transfer progress is reported via a callback to thetransferProgress() method in the FileTransferEventListener interface. TheFileTransferProgress object returned will include the percentage complete inaddition to the information reported by a transfer completion.

In making asynchronous calls, the transfer progress arguments are optional, andcan range 1-100. Values outside of this range will be ignored. The value suppliedrepresents the interval at which the Notifications are emitted. For example, a valueof 5 will emit a Notification after 5 percent, 10 percent, 15 percent, and so on, up to100 percent.

The intervals at which Notifications are emitted are calculated internally based onblocks of 4 kb (FTP and FTPS). If files are too small, or sizes do not fall on a 4 kbboundary, the increments will get rounded up.

Calls to getAsync() require a file size to be supplied with the call for calculating thepercentage increments. This is because the FTP protocol does not have a way ofobtaining a remote file's size. If the size and/or increments supplied are notconsistent, then the only Notification sent will be at 100 percent.


Managing monitor policiesProgrammatically managing Monitor policies involves making a remote JMXConnection to the Master Agent MBeanServer and interacting with theMonitorManagerMBean. Refer to “Making a Remote JMX Connection to the MasterAgent” on page 204 for details of making this connection.

When managing monitor policies on the Master Agent programmatically, two actionsare required:

v Creating and registering a MonitorPolicy object with the MonitorManagerMBean.

v Creating and registering a MonitorPolicyAction object with theMonitorManagerMBean.

MonitorPolicy objectA MonitorPolicy object contains the details about the JMX MonitorMBean to becreated on the Master Agent. Specifically, it contains:

v Fully qualified class name of the type of monitor to create(javax.monitor.CounterMonitor)

v A JMX AttributeList containing any Attributes to be set on the MonitorMBeanwhen it is created (for GaugeMonitors, the HighThreshold and LowThresholdattributes must be set).

v ObjectName query string to search for the MBeans

v Description for the Monitor

MonitorPolicy objects are added and removed from MonitorManagerMBean registryusing the addMonitorPolicy() and removeMonitorPolicy() methods.

MonitorPolicyAction objectA MonitorPolicyAction object is for associating a MonitorPolicy with its targetdevice(s), that can be individual agents, all agents on a single device, or all agentson all devices of a particular device type. The subclasses of MonitorPolicyActioneach represent a different type of policy application (single agent, device type, andso on).

MonitorPolicyAction objects are registered and de-registered with theMonitorManagerMBean using the registerMonitor() and deregisterMonitor()methods. After a MonitorPolicyAction has been registered with theMonitorManagerMBean, JMX MonitorMBeans will be created immediately on affectedagents, or when they come online.

The following example creates a MonitorPolicy for the TotalMemory attribute on theJVMEnvironmentMBean and registers it to be applied on all General Agents runningon Linux:


Managing data capture policiesProgrammatically managing data capture policies involves making a remote JMXConnection to the Master Agent MBeanServer. Refer to “Making a Remote JMXConnection to the Master Agent” on page 204 for details of making this connection.

Data Capture policies provide an automated way of transferring diagnostic data andinvoking other captures. After a policy is active, it will cause capture files fromcompleted captures to be transferred, solicited captures to be invoked on captureMBeans in the policy's capture list, and create capture bundle .ZIP files fromcompleted invocations. This section provides examples of how to programmaticallymanage data capture policies. These examples could be used to create amanagement application that connects to the Master Agent, manages policies, andlistens and/or query for invocation status.

Note: The Data Capture Policy Manager task in IBM Director already provides thisfunctionality.

The following actions are involved in managing data capture policies:

v Creating a Capture Policy

v Adding a Policy to the Policy Registry

v Activating a Capture Policy

v Receiving Capture Completion Notifications

v Querying Invocation History

v Terminating and Deleting a Policy

Creating, Adding, and Activating a Capture PolicyThe following example creates a data capture policy, registers it with theDataCapturePolicyRegistryMBean, and activates it through a call to the

/** Create MonitorPolicy*/ AttributeList al = new AttributeList();al.add(new Attribute("ObservedObject",new ObjectName( Mgmt

Const.MASTER_AGENT_DOMAIN +MgmtJVMEnvironmentMBean.OBJECT_NAME_BASE)));

al.add( new Attribute( "ObservedAttribute", "TotalMemory" ) );al.add( new Attribute( "GranularityPeriod", new Long(60000) ) );al.add( new Attribute( "HighThreshold", new Long(33554432) ) );al.add( new Attribute( "LowThreshold", new Long(0) ) );al.add( new Attribute( "NotifyHigh", new Boolean(true) ) );al.add( new Attribute( "NotifyLow", new Boolean(false) ) );MonitorPolicy gaugePolicy = new MonitorPolicy(GaugeMonitor.

class.getName(),al,MgmtConst.MASTER_AGENT_DOMAIN + MgmtJVMEnvironmentMBean.OBJECT_NAME_BASE,"MonitorJVM TotalMemory" );

/** Create MonitorPolicyAction*/MonitorPolicyAction action = new DeviceTypeMonitorPolicyAction(counterPolicy,new

Integer(MgmtConst.dTypeLinux));/** Add policy and register action*/ObjectName mgrName = new ObjectName(MonitorManagerMBean.OBJECT_NAME);connection.invoke(mgrName,"addMonitorPolicy",new Object[] {gaugePolicy},

new String[]{MonitorPolicy.class.getName()});

connection.invoke(mgrName,"registerMonitor",new Object[] {action},new String[]{DeviceTypeMonitorPolicyAction.class.getName()});


DataCaptureManagerMBean. Registration of the policy with theDataCapturePolicyRegistryMBean involves invoking the addCapturePolicy method.Activating the policy requires invoking the activatePolicy() method on theDataCaptureManagerMBean.




import javax.management.InstanceNotFoundException;import javax.management.MBeanException;import javax.management.MBeanServerConnection;import javax.management.ObjectName;import javax.management.ReflectionException;

import com.ibm.retail.si.mgmt.MgmtConst;import com.ibm.retail.si.mgmt.capture.DataCaptureConst;import com.ibm.retail.si.mgmt.capture.DataCaptureManagerMBean;import com.ibm.retail.si.mgmt.capture.DataCapturePolicy;import com.ibm.retail.si.mgmt.capture.DataCapturePolicyImpl;import com.ibm.retail.si.mgmt.capture.DataCapturePolicyRegistryMBean;import com.ibm.retail.si.mgmt.capture.DeviceCapturePolicyApplication;import com.ibm.retail.si.mgmt.capture.DeviceTypeCapturePolicyApplication;import com.ibm.retail.si.mgmt.capture.GenericLogCaptureMBean;import com.ibm.retail.si.mgmt.capture.RMADataCaptureMBean;import com.ibm.retail.si.mgmt.policies.DeviceTypePolicyApplication;import com.ibm.retail.si.mgmt.policies.PolicyApplicationList;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class AddCapturePolicy {

public DataCapturePolicy createAndActivateCapturePolicy() {// Create a remote connection to the Master AgentMasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

/** Create the policy’s trigger list. The list consists of one entry:* <All device types, All General Agents, RMADataCaptureMBean>*/

PolicyApplicationList triggerList = new PolicyApplicationList();triggerList.addPolicyApplication(new DeviceTypeCapturePolicyApplication(MgmtConst.dTypeAll, MgmtConst.GENERAL_AGENT_DEFAULT_ROLE,

DeviceTypePolicyApplication.WILD_CARD, RMADataCaptureMBean.OBJECT_NAME_ID));

/** Create policy’s capture list. The list consists of two entries:* <MyDevice1, GenericLogCaptureMBean, {C:\logs\*.log,C:\data\*.dat}>* <MyDevice2, GenericLogCaptureMBean, {C:\logs\*.log,C:\data\*.dat}>*/

PolicyApplicationList captureList = new PolicyApplicationList();captureList.addPolicyApplication(new DeviceCapturePolicyApplication("MyDevice1", GenericLogCaptureMBean.OBJECT_NAME_ID, new String[]{"C:\\logs\\*.log",

"C:\\data\\*.dat"}));captureList.addPolicyApplication(new DeviceCapturePolicyApplication("MyDevice2", GenericLogCaptureMBean.OBJECT_NAME_ID, new String[]{"C:\\logs\\*.log",

"C:\\data\\*.dat"}));

// Create the policy objectDataCapturePolicy policy = new DataCapturePolicyImpl("Capture Policy Description", triggerList, captureList, DataCaptureConst.DEFAULT_CAPTURE_TIMEOUT);

} catch (InstanceNotFoundException e) {// ..

} catch (MBeanException e) {// ..

} catch (ReflectionException e) {// ..

} catch (IOException e) {// ..

}}

// Query for ObjectName of the policy manager MBeanObjectName captureMgrName = MgmtUtils.getObjectName(agentConnection, DataCaptureManagerMBean.OBJECT_NAME_ID);

if(captureMgrName == null) {// Error

} else {// MBean found, activate the policytry {

agentConnection.invoke(captureMgrName, "activatePolicy", new Object[]{policy.getPolicyId()}, new String[]{String.class.getName()});} catch (InstanceNotFoundException e) {

// ..} catch (MBeanException e) {

// ..} catch (ReflectionException e) {

// ..} catch (IOException e) {

// ..}

}

return policy;}

}


This example illustrates the use of both types of policy applications, a device typepolicy application, and a device policy application. The device type policyapplication, which comprises the policy's entire trigger list, matches all agent devicetypes, all RMA Service General Agents, and the RMALogCaptureMBean. Looselyworded, this policy application list translates to: "Invoke the capture policy when anunsolicited capture notification is received from the RMALogCaptureMBean on a RMAService General Agent."

The capture list has two individual device policy applications. Each applies to theGenericLogCaptureMBean on devices MyDevice1 or MyDevice2. Each also suppliescapture arguments to be supplied to the GenericLogCaptureMBean when a capture isinvoked. Loosely worded, this application list translates to: "When a capturenotification is received that applies to the trigger list, invoke solicited captures ontothe GenericLogCapture MBeans on the devices MyDevice1 and MyDevice2.

Receiving Capture Completion NotificationsCapture completion notifications (of typecom.ibm.retail.si.mgmt.notifications.DataCaptureNotification) are sent bydata capture client MBeans (running on the General or Master Agents) when asolicited or unsolicited capture completes. The easiest way of receiving all of theseevents is by registering a single NotificationListener with theMgmtNotificationControlMBean, described in“Retrieving Store Events (Notifications)”on page 210.

Each DataCaptureNotification includes information about the capture, includingthe capture ID, client paths to the capture files, and error code from the capture. Todetermine the agent from which the event (and the capture) originated, examine theMgmtDeviceInfo object returned from the getOriginatingDevice() method on theDataCaptureNotification.

Querying Invocation HistoryThe DataCaptureHistoryMBean provides an interface to the logs and capture historyfor all registered policies. The capture history for each policy is contained in aCaptureHistory object, which contain other objects that break down the capturehistory in a hierarchical manner. An empty CaptureHistory object is createdwhenever a policy is activated.

CapturePolicyInvocationRecordsA CaptureHistory object contains a CapturePolicyInvocationRecord for each timethe policy is invoked on an agent by a DataCaptureNotification or a manualtrigger. The key for an invocation record is its start date, which takes the form of theMaster Agent system timestamp when the invocation was manually triggered orwhen an unsolicited capture notification was received. It also has a state thatrepresents an aggregation of all nested CaptureAgentRecords.

CaptureAgentRecordsA CapturePolicyInvocationRecord contains a CaptureAgentRecord for each agentinvolved in each policy invocation. CaptureAgentRecord objects represent policyactivations on an agent, and are used to track the progress and status of a set ofMBean captures on an agent.

CaptureInstanceRecordsA CaptureAgentRecord object contains a CaptureInstanceRecord for eachDataCaptureMBean instance a capture is performed on. One CaptureInstanceRecordinstance contains a set of CaptureFile instances and CaptureLogMsg instances. The


CaptureFile instances contain information about each capture file, and whether ithas been transferred to the Master Agent. Two sets of CaptureLogMsg instancesdetail the capture log and the transfer log for that capture. All CaptureLogMsginstances are translated, with a msgKey attribute and a set of message parameters.The msgKey attribute is a key into a resource bundle. The resource bundle used forcapture messages is com.ibm.retail.si.mgmt.resources.CaptureResources,located in rma.jar. The parameters are message parameters used to format themessage using the MessageFormat class.

Terminating and Deleting a Data Capture PolicyWhen a data capture policy no longer needs to be in effect, it should be terminated.If it will never be activated again, then it should also be removed. Only non-activepolicies can be removed, so a policy must be terminated before being deleted.Invoke the terminatePolicy() method on the DataCaptureManagerMBean toterminate a policy. Invoke the removePolicy() method on theDataCaptureManagerMBean to remove a policy. The following example terminates andremoves a registered policy:

Managing software distribution policiesRMA provides a RMASWPackageDistributorMBean that automates the creation andtermination of software policies by processing properly formatted JAR files. Thismethod of distribution takes much of the work from you. The details of using thisMBean are described in “RMA Package Distributor MBean” on page 174.




import com.ibm.retail.si.mgmt.capture.DataCaptureManagerMBean;import com.ibm.retail.si.mgmt.capture.DataCapturePolicy;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class TermDeleteCapturePolicy {

public void terminateAndDeletePolicy() {// Create a remote connection to the Master AgentMasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

DataCapturePolicy policy = createAndActivateCapturePolicy();

// Query for ObjectName of the policy manager MBeanObjectName captureMgrName = MgmtUtils.getObjectName(agentConnection, DataCaptureManagerMBean.OBJECT_NAME_ID);

if(captureMgrName == null) {// Error

} else {// MBean found, terminate and delete the policytry {

agentConnection.invoke(captureMgrName, "terminatePolicy", new Object[]{policy.getPolicyId()}, new String[]{String.class.getName()});agentConnection.invoke(captureMgrName, "removePolicy", new Object[]{policy.getPolicyId()}, new String[]{String.class.getName()});





}}

}

}


Applications that require control over the activation and termination of softwarepolicies can do so programmatically. The remainder of this section describes theactions involves in managing software policies.

Managing software policies programmatically requires a policy XML file andresource files residing on the Master Agent. This file must be created beforecreating and activating policies. For details on the format and content of the policyXML file, refer to “Software Distribution Policy” on page 178.

All classes related to software distribution policies are in thecom.ibm.retail.si.mgmt.swdist package. The following are the actions involved inmanaging software policies:

v Registering a draft policy with the SWDistPolicyRegistryMBean.

v Registering for state and completion notifications with theMgmtSWPolicyMasterMBean.

v Activating the draft policy.

v Querying the SWDistPolicyHistoryMBean for distribution status and historyinformation.

v Terminating and deleting a policy.

Registering draft policiesAll software polices (active or inactive), are represented as SWPolicy objects.Before a SWPolicy can be activated, a draft must be registered with theSWDistPolicyRegistryMBean. The addSWPolicy() method is used to add a draftSWPolicy on the SWDistPolicyRegistryMBean. From this MBean, it can be updatedor copied using the updateSWPolicy() or copySWPolicy() methods before beingactivated. The following is an example of creating and registering a SWPolicy:



State and progress notificationsNotifications of typecom.ibm.retail.si.mgmt.notifications.MgmtSWPDeviceStateNotification areemitted by clients at the start of, during, and at the completion of distributions.These Notifications can be accessed through the MgmtNotificationControlMBean.


import java.io.IOException;import java.net.InetAddress;


import com.ibm.retail.si.mgmt.policies.PolicyApplication;import com.ibm.retail.si.mgmt.swdist.FTPAccessInfo;import com.ibm.retail.si.mgmt.swdist.SWDConst;import com.ibm.retail.si.mgmt.swdist.SWDistPolicyRegistryMBean;import com.ibm.retail.si.mgmt.swdist.SWPolicy;import com.ibm.retail.si.mgmt.util.MgmtUtils;import com.ibm.retail.si.mgmt.xfer.stream.RMAFileTransferConnection;import com.ibm.retail.si.mgmt.xfer.stream.RMAFileTransferConstants;

public class CreateSWPolicy {

public SWPolicy createAndRegisterSWPolicy() {// Create a remote connection to the Master AgentMasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

// Create File Transfer InformationString hostname = InetAddress.getLocalHost().getHostAddress();int port = RMAFileTransferConstants.DEFAULT_SERVER_PORT;String xferImpl = RMAFileTransferConnection.CONFIG_IMPL_NAME;FTPAccessInfo xferInfo = new FTPAccessInfo(hostname, port, xferImpl);

// Set the locations of the policy.xml file and resource filesxferInfo.setFtpDirectoryPath("C:\\rma\\policies\\mypolicy");xferInfo.setResourceFileFTPPath("C:\\rma\\policies\\mypolicy\\pkgfiles");

// Scheduled date and time for the policy. Any time in the past will invoke immediatelylong invokeNow = System.currentTimeMillis();

/** Create policy object as an install policy to be invoked immediately.*/

SWPolicy policy = new SWPolicy("MySWPolicy", invokeNow, xferInfo, "policy.xml", SWDConst.INSTALL,PolicyApplication.APP_TYPE_DEV_LIST);

// Add the target devicespolicy.addAppliedDevice("device1");policy.addAppliedDevice("device2");

// Set the destination directory on the clientpolicy.setClientTargetPath("C:\\temp\\mypolicytmp");

// Query for ObjectName of the policy registry MBeanObjectName swPolicyRegName = MgmtUtils.getObjectName(agentConnection, SWDistPolicyRegistryMBean.OBJECT_NAME_ID);

if(swPolicyRegName == null) {// Error

} else {// MBean found, add the policytry {

Boolean rc = (Boolean) agentConnection.invoke(swPolicyRegName, "addSWPolicy",new Object[]{policy}, new String[]{SWPolicy.class.getName()});





}}

return policy;}

}


See “MgmtNotificationControlMBean” on page 162.). To ensure that all notificationsare received, NotificationListeners should be added before activating a policy.

The message in each MgmtSWPDeviceStateNotification (by way ofjavax.management.Notification.getMessage()) is a formatted message thatcontains progress information for the policy invocation on the client. Creating aninstance of com.ibm.retail.si.mgmt.DeviceStateMessage with the message Stringwill cause the information not be parsed and accessible.

The MgmtSWPDeviceStateNotification also exposes log information in the form ofSWLogMsg instances. Included is log information from standard error, standard out,and the client during policy invocation. The MgmtSWPDeviceStateNotification alsoexposes progress information (number of commands completed, total number ofcommands, etc.).

Activating a draft policyActivating a draft policy requires the activateSWPolicy() method to be called onthe MgmtSWPolicyMasterMBean. The policy ID from a registered draft policy isrequired. When activated, a SWPolicy is no longer available to be edited from theSWDistPolicyRegistryMBean. The following example activates a policy:

Policy invocation history and statusThe SWDistPolicyHistoryMBean provides an interface to the logs and distributionhistory for all registered policies. The history for each policy is contained in aSWPolicyHistory object, which contain DeviceSWPolicyRecord objects for eachagent that applies to the policy. The policy ID is the primary means for tracking a




import com.ibm.retail.si.mgmt.swdist.MgmtSWPolicyMasterMBean;import com.ibm.retail.si.mgmt.swdist.SWPolicy;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class ActivateSWPolicy {public void activateSWPolicy(SWPolicy policy) {

// Create a remote connection to the Master AgentMasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

// Query for ObjectName of the policy master MBeanObjectName swPolicyMasterName = MgmtUtils.getObjectName(agentConnection, MgmtSWPolicyMasterMBean.OBJECT_NAME_ID);

if(swPolicyMasterName == null) {// Error

} else {// MBean found, activate the policytry {

agentConnection.invoke(swPolicyMasterName, "activateSWPolicy", new Object[]{new Integer(policy.getPolicyID())},new String[]{Integer.TYPE.getName()});





}}

}}


software policy in the SWDistPolicyHistoryMBean, where the getPolicyHistory()method returns the SWPolicyHistory for a policy.

Terminating and deleting a PolicyWhen a software policy no longer needs to be in effect, it should be terminated andthen removed. Only non-active policies can be removed, so a policy must beterminated before being deleted. Invoke the terminatePolicy() method on theMgmtSWPolicyMasterMBean to terminate a policy. Invoke the removePolicy() methodon the SWDistPolicyRegistryMBean to remove a policy. The following exampleterminates and removes a registered policy:





import com.ibm.retail.si.mgmt.swdist.MgmtSWPolicyMasterMBean;import com.ibm.retail.si.mgmt.swdist.SWDistPolicyRegistryMBean;import com.ibm.retail.si.mgmt.swdist.SWPolicy;import com.ibm.retail.si.mgmt.util.MgmtUtils;

public class TermDeleteSWPolicy {public void terminateAndDeletePolicy() {

// Create a remote connection to the Master AgentMasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();

// Create and register policySWPolicy policy = createAndRegisterSWPolicy();

// Activate the policyactivateSWPolicy(policy);

// Query for ObjectName of the policy master MBeanObjectName swPolicyMasterName = MgmtUtils.getObjectName(agentConnection, MgmtSWPolicyMasterMBean.OBJECT_NAME_ID);

if(swPolicyMasterName == null) {// Error

} else {// MBean found, terminate the policytry {

agentConnection.invoke(swPolicyMasterName, "terminateSWPolicy", new Object[]{new Integer(policy.getPolicyID())},new String[]{Integer.TYPE.getName()});





}}

// Query for ObjectName of the policy registry MBeanObjectName swPolicyRegName = MgmtUtils.getObjectName(agentConnection, SWDistPolicyRegistryMBean.OBJECT_NAME_ID);

if(swPolicyRegName == null) {// Error

} else {// MBean found, remove the policytry {

Boolean rc = (Boolean) agentConnection.invoke(swPolicyRegName, "removeSWPolicy", new Object[]{policy},new String[]{SWPolicy.class.getName()});


SystemStateManagerThe SystemStateManager and SystemStateManagerMBean are singleton componentsthat manage system state transitions during the invocation of a software distributionpolicy. The software distribution client uses this functionality in order to change thesystem into a certain state before executing a policy and back into the previousstate after executing a policy. The state that it will change to is defined in theSWPolicy object on the Master Agent.

There are a set of predefined states. The NOOP state does nothing and cannot beoverridden. The following summarizes the predefined system states:

v NOOP (Always does nothing)

v NORMAL

v SW_MAINT

v DIAGS

v DATA_MAINT

v OS_UPDATE

v DRIVER_UPDATE

This functionality provides a hook for providing custom state transition actions. Forexample, it might be desirable for the SW_MAINT state to stop the running POSApplication before actually doing the update to follow. Registration of an instance ofSystemStateHandler to handle the SW_MAINT state is how this task is accomplished.By default all system state transitions do nothing, so nothing will happen withoutany registered SystemStateHandlers.

SystemStateChangeListener and SystemStateChange NotificationsWhen issuing a state change request, an instance of SystemStateChangeListener issupplied. For state changes that return Yes or No, this instance is ignored. For astate change request that is deferred, this instance is the means to notify theoriginal caller that the state change has completed. For most state changerequests, the listener will be the SystemStateManger itself. When called back by thehandler for a successful state change, the SystemStateManager will send aSystemStateChangeNotification, which will include the request state. For failedstate changes, a SystemStateChangeErrorNotification will be sent, which willinclude the target state, and an error message describing why the state changefailed.

SystemStateHandlerThe details of transferring into/out of states is handled by an instance ofSystemStateHandler. The method defined in this interface, requestStateChange(),determines if the state change can be performed, and if so, performs the state





}}

}}


change. It should promptly return one of three values, a YES, NO, or DEFER. If thestate change can be performed but it will take a long time, then DEFER should bereturned and the state change executed in a separate thread. The suppliedSystemStateChangeListener provides a way to notify the original caller when thestate change completes.

There is only one SystemStateHandler per agent, with the ability to override theagent's instance provided by the setSystemStateHandler() method in the singletonSystemStateManager. Thus, all that needs to be done in order provide a custom setof system state changes is to implement and register a SystemStateHandler.

Coding best practicesThis section describes the task of using error logging and the functions of logginglevels.

Using error loggingError logs are critical in detecting and correcting application errors. The moreinformation about what the application was doing at the time of the problem, theeasier it is to resolve the problem. Unfortunately, logging too much information canhave a negative impact on performance. Therefore, finding the right amount ofinformation to log is important. This task shows you how to log errors in a way thatis consistent with the rest of the IBM Remote Management Agent code. Topics suchas error log entry contents, APIs, and correct use of logging levels are discussed.

Logging levelsBecause of the negative impact of logging too much information on the system, it isimportant to use logging levels consistently. This enables you to know what kind ofinformation is logged at each level. Using this knowledge, you can set the logginglevel for your system to give you just the information that you need.

Use Table 37 to identify the purpose of each logging level.

Table 37. Logging level functions

Logging level Description

FATAL Severe errors that cause premature termination.

ERROR Other runtime errors or unexpected conditions. This level is used for:

v Java exceptions

v Missing data files such as simgmt.pro

v Missing property files

WARN Use of deprecated APIs, poor use of API, or other runtime situationsthat might require attention.

INFO Interesting runtime events (such as startup and shutdown). Expectthese to be immediately visible in the logs, so be conservative andkeep them to a minimum.

DEBUG Detailed information on flow through the system.


Table 37. Logging level functions (continued)

Logging level Description

TRACE More detailed information. By default, the message priority should beno lower than info. That is, by default debug and trace messagesshould not be seen in the logs. You want to have exception andproblem information available for first-pass problem determination ina production level enterprise application without turning on debug ortrace as default log levels. Too much information is available in theselevels to be appropriate for day-to-day operations. This level is usedfor:

v Method entry

v Exit tracing

Logging APIsTable 38 shows the list of APIs and their effect after factoring and includingdifferences for both Jakarta Commons Logging and Sun's JDK 1.4. These are theAPIs that Store Integrator uses. The idea behind the Jakarta Commons Logging APIis to be logging implementation independent. So you should treat log.fatal() andlog.error() differently even though they look the same in the error logs. That wayif your logging implementation changes to one that distinguishes between error andfatal levels, your software takes advantage of that.

Table 38. Log levels with sample log entries

API JDK Log Level Sample Log Entry

Log.fatal() SEVERE Apr 21, 2006 8:10:48 AM Test main SEVERE: errortext

Log.error() SEVERE Apr 21, 2006 8:10:48 AM Test main SEVERE: errortext

Log.warn() WARNING Apr 21, 2006 8:10:48 AM Test main WARNING:error text

Log.info() INFO Apr 21, 2006 8:10:48 AM Test main INFO: errortext

Log.debug() FINE Apr 21, 2006 8:10:48 AM Test main FINE: errortext

Log.trace() FINEST Apr 21, 2006 8:10:48 AM Test main FINEST: errortext

Controlling error log outputThe output of the logging calls is configurable based on the settings of%SI_HOME%\user\ext\user_log.pro, which overrides settings in%RMA_HOME%\mgmt_log.pro. This allows the end user to control what informationis included in the error logs. See “Logging configuration” on page 47 for moredetails.

Because logging an error involves some processing time, it is recommended thatyou do a test before an error is logged. This way if the error log is just going to bethrown away, the processing time is avoided. Specifically, it is recommended thatyou call log.isInfoEnabled(), log.isDebugEnabled(), and log.isTraceEnabled()before logging an error at those levels. For example:


if log.isInfoEnabled(){

log.info("Text to be logged");}

Error log entry contentsThere are two versions of the log APIs for each logging level. One takes a Stringand one takes a String and an exception as a parameter. In order to standardizethe log entries, it is recommended that any errors including exceptions, should belogged using the two-parameter version of the API, which provides a consistentappearance in the log entries.


Appendix A. Javadoc pdf file

For API information, refer to the IBM Remote Management Agent Javadoc pdf filethat is associated with this user guide. The Javadoc pdf files for all versions of RMAcan be obtained by going to the IBM Retail Store Solutions Web site atwww.ibm.com/solutions/retail/store/support. Click Publications. Then scroll down toRemote Management Agent.


http://www.ibm.com/solutions/retail/store/support

Appendix B. Inventory tables

The RMA inventory collection provides a limited subset of the information that IBMDirector can provide. The following table lists the inventory information that IBMDirector provides and indicates whether it is supported on the device type.

Table 39. Inventory tables

Inventory table Windows Linux 4690

Adapter/Fibre Channel Adapter N N N

Adapter/IDE Adapter Y N N

Adapter/Network Adapter Y Y N

Adapter/RAID Controllers N N N

Adapter/SCSI Adapter Y N N

Chassis N N N

Cluster N N N

Device/External/Keyboard Y N N

Device/External/Pointing Device Y N N

Device/External/Printer Y N N

Device/External/RAID Enclosures N N N

Device/Internal/IDE Device Y N Y

Device/Internal/Management Proc. N N N

Device/Internal/Parallel Port Y N Y

Device/Internal/PCI Device N N N

Device/Internal/SCSI Device Y N N

Device/Internal/Serial Port Y N Y

Device/Internal/System Slots Y N Y

Device/Internal/USB Device Properties N N Y

Management Proc. Network Settings N N N

Memory/Cache Y N Y

Memory/Installed Memory Y Y Y

Memory/Logical Memory N N N

Memory/Memory Modules Y N Y

Network/IP Address Y Y Y

Network/IPX Address Y N N

Network/Network Adapter Y N Y

OS Specific/Geographic Y Y N

OS Specific/LAN Network ID Y Y N

OS Specific/Lease N N N

OS Specific/Regional Y N N

Settings/Asset ID Y Y Y

Settings/Basic System Information Y Y Y

Settings/CIM N N N

Settings/Device Drivers Y N N


Table 39. Inventory tables (continued)

Inventory table Windows Linux 4690

Settings/Firmware Y Y Y

Settings/IP Address Y Y Y

Settings/IPX Address Y N N

Settings/Port Connectors Y N Y

Settings/System Y Y Y

Settings/Video Y N N

Settings/Retail Store Information Y Y Y

Settings/4690 Controller Properties N N Y

SMBIOS/Baseboard Y Y Y

SMBIOS/Component ID Y Y Y

SMBIOS/On Board Device Y N Y

SMBIOS/Physical Enclosure Y N Y

SMBIOS/Processor Y Y Y

SMBIOS/System BIOS Y Y Y

SMBIOS/System Board Configuration N N N

SNMP N N N

Storage/Disk Y Y N

Storage/Logical Drive Y Y Y

Storage/Partition Y Y Y

Storage/RAID Disk Drives N N N

Storage/RAID Logical Drives N N N

Storage/SMI-S Storage Device N N N

Software/4690 ASM Package Properties N N Y

Software/Device Drivers Y N N

Software/Installed Packages Y N N

Software/Operating System Y Y Y

Software/Software Y Y Y


Appendix C. UPOS Inventory Table Definitions

The following section outlines the tables that are defined for the UPOS inventoryinformation of each device. The peripheral information is categorized into threegroups of information, with each group representing a database table.

General Properties TableThe first table defined for each device is a general properties table. All devices willhave this table, which includes properties that are common to all peripheral devices.

Table 40. General properties table

UPOS Attribute UPOS Specification

PhysicalDeviceName Architecture

ModelName Statistics

Manufacturer Statistics

PhysicalDeviceDescription Architecture

DeviceServiceDescription Architecture

DeviceServiceVersion Architecture

DeviceControlDescription Architecture

DeviceControlVersion Architecture

SerialNumber Statistics

Interface Statistics

FirmwareRevision Architecture

PowerState Architecture

PowerNotify Architecture

ManufactureData Statistics

MechanicalRevision Statistics

InstallationDate Statistics

UnifiedPOSVersion Statistics

DeviceCategory Statistics

Note: The UPOS Specification column above indicates which specification theattribute information is defined.

Device Capabilities TablesThe second set of tables defined for each device is the capabilities tables, whichsupports all devices. The capabilities tables defines the capabilities of each device,and includes capabilities that are common for all device types and those capabilitiesthat are specific to that device. The following tables list the table definitions for eachdevice. If a device is not listed, it has no device specific capabilities and its tableconsists of only the five common ones.

Table 41. Cash Changer Device Capabilities Table


CapCompareFirmwareVersion Common


Table 41. Cash Changer Device Capabilities Table (continued)


CapUpdateFirmware Common

CapPowerReporting Common

CapStatisticsReporting Common

CapUpdateStatistics Common

CapDeposit Device Specific

CapDepositDataEvent Device Specific

CapNearEmptySensor Device Specific

CapEmptySensor Device Specific

CapNearFullSensor Device Specific

CapFullSensor Device Specific

CapPauseDeposit Device Specific

CapRepayDeposit Device Specific

CapDiscrepancy Device Specific

Table 42. Cash Drawer Device Capabilities Table







CapStatus Device Specific

CapStatusMultiDrawerDetect Device Specific

Table 43. Coin Dispenser Capabilities Table







CapNearEmptySensor Device Specific

CapEmptySensor Device Specific

CapJamSensor Device Specific

Table 44. Check Scanner Device Capabilities Table






Table 44. Check Scanner Device Capabilities Table (continued)




CapAutoSize Device Specific

CapColor Device Specific

CapImageFormat Device Specific

CapContrast Device Specific

CapAutoContrast Device Specific

CapValidationDevice Device Specific

CapMICRDevice Device Specific

CapConcurrentMICR Device Specific

CapAutoGenerateFileID Device Specific

CapImageTagData Device Specific

CapAutoGenerateImageTagData Device Specific

CapStoreImageFiles Device Specific

CapDefineCropArea Device Specific

Table 45. Fiscal Printer Device Capabilities Table







CapCoverSensor Device Specific

CapJrnPresent Device Specific

CapJrnNearEndSensor Device Specific

CapJrnEmptySensor Device Specific

CapRecPresent Device Specific

CapRecNearEndSensor Device Specific

CapRecEmptySensor Device Specific

CapSlpPresent Device Specific

CapSlpNearEndSensor Device Specific

CapSlpEmptySensor Device Specific

CapSlpFullSlip Device Specific

Table 46. Hard Totals Device Capabilities Table





Appendix C. UPOS Inventory Table Definitions 237

Table 46. Hard Totals Device Capabilities Table (continued)




CapErrorDetection Device Specific

CapTransactions Device Specific

CapSingleFile Device Specific

Table 47. Line Display Device Capabilities Table







CapScreenMode Device Specific

CapCursorType Device Specific

CapBlink Device Specific

CapBlinkRate Device Specific

CapBrightness Device Specific

CapReverse Device Specific

CapBitmap Device Specific

CapCustomGlyph Device Specific

CapDescriptors Device Specific

CapHMarquee Device Specific

CapVMarquee Device Specific

CapReadBack Device Specific

CapCharacterSet Device Specific

CapMapCharacterSet Device Specific

CapICharWait Device Specific

Table 48. MSR Device Capabilities Table







CapISO Device Specific

CapJISOne Device Specific

CapJISTwo Device Specific

CapTransmitSentinels Device Specific


Table 49. MICR Device Capabilities Table







CapValidationDevice Device Specific

Table 50. PIN Pad Capabilities Table







CapDisplay Device Specific

CapKeyboard Device Specific

CapLanguage Device Specific

CapMACCalculation Device Specific

CapTone Device Specific

Table 51. POS Keyboard Device Capabilities Table







CapKeyUp Device Specific

Table 52. POS Power Device Capabilities Table







CapBatteryCapacityRemaining Device Specific

CapFanAlarm Device Specific

CapHeatAlarm Device Specific

CapQuickCharge Device Specific


Table 52. POS Power Device Capabilities Table (continued)


CapRestartPOS Device Specific

CapShutdownPOS Device Specific

CapStandbyPOS Device Specific

CapSuspendPOS Device Specific

CapUPSChargeState Device Specific

CapVariableBatteryLowThreshold Device Specific

CapVariableBatteryCriticallyLowThreshold Device Specific

Table 53. Scale Device Capabilities Table







CapDisplay Device Specific

CapDisplayText Device Specific

CapPriceCalculating Device Specific

CapStatusUpdate Device Specific

CapTareWeight Device Specific

CapZeroScale Device Specific

Table 54. Tone Indicator Device Capabilities Table







CapPitch Device Specific

CapVolume Device Specific

Table 55. POS Printer General Device Capabilities Table

UPOS Attribute UPOS Specication






CapCoverSensor Device Specific


Table 55. POS Printer General Device Capabilities Table (continued)

UPOS Attribute UPOS Specication

CapConcurrentJrnRec Device Specific

CapConcurrentJrnSlp Device Specific

CapConcurrentRecSlp Device Specific

CapConcurrentPageMode Device Specific

CapCharacterSet Device Specific

CapMapCharacterSet Device Specific

Table 56. POS Printer Journal Station Capabilities Table


CapJrnPresent Device Specific

CapJrnNearEndSensor Device Specific

CapJrnEmptySensor Device Specific

CapJrnCartridgeSensor Device Specific

CapJrnColor Device Specific

CapJrn2Color Device Specific

CapJrnBold Device Specific

CapJrnItalic Device Specific

CapJrnUnderline Device Specific

CapJrnDhigh Device Specific

CapJrnDwide Device Specific

CapJrnDwideDhigh Device Specific

Table 57. POS Printer Receipt Station Capabilities Table


CapRecPresent Device Specific

CapRecNearEndSensor Device Specific

CapRecEmptySensor Device Specific

CapRecCartridgeSensor Device Specific

CapRecPaperCut Device Specific

CapRecStamp Device Specific

CapRecPageMode Device Specific

CapRecMarkFeed Device Specific

CapRecColor Device Specific

CapRec2Color Device Specific

CapRecBold Device Specific

CapRecItalic Device Specific

CapRecUnderline Device Specific

CapRecDhigh Device Specific

CapRecDwide Device Specific

CapRecDwideDhigh Device Specific


Table 57. POS Printer Receipt Station Capabilities Table (continued)


CapRecBarCode Device Specific

CapRecBitmap Device Specific

CapRecLeft90 Device Specific

CapRecRight90 Device Specific

CapRecRotate180 Device Specific

Table 58. POS Printer Slip Station Capabilities Table

CIM Attribute UPOS Specification

CapSlpPresent Device Specific

CapSlpNearEndSensor Device Specific

CapSlpEmptySensor Device Specific

CapSlpCartridgeSensor Device Specific

CapSlpBothSidesPrint Device Specific

CapSlpFullSlip Device Specific

CapSlpPageMode Device Specific

CapSlpColor Device Specific

CapSlp2Color Device Specific

CapSlpBold Device Specific

CapSlpItalic Device Specific

CapSlpUnderline Device Specific

CapSlpDhigh Device Specific

CapSlpDwide Device Specific

CapSlpDwideDhigh Device Specific

CapSlpBarCode Device Specific

CapSlpBitmap Device Specific

CapSlpLeft90 Device Specific

CapSlpRight90 Device Specific

CapSlpRotate180 Device Specific

Device Properties TablesThe third set of tables defined for each device is the properties tables. Not alldevices will have this table, which defines the properties of the device. All propertiesin this table are specific to that device. The following tables list the table definitionsfor each device that has a properties table. If a device is not listed, that indicates ithas no device specific properties.

Table 59. Cash Changer Device Properties Table


DeviceStatus Device

FullStatus Device

DeviceExits Device


Table 59. Cash Changer Device Properties Table (continued)


CurrencyCode Device

CurrencyCashList Device

CurrencyCodeList Device

DepositCashList Device

DepositCodeList Device

AsyncMode Device

Table 60. Cash Drawer Device Properties Table


DrawerOpened Device

Table 61. Check Scanner Device Properties Table


ImageFormat Device

Color Device

Quality Device

QualityList Device

MaxCropAreas Device

ConcurrentMICR Device

RemainingImagesEstimate Device

ImageMemoryStatus Device

MapMode Device

Contrast Device

Table 62. Coin Dispenser Device Properties Table


DispenserStatus Device

Table 63. Fiscal Printer Device Properties Table


CountryCode Device

JrnNearEnd Device

JrnEmpty Device

RecNearEnd Device

RecEmpty Device

SlpNearEnd Device

SlpEmpty Device

Table 64. Line Display Device Properties Table


ScreenMode Device


Table 64. Line Display Device Properties Table (continued)


Rows Device

Columns Device

BlinkRate Device

GlyphHeight Device

GlyphWidth Device

CustomGlyphList Device

ScreenModeList Device

CharacterSet Device

CharacterSetList Device

DeviceBrightness Device

DeviceDescriptors Device

DeviceWindows Device

DeviceRows Device

DeviceColumns Device

MaximumX Device

MaximumY Device

Table 65. Hard Totals Device Properties Table


TotalsSize Device

Table 66. Keylock Device Properties Table


KeyPosition Device

PositionCount Device

Table 67. MSR Device Properties Table


DecodeData Device

ParseDecodeData Device

TracksToRead Device

TransmitSentinels Device

ErrorReportingType Device

Table 68. PIN Pad Device Properties Table


MinimumPINLength Device

MaximumPINLength Device

AvailableLanguagesList Device

AvailablePromptsList Device


Table 68. PIN Pad Device Properties Table (continued)


TerminalID Device

Table 69. POS Keyboard Device Properties Table


EventTypes Device

POSKeyData Device

POSKeyEventType Device

Table 70. POS Power Device Properties Table


UPSChargeState Device

PowerSource Device

BatteryCapacityRemaining Device

BatteryLowThreshold Device

BatteryCriticallyLowThreshold Device

QuickChargeMode Device

PowerFailDelayTime Device

EnforcedShutdownDelayTime Device

Table 71. Scale Device Properties Table


MaxDisplayTextChars Device

MaximumWeight Device

WeightUnit Device

Table 72. POS Printer Device Properties Table


CoverOpen Device

MapMode Device

CartridgeNotify Device

CharacterSet Device

CharacterSetList Device

MapCharacterSet Device

FontTypefaceList Device

PageModeDescriptor Device

PageModeArea Device

Table 73. POS Printer Journal Station Properties Table


JrnNearEnd Device

JrnEmpty Device


Table 73. POS Printer Journal Station Properties Table (continued)


JrnCurrentCartridge Device

JrnCartridgeState Device

JrnLetterQuality Device

JrnLineHeight Device

JrnLineWidth Device

JrnLineSpacing Device

JrnLineChars Device

JrnLineCharsList Device

Table 74. POS Printer Receipt Station Properties Table


RecNearEnd Device

RecEmpty Device

RecCurrentCartridge Device

RecCartridgeState Device

RecLetterQuality Device

RecLineHeight Device

RecLineWidth Device

RecLineSpacing Device

RecLineChars Device

RecLineCharsList Device

RecSidewaysMaxChars Device

RecSidewaysMaxLines Device

Table 75. POS Printer Slip Station Properties Table


SlpNearEnd Device

SlpEmpty Device

SlpCurrentCartridge Device

SlpCartridgeState Device

SlpLetterQuality Device

SlpLineHeight Device

SlpLineWidth Device

SlpLineSpacing Device

SlpLineChars Device

SlpLineCharsList Device

SlpSidewaysMaxChars Device

SlpSidewaysMaxLines Device


Table 76. Retail Display Properties Table


BacklightState Device

CurrentBrightnessLevel Device

CurrentVideoSource Device

DisplayTechnology Device

HorizontalResolution Device

HorizontalScreenSize Device

LightSourceCount Device

LightSourceIlluminationType Device

LightSourceType Device

PreferredResolutionAndRefreshRate Device

RecommendedBrightnessLevel Device

RefreshRate Device

ScanMode Device

SupportedResolutionsAndRefreshRates Device

SupportedVideoSources Device

SupportsColor Device

VerticalResolution Device

VerticalScreenSize Device


Appendix D. JMX Browser Plug-Ins

For V2R2 or earlier: JMX Browser plug-ins are custom components that plug intothe JMX Browser to enhance or limit the functionality. For RMA, there are currentlytwo special plug-ins that help simplify use of the designated JMX instances: theMonitor Manager and the RMA Software Package Distributor plug-ins.

The creation of JMX monitors has been replaced with integration into IBM Directormonitoring. Configuration of the RMASWPackageDistributorMBean is only required fordistributing software to agents prior to V2R2.

Create a JMX Monitor PolicyA monitor policy can be created in one of the following ways. From the JMXbrowser screen (shown in Figure 119) :

v Right-click in the Object Tree panel on an instance or group and select theCreate Monitor menu option.

v Right-click in the Instance panel on an attribute displayed in the Properties taband select Create Monitor.

This will start the Monitor Policy Wizard, a dialog to assist with creating monitorpolicies.

Monitor Policy WizardThe purpose of the Monitor Policy Wizard (as shown in Figure 120 on page 250) isto aid in the creation and modification of policies for the Monitor Manager. TheMonitor Policy Wizard contains two pages in the creation of the policy. The firstpage helps to collect the data required to create the policy, and the second pagecontains advanced options that can be set for the monitor policy.

Figure 119. Create Monitor menu option from the Instance panel


The first page of the wizard contains all the main settings for the policy.

DescriptionSpecifies the name of the policy.

Mbean ClassSpecifies the name of the class of MBean that the policy is to be gearedtowards. When selecting the MBean Class, there is a class of MBean calledCIMProxyMBean. This kind of bean has a special field that is displayed whenselected. This field is CIM Class, where you will specify the type of CIMClass to be monitored. After selecting the CIM Class or after selecting anon-CIMProxyMBean bean, the MBean field is ready.

MbeanSpecifies a specific MBean or you can select the '*' to mean any MBean.Following the selection of the MBean, select the attribute.

AttributeMonitors a specific attribute of an MBean. By selecting an attribute, you cannarrow down the type of monitor policy to create, which will be visible in thenext drop-down field, which is the monitor type field.

Initial Threshold NumberIndicates the specific fields needed by the selected monitor type.

After you complete the fields in Figure 120, click Finish to save the policy. To selectadvanced options, click Next to continue to the next page.

If you check Apply policy when finished, the Apply Monitor Policy dialog isdisplayed.

Figure 120. Monitor Policy Wizard


Counter Monitor advanced optionsThere are three advanced options for the Counter Monitor (Figure 121). Theseoption are not the same for all the monitor types, so complete these carefully. Thedefault values are entered for you.

Granularity PeriodSpecifies the frequency in which the monitor will check for changes.

Offset NumberSpecifies to the monitor the value to be added to the monitor's thresholdafter the observed attribute exceeds the current threshold value.

Modulus NumberSpecifies to the monitor what the counter's maximum value can be beforerolling over to 0.

Gauge Monitor advanced optionsThere are three advanced options for the Gauge Monitor (as shown in Figure 122on page 252):

Notify HighNotifies the monitor to generate an event when the value being monitoredchanges and becomes higher than the range entered in the high and lowthresholds.

Notify LowNotifies the monitor to generate an event when the value being monitoredchanges and becomes lower than the range entered in the high and lowthresholds.


Figure 121. Counter Monitor Advanced Options panel

Appendix D. JMX Browser Plug-Ins 251

String Monitor advanced optionsThere are three advanced options for the String Monitor (as shown in Figure 123 onpage 253):

Notify MatchNotifies the monitor to generate an event when the value being monitoredchanges and it matches the compare string.

Notify DifferNotifies the monitor to generate an event when the value being monitoredchanges and it does not match the value being compared.


Figure 122. Gauge Monitor Advanced Options panel


Boolean Monitor advanced optionsThere are three advanced options for the Boolean Monitor (as shown in Figure 124on page 254):

Notify TrueNotifies the monitor to generate an event when the value being monitoredchanges and it is equal to True.

Notify FalseNotifies the monitor to generate an event when the value being monitoredchanges and it is equal to False.

Granularity PeriodSpecifies the frequency in which the monitor will check for changes to thevalue.

Figure 123. String Monitor Advanced Options panel


Apply Monitor Policy dialogClicking Apply opens the Apply Monitor Policy dialog (as shown in Figure 125 onpage 255). You must choose the target to which to apply to the monitor:

Device TypeApplies the monitor to all systems of a specific device type, which is thedefault. If you select this option, you must also must select a TargetIdentifier from the drop-down list, indicating the device type.

Individual DeviceApplies the monitor to all agents on a specific target system. If you selectthis option, you must also select a Target Identifier from the drop-down list,indicating the name of the device.

Individual AgentApplies the monitor to a specific agent on a specific target system. Ifselected, you also must select a Target Identifier from the drop-down list,indicating the device name and port.

Figure 124. Boolean Monitor Advanced Options panel


After you select the target type and chose the target identifier, click Apply tocomplete the application of the monitor policy to the chosen system or systems.

Monitor Manager plug-inThe Monitor Manager plug-in provides a way to apply a Monitor Policy instance andregister it to a group of devices. To access the Monitor Manager Plug-in:

v Invoke the JMX Browser task on one or more Master Agent managed objects.

v Expand the MGMT category branch and select the MonitorManager MBean

Use the panels of the Monitor Manager to do the following:

v Edit policies

v Apply policies

v Delete policies

These tasks are performed using the supplied buttons in the plug-in. In the MonitorManager plug-in, there are two tabs. The first tab, Policies, displays all the policieson the Managed Objects. The Applied Policies tab shows all the policies that havebeen applied.

Policies tabThe Policies tab provides a table that is used to display all policies. The tabledisplays the name of the policy and the ID of the monitor bean that it isrepresenting (as shown in Figure 126 on page 256).

Figure 125. Apply Monitor Policy frame


On the Policies tab, you can manage all policies:

v Click Edit to modify the selected policy. If more than one policy is selected, theEdit button is disabled, because only one policy can be edited at a time

v Click Apply to commit to all selected policies in the Policies tab. Clicking Applyopens the Apply Monitor Policy dialog. See “Apply Monitor Policy dialog” on page254 for more information.

v Click Delete to remove all selected policies.

The Apply and the Delete buttons are the only two buttons that are enabled whenmultiple policies are selected.

Applied Policies tabOn the Applied Policies tab (Figure 127), you can manage all of the applied policies.The description of the policy is displayed, along with the target type and identifier ofthe objects for which this policy was intended.

v Click Edit to view and change the properties of the selected policy.

v Click Delete to remove the selected policies.

Figure 126. Policies tab

Figure 127. Applied Policies tab


Notices

References in this publication to IBM products, programs, and services do not implythat IBM intends to make these available in all countries in which IBM operates. Anyreference to an IBM product, program, or service is not that only IBM's product,program, or service can be used. Any functionally equivalent product, program, orservice that does not infringe any of IBM's intellectual property rights can be usedinstead of the IBM product, program, or service. Evaluation and verification ofoperation in conjunction with other products, except those expressly designated byIBM, are the user's responsibility.

IBM might have patents or pending patent applications covering the subject matterin this document. The furnishing of this document does not give you any license tothese patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

The following paragraph does not apply to the United Kingdom or any other countrywhere such provisions are inconsistent with local law: INTERNATIONAL BUSINESSMACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUTWARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUTNOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. Some statesdo not allow disclaimer of express or implied warranties in certain transactions,therefore, this statement might not apply to you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM might make improvementsand/or changes in the product(s) and/or program(s) described in this publication atany time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of thoseWeb sites. The materials at those Web sites are not of the materials for this IBMproduct and use of those Web sites is at your own risk.

Information concerning non-IBM products was obtained from the suppliers of thoseproducts, their published announcements or other publicly available sources. IBMhas not tested those products and cannot confirm the accuracy of performance,compatibility or any other claims related to non-IBM products. Questions on thecapabilities of non-IBM products should be addressed to the suppliers of thoseproducts.

This product includes software developed by the MX4J project(mx4j.sourceforge.net) and by the Apache Software Foundation (www.apache.org/).

TrademarksIBM, ThinkVantage, Tivoli, Wake on LAN, and WebSphere are trademarks ofInternational Business Machines in the United States or other countries, or both.


http://mx4j.sourceforge.net

http://www.apache.org/

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. inthe United States or other countries, or both.

Microsoft, Windows and the Windows logo are trademarks of Microsoft Corporationin the United States or other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, or both.


Index

Numerics4690 OS installation 30

Aaccessing General Agent MBeans 208accessing MBean instrumentation 208advanced options

boolean monitor 253counter monitor 251gauge monitor 251string monitor 252

agent application roles 155agent class path and environment 46agent configuration 41, 51agent configuration file 41agent JVM diagnostics 143agent properties 41agent roles 52agent startup sequence 50agent Windows event log integration 52AgentStartupMBean 51architecture 147architecture, understanding 153associated policy manager

invoking associated subtasks 134associations 65attributes, managed objects 64

Bbest practices 228boolean monitor advanced options 253

Ccapture bundle directory 191capture completion notifications

receiving 221capture file processing 193capture file transfer 192capture history cleanup 193capture history information 193capture policy application 191capture processing 186CaptureAgentRecords 221CaptureInstanceRecords 221CapturePolicyInvocationRecords 221capturing data 185CD-ROM xviCHXI 199CIM Adapter MBean 164CIM configuration 167CIMEventMapper interface 165class

RMAfile 199client configuration 162

coding best practices 228common properties 215component JVM registration 202components, description 154configuration

CIM 167configuration, agent 41configuration, client 162configuration, logging 162configuration, security 43configuration, SSL 44content, software policy 181conventions xvicounter monitor advanced options 251

Ddata

capturing 185data capture 184data capture implementations

deleting 131data capture policies 131

associating 132capture bundle

retrieving 137deleting from capture history 136managing 219manipulating associated 133refreshing displayed capture history 135removing associations 134status frame 134viewing associated 132viewing capture history 135

data capture policy 188activating 219adding 219creating 219deleting 222terminating 222

data capture policy managerdata capture implementations

adding 129creating 129editing 130removing 129right pane 129

data capture implementations Pane (rightpane) 129

data capture policy 124creating 123deleting 124finding in tree 127renaming 123

Data Capture Policy Groupcreating 121deleting 122renaming 122


data capture policy manager (continued)data collection 118device types

adding 127removing 127

device types pane (center pane) 129exporting policies to file 125file menu 119help menu 121importing policies from file 126menu bar 119policies pane (left pane) 121policy group

moving 124removing 124

tasks 117Data Capture Policy Manager task 66data capture properties 43DataCaptureManagerMBean 189DataCaptureMBean 185DataCaptureMBeanSupport 187DataCapturePolicy class 190delete package 93Deploying package 94deployment scenarios overview 9destination directory, OS settings 82development environment 197device capabilities tables 235device properties tables 242diagnostic data capture overview 6Director Console 60disciplines, RMA 149disconnect() 216discovery 67Discovery Preferences panel 67distributing the MBean classes 204distribution, software 78draft policies

activating 225registering 223

dynamic groups 62

EEdit Package 93Editing a software package 80editor, software package 79Embedded Agent 153error log entry contents 230error log output 229error logging 228event action plans 75event fetching properties (Master Agent only) 43event infrastructure, RMA 159event log 75event properties 42EventControlMBean 161events overview 5examples, programming 199executable commands, OS settings 83export package 94

extensions, IBM Director 59extensions, installing 33extrinsic event registrations 166

Ffile transfer 95, 168file transfer error handling 193file transfer implementations 170file transfer overview 6files

RMAfile class 199files, OS settings 82FileTransferConnection 169FileTransferConnection interface

FileTransferConnection interface, using 214forwarding, log 162FTPConnection properties 215FTPSConnection properties 216

Ggauge monitor advanced options 251General Agent 153, 154General Agent MBeans, accessing 208General Agent service registration 203general properties table 235Getting package files to the Master Agent 175Groups 60groups, security 19guide, using xv

Hhandler levels

adjusting using JMX Browser 102hardware requirements 17health checking 154

IIBM Director

events per minute 144troubleshooting 144

high log collection 144JVM diagnostics 145log collection settings 144RAS logging 144

IBM Director Console 60IBM Remote Management Agent xv, 149import file format table 70import package 93importing, threshold plans 113in-store processor 17indications

MSStorageDriver_FailurePredictEvent 166RSS_SpNumericSensorAlert 166UPOS 166

infrastructure overview 7infrastructure, event 159


installation 21, 33CD 21interactive 21Linux 27, 29

installation procedureinteractive 21

installation roles, IBM Director 18installation, SFCB 27, 28installing 21installing extensions 33installing IBM Director extensions 59installing Remote Management Agent 13instance panel

methods 98Instance panel 97

properties 97interactive installation 27interactive installation procedure 29interactive installation, Linux 34interactive installation, Windows 33interactive uninstallation

procedure 37introducing Remote Management Agent 1inventory 74, 163inventory collection 74inventory overview 6inventory tables

inventory tables, RMA 233inventory, viewing 74invocation history

querying 221

JJAR files 197Java 2 requirements 17Java class path 46JAVA Management Extensions 149Javadoc pdf file 231JMX Browser 95JMX Browser task 66JMX connection, remote

Master Agent, making a remote JMXconnection 204

JMX tree panel 96

LLinux uninstallation

procedure 39locating agent MBeans 209log directories 143log forwarding 162log, event 75logging APIs 229logging configuration 47, 162logging levels 48, 228

adjusting using JMX Browser 102logging parameters 49

Mmaking a remote JMX connection to the Master

Agent 204managed object attributes 64managed object groups 60Managed Object groups 61managed object states 64managed object types 63managed objects 62management agent discovery 154management interface, exposing 199Management model 151Master Agent 153, 154Master Agent, adding 67Master Agent, editing 69Master Agent, exporting list 71Master Agent, importing list 69Master Agent, removing 69MBean instrumentation, accessing 208MBean object naming 200MBean registration 202MBeans

registering 199writing 199

MBeans, locating agent MBeans 209method execution dialog 99MgmtClientHealthMBean 154MgmtMasterHealthMBean 154MgmtNotificationControlMBean 162Mid-level management 150monitor manager plug-in 255monitor policies, managing 218monitor policy

creating 249wizard 249

Monitor policy 171monitor policy dialog

applying 254monitor policy wizard 249monitoring overview 6MonitorPolicy object 218MonitorPolicyAction 218MSStorageDriver_FailurePredictEvent indications 166

Nnotices 257notification listeners 210notification processor

using 211NotificationProcessor 162notifications

progress 224retrieving 210state 224SystemStateChange 227SystemStateChangeListener 227

Index 261

Oobject naming, MBean 200objectives 147operating system settings 81Outer tags and attributes 181overview 149overview, deployment scenarios 9overview, diagnostic data capture 6overview, events 5overview, file transfer 6overview, infrastructure 7overview, inventory 6overview, monitoring 6overview, power management 5overview, retail peripheral management 6overview, RMA 5overview, software distribution 5

Ppackage creation 85package creation for update 31package editor, software 79package general information 80package JAR file format 175package staging 176Package Wizard 80Peripheral Type, description 115plug-ins

monitor manager 255Policy invocation 192policy invocation history 225policy invocation status 225policy XML variables 184post capture file processing 192post capture file transfer 192post installation

Linux 29Windows 26

post-distribution action, OS settings 85power management 138power management overview 5problem determination

solutions 146symptoms 146

problem symptoms 146product

overview 149programming 195programming examples 199programming IBM Remote Management Agent 199progress notifications 224publications, related xvi

RRAS log collection 144registration, MBean 202related xvirelated publications and diskettes xvi

Remote Management Agent, installing 13Remote Management Agent, introducing 1Remote Management Agent, using 13Remote Management General Agent 21Rename Package 93resource monitors 103

threshold monitor 104, 108retail devices 63Retail Extensions for IBM Director uninstallation

notes 39Retail Extensions silent installation 35retail peripheral management 113

console 114retail peripheral management overview 6Retail Peripheral Management task 66retries 193RMA data capture

policy invocationinvoking 137

RMA events 160RMA overview 5RMA package distributor MBean 174RMA Software Distribution 172RMA Software Distribution task 66RMADataCaptureMBean 189RMAfile class 199RMI Properties 42roles, agent 52RSS_SpNumericSensorAlert indications 166RtlNotifications 160

SSecurity configuration 43security groups 19security modes 19setting up development environment 197severity mapping 78SFCB installation 27, 28silent installation 30silent uninstallation

procedure 38software distribution 78Software Distribution 4690 Command Wizard 87software distribution overview 5software distribution policies 222Software Distribution Policy 178software distribution, RMA 172software package creation 85software package editor 79software package, editing 80software policy

deleting 226terminating 226

software policy content 181software policy target device content 182Software Policy XML file structure 180software requirements 17SSL configuration 44starting Discovery 71state notifications 224


states, managed object 64Storage 171Store Authorization Management task 66, 72store events

retrieving 210Store Integration Framework 154string monitor advanced options 252subtasks, software package 87

delete package 93Deploying package 94Edit Package 93export package 94import package 93Rename Package 93

summary of changes xixsupported operating systems 17SystemStateChange

SystemStateChange 227SystemStateChangeListener 227

SystemStateChangeListener 227SystemStateHandler 227SystemStateManager 227

Ttasks 65threshold plans, importing 113trademarks 257Transfer progress 217Transfer types 216troubleshooting 143

logs 143problem 143solution 143

Uuninstallation 37uninstallation notes, Retail Extensions for IBM

Director 39uninstallation result 39uninstallation, Linux 39uninstallation, silent 38updating RMA 30UPOS 113UPOS indications 166UPOS inventory tables

inventory tables, UPOS 235user-defined monitors 110using JMX Browser 102using Remote Management Agent 13

Vviewing inventory 74

WWeb site xviWindows event log integration, agent 52

Windows installation 21Windows PATH 47wizard, package 80writing MBeans 199

XXML variables, policy 184

Zzip files 197

Index 263

Readers’ Comments — We'd Like to Hear from You

Remote Management AgentUser's GuideVersion 2 Release 6

Publication No. GC30-4106-10

We appreciate your comments about this publication. Please comment on specific errors or omissions, accuracy,organization, subject matter, or completeness of this book. The comments you send should pertain to only theinformation in this manual or product and the way in which the information is presented.

For technical questions and information about products and prices, please contact your IBM branch office, your IBMbusiness partner, or your authorized remarketer.

When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in anyway it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use thepersonal information that you supply to contact you about the issues that you state on this form.

Comments:

Thank you for your support.

Send your comments to the address on the reverse side of this form.

If you would like a response from IBM, please fill in the following information:

Name Address

Company or Organization

Phone No. Email address

Readers’ Comments — We'd Like to Hear from YouGC30-4106-10

GC30-4106-10

��Cut or FoldAlong Line

Cut or FoldAlong Line

Fold and Tape Please do not staple Fold and Tape

Fold and Tape Please do not staple Fold and Tape

NO POSTAGENECESSARYIF MAILED IN THEUNITED STATES

BUSINESS REPLY MAILFIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK

POSTAGE WILL BE PAID BY ADDRESSEE

IBM CorporationRetail Store Solutions Information Development, Dept ZBDAP. O. Box 12195RESEARCH TRIANGLE PARK NC 27709-9990

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

__

_

��

Program Number: 5639-FF1

GC30-4106-10

ibm rma userguide

Documents