IBM RMA Userguide

Remote Management Agent
User's Guide
Version 2 Release 6
GC30-4106-10
User's Guide
Version 2 Release 6
GC30-4106-10
Note
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
257.
| August 2010
| This edition applies to Version 2 Release 6 of the licensed program IBM Remote Management Agent (program
| number 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 at
| www.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, address
| your comments to:
| IBM Corporation
| Retail Store Solutions Information Development
| Department ZBDA
| PO Box 12195
| Research Triangle Park, North Carolina 27709 USA
| When you send information to IBM, you grant IBM a nonexclusive right to use or distribute whatever information you
| supply 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 Contract
with IBM Corp.
Contents
Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
About this guide . . . . . . . . . . . . . . . . . . . . . . . . xv

Who should read this guide . . . . . . . . . . . . . . . . . . . . xv
How this guide is organized . . . . . . . . . . . . . . . . . . . . xv
Conventions used in this guide . . . . . . . . . . . . . . . . . . . xvi
Related publications . . . . . . . . . . . . . . . . . . . . . . . xvi
Providing feedback . . . . . . . . . . . . . . . . . . . . . . . xvii
Summary of changes . . . . . . . . . . . . . . . . . . . . . . xix

| Web-only update of GC30-4106-09 . . . . . . . . . . . . . . . . . xix
Web-only update of GC30-4106-08 . . . . . . . . . . . . . . . . . xix
Web-only update of GC30-4106-05 . . . . . . . . . . . . . . . . . xx
Web-only update of GC30-4106-04 . . . . . . . . . . . . . . . . . xx
Part 1. Introducing IBM Remote Management Agent . . . . . . . . . . . . . . 1
Chapter 1. Retail systems management . . . . . . . . . . . . . . . 3

The need for systems management. . . . . . . . . . . . . . . . . . 3
The importance of standards . . . . . . . . . . . . . . . . . . . . 4
Management solutions . . . . . . . . . . . . . . . . . . . . . . 4
Chapter 2. RMA Overview . . . . . . . . . . . . . . . . . . . . . 5

Power management . . . . . . . . . . . . . . . . . . . . . . . 5
Events Management . . . . . . . . . . . . . . . . . . . . . . . 5
Software distribution . . . . . . . . . . . . . . . . . . . . . . . 5
Inventory and Asset tracking . . . . . . . . . . . . . . . . . . . . 6
Monitoring Retail Systems . . . . . . . . . . . . . . . . . . . . . 6
Diagnostic data capture . . . . . . . . . . . . . . . . . . . . . . 6
Retail peripheral management . . . . . . . . . . . . . . . . . . . . 6
File transfer . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 3. Infrastructure components . . . . . . . . . . . . . . . . 7
Chapter 4. Deployment scenarios. . . . . . . . . . . . . . . . . . 9

Small enterprise scenario . . . . . . . . . . . . . . . . . . . . . 10
Medium enterprise scenario . . . . . . . . . . . . . . . . . . . . 11
Large enterprise scenario . . . . . . . . . . . . . . . . . . . . . 11
Part 2. Installing and using the IBM Remote Management Agent . . . . . . . . 13
Chapter 5. RMA Requirements . . . . . . . . . . . . . . . . . . 17

Hardware requirements . . . . . . . . . . . . . . . . . . . . . . 17
Software requirements . . . . . . . . . . . . . . . . . . . . . . 17
Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Supported operating systems . . . . . . . . . . . . . . . . . . 17
IBM Director . . . . . . . . . . . . . . . . . . . . . . . . . 18
Installation roles . . . . . . . . . . . . . . . . . . . . . . . 18
© Copyright IBM Corp. 2004, 2010 iii

Network Configuration Requirements . . . . . . . . . . . . . . . . 18
| Chapter 6. Understanding RMA Security . . . . . . . . . . . . . . 19

| Master Agent Security Modes . . . . . . . . . . . . . . . . . . . 19
| Installation and upgrades . . . . . . . . . . . . . . . . . . . . 19
| Security groups. . . . . . . . . . . . . . . . . . . . . . . . 19
| General Agent Security . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 7. Installing the Remote Management General Agent and Master

Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Interactive installation on Windows . . . . . . . . . . . . . . . . . 21
Installation procedure . . . . . . . . . . . . . . . . . . . . . 21
Interactive installation on Linux . . . . . . . . . . . . . . . . . . . 27
Linux prerequisites . . . . . . . . . . . . . . . . . . . . . . 27
Small Footprint CIM Broker . . . . . . . . . . . . . . . . . . . 27
Silent installation of the Remote Management Agent on Windows . . . . . . 30
4690 OS installation . . . . . . . . . . . . . . . . . . . . . . . 30
Updating RMA . . . . . . . . . . . . . . . . . . . . . . . . . 30
Package import. . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 8. Installing Retail Extensions for IBM Director . . . . . . . . 33

Interactive installation for Windows . . . . . . . . . . . . . . . . . 33
Interactive installation for Linux . . . . . . . . . . . . . . . . . . . 34
Silent installation of the Retail Extensions for IBM Director for Windows and
Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 9. Uninstalling IBM Remote Management Agent . . . . . . . . 37

Interactive uninstallation for Windows . . . . . . . . . . . . . . . . 37
Silent uninstallation for Windows . . . . . . . . . . . . . . . . . . 38
Uninstallation for Linux . . . . . . . . . . . . . . . . . . . . . . 39
Uninstallation result . . . . . . . . . . . . . . . . . . . . . . . 39
Retail Extensions for IBM Director uninstallation notes . . . . . . . . . . 39
Chapter 10. Agent configuration . . . . . . . . . . . . . . . . . . 41

Directory structure. . . . . . . . . . . . . . . . . . . . . . . . 41
Agent configuration file . . . . . . . . . . . . . . . . . . . . . 41
Security configuration . . . . . . . . . . . . . . . . . . . . . 43
SSL configuration . . . . . . . . . . . . . . . . . . . . . . . 44
Updating SSL certificates . . . . . . . . . . . . . . . . . . . . 45
Agent class path and environment . . . . . . . . . . . . . . . . . 46
Logging configuration . . . . . . . . . . . . . . . . . . . . . 47
Agent startup sequence . . . . . . . . . . . . . . . . . . . . 50
Agent roles . . . . . . . . . . . . . . . . . . . . . . . . . 52
Agent Windows event log integration . . . . . . . . . . . . . . . . 52
Chapter 11. Using Retail Extensions for IBM Director . . . . . . . . . 59

IBM Director Console . . . . . . . . . . . . . . . . . . . . . . 60
Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Managed Objects . . . . . . . . . . . . . . . . . . . . . . . 62
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Discovery Preferences panel . . . . . . . . . . . . . . . . . . . 67
Starting Discovery. . . . . . . . . . . . . . . . . . . . . . . 71
Store Authorization Management task . . . . . . . . . . . . . . . . 72
Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
iv RMA V2R6 User's Guide

Inventory collection . . . . . . . . . . . . . . . . . . . . . . 74
Viewing inventory . . . . . . . . . . . . . . . . . . . . . . . 74
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Event log . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Event action plans . . . . . . . . . . . . . . . . . . . . . . 75
RMA Software Package Editor . . . . . . . . . . . . . . . . . . 79
Editing a software package . . . . . . . . . . . . . . . . . . . 80
RMA Software Distribution 4690 Command Wizard . . . . . . . . . . 87
Software package subtasks . . . . . . . . . . . . . . . . . . . 93
RMA File Transfer task . . . . . . . . . . . . . . . . . . . . . . 95
Task invocation . . . . . . . . . . . . . . . . . . . . . . . . 95
JMX Browser task. . . . . . . . . . . . . . . . . . . . . . . . 95
JMX tree panel . . . . . . . . . . . . . . . . . . . . . . . . 96
Instance panel . . . . . . . . . . . . . . . . . . . . . . . . 97
Method Execution dialog . . . . . . . . . . . . . . . . . . . . 99
Adjusting the handler and logger levels using JMX Browser . . . . . . . . 102
Resource Monitors . . . . . . . . . . . . . . . . . . . . . . . 103
Creating a Threshold Monitor . . . . . . . . . . . . . . . . . . 104
Creating a Recording Monitor . . . . . . . . . . . . . . . . . . 108
User-Defined Monitors . . . . . . . . . . . . . . . . . . . . . . 110
Importing threshold plan files . . . . . . . . . . . . . . . . . . . 113
Retail Peripheral Management . . . . . . . . . . . . . . . . . . . 113
Retail Peripheral Management Console . . . . . . . . . . . . . . 114
Data Capture Policy Manager task . . . . . . . . . . . . . . . . . 117
Data Capture Policy Manager . . . . . . . . . . . . . . . . . . 118
Data Capture Policies . . . . . . . . . . . . . . . . . . . . . 131
Status Frame for Data Capture Policies . . . . . . . . . . . . . . 134
Power management . . . . . . . . . . . . . . . . . . . . . . 138
Chapter 12. Troubleshooting. . . . . . . . . . . . . . . . . . . 143

Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
RMA Agents . . . . . . . . . . . . . . . . . . . . . . . . 143
Agent JVM Diagnostics . . . . . . . . . . . . . . . . . . . . 143
IBM Director . . . . . . . . . . . . . . . . . . . . . . . . 144
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . 146
Part 3. Objectives and architecture . . . . . . . . . . . . . . . . . . . . . 147
Chapter 13. Architecture overview and objectives . . . . . . . . . . 149

IBM Remote Management Agent disciplines. . . . . . . . . . . . . . 149
Java Management Extensions . . . . . . . . . . . . . . . . . . . 149
Mid-level management . . . . . . . . . . . . . . . . . . . . . 150
Management model. . . . . . . . . . . . . . . . . . . . . . . 151
Chapter 14. Understanding the architecture . . . . . . . . . . . . . 153

RMA Component. . . . . . . . . . . . . . . . . . . . . . . . 153
General Agent. . . . . . . . . . . . . . . . . . . . . . . . 153
Master Agent . . . . . . . . . . . . . . . . . . . . . . . . 153
Component's relationship and roles . . . . . . . . . . . . . . . . . 154
Agent discovery and health checking . . . . . . . . . . . . . . . . 154
MgmtMasterHealthMBean . . . . . . . . . . . . . . . . . . . 154
MgmtClientHealthMBean . . . . . . . . . . . . . . . . . . . . 154
Agent application roles . . . . . . . . . . . . . . . . . . . . 155
| Embedded Agent (General Agent) . . . . . . . . . . . . . . . . . 156
| Proxy ObjectNames . . . . . . . . . . . . . . . . . . . . . 157
Contents v
| JMX Browser Changes for Local Mode Embedded Agents . . . . . . . 158
RMA event infrastructure . . . . . . . . . . . . . . . . . . . . . 159
RMA events (RtlNotifications) . . . . . . . . . . . . . . . . . . 160
EventControlMBean . . . . . . . . . . . . . . . . . . . . . 161
NotificationProcessor . . . . . . . . . . . . . . . . . . . . . 162
MgmtNotificationControlMBean . . . . . . . . . . . . . . . . . 162
Logging configuration and forwarding . . . . . . . . . . . . . . . . 162
Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . 163
CIM Implementation . . . . . . . . . . . . . . . . . . . . . . 163
CIM Adapter MBean . . . . . . . . . . . . . . . . . . . . . 164
CIMEventMapper interface . . . . . . . . . . . . . . . . . . . 165
CIM configuration . . . . . . . . . . . . . . . . . . . . . . 167
File Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 168
FileTransferConnection . . . . . . . . . . . . . . . . . . . . 169
Managing file transfer implementations . . . . . . . . . . . . . . 170
Storage . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Monitor policy . . . . . . . . . . . . . . . . . . . . . . . . . 171
RMA Software Distribution . . . . . . . . . . . . . . . . . . . . 172
RMA Package Distributor MBean . . . . . . . . . . . . . . . . . 174
Software Distribution Policy . . . . . . . . . . . . . . . . . . . 178
Diagnostic Data Capture . . . . . . . . . . . . . . . . . . . . . 184
DataCaptureMBean. . . . . . . . . . . . . . . . . . . . . . 185
DataCaptureMBeanSupport . . . . . . . . . . . . . . . . . . . 187
Data Capture Policy . . . . . . . . . . . . . . . . . . . . . 188
RMADataCaptureMBean . . . . . . . . . . . . . . . . . . . . 189
DataCaptureManagerMBean . . . . . . . . . . . . . . . . . . 189
Part 4. Programming . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Chapter 15. Development environment . . . . . . . . . . . . . . . 197

Setting up the development environment . . . . . . . . . . . . . . . 197
Chapter 16. Programming examples . . . . . . . . . . . . . . . . 199

Working With Files . . . . . . . . . . . . . . . . . . . . . . . 199
Writing and registering your own MBeans . . . . . . . . . . . . . . 199
Exposing a management interface . . . . . . . . . . . . . . . . 199
MBean Object Naming . . . . . . . . . . . . . . . . . . . . 200
MBean registration . . . . . . . . . . . . . . . . . . . . . . 202
Distributing the MBean classes . . . . . . . . . . . . . . . . . 204
Making a Remote JMX Connection to the Master Agent . . . . . . . . . 204
Accessing MBean instrumentation . . . . . . . . . . . . . . . . 208
Retrieving Store Events (Notifications) . . . . . . . . . . . . . . . 210
Using the FileTransferConnection interface . . . . . . . . . . . . . . 214
Common properties. . . . . . . . . . . . . . . . . . . . . . 215
Transfer types. . . . . . . . . . . . . . . . . . . . . . . . 216
Transfer progress . . . . . . . . . . . . . . . . . . . . . . 217
Managing monitor policies . . . . . . . . . . . . . . . . . . . . 218
MonitorPolicy object . . . . . . . . . . . . . . . . . . . . . 218
MonitorPolicyAction object . . . . . . . . . . . . . . . . . . . 218
Managing data capture policies . . . . . . . . . . . . . . . . . . 219
Creating, Adding, and Activating a Capture Policy . . . . . . . . . . 219
Receiving Capture Completion Notifications . . . . . . . . . . . . . 221
Querying Invocation History . . . . . . . . . . . . . . . . . . . 221
Terminating and Deleting a Data Capture Policy . . . . . . . . . . . 222
Managing software distribution policies . . . . . . . . . . . . . . . 222
Registering draft policies . . . . . . . . . . . . . . . . . . . . 223
vi RMA V2R6 User's Guide

State and progress notifications . . . . . . . . . . . . . . . . . 224
Activating a draft policy . . . . . . . . . . . . . . . . . . . . 225
Policy invocation history and status . . . . . . . . . . . . . . . . 225
Terminating and deleting a Policy. . . . . . . . . . . . . . . . . 226
SystemStateManager . . . . . . . . . . . . . . . . . . . . . . 227
SystemStateChangeListener and SystemStateChange Notifications . . . . 227
SystemStateHandler . . . . . . . . . . . . . . . . . . . . . 227
Coding best practices . . . . . . . . . . . . . . . . . . . . . . 228
Using error logging . . . . . . . . . . . . . . . . . . . . . . 228
Controlling error log output . . . . . . . . . . . . . . . . . . . 229
Error log entry contents . . . . . . . . . . . . . . . . . . . . 230
Appendix A. Javadoc pdf file . . . . . . . . . . . . . . . . . . 231
Appendix B. Inventory tables . . . . . . . . . . . . . . . . . . 233
Appendix C. UPOS Inventory Table Definitions . . . . . . . . . . . 235

General Properties Table . . . . . . . . . . . . . . . . . . . . . 235
Device Capabilities Tables . . . . . . . . . . . . . . . . . . . . 235
Device Properties Tables . . . . . . . . . . . . . . . . . . . . . 242
Appendix D. JMX Browser Plug-Ins . . . . . . . . . . . . . . . . 249

Create a JMX Monitor Policy . . . . . . . . . . . . . . . . . . . 249
Monitor Policy Wizard . . . . . . . . . . . . . . . . . . . . . . 249
Counter Monitor advanced options . . . . . . . . . . . . . . . . 251
Gauge Monitor advanced options. . . . . . . . . . . . . . . . . 251
String Monitor advanced options . . . . . . . . . . . . . . . . . 252
Boolean Monitor advanced options . . . . . . . . . . . . . . . . 253
Apply Monitor Policy dialog . . . . . . . . . . . . . . . . . . . 254
Monitor Manager plug-in . . . . . . . . . . . . . . . . . . . . . 255
Policies tab . . . . . . . . . . . . . . . . . . . . . . . . . 255
Applied Policies tab. . . . . . . . . . . . . . . . . . . . . . 256
Notices . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
Trademarks. . . . . . . . . . . . . . . . . . . . . . . . . . 257
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
Contents vii
viii RMA V2R6 User's Guide
Figures
1. RMA infrastructure. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
2. Small enterprise deployment scenario . . . . . . . . . . . . . . . . . . . . . . . 10
3. Medium enterprise deployment scenario . . . . . . . . . . . . . . . . . . . . . . 11
| 4. Lock icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
5. IBM Remote Management Agent components for a Windows installation . . . . . . . . . . 22
6. Network interface panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7. Security mode panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
8. Summary panel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
9. Post installation window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
10. Summary information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
11. Remove installation directory dialog . . . . . . . . . . . . . . . . . . . . . . . . 37
12. Remove user directory dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 38
13. Java logging hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
14. Sample Windows Application event . . . . . . . . . . . . . . . . . . . . . . . . 57
15. Sample Windows Application event viewed in IBM Director . . . . . . . . . . . . . . . 58
16. IBM Director Console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
17. Dynamic group editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
18. Display System Attributes panel . . . . . . . . . . . . . . . . . . . . . . . . . 65
19. Discovery Preferences panel . . . . . . . . . . . . . . . . . . . . . . . . . . 67
20. Define Master Agent Panel . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
21. Store Authorization Management task window . . . . . . . . . . . . . . . . . . . . 72
22. Store Authorization Management credentials dialog . . . . . . . . . . . . . . . . . . 73
23. Select Client Authentication Key File . . . . . . . . . . . . . . . . . . . . . . . 73
24. Inventory collection panel. . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
25. Viewing inventory browser . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
26. Simple Event Filter Builder . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
27. Event filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
28. Newly created Event Action Plan appears in the Tasks frame . . . . . . . . . . . . . . 77
29. RMA Software Distribution task . . . . . . . . . . . . . . . . . . . . . . . . . 80
30. Install Package Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
31. Operating system settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
32. RMA Software Distribution File Selection panel . . . . . . . . . . . . . . . . . . . . 83
33. Package Commands dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
34. RMA Software Distribution Add Program dialog. . . . . . . . . . . . . . . . . . . . 84
35. RMA Software Distribution progress panel . . . . . . . . . . . . . . . . . . . . . 86
36. Software package subtasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
37. 4690 Package Commands dialog . . . . . . . . . . . . . . . . . . . . . . . . . 87
38. 4690 Package Commands dialog . . . . . . . . . . . . . . . . . . . . . . . . . 88
39. 4690 Create Command dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 89
40. 4690 Create Command (manually) dialog . . . . . . . . . . . . . . . . . . . . . . 89
41. Re-IPL dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
42. Re-IPL window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
43. Custom ASM Package dialog . . . . . . . . . . . . . . . . . . . . . . . . . . 91
44. ASM product state dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
45. Product options dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
46. Editing a command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
47. Import RMA Software Distribution Package dialog. . . . . . . . . . . . . . . . . . . 94
48. Export RMA Software Distribution Package dialog. . . . . . . . . . . . . . . . . . . 94
49. JMX tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
50. Properties tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
51. Set Value dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
52. Methods tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
53. Unsupported Method dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
© Copyright IBM Corp. 2004, 2010 ix
54. Method Execution dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
55. Saved JMX Method task . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
56. Handler levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
57. Logger levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
58. Resource Monitor task . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
59. Selecting Disk Utilization resource . . . . . . . . . . . . . . . . . . . . . . . . 104
60. Selecting Individual Threshold . . . . . . . . . . . . . . . . . . . . . . . . . 105
61. Threshold configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
62. Example Threshold Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 107
63. All Available Thresholds view . . . . . . . . . . . . . . . . . . . . . . . . . . 108
64. Selecting Use Disk Space resource . . . . . . . . . . . . . . . . . . . . . . . 108
65. Selecting Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
66. Creating a new record . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
67. Example Recording Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . 110
68. All Available Recordings view . . . . . . . . . . . . . . . . . . . . . . . . . . 110
69. JMX Browser task . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
70. Selecting Add User-Defined Resource Monitor . . . . . . . . . . . . . . . . . . . 112
71. Creating a new user-defined resource monitor . . . . . . . . . . . . . . . . . . . 112
72. User-defined Monitors view . . . . . . . . . . . . . . . . . . . . . . . . . . 113
73. Retail Peripheral Management Console (MSR selected) . . . . . . . . . . . . . . . . 114
74. Retail Peripheral Management Console (using Group by Model) . . . . . . . . . . . . . 117
75. Peripheral Inventory Query Browser for POS Printer . . . . . . . . . . . . . . . . . 117
76. Data Capture Policy Manager task . . . . . . . . . . . . . . . . . . . . . . . . 118
77. Data Capture Policy Manager frame . . . . . . . . . . . . . . . . . . . . . . . 119
78. Data Capture Policy Manager File Menu. . . . . . . . . . . . . . . . . . . . . . 120
79. Data Capture Policy Manager File-Close Dialog . . . . . . . . . . . . . . . . . . . 120
80. Capture Policy Manager Help Menu . . . . . . . . . . . . . . . . . . . . . . . 121
81. Data Capture Policy Manager Policy Group Dialog . . . . . . . . . . . . . . . . . . 122
82. Data Capture Policy Group Context Menu . . . . . . . . . . . . . . . . . . . . . 122
83. Data Capture Policy Create/Rename Dialog . . . . . . . . . . . . . . . . . . . . 123
84. Data Capture Policy Context Menu. . . . . . . . . . . . . . . . . . . . . . . . 124
85. Data Capture All Policies Group Context Menu . . . . . . . . . . . . . . . . . . . 125
86. Data Capture Policy Manager Export Dialog . . . . . . . . . . . . . . . . . . . . 126
87. Data Capture Policy Manager Import Dialog . . . . . . . . . . . . . . . . . . . . 127
88. Data Capture Policy Manager Find Dialog . . . . . . . . . . . . . . . . . . . . . 127
89. Data Capture Device Type right-click context menu. . . . . . . . . . . . . . . . . . 128
90. Data Capture Policy List Folder right-click Context Menu. . . . . . . . . . . . . . . . 128
91. Data Capture Implementation Group right-click context menu . . . . . . . . . . . . . . 130
92. Data Capture Implementation Creation Dialog. . . . . . . . . . . . . . . . . . . . 130
93. Data Capture Implementation right-click Context Menu . . . . . . . . . . . . . . . . 131
94. IBM Director Console with Policy Subtasks . . . . . . . . . . . . . . . . . . . . . 132
95. IBM Director Console with associated Policy Subtasks . . . . . . . . . . . . . . . . 133
96. Policy Subtask Association right-click Context Menu . . . . . . . . . . . . . . . . . 134
97. Policy Invocation Status Dialog . . . . . . . . . . . . . . . . . . . . . . . . . 135
98. Policy Invocation Status Dialog - Loading Message. . . . . . . . . . . . . . . . . . 135
99. Policy Invocation Status Dialog - Refresh . . . . . . . . . . . . . . . . . . . . . 136
100. Policy Invocation Status Dialog - Dialog Context Menu . . . . . . . . . . . . . . . . 137
101. Policy Invocation Status frame - Transferring Message . . . . . . . . . . . . . . . . 138
102. Power management shutdown and restart selections . . . . . . . . . . . . . . . . . 139
103. Power management power on selections . . . . . . . . . . . . . . . . . . . . . 139
104. Power management job example . . . . . . . . . . . . . . . . . . . . . . . . 140
105. TWGRas.properties file . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
106. Mid-level management . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
| 107. Embedded Agent model (Prior to V2R6) . . . . . . . . . . . . . . . . . . . . . . 156
| 108. (V2R6 or later) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
| 109. Proxy Objectnames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
x RMA V2R6 User's Guide

110. Event infrastructure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
111. CIM proxy MBeans for component names . . . . . . . . . . . . . . . . . . . . . 165
112. File transfer interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
113. Software distribution overview . . . . . . . . . . . . . . . . . . . . . . . . . 173
114. RMA Package Distribution overview . . . . . . . . . . . . . . . . . . . . . . . 174
115. Software policy distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
116. Data capture processing . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
117. Data capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188
118. DataCaptureManagerMBean . . . . . . . . . . . . . . . . . . . . . . . . . . 190
119. Create Monitor menu option from the Instance panel . . . . . . . . . . . . . . . . . 249
120. Monitor Policy Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250
121. Counter Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . 251
122. Gauge Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . . 252
123. String Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . . 253
124. Boolean Monitor Advanced Options panel . . . . . . . . . . . . . . . . . . . . . 254
125. Apply Monitor Policy frame. . . . . . . . . . . . . . . . . . . . . . . . . . . 255
126. Policies tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
127. Applied Policies tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
Figures xi
xii RMA V2R6 User's Guide
Tables
1. Configuration subdirectory descriptions. . . . . . . . . . . . . . . . . . . . . . .41
2. Agent properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
3. RMI properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
4. Event properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .42
5. Event fetching properties (Master Agent only) . . . . . . . . . . . . . . . . . . . .43
6. Data capture properties . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
7. Java logging levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
8. Configurable logging parameters . . . . . . . . . . . . . . . . . . . . . . . . .49
9. XML definition of the agent configuration file for Windows event log integration . . . . . . . .53
10. Mapping Windows event log definitions to RMA Notifications . . . . . . . . . . . . . . .56
11. Event type to severity mapping . . . . . . . . . . . . . . . . . . . . . . . . .56
12. Managed Object groups . . . . . . . . . . . . . . . . . . . . . . . . . . . .61
13. Retail devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
14. Device states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
15. Import file format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .70
16. Severity mapping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .78
17. Package general information . . . . . . . . . . . . . . . . . . . . . . . . . .80
18. RMA File Transfer task invocation support . . . . . . . . . . . . . . . . . . . . .95
19. Device types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
20. Power management support by Agent type . . . . . . . . . . . . . . . . . . . . . 140
21. Common symptoms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
22. IBM Remote Management Agent managed disciplines . . . . . . . . . . . . . . . . 149
23. Logging MBeans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
24. Managing file transfer implementations . . . . . . . . . . . . . . . . . . . . . . 170
25. Methods used for managing implementations . . . . . . . . . . . . . . . . . . . . 170
26. Required properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
27. Valid platform names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
28. Valid system states . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
29. SoftwarePolicy:Component tag attributes . . . . . . . . . . . . . . . . . . . . . 182
30. SoftwarePolicy:Exec tag attributes . . . . . . . . . . . . . . . . . . . . . . . . 183
31. Policy XML variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
32. javax.management.Notification fields . . . . . . . . . . . . . . . . . . . . . . . 186
33. Common properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
34. RMA File Streaming Properties . . . . . . . . . . . . . . . . . . . . . . . . . 215
35. FTPConnection properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
36. FTPSConnection properties . . . . . . . . . . . . . . . . . . . . . . . . . . 216
37. Logging level functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228
38. Log levels with sample log entries . . . . . . . . . . . . . . . . . . . . . . . . 229
39. Inventory tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233
40. General properties table. . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
41. Cash Changer Device Capabilities Table. . . . . . . . . . . . . . . . . . . . . . 235
42. Cash Drawer Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 236
43. Coin Dispenser Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . 236
44. Check Scanner Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . 236
45. Fiscal Printer Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 237
46. Hard Totals Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . 237
47. Line Display Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 238
48. MSR Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . 238
49. MICR Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . 239
50. PIN Pad Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . . . 239
51. POS Keyboard Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . 239
52. POS Power Device Capabilities Table. . . . . . . . . . . . . . . . . . . . . . . 239
53. Scale Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . . . . 240
© Copyright IBM Corp. 2004, 2010 xiii
54. Tone Indicator Device Capabilities Table . . . . . . . . . . . . . . . . . . . . . . 240
55. POS Printer General Device Capabilities Table . . . . . . . . . . . . . . . . . . . 240
56. POS Printer Journal Station Capabilities Table . . . . . . . . . . . . . . . . . . . 241
57. POS Printer Receipt Station Capabilities Table . . . . . . . . . . . . . . . . . . . 241
58. POS Printer Slip Station Capabilities Table . . . . . . . . . . . . . . . . . . . . . 242
59. Cash Changer Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 242
60. Cash Drawer Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . 243
61. Check Scanner Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 243
62. Coin Dispenser Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 243
63. Fiscal Printer Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . 243
64. Line Display Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 243
65. Hard Totals Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 244
66. Keylock Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . . . 244
67. MSR Device Properties Table. . . . . . . . . . . . . . . . . . . . . . . . . . 244
68. PIN Pad Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . . 244
69. POS Keyboard Device Properties Table . . . . . . . . . . . . . . . . . . . . . . 245
70. POS Power Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 245
71. Scale Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . . . 245
72. POS Printer Device Properties Table . . . . . . . . . . . . . . . . . . . . . . . 245
73. POS Printer Journal Station Properties Table . . . . . . . . . . . . . . . . . . . . 245
74. POS Printer Receipt Station Properties Table . . . . . . . . . . . . . . . . . . . . 246
75. POS Printer Slip Station Properties Table . . . . . . . . . . . . . . . . . . . . . 246
76. 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 IBM
Remote Management Agent (RMA) software product.
Who should read this guide

This 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 Java
programming language and the Java Management Extensions (JMX) standard is
recommended.
How this guide is organized

This guide consists of four parts:
v Part 1, “Introducing IBM Remote Management Agent,” on page 1 introduces the
IBM Remote Management Agent and describes the needs for remote
management along with the benefits that RMA can provide. This section also
discusses common general deployment strategies.
– Chapter 1, “Retail systems management,” on page 3 explains the growing
need for system management because of the increasing number of devices
used throughout the retail environment.
– Chapter 2, “RMA Overview,” on page 5 explains how RMA provides support
for the activities and disciplines that comprise system management.
– Chapter 3, “Infrastructure components,” on page 7 defines how RMA serves
as a gateway to all store resources.
– Chapter 4, “Deployment scenarios,” on page 9 gives an overview of how RMA
is deployed in enterprises of varying size and complexity.
v Part 2, “Installing and using the IBM Remote Management Agent,” on page 13
describes how to install and use the RMA agents and the Retail Extensions for
IBM® Director. It also provides examples on performing common management
tasks, such as monitoring and software distribution.
– Chapter 5, “RMA Requirements,” on page 17 list the requirements for
installing the Remote Management Agent.
– Chapter 6, “Understanding RMA Security,” on page 19 discusses the two
security modes for Master Agents.
– Chapter 7, “Installing the Remote Management General Agent and Master
Agent,” on page 21 describes how to install the Remote Management General
Agent and Master Agent.
– Chapter 8, “Installing Retail Extensions for IBM Director,” on page 33
describes the Retail Extensions for IBM Director.
– Chapter 9, “Uninstalling IBM Remote Management Agent,” on page 37
describes the procedure for uninstalling the Remote Management Agent.
– Chapter 10, “Agent configuration,” on page 41 describes configuration
processes to perform after installation is complete.
– Chapter 11, “Using Retail Extensions for IBM Director,” on page 59 provides
information on how to use the Retail Extensions for IBM Director.
– Chapter 12, “Troubleshooting,” on page 143 describes some common
problems and solutions.
© Copyright IBM Corp. 2004, 2010 xv

v Part 3, “Objectives and architecture,” on page 147 describes the architecture of
the RMA agents in order to provide the necessary background information for
writing management applications using the RMA programming interfaces.
– Chapter 13, “Architecture overview and objectives,” on page 149 contains a
high-level overview of the objectives and architecture of the Remote
Management Agent.
– Chapter 14, “Understanding the architecture,” on page 153 presents a more
detailed discussion of the Remote Management Agent architecture.
v Part 4, “Programming,” on page 195 describes how to use the RMA programming
interfaces to extend RMA with your own Java Managed Beans (MBeans) or to
write management applications that manage store resources.
– Chapter 15, “Development environment,” on page 197 discusses the
development environment.
– Chapter 16, “Programming examples,” on page 199 gives specific
explanations and examples of programming with the IBM Remote
Management Agent Application Programming Interface (API).
v Part 5 contains the appendixes, including reference to the Javadoc.pdf file, a
table of inventory information that IBM Director provides and which RMA supports
by device type.
– Appendix A, “Javadoc pdf file,” on page 231 provides information on using the
RMAJavadoc.pdf file.
– Appendix B, “Inventory tables,” on page 233 provides a list of inventory
information that IBM Director provides and supports, based on the device
type.
– Appendix C, “UPOS Inventory Table Definitions,” on page 235 includes the
tables that are defined for the Unified Point of Service (UPOS) inventory.
– Appendix D, “JMX Browser Plug-Ins,” on page 249 provide legacy procedures
for creating the JMX monitors (pre-V2R3).
v “Notices” on page 257 contains important notices and trademark information.
Conventions used in this guide

The following conventions are used throughout this document:
environment variables
This document uses percent signs (%VAR%) to designate environment
variables in Windows, and it uses $VAR to designate environment variables
in Linux.. Follow the appropriate format for your operating system.
Related publications
The following IBM publications provide additional information on using the IBM
Remote Management Agent. You can download these publications from the IBM
Retail 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 feedback
Your feedback is important in helping IBM provide accurate and high-quality
information.
To provide feedback:
v Go to http://www.ibm.com/solutions/retail/store. Click Support, then click
Publications. Click the publication comments within the introductory text.
Provide the requested information and your comments. Be sure to include the
name and form number of the document in the [Publication ID] field.
v You can mail your comments to:
IBM Corporation Retail Store Solutions
Information Development Department ZBDA
P.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, the
page 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 Web
site at www.ibm.com/solutions/retail/store/support/publications/.
About this guide xvii

xviii RMA V2R6 User's Guide
Summary of changes
| Web-only update of GC30-4106-09
| This update documents the changes to the IBM Remote Management Agent guide
| since 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-08

This update documents the following changes to the IBM Remote Management
Agent 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 Master
Agents)
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, Windows
Server 2003 x64
© Copyright IBM Corp. 2004, 2010 xix

v New supported platforms for General Agent: POSReady 2009, SUSE Linux
Environment 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 . . . . . . . . . . . . . . . 3
The need for systems management. . . . . . . . . . . . . . . . . . 3
The importance of standards . . . . . . . . . . . . . . . . . . . . 4
Management solutions . . . . . . . . . . . . . . . . . . . . . . 4
Chapter 2. RMA Overview . . . . . . . . . . . . . . . . . . . . . 5

Power management . . . . . . . . . . . . . . . . . . . . . . . 5
Events Management . . . . . . . . . . . . . . . . . . . . . . . 5
Inventory and Asset tracking . . . . . . . . . . . . . . . . . . . . 6
Monitoring Retail Systems . . . . . . . . . . . . . . . . . . . . . 6
Diagnostic data capture . . . . . . . . . . . . . . . . . . . . . . 6
Retail peripheral management . . . . . . . . . . . . . . . . . . . . 6
File transfer . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Chapter 3. Infrastructure components . . . . . . . . . . . . . . . . 7
Chapter 4. Deployment scenarios. . . . . . . . . . . . . . . . . . 9

Small enterprise scenario . . . . . . . . . . . . . . . . . . . . . 10
Medium enterprise scenario . . . . . . . . . . . . . . . . . . . . 11
Large 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 the
point-of-sale (POS) device used at the end of the shopping experience. Now, retail
systems includes new devices that present the customer with technology at every
step of the in-store experience. A wide range of devices—including handheld
customer units, attendant facing units, wireless cart-mounted devices, self-service
kiosks, 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 of
the infrastructure, including elements that are located within the store, as well as
those at the enterprise. It is imperative that these devices remain in service and
function as intended. When devices do fail, the failures must be detected and
promptly corrected, or the failures be predicted before they occur. This presents a
strong need for manageability.
The need for systems management

Systems 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. An
operator or an application can monitor and maintain the health of a device with this
functionality, taking corrective action when needed. This management is aimed at
keeping the device in service, which is especially important in the retail space
because fully functional devices means additional sales tools are in front of the
customer.
Systems management is usually thought of as covering some portion or all of the

following disciplines:
power management
The ability to remotely manage the power states of POS systems. Proper
use of this feature can reduce energy consumption and operational costs.
event management
Indications of immediate and potential problems, thresholds met, or general
status information. Can be used in triggering both manual and automated
corrective actions.
operational control and monitoring
Provides control of the device or elements of the device's operation.
Applications can "watch" defined elements in a device for
application-defined trigger points.
performance monitoring and management
Overseeing and managing the use of system resources to best manage
performance. Information can be used for system- and network-resource
planning.
software distribution
Software and firmware updates; installation and uninstallation of function on
devices.
asset tracking and inventory
Asset tracking for both hardware and software, which can be extremely
important to business functions within an organization. Asset and inventory
tracking is required for use by software distribution tools, and is helpful in
understanding and planning fixes.
configuration management
The ability to view and replicate configuration settings for any device in the
enterprise. Configuration management also offers the ability to remotely
configure or alter the configuration of a device or software element on a
device.
All of these functional disciplines, working together, form a comprehensive

management solution. Although it is not necessary for a particular management
application to support all of these disciplines, it is imperative that the device being
managed supports them in a consistent, open, and well-understood way.
The importance of standards

The key to enabling all of the disciplines of system management is manageability
standards. The retailer needs devices that are manageable, and these devices
need to be compatible with the other devices in their IT space. It would not be
logical for device manageability to be inconsistent with or unusable by the
systems-management application software that the retailer has chosen for its
enterprise. Personnel who are defining manageability for new devices must fully
understand the device that they are trying to manage and the space in which the
device is intended to operate. This personnel must have knowledge of any existing
management standards and schemas for that space.
Management solutions
When creating a complete management solution, several components are required.
IBM Retail Store Solutions supports customers ranging from the small and medium
business (SMB) to the large enterprise, and provides two complete solutions; each
fitting a different segment. The SMB solution is based around IBM Director, and the
solution for large enterprises is built around the power and expansiveness of IBM
Tivoli® applications.
The Remote Management Agent is the common component in both solutions. With
RMA, you can start with a smaller and less expensive installation based on IBM
Director. When the need for more capacity arises, you can easily move to a full
Tivoli solution without changing the agent infrastructure in the store, which is RMA.
You should consider such factors as your environmental needs and what type of
functions you need to deploy. For example, how many devices do you need to
manage? Do you need to manage them centrally from one tool? Can you divide
your enterprise into regions? Who needs to have access to individual management
tools? Do you already have an enterprise management tool, and can it be
integrated?
All of these questions will help you and your service team better understand how to
configure a solution that best fits your needs. The most important thing to
remember when examining a systems management solution is that there is not one
solution. Everyone's needs and wants are different, and the key is to provide
solutions that address all of them.

Chapter 2. RMA Overview
| IBM Remote Management Agent, along with other IBM retail solutions such as IBM
| Director, is the backbone of the IBM Retail System Management system that helps
| you view, track, and control your retail hardware and software environment. With
| IBM Remote Management Agent, you can manage your store or enterprise retail
| operations from a single console. Designed specifically to support your retail
| environment, 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 device
| driver 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 retail
infrastructure from the enterprise, you can use other management applications to
connect with the RMA Master Agent and manage the resources in each store,
including custom management applications written using Java Management
Extensions (JMX) and the RMA programming interfaces.
This chapter explains how RMA provides support for the management disciplines
discussed in Chapter 1, “Retail systems management,” on page 3.
Power management
RMA provides support for managing the power states of POS systems in your
enterprise. This includes the ability to remotely shut down, suspend, reboot, and
power on (using Wake On LAN®). These operations can be invoked and scheduled
from IBM Director.
Events Management
Hardware and software resources in the store generate notification events, which
the 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 to
RMA events, and forwarded to other applications.
The IBM Director Server retrieves RMA events from the RMA Master Agent in each
store, 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 take
proactive actions in response to specific events.
Software distribution
RMA provides support for the distribution of generic software packages (consisting
of files, or a set of commands, or both). RMA defines a standard package format
and facilities for deploying packages to multiple clients on various platforms in the
store 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 tracking

JMX MBeans, registered on all RMA agents, provide access to all instrumentation
on each store device. Instrumentation for each store device can be accessed on the
RMA Master Agent.
You can use IBM Director to retrieve and store collections of hardware- and
software-inventory information, including retail-specific information for peripherals.
This information is stored in the IBM Director database, and it can be monitored or
queried (even when not connected to the RMA Master Agents).
Monitoring Retail Systems

RMA supports active monitoring of store resources, with the ability to define
thresholds and record values. Monitor policies can be registered with each RMA
Master 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 Director
monitoring interface, where retail-specific monitors, as well as the default IBM
Director monitors, can be created.
Diagnostic data capture

RMA provides infrastructure for performing diagnostic data captures, where files can
be gathered when errors occur. After they are collected, the capture files are
automatically transferred to each store's Master Agent, and from there can be
transferred to the enterprise for diagnosis.
The Retail Extensions for IBM Director provide a user interface for creating and
managing RMA data-capture policies.
Retail peripheral management

The RMA agents include JMX MBeans that provide access to UPOS peripheral
instrumentation.
You can use the Retail Peripheral Management tasks in IBM Director to monitor
retail peripherals and collect inventory.
File transfer
RMA supports the ability to perform file operations remotely.
You can use the RMA File Transfer task in IBM Director to browse the file system
and to perform file operations on devices that are running the RMA agent, including
sending, receiving and viewing files.

Chapter 3. Infrastructure components
RMA serves as a gateway to all store resources. At the enterprise level, there are
numerous integration possibilities for enterprise management, as Figure 1
illustrates:
WebSphere Custom IBM Director

Remote Server Application Server
Master
Agent
General
General
Agent
Agent
Store
Figure 1. RMA infrastructure
IBM Director, enterprise management tools based on JMX, and custom

management applications written to the RMA APIs can all connect to the Master
Agent to manage store resources. These are the components that make up the
RMA infrastructure in the store, and they comprise an IBM Director deployment at
the enterprise:
RMA General Agent
Forms the client portion of the RMA infrastructure, running on each POS
client device.
RMA Master Agent
Runs in each store that aggregates all resources in the store. The Master
Agent is the single point of access to all store resources from the
enterprise. There should be only one Master Agent per store, which will
automatically connect to all in-store devices running the RMA General
Agent.

IBM Director Server
Communicates with one or more in-store Master Agents to provide a
consolidated view of many stores.
IBM Director Console
Connects to the IBM Director Server to provide a user interface for
managing the IT infrastructure, including retail devices. The IBM Director
Console can be run on the Director Server system or any other system on
the enterprise network.
Retail Extensions for IBM Director
Must be installed on all IBM Director Servers and IBM Director Consoles
where retail management is to be performed.

Chapter 4. Deployment scenarios
You should consider the following factors when estimating the capacity and
performance 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 as
IBM Director Server?
v The amount of management being performed on IBM servers and other
non-retail hardware.
As the number of devices grows, more IBM Director Servers are required, as is
depicted in the scenarios in this section.

Small enterprise scenario
An enterprise with a small number of stores and devices can use one IBM Director
Server, connecting to all store Master Agents.
IBM Director Server
Master Master
Agent Agent
General General
General General
Agent Agent
Agent Agent
Store Store
Figure 2. Small enterprise deployment scenario

Medium enterprise scenario
As the number of managed clients exceeds the capacity of a single IBM Director
Server, the enterprise should be logically divided into regions, each with its own
IBM Director Servers. Managing the stores in each region requires logging in to the
IBM Director Server for that region. You should leave some room in the IBM
Director Server in each region for future growth.
IBM Director Server IBM Director Server
Store Store Store Store Store Store
Figure 3. Medium enterprise deployment scenario
Large enterprise scenario

When the number of IBM Director Servers becomes hard to manage, a large
enterprise solution, like WebSphere® Remote Server plus Tivoli Enterprise Console
(TEC), IBM Tivoli Monitoring (ITM), and Tivoli Provisioning Manager (TPM) might be
necessary.
Chapter 4. Deployment scenarios 11

Part 2. Installing and using the IBM Remote Management
Agent
Chapter 5. RMA Requirements . . . . . . . . . . . . . . . . . . 17
Hardware requirements . . . . . . . . . . . . . . . . . . . . . . 17
Software requirements . . . . . . . . . . . . . . . . . . . . . . 17
Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Supported operating systems . . . . . . . . . . . . . . . . . . 17
IBM Director . . . . . . . . . . . . . . . . . . . . . . . . . 18
Installation roles . . . . . . . . . . . . . . . . . . . . . . . 18
Network Configuration Requirements . . . . . . . . . . . . . . . . 18
| Chapter 6. Understanding RMA Security . . . . . . . . . . . . . . 19

| Master Agent Security Modes . . . . . . . . . . . . . . . . . . . 19
| Installation and upgrades . . . . . . . . . . . . . . . . . . . . 19
| Security groups. . . . . . . . . . . . . . . . . . . . . . . . 19
| Windows . . . . . . . . . . . . . . . . . . . . . . . . . 19
| Linux . . . . . . . . . . . . . . . . . . . . . . . . . . 19
| 4690 OS . . . . . . . . . . . . . . . . . . . . . . . . . 20
| IBM Director . . . . . . . . . . . . . . . . . . . . . . . . 20
| General Agent Security . . . . . . . . . . . . . . . . . . . . . . 20
Chapter 7. Installing the Remote Management General Agent and Master

Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Interactive installation on Windows . . . . . . . . . . . . . . . . . 21
Windows post installation . . . . . . . . . . . . . . . . . . . 26
Interactive installation on Linux . . . . . . . . . . . . . . . . . . . 27
Linux prerequisites . . . . . . . . . . . . . . . . . . . . . . 27
Small Footprint CIM Broker . . . . . . . . . . . . . . . . . . . 27
SFCB installation . . . . . . . . . . . . . . . . . . . . . . 27
SFCB configuration . . . . . . . . . . . . . . . . . . . . . 28
Starting SFCB on startup . . . . . . . . . . . . . . . . . . . 29
Post installation. . . . . . . . . . . . . . . . . . . . . . . 29
Silent installation of the Remote Management Agent on Windows . . . . . . 30
4690 OS installation . . . . . . . . . . . . . . . . . . . . . . . 30
Updating RMA . . . . . . . . . . . . . . . . . . . . . . . . . 30
Package import. . . . . . . . . . . . . . . . . . . . . . . . 31
Chapter 8. Installing Retail Extensions for IBM Director . . . . . . . . 33

Interactive installation for Windows . . . . . . . . . . . . . . . . . 33
Interactive installation for Linux . . . . . . . . . . . . . . . . . . . 34
Silent installation of the Retail Extensions for IBM Director for Windows and
Linux. . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Chapter 9. Uninstalling IBM Remote Management Agent . . . . . . . . 37

Interactive uninstallation for Windows . . . . . . . . . . . . . . . . 37
Silent uninstallation for Windows . . . . . . . . . . . . . . . . . . 38
Uninstallation for Linux . . . . . . . . . . . . . . . . . . . . . . 39
Uninstallation result . . . . . . . . . . . . . . . . . . . . . . . 39
Retail Extensions for IBM Director uninstallation notes . . . . . . . . . . 39
Chapter 10. Agent configuration . . . . . . . . . . . . . . . . . . 41

Directory structure. . . . . . . . . . . . . . . . . . . . . . . . 41
Agent configuration file . . . . . . . . . . . . . . . . . . . . . 41
Security configuration . . . . . . . . . . . . . . . . . . . . . 43
SSL configuration . . . . . . . . . . . . . . . . . . . . . . . 44
Updating SSL certificates . . . . . . . . . . . . . . . . . . . . 45
Agent class path and environment . . . . . . . . . . . . . . . . . 46
Java class path. . . . . . . . . . . . . . . . . . . . . . . 46
Windows PATH . . . . . . . . . . . . . . . . . . . . . . . 47
Logging configuration . . . . . . . . . . . . . . . . . . . . . 47
Logging levels . . . . . . . . . . . . . . . . . . . . . . . 48
RMA logging configuration file changes . . . . . . . . . . . . . . 49
Agent startup sequence . . . . . . . . . . . . . . . . . . . . 50
MgmtAgentStartupMBean . . . . . . . . . . . . . . . . . . . 51
Agent configuration . . . . . . . . . . . . . . . . . . . . . 51
Agent roles . . . . . . . . . . . . . . . . . . . . . . . . . 52
Agent Windows event log integration . . . . . . . . . . . . . . . . 52
Agent configuration file . . . . . . . . . . . . . . . . . . . . 52
Event qualifiers . . . . . . . . . . . . . . . . . . . . . . . 53
Configuration file format . . . . . . . . . . . . . . . . . . . 53
Event mapping . . . . . . . . . . . . . . . . . . . . . . . 56
Example forwarded event . . . . . . . . . . . . . . . . . . . 57
Chapter 11. Using Retail Extensions for IBM Director . . . . . . . . . 59

IBM Director Console . . . . . . . . . . . . . . . . . . . . . . 60
Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Managed Object groups . . . . . . . . . . . . . . . . . . . 60
Dynamic groups . . . . . . . . . . . . . . . . . . . . . . 62
Managed Objects . . . . . . . . . . . . . . . . . . . . . . . 62
Managed Object types . . . . . . . . . . . . . . . . . . . . 63
Managed Object states . . . . . . . . . . . . . . . . . . . . 64
Managed Object attributes. . . . . . . . . . . . . . . . . . . 64
Associations . . . . . . . . . . . . . . . . . . . . . . . . 65
Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Discovery Preferences panel . . . . . . . . . . . . . . . . . . . 67
Adding a Master Agent . . . . . . . . . . . . . . . . . . . . 67
Editing a Master Agent . . . . . . . . . . . . . . . . . . . . 69
Removing a Master Agent . . . . . . . . . . . . . . . . . . . 69
Importing a list of Master Agents . . . . . . . . . . . . . . . . 69
Exporting a list of Master Agents . . . . . . . . . . . . . . . . 71
Starting Discovery. . . . . . . . . . . . . . . . . . . . . . . 71
Store Authorization Management task . . . . . . . . . . . . . . . . 72
Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Inventory collection . . . . . . . . . . . . . . . . . . . . . . 74
Viewing inventory . . . . . . . . . . . . . . . . . . . . . . . 74
Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Event log . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Event action plans . . . . . . . . . . . . . . . . . . . . . . 75
Creating an action event plan . . . . . . . . . . . . . . . . . 75
| Publishing custom event types . . . . . . . . . . . . . . . . . 78
Severity mapping . . . . . . . . . . . . . . . . . . . . . . 78
RMA Software Package Editor . . . . . . . . . . . . . . . . . . 79
Editing a software package . . . . . . . . . . . . . . . . . . . 80
Package Wizard general information . . . . . . . . . . . . . . . 80
Operating system settings . . . . . . . . . . . . . . . . . . . 81
Package creation and saving progress . . . . . . . . . . . . . . 85

RMA Software Distribution 4690 Command Wizard . . . . . . .
. 87 . .
Adding new commands . . . . . . . . . . . . . . . . .
. 88 . .
Editing Commands . . . . . . . . . . . . . . . . . .
. 92 . .
Importing Commands . . . . . . . . . . . . . . . . .
. 93 . .
Software package subtasks . . . . . . . . . . . . . . . .
. 93 . .
Edit package. . . . . . . . . . . . . . . . . . . . .
. 93 . .
Rename package . . . . . . . . . . . . . . . . . . .
. 93 . .
Delete package. . . . . . . . . . . . . . . . . . . .
. 93 . .
Import package . . . . . . . . . . . . . . . . . . . .
. 93 . .
Export package. . . . . . . . . . . . . . . . . . . .
. 94 . .
Deploying a package. . . . . . . . . . . . . . . . . .
. 94 . .
RMA File Transfer task . . . . . . . . . . . . . . . . . . .
. 95 . .
Task invocation . . . . . . . . . . . . . . . . . . . . .
. 95 . .
JMX Browser task. . . . . . . . . . . . . . . . . . . . .
. 95 . .
JMX tree panel . . . . . . . . . . . . . . . . . . . . .
. 96 . .
Instance panel . . . . . . . . . . . . . . . . . . . . .
. 97 . .
Properties . . . . . . . . . . . . . . . . . . . . . .
. 97 . .
Methods . . . . . . . . . . . . . . . . . . . . . .
. 98 . .
Method Execution dialog . . . . . . . . . . . . . . . . .
. 99 . .
Adjusting the handler and logger levels using JMX Browser . . . . . . . . 102
Resource Monitors . . . . . . . . . . . . . . . . . . . . . . . 103
Creating a Threshold Monitor . . . . . . . . . . . . . . . . . . 104
Creating a Recording Monitor . . . . . . . . . . . . . . . . . . 108
User-Defined Monitors . . . . . . . . . . . . . . . . . . . . . . 110
Importing threshold plan files . . . . . . . . . . . . . . . . . . . 113
Retail Peripheral Management . . . . . . . . . . . . . . . . . . . 113
Retail Peripheral Management Console . . . . . . . . . . . . . . 114
Data Capture Policy Manager task . . . . . . . . . . . . . . . . . 117
Data Capture Policy Manager . . . . . . . . . . . . . . . . . . 118
Menu Bar . . . . . . . . . . . . . . . . . . . . . . . . 119
Policies Pane (Left Pane) . . . . . . . . . . . . . . . . . . 121
Device Types Pane (Center Pane) . . . . . . . . . . . . . . . 129
Data Capture Implementations Pane (Right Pane) . . . . . . . . . 129
Data Capture Policies . . . . . . . . . . . . . . . . . . . . . 131
Associating Data Capture Policies . . . . . . . . . . . . . . . 132
Viewing Associated Data Capture Policies . . . . . . . . . . . . 132
Manipulating Associated Data Capture Policies . . . . . . . . . . 133
Status Frame for Data Capture Policies . . . . . . . . . . . . . . 134
Viewing Capture History for a Policy . . . . . . . . . . . . . . 135
Refreshing the Displayed Capture History . . . . . . . . . . . . 135
Deleting from a Capture History . . . . . . . . . . . . . . . . 136
Retrieving the Capture Bundle for a RMA Data Capture Policy Invocation 137
Power management . . . . . . . . . . . . . . . . . . . . . . 138
Chapter 12. Troubleshooting. . . . . . . . . . . . . . . . . . . 143

Logs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
RMA Agents . . . . . . . . . . . . . . . . . . . . . . . . 143
Agent JVM Diagnostics . . . . . . . . . . . . . . . . . . . . 143
IBM Director . . . . . . . . . . . . . . . . . . . . . . . . 144
Director Event Configuration . . . . . . . . . . . . . . . . . 144
RAS Logging . . . . . . . . . . . . . . . . . . . . . . . 144
JVM 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 IBM
Remote Management Agent.
Hardware requirements
The Master Agent runs on the in-store processor. The in-store processor is a
Microsoft Windows, Linux, or 4690 V6 Enhanced system that runs the IBM Remote
Management Agent service and provides a point of interface for enterprise
applications or other in-store applications. The in-store processor should have a
minimum 1 GHz processor with 1 GB of RAM. The Master Agent Service requires
approximately 80 MB of memory without any extensions or connected General
Agents. Memory usage will increase as extensions are added, connections are
made, and policies are applied.
| The General Agent runs as an embedded agent in a Java virtual machine (JVM), as
| a system service on a 4690 controller, or on a Windows or Linux system. The
| Master Agent and General Agent services cannot be installed on the same
| computer. The General Agent Service requires approximately 70 MB of virtual
| memory when running in a Windows environment and 40 MB of virtual memory
| when running in a Linux environment.
On 4690 operating systems, additional memory is required for each terminal that
the controller supports.
Software requirements
This section describes the software requirements for the IBM Remote Management
Agent.
Java
The IBM Remote Management Agent installs its own IBM Java 6 Runtime
Environment (JRE) software. It does not require a JRE to be installed before RMA
installation.
Supported operating systems

The IBM Remote Management Agent, Version 2 Release 6 must be installed on
one 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 with
previous 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 levels
of 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 Director
The Retail Extensions for IBM Director for IBM Remote Management Agent V2R6
require IBM Director 5.20.3 Service Update 3 on the following platforms:
v Windows 2003 Server
v Windows 2003 Server x64
Installation roles
| The IBM Remote Management Agent can be installed as a Master Agent or as a
| General Agent. Chapter 7, “Installing the Remote Management General Agent and
| Master Agent,” on page 21 only describes the installation of the General Agent
| Service or Master Agent Service components. Starting a General Agent
| programmatically within an application JVM is discussed in “Embedded Agent
| registration” on page 202.
Network Configuration Requirements

The IBM Remote Management Agent uses the following network ports. This
information can be used for enterprise network configuration:
v 10149: Serialized Object Exchange/Stream (SOXS) Communication between
Management Applications (IBM Director) and a Master Agent.
v 10150: Java RMI (Remote Method Invocation) Communication between
Management Applications (the IBM Director) and a Master Agent.
Note: Due to the design of RMI, opening up port 10150 alone on a firewall will
not work. Remote connections made to a Master Agent through a firewall
can only use SOXS.
v 10151: Java RMI (Remote Method Invocation) Communication between Master
Agents and General Agents inside the store.
Note: Due to the design of RMI, opening up port 10150 alone on a firewall will
not 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. The
multicast address used is 225.6.29.63

|
Chapter 6. Understanding RMA Security
| RMA V2R5 introduced security enhancements to improve Master Agent and
| General Agent security. The security changes to the Master Agent improved the
| authentication method used by management applications to access the Master
| Agent. The General Agent security enhancements prevents unauthorized access to
| General Agents within a store.
| Master Agent Security Modes

| The RMA V2R5 Master Agent can run in one of two security modes, each using
| one of the two forms of authentication: enhanced security mode or standard
| security mode. When running in enhanced security mode, all incoming JMX
| connections requires a valid username and password.
| Installation and upgrades

| The RMA installation prompts the user to select a security mode during a fresh
| installation of the RMA Master Agent or an upgrade of a Master Agent from a prior
| version of RMA.
| The security mode can be changed after installation from mode to mode by
| changing the security configuration file on the Master Agent system (see “Security
| configuration” on page 43).
| Security groups
| Enhanced authentication not only validates a given username and password, but
| also verifies that the user is a member of a specific system group. The group
| membership requirements on each platform are described below.
| Note: When upgrading the Master Agent to secure mode using RMA Software
| Distribution, a valid Windows username and password is required to connect
| after the updated Master Agent starts in secure mode. You should have an
| Administrator username and password (Windows) or the root password
| (Linux) before you upgrade. Depending on the system environment, it also
| might be necessary for you to pre-configure some security groups.
| Windows
| During installation of a Master Agent on Windows, a Windows local group called
| RMAAdmin is created for RMA authentication. During authentication, the supplied
| username is checked for membership in this group, and the username and
| password are verified. During installation, the local Administrators group of the
| system is added to the RMAAdmin group. You can modify the contents of the
| RMAAdmin group to contain other local or domain user accounts and groups.
| Linux
| If it does not already exist, a group called rmaadmin is created for RMA
| authentication during installation of a Master Agent on Linux. During authentication,
| the supplied username is checked for membership in this group, and the username
| and password are verified. The root user is added as the only member of this
| group during installation. You can modify the contents of the rmaadmin group to
| contain other user accounts.

| 4690 OS
| To 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 -> Authorization

| Manager with User Defined Attribute #8 enabled. This user allows the IBM
| Director Server to authenticate with the 4690 Master Agent. Refer to the 4690 OS
| publications listed in “Related publications” on page xvi for more details.
| IBM Director
| When IBM Director connects to a Master Agent that is running in enhanced security
| mode, a username and password is required to authenticate with that store. Master
| Agents that require authentication are denoted with a lock icon:
|
Figure 4. Lock icon
| Authenticating with the Master Agent using the Store Authorization task will remove
| the 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 on
| working with secured Master Agents in IBM Director.
| General Agent Security

| The General Agent is secured by creating an exclusive relationship between the
| Master Agent and General Agent. After the Master Agent connects to a General
| Agent, only that Master Agent can connect to that General Agent going forward.
| With this authentication method, a key exchange is performed between the Master
| Agent and General Agent. Each General Agent is installed with a default key that
| establishes a relationship between that General agent and the first Master Agent it
| discovers.
| Once discovered, a key pair is exchanged between the Master Agent and General
| Agent to use as a basis for authentication. If a Master Agent is lost, then all of the
| keys for the General Agents are also lost, and reinstalling the Master Agent does
| not work. To prevent the keys from being lost, you should back up the key store
| files so they can be restored on the new machine. You can do this manually by
| regularly backing up the %SI_HOME%\user\rma\security\keys_ma.dat file on the
| Master Agent. You can also back up the Master Agent keys from the enterprise
| using the Store Authorization Management task in IBM Director. Using the Store
| Authorization Management task, the backup operation can be scheduled or invoked
| immediately.
| If you are unable to restore the keys on the Master Agent, the keys on each
| General Agent should be restored to the default key. You can restore the key by
| deleting the %SI_HOME%\user\rma\security\keys_ga.dat file on each General
| Agent, and restarting the General Agent service.

Chapter 7. Installing the Remote Management General Agent
and Master Agent
The IBM Remote Management Agent is delivered on a single CD, which includes
the Remote Management General Agent, Master Agent, and the Retail Extensions
for IBM Director. Before attempting to install the Remote Management Agent
software, read all the installation instructions in this chapter.
The level of the Master Agent must always be at the same level or later than those
on any client to avoid unpredictable results. Therefore, it is important to always
upgrade 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 Agents
to which it is connected. Therefore, you should upgrade the Retail Extensions for
IBM Director before upgrading the Master Agents.
The installation software uses InstallShield MultiPlatform on Windows, and a Red

Hat Package Manager (RPM) package on Linux. To install the Remote
Management Agent code, follow the procedure described in “Interactive installation
on Windows,” “Interactive installation on Linux” on page 27, or “Silent installation of
the Remote Management Agent on Windows” on page 30 sections.
Interactive installation on Windows

The following sections describe IBM Remote Management Agent installation and
post-installation procedures for a Windows system.
Installation procedure
To 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 issue
the D:\windows\rma\setup.exe command, where D is the CD drive.
4. On the Welcome to the InstallShield Wizard for Remote Management Agent for
IBM Remote Management Agent panel, click Next.
5. On the Software License Agreement panel, select I accept the terms in the
license agreement. Installation cannot continue until you read and agree to
the license terms. Click Next.
Note: Steps 6-9 are for fresh installations only. If RMA is already installed on
the system, then proceed to Step 10 on page 24.
6. The default installation directory is displayed. To use the default, click Next to
continue. Otherwise, click Browse to select a different directory, and then click
Next.
Note: If Store Integrator (SI) is installed on the system, then install RMA to
that file location.

7. A list of agent types is displayed, as shown in Figure 5. Select the radio button
for the agent that you want to install and click Next.
Figure 5. IBM Remote Management Agent components for a Windows installation
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.

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 IP
subnet as the store's Master Agent and click Next.
v For a Master Agent, choose the interface that is exposed externally to the
management 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 click
Next.
Figure 7. Security mode panel

11. A summary panel (Figure 8) is displayed with the information pertaining to the
installation. If any of the information is not correct, click Back to return to a
previous panel and change your selection. When all selections are correct,
click Next.
Figure 8. Summary panel
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 installation
process.
All products in the Store Integrator family are installed in terms of components.
Each component is installed into its own directory <COMPONENT>xxxxxxx under the
root directory, where xxxxxxx stands for the version number.
The RMA component is installed with the Remote Management Agent. The directory
is created under the installation root directory.
A maximum of two versions of each component can be on the system: the current
version and a backup version that can be reactivated if the current version does not
work as expected.
(This is similar to the 4690 OS Apply Software Maintenance Process.) Reactivation

of the backup version is done by uninstalling the current version, which changes all
environment variables to point to the backup version's directories.
Note: When an agent is migrated from a previous version, certain configuration

and data files in the %SI_HOME%\user\rma directory could be migrated to
new formats. As a result, going back to the previous version can cause
unpredictable results and is unsupported.
Windows post installation
Following the completion of the installation process, you are required to reboot
before the new installation will take effect. Upon restart, the IBM Remote
Management Agent Service starts running. There is an entry for the IBM Remote
Management Agent Service in the Windows Services Applet from the Control Panel.
Figure 9. Post installation window
Note: If a Master Agent running in enhanced security mode was installed, you can
make custom changes to the RMAAdmin security group. For more information
about group membership when running in enhanced security mode, see
“Security groups” on page 19.

Interactive installation on Linux
You can install the IBM Remote Management Agent on a Linux system. The RMA
agent is installed and upgraded via an RPM package. On the installation CD, there
are two RPM files; one for a Master Agent, the other for a General Agent.
Linux prerequisites
RMA relies on access to Common Information Model (CIM) information on each
system to perform certain functions. Without CIM information, limited system
information is available to RMA, and as a result some functionality is not present or
is only available in a limited fashion. The following lists the features that are not
available 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 Broker

On SUSE Linux Enterprise, CIM information is provided by Small Footprint CIM
Broker (SFCB). This section describes how to install and configure SFCB on a
SUSE Linux Enterprise system.
SFCB installation
The following RPM packages, included in the SLED distribution, provide SFCB
support on a SUSE Linux Enterprise system:
v sblim-sfcb
Note: If you want to use UPOS Peripheral Management on a supported Linux

system, the minimum SFCB version is sblim-sfcb-1.3.2-18.10.1. You can
download 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 the
required 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 configuration
After SFCB is installed, it must be configured to use unauthenticated Hypertext
Transfer 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 startup
SFCB must be configured to start when the system starts, but before the RMA
service. To configure SFCB to run on startup, enable the sfcb service to start in the
appropriate 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 SUSE

documentation.
Installation procedure
The following instructions describe how to manually upgrade and install RMA on
Linux.
To upgrade an RMA Agent from a previous version on 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 the
mount command. For example, issuing the mount /dev/cdrom /media/cdrom
command 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 the
mount command. For example, issuing the mount /dev/cdrom /media/cdrom
command 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 installation
During the installation process, the Remote Management Agent Service will be
installed. There is a SysInit shell script for running the Service in the /etc/init.d
directory, rmsvc-ga (General Agent) or rmsvc-ma (Master Agent). This script has
the following parameters (status, start, stop and restart).
Fresh installations only: Before running either of the agents for the first time on
Linux, the rma-config script must be run in order for required configuration values
to 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 of
information. The script can be run silently by supplying each configuration value on
the 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 and
myStoreId 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 time
following installation. After running the script, the RMA agent must be restarted for
the changes to be reflected.
Note: If a Master Agent was installed running in enhanced security mode, custom
changes to the rmaadmin security group can be made. For more information
about group membership when running in enhanced security mode, see
“Security groups” on page 19.
Silent installation of the Remote Management Agent on Windows

For 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 installation
Refer to the 4690 Planning, Installation, and Configuration Guide for more
information on enabling this option.
Updating RMA
Using RMA Software Distribution in IBM Director, you can upgrade the RMA agents.
Package files located directly on the installation CD can be imported into IBM
Director, creating RMA Software packages that can then be deployed to all
Windows and Linux systems running RMA. As of 4690 OS V6, RMA is included in
the base 4690 OS. You must upgrade 4690 OS in order to upgrade RMA.

For more information about the RMA Software Distribution task, see “Software
distribution” on page 78.
Package import
To upgrade RMA, use one of the package files located in the dirpkgs directory on
the RMA installation CD:
RMA_GeneralAgent_x.y.zzzz_Win32.rsdp
Upgrades the General Agent running on a Windows system.
RMA_MasterAgent_EnhancedSecurity_x.y.zzzz_Win32.rsdp
Upgrades the Master Agent running on a Windows system and enables
enhanced security mode.
RMA_MasterAgent_StandardSecurity_x.y.zzzz_Win32.rsdp
Upgrades the Master Agent running on a Windows system and enables
standard security mode.
RMA_x.y.zzzz_Linux.rsdp
Upgrades the General Agent or Master Agent running on a Linux system.
Notes:
1. Once an agent has been migrated from a previous version, certain configuration
and data files in the %SI_HOME%\user\rma directory are migrated to new
formats. As a result, going back to the previous version can cause unpredictable
results.
2. When updating the Master Agent using RMA Software Distribution in IBM
Director, there are two packages on the installation CD to upgrade RMA. One
package upgrades the Master Agent and enables enhanced security mode, the
other 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 the
Retail Extensions for IBM Director. The CD is used for installation on Windows- or
Linux-based IBM Director systems. The Retail Extensions for IBM Director provide
the additional functionality to support the management of retail devices and must be
installed on all IBM Director Servers and Consoles.
Note: Read all of the instructions carefully before attempting to install the Retail
Extensions for IBM Director software.
The installation software uses InstallShield MultiPlatform. To install the Retail

Extensions for IBM Director code, follow the procedures described in one of the
following 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 and
Linux” on page 35
Interactive installation for Windows

You can install the Retail Extensions for IBM Director on a Windows 2003 Server
system 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 the
D:\windows\rma4itd\setup.exe command, where D is the CD drive.
4. On the Welcome to the InstallShield Wizard for Retail Extensions for IBM
Director panel, click Next.
license agreement. Installation cannot continue until you read and agree to the
terms. Click Next.
6. If you are upgrading from RMA Extensions for IBM Director V2R3 or earlier, a
panel appears that informs you that the UPOS peripheral inventory information

will be removed during installation due to database table format changes. After
the upgrade completes, inventory information will be restored after the first
inventory 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 the
IBM Director application and sets this up as the installation location. The
software 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 with
the installation, click Next.
Figure 10. Summary information
8. The installation process takes several minutes top complete. When the process
is complete, click Finish.
Note: If the IBM Director Server is running, the server is stopped so that the
extensions can be installed. If the server is stopped by the installation
program, it is then restarted when the installation is complete.
Interactive installation for Linux

You can install the Retail Extensions for IBM Director on a Linux system that
currently 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.

For example, issuing the mount /dev/cdrom/ /media/cdrom command as root
mounts 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 long
time. If you know the location of the JRE, you can bypass the search by
issuing the /media/cdrom/linux/rma4itd/setup.bin -is:javahome jrepath
command to run the installation program, where jrepath is the path to the
IBM JRE directory.
4. Click Next on the Welcome to the InstallShield Wizard for Retail Extensions for
IBM Director panel.
license agreement. Installation cannot continue until you read and agree to the
license terms. Click Next.
6. If you are upgrading from RMA Extensions for IBM Director V2R3 or earlier, a
panel is displayed to notify you that the UPOS peripheral inventory information
will be removed during installation due to database table format changes. After
the upgrade has completed, inventory information will be restored after the first
inventory 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 the
IBM Director application and sets this location for the install. The software must
be installed in the same location that IBM Director is installed; therefore, you
cannot change this location. When you are ready to proceed with the
installation, click Next.
8. The installation takes several minutes. When the process is complete, click
Finish.
Note: If the IBM Director Server is running, the server is stopped so that the
extensions can be installed. If the server is stopped by the installation
program, it is restarted when the installation is complete.
Silent installation of the Retail Extensions for IBM Director for

Windows 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 to
the 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 Windows

This section describes the procedure for interactively uninstalling the Remote
Management 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. Click
Next.
4. If this is the last level of RMA that you are removing from the system, you have
the option to delete the RMA installation directory. A panel (Figure 11) prompts
whether you want to delete the installation directory and all of its contents:
Figure 11. Remove installation directory dialog
Attention: If StoreIntegrator is also installed in the RMA installation directory,

then you should not delete this directory.

5. If this is the last level of RMA that you are removing from the system and you
did not select the option to delete the RMA installation directory, you have the
option to delete the RMA configuration directory, %SI_HOME%\user\rma. The
following panel is displayed, which prompts if you want to delete the
configuration directory and all of its contents:
Figure 12. Remove user directory dialog
6. The Uninstaller panel displays summary information. Click Next.

7. The Uninstaller panel displays the status of the uninstallation operation. RMA is
removed and environment variables are updated as needed.
8. An Uninstaller summary panel is displayed, which confirms if the uninstallation
was 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 that
environment variables can be updated.
Silent uninstallation for Windows

This section describes the procedure for silently uninstalling the IBM Remote
Management Agent on Windows.
1. Log on as Administrator.
2. Refer to the uninstallation section of the sample response file on the installation
CD and use it to prepare your own response file.
3. Run the %SI_HOME%\uninstrma.bat -silent
your_response_file_path_and_name program to uninstall.
4. After uninstalling RMA from a Windows system, you will need to reboot so that
environment variables can be updated.

Uninstallation for Linux
This section describes the procedure for interactively uninstalling the Remote
Management Agent on Linux. When uninstalling the V2R6 agent RPMs on Linux,
the /opt/ibm/StoreIntegrator/user/rma directory might be deleted. The deletion is
triggered by the existence of the /opt/ibm/StoreIntegrator/user/rma/DoNotDelete file.
When the /opt/ibm/StoreIntegrator/user/rma/DoNotDeleteexists, the user directory is
not deleted during uninstallation. By default, the /opt/ibm/StoreIntegrator/user/rma
file will always be included during installation, even if it was previously deleted.
Therefore, you must delete the /opt/ibm/StoreIntegrator/user/rma/DoNotDeletefile
before 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 result
After 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 license
file 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 a
result of uninstallation when rolling back to a previously installed level. When you
are installing only one level of RMA on the system, removal is optional during
uninstallation.
Note: The RMA configuration directory contains all data and configuration files for
RMA. Removal of this folder deletes all of these files, regardless of how or
when they were created.
Retail Extensions for IBM Director uninstallation notes

Installing the Retail Extensions for IBM Director results in IBM Director creating new
persistent objects within its persistent storage mechanism. These objects are tied
directly back to the classes that created them to allow the objects to be recreated
whenever the IBM Director Server is restarted.
Uninstalling only the extensions will cause the IBM Director Servers to crash on a
restart 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 uninstall
IBM Director, remove the IBM Director installation folder (to clear out the Retail
Extensions 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, the
extensions cannot be uninstalled to go back to the previous level after the Retail
Extensions for IBM Director are updated to a new version and the server is
restarted.

Chapter 10. Agent configuration
This section explains how to configure the General Agent or Master Agent after
installation is complete. See “Discovery” on page 67 for information on how to
configure the Retail Extensions for IBM Director.
Directory structure
The 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 Java
archive (JAR) files to be added to the agent class path. This directory
should be used to extend the agent class path.
/classes Directory that is added to the agent class path that contains properties
files 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 file

The 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 of

configurations. The following tables describe the properties in this file. Every
property 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. A
value 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 the
system'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 is
exposed 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 made
to 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 the
agent'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, this
value 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 this

property 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 property
represents the lease duration (in ms) granted to other virtual machines (VMs) that hold
remote references to objects that have been exported by this VM. Clients usually renew a
lease when it is 50% expired, so a short value will increase network traffic and risk late
renewals in exchange for reduced latency in calls to Unreferenced.
rmi.checkInterval
Value for the sun.rmi.dgc.checkInterval system property. The value of this property
represents (in ms) how often the RMI runtime checks for expired Distributed Garbage
Collection (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) or
false.
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.maxevents
The maximum number of events that are stored before the persistence store begins
discarding 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 passes
without 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 persisted
events, will be deleted for a Master Agent (MA). When checked, if the earliest persisted
event 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 incoming
event 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 in
progress 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 the
network. After the initial timeout, file transfer will retry at increasing intervals up to the
maxXferRetryPeriod (the default is 15000).
com.ibm.retail.si.mgmt.capture.maxXferRetryPeriod
Parameter for the maximum timeout period (in ms) for transferring data capture files over
the network (the default is 600000).
Security configuration
The security configuration file is called security.properties. This file is located in
directory %SI_HOME%\user\rma\security.
There are three properties in the security configuration. The first is the security
mode, which is either standard or enhanced. Standard mode security is the only
mode available on RMA V2R4 and earlier; however, standard mode security is still
supported on later versions. Enhanced mode security requires a username and
password to unlock access to a Master Agent.
Chapter 10. Agent configuration 43

The second and third properties are related to enhanced security. The
ConnectionKeyLifetime property defines the lifetime of the authentication
public/private key pair. The RenewKeysPercentOfLifetime property defines the
percentage of the lifetime that passes before the Master Agent generates a key
expiration warning event. The key pair is renewed automatically when the IBM
Director server receives the expiration warning event. The following example shows
the 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 configuration
The use of Secure Sockets Layer (SSL) to create sockets is controlled by the
ssl.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% is
the installation directory for IBM Director. By default, this directory is C:\Program
Files\IBM\Director on Windows and /opt/ibm/director on Linux.
Components that use this functionality create an instance of the RMASocketFactory

with a configuration alias. Depending on the SSL configuration, the sockets created
can be secure or non-secure. The ssl.properties file contains documentation on the
properties and how to configure the configuration aliases.
There are two primary aliases in the file, which are SSL and NOSSL. In most
instances, 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 when
making remote JMX connections using RMI. The RMA alias determines the use of
SSL for connections between a Master Agent and a General Agent. The RMAMA alias
determines the use of SSL for connections between any management application
(including IBM Director) and the Master Agent. When the RMA or RMAMA aliases are
set to NOSSL, authentication for remote JMX connections is disabled.
RMA File Streaming also makes use of the RMASocketFactory. So that streaming
operations are secure, file streaming sockets are always created using the SSL
alias.
It is important that the keystore on each client have the necessary certificates from
each 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 and
truststore, or by having the configuration use a different keystore and truststore that
have these certificates.
The management of the installed keystores is performed using the keytool program
installed with the JRE. Among the functionality that this tool provides is the ability to
view, add, and delete certificates from a keystore.
If the keystore used with the SSL alias is changed from the default, then the new
keystore must contain a certificate to be used by RMA for remote JMX
authentication. The new certificate must be inserted under the alias rsscert.
Updating SSL certificates

RMA uses SSL sockets for communication so that data is encrypted when
transmitted. The certificates used for SSL are also used by RMA to authenticate
connections between IBM Director servers and Master Agents running in standard
security mode. Master Agents running in enhanced security mode do not use
certificates for authentication. A default set of certificates is installed with each
system, providing an initial level of security. Replacing the default certificates with a
custom generated set of certificates will provide an increased level of security. The
certificates must match on all systems across the enterprise network; from IBM
Director, to the Master Agent, to the General Agents. The certificate updates must
be made on each system at once throughout the enterprise, otherwise connectivity
will not be established to all systems.
Note: If Store Integrator (SI) is also used on systems in the network, the
certificates 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 new
certificate 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 password
for these files. Appropriate values should be used in practice.

The key store and trust store files with the new certificate must be put on each
system in the enterprise network. The ssl.properties file on each managed system
in the enterprise network must also be updated with the new filenames and
password.
The property keys in the ssl.properties file that should be updated with the fully
qualified 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 is
F:/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 fully
qualified 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 is
F:/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 automatically
encrypted when the agent restarts and the "_encrypted" suffix will also be
added to the property key.
Agent class path and environment

The environment and class path that the RMA agent uses are set during agent
startup. RMA provides extension points for adding additional entries to the agent
class path or PATH (Windows) that the agent uses.
Java class path

To 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 the
end of the agent's class path. When a level of RMA is uninstalled, these JAR files
are not removed. On 4690 V6 and later, the RMA agent classpath is extended by
setting the %RMACPEXT% user logical file name.
The %SI_HOME%\user\rma\classes directory is of the agent's class path. Java

resources that can be searched for in the class path such as properties files can be
placed in this directory. JAR files can also be extracted into this directory, but it is
not recommended.

Windows PATH
The agent service constructs its own PATH during startup. This PATH includes a
minimal set of directories required to run the agent. To extend this path, define a
system environment variable called RMA_PATH_EXT. The value of this variable will be
added to the end of the agent PATH.
Logging configuration
RMA uses the Commons-Logging API for logging, and the Java logging
implementation. RMA supplies the Java Development Kit (JDK) logging
configuration 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. A
user-provided logging configuration file can also be modified to override logging
levels in the base logging file. The name and location for the user configuration file
is %SI_HOME%\user\rma\ext\user_log.pro. If you make logging-level changes for
RMA extensions or overrides to the supplied levels in this file, the user logging
configuration is preserved when an agent install is upgraded.
As of V2R3, RMA uses a memory logging configuration to buffer high-level logging

messages in memory and only push them to disk when a more serious error
occurs. This change greatly increases the serviceability of RMA but does change
how RMA logging is configured. To understand the changes to logging
configuration, one must first understand how Java logging works.
Java logging is organized in a layered hierarchy that systematically filters and

controls the output that is passed down to the next lower layer. The following image
from java.sun.com/j2se/1.4.2/docs/guide/util/logging/overview.html diagrams this
hierarchy.
Figure 13. Java logging hierarchy
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 handlers
are com.ibm.retail.si.mgmt.logging.RMALogHandler, which handles memory
logging, 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 final
determining factor for what is written to disk. In a similar fashion, the .level
parameter of the logger will determine what is passed down to the handler. By
default, the java.util.logging.FileHandler.level is set to INFO and the
com.ibm.retail.si.mgmt.logging.RMALogHandler.level is set to ALL. This default

only does regular INFO, WARNING, and SEVERE logging on the FileHandler, but
does all configured logging on the RMALogHandler.
Note: The user-provided logging configuration file only overrides the two RMA
handler filters and any logging filter (those properties with the .level
parameter). The user-provided logging configuration is applied after the
RMA-supplied logging configuration. You must restart the agent for an
updated user logging configuration to be applied.
Logging levels
As 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 pushed
to disk on a trigger, the logger (com.ibm.retail.si.mgmt.level) must be configured
to FINE. FINE level logging should be sufficient for diagnosing problems
encountered in a production environment. FINEST level logging provides a much
more granular logging view not necessary outside of a development or lab
environment.
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 the
Commons-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 configuration
files.
Table 7. Java logging levels
Java logging level (Commons-Logging
level) Description
SEVERE (ERROR) Critical errors that warrant the writing of the
memory buffer to disk and collection of other
This is the default configured push level for problem determination data.
RMA memory logging.
Note: Push level will trigger on that level When a SEVERE error has occurred, RMA
and above (for example, SEVERE would will most likely not be functioning properly.
also trigger on a FATAL error).
WARNING (WARN) Serious errors that indicate that some area of
RMA has malfunctioned but is not
threatening the overall operation of RMA.
Also, these errors could indicate a serious
error in a component of the system on which
RMA depends.
When a WARNING error has occurred, RMA

might have timed out on some operation or
connection or might have had an operation
fail that should have completed normally.
INFO (INFO) Informational messages that show the
normal program flow.
This level of logging provides a non-detailed

summary of the program flow for RMA.

Table 7. Java logging levels (continued)
Java logging level (Commons-Logging
level) Description
FINE (DEBUG) Debug level of logging used for determining
the cause of more serious errors by
This is the default configured logging level evaluating the events leading up to the error.
for RMA memory logging.
This level of logging should be sufficient for
problem determination in a production
environment.
FINEST (TRACE) Trace level of logging used for determining
the cause of more serious errors by
evaluating the events leading up to the error.
This level of logging should only be used for

problem determination in a development
environment. FINEST logging provides an
overly granular output of low-level data.
The level of both the handlers and the loggers can be changed dynamically using
the JMX Browser as described in “Adjusting the handler and logger levels using
JMX Browser” on page 102. Modifications to handler and logger levels with the JMX
Browser, however, are only in effect until the agent is restarted. To permanently
modify the handler and logger levels, use the user-provided logging configuration
file at %SI_HOME%\user\rma\ext\user_log.pro.
RMA logging configuration file changes

The RMA logging configuration file (mgmt_log.pro) has a specific subsection to
define the properties for the memory logger. Also, the logging control is centered on
the logging handlers, so the com.ibm.retail.si.mgmt.level is set to FINE by
default.
Table 8. Configurable logging parameters
Property Description
com.ibm.retail.si.mgmt.logging.RMALogHandler.pattern Pattern (file name and path) used for the output
memory logging file
Default: %SI_HOME%/silogs/simgmt_m
com.ibm.retail.si.mgmt.logging.RMALogHandler.limit File size limit in bytes (size of file before wrapping to
next file)
Default: 5000000
Minimum: 1
Maximum: ? (disk-dependent)
com.ibm.retail.si.mgmt.logging.RMALogHandler.count File count limit (number of files to write before purging
oldest file)
Default: 10
Minimum: 1
Maximum: ? (disk-dependent)
com.ibm.retail.si.mgmt.logging.RMALogHandler.formatter Default logging output formatter (file that formats
logging data; in almost all cases leave this as the
default)
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 logging
levels)
Default: ALL
Valid 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: 15000
Minimum: 1
Maximum: ? (memory-dependent)
com.ibm.retail.si.mgmt.logging.RMALogHandler.push Trigger level at which to write logs (defined using
Java logging levels)
Default: WARNING
Valid values: OFF, SEVERE, WARNING
Note: Settings of INFO, FINE, FINER, FINEST, and
ALL will default to WARNING.
Agent startup sequence

The installed Master Agent and General Agents each run in their own JVMs as
system services, and have their own set of MBeans that are instantiated upon
startup. Management agents and other applications might need to change the
startup sequence to add their own MBeans and register their own
NotificationListeners.

MgmtAgentStartupMBean
Each management agent service exposes an interface, the AgentStartupMBean, in
order to facilitate adding to or removing from the agent startup sequence. It has the
following characteristics:
v Maintains its configuration in an XML file that is read and processed when the
MBean 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 operations
on this MBean.
v Process other XML files that contain additional MBeans to create.
Agent configuration
This MBean processes an XML configuration file named AgentStartupConfig_1.xml.
This configuration file contains all of the MBeans to instantiate at startup (after the
default startup sequence has been processed), and all NotificationListeners to
register. 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 created

during startup. Each NotificationListener element under NotificationListeners
represents a NotificationListener to be added after all MBeans have been
created. Only MBeans can be added as listeners to other MBeans, not Java objects
that implement NotificationListener.
To extend the agent startup sequence, all that is required is to create or edit an
XML 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. (For
additional information, refer to the RMAJavadoc.pdf file that is associated with this
user guide.)

Agent roles
Agent roles enable sets of descriptive information to be provided about the device
on which the agent is running. This information gives an additional set of criteria for
identifying groups of agents in addition to platforms, which is useful in applying
storewide policies.
Information from the agent roles takes the form of a role name and an associated
model. By default, the RMA agent comes installed with one of two roles, RMA-GA
or RMA-MA, and an associated model RMA-V2. Upon starting the agent on IBM
hardware not running 4690 OS, the system's four-character machine type is added
as 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, XML
files 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 read
at agent startup and have their information added to the master configuration before
being deleted. The following code is an example of an extension file for adding the
role 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 system
events. You can view these event logs on the system using the Windows Event
Viewer, 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 of
system problems or to predict potential problems.
Events that are added to the Windows event logs can be read by the RMA Master
or General Agent, converted to an RMA (JMX) Notification, and forwarded to other
applications. For example, a management application like IBM Director can
consume these events. You can also configure filters to determine which events are
forwarded 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 truly
pertinent at the enterprise.
Agent configuration file

At startup, the RMA service looks in the %SI_HOME%/user/rma/config/events folder
for a configuration file named Win32EventLogConfig.xml. This file contains the
filtering and mapping information that determines which events are propagated. It
also allows you to configure the severity of error event mappings. This file must be
configured 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 use
RMA Software Distribution to forward the updated configuration file to other
systems.
Event qualifiers
All events in RMA use a dotted notation called event qualifiers to identify a general
event category that is used to filter events on IBM Director and to build event action
plans. 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.

LogType
The log type from which the event originates (Application, System, or
Security).
EventSource
The name of the event source, as defined by the application that sources
the event. Any period (.) character in the event source name is replaced by
an underscore (_) character.
EventCategory
The name of the event category, as defined by the application that sources
the event. If no category is specified, there will not be a fourth qualifier. If
this qualifier contains a period, each half is treated as a qualifier, so that
you can subdivide the categories for further granularity.
For example, a message from the Windows system event log has the following
qualifier:
WindowsEventLog.System.Dhcp
A message from an external application might appear as follows:

WindowsEventLog.Application.MyRetailApp.Printer
Configuration file format

The configuration file format is XML to allow the specification of the qualifiers and
the severity for those event log entries that match. Windows allows special
characters to be included in the source and category names that cannot be used in
a qualifier, so XML provides a format to allow these to be identified. Table 9 shows
the 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 (no
attributes)
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 log
integration (continued)
XML tag Attributes
Filter Entry Definition of an entry in the filter configuration.
sourcename
(Required) A case-sensitive string that contains the source
name 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 the
level 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 use
for error events (global).
Category Definition of the category to match in the filter along with the source
name.
Notes:
1. Either ID or name must be specified.
2. The category tag is ignored if a wildcard is specified in the Filter
Entry. In other words, you can only specify categories on
specific filter entries.
id The numeric identifier of the category of the event to
match.
name A string that contains the category name of the event to
match (which was loaded from the category resource
bundle).
qualifier
The text string to use as the fourth level of the notification
to be sent for matching events.
level (Required) A comma-separated string that identifies the
level 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 use
for 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 more
of the following tags, each of which will only appear once: ApplicationLog,
SecurityLog, and SystemLog. These container tags scope the filter entries for that
specific log type. Those tags will contain one or more FilterEntry tags.
FilterEntry tags define the criteria used to determine if a log entry should be
created in RMA Notification. A filter entry must include a source name. Specifying
the 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, then
include additional tags to indicate the category name and the level to use for that
specific category.
Specifying the level attribute indicates the severity level(s) of the events to be
propagated through RMA. Its comma-separated list contains an entry for each level
to 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 in
RMA.
v A value of WARNING indicates that Warning-level events will create an
RtlNotification in RMA.
v A value of INFO indicates that Information-level events will create an
v If SUCCESS AUDIT is included in the string, then those events will create an
v If FAILURE AUDIT is included in the string, then those events will create an
v A value of OFF indicates that none of the events that match that criteria will create
an RtlNotification in RMA (the event long entry is excluded from creating an
RtlNotification). Note that OFF should be the only member of the string when it is
specified.
The default mapping of event severities is to map an error type Windows event to
an RtlErrorNotification event, which is a Minor severity in the IBM Director log. You
can use the optional errorseverity attribute on either of these tags. However, it will
override the default mapping to allow higher-severity notifications to occur. This
value 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 events
will be forwarded to RMA. Events that have an event source of MyRetailApp and an
event category of Printer that are Warning- or Error-type events are also forwarded
(note that ERROR was already covered in the global category). Therefore, all
Error-type events are mapped to the RMA Minor error severity except for Printer
Warning- or Error-type events, which are mapped to the RMA Critical error severity.

Event mapping
Table 10 shows the mapping between a Windows event log record and an RMA
Notification.
Note: RMA supplies the Event Category and Event Message values that are
returned by the resource bundle lookup for an event source, as defined by
the CategoryMessageFile and EventMessageFile registry keys. Refer to
Microsoft documentation for more details.
Table 10. Mapping Windows event log definitions to RMA Notifications
Windows event log record field RMA Notification field
TimeGenerated TimeStamp
LogType EventQualifiers
SourceName
EventCategory
EventType NotificationType
Strings MessageText
Data UserData
ComputerName OriginatingDevice
DeviceID of the GA that originates the log
The Event Type is mapped using the scheme in Table 11. Note that the RMA
Notification type is the go between bridging the Windows event log event type to
the IBM Director severity, which is why the configuration parameter is expressed in
terms of the IBM Director severity level.
Table 11. Event type to severity mapping
IBM Director
Windows event type RMA Notification type severity
Information Success Audit RtlInformationNotification Harmless
Warning RtlWarningNotification Warning
Error Varies based on configuration settings: Minor
Failure Audit MINOR = RtlErrorNotification Critical
CRITICAL = RtlAlertNotification Fatal
FATAL = RtlCriticalNotification

Example forwarded event
Figure 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 and
forwarded by RMA; and it shows up as follows in the IBM Director event log for the
system 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 peripherals
attached to those devices
v Event viewing and handling, including alert action plans tied to events and
conditions
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

The IBM Director Console provides a main application window that displays all
manageable enterprise systems in a logical manner. The window, as shown in
Figure 16, is divided into three sections: Groups, Managed Objects, and Tasks.
Figure 16. IBM Director Console
Groups
The Groups panel is the leftmost pane of the console window. It displays a list
containing objects that represent specific filters. These filters define the criteria used
to determine if a managed object should be included. When a group (filter) is
selected, the Managed Object panel displays all systems that meet the criteria of
the selected filter.
Managed Object groups

A default group (filter) is added automatically for each unique Managed Object type
(device type) that is discovered. Selecting this group changes the Managed Object
pane 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 the
retail-specific groups under that folder. It also creates a number of hardware-specific
dynamic groups that uses the model type and number information in the Retail
Store Information table to determine membership. Table 12 on page 61 shows the
new groups.

Table 12. Managed Object groups
Icon Group name Description
Anyplace Kiosk Clients Includes all kiosk models, regardless of
platform
IBM SurePOS 100 Clients Includes all Model 4613s, regardless of

platform
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 of
platform
IBM SurePOS 700 Clients Includes all Model 4800s, regardless of
platform
Chapter 11. Using Retail Extensions for IBM Director 61

Dynamic groups
Additional dynamic groups can be created using IBM Director's Dynamic Group
Editor (Figure 17). To start the editor, right-click in the Groups panel and select New
Dynamic from the menu displayed. A Retail Store Information table is included
under the Available Criteria tree, which lets you include retail-specific information in
the filter criteria. To use this information, select Console > New Group > Dynamic
Group > Console > Hardware > Settings > Retail Store Information. A list of the
attributes that are available for selection is displayed.
Figure 17. Dynamic group editor
Managed Objects
The Managed Objects panel is the middle pane of the console window. It displays a
list containing the representation of all devices that match the current filter selected
in the Groups panel. It can display the matching devices in a number of selectable
ways.
Each entry in the middle panel represents a device in the retail space managed
through RMA. These devices can be the target of specific management actions,
such as events, software distribution, and inventory collection.

Managed Object types
There are many types of devices in the retail space and each of them is
represented on the management console using a unique icon to help distinguish
them. 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 device

that is a Master Agent
IRES Branch Server An object representing an IRES Branch

Server (always a Master Agent)
4690 Master Agent An object representing a Master Agent

running on 4690 OS
4690 Controller An object representing a General Agent

running on a 4690 Controller
4690 Terminal An object representing a 4690

Point-of-Sale Terminal
Self-Checkout BOSS An object representing a Self-Checkout

Back Office Server System
Self-Checkout Lane An object representing a Self-Checkout

Lane
Anyplace Kiosk An object representing an Anyplace

Kiosk system
Windows POS System An object representing a Windows

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

Point-of-Sale device

Managed Object states
The management console icons indicate the state of the device, as shown in the
following 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 authorization
credentials have not been provided to allow this store to be managed. For a
general agent, this indicates the system is already managed by another master
agent (as a different managed object) and cannot be managed by a second one.
Managed Object attributes

Each managed object has attributes that uniquely describe something about that
device. These attributes include information about the device and about the Master
Agent to which they are connected. The attributes for a managed object can be
displayed by right-clicking the object and selecting Open. A Display System
Attributes window is displayed, which is similar to Figure 18 on page 65.

Figure 18. Display System Attributes panel
Associations
While the filter controls the members displayed in the center panel, associations
control the relationships between those members and how they are displayed. The
Store Association is included for Retail Systems and listed under the Associations
menu. When selected, it changes the view and displays the retail devices based on
their relationships to each other and to the store of which they are a member. To
select 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 folder
presents all of the managed objects representing the devices managed by the
Master Agent for that store.
Tasks
The Tasks panel is the rightmost pane of the console window (Figure 16 on page
60). 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 of
function, which might be targeted or run stand-alone, and limited to specific types of
managed objects.

The following tasks are specific to Retail Systems:
JMX Browser task
Used to view the JMX information, classes, attributes and methods for
devices that support JMX. It is described in detail in “JMX Browser task” on
page 95.
RMA Software Distribution task
Used to create and manage software distribution packages for delivery to
Retail-Managed Objects. Also used to reconcile the differences between
IBM Retail software distribution packages and IBM Director software
distribution packages. It is described in detail in “RMA Software Distribution”
on page 172.
Retail Peripheral Management task
Used to target tasks specifically for systems that support certain peripheral
devices. It is described in detail in “Retail Peripheral Management” on page
113.
Data Capture Policy Manager task
Used to create, edit, delete, apply, and invoke new data capture policies on
RMA Master Agent systems. It is described in detail in “Data Capture Policy
Manager task” on page 117.
Store Authorization Management task
Used to supply credentials for making connections to locked Master Agents
as well as the ability to backup and restore the authentication keys used by
the Master Agent to connect to General Agents within the store. It is
described in detail in “Store Authorization Management task” on page 72.
RMA File Transfer task
Used to browse the file system and to perform file transfer operations on a
retail device.

Discovery
After IBM Director is initialized, managed objects are added for management
through a process called discovery. Retail Managed Objects are added to the
console by running Discovery for JMX Devices.
Discovery Preferences panel

The configuration for discovery in IBM Director is defined through the Discovery
Preferences 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 retail
devices.
Figure 19. Discovery Preferences panel
The Discovery Preferences panel includes a list of the Master Agents (one per
store) that are managed by this IBM Director Server. A unique name is provided for
each store definition, along with the information needed to connect to this Master
Agent. An IP address or hostname (for Master Agents using DHCP) must be
specified to make the connection to the agent. Click the Connection Log button to
display a dialog with detailed information about the most recent connection attempts
for that entry.
Adding a Master Agent

To add a Master Agent, click Add under the List of Store Master Agents table as
shown in Figure 19. The Define Master Agent panel (Figure 20 on page 68) is
displayed.

Figure 20. Define Master Agent Panel
1. Provide an Entry Name, which is a unique label for each set of store
information entered.
2. Select to use name resolution (DNS) or a static IP address when initiating a
connection to the Master Agent.
Note: If a hostname is used, ensure that the hostname resolves to the correct
IP address for the Master Agent.
3. Select the connection protocol to use for this store. The default protocol
selection 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 select
SOXS or RMI if a store requires a specific connection protocol or special port
number.
For example, a manual configuration is required when connecting to a store
network 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 port
number on the configured routing device. Note that in this example, the
configured connection IP address should be that of the routing device that is
providing connectivity to the store. Forwarding should be configured to direct the
appropriate traffic to the in-store Master Agent.
Another example where manual configuration might be useful is when
connecting to a store network that has network address translation (NAT)
configured on the in-store router. In this case, the configuration should be
manually selected with SOXS and the appropriate port number based on

whether port redirection is configured. The SOXS protocol will connect to a
device 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 are
forwarded up to the IBM Director Server from the Master Agent, and this is
determined based on the event type. The default is for only Fatal, Critical, and
Minor events to be forwarded.
5. Click OK when all of the information has been entered. The new store will be
added to the table displayed.
6. Click OK on the Discovery Preferences dialog to save the modified discovery
preferences information.
Editing a Master Agent

To edit a Master Agent:
1. Select the entry for the store that you want to edit from the table displayed and
click Edit under the List of Store Master Agents table.
2. The Define Master Agent dialog is again shown, but displays the current values
for the edited store already filled in. Modify the values as needed and click OK
when ready.
3. Click OK on the Discovery Preferences dialog to save the modified discovery
preferences information.
Note: If you make changes to the connection protocol settings, they do not take
effect until the next time that the store connection to Director is lost and
reconnected. 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 Master

Agent that has already been discovered and managed causes the previously
defined connection to be terminated. Any managed objects created using
that connection should be manually deleted before running discovery again
with the new connection information, to avoid confusion with multiple
managed objects using the same name but different connection parameters.
Removing a Master Agent

To remove a Master Agent:
1. Select the entries for the stores that you want to remove from the table
displayed and click Remove under the List of Store Master Agents table. A
Remove Master Agent confirmation dialog displays, prompting you with the list
of 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 managed
causes the corresponding connection to be terminated. Any managed objects
created using that connection must be manually deleted.
Importing a list of Master Agents

To 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 following
table.
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 Master
Agents configured to use DHCP) or the IP address to
connect to the Master Agent. These are the valid values:
HOSTNAME
If HOSTNAME is specified, MasterHostname.n must
have a value.
IPADDRESS
If IPADDRESSis specified, MasterIPAddress.n must
have 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 to
IBM Director from the Master Agent for store n. These are
the valid values:
0x0003 = Fatal Only

0x000F = Fatal & Critical
0x001F = Fatal, Critical, & Minor
0x007F = Fatal, Critical, Minor & Warning
0x03FF = Fatal, Critical, Minor, Warning & Harmless
0x07FF = All
MAProtocol.n The protocol used when connecting to the Master Agent for
store 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=3
Storename.1=Chicago 123
MAUseForCnx.1=HOSTNAME
MasterHostname.1=ShopOurStore.chicago.ibm.com
MasterIPAddress.1=
MasterPort.1=10150
Storename.2=Houston 456
MAUseForCnx.2=HOSTNAME
MasterHostname.2=ShopOurStore.houston.ibm.com
MasterIPAddress.2=
MasterPort.2=10150
MAEventFilter.2=0x000F
Storename.3=New York 789
MAUseForCnx.3=IPADDRESS

MasterHostname.3=
MasterIPAddress.3=10.1.1.130
MasterPort.3=10150
MAProtocol.3=RMI
Exporting a list of Master Agents

To export a list of Master Agents:
1. Select the Master Agent definitions to export from the List of Store Master
Agents table.
2. Click Export under the List of Store Master Agents table to bring up the Export
Master 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 Master
Agents” on page 69.
Starting Discovery
The Discovery task is started from the console by clicking the toolbar button on the
far left of the toolbar panel. A discovery engine does a search using criteria
specified for the systems to be added, and creates managed objects for each of the
devices that meet the engine's criteria. For retail, these are systems that implement
RMA. To discover Retail-Managed Objects only, click the down-arrow of the toolbar
button and then select JMX Devices from the list.
For retail, the discovery engine creates a connection to each of the Master Agent
systems defined in the Discovery Preferences Retail Store Devices tab. All of a
retail store's devices are managed using RMA, with the Master Agent serving as the
main point of control. IBM Director connects to each Master Agent, learns about the
devices that are being managed, and creates a managed object in IBM Director to
represent each device known to the Master Agent. The name of each managed
object is the device ID and includes the unique store ID in parentheses next to the
device ID to provide an almost unique name. The only exception is when multiple
RMA agents are running on the same system.
If the Master Agent was installed with enhanced security enabled, then the store
managed object that is discovered for that store is initially in the offline state and
displays a lock icon next to it. This icon indicates to the user that IBM Director is
currently not authorized to manage that device (and store). The user must use the
Store Authorization Management task and provide the username and password for
the store, to authorize this IBM Director server to manage that store. Once the
correct authorization has been established, the lock icon will disappear from the
store managed object and all of the managed systems for that store will appear with
their current state.
RMA General Agents only support connections to a single Master Agent. They
initially 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 key
exchange takes place between the General Agent and Master Agent to create a
unique authorization key that is only known by the two systems. After this point, no
additional Master Agents will be able to connect to the General Agent using the
default key. If a new connection attempt is made, the General Agent will appear as
offline and 'locked' on the IBM Director Console for the additional Master Agent
connection. The Store Authorization Management task allows these connection keys

to be backed up and restored in case the Master Agent system needs to be
replaced. You should regularly backup the keys on a Master Agent, especially when
new General Agent systems are added.
Store Authorization Management task

Master Agents running in enhanced security mode are discovered with a lock icon
next to the managed object icon, which indicates that authorization has not yet
been provided for this managed object and therefore this system cannot be
managed. The Store Authorization Management task allows you to unlock the
Master Agent and manage the security of your connection to each store.
Invoking the task displays a window that allows the user to specify the username
and password that must be used to authorize the IBM Director server to
communicate with the Master Agent system in that store. The task displays all of
the targeted systems in the table, allowing you to work with the authorization of one
store or multiple stores at the same time. This task is used to manage the
authorizations to Master Agents that have been secured ( installed with the
enhanced security option selected). This task is also used to manage the keys
between the master agents and their general agents. There are additional subtasks
available to allow you to backup the keys assigned to the general agents from the
master agent, and to restore the keys from a backed up version to the master
agent.
Figure 21. Store Authorization Management task window
You can select one or more of the targeted systems listed in the table in the Store
Authorization task and choose the Manage Store Authorization menu option. This
launches the Store Authorization Management credentials dialog and allows the
user to enter the username and password that must be used to authorize IBM
Director to manage that store. This username must exist on the system and must
be a member of the security group (varies based on OS). You can use this dialog to
enter the username and password for the initial authorization of a new store or to
update the authorization information for an existing store.

Figure 22. Store Authorization Management credentials dialog
The authorization request is sent when you press the OK button on the dialog, and
then the status information is updated in the table based on the results of the
request. The keys assigned to the general agents by the master agent can be
backed up on the IBM Director server in case a problem requires the master agent
to be reinstalled or replaced. Select one or more of the targeted systems listed in
the table in the Store Authorization task and choose the Backup Client
Authentication Keys menu option. This will launch the scheduler dialog, allowing
you to choose to execute the backup now, schedule it for another time, or schedule
periodically. The keys are stored on the IBM Director server in the
data\rma\authmgmt folder in the install location. The filename is composed of the
store name, the device name of the master agent and an encoded timestamp. Up
to two versions of the backup file will exist. The timestamp is encoded in the
filename with the format yyyyMMddHHmmss. For example, the filename
RtlAuth_Store001_MyStoreServer20090630142311.ckb would contain the backup
for a store named Store001 and the master agent with the device name
MyStoreServer taken on June 30, 2009 at 2:23:11 pm.
Restoring the keys is also done from the Store Authorization task window. Select
the master agent system that you want to restore the keys for, and choose the
Restore Client Authentication Keys menu option. This launches a file dialog
allowing you to select the file to use to restore the keys from. Select the file to use
for the restore and hit OK to restore those keys to the selected master agent.
Figure 23. Select Client Authentication Key File

Inventory
The IBM Director Console provides an inventory task that for collecting the
inventory information for a managed object and storing it in a database table. This
information can be viewed at any time, even when the system is offline, and can be
used to define the criteria for managed object filters (groups).
Inventory collection
Inventory 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 events
exist, then the results of an inventory collection might be delayed.
The inventory collection that is performed on Retail Systems uses the MBean
information that has been gathered by the General Agent for a specific device.
When the Retail Extensions for IBM Director receives the new inventory system
event, it maps that information to the existing IBM Director inventory database
tables.
To start the collection, right-click the device on which you want to perform the
collection, and select Collect Inventory from the menu. To start collecting on multiple
devices at once, first select all of the devices from the list, then right-click one of the
selected devices, and select Collect Inventory from the menu.
The Inventory Service window is displayed to inform you of the status of your
inventory requests. When the inventory has been completed on the device, the
status column is updated to reflect the current status.
Figure 24. Inventory collection panel
Viewing inventory
After the inventory information has been collected, you can view the information for
a 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 of
each branch represents one of IBM Director's Inventory database tables. Selecting
it displays the results of a database query using the selected branch to define the
criteria of the query and contents of that database table in the right-hand panel (the
query results panel).

Figure 25. Viewing inventory browser
Events
The IBM Director Console provides two tasks for managing events. The first is an
event log that you can use to view all of the events that have been received for a
system or group of systems. The second task is event action plans.
Event log
The Event Log displays all of the events for the selected systems. RMA uses a
store and forward methodology so that events that occur when a device or store is
disconnected can be sent when the device or store is reconnected. These retail
notifications are mapped into IBM Director events, and the date and time are set to
when the event occurred.
Event action plans

The real power of events comes in supporting the configuration of actions to be
automatically taken when a specific event or set of events occur. IBM Director
provides support for events to be grouped into families and to provide several levels
of qualifiers. The Retail Extensions for IBM Director forward the RtlNotifications
and MonitorNotifications received from RMA and convert them into IBM Director
Events. After they are received, the event's family and qualifiers are published to be
used within Director's Event Action Plan Builder.
Creating an action event plan

The following steps demonstrate how to create an event action plan to monitor
conditions on a Self-Checkout Lane and to page somebody when a specific event
occurs.

1. Open the Event Action Plan Builder by double-clicking the Event Action Plan
task 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 Filters
panel, and select New > Simple Event Filter from the menu.
a. From the Simple Event Filter Builder window, click the Event Type tab, and
clear 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 that
| causes 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). For
| more information on adding a custom, predefined set of event types to the
| tree, see the “Publishing custom event types” on page 78
c. Save this event filter by clicking Save As. Provide a unique name for this
filter (in the example we chose JMX Monitor Changes) and click OK.
Figure 26. Simple Event Filter Builder
3. Right-click the Send an Alphanumeric Page (via TAP) item in the Actions
panel of the Event Action Plan Builder and select Customize.
a. Select the serial port that the dialing software will use to find the modem
through 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 local
phone 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 Send
entry field. Remember that event data substitution can be used to customize
the message based on the event that has occurred. The pager message is
limited to 256 characters. Click on the Help tab for more details.
e. Optionally, include any special characters required to initialize the modem.

f. Save this event action by clicking the Save As icon on the toolbar. Provide a
unique name for this pager action (in the example we chose "Page
SysAdmin") and click OK.
Figure 27. Event filter
4. Finally, create the new event action plan by bringing up the context menu in the
Event 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 this
example Self-checkout Plan was chosen) and click OK.
a. Select the JMX Monitor Changes event filter created earlier in the middle
panel and then right-click the action plan created above and select the Add
Event Filter menu choice. This will add the selected filter to the plan.
b. Select the Page SysAdmin action created earlier in the right-hand panel
and then right-click the newly added filter in the Event Action Plan panel and
select the Add Action menu choice. This will add the selected action to this
filter in the plan, as shown in Figure 27.
c. Look at the main console and you will see the new Event Action Plan listed
under the Event Action Plans task, as seen in Figure 28. Drag the event
action plan on the main console to one or more Managed Objects to apply
that plan to the Managed Object or Objects.
Figure 28. Newly created Event Action Plan appears in the Tasks frame

| Publishing custom event types
| If you create a custom event types, they must be published with the IBM Director
| Server before they can appear in the Event Action Plan Wizard. To publish the
| custom event type, create an XML file and place it in the Director\proddata\rma
| directory. There is no restriction on the number of files you can create and there is
| no formal naming convention. However, each file you create must have an .xml file
| extension.
| The general format of the xml file is to define a <publishlist> element for each
| event type, with several <publishevent> types inside. Each nested <evtqualifier>
| element provides an event qualifier, which is listed in order. The following example
| defines two event types: MyApplication.Device.Error and
| MyApplication.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 to
| recognize any changes.
Severity mapping
IBM Director event-severity levels are different than those provided in RMA. The
following table shows the mapping between RMA event-severity levels and IBM
Director 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 distribution
The IBM Director Console provides the capability to create software distribution
packages that can be installed on managed systems, and to schedule those
packages for delivery and installation on those systems. Due to differences in the
base IBM Director software-distribution packages, the RMA Software Distribution

task has been created to use IBM Director's underlying distribution framework
alongside the new features needed for RMA. This section describes both of these in
more detail as they relate to retail.
A user can use the RMA Software Distribution task to maintain and distribute
software packages in retail stores. To provide this functionality, the RMA Software
Distribution 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 task
in the task panel on the right side of the console. You can initiate any of the
subtasks by right-clicking the package. The only subtask that cannot be performed
using double or single clicks is the distribution of the packages. This is explained in
the “Software distribution” on page 78 section.
Before deploying RMA Software packages to RMA V2 agents, a one-time

configuration step must be performed on each Master Agent.
RMA Software Package Editor

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

Figure 29. RMA Software Distribution task
Editing a software package

The RMA Software Distribution Package Wizard edits a software package using a
generic flow regardless of whether you are creating a new package or editing an
existing package. On each panel, required data is gathered for the RMA software
distribution framework to complete from start to finish. The information collected
relates to both the general distribution settings and to individual operating systems
data and commands.
Package Wizard general information

This portion of the RMA Software Distribution Package Wizard prompts you for the
general information pertaining to the package: a name and a description for the
package. Along with these fields, you select the target operating systems on which
this package will be used, in addition to the state the system must be in for the
package to be deployed. When ready, click Next to continue to the operating
system settings panels.
Table 17. Package general information
Field Description
Package Name This is the name of the package. The package name
is presented under the RMA Software Distribution task
so that you can differentiate amongst saved
packages.
Package Description This description is used as a comment field to remind
you of the intent of this package.

Table 17. Package general information (continued)
Field Description
Target OS Specifies all the operating systems for which this
package is targeted. An RMA Agent will not be able to
use this package without this information. This
information is also used later in the wizard so that you
can use unique files and commands.
Target State Specifies what the agent's system state is to be in
order for this package to be deployed. For more
information, see “SystemStateManager” on page 227.
Figure 30. Install Package Wizard
Operating system settings

The purpose of this section of the wizard is to set up the package on each of the
operating systems, independent of one another. Each operating system might
require different commands and files to be used during the deployment process.
Each operating system has its own page in the wizard for completing these
settings. If three operating systems were chosen, then three pages are displayed
for you to complete. On each of these pages the operating system is indicated
above the collection fields.

Figure 31. Operating system settings
Destination directory: This is the location on the target system for this operating
system where all needed files will be placed before you run the commands. If the
directory already exists, be sure that the RMA agents have access to the specified
location.
Files: When creating packages, files might be needed to perform special

operations or for installing new programs. You can use the wizard to add files to the
package by clicking Files on the right-hand side of the wizard, which opens a dialog
that shows all of the drives currently connected to the local system. Here you can
select the files to be placed into the package, either from the local system or the
system 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 button
in the panel). By default, the file dialog does not recursively go through all child
directories and add the files to the package. To do this, select the Include
Subfolders check box below the file tree on the left side. Another option to add
files to the package is to save the full path information of the files being added to
the package. By default, when selecting files, the file dialog does not save the full
path information.
The list on the right side of the dialog shows how the files are placed in the
destination directory that is defined in the operating systems page of the wizard. If a
file or directory needs to be removed, highlight it and click the left arrow (bottom
arrow button on the panel).

Figure 32. RMA Software Distribution File Selection panel
Executable commands: This portion of the wizard is used to gather information

for all the commands to be invoked during the package installation. The displayed
interface for entering command information will vary depending on the target
platform. Information for each platform is presented below.
To enter commands, click Commands. This button displays a dialog that shows a
table of the current list of commands that will be invoked during the package
distribution.

Figure 33. Package Commands dialog
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. This
button displays a dialog box in which you can enter the path, arguments, return
code, return code file, and command log (shown in Figure 34).
Figure 34. RMA Software Distribution Add Program dialog

When finished, click OK to save the new command. The new command is placed
into the table at the top.
To remove a command from the package, highlight the command in the table and
click Remove. If you would like to edit a command in the table, just double-click on
the row to open the command entry dialog. You will be in edit mode, so any
changes you make will override the table selection that you double-clicked. Click
Cancel to cancel any changes that you have made.
Adding Commands for 4690 Packages: When you are adding a command for a
4690 OS package, a wizard is displayed that guides you through the process of
creating the command. See “RMA Software Distribution 4690 Command Wizard” on
page 87 for information on creating commands with this wizard.
Post-distribution action: This combination of radio buttons is used to determine

what the package will do when all files have been transferred and all the given
commands have been performed. See Figure 31 on page 82. The choices are: Do
Nothing, Restart Computer, or Restart Computer with Return File. If you
choose Restart Computer with Return File, two text fields at the bottom of the
page 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 progress

This page in the wizard shows the progress of the package saving process after
clicking Finish. For packages containing many files or large files, the
package-saving process might take a long time because all packages are saved
onto the IBM Director Server so that users can access the packages from any IBM
Director Console.

Figure 35. RMA Software Distribution progress panel
The progress panel shows you the current step and its progress, in addition to the
overall progress.
When the wizard finishes creating the package and transferring the files, the
package is ready to use. A dialog notifies you that the package has been
successfully saved. Click OK to close the wizard and the new package is displayed
under the IBM Director Tasks list as shown in Figure 36 on page 87.

Figure 36. Software package subtasks
RMA Software Distribution 4690 Command Wizard

This section describes how to use the 4690 Command Wizard to add 4690
commands to an RMA Software Distribution package. This wizard displays custom
panels for certain 4690 system commands that obtain the required information for
that command in a user-friendly manner. To enter commands, click Commands on
the platform package options dialog. This button displays a dialog that shows a
table of the current list of commands that will be invoked during the package
distribution.
Figure 37. 4690 Package Commands dialog

Adding new commands
To add a new command, click Add from the command list dialog, which will launch
the 4690 Command Wizard (Figure 38). The wizard begins with a list of available
commands.
Figure 38. 4690 Package Commands dialog
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, return
code, return code file, and command log:

Figure 39. 4690 Create Command 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 command

information manually from the command list, this dialog appears for obtaining the
command path, arguments, return code, return code file, and command log:
Figure 40. 4690 Create Command (manually) dialog
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 reboot

terminals 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 41. Re-IPL dialog
After you select one of the command options, click Finish to complete the
command. The command is displayed in the command list dialog.
Apply Software Maintenance (ADXCST0L): The Apply Software Maintenance

command performs operations on one or more 4690 ASM packages. When you
select Apply Software Maintenance (ADXCST0L) from the command list,
Figure 42 dialog is displayed:
Figure 42. Re-IPL window
From this panel, select each product that will be affected by the command and add
them to the list on the right. To add a product, select the product name from the list

on the left and click Add to add it to the list on the right. To remove a package from
the 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 named
Custom ASM Package and click Add.
Figure 43. Custom ASM Package dialog
You will be prompted for information about the package's product control file, which
uniquely identifies the package. After you supply the fifth and seventh characters of
the package's product control file name, click OK and the package is added as a
selected product into the list on the right.
After you select one or more products, click Next to proceed.
Figure 44. ASM product state dialog
Figure 44 dialog opens with a table for each package that you selected in the
previous dialog, along with a drop-down list of ASM states. For each product in the
table, select the desired target ASM state; then click Next to proceed. The final
panel displayed is Figure 45 on page 92, which list the additional command options:

Figure 45. Product options dialog
After you select command options, click Finish to complete the command. The
command then appears in the command list dialog.
Editing Commands
After you create a command with the 4690 Command Wizard, you can edit a
command by double-clicking the command in the command list table, which opens
the command entry dialog. Because you are editing the command, any changes
you 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 your
changes.
Figure 46. Editing a command

Importing Commands
When you are creating a command for the 4690 platform, the commands from an
existing Remote Command Processor (RCP) command file can be imported into the
package. To import a list of commands, click Import on the command list dialog. A
file dialog is displayed where you can select the command file to import. The
command file might be on the server or on the local console. There must be one
command per line in the file in order for the commands to import correctly. Once
imported, the commands appear in the command list dialog and can be edited.
Software package subtasks

You can use the RMA Software Distribution task to perform multiple actions on an
existing software package. These actions are grouped into subtasks, called the
Package Subtasks.
Edit package
From the Task panel of the IBM Director Console, right-click the package to access
the package subtask menu. Click the Edit Package menu item to activate the
subtask 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 the
package. For more information on the Package Wizard, see “Package Wizard
general information” on page 80.
Rename package
the package subtask menu. Click the Rename Package menu item to activate the
subtask that opens a dialog for the new name of the package to be entered. When
the new name of the package has been entered, click OK to save the new name.
Delete package
the package subtask menu. Select the Delete Package menu item to activate the
subtask that opens a dialog to confirm that you want to delete the selected
package. Click Yes to delete the package.
Import package
From the task panel of the Director Console, right-click the RMA Software
Distribution task and select Import Package. The following dialog is displayed for
you to enter or select the location and name of the file from which to import the
RMA software distribution package.

Figure 47. Import RMA Software Distribution Package dialog
Export package
From the task panel of the Director Console, right-click the package to access the
package subtask menu. Click Export Package. The following dialog is displayed for
you to enter or select the location and name of the file from which to export the
RMA software distribution package.
Figure 48. Export RMA Software Distribution Package dialog
Deploying a package
All packages that have been created or imported onto the server are distributed the
same as IBM Director software distribution packages. Drag the package from the
task pane over to the system (or systems) in the Managed Objects pane and follow
the instructions for deployment that appears in the scheduler panel that displays
when the package is dropped.
Note: 4690 Software Distribution packages can only be deployed to 4690 V6 or

later agents that appear in the 4690 Maintenance Capable group. This group
contains all master controllers and all lone controllers in a single controller

setup. Refer to the 4690 publications for information on invoking commands
on a non-master controller from the master controller.
When a software package is deployed to a store, it is retained at that store for 120
days. Therefore, subsequent deployments of the package to systems at that store
are not required to be retransmitted from the Director server to the store. Each
deployment resets the 120 day timer. Additionally, if a network problem occurs and
the entire software package is not transferred, then the next time that package is
deployed, only the remaining portion of the package that was not transferred will be
sent.
These features reduce the amount of data transferred between the Director server
and agents in the stores. In addition, subsequent deployments of the software
package complete in a shorter amount of time, increasing the efficiency of software
distribution.
RMA File Transfer task

The RMA File Transfer task provides support for file transfer operations on
retail-managed objects. The user interface is similar to the IBM Director File
Transfer task but with some of the functionality removed. Those accustomed to
using the IBM Director File Transfer task should find the RMA File Transfer task
easy to use. Refer to the IBM Director publications for further information on the
IBM Director File Transfer task.
Task invocation
You 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 RMA
V2R4 or later. On 4690, you can only invoke the task on a Master Agent that is
running 4690 V6R2 or later. General Agent support depends upon the RMA version
of the Master Agent: the Master Agent must be V2R6 or later. Table 18 summarizes
this support:
Table 18. RMA File Transfer task invocation support
Target managed Required RMA Required Master
object type Platform version Agent 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
4690 V6R2 V2R6 V2R6 or later
General Agent
(controller only)
Note: 4690 OS support is limited to 4690 OS V6R2 only.
JMX Browser task

Retail Extensions for IBM Director includes a task on the Tasks panel specifically for
viewing information at the JMX level (the underlying protocol). The JMX Browser
supports viewing information retrieved using the JMX API from devices that support
JMX. 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 panel

The JMX Browser opens with a tree view of JMX objects for the systems you
selected. Expand the object tree to view categories, instance groupings, and
instances for the specific system.
Figure 49. JMX tree
Each type of tree node is represented by a different icon to help differentiate

between the various pieces. Here is a mapping of the type of nodes:
Category
These tree nodes represent the categories of JMX objects. All children
nodes can be more categories, instance collections, or instances.
Collection
Collections contain one or more JMX instances. The instances do not show
up as child nodes in the tree. Instead, they are selectable in the Instance
panel on the right side.
Instance

Instance nodes represent JMX instances. When an instance is selected, the
Instance panel loads the data from that instance. Unlike a collection, there
is no need to select an instance in the Instance panel.
When navigating through the JMX tree, each category has a small square to the
right of the icon to expand or collapse the view, showing inner categories,
collections, and instances. To view the information for a specific JMX instance, click
the JMX instance in the tree, and its information will be displayed in the JMX
Instance panel on the right side of the browser. If you select a collection of
instances, look for the selectable instances in the top section of the JMX Instance
panel.
Instance panel
This panel shows the property and method information pertaining to the selected
JMX instance. In the case that a JMX Collection is selected in the Tree panel, the
Instance panel will show a list of available instances at the top. When one of the
shown instances is selected, the Property and Method information will be populated
accordingly in the bottom half of the panel.
Properties
Figure 50. Properties tab
The list of properties belonging to the JMX instance is selected in the Instance
panel. All of the readable properties are displayed here, showing each property's
name, type, value, and whether it is modifiable. The property can be determined to
be modifiable if the lock in the Modifiable column is set to unlocked. If a property is
modifiable, the property can be modified by either double-clicking on the property's
row in the table, or by right-clicking and selecting Set Value. It is also possible that
a property that is modifiable cannot be modified using the JMX Browser. Some
property types are not supported by the base JMX Browser but might be enhanced
so that the unsupported properties become supported.
When you choose a property to be modified, a dialog is displayed for you. The
current value of the property is set in the dialog as an initial value. Some property
types can be set to a null value. This option should only be used by those who
understand how the property is being used and how a null value will affect
operations of the selected JMX instance.

Figure 51. Set Value dialog
Click Save to save the current setup of the property for future execution on this or
any other JMX instance of the same class on any device. When you click Save, a
dialog 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 existing
saved task. These saved tasks are found under the JMX Browser task and can be
started by dragging the task to the target device.
Methods
Figure 52. Methods tab
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 method
shown in the method table. All the methods listed can be run by either
double-clicking on the row the method belongs to in the table, or by right-clicking
the row and selecting Execute. Even though all methods are executable, not all the
parameters contained in the methods are supported by the JMX Browser. When a
method is chosen for execution and contains a parameter that is unsupported by

the JMX Browser, you are informed by a dialog.
Figure 53. Unsupported Method dialog
Method Execution dialog

This dialog is used to run the selected JMX Method. At the top of the Method
Execution dialog, information about the selected JMX instance is displayed along
with the name of the selected method. In the middle of the dialog is the input
section, containing all the parameters that must be set in order for the method to
run properly. Each parameter is placed in its own row in the section, providing a
clear view of each parameter's name, type, and current value. The name of each
parameter is specified by the JMX instance.
The values for the parameter can be set by clicking the button to the right of the
parameters, which displays a dialog similar to that used to set the values for
properties in the properties panel. All the same operations can be performed on the
value of the parameter as are available for setting the value of a JMX instance
property. When finished setting the value of the parameter, click OK to save the
value.

Figure 54. Method Execution 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 and
the instance runs the method. After the method has been run, a new section is
displayed 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 or
any other JMX instance of the same class on any device. When you click Save, a
dialog 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 existing
saved task. These saved tasks are found under the JMX Browser task and can be
started by dragging the task to the target device.

Figure 55. Saved JMX Method task

Adjusting the handler and logger levels using JMX Browser
It is possible to adjust the logging handler and logger levels on the fly using the
JMX Browser in IBM Director. The following images identify where this can be done
for the new RMALogHandler and the logger levels:
Figure 56. Handler levels

Figure 57. Logger levels
Resource Monitors
The IBM Director Console provides a Resource Monitors task for setting thresholds
or recording monitorable attributes for a managed object. RMA V2R3 and later
Managed Objects are supported for this task. This section provides an example of
how to create both a threshold monitor and a recording monitor. Further details
about the Resource Monitors task can be found in the documentation for IBM
Director. For releases prior to V2R3, see Appendix D, “JMX Browser Plug-Ins,” on
page 249.

Creating a Threshold Monitor
This section provides an example of how to create a threshold monitor. At the
completion of the steps in this section, a threshold monitor for Hard Disk utilization
will be active on the RMA agent that you selected.
1. From the Director Console, start the Resource Monitors task targeted to a Retail
Client with Windows managed object.
Figure 58. Resource Monitor task
2. From the Resource Monitors task, select and drag the Disk Utilization attribute
from the Available Resources pane to the Selected Resources pane. At this
point, the value for disk utilization will appear and will be updated every few
seconds.
Figure 59. Selecting Disk Utilization resource

3. In the Selected Resources pane, right-click the value for Disk Utilization and
select Individual Threshold. This action will start the System Threshold dialog
for this attribute.
Figure 60. Selecting Individual Threshold
4. Enter a meaningful name and description for your monitor and configure the
other fields as appropriate. For this example:

Figure 61. Threshold configuration
Name A user defined name for the monitor.

Description
A user defined description for the monitor.
Enable to generate events
Selecting this box will cause the agent to generate events when
thresholds are exceeded.
Generate events on value change
Selecting this box will cause an event to be generated every time the
monitored attribute changes value. When this box is checked, the value
of the minimum duration field will be ignored.
Maximum queued events
For retail systems, this box has no meaning as RMA provides its own
method of storing and forwarding events.
Minimum Duration
This field defines how long the attribute must stay in a given threshold

before an event will be generated. A value of 0 in this field will cause an
event to be generated immediately when a threshold is reached.
Resend Delay
This field indicates how long the system should wait before sending
additional events when a threshold persists for a long period of time. A
value of 0 in this field will cause only one event to be generated for
each time a threshold is reached.
Above or Equal/Below or Equal
These 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 and
activate it. This will register the monitor with the in-store Master Agent for the
system 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. The
only interaction between the Director Server and that system will be when the
system generates an event based on the monitor created. In the Resource
Monitors task frame, there is now an icon next to the attribute which indicates
that it has an active threshold monitor.
Figure 62. Example Threshold Monitor
6. To view all created threshold monitors, select View > View All Thresholds from
the main menu. You can edit or delete created thresholds from this view.

Figure 63. All Available Thresholds view
Creating a Recording Monitor

This section provides an example of how to create a recording monitor. At the
completion of the steps defined in this section, a recording monitor for Hard Disk
used space will be active on the RMA agent that you selected.
Client with Windows managed object (see Figure 58 on page 104).
2. From the Resource Monitors task, select and drag the Used Disk Space
attribute from Available Resources pane to the Selected Resources pane.
Figure 64. Selecting Use Disk Space resource
3. In the Selected Resources pane, right-click the value for Used Disk Space and
select Record. This action will start the Resource Monitor Recording dialog for
this attribute.

Figure 65. Selecting Record
4. To create a new recording for this attribute, select File > New from the main
menu.
5. Enter a meaningful name for the recording in the Description field, and select a
value for the Duration field.
Figure 66. Creating a new record
6. When finished, click OK to complete and start the recording. The recording work
for this monitor will be handled on the selected system in the store. The
interaction between the Director Server and that system will be a polling cycle
for 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 when
necessary to diagnose a problem.
7. In the Resource Monitors task frame, there is now an icon next to the attribute
that indicates that it has an active recording monitor.

Figure 67. Example Recording Monitor
8. To view all created recording monitors, select View > View All Recordings from
the main menu. Recordings that you create can be graphed, exported, deleted,
or stopped from this view.
Figure 68. All Available Recordings view
Attention: To reduce network and processor load and to minimize the risk of
problems when restarting the Director Server, you must manually stop or delete all
active recordings before restarting the server. Leaving a recording in progress
across a Director Server restart can lead to unpredictable results.
User-Defined Monitors
From the JMX Browser task it is possible to define a new, monitorable attribute
based on many of the MBean attributes that are provided. The newly defined
monitors are displayed in the Resource Monitors task in a User Defined Monitors
folder, and you can use them in the same manner as the predefined monitors for
thresholds or recordings.
This section provides an example of how to add a user-defined monitor to the

Resource Monitors task using the JMX Browser. At the completion of the steps

defined in this section, a user-defined monitor for the thread count in the RMA
agent JVM will be active on the RMA agent that you selected.
1. From the Director Console, start the JMX Browser task targeted to a Retail
Figure 69. JMX Browser task
2. Right-click the ThreadCount attribute from the JAVA-Threading MBean in the

JMX Browser and select Add User-Defined Resource Monitor.

Figure 70. Selecting Add User-Defined Resource Monitor
3. Enter a meaningful name in the Monitor Name field and select either String
Monitor or Gauge Monitor, if the option is available. Use a String Monitor to
define specific text values that will trigger events; use a Gauge Monitor to define
high and low numerical ranges to trigger the events.
Figure 71. Creating a new user-defined resource monitor
4. When you are finished, click OK to complete. The user-defined monitor is now
available in the Resource Monitors task.

6. In the Available Resources pane, under the User-defined Monitors folder, the
user-defined monitor is now available.
Figure 72. User-defined Monitors view
Importing threshold plan files

Once you have created a set of thresholds to be monitored, it can be saved as a
threshold plan file that you can import onto a server. This is useful for
backup/restore scenarios as well as for distributing monitors across multiple IBM
Director servers.
To import a threshold plan file:

1. From the main IBM Director Console, right-click the Resource Monitors task and
select Import Plan from File, to bring up the Import Threshold Plan from File
dialog.
2. Select the path and filename of a threshold plan file that was previously
exported.
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 a
subtask under the Resource Monitors task.
Retail Peripheral Management

Retail Peripheral Management is a task to help users manage the peripherals
attached to their retail systems. One of the key components of this new task is a
new management console for peripherals, so that certain common tasks can be
targeted specifically for the peripherals, making it easier to perform the specified
task.
Note: Peripheral information is only available if the following has occurred:
1. The peripheral devices must be using drivers that implement the Unified Point
Of Sale (UPOS) Specification, Version 1.9.5 or later.
2. The devices were opened (or opened, claimed, and enabled) by an application
running on the system at the time inventory was collected.
3. An inventory collection was previously performed on the systems with the
devices to manage.
Retail Peripheral Management Console

The Retail Peripheral Management Console provides a platform so that a user can
perform tasks targeted for systems that have specific peripheral devices. This new
task frame for managing peripherals provides you with an interface to select the
device type to work with, display which systems support this device type, and
present 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 the
main IBM Director Console. The leftmost pane is a tree view that displays a
hierarchy whose leaf nodes are device types. The center pane contains the list of
systems that have devices that match the selected device type in the left pane (a
selection in the left pane will filter the list in the center pane). The rightmost pane
shows 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 as
other IBM Director tasks, through both context menu and dragging.
The Retail Peripheral Management task can be invoked on a target set of systems
or can be started untargeted. If started untargeted, device operations are scoped to
include all Retail-Managed Objects. In the targeted case, device operations include
the subset of Retail-Managed Objects from the original target list.
Figure 73. Retail Peripheral Management Console (MSR selected)
In the figure above, the peripheral type of MSR was selected. The center panel's
content 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 retail
system has the selected peripheral device. The information in the database is
accurate based on the last inventory collection request for each retail system.

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 (for
example, 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 that

also 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 Character

Recognition 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 a

tone
Hard Totals An object representing a device that securely stores

and maintains a list of transaction information
internally (this is typically some kind of flash memory
device)
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 (the

machine that gives out the change at a cash register)
Retail Display An object representing a retail display device (touch

and 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 by
Groups the devices displayed for the selected device type using certain
criteria. The choices are:
None No grouping is used.
Model Use the model information for grouping.
Manufacturer
Use the manufacturer information for grouping.
Firmware Level
Use the firmware level for grouping.
Note: If data for the selected grouping criteria is not available, a generic folder will
be added to group all devices that do not have that data. For example,
selecting the Group by Model choice with the POS Printer peripheral type
selected would change the view to as shown:

Figure 74. Retail Peripheral Management Console (using Group by Model)
Invoking the inventory task from the Retail Peripheral Management Console will
start a custom Inventory Query Browser. Use this window to select which inventory
table to display for the specified peripheral type in the left-hand pane, and the
inventory results display in a table on the right.
Figure 75. Peripheral Inventory Query Browser for POS Printer
Data Capture Policy Manager task

IBM Retail Extensions for IBM Director includes a task to the Tasks panel to handle
data capture operations from RMA Agents. This task, the Data Capture Policy
Manager task, is used to maintain and deploy RMA Data Capture Policies to each
retail store. Use this task to create a new Data Capture Policy and perform the
following 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

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 Capture
Policies to the IBM Director Server
Note: This task does not support Data Capture Policies created outside of IBM
director.
The Data Capture Policy Manager task in the tasks pane is used to manage
creation, deletion, and editing of Data Capture Policies. All created Data Capture
Policies are represented as subtasks of the Data Capture Policy Manager task.
These policies can then be associated with RMA Master Agent systems to create
and activate the Data Capture Policies. After Data Capture Policies are associated,
a Data Capture Invocation Status frame can be started from the association to
control and view details of the invocation and transfer of the Data Capture. Each of
these areas is explained in detail below. Also, for more information about the RMA
Data Capture infrastructure, see “Diagnostic Data Capture” on page 184.
Data Capture Policy Manager

Data Capture policies contain configuration information about how to collect data
through the different Data Capture MBeans exposed in the managed environment.
These policies can be associated to specific Managed Objects, to specify when and
how these Managed Objects will collect the captures.
Figure 76. Data Capture Policy Manager task
The Data Capture Policy Manager frame is started in one of three ways, as shown
below.

Note: If you are opening the Data Capture Policy Manager for the first time, it
important that you drag the Data Capture Policy Manager to the Master
Agent. If you do not drag it to the Master Agent, the Data Capture
Implementations area is empty (meaning there are no implementations
displayed on the right-hand side of the Data Capture Policy Manager).
Similarly, if you have recently discovered a new managed object that
includes its own custom data capture implementation (or if you have recently
added a new data capture implementation to an already-discovered
managed object), it is important that you drag the Data Capture Policy
Manager to the Master Agent. Otherwise, the new implementation will be
missing from the Data Capture Policy Manager.
1. By dragging one to many Master Agent Managed Objects to the Data Capture
Policy 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.
Figure 77. Data Capture Policy Manager frame
The frame contains a menu bar and is split in three different panes.
Menu Bar
The menu bar contains two menus: File and Help.
File Menu
The File Menu (see Figure 78 on page 120) has multiple options:

Figure 78. Data Capture Policy Manager File Menu
New > New Policy

The New Policy option will create a new Data Capture policy in the
All Data Capture Policies Group. This is described in the Policies
Pane section that follows.
New > New Policy Group
The New Policy Group option will create a new Data Capture policy
group. This is described in the Policies Pane section below.
Import > Import
The Import option provides the functionality to import created Data
Capture policies from a file, so that they can be restored. This is
described in the Importing Policies from File section below.
Export > Export
The Export option provides the functionality to export created Data
Capture policies to a file, so that they can be saved, moved from
one IBM Director Server to another or both. This is described in the
Exporting 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/existing
policies will be done and a dialog box will appear if any are found
to be invalid. This validation is only that the policies are complete,
not that the given mappings will work (This will not detect if a
Windows Specific Data Capture Implementation was added under a
Linux Terminal. You can use any mapping, even those that might
result in errors when trying to invoke the Data Capture Policies
later.)
Figure 79. Data Capture Policy Manager File-Close Dialog

Help Menu
The Help Menu provides access to the help for the Data Capture Policy
Manager Frame.
Figure 80. Capture Policy Manager Help Menu
Policies Pane (Left Pane)

The leftmost pane shows the existing policies in a tree view component. The
policies are persistent objects in IBM Director and the Data Capture Policy Manager
frame will display all Data Capture policies regardless of which specific Master
Agent 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 will
always be present and will contain All Policies, regardless of what other group they
are in.
Under each group will be Data Capture Policies. Policies can be in one to many
groups, 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. Under
each folder, there will be device types (that is, Retail Systems), and under each
type will be all of the different Data Capture Implementations associated to that
type.
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 Policy
Group, open the File Menu and choose the New > New Policy Group option. This

will open a dialog box that will prompt for the name of the policy group. The policy
group will then be added to the Data Capture Policies Tree. Also, a Task Group will
be created under the Data Capture Policy Manager task to match this group.
Figure 81. Data Capture Policy Manager Policy Group Dialog
Renaming a Data Capture Policy Group: To rename a Data Capture Policy

Group, right-click a Data Capture Policy Group and select the Rename option. This
will open a dialog box that will prompt for the name of the Policy group. The policy
group will then be renamed in the tree and the subtask group will be renamed.
Figure 82. Data Capture Policy Group Context Menu
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 open
a dialog box that will prompt for confirmation. Choose Yes to delete the object and

all of its sub-objects in the tree, or choose No to cancel. If Yes is chosen, the Policy
Group will be removed and its Data Capture Policy Manager subtask group will be
deleted.
Creating a Data Capture Policy: To create a new Data Capture policy, right-click
a Data Capture policy group folder and choose the New Policy option. This will
open a dialog box that will prompt for the name of the policy. The policy will then be
added to the selected Policy Group and the All Policies Group. Also, a subtask for
association of this policy will be created under the Data Capture Policy Manager
task in the main IBM Director Console frame in an appropriate task group to match
the Policy Group Folder.
Figure 83. Data Capture Policy Create/Rename Dialog
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 will
open a dialog box that will prompt for the new name of the policy (this is the same
dialog box as when a new policy is created).

Figure 84. Data Capture Policy Context Menu
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 that
will prompt for confirmation. Choose Yes to delete the object and all of its
sub-objects in the tree, or choose No to cancel. If Yes is chosen, the Policy will be
removed from any Policy Groups it is in and the All Policies Group and its Data
Capture Policy Manager subtask will be deleted. This will remove it from any
Managed Objects with which it was associated.
To delete all Policies under a Policy Group, right-click the Policy Group and choose
the Delete All Policies option. This will open a dialog box that will prompt for
confirmation. Choose Yes to delete all Policies in the Policy Group, or choose No to
cancel. If Yes is chosen, all the Policies will be removed from this Policy Group in
addition to the All Policies Group and their Data Capture Policy Manager subtasks
will be deleted.
Moving a Data Capture Policy to a Policy Group: To move a Data Capture

Policy to a different Policy Group, select the Data Capture Policy and drag it to a
Policy Group. A Policy can be in many groups simultaneously.
Removing a Data Capture Policy from a Policy Group: To remove a Policy

from a Policy Group, right-click the Policy and choose the Remove option. This will
open a dialog box that will prompt for confirmation. Choose Yes to remove the
object and all of its sub-objects in the tree, or choose No to cancel. If Yes is
chosen, 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 and
choose the Remove All Policies option. This will open a dialog box that will prompt
for confirmation. Choose Yes to remove all Policies in the Policy Group, or choose
No to cancel. If Yes is chosen, all the Policies will be removed from this Policy

Group. (This is not an option in the All Policies Group.)
Figure 85. Data Capture All Policies Group Context Menu
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 will
open an export dialog that will prompt for the filename and location. The location
can be either on the IBM Director Console or Server.
To export all Data Capture Policies in a Policy Group to file, right-click the Data
Capture Policy Group and choose the Export All Policies option. This will open an
export dialog that will prompt for the filename and location. The location can be
either on the IBM Director Console or Server.
To export all Data Capture Policies to file, select Export Menu from the File Menu
and choose the Export option. This will open an export dialog that will prompt for
the filename and location. The location can be either on the IBM Director Console
or Server.

Figure 86. Data Capture Policy Manager Export Dialog
Importing Policies from File: There are two ways to import Data Capture
Policies from file.
The first way is to select Import Menu from the File Menu and choose the Import
option. 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 create
all policies from the import file in the All Policies Group.
The second way is to right-click a Data Capture Policy Group and choose the
Import option. 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
create all policies from the import file in the selected group and the All Policies
Group.
These conditions apply to importing policies:

v If any current policies on the system have a name that matches a policy name in
the import, it will fail.
v If any current implementations on the system have a name that matches an
implementation in the import policies, the data in the implementations will be
cross examined and the import will fail if they do not match.

Figure 87. Data Capture Policy Manager Import Dialog
Finding a Data Capture Policy in the Tree: To find a Data Capture Policy in the
Data Capture Policies Tree, right-click in the white space in the tree and choose the
Find option. This will open a find dialog that will prompt for the name to find. This
will search the All Policies Group for this Data Capture Policy and select it.
Figure 88. Data Capture Policy Manager Find Dialog
A second way to find a Data Capture Policy in the Data Capture Policies Tree is to
right-click a Policy Group and choose the Find option. This will open a find dialog
that will prompt for the name to find. This will search the selected Policy Group for
this Data Capture Policy and select it.
Adding Device Types to a Policy: To add Device Types to a policy, select the
Device Type or Device Types from the Device Types Pane (Center Pane) and drag
them to the Policies Pane (Left Pane). They can be dropped onto a Trigger List
Folder, a Capture List Folder, a Policy, or a Policy Group Folder. If they are dropped
on a List Folder, then they will be added to that list. If they are dropped on a Policy
or Policy Group, a confirmation dialog will appear confirming that you want to add
them to all List Folders under that element.
Removing Device Types from a Policy: To remove a Device Type from the
Policy Tree, right-click the Device Type and choose the Remove option. This will
open a dialog box that will prompt for confirmation. Choose Yes to remove the

object and all of its sub-objects in the tree, or choose No to cancel. If Yes is
chosen, the Device Type will be removed from its List Folder.
Figure 89. Data Capture Device Type right-click context menu
To remove all Device Types under a List Folder, right-click the List Folder and
choose the Remove All Device Types option. This will open a dialog box that will
prompt for confirmation. Choose Yes to delete all Device Types in the List Folder, or
choose No to cancel. If Yes is chosen, all the Device Types will be removed from
this List Folder.
Figure 90. Data Capture Policy List Folder right-click Context Menu

Adding Data Capture Implementations to a Policy: To add Data Capture
Implementations to a policy, select Data Capture Implementation from the Data
Capture Implementations Pane (Right Pane) and drag it to the Policies Pane (Left
Pane). They can be dropped onto a Device Type, a Trigger List Folder or Capture
List Folder, a Policy, or a Policy Group Folder. If they are dropped on a Device
Type, they will be added under that Device Type. If they are dropped on a List
Folder, a Policy, or a Policy Group, a confirmation will appear confirming that you
want to add them to all Device Types in that element.
Removing Data Capture Implementations from a Policy: To remove a Data

Capture Implementation from the Policy Tree, right-click Data Capture
Implementation and choose the Remove option. This will open a dialog box that
will prompt for confirmation. Choose Yes to remove the object, or choose No to
cancel. If Yes is chosen, the Data Capture Implementation will be removed from its
Device Type.
To remove all Data Capture Implementations under a Device Type, right-click the
Device Type and choose the Remove All Implementations option. This will open a
dialog box that will prompt for confirmation. Choose Yes to remove all Data Capture
Implementations for the Device Type, or choose No to cancel. If Yes is chosen, all
the 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 tree
of Device Types is built when the Data Capture Policy Manager frame is started
and will not be refreshed until the frame is closed and re-opened. The pane will not
accept 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 to
the Policies Pane (Left Pane).
Data Capture Implementations Pane (Right Pane)

The rightmost pane shows the applicable Data Capture Implementations. This tree
is built in two steps. Step one is to populate the Data Capture Implementation
Groups from the targeted Master Agents. The groups are built when the Data
Capture Policy Manager frame is opened. In the event that any of the chosen
Master Agents are offline, the Data Capture Policy Manager frame will still open, but
will only create new Implementation Groups based on the data from the online
Master 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 (Left
Pane), customized instances of the Data Capture Implementation Groups must be
created. This process will use populated metadata from the Data Capture
Implementation Group that was retrieved from the Master Agent when the Group
was created. If the selected Group does not have any metadata, or the metadata is
blank, the custom implementation takes no parameters and will only prompt for a
name to be entered.
Creating a Data Capture Implementation: To create a new Data Capture

Implementation, right-click a Data Capture Implementation Group and choose the
New option. This will open a dialog box that will prompt for all input data based on
the metadata supplied. Enter all data and select OK to complete, or choose Cancel
to cancel. If OK is chosen, the Data Capture Implementation will be created for this
Implementation Group. If Cancel is chosen, nothing will be done.

Figure 91. Data Capture Implementation Group right-click context menu
Figure 92. Data Capture Implementation Creation Dialog
Editing a Data Capture Implementation: To edit an existing Data Capture

Implementation, right-click the Data Capture Implementation and choose the Edit
option. This will open the same dialog box as the create did, but pre-populated with
existing inputs.

Figure 93. Data Capture Implementation right-click Context Menu
Deleting a Data Capture Implementation: To delete an Implementation from the

Implementation Tree, right-click the Implementation and choose the Delete option.
This will open a dialog box that will prompt for confirmation. Choose Yes to delete
the object, or choose No to cancel. If Yes is chosen, the Implementation will be
removed from its Implementation Group and all Data Capture Policies to which it
has been added.
To delete all Implementations under an Implementation Group, right-click the

Implementation Group and choose the Delete All Implementations option. This will
open a dialog box that will prompt for confirmation. Choose Yes to delete all
Implementations in the Implementation Group, or choose No to cancel. If Yes is
chosen, all the Implementations will be removed from this Implementation Group
and all the Data Capture Policies to which they had been added.
Data Capture Policies

Data Capture policies contain configuration information about how to collect data
through 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 when
and how these Managed Objects will collect the captures.

Figure 94. IBM Director Console with Policy Subtasks
Associating Data Capture Policies

To associate a Policy Manager Subtask with a RMA Master Agent, simply drag the
subtask to the RMA Master Agent, or drag one or many RMA Master Agents to the
subtask. This will associate the Policy Manager Subtask with the chosen RMA
Master Agents and create and activate the corresponding Data Capture Policies on
the chosen RMA Master Agents.
Viewing Associated Data Capture Policies

To view associated Policy Manager Subtasks in the Managed Object (Center) Panel
in the IBM Director Console, right-click the Associations menu and choose the Data
Capture Policies option.

Figure 95. IBM Director Console with associated Policy Subtasks
Manipulating Associated Data Capture Policies

The ability to manually invoke Policy Manager Subtasks will be accessible by way
of a right-click context menu from the association. This menu will display these
options:
v Invoke Policy(s) Now
v View Policy Invocation History
v Remove Policy Association(s)

Figure 96. Policy Subtask Association right-click Context Menu
Removing Policy Associations: The Remove option will remove the association
of the Policy Manager subtask from the RMA Master Agent and terminate and
remove 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 on
the RMA Master Agent systems they are associated with. After the invocation
commands are sent to all applicable RMA Master Agent systems, the Policy
Invocation Status frame will be displayed for the selected policies as described in
“Status Frame for Data Capture Policies.”
Status Frame for Data Capture Policies

To view the status of a policy or policies, select them and right-click to open the
context menu. From the context menu, choose View Policy Invocation History.
(Also, this can be accessed by double-clicking on any policy association.) This will
display the Policy Invocation Status Frame that will provide a view of the current
Capture History status for each selected policy.

Figure 97. Policy Invocation Status Dialog
Viewing Capture History for a Policy

To view a RMA Data Capture History, select a policy from the left pane of the
dialog. This loads the Capture History for the policy from the RMA Master Agent
system with which it is associated. During the loading process a status message
will be displayed at the bottom of the frame. After loading is completed, the right
pane of the dialog will be populated with the Capture History information.
Figure 98. Policy Invocation Status Dialog - Loading Message
Refreshing the Displayed Capture History

This dialog provides a refresh option from the View Menu to refresh the currently
displayed Capture History as shown in Figure 99 on page 136. Also, each time a

different policy is selected, the RMA Master Agent for that policy is queried for
Capture 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 the
data must be retrieved through a remote call to an RMA Master Agent. It is for this
reason that the refreshing of Capture History data will work as described above.
Figure 99. Policy Invocation Status Dialog - Refresh
Deleting from a Capture History

Over time, many Invocation Records can build up for a Data Capture Policy. In a
large or busy environment, users might want to clean up Invocation Records for a
given Policy. Use the Data Capture Invocation Status dialog to delete Invocation
Records from RMA by right-clicking the Invocation Record and selecting the Delete
invocation_record_name option.
Note: This option will not be available until the invocation has completed all
captures.
This prompts the user on whether to delete the record based on the IBM Director
Console Prompting Preferences: Ask for confirmation before deleting any
nonrecoverable item (Options > Console Preferences > Prompting
Preferences).

Figure 100. Policy Invocation Status Dialog - Dialog Context Menu
If the answer is Yes to the confirmation message, a command will be sent to the
RMA Master Agent to delete the selected invocation record. While the delete is in
progress a message will display. When deletion completes, the Capture History for
the selected policy will automatically refresh.
Retrieving the Capture Bundle for a RMA Data Capture Policy

Invocation
After a policy invocation completes, a Capture Bundle is created on the RMA
Master Agent that contains all of the files captured. Use the Data Capture
Invocation Status dialog to retrieve the Capture Bundle from RMA by right-clicking
the Invocation Record and selecting the Transfer Capture Bundle option.
Note: This option will not be available until the invocation has completed all
captures.
The transfer moves the Capture Bundle file from the RMA Master Agent into the
data\rma\capture directory in the IBM Director installation directory on the IBM
Director Server using RMA File Streaming.
The default path is c:\Program Files\IBM\Director\data\rma\capture on a Windows

installation and /opt/IBM/Director/data/rma/capture on a Linux installation. While the
transfer is in progress, the status bar at the bottom of the Data Capture Invocation
Status frame will be updated.

Figure 101. Policy Invocation Status frame - Transferring Message
Note: For large data capture bundles, the progress message might reset to Ready
prior to completion of the transfer.
When the transfer completes, a confirmation dialog box will confirm that the transfer
was either successful, or that an error occurred. The file name of the data capture
bundle is displayed when the transfer succeeds, which will be similar in name to
this 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 management
The IBM Director console provides a power management interface for its managed
objects. 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 and

select an option from the power management group in the context menu.

Figure 102. Power management shutdown and restart selections
Figure 103. Power management power on selections
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. After
the job has been created or scheduled, an entry will appear under the managed
object. To see this entry, the display of jobs must be enabled under the
Associations menu in the Director Console.

Figure 104. Power management job example
The options available from the power management task menu will be different
based on both the type of the managed object and its current state (online or
offline). 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
Shutdown and Power On2, 3, 6
Agent Power Off1 Restart 1
Suspend 1, 6
(Wake on LAN)
Linux General Yes Yes No Yes
Agent, Linux
Kiosk General
Agent
Windows Yes Yes Yes4 Yes
General Agent,
Windows Kiosk
General Agent,
SCS Lane
Master Agent, No Yes No No
SCS Boss, 4690
Controller Master (If the in-store (Wake on LAN
Agent Master Agent is packets are sent
powered off, all from the Master
communication Agent to other
is lost with the devices in the
other agents in store. The
the store.) Master Agent
must be online
for this to work.)
4690 Controller Yes Yes No No
General Agent

Table 20. Power management support by Agent type (continued)
Shutdown and Power On2, 3, 6
Agent Power Off1 Restart 1
Suspend 1, 6
(Wake on LAN)
5 5
4690 Classic Yes Yes Yes5 No
Terminal
4690 Enhanced Yes5 Yes5 Yes5 Yes
Terminal
Notes:
1. Shutdown and Power Off, Restart, and Suspend are available when the
managed object is online.
2. Power On (Wake on LAN) is available when the managed object is offline or
suspended.
3. Power On (Wake on LAN) functionality requires that system BIOS and network
settings are configured properly to support Wake On LAN.
4. Suspend functionality requires that system BIOS and network settings are
configured properly to support Wake On LAN. The system hardware must be
able to support the suspend function.
5. Refer to the 4690 publications for the situations in which power management is
supported on a terminal.
6. Due to the continual network communication between a Master Agent and
General Agent in an RMA environment, the network card on a General Agent
must be configured to only allow management stations to bring the computer
out of standby or to only Wake on Magic Packets, for Suspend and Wake On
LAN to work properly.

Chapter 12. Troubleshooting
This section helps you find information about troubleshooting problems with the IBM
Remote Management Agent or the Retail Extensions for IBM Director.
Logs
Log data is produced for the Master Agent, General Agent, and Retail Extensions
for IBM Director.
RMA Agents
The logs for the Remote Management Agent are written to the following locations
depending on the operating system. If the product is installed on the default
location, 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. The
memory log files are named simgmt_m.X, with simgmt_m.0 being the most recent
file. 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 the
default 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” on
page 47.
Additionally, the RMA Agents have the output from the standard out and standard
error streams redirected to files, rma.stdout and rma.stderr, in the silogs directory.
Agent JVM Diagnostics

The MgmtJVMEnvironment MBean in each agent exposes instrumentation for the
Java virtual machine that the agent is running in. This information can be helpful in
diagnosing problems in the agent JVM. Also of the MBean interface are two
methods, javaDump() and heapDump(), which produce core dumps and heap dumps
from the agent JVM. The javaDump() method produces a Java core text file and the
heapDump() method produces heap snapshot files with the .phd extension. These
files 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 Director
The Retail Extensions for IBM Director use IBM Director Logging (RAS Logging) to
provide log information. You should only enable logging for IBM Director when trying
to debug a problem. Enabling logging can result in a significant performance
degradation.
Note: You can troubleshoot connection issues between IBM Director Server and
specific Master Agents by clicking Connection Log on the Retail Store
Devices tab of the Discovery Preferences window.
This information assumes that IBM Director is installed into its default location on
Windows (C:\Program Files\IBM\Director). The files or directories referenced in this
section will reside in the same subdirectories when IBM Director is installed to a
different location.
Director Event Configuration

The Retail Extensions for IBM Director provide a configuration option to tune the
rate at which the extensions provide events to IBM Director. The default rate is 900
events per minute, and it can be changed by specifying the
RMA.event.handler.events.per.minute property in the Director installation path in
the \data\TWGServer.prop file. This value will balance the amount of events
buffered to disk versus those buffered in memory. The rate can be raised or
lowered to control the amount of memory that the Director Servers process uses.
RAS Logging
The Retail Extensions for IBM Director use the IBM Director logging API. The
information provided is designed to enable log collection and the enablement of
tracing for Retail Extensions. For detailed information about troubleshooting IBM
Director, refer to the IBM Director documentation.
Log Collection: The easiest way to obtain the logs is to use the rasdump utility
to dump the logs, and to redirect the log output to a file. From the IBM Director log
directory, run the rasdump program and redirect the output to a file. This example
shows 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.properties

file, it is necessary to run the rasdump command as follows in order to see the full
log:
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 IBM
Director 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.

Figure 105. TWGRas.properties file
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 the
different components. The following components should be enabled when logging is
needed. Note that a value of -1 for twg.ras.comps will enable tracing for all
components, 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 to
capture a set of logging data.
JVM Diagnostics
IBM Director provides a command line interface for invoking tasks, using the dircli
program. This interface can be used for producing Java core dumps or Java heap
snapshots of the IBM Director Server JVM to help diagnose problems. To produce a
Java 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.
Chapter 12. Troubleshooting 145

Troubleshooting
Use Table 21 to determine the action to take due to symptoms of common
problems.
Table 21. Common symptoms
Problem or symptom Solution
RMA devices do not 1. Check Discovery Preferences and verify settings for Master
display in the IBM Director Agent are correct.
Console.
2. Check the Connection Log for the Master Agent's entry in
the Retail Discovery Preferences panel.
3. Verify that there is an active network connection between
the Master Agent and the IBM Director Servers.
4. Check the configured network interface in simgmt.pro on
the Master Agent.
5. Check the General Agent logs to see if there were errors
starting the General Agent.
6. Check the Master Agent logs to see if there were errors
making a connection to the General Agent.
7. Verify that RMA discovery multicast packets are being sent
between the computer running the General Agent and the
computer running the Master Agent.
General Agent devices not 1. Check firewall settings on Master Agent.
discovered or offline on
2. Check firewall settings on missing General Agents.
3. If your General Agents are on a different subnet than your
Master Agent, verify that the TimeToLive parameter is set
accordingly in simgmt.pro on each General Agent.
On Windows the RMA Check the Windows Application and System logs in the
Agent service is not Windows Event Viewer for detailed error messages.
started or returns an error
message when starting.

Part 3. Objectives and architecture
Chapter 13. Architecture overview and objectives . . . . . . . . . . 149
IBM Remote Management Agent disciplines. . . . . . . . . . . . . . 149
Java Management Extensions . . . . . . . . . . . . . . . . . . . 149
Mid-level management . . . . . . . . . . . . . . . . . . . . . 150
Management model. . . . . . . . . . . . . . . . . . . . . . . 151
Chapter 14. Understanding the architecture . . . . . . . . . . . . . 153

RMA Component. . . . . . . . . . . . . . . . . . . . . . . . 153
General Agent. . . . . . . . . . . . . . . . . . . . . . . . 153
| Embedded Agent . . . . . . . . . . . . . . . . . . . . . 153
Master Agent . . . . . . . . . . . . . . . . . . . . . . . . 153
Component's relationship and roles . . . . . . . . . . . . . . . . . 154
Agent discovery and health checking . . . . . . . . . . . . . . . . 154
MgmtMasterHealthMBean . . . . . . . . . . . . . . . . . . . 154
MgmtClientHealthMBean . . . . . . . . . . . . . . . . . . . . 154
Agent application roles . . . . . . . . . . . . . . . . . . . . 155
| Embedded Agent (General Agent) . . . . . . . . . . . . . . . . . 156
| Proxy ObjectNames . . . . . . . . . . . . . . . . . . . . . 157
| Events . . . . . . . . . . . . . . . . . . . . . . . . . 158
| JMX Browser Changes for Local Mode Embedded Agents . . . . . . . 158
| Existing Managed Objects . . . . . . . . . . . . . . . . . . 158
RMA event infrastructure . . . . . . . . . . . . . . . . . . . . . 159
RMA events (RtlNotifications) . . . . . . . . . . . . . . . . . . 160
EventControlMBean . . . . . . . . . . . . . . . . . . . . . 161
Client configuration . . . . . . . . . . . . . . . . . . . . . 162
NotificationProcessor . . . . . . . . . . . . . . . . . . . . . 162
MgmtNotificationControlMBean . . . . . . . . . . . . . . . . . 162
Logging configuration and forwarding . . . . . . . . . . . . . . . . 162
Inventory . . . . . . . . . . . . . . . . . . . . . . . . . . 163
CIM Implementation . . . . . . . . . . . . . . . . . . . . . . 163
CIM Adapter MBean . . . . . . . . . . . . . . . . . . . . . 164
CIMEventMapper interface . . . . . . . . . . . . . . . . . . . 165
Default extrinsic event registrations . . . . . . . . . . . . . . . 166
UPOS indications . . . . . . . . . . . . . . . . . . . . . 166
RSS_SpNumericSensorAlert indications . . . . . . . . . . . . . 166
MSStorageDriver_FailurePredictEvent indications . . . . . . . . . . 166
CIM configuration . . . . . . . . . . . . . . . . . . . . . . 167
File Transfer . . . . . . . . . . . . . . . . . . . . . . . . . 168
FileTransferConnection . . . . . . . . . . . . . . . . . . . . 169
Managing file transfer implementations . . . . . . . . . . . . . . 170
Storage . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Monitor policy . . . . . . . . . . . . . . . . . . . . . . . . . 171
RMA Software Distribution . . . . . . . . . . . . . . . . . . . . 172
RMA Package Distributor MBean . . . . . . . . . . . . . . . . . 174
Package JAR file format . . . . . . . . . . . . . . . . . . . 175
Getting package files to the Master Agent . . . . . . . . . . . . 175
Package staging . . . . . . . . . . . . . . . . . . . . . . 176
Software Distribution Policy . . . . . . . . . . . . . . . . . . . 178
Software Policy XML file structure . . . . . . . . . . . . . . . 180
Policy XML variables . . . . . . . . . . . . . . . . . . . . 184
Diagnostic Data Capture . . . . . . . . . . . . . . . . . . . . . 184
DataCaptureMBean. . . . . . . . . . . . . . . . . . . . . . 185
Capturing Data . . . . . . . . . . . . . . . . . . . . . . 185

Capture Processing. . . . . . . . . . . . . . . . . . . . . 186
DataCaptureMBeanSupport . . . . . . . . . . . . . . . . . . . 187
Data Capture Policy . . . . . . . . . . . . . . . . . . . . . 188
RMADataCaptureMBean . . . . . . . . . . . . . . . . . . . . 189
DataCaptureManagerMBean . . . . . . . . . . . . . . . . . . 189
DataCapturePolicy class . . . . . . . . . . . . . . . . . . . 190
Capture policy application . . . . . . . . . . . . . . . . . . 191
Capture bundle directory . . . . . . . . . . . . . . . . . . . 191
Policy invocation . . . . . . . . . . . . . . . . . . . . . . 192
Post Capture File Transfer and Processing . . . . . . . . . . . . 192
Retries 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 all
management applications behave in a consistent manner.
v Expose device and application instrumentation.
IBM Remote Management Agent disciplines

IBM 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 and
hardware components.
Inventory Provides support for local and remote inventory reporting of both software and
hardware components. For software components, the inventory information
typically includes product description, product manufacturer, and product version
information (including maintenance levels).
Event notification and forwarding Hardware and software components can generate notification events that are
monitored by IBM Remote Management Agent applications. The events can
include normal operational or error information. The architecture presents a
multi-tiered framework for collecting and filtering events at the store level for
access by an enterprise system management application.
Remote operations Component MBeans within the IBM Remote Management Agent can provide
various remote operations.
Software distribution Provides support for the automated installation or uninstallation of software
packages.
Monitoring Provides support for the monitoring of MBean attribute values with notification
events 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-wide
policies to transfer capture files and invoke captures on other components.
File transfer Provides support for performing file operations remotely, including the ability to
send, receive, and view files.
Java Management Extensions

The IBM Remote Management Agent architecture is based on Java Management
Extensions (JMX). The JMX Specification describes a general management
framework for any Java (or even non-Java) program. It is a multi-tier architecture
that includes an instrumentation layer, MBeans, an agent layer, MBeanServer, and
a management layer. MBeans are Java objects that expose a management
interface for a managed resource.
All MBeans within a Java virtual machine are registered with an object repository
called an MBeanServer. The MBeanServer provides access to each MBean's
attributes and operations, and it handles the sending of notifications (events).

MBeans become useful for the IBM Remote Management Agent when their
interfaces are exported so that they can be accessed by remote management
applications. Refer to the latest Java Management Extensions (JMX) Specification
(java.sun.com/products/JavaManagement/) to obtain complete information about the
JMX framework. JMX is used both internally and externally to implement the
disciplines discussed above.
Mid-level management
The IBM Remote Management Agent uses a mid-level manager or proxy approach
to isolate the management tools from the infrastructure and to treat the store as the
point of management control. It does this by acting as a proxy for all of the
resources (JMX MBeans) in the store. This single store, single agent view becomes
the interface for all outside management actions. Collectively, this environment is
referred to as the Remote Management Agent. It introduces a new point of
collection and control in the store that becomes the focus of all outside
management actions, and is responsible for executing all management actions.
Figure 106 is a diagram of the mid-level manager environment.
Figure 106. Mid-level management
Figure 106 shows how the IBM Remote Management Agent is modeled using the
mid-level manager approach. All instrumentation exposed on the managed devices
has a single implementation model and is provided by the vendor of the device
being managed, not by the management application vendor. The agents provided
by management tool vendors are neatly contained above the mid-level manager
(Master Agent) and have equal access to the system.

Management model
The IBM Remote Management Agent model is broken down into well defined roles,
with well defined relationships among them. The goal to make it easier for
developers of non-IBM software and users who want to build upon the available
software to know where in the model their component fits, and what their
responsibilities are in building that component. All IBM Remote Management Agent
code falls into one of the following four roles, and must adhere to the defined
responsibilities 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, and
exposes 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 management
sub-agents and management agent(s).
v Exposes a collective management interface representing all management
sub-agents for use by all management agents and management applications.
v Manages filtering and forwarding of notifications to Management Agents and
Management Applications.
v Provides a point of implementation and control for store-wide policy (such as
software distribution and monitor control).
3. Management Agent (optional):
v Uses the Management Agent API for interacting with management
sub-agents.
v Central point of contact and communication proxy for its corresponding
management application.
v Single presence of the management vendors toolset in the IBM Remote
Management 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 Remote
Management 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 Java
Management Extensions (JMX), which is the management and instrumentation
standard for Java. JMX is defined by JSR-003, and deals only with management
issues within the context of a single JVM. Each agent running within the IBM
Remote Management Agent environment is built upon a single JMX agent
(MBeanServer) and on instantiated resources registered with the agent called
MBeans.
To complete the IBM Remote Management Agent infrastructure hierarchy, some

additional remote connectivity support is required. This support provides the
communications bridge between each of the management roles previously
discussed. The standard that defines the remote interfaces for accessing a JMX
Agent, JSR-160, provides this remote connectivity support.
The following sections describe the primary components of the IBM Remote
Management Agent infrastructure.
RMA Component
| Two primary components make up the JMX infrastructure for the IBM Remote
| Management Agent environment: the General Agent and the Master Agent. Both are
| required by the IBM Remote Management Agent to manage the store. Their roles
| are distinguished by the MBeans that are attached to them, with the General Agent
| receiving MBeans designed for the client, and the Master Agent receiving those
| required for control of the store.
General Agent
The General Agent is designed for use within all endpoint devices within the store
network. Examples include the POS controllers and terminals, Mobile Tablets for
Retail, and kiosks. The General Agent, by default, includes MBeans to handle client
discovery, provide JVM information, and handle the configuration and forwarding for
| logging. It can be instantiated from inside an application JVM as an embedded
| agent, or run as a service in its own JVM.
| Embedded Agent
| Embedded Agents are General Agents that get instantiated within an application
| JVM. With RMA V2R6, embedded agents include a local or remote embedded
| agents, as discussed in “Embedded Agent (General Agent)” on page 156.
Master Agent
The Master Agent is the single point of access for all store resources. It is based on
the same functionality as the General Agent, and devices that it runs on can be
managed. To manage the rest of the devices in the store, the Master Agent has an
additional set of MBeans loaded at agent startup. This set of MBeans includes
those MBeans for managing the proxy relationships with General Agents running
within the store. Additionally, there are policy MBeans managing software
distribution, monitors, and notifications.

Component's relationship and roles
The role of the Master Agent is to discover the General Agents that exist within the
environment, to create proxy MBeans for MBeans that exist on those General
Agents, and to control all interactions among them. By doing this, a single view of
all MBeans in the environment are presented at the Master Agent, giving the
management application a single point of control for the entire environment.
Note: Only one Master Agent can manage a given General Agent. The first Master
Agent to discover a General Agent will be the only agent that is allowed to
connect to that General Agent.
This functional hierarchy becomes more important for disciplines that require some
distributed policy control, such as software distribution or device monitoring.
Components responsible for managing a discipline on the Master Agent interact
with the appropriate General Agent MBeans to carry out an operation based on
notifications emitted when devices are online or offline.
Agent discovery and health checking

The Master Agent component provides discovery of general agents within the store,
and monitors their continued health and status. This function provides a simple
discovery and health checking mechanism that is both reliable and inexpensive in
the store environment. This function group triggers the creation and deletion of
device information on the Master Agent. These triggers, in the form of JMX
Notifications, can be used by other management applications to trigger
management functions, like inventory.
Implementing this function requires two MBean interfaces: MgmtClientHealthMBean

and MgmtMasterHealthMBean. The MgmtClientHealthMBean interface, implemented as
the General Agent, provides a simple periodic heartbeat containing agent
information. The MgmtMasterHealthMBean interface, implemented as the Master
Agent, listens for client heartbeats, emits notifications when agents are discovered
or go offline, and maintains information about each discovered agent. It also
registers to listen for JMXConnectionNotifications from the JSR-160
implementation.
MgmtMasterHealthMBean
The MgmtMasterHealthMBean is located at one place in the store: the Master Agent
running 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 between
management agents.
Note: Other functions on the Master Agent are driven by these notifications, such
as pending software distributions, application of monitors, and any other
specific response that might be required by management applications.
MgmtClientHealthMBean
This entity is located within each General Agent running within the store, and is
responsible 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 mechanism

for determining the status of General Agents on the network. This mechanism is
comprised of two components, where the MgmtClientHealthMBean is located within
the General Agent and is responsible for generating a heartbeat at regular,
configurable intervals. The second component is the MgmtMasterHealthMBean, which
is located in the Master Agent. Its job is to listen for the heartbeats generated by
the General Agents, and use that to decide whether the heartbeat represents a new
device or an existing healthy one. However, if the Master Agent misses a
configurable number of heartbeat frames (as defined on the client, and carried in its
heartbeat frame), then the device is considered to be offline by the Master Agent.
The RMA Master Agent generates two different Notifications, one for a General
Agent coming on-line, and one for a General Agent going off-line. These
notifications are used internally by the Master Agent to control the creation and
removal of proxied MBeans at the Master Agent that control the visibility of those
MBeans in the complete Remote Management Agent environment. Since these are
JMX Notifications, they can be used by Management Applications using the Remote
Management Agent, or by other local MBeans as the applications requires. For
example, 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 requirements
on the system and network. Generating these discovery frames requires very little
of the system, and consumes almost no network bandwidth. Since this mechanism
is based on Multicast traffic, there are trade-offs. While it presents limited demands
on the system and network, it does require some forethought when configuring the
network. Multicast traffic is confined to a single IP subnet and therefore is an asset
for 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 no
special considerations to setting up the network. However, if the store contains
more than one subnet, and devices exist on those multiple subnets that need to be
discovered as the Remote Management Agent's domain, then the routers between
those subnets must be configured to pass the discovery multicast traffic. Also, the
Time to Live (com.ibm.retail.si.mgmt.generalagent.discovery.ttl) parameter
must be configured accordingly on each RMA General Agent in the simgmt.pro file.
For purposes of configuration, the Discovery mechanism employed in the Remote
Management 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 a

discovery frame from an agent, indicates it is available, and causes a missed
interval 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 considered
off-line.
Agent application roles

During agent startup, each General and Master agent automatically detects its
device type, indicating the platform (for example, Windows XP, Linux, or 4690). This
information, along with the agent's device ID, is kept with the device information for
each agent (com.ibm.retail.si.mgmt.MgmtDeviceInfo). It is also useful in applying
policies to agents running in the store, where policies can be applied to all agents
based on device type. However, device type alone might not always provide enough
flexibility 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 have
one or more application roles assigned to them. These roles indicate which
applications 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 RMA
Master or General Agent, and are exposed as agent attributes, just like device ID
and device type. The MgmtMasterHealthMBean and MgmtClientHealthMBeans
(Discovery) contain an attribute for their roles. Additionally, a getModels() method
exists to get the model numbers for a role. The role and model information for all
agents 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 application
| JVM. Prior to RMA V2R6, embedded agents and RMA Service agents were
| discovered by a store Master Agent in the same manner. The Master Agent made a
| separate JMX connection to each General Agent, regardless of the type. Each
| agent was treated as a separate device by the Master Agent, and in IBM Director
| each agent appeared as a separate managed object. Figure 107 illustrates an
| Embedded Agent model prior to RMA V2R6:.
|
|
|
| Figure 107. Embedded Agent model (Prior to V2R6)
|
| The design for embedded agents was changed in RMA V2R6 to include two
| embedded agent modes: local or remote. A remote mode embedded agent is
| discovered as a separate management object with its own JMX connection, which
| is the design for RMA V2R6 or earlier. Local mode embedded agents are
| discovered locally by an instance of the RMA Service agent. The embedded agent's
| instrumentation is accessible through the JMX Connection to the RMA Service
| Agent, through MBean proxies. As a result, the embedded agent's instrumentation
| is accessible only when an RMA Service agent is running and has discovered the
| agent. Figure 108 on page 157 illustrates an Embedded Agent model for RMA

| V2R6 or later releases:
|
|
|
| Figure 108. (V2R6 or later)
|
| In addition to specifying the agent mode (local or remote) when creating an
| embedded agent, an optional agent ID can be supplied to identify the JVM or
| application the agent is running in. This agent ID will be seen inside the JMX
| Browser in the IBM Director.
| Proxy ObjectNames
| The ObjectNames for embedded agent proxy MBeans conforms to a set of
| conventions in order to make the names unique, and in order to be able to easily
| locate MBeans registered with each embedded agent. In addition to the deviceId
| and systemId keys already added to MBean ObjectNames, an additional agentId
| key is added to each proxy ObjectName. Non proxy MBeans registered with the
| service agent will not have the agentId key:
|

|
|
| Figure 109. Proxy Objectnames
|
|
| Events
| When running in local mode, events sent by any embedded MBean are received by
| the service agent, where they are forwarded to the RMA event infrastructure for
| delivery up to a Master Agent. When the RMA Service agent is not connected to an
| embedded agent, events sent from within the embedded agent are not stored for
| later delivery to the service agent. However, once events are received by the
| service agent, they are stored and forwarded if the service agent is not connected
| to a Master Agent.
| JMX Browser Changes for Local Mode Embedded Agents

| The JMX Browser in V2R6 and later provides functionality to separate and easily
| browse 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 RMA
| Service agent is always present (even for older managed objects), and will have its
| instrumentation listed under RMA Service, which is always listed first. Any
| embedded agents are listed under a node with the Embedded Agent: title, along
| with its agent ID.
| Existing Managed Objects

| Customers who have discovered older embedded agents have multiple IBM
| Director managed objects for those agents, which all have the same name. After
| making changes to use local mode embedded agents, those managed objects will
| stay offline permanently (unless the embedded agent is run in remote mode). The
| older managed objects are not automatically removed. You will need to manually
| delete the objects.

RMA event infrastructure
The RMA event infrastructure provides access to all events emitted in the store. On
each agent, all events sent by agent MBeans are received and processed by an
EventControlMBean. The manner in which events are processed depends on
whether 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 when
disabling store and forward, as all events that take place on agent startup before a
remote connection has been established will be lost. This can also prevent software
distribution tasks that cause an agent to reboot from completing successfully on the
IBM Director Server. When store and forward is enabled, events are delivered to
each remote connection. When not connected, the events are buffered and
periodically persisted. RMA also takes over the transport of the events from JMX
when store and forward is enabled, because JMX does not provide guaranteed
delivery.
On the Master Agent, events emitted from all General Agent EventControlMBeans
and Master Agent MBeans are received by the NotificationProcessor and
forwarded to the MgmtNotificationControlMBean, where they are processed and
re-emitted for listening management applications. An EventControlMBean also exists
on the Master Agent, so that Management applications can receive events from all
agents in the store from one location. Figure 110 on page 160 outlines the RMA
Event Infrastructure.

Figure 110. Event infrastructure
RMA events (RtlNotifications)

RMA provides its own event classes in order to provide additional information
specific to RMA, and to provide each event with a severity. The base class for all
RMA 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

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, RtlNotification

subclasses provide additional information that base JMX Notifications do not. An
example of this is translation information for the event message. A resource bundle
class, message key, and message parameters (passed to MessageFormat) can be
set on each RtlNotification and can be used wherever events are displayed.
RtlNotification also supports the concept of event qualifiers, which is a set of

ordered strings intended to describe the type of event. The idea is for each string to
go from general to specific, describing the event in a hierarchical manner. A string
array of event qualifiers can be set on each RtlNotification. The setting of event
qualifiers is optional. A default array ("Retail," "base") is set on each
RtlNotification by default.
When events are transmitted, the RMA event infrastructure updates a field in each
RtlNotification that has a MgmtDeviceInfo object corresponding to the agent that
sent the event. The MgmtDeviceInfo can be accessed from the
getOriginatingDevice() method. The Store ID in each MgmtDeviceInfo instance will
be null until it is received by a Master Agent.
Like JMX Notifications, an object can be supplied to the notification as user data. It
is important to use objects whose types can be resolved in all Java virtual
machines. Otherwise, RMA will be unable to deserialize event objects as they are
transferred between agents. Strings, Java primitive wrapper types (Integer, Double,
Long, and so forth), and collections of these types are viable options. Also, the
RtlNotification subclasses should not be further subclassed, for this same
reason.
EventControlMBean
The EventControlMBean forms the client portion of the RMA event infrastructure. It
acts as a central point of control and access for all events emitted on the RMA
Agent. On the General Agent, this MBean adds itself to all MBeans that emit
events. On the Master Agent, this MBean adds itself as a listener to the
MgmtNotificationControlMBean. Upon receiving an event, it either re-emits it or
buffers the event, based its connectivity status of the remote connection, (Master
Agent or Management Application), and whether store and forward is enabled.
Whenever a connection is closed, lost, or does not exist, events are buffered in the
order in which they were emitted. The buffer is periodically persisted so that it can
be restored at the point in which it left off whenever the agent is restarted. While
disconnected, events continue to be buffered, across one or more restarts of the
agent. When the remote connection is re-established, events in the buffer begin
being emitted, starting with the earliest event and continuing until the buffer has
been emptied.

Client configuration
Due to the possible resource constraints (memory, disk space), participation in
event store and forwarding is configurable, as is the number of events that are
buffered per remote connection. The configuration for store and forwarding is done
in the RMA configuration properties file, simgmt.pro. These properties are described
further in “Agent configuration file” on page 41:
com.ibm.retail.si.mgmt.eventcontrol.storeandforward=true
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.maxevents=200000
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffersizethreshold=1000
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffertimethreshold=3000000
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.eventExpirationTimeout=7
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.eventExpirationCleanupFrequency=1
These properties can be changed by editing the simgmt.pro file, or through the
MgmtAgentConfigurationMBean, 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 and
| forwarding, and will buffer 200 000 events. At an average event size of 500 bytes,
| this equates to roughly 100 MB of disk storage.
NotificationProcessor
The NotificationProcessor acts as a central collection point for all events. It
handles the fetching and delivery of all events from each remote agent. By calling
the addEventFetcher() method, a remote JMX Connection to a RMA Agent gets
registered with the RMA Agent. This registration begins the flow of events from the
RMA Agent to the NotificationProcessor. A separate thread is created to make
remote calls to the agent to fetch groups of events.
As events are fetched they are enqueued until they can be delivered. An overflow
file is used to store incoming events when the memory queue size reaches a
configurable threshold. The memory queue size, and other configuration parameters
for event fetching are described in Table 5 on page 43.
As each event is delivered, it is forwarded to registered listeners through its

supporting listener interface (NotificationProcessorListener). On the Master
Agent, this listener interface is implemented by the MgmtNotificationControlMBean
to receive all store notifications.
MgmtNotificationControlMBean
The MgmtNotificationControlMBean, running on the Master Agent, provides a single
point of access to a management application for all store events. By adding a
NotificationListener to this MBean, all store events can be accessed by a
management application in real time as they are emitted. It works by registering
with the NotificationProcessor, receiving all Notifications from any General Agent
or Master Agent MBean, performing some additional processing on them, and
retransmitting them.
Logging configuration and forwarding

This set of MBeans performs logging level configuration that provides the ability to
remotely make non-persistent changes to logging levels. Restarting the agent JVM
causes the logging levels to revert to their persistent values.

The MgmtLoggingCtrlMBean controls the creation of all logging MBeans during agent
startup. Based on the logging packages detected, the appropriate logging and
remote logging MBeans are created. Table 23 is a summary of the logging MBeans
that can be created.
Table 23. Logging MBeans
MBean Name and Object
Name ID Description
MgmtLoggingCtrlMBean MBean started on all agents that sets up remote logging
MBeans and internal logging MBeans for all applicable log
types. The default remote logging level is OFF.
Log4JLoggerMBean MBean used to dynamically change the Log4J logging level
(Id=Log4JLoggers) (TRACE,DEBUG,etc) for any logger in the hierarchy.
Instantiated if the system detects Log4J.
JDKLoggerMBean MBean used to dynamically change the JDK logging level
(Id=JDKLoggers) (FINEST,FINE,etc) for any logger in the hierarchy.
Instantiated if the system detects JDK Logging,
JDKHandlerMBean MBean for dynamically changing the JDK logging level for
(Id=JDKHandlers) any of the JDK logging handlers.
Inventory
The function of inventory is to collect data about both hardware and software
components that comprise the system as a whole. It is the collection of specific
attribute information from the agent infrastructure. As such, the function of collecting
inventory is different than providing the correct information for collection. The
process 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 those
applications 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 that
support the retrieval of this information. This lets the inventory collection be added
to the MBean that is most appropriate. The consumer of the inventory data, namely
management agents and applications, can search out the predefined interfaces
using normal JMX interactions. The IBM Remote Management Agent API defines
two MBean interfaces for software and hardware inventory,
MgmtSoftwareInventoryMBean and MgmtHardwareInventoryMBean. These interface
definitions are based on the work done by the Distributed Management Task Force
(DMTF) for both Desktop Management Interface (DMI) and Common Information
Model (CIM). This information is consistent with that used by the Tivoli management
software as well.
CIM Implementation
CIM is a schema used to model the elements that comprise a complete
manageable system. As a standard, it is owned and maintained by the DMTF and is
widely adopted as the mechanism to use when modeling and exposing components
for management. For example, all variants of Microsoft Windows since NT 4.0 have
used an interface known as Windows Management Infrastructure (WMI), an
implementation of the CIM model, as their internal and external management
instrumentation model.

CIM also supports events, otherwise known as indications. There are two types of
indications: intrinsic indications and extrinsic indications. Intrinsic indications are
sent when a CIM object is created or deleted. Extrinsic indications are events
emitted by the provider for a CIM class, such as a state change or an alert for a
piece of hardware.
CIM Adapter MBean

RMA infrastructure contains a CIM/JMX Adapter, or CIMAdapterMBean, used to
translate managed objects from CIM into JMX. Specifically, this MBean creates
proxy 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 WMI

implementation and the Pegasus implementation on IRES. On unsupported CIM
implementations, the CIMAdapterMBean is instantiated but does not create any proxy
MBeans (the active attribute is false). Indications are only supported on WMI.
Note: The CIMAdapterMBean has a property called NativeTraceEnabled to turn on

debug tracing for CIM. This property is only applicable for the Windows
platform.
The CIMAdapterMBean works by creating proxy MBeans for CIM instances whose
class name exists in the class filter in a CIM namespace. Adding a class name to the
filter not only creates proxies for CIM instances of that class, but for all of its
subclasses as well. Likewise, removing a class name from the class filter removes
all proxy MBeans created for that class and all of its subclasses. The MBean is
created with a default set of namespace configurations that can be modified
programmatically or from the JMX Browser from within IBM Director.
All CIM proxy MBeans are categorized under the component name CIM in the JMX
Browser as shown in Figure 111 on page 165.

Figure 111. CIM proxy MBeans for component names
CIMEventMapper interface
The CIMAdapterMBean receives indications from the CIMOM in the form of
javax.wbem.cim.CIMInstance objects. CIM indications are CIM instances
themselves, so their structure is defined in a MOF file. Because each event type
has a different structure and meaning, the corresponding JMX Notifications will also
be different. The easiest way to convert CIMInstances into JMX Notifications is
through Java code, with an instance of the
com.ibm.retail.si.mgmt.cim.CIMEventMapper interface. The association between
the CIM indication class and the CIMEventMapper implementation is made in the CIM
adapter configuration XML file, %SI_HOME%\user\rma\config\CIMConfig.xml.
The CIMEventMapper interface's createCIMNotification() method performs the

conversion by returning an RtlNotification object from the supplied CIMInstance
object. The details of how RtlNotifications are created, their severity, and format
are left up to each CIMEventMapper implementation.
The CIMEventMapper interface requires that implementations process each

CIMInstance and create an RtlNotification from it. The severity of the Notification
is determined by the type of RtlNotification class instantiated (that is,
RtlInformationNotification, RtlWarningNotification, RtlErrorNotification, and
so 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

Note: When setting the user data field, it is important to use types that are
guaranteed to be in the class path of all JVMs that could receive the event
(General Agent, Master Agent, IBM Director, or any other management
application that interacts with the Master Agent).
Default extrinsic event registrations

Default 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 service
processors on IBM POS systems
v MSStorageDriver_FailurePredictEvent: Predictive failure indications for SMART
hard drives (WMI only)
UPOS indications
UPOS_SysMgmtEvent indications are emitted by the UPOS drivers for retail
peripherals. The indications emitted originate from all UPOS Status Update Events.
Refer to the UnifiedPOS specification for detailed information on all UPOS
indications.
The CIMEventMapper instance for UPOS indications is

com.ibm.retail.si.mgmt.cim.upos.UPOSEventMapper. This class, shipped with RMA,
will create RtlNotifications from instances of UPOS_SysMgmtEvent. The
RtlNotifications are created based on the information in two separate properties
files: 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 qualifiers
for that event. UPOSEventSeverities.properties maps each set of event qualifiers to
a severity, which will be the severity of the event created. The initial versions of
these 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 the
UPOSEventConfigMBean.
The UPOSEventConfigMBean is registered by the UPOSEventMapper in order to manage

the severities and event types. The exposed attributes are the event qualifier
names, 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 included
are methods for adding and removing event types. All changes made through the
MBean take effect immediately and are persisted.
RSS_SpNumericSensorAlert indications
RSS_SpNumericSensorAlert indications are emitted by the service processors in IBM
POS systems. The indications are emitted when the service processor changes
states, of which there are two: OK and Critical. The following summarizes the event
qualifiers 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 indications
MSStorageDriver_FailurePredictEvent indications are emitted on Windows systems
that have SMART (Self-Monitoring, Analysis and Reporting Technology) enabled

drives. The indications warn of a possible failure in the future. All indications result
in an Alert level RtlNotification with the qualifiers
Retail.hw.storage.failure.predict.
CIM configuration
The 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 CIM
configuration in the agent properties file, %SI_HOME%\user\rma\simgmt.pro. Upon
upgrading, those configuration settings are migrated. When RMA is installed fresh
or when the configuration XML file does not exist, it will be created with default
values. The following is an example:
<CIMConfig eventPollingInterval="30">
<namespace="root\cimv2">
<EventConfiguration>
<EventRegistration cimClass="UPOS_SysMgmtEvent"
mappingClass="com.ibm.retail.si.mgmt.cim.upos.UPOSEventMapper"/>
<EventRegistration cimClass= RSS_SpNumericSensorAlert
mappingClass= 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>
The top level element, CIMConfig, has one attribute, eventPollingInterval. The
value of this attribute represents the number of seconds between polling requests
for CIM lifecycle events.
Underneath the CIMConfig element is a CIMNamespaceConfig element, which

contains 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 class
from which the CIM Adapter will query and create CIM Proxy MBeans. The
lifeCycleEvents attribute determines whether an attempt is made to register to
receive lifecycle events for that class.
Note: Polling for lifecycle events can be a processor-intensive action, and you
should only enable it for CIM Classes whose instances are expected to
change after the system starts (that is, peripheral devices).

Use methods in the CIMAdapterMBean interface to edit the class filter of the XML
configuration. 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 its
configuration information. Each extrinsic indication CIM event class listed in the
configuration has a corresponding CIMEventMapper class, used when creating
RtlNotifications. The configuration XML for each namespace can contain an
EventConfiguration element, which can contain one or more EventRegistration
sub-elements. The EventRegistration elements require a CIM Event class, for the
type of events for which to listen, and the fully qualified classname of a
CIMEventMapper class, to be used for creating RtlNotifications from the CIM
Events.
Use methods in the CIMAdapterMBean interface to edit event registrations. The

methods are:
v addExtrinsicEventRegistration(Namespace, Event Class, CIMEventMapper
Class)
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. This
file can be edited when the agent is not running, or through the
CIMAdapterMBean interface. Changes made through the MBean interface
will not only be dynamic, but will also be persisted.
File Transfer
To support the transfer and consolidation of data from client devices, RMA includes
a file transfer interface. You can use this functionality to initiate file transfer
operations 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 transfer
functionality. RMA includes an implementation of this interface,
RMAFileTransferConnection, for performing file transfer operations. For transfers to
and from agents running RMA V2, implementations exist for FTP and FTPS (FTP
over SSL). The following diagram illustrates how the file transfer interface fits into
the RMA architecture:

Figure 112. File transfer interface
FileTransferConnection
This interface is implemented by all file transfer implementations, with the intent for
it 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 is
really a system timestamp of when it was created. This connection ID serves as a
key for identifying the connection with the FileTransferManager.
RMAFileTransferConnection is the primary implementation of the file transfer

interface used to transfer files to agents running RMA over a secure, authenticated
connection on port 10190. The server portion of the protocol, running on both the
Master and General agent, always binds using a socket created from a
RMASocketFactory instance. The "SSL" alias is supplied so that an SSL socket is
always returned, regardless of how the MA connects to GAs or how the MA's
JMXConnectorServer is bound. Connections are authenticated based on the same
method that authenticates the JMX Connections between the systems.
Further details about making both an authenticated remote JMX Connection to an

RMA Agent and a file transfer connection to an RMA agent is described in “Using
the FileTransferConnection interface” on page 214.

FileTransferException
Exception class for file transfer. Thrown by each implementation when an
error occurs. An included error code field is set by the throwing component.
FileTransferManager
This singleton creates and manages all file transfer connections. Whenever
a file transfer needs to be performed by the FileTransferMBean or any other
code in the JVM, the connect() method is called on this object, returning an
instance of FileTransferConnection. The FileTransferManager keeps a
reference to all connections made, and periodically cleans up all stale
connections. This class also manages the supported file transfer
implementations on each device. In addition to the default implementations,
additional implementations of the FileTransferConnection interface can be
registered with the manager and used. During startup, the manager
attempts to load via reflection the registered class for each implementation.
This configuration for all file transfer implementations is stored in the
agent's MgmtAgentConfiguration.
FileTransferMBean
This mean also provides a management interface for the
FileTransferManager, where the set of file transfer implementations can be
managed. Implementation classnames can be added or removed, and the
list of supported implementations is exposed as an attribute. The
FileTransferMBean is included as of the default set of RMA MBeans, and is
instantiated on both the General and Master Agents.
Managing file transfer implementations

The FileTransferManager maintains a registry of active file transfer
implementations. Each implementation is identified by a name (FTP), which is
mapped to an implementation class
(com.ibm.retail.si.mgmt.xfer.ftp.FTPConnection). You can use this mapping to
be add and remove different implementations, as well as to substitute different
implementations of the same protocol. Most importantly, you inform other
applications of which mechanisms are supported and active. An attempt is made to
load each implementation class name during startup (by way of Class.forName()).
Each implementation class that cannot be loaded is considered inactive and will be
rejected when an attempt is made to use it. The registered and active
implementations are exposed as attributes in the FileTransferMBean:
Table 24. Managing file transfer implementations
Attribute name Description
registeredImplementations Names of all registered implementations (such
as FTP, FTPS, STREAM)
activeImplementations Names of all registered implementations that
were successfully loaded during startup (such as
FTP, FTPS assuming STREAM could not be
loaded)
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 implementation
name supplied (such as FTP) returns
com.ibm.retail.si.mgmt.xfer.ftp.FTPConnection
Storage
Each implementation and its class are stored as properties in the
MgmtAgentConfiguration. Each implementation is assigned a number, prefixed with
a common name, and its additional properties following the number:
com.ibm.retail.si.mgmt.xfer.impl.1.name=FTP
com.ibm.retail.si.mgmt.xfer.impl.1.class=com.ibm.retail.
si.mgmt.xfer.ftp.FTPConnection
com.ibm.retail.si.mgmt.xfer.impl.2.name=FTPS
com.ibm.retail.si.mgmt.xfer.impl.2.class=com.ibm.retail.
si.mgmt.xfer.ftps.FTPSConnection
Monitor policy
JMX enables the construction and control of distributed monitors, defined in
package javax.management.monitor, each of which watches a given attribute on an
MBean at a specified interval. When the value meets a defined condition, the
monitor issues a MonitorNotification to the managing infrastructure. At the Master
Agent, monitor notifications are wrapped in a RtlMonitorNotification and
re-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 are
not persisted. They must be recreated each time the General Agent (MBeanServer)
is restarted. The mechanism provided by the IBM Remote Management Agent for
automatically creating JMX monitors upon General Agent startup is through monitor
policies, managed by the MonitorManagerMBean on the Master Agent. Its job is to
create MonitorMBeans on General Agents based on registered policies. Information
contained 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 the
stringToCompare 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, or
all agents running on all devices of a specific device type.
The management of monitor policies can be performed programmatically or from

the Resource Monitors task within IBM Director.

RMA Software Distribution
The creation of a software package occurs within the IBM Director Console, using
the RMA Software Distribution task to create an installation package. This wizard
guides you through the creation process, having you choose the files for the
package 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 that
houses 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 the
RMASWPackageDistributorMBean. When the package is deployed to a set of devices
by IBM Director, this file will be sent to the Master Agent in each target device's
store and processed by the RMASWPackageDistributorMBean. This MBean sits on top
of the RMA Software Policy Manager and automates the creation of device software
policies within a store. The following diagram shows RMA software distribution, end
to end:

Figure 113. Software distribution overview
The following sections explain each portion of the RMA Software Distribution
infrastructure. The first section, “RMA Package Distributor MBean” on page 174,
explains the format of RMA package JAR files and how to deploy them by
interfacing with the RMASWPackageDistributorMBean. The section that follows,
“Software Distribution Policy” on page 178, summarizes how the RMA Master Agent

Policy Manager invokes policies onto clients and explains in detail the format of the
policy XML file, with the goal of being able to create policy XML files for newly
created package JAR files.
RMA Package Distributor MBean

Even though this package file format is used by the Retail Extensions for IBM
Director to deploy software packages to devices, it also can be used by other
management applications to deploy software to stores. The
RMASWPackageDistributorMBean automates the creation of software policies by
unpacking and processing package JAR files the comply with a specific set of
conventions. Even though this package file format is used by the Retail Extensions
for IBM Director to deploy software packages to devices, it also can be used by
other management applications to deploy software to stores.
This section explains the conventions used by the RMASWPackageDistributorMBean

and how it can be used to easily deploy a software package to multiple clients. The
following diagram presents an overview of the RMASWPackageDistributorMBean.
Figure 114. RMA Package Distribution overview

Package JAR file format
The JAR file processed by the RMA Package Distributor MBean contains all of the
files and information required to deploy a package to a set of devices in a store. It
must 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 directory
on each client.
The policy.xml file is the software policy XML file that is sent to all clients. There
should 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 in

creating device software policies on each Master Agent. The following table lists
each 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 in
curly braces {}. Backslashes should be
replaced with forward slashes. Example:
{Windows=C:/temp,Linux=/tmp/pkg}
package_target_state Name of the system state each client should
change to upon running the policy. Example:
SW_MAINT. For more information, refer to
Chapter 16, “Programming examples,” on
page 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 Agent

You 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 Distributor
MBean is that the full path to the file, as it exists on the Master Agent, is known and
can be supplied when requesting to stage the package. Using any of the file
transfer implementations is a way for transferring package JAR files to the Master

Agent. Information on using the RMA file transfer interface is described in
Chapter 16, “Programming examples,” on page 199.
Package staging
When a package file has been created and exists on the Master Agent system, the
package can be staged and deployed to all target devices using the
RMASWPackageDistributorMBean. Using the MBean,
(com.ibm.retail.si.mgmt.swdist.pkgdist.RMAPackageDistributorMBean), to deploy
a package process involves two steps:
1. Staging the package, which involves preparing the package files and creating
RMA 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 method

requires 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), each
corresponding 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 staged
asynchronously, and it returns immediately. The staging is performed
asynchronously because of the time required to stage a package. If the call were
synchronous and were being made over a remote JMX Connection, the socket
making 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.xml
and 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 configured
FTP 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 policies
created by this MBean from others not automatically created, and provides a
method for obtaining information about the policy once activated (such as status
notifications). If applicable, a directory is created on the FTP server for the package
files 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 or
unexpected), 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, a

SWPkgDistStagingProgressNotification is sent. Each notification contains fields for
the 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 is
processed, a status object (PackageStatusXML) is kept that contains the staging
status for all devices. The PackageStatusXML contains a DevicePackageStatusXML
object 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 a

corresponding resource bundle key in
com.ibm.retail.si.mgmt.itd.server.swd.RetailSWDResources to use for displaying
a message in the IBM Director Console. The error message parameters are to be
supplied as parameters to the MessageFormat class.
When package staging has completed, the PackageStatusXML object contains a

DevicePackageStatusXML object for each staged device. This information is
transformed into an XML String, which is supplied along with the job ID to a
SWPkgDistStagingStatusNotification to be sent to all listening management
applications. The XML message is the Notification's user data. The following
example 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 the
PackageStatusXMLParser class. The following code sample is an example of its
usage:
// Parse XML reply
try {
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 listeners
are added to the MgmtNotificationControlMBean, NotificationProcessor, or the
RMAPackageDistributorMBean directly. Otherwise, the response from the package
staging will not be received, and the status from the deployment will never be
obtained.
When each device policy has been activated, status information from clients is
relayed in the same way for all RMA Software Policies, using
MgmtSWPDeviceStateNotifications. Thus, just as it is important to be registered for
events prior to staging a package, it is important to be registered for policy status
events prior to policy activation.

Software Distribution Policy
The Remote Management Agent infrastructure defines a mechanism for performing
software 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 the
Master Agent to apply a policy to the General Agent device. When it applies the
policy, the General Agent component performs the steps contained in an XML file.
Like the MonitorManager, the Master Agent component interacts with these General
Agent MBeans based on defined distribution policies resident at and controlled by
the Master Agent.
The functionality provided by the Remote Management Agent software policy

framework is a simple triggered pull of defined software policies to devices within a
store network. A software policy is defined as an entity that provides software
(packages, updates, patches, and so forth) on client devices. Among the information
it contains is when the policy should be applied, the devices to which it should be
applied, and the location of the policy XML file.
The policy XML file contains information about resource files that must be obtained
to support the software policy, as well as the commands for one or more device
platforms. A client retrieves this pre-assembled XML file, along with the other
resource files that are identified for distribution. Because the client knows the
platform on which it is running, it can process information specific to its platform
from the policy XML file and run the software policy. The following is a simple
example policy XML file:

<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/swdi
st/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: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"/>
The software policy XML file Installation portion simply creates a new directory
on a Linux or Windows client, reboots the device through a generic reboot
mechanism, and subsequently creates another directory after rebooting. In this
example, each executable portion of the software policy XML file looks similar for
both platforms, but in practice each device requires instructions with different
syntax, and possibly a different process to achieve the end result. More detail on
the construction of software policy XML files is provided in “Software Policy XML file
structure” on page 180. In this example, only the Windows based clients retrieve
resource files.
The process of applying a software policy to the devices in the store network is to
first create such a software policy. The software policy XML file must be created
separately and made available to the Remote Management Agent software policy
framework. The software policy entry must include the name of the software policy
XML file and file transfer information. This information varies based on the file
transfer implementation used. When the software policy is activated and is ready to
run, it then becomes the job of the SWPolicyMasterMBean to signal all client devices
impacted by the software policy either immediately or when these devices come
online. The MgmtSWPolicyClientMBean present on a device impacted by a software
policy receives the notifying signal from the master, pulls down the appropriate

software policy XML file, and invokes the software policy based on instructions for
its platform. As a policy is being activated, it emits
MgmtSWPDeviceStateNotifications to relay status information to the Master Agent.
Additional functionality (for example, the verification of package dependencies) is

outside the scope of software policies and is left up to the users of the software
policy management framework or the installation executable files. Figure 115
illustrates the software policy distribution process at a high level.
Figure 115. Software policy distribution
Software Policy XML file structure

The creation of a software policy is accomplished by interacting with the software
distribution MBeans on the Master Agent, and by creating a software policy XML file
with the instructions a client must use to apply the policy. Both of these actions are
automated by the RMA Software Distribution task in the IBM Director Console. A

guide for the values that are valid in the creation of such an XML file can be
determined from the XML schema for software policy XML files.
Outer tags and attributes: The outer tags and attributes that define a software
policy 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:SoftwarePolicy

attribute. The use of namespace becomes clear as the rest of the software policy
XML file is outlined in this section. The expected location of the XML schema that is
used to validate the software policy XML file is given in the xsi:schemaLocation
attribute. Copy this text exactly to begin creation of a software policy XML file. A
predominant number of XML parse errors are associated with an inappropriately
declared root tag.
Note: The namespace must be included before all element tags used within a
software policy XML file, but it is not required before the attributes of any
particular tag. The discussion in this section includes the namespace in all
tags where it is necessary.
Software policy content: The elements and attributes of the software policy
content provide a general description of the software policy, outline the resource
files needed for installation, and describe what types of actions are to be taken by
the software policy for each platform.
Each software policy must contain a descriptor. This is accomplished by including

the following element tags within the outer software policy tags:
<SoftwarePolicy:SWPolicyDescriptor>
<SoftwarePolicy:Description> Base Lab Testing Policy for RMA
Package</SoftwarePolicy:Description>
</SoftwarePolicy:SWPolicyDescriptor>
The first element within the policy, enclosed inside the

SoftwarePolicy:SWPolicyDescriptor tag, contains a text description of the policy.
Each platform affected by the policy is represented by the inclusion of a

SWPolicyTarget tag as follows:
<SoftwarePolicy:SWPolicyTarget targetOS="Windows">
..{software policy target device content}..
</SoftwarePolicy:SWPolicyTarget>
The SoftwarePolicy:SWPolicyTarget tag must follow the descriptor tag. The

targetOS attribute tag specifies the platform of the target device. A value of Windows
is 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 for
general purpose, and is not targeted for a specific platform. The
SoftwarePolicy:SWPolicyTarget tag is required.

Software policy content can be made very general or very specific. For example, a
software policy that would apply a similar action to a large number of different
platforms would have several target elements each specifying how the action would
be accomplished for each platform.
Note: Only a single occurrence of a SWPolicyTarget element should be entered

into the software policy XML file for each platform.
Software policy target device content: The target device tags contain two types
of elements: the resource files to be transferred and a set of commands to be
invoked.
The element tags that declare resource files that will be used with a target device
software 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 be

downloaded when running a policy. Only one of these tags is required per device
target. This tag is optional if resource files are not required to invoke the software
policy on that target. The preceding example declares resource files resfile1.txt, and
resfile2.txt.
When present, the SoftwarePolicy:SWPolicyResourceFiles tag can contain zero or

more SoftwarePolicy:Component elements representing resource files that are to be
downloaded. 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. Any Any string value Required
acceptable string filename.
size The size of the file in bytes. The Any integer value Optional
tag value is not used, but a value
must be present. You can enter 0.
The SoftwarePolicy:Installation tag is used to declare elements within the

device target element representing the installation steps of a software policy. An
example of this element is as follows:
<SoftwarePolicy:Exec executable="echo Beginning Policy Execution"
expectedRC="0">
<SoftwarePolicy:Exec executable "mkdir /TEST" expectedRC="0"/>
<SoftwarePolicy:Exec executable "mkdir /TEST1" expectedRC="0"/>
<SoftwarePolicy:Exec executable="echo Completed Policy Execution"
expectedRC="0">
The SoftwarePolicy:Installation tag can contain several other element tags. An

individual instruction in a software policy is declared with the SoftwarePolicy:Exec
tag. 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 on A string value - Any Required
the device target operating system. Any executable instruction is
executable instruction is acceptable. Spaces acceptable. Spaces are
are allowed. Quotes can be included in the allowed. Quotes can be
instruction provided to preserve spaces. included in the instruction
provided to preserve
spaces. Use XML "&quot"
or "&#34" within the
attribute quotation mark
delimiters for the attribute
value. A quoted string
might not work on all
operating systems.
expectedRC The expected text value that is returned in the Any string value Required
error stream from performing the instruction
step. Spaces are allowed.
rcFile This attribute is used to specify a file in which Any string value Not required
the return code for an executable instruction
is to be returned. This attribute is used if an
instruction implements a reboot or restarts the
RMA service. The software policy developer
must insure that the file is created and
populated with the return code for proper
execution of the software policy. There can be
no spaces in the string unless it is quoted
(use XML """ or """) within the
attribute quotation mark.
failureLog The path to a log file that is read after the Any string value Not required
command is invoked. Each line from the file is
appended as a standard out message.
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 be
invoked using the client operating system's shell interpreter in order to be invoked
correctly. The following lists the syntax for invoking shell command or scripts on
various 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 4690
Remote Command Processor (RCP). Thus, the syntax of the commands
in the policy must be the same as when the commands are invoked using
RCP.
On Linux, a properly formatted, executable shell script can be entered as a valid

command.
Important: Always test package commands before deploying.
The arguments for an instruction represented by the SoftwarePolicy:Exec tag can

be declared using nested argument element tags of the form,
SoftwarePolicy:ExecArg.

Note: The argument element tag is not mandatory (for example, an instruction that
has no arguments or when the entire instruction and its arguments are within
the 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. If
there are spaces within the argument, then an XML """ special character must
be 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 the
software policy developer must be aware of the operating system capabilities
and 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 policy
developer desires specific behavior during a reboot, it is possible to use the
SoftwarePolicy:Exec tag to specify an actual reboot command for the target device
operating system with appropriate arguments.
Creation of the software policy XML file provides a client payload that directs the
client in the action of the software policy. The target device instructions rely on the
device operating system to support shell command invocation with appropriate
privileges to accomplish the operations requested by the software policy. The
process of selecting the instructions (or developing new ones) that include a
software policy is beyond the scope of this design.
Policy XML variables

In order to make policy XML files more flexible and general-purpose, the policy XML
file supports variables that will have concrete values substituted when supplied. In
the 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 will
probably 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 with
the policy.
rma.data.dir The path to the RMA Configuration Directory (%SI_HOME%\user\
RMA)
Diagnostic Data Capture

RMA supports diagnostic data capture through the use of the DataCaptureMBean
interface. All implementations of this interface gather component information and
collect it into a single file. These components are brought together at the store level
with Data Capture policy. Capture policy facilitates the transfer of capture data to a
central location and the optional invocation of captures on other components.

DataCaptureMBean
The DataCaptureMBean interface is implemented by all MBeans that can collect
diagnostic data. Captures can be triggered manually by the MBean interface, or
automatically when there is a system detected error. How and where errors are
detected is up to the implementer. Errors could be detected internally by the
DataCaptureMBean implementation or detected in another MBean. If detected in
another MBean, possible methods of initiating the capture include Notifications
received by the DataCaptureMBean, callbacks to registered event listeners, or a
direct call to the DataCaptureMBean.
By registering an implementation of this MBean with the RMA General Agent, the
MBean 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 such
as request queueing and running captures in a separate Thread. It also handles the
generation of unique capture identifiers. It is recommended that this class be
extended instead of implementing the DataCaptureMBean interface directly.
Capturing Data
A capture is performed by calling the capture() method on the DataCaptureMBean. It
takes as arguments a constant indicating the capture type and a String array of
implementation specific parameters. Each implementation determines the format
and purpose of these parameters. An in-progress capture can be aborted by calling
the abortCapture() method.
The capture type is a constant that indicates whether the capture is being manually
triggered (SOLICITED_TYPE) or performed as the result of a system detected error
(UNSOLICITED_TYPE). This capture type is used by the Master Agent to trigger
other policy based actions in response to either type of capture.
The return value from the capture() method is a capture ID String. This unique ID
is 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 any
other form) on the local file system.
2. Emit a DataCaptureNotification with the appropriate information about the
capture. The Notification should contain (in addition to that information already
defined by RMA RtlNotifications):
v The unique capture ID that is used by management applications in referring
to 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 the
agent device). Files could be supplied for successful or unsuccessful
captures.
v If an error occurred during the capture, an error message indicating the
reason for the failure.
The DataCaptureNotification instance created will have the following values for
the 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 the
same MBean that emits the DataCaptureNotification
Note: It is important to note that captures can take place over extended periods of
time. Thus it is important that calls to the capture() method should not block
for a long period of time. Although it is not required, captures taking
extended periods of time should be run in a separate Thread. This problem
can be avoided by extending the DataCaptureMBeanSupport class.
Capture Processing
The issuing of a DataCaptureNotification is a means for indicating that a capture
has completed to the Master Agent and to any management application.
Management applications can listen for DataCaptureNotifications and perform
application specific processing after captures have completed. A typical response to
the completion of a data capture is to transfer the files from the agent computer to a
central location. The RMA General Agent supports data retrieval through the
FileTransferMBean. Figure 116 illustrates this process:
Figure 116. Data capture processing
See “File Transfer” on page 168 for more details.

The Master Agent includes a component that defines a policy based mechanism for
performing a set of actions such as file streaming transfer of capture files to a
central location in response to completed captures. The details of this component
are in “DataCapturePolicy class” on page 190.
DataCaptureMBeanSupport
The DataCaptureMBeanSupport class is an abstract class that provides a default
implementation of the DataCaptureMBean interface. It handles much of the overhead
for 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 unique

identifier for the capture and invokes it in a separate Thread. Subclasses implement
the protected performCapture() method to perform the actual capture. Passed with
it is an instance of the interface DataCaptureRequest. This object contains
information about the capture and its result. The performCapture() method should
modify the instance passed in with capture file names and/or error messages before
completing.
After the capture completes, the protected captureCompleted() method is called, to

which it passes the DataCaptureRequest instance returned from performCapture().
This method handles post capture processing, which by default is to send a
DataCaptureNotification based on the information in the DataCaptureRequest.
Subclasses can override this method to perform their own post capture processing
along 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. After
ending capture execution, a call is made to the captureAborted() method. Like the
captureCompleted() method, this method is provided as a hook for subclasses to
perform any processing after the capture has been aborted. The default
implementation of this method sends an unsuccessful DataCaptureNotification
with an error message indicating that the capture was aborted, and with the capture
filenames in the DataCaptureRequest at that time.
Because this class ensures capture method calls are non-blocking, it is

recommended that this class be used when creating a DataCaptureMBean
implementation.
Figure 117 on page 188 illustrates this process:

v Steps 1 and 2: A system error is detected and a capture performed, writing
diagnostic data to files on disk. The system error could be an application error, or
any error that can be reported to RMA.
v Step 3: The DataCaptureNotification emitted by the General Agent flows to the
Master Agent.
v Step 4: In response to the DataCaptureNotification, the Master Agent makes a
file transfer connection to the General Agent, to transfer the captured files. After
being transferred, the captured files are compressed into a capture bundle, which
is stored on the Master Agent.

v Step 5: The capture bundle is retrieved from the Master Agent by a Management
Application that is running at the enterprise.
Figure 117. Data capture
Data Capture Policy

The DataCaptureMBean interface serves as the interface for data capture in the RMA
infrastructure. Any management application can communicate directly with an
instance 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 be
desirable for a completed capture on one component to initiate captures on one or
more other components on the same device.
Additionally, management applications are required to listen for notifications of

completed captures and transfer the diagnostic data from all devices. Instead of
management applications having to perform post-capture processing and manage
chains of capture dependencies, the RMA Master agent provides a centralized,
policy based component for performing these tasks called the
DataCaptureManagerMBean. 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 automatically
in response to a completed unsolicited capture

A DataCapturePolicy, registered with the DataCaptureManagerMBean running on the
Master Agent, defines the list of capture MBeans and details needed for performing
the captures and transferring files.
RMADataCaptureMBean
RMA includes an implementation of the DataCaptureMBean interface, the
RMADataCaptureMBean, which captures useful problem determination data from an
RMA agent. RMA memory logging triggers the RMADataCaptureMBean to capture data
when a problem occurs. The RMADataCaptureMBean captures the following data when
invoked:
v Logs
– rma.stderr
– rma.stdout
– RMA CIM tracing (rmacimtrc.log)
– The regular logging file(s) specified by the base FileHandler pattern in the
logging configuration file (default is simgmt.*)
– The memory logging file(s) specified by the RMALogHandler pattern in the
logging 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 last
10 minutes).
DataCaptureManagerMBean
At the center of the capture infrastructure is the DataCaptureManagerMBean, which
manages data capture policies and listens for DataCaptureNotifications emitted by
DataCaptureMBeans running in the store (including the Master Agent). The receipt of
these notifications triggers file transfers of captured data and captures on other
DataCaptureMBeans running on devices in the store. Figure 118 on page 190
illustrates this process. In this diagram, there is an capture policy active on the
Master Agent. An unsolicited capture occurs on LaneX, resulting in the Lane
sending a Data Capture Notification of type UNSOLICITED (1). When the
notification is received by the Master Agent, the manager will detect that the capture
applies 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 the
policy's capture list, any unsolicited capture by a Lane will result in a solicited
capture on CC. When the solicited capture completes on CC (by emitting a
DataCaptureNotification of type SOLICITED (4)), its files are transferred to the
Master Agent (5) and a capture bundle file will be created containing the capture
files from both LaneX and CC.

Figure 118. DataCaptureManagerMBean
DataCapturePolicy class
A DataCapturePolicy object is a container object used by the DataCaptureManager
to store policy configuration information. Instances of this object are registered with
the DataCapturePolicyRegistryMBean, and then activated. Once activated, the
DataCaptureManagerMBean will register NotificationListeners with MBeans listed in
the policy to receive DataCaptureNotifications. These notifications will initiate file
transfers on completed captures as well as captures on the other
DataCaptureMBeans 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 will
initiate 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 invoked
when an unsolicited capture occurs on a device in the trigger list.
v Capture Timeout: This value defines a time window, in minutes, in which all
captures must be completed. The timeout period starts when the unsolicited
notification is received or the first capture is triggered. After the time window
expires, the capture sequence will time out and will go inactive. The minimum
value is 1.

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 this
file.
Capture policy application

Data Capture policies use two lists, a trigger list, and a capture list. Each trigger list
contains pairings of MBean IDs with a device ID or device type. The pairings in this
list are used to determine when captures from arriving DataCaptureNotifications
result in solicited captures on the MBeans in the capture list. Each policy's capture
list also contains a list of these mappings, which is used to compile a list of agents
to invoke solicited captures. Use the pairings between MBean and device, as they
are used in the trigger and capture lists, to target different agents.
The pairings that make up each list are instances of either

DeviceCapturePolicyApplication or DeviceTypeCapturePolicyApplication. Each
takes 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 of
capture parameters passed to the DataCaptureMBean when invoked by way of a
solicited capture. The following examples shows an single device application for the
GenericLogCaptureMBean, whose parameters, the names of the files to capture when
invoked, are listed as nested elements:
<DeviceCapturePolicyApplication mbeanId="GenericLogCapture" deviceId="CC">
<CaptureParams>
<CaptureParam>C:\silogs\CC.0<CaptureParam>
<CaptureParam>
</DeviceTypeCapturePolicyApplication>
An example of the trigger list/capture list concept comes from the policy depicted in
Figure 118 on page 190. The desired behavior of the policy is to initiate a solicited
capture on a capture MBean "GenericLogCapture running on 4690 controller CC in
response to an unsolicited capture from a Self Checkout Lane MBean
SCSDataCapture. To create this policy, you would supply a new policy with the
following information:
v Trigger List: A PolicyApplicationList with one
DeviceTypeCapturePolicyApplication, pairing the SCSDataCaptureMBean with the
SCS-Lane Role.
v Capture List: A PolicyApplicationList with one
DeviceCapturePolicyApplication, pairing "GenericLogCapture" with the device
ID "CC".
Capture bundle directory

Capture file processing is performed by an instance of CaptureFileProcessor. Its
job is to create a bundle ZIP file from the files that comprise a completed capture
invocation, and to delete those capture files after the bundle has been created. A
completed capture invocation is one in which all captures have completed
(successfully or unsuccessfully) and their files transferred (if any). Capture bundles
are stored in a location given by the CaptureBundleDirectory attribute on the
DataCaptureManagerMBean. This value would be used by a management application
(RMA Data Capture task in IBM Director) to check for and retrieve completed
captures. The default path on the Master Agent to where capture bundle files are
stored 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 invocation
When a policy is triggered on an agent (either manually or by the arrival of an
unsolicted capture event), a CapturePolicyInvocationPlan is created to determine
which captures to invoke. A CapturePolicyInvocationPlan object takes a policy's
capture list, a policy's trigger list (optional), and a list of all online agents and
returns a list of <MBean, Agent> pairs that represent captures to invoke. The pairs
represent an aggregation because it is possible that an agent could be affected by
more 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 get
invoked later under that invocation.
The applicable MBeans defined in the policy that are online at that time will have
captures initiated (by way of the DataCaptureMBean interface's capture(String,
long) method). The String is the type of capture (solicited or unsolicited), and the
long is the capture timeout. While these captures are taking place, the policy will be
in a blocked state, where the MBeans defined in the policy will not be triggered
again on that agent until the policy completes successfully or unsuccessfully. This is
to keep all captures for the policy into a single contained unit, and to prevent a
backlog of captures.
Policies will always act independently of one another. In other words, if an MBean is
defined in another active policy, it will be called to capture even though it might be
in the middle of a capture from another policy. The DataCaptureMBean will provide a
base implementation, DataCaptureMBeanSupport, that handles the execution of
captures in a separate Thread.
If an agent shuts down during the middle of a capture or file transfer

(MBeanServerNotification.UNREGISTRATION notifications received by the
DataCaptureManager for an MBean), a synchronization process will occur during
startup that will resume file transfers.
Post Capture File Transfer and Processing

The arrival of a DataCaptureNotification triggers a two stage process of
transferring the capture files from the clients to the Master Agent and bundling all of
the capture files and logs into a single .ZIP file. The bundles will be available for
management applications to read and transfer to an enterprise location.
Capture File Transfer: When a DataCaptureNotification is received by the

DataCaptureManager (solicited or unsolicited), a request is submitted to transfer the
capture files to the Master Agent. The DataCaptureNotification contains a list of
the capture file names (fully qualified) as they exist on the client. The format of the
file path in the notification does not matter, since they are passed back to the client
during the file transfer.
The transfer will be performed using each device's FileTransferMBean using the
RMA File Streaming implementation. File streaming, added in V2R2, is the only way
to 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 for
data 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 under
the transfer root for the capture files. The directory structure that is created for the
files 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 a

policy 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 RMALogCapture
implementation 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 XML
history log (history.xml) located in the root of the bundle ZIP file. This log contains
all of the history information for that invocation, and it can be parsed and used by a
management application. The log is in the same format as that stored on the
Master 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 DataCaptureHistoryParser
class to parse it.
Retries and Maintaining Capture History Information

It is quite possible that the transfer of capture files will not succeed on the first try
after the completion notification has been received. The Master Agent should retry
as many times as possible in order to transfer the capture files.
It is also important that the capture history information on the Master Agent be
maintained, since the Master Agent cannot be notified asynchronously of all
possible external actions that would require the information to be updated. For
example, a capture file on a client could get deleted by some external process or
user. Only by going back to the client and synchronizing will the Master Agent know
and respond. This section describes how both of these functions are handled.
File Transfer Error Handling and Retries: The transfer directory, the location on
the Master Agent where capture files are transferred, is a staging directory, or a
temporary storage location. As each capture file is transferred from the client, the
capture history updated to reflect the fact that it has been transferred. Only when
the bundle zip file has been created successfully with all capture files will the
transfer directory for the invocation be deleted. Until then, the capture files will
remain. This means that a transfer error does not fail a capture, it only delays the
completion of it.
Capture History Cleanup: History cleanup and synchronization is needed

because it is not guaranteed that all invocations will complete. One possible
scenario is that an agent goes down during the middle of the transfer of capture
files and never comes back up. Without cleanup, this capture history would remain
forever or until the policy was terminated.
To handle history maintenance, a synchronization is performed when each capture

MBean is discovered. Synchronization is a two stage process. One is comparing
the current Master Agent information with that of the client, and the other is
comparing the info the client has with that of the Master Agent.

Calling getCaptureFiles(captureId), a method in the Data Capture MBean
interface, will return the most up to date capture file information for a capture from
the client. This method will check for the existence of the files on the client machine
and will return only those that still exist. The Master Agent will update its history and
status information based on what is returned, removing file names that no longer
exist 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 older
than a threshold value, the persisted attribute HistoryThresholdDays (default is 1
day). The history cleanup operation involves only processing on the Master Agent
side. It does not involve contacting each client for updated capture status
information, which would result in network traffic. Capture status information is
obtained from the client only once, when the client is discovered.

Part 4. Programming
Chapter 15. Development environment . . . . . . . . . . . . . . . 197
Setting up the development environment . . . . . . . . . . . . . . . 197
Chapter 16. Programming examples . . . . . . . . . . . . . . . . 199

Working With Files . . . . . . . . . . . . . . . . . . . . . . . 199
Writing and registering your own MBeans . . . . . . . . . . . . . . 199
Exposing a management interface . . . . . . . . . . . . . . . . 199
MBean Object Naming . . . . . . . . . . . . . . . . . . . . 200
MBean registration . . . . . . . . . . . . . . . . . . . . . . 202
| Embedded Agent registration . . . . . . . . . . . . . . . . . 202
General Agent service registration . . . . . . . . . . . . . . . 203
| Creating An Embedded General Agent. . . . . . . . . . . . . . 203
| Embedded Agent Configuration . . . . . . . . . . . . . . . . 203
| Embedded Agent Communcation . . . . . . . . . . . . . . . . 204
Distributing the MBean classes . . . . . . . . . . . . . . . . . 204
Making a Remote JMX Connection to the Master Agent . . . . . . . . . 204
Accessing MBean instrumentation . . . . . . . . . . . . . . . . 208
Accessing General Agent MBeans from the Master Agent. . . . . . . 208
Locating Agent MBeans . . . . . . . . . . . . . . . . . . . 209
Retrieving Store Events (Notifications) . . . . . . . . . . . . . . . 210
Adding Notification Listeners . . . . . . . . . . . . . . . . . 210
Using the Notification Processor . . . . . . . . . . . . . . . . 211
Using the FileTransferConnection interface . . . . . . . . . . . . . . 214
Common properties. . . . . . . . . . . . . . . . . . . . . . 215
RMAFileTransferConnection properties . . . . . . . . . . . . . 215
FTPConnection properties . . . . . . . . . . . . . . . . . . 215
FTPSConnection properties . . . . . . . . . . . . . . . . . . 216
Transfer types. . . . . . . . . . . . . . . . . . . . . . . . 216
Transfer progress . . . . . . . . . . . . . . . . . . . . . . 217
Managing monitor policies . . . . . . . . . . . . . . . . . . . . 218
MonitorPolicy object . . . . . . . . . . . . . . . . . . . . . 218
MonitorPolicyAction object . . . . . . . . . . . . . . . . . . . 218
Managing data capture policies . . . . . . . . . . . . . . . . . . 219
Creating, Adding, and Activating a Capture Policy . . . . . . . . . . 219
Receiving Capture Completion Notifications . . . . . . . . . . . . . 221
Querying Invocation History . . . . . . . . . . . . . . . . . . . 221
CapturePolicyInvocationRecords . . . . . . . . . . . . . . . . 221
CaptureAgentRecords . . . . . . . . . . . . . . . . . . . . 221
CaptureInstanceRecords . . . . . . . . . . . . . . . . . . . 221
Terminating and Deleting a Data Capture Policy . . . . . . . . . . . 222
Managing software distribution policies . . . . . . . . . . . . . . . 222
Registering draft policies . . . . . . . . . . . . . . . . . . . . 223
State and progress notifications . . . . . . . . . . . . . . . . . 224
Activating a draft policy . . . . . . . . . . . . . . . . . . . . 225
Policy invocation history and status . . . . . . . . . . . . . . . . 225
Terminating and deleting a Policy. . . . . . . . . . . . . . . . . 226
SystemStateManager . . . . . . . . . . . . . . . . . . . . . . 227
SystemStateChangeListener and SystemStateChange Notifications . . . . 227
SystemStateHandler . . . . . . . . . . . . . . . . . . . . . 227
Coding best practices . . . . . . . . . . . . . . . . . . . . . . 228
Using error logging . . . . . . . . . . . . . . . . . . . . . . 228
Logging levels. . . . . . . . . . . . . . . . . . . . . . . 228
Logging APIs . . . . . . . . . . . . . . . . . . . . . . . 229

Controlling error log output . . . . . . . . . . . . . . . . . . . 229
Error log entry contents . . . . . . . . . . . . . . . . . . . . 230

Chapter 15. Development environment
One of the advantages of Remote Management Agent's use of Java is the flexibility
of the development environment. Programming tasks can be performed on any
system that has a text editor and the Java Development Kit (JDK). This section
explains how you set up your environment for writing MBeans.
Setting up the development environment

To create MBeans for the Remote Management Agent, you need the correct level of
the Java Development Kit (JDK) loaded on your development system. The correct
level of the JDK required can be downloaded the IBM JDK from
www.ibm.com/developerworks/java.
For the purposes of building and compiling MBean classes and management
applications, you can use the IBM Java 6 compiler. When running management
applications, you can use an IBM Java 6 JRE. When creating extension MBeans to
be registered with the RMA agent, however, you must pay attention to the JRE
version of the target platform. All RMA Agents run with the IBM Java 6 JRE on
Windows, Linux, or 4690 Enhanced. The RMA Agent on 4690 Classic runs with the
1.4.2 IBM JRE.
Since JMX is not included with Java 1.4, a JMX implementation must be added to
the class path when running inside a 1.4 JVM. Additionally, the .class files need to
be compiler option -target 1.4. The supported JMX implementation for 1.4 IBM
JRE'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 also
included 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 system
environment 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

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. For
example, to run the fictitious Java program com.test.MyTest with the RMA class
path on Windows, issue the rmaJava.bat com.test.MyTest command.

Chapter 16. Programming examples
This section describes details of programming with IBM Remote Management
Agent. 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 software
distribution
Working With Files

Working with certain file types in Java on 4690 OS V6 and later requires the use of
non-standard Java APIs ( the File4690 class). As a result, extension MBeans
running on 4690 OS V6 and later require the use of different file APIs than other
platforms. To prevent users from having to make the determination of which file API
to use, the RMA API includes a class, RMAFile, that automatically makes this
determination.
The RMAFile class does not extend java.io.File, but it does provide the same
interface. It also provides methods for creating implementation-specific InputStream,
OutputStream, and RandomAccessFile objects. The determination as to when to use
RMAFile should be made based on the target platforms on which the extension
MBeans will run. If it is known that an extension will not be run on a 4690 OS, then
regular Java APIs can be used when working with files. Otherwise, the RMAFile
class provides a platform neutral option for file access.
Writing and registering your own MBeans

Enabling application components to be managed has numerous benefits, especially
in a store environment with numerous, distributed stores. The ability to expose and
monitor application attributes, manage application configurations, and forward
application events to the enterprise can all provide time and cost savings for your IT
staff. This section describes how to instrument application components with MBeans
using JMX. The steps involved in performing this task include:
Exposing a management interface
Define the MBean interface and implementation for the managed resource.
MBean object naming
Define a unique and structured name for the MBean within the
management infrastructure. This enables a remote management application
to individually search and access each MBean within the store.
MBean registration
Register the MBean with the JMX MBeanServer. This exposes the MBean
for external access.
Distributing the MBean classes
Install the Java class files associated with the MBean into the correct
places within the management infrastructure.
Exposing a management interface

Making a resource manageable involves the creation of an MBean for that
resource. The JMX specification defines multiple types of MBeans, in addition to the

standard MBean, including dynamic, model, and open MBeans. Even though each
is implemented differently and some have additional features for added flexibility,
they all expose a management interface for a managed resource. The standard
MBean is the simplest type of MBean to implement, requiring only that the
managed resource MyClass implements the Java interface MyClassMBean. This
example uses a simple standard MBean called SampleMBean, which exposes a
read/write String attribute, Attribute1, and a read-only boolean attribute, BoolAttr.
An operation called operation1 is also exposed. operation1 takes a single String
parameter and returns an int. The SampleMBean interface is the MBean interface
that 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 Naming

Within the scope of a JMX managed system, an MBean does not derive its unique
identity from the instance itself, as this cannot be viewed across multiple JVMs, but
from a unique characteristic of an MBean: its ObjectName. An MBean ObjectName is
a 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 is
left to the MBean provider. In order to provide some organization of MBeans within
the IBM Remote Management Agent management infrastructure, some rules and
conventions should be applied when naming MBeans.
The value in ObjectNames is in deriving contextual usage from them. Specifically, an

application that consumes these MBeans can benefit from having a known
structured format with specific content. This is the case for the IBM Remote
Management Agent, as it provides context and a structured space that eliminates
the possibility of naming collisions. The ObjectNameFactory class, described below,
creates or reformats ObjectNames in order to comply with RMA Object Naming
conventions.
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 identification
These system-wide identification elements are always obtainable from the
General/Master Agent, using the single instance of ObjectNameFactory
provided in the Remote Management API. Using the createObjectName
methods of this class, it is possible to build a name that is consistent with
the object naming conventions described in this document where these
elements are automatically added.

Remote Management MBean identifier
This identifies an MBean as being related to Remote Management
MBean identifier. Syntax: SIFMBean=true.
Store ID
(RMA V2R4 and earlier) This is retrieved from the Master/General
Agent relationship, and is unique to a given store. It is only applied
to proxied MBeans on the Master Agent. It is a configured element
on the Master Agent. Syntax: StoreID=x.
Device ID
This is an automatically generated element of all agents, and is
unique to each physical device within the store. This value defaults
to the device's host name and then to an integer representing the
device's IP address. For 4690 terminals, it is <controller id>.<
terminal number>, and for controllers, just <controller id>.
Syntax: DeviceID=x.
System ID
This is an automatically generated element of all agents, and is
unique to each agent running in the store. The system ID takes the
form: <deviceId>.<mgmtPort>, where mgmtPort is the agent's
management port. Syntax: SystemId=<deviceId>.<mgmtPort>.
| Agent ID
| This element is exposed automatically on each embedded agent
| MBean proxy. It is used to identify all of the MBeans on a particular
| embedded General Agent. Its value is derived from the embedded
| agent ID supplied during the creation of an embedded General
| Agent.
Component identification
Component name
Unique identification for a functional component (Required). In the
case of the IBM Remote Management Agent components, there is
a list of reserved component names. Syntax: SIFComponent=xyz.
Device major version
The major version of the component being represented (optional).
Syntax: DMajorVer=x.
Device minor version
The 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 value
can be useful for grouping multiple instances of the same MBean
(each with a different ID value). For example, all Data Capture
MBeans have a SIFType=DataCapture.
Unique identifier
Uniquely identifies the MBean within the component and type
(required). For MBeans where only one instance exists in the
system, this is the MBean type (such as SessionManager). For
MBean types that can have multiple instances, add a tag to the
type (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 is
sometimes externally controlled. It is recommended that the default domain of the
MBeanServer be used. The SIFMBean Identifier key is used to identify Remote
Management MBeans.
Putting all of the pieces together, a component builds a base ObjectName by first
constructing the component specific portion and then acquiring the system-wide
information from the from the agent's ObjectNameFactory instance. Prior to V2R2,
the ObjectNameFactory was a singleton (There is still a singleton, but its use is
deprecated). The MgmtAgent interface now provides an ObjectNameFactory for the
agent. The following example illustrates how to create an ObjectName using the
ObjectNameFactory:
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,S
IFComponent=AEF,type=Sample,id=sample1
MBean registration
| Registration of MBeans depends on whether the General Agent is running as an
| embedded agent or as the installed service.
| Embedded Agent registration

All MBeans are Java objects until they are exposed through the JMX MBeanServer
through the registerMBean or createMBean methods. Each MgmtAgent instance
creates and manages an MBeanServer through which MBeans can be added to the
IBM Remote Management Agent infrastructure. The following is an example of how
to obtain the MBeanServer and register an instance of the SampleMBean :
import javax.management.MBeanServer;
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 registration

To add MBeans and Notification Listeners to the startup sequence of the installed
Agent service. For more information see “Agent startup sequence” on page 50.
| Creating An Embedded General Agent

| MgmtAgentFactory.createEmbeddedGeneralAgent(Properties) is a factory method
| introduced with V2R6 to create embedded agents. The Properties object supplied
| as an argument provides all the configuration options, which are described below in
| further detail. This factory method replaces the factory method used prior to RMA
| V2R6, MgmtAgentFactory.getGeneralAgent(). If the getGeneralAgent() method is
| called, 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 to
| make sure you include soxs.jar and sibeep.jar in their classpath for your
| applications.
| Embedded Agent Configuration

| A Properties object supplied for the factory method provides all the configuration
| options 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 no
| agent mode is supplied, remote mode is the default. Local mode is the
| recommended mode for embedded agents not running within 4690 Terminals, as it
| will prevent multiple agent objects for a single system from being discovered and
| displayed on the IBM Director console. Any Java applications running in a 4690
| terminal should supply remote mode because the RMA Service agent does not run
| there. If the embedded agent runs in local mode, it will never get discovered
| because there is not a real agent to discover it.
| The agent ID parameter uniquely identifies the agent among other embedded
| agents on the system, and is used by the RMA service agent to separate the
| MBeans from different embedded agents. Strings that identify the application
| running in the JVM are recommended. The intention is for the agent ID not to
| change, 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 will
| be generated as deviceId random#. If an agent ID parameter is not supplied for a
| remote 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 Communcation

| The local mode embedded agents and the service agent communicate using the
| loopback 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 and
| the connections are unauthenticated. When the embedded agent is running in
| remote mode, the connection stills needs to be encrypted and authenticated. As a
| result, separate SSL configuration, rma-ea-ssl.properties, is used by remote mode
| embedded agents. This configuration is based on the StoreIntegrator AEFBundle
| class so it can be overridden. The default is to use a properties file and separate
| SSL keystore, which is included inside simgmt.jar.
Distributing the MBean classes

Applications get their MBean classes into the class path of the Master or General
Agent by copying JAR files into the \ext directory under the RMA configuration
directory. During startup, JAR files found in this directory are added to the Agent's
class path.
On 4690 V6, the JAR files are added to the RMA classpath by adding the paths to
the RMACPEXT user logical filename.
Making a Remote JMX Connection to the Master Agent

This section describes the interaction with specific Master Agent MBeans. To
interact with the Master Agent MBeanServer in any way, a remote
MBeanServerConnection is required. The JSR-160 specification defines the
interfaces for remote JMX connectivity. The RMA Master Agent supports two remote
JMX implementations: the RMI (Remote Method Invocation) JMX Connector, and
the IBM proprietary SOXS (Serialized Object Exchange/Stream) JMX Connector.
For V2R4 and later agents, the recommended protocol to use is SOXS, although
RMI will still be available. Connections to Master Agents prior to V2R4 should only
use RMI. The following is an example of a class that creates and manages a
JMXConnector instance for obtaining a remote MBeanServerConnection to a Master
Agent:
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 minor
modifications. First, the port used is 10151. Second, general agents only run a
RMI JMXConnectorServer, so connecting using SOXS is not supported. Finally,
the JNDI naming convention is /jndi/hostname.10151, where hostname should
be the actual host name of the system where the general agent is running. You
can 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 standard
security mode that uses certificate-based authentication.
4. The SOXS Connector requires a RMASocketFactory instance to be supplied via
the SoxsConnector.CLIENT_SOCKET_FACTORY property. The SSL configuration
supplied to the RMASocketFactory must match the configuration (SSL/NOSSL)

used on the Master Agent, or else the connection will fail. See “SSL
configuration” 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.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();
// 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 authentication

Object credentials = null;
if( isEnhancedSecurity )
{
// Enhanced security, uses a username and password
MasterAgentCredentialEncoder encoder = new MasterAgentCredentialEncoder();
RMAJMXCredentials credentialInfo =
RMAJMXCredentials.createMasterAgentUsernamePWCredentials( "username", "password" );
credentials = encoder.encodeCredentials( credentialInfo );
}
else
{
// Standard security
RMACredentialEncoder 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 data
if( 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 information

connector = JMXConnectorFactory.newJMXConnector( serviceUrl, properties );
connector.connect( properties );
agentConnection = connector.getMBeanServerConnection();
// Obtain the Master Agent’s device information

initAgentDeviceInfo();
// 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 (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()});
// ...
// ...
// ...
// ...
}
}
}
}
Accessing MBean instrumentation

As discussed in the RMA architecture, the Master Agent is a mid-level manager that
provides access to store resources from a single, centralized location. With an
MBeanServerConnection to the Master Agent, you can access the MBean
instrumentation from the Master Agent or from any General Agent in the store that
the Master Agent discovers. The instrumentation that can be accessed falls into one
of 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 of

MBean instrumentation.
Accessing General Agent MBeans from the Master Agent

The APIs and procedures for accessing store instrumentation changed with RMA
V2R5. This section provides an explanation of how to access store MBeans in RMA
V2R5 and earlier. In the case of RMA V2R5, an example for using the new APIs is
provided.
V2R4 and earlier: On Master Agents running RMA V2R4 and earlier, proxy
MBeans are registered on the Master Agent for every MBean on each General
Agent. You can locate a General Agent MBean by using the query methods on the
MBeanServerConnection interface, such as queryNames(). Using the queried
ObjectName and the MBeanServerConnection, you can get and set attributes (using
getAttribute() and setAttrbute()) and you can invoke methods (using invoke()).

V2R5 and later: Instead of having to query for proxy MBeans and access them
directly through the MBeanServerConnection, you can perform all MBean
operations on store agents by the methods provided in the ProxyManagerMBean. All
accessor methods require the system ID of the agent on which the operation is to
be performed, as well as a query ObjectName for finding the MBean(s) on which to
perform the operation (for example, the getAttribute() method).
The following code is an example of how to invoke the search method on all
MBeans with an MBean ID of Test on agent test.10151, with a string argument of
foo, and a primitive integer argument of 5:
import javax.management.MBeanServerInvocationHandler;
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 MBeans

ObjectName 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 method

Object[] methodParms = { "foo", new Integer(5) };
String[] methodParamTypes = { String.class.getName(), Integer.TYPE.getName() };
// Make call to the proxy manager

Object retVal = proxyMgr.invokeMethod( "test.10151", queryName, "search",
methodParms, methodParamTypes );
}
}
}
Locating Agent MBeans

If you have an MBeanServerConnection object (that is, you are connected to the
Master or a General Agent), you can query for the fully-qualified object names of
any MBean that is registered locally on that agent. For example, consider a custom
MBean 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 MBeanServerConnection
object. 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 register
NotificationListener objects for receiving Notifications through remote JMX
connections. However, any events sent when not connected are not buffered for
when the connection is re-established. Since guaranteed event delivery is not
provided by remote JMX, RMA provides a store and forward feature for events,
explained Chapter 14, “Understanding the architecture,” on page 153. This feature
is implemented on top of JMX, with RMA providing an additional means for event
transport.
Depending on the requirements of a management application, this feature might or

might not be required. As a result, there are two ways of accessing events emitted
by 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 Master
Agent. Use of the NotificationProcessor starts extra threads for event transport
and delivery, creates separate memory buffers on the Master Agent for each remote
JMX connection, sets up a temporary storage locations on the Master Agent for
each remote JMX connection, and uses disk space on the client side to temporarily
store events that overflow from the memory capacity being reached. While the
speed of event transport using both methods is basically the same, the use of the
NotificationProcessor uses additional threads and storage not required by remote
JMX alone.
Adding Notification Listeners

The easiest and simplest option for receiving events from a particular MBean is to
add a NotificationListener directly to that MBean. When events from all agents in
the store are required, then adding a single listener to the
MgmtNotificationControlMBean is the best option. The
MgmtNotificationControlMBean is a central collection point on the Master Agent for
JMX notifications emitted by each General Agent. The MBean re-sends all of the
notifications that it receives after processing them, adding information about the
originating agent. It is from this MBean that the Master Agent's EventControlMBean
receives its events. The following is an example of adding a NotificationListener
to the MgmtNotificationControlMBean. It relies on the MasterAgentConnectionHelper
class outlined in the section “Making a Remote JMX Connection to the Master

Agent” on page 204.
import javax.management.Notification;
import javax.management.NotificationListener;
import com.ibm.retail.si.mgmt.notifications.MgmtNotificationControlMBean;
public class EventExample {
public void example() {

MasterAgentConnectionHelper connectionHelper = new MasterAgentConnectionHelper("127.0.0.1");
MBeanServerConnection agentConnection = connectionHelper.getAgentConnection();
// Create handler for events

NotificationListener myListener = new MyListener();
// Query for ObjectName of the target MBean

ObjectName mgmtNotCtrlName = MgmtUtils.getObjectName(agentConnection, MgmtNotificationControlMBean.OBJECT_NAME_ID);
if(mgmtNotCtrlName == null) {
// Error
} else {
// MBean found, add the listener
try {
agentConnection.addNotificationListener(mgmtNotCtrlName, myListener, null, null);
// MBean not found
// Error making remote call
}
}
}
class MyListener implements NotificationListener {

public void handleNotification(Notification notification, Object handback) {
// Do something with the Notification
}
}
}
The method MgmtUtils.getObjectName() is a convenience way for finding an

MBean's ObjectName based on the value of the ID field. This code simply obtains
the ObjectName of the MgmtNotificationControlMBean, and then calls the method
MBeanServerConnection.addNotificationListener() to add a
NotificationListener instance to receive events from the MBean.
Using the Notification Processor

The NotificationProcessor is a object (not an MBean) on the MA and the Director
Server that acts as a central collection point for all events. It handles the fetching
and delivery of all events from each remote agent's EventControlMBean. By calling
the addEventFetcher() method, a remote JMX Connection to an RMA agent gets
registered. This registration begins the flow of events from the RMA Agent to the
NotificationProcessor by starting a separate thread make remote calls to fetch
groups of events. As each event is delivered, it is forwarded to registered listeners
through the NotificationProcessor's supporting listener interface
(NotificationProcessorListener).
Note: Some lines of code are split over two lines to fit on the page.

import java.util.LinkedList;
import java.util.List;
import javax.management.Notification;
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;
public class NotProcExample {

// 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 numbers

NotificationProcessorData notProcData = new MyNotificationProcessorData();
// Storage object for overflowed events

DiskOverflowStorage diskOverflowStorage = new MyDiskOverflowStorage();
// Use the local host name as the identifier for ourselves to the MA
String localHostName = InetAddress.getLocalHost().getHostAddress();
NotificationProcessor notProc = null;

try {
// Initialize the NotificationProcessor
notProc = new NotificationProcessor(fetchSize, fetchTimeout, memQueueCapacity, notProcData,
diskOverflowStorage);
// Add for fetched events listener, with no filter

MyNotificationProcessorListener listener = new MyNotificationProcessorListener();
notProc.addNotificationProcessorListener(listener, null);
// Start the NotificationProcessor

notProc.start();
// Query for ObjectName of the target Event Control MBean

ObjectName 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 number
return 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 file
return 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 data
return false;
}
/**
* @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#recreateStorage()
*/
public DiskOverflowStorage recreateStorage() throws MgmtException {
// Delete the file and recreate
return null;
}
/**
* @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#restoreMemoryQueue()
*/
public List restoreMemoryQueue() throws MgmtException {
// Read memory contents from disk
return new LinkedList();
}
/**
* @see com.ibm.retail.si.mgmt.util.DiskOverflowStorage#retrieveDataBlock()
*/
public byte[] retrieveDataBlock() throws MgmtException {
// Retrieve the next block of event data
return null;
}
/**
* @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
}
}
}
/**
* @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
}
}
}
Using the FileTransferConnection interface

RMA includes a generic file transfer interface for use by the different underlying
implementations. This interface is described in “File Transfer” on page 168. This
section explains how code inside an agent JVM can use the FileTransferManager
and an implementation of FileTransferConnection interface to create a connection
and 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 {

// Obtain file transfer manager
FileTransferManager xferMgr = FileTransferManager.instance();
// Create connection properties for RMA File Streaming

Properties 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 password
MasterAgentCredentialEncoder encoder = new MasterAgentCredentialEncoder();
RMAJMXCredentials credentialInfo =
RMAJMXCredentials.createMasterAgentUsernamePWCredentials( "username", "password" );
credentials = encoder.encodeCredentials(credentialInfo);
}
else
{
// Standard security
RMACredentialEncoder 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 connection
connectionId = xferMgr.createConnection(xferProps);
FileTransferConnection xferConn = xferMgr.getConnection(connectionId);

// Retrieve file
xferConn.get("C:\\localfile.dat", "C:\\remotefile.dat");
// Other file transfer operations....

} catch (FileTransferException fte) {
// Handle
} finally {
// Release connection
if(connectionId != -1) {
xferMgr.disconnect(connectionId);
}
}
}
}
As is previously described, the singleton FileTransferManager acts a source for all

FileTransferConnections inside an agent JVM. Calling the createConnection()
method on the FileTransferManager creates a FileTransferConnection instance to
be used for transferring files. It returns a connection ID that uniquely identifies the
connection. The method takes a Properties object as an argument that supplies the
information needed to create the connection. The following common properties are
required, and are used to determine which file transfer implementation will be
instantiated. Each implementation has its own required properties specific to that
implementation that are used to initialize and connect the instance. The example
above uses RMA File Streaming, so it will require values for the common properties
in addition top for those specific to RMA File Streaming.
Common properties
Table 33. Common properties
Name Description
com.ibm.retail.si.mgmt.xfer.impl (Required) Identifier for the
implementation, such as STREAM (RMA
File Streaming), FTP, or FTPS
RMAFileTransferConnection properties
Table 34. RMA File Streaming Properties
Name Description
com.ibm.retail.si.mgmt.xfer.stream.hostname (Required) Host name or IP Address
to connect to
com.ibm.retail.si.mgmt.xfer.stream.port (Optional) Overrides the port to
connect to. Defaults to 10190
com.ibm.retail.si.mgmt.xfer.stream.credentials (Required) A byte array of encoded
credential information. The credential
format is the same as for making
JMX connections to that agent
FTPConnection properties
Table 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 properties
Table 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 to

perform file transfer operations. After the instance is no longer needed, the
disconnect() method should be called. This method cleanly disconnects and will
unregister the connection from the FileTransferManager. Even if this method is not
called, a Timer in the FileTransferManager periodically checks each connection and
will eventually disconnect it.
Transfer types
The FileTransferConnection interface supports both blocking and non-blocking
forms of transfers, corresponding to the put() and get() methods and the
putAsync() and getAsync() methods, respectively. The difference between the two
types is that calls to put() and get() block until the transfer completes. Calls to
putAsync() and getAsync() return after the transfer successfully begins and wait in
the background for the transfer to complete. A callback object implementing the
FileTransferEventListener interface is required when making asynchronous calls.
When the transfer completes, either successfully or unsuccessfully, a call is made
to the transferCompleted() method of the callback object to signal completion.

An argument to the handleTransferEvent() method is a FileTransferProgress
object. 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 the

FileTransferProgress object and construct either a
FileTransferProgressNotification 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 of
time. In particular, invoking the operations such as put() and get() on large
files could take a long period of time, possibly resulting in a socket timeout
on the remote JMX call. For transfers that take a large amount of time, an
asynchronous call can be made to ensure that the remote call will not time
out.
When making asynchronous putAsync() and getAsync() calls, a check is made to

see if the connection is busy transferring a file or sending another command. If the
connection is busy, then the request will not be made. This is done to ensure that
remote JMX calls do not block when waiting for a lock on the connection. The
isBusy() method provides non-synchronized access to the busy status of a
connection.
Transfer progress
The asynchronous putAsync() and getAsync() calls also support the ability for
transfer progress to be reported by percentage increments via callbacks. A typical
use for these notifications would be in a management application to implement a
progress bar. Transfer progress is reported via a callback to the
transferProgress() method in the FileTransferEventListener interface. The
FileTransferProgress object returned will include the percentage complete in
addition to the information reported by a transfer completion.
In making asynchronous calls, the transfer progress arguments are optional, and
can range 1-100. Values outside of this range will be ignored. The value supplied
represents the interval at which the Notifications are emitted. For example, a value
of 5 will emit a Notification after 5 percent, 10 percent, 15 percent, and so on, up to
100 percent.
The intervals at which Notifications are emitted are calculated internally based on
blocks of 4 kb (FTP and FTPS). If files are too small, or sizes do not fall on a 4 kb
boundary, the increments will get rounded up.
Calls to getAsync() require a file size to be supplied with the call for calculating the
percentage increments. This is because the FTP protocol does not have a way of
obtaining a remote file's size. If the size and/or increments supplied are not
consistent, then the only Notification sent will be at 100 percent.

Managing monitor policies
Programmatically managing Monitor policies involves making a remote JMX
Connection to the Master Agent MBeanServer and interacting with the
MonitorManagerMBean. Refer to “Making a Remote JMX Connection to the Master
Agent” on page 204 for details of making this connection.
When managing monitor policies on the Master Agent programmatically, two actions
are required:
v Creating and registering a MonitorPolicy object with the MonitorManagerMBean.
v Creating and registering a MonitorPolicyAction object with the
MonitorManagerMBean.
MonitorPolicy object
A MonitorPolicy object contains the details about the JMX MonitorMBean to be
created 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 MonitorMBean
when it is created (for GaugeMonitors, the HighThreshold and LowThreshold
attributes 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 registry

using the addMonitorPolicy() and removeMonitorPolicy() methods.
MonitorPolicyAction object
A MonitorPolicyAction object is for associating a MonitorPolicy with its target
device(s), that can be individual agents, all agents on a single device, or all agents
on all devices of a particular device type. The subclasses of MonitorPolicyAction
each represent a different type of policy application (single agent, device type, and
so on).
MonitorPolicyAction objects are registered and de-registered with the

MonitorManagerMBean using the registerMonitor() and deregisterMonitor()
methods. After a MonitorPolicyAction has been registered with the
MonitorManagerMBean, JMX MonitorMBeans will be created immediately on affected
agents, or when they come online.
The following example creates a MonitorPolicy for the TotalMemory attribute on the
JVMEnvironmentMBean and registers it to be applied on all General Agents running
on Linux:

/*
* 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,"Monitor
JVM 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()});
Managing data capture policies

Programmatically managing data capture policies involves making a remote JMX
Connection to the Master Agent MBeanServer. Refer to “Making a Remote JMX
Connection to the Master Agent” on page 204 for details of making this connection.
Data Capture policies provide an automated way of transferring diagnostic data and
invoking other captures. After a policy is active, it will cause capture files from
completed captures to be transferred, solicited captures to be invoked on capture
MBeans in the policy's capture list, and create capture bundle .ZIP files from
completed invocations. This section provides examples of how to programmatically
manage data capture policies. These examples could be used to create a
management application that connects to the Master Agent, manages policies, and
listens and/or query for invocation status.
Note: The Data Capture Policy Manager task in IBM Director already provides this
functionality.
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 Policy

The following example creates a data capture policy, registers it with the
DataCapturePolicyRegistryMBean, and activates it through a call to the

DataCaptureManagerMBean. Registration of the policy with the
DataCapturePolicyRegistryMBean involves invoking the addCapturePolicy method.
Activating the policy requires invoking the activatePolicy() method on the
DataCaptureManagerMBean.
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;
public class AddCapturePolicy {
public DataCapturePolicy createAndActivateCapturePolicy() {

// Create a remote connection to the Master Agent
/*
* 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 object

DataCapturePolicy policy = new DataCapturePolicyImpl("Capture Policy Description", triggerList, captureList, DataCaptureConst.DEFAULT_CAPTURE_TIMEOUT);
// ..
// ..
// ..
// ..
}
}
// Query for ObjectName of the policy manager MBean
ObjectName captureMgrName = MgmtUtils.getObjectName(agentConnection, DataCaptureManagerMBean.OBJECT_NAME_ID);
if(captureMgrName == null) {
// Error
} else {
// MBean found, activate the policy
try {
agentConnection.invoke(captureMgrName, "activatePolicy", new Object[]{policy.getPolicyId()}, new String[]{String.class.getName()});
// ..
// ..
// ..
// ..
}
}
return policy;
}
}

This example illustrates the use of both types of policy applications, a device type
policy application, and a device policy application. The device type policy
application, which comprises the policy's entire trigger list, matches all agent device
types, all RMA Service General Agents, and the RMALogCaptureMBean. Loosely
worded, this policy application list translates to: "Invoke the capture policy when an
unsolicited capture notification is received from the RMALogCaptureMBean on a RMA
Service General Agent."
The capture list has two individual device policy applications. Each applies to the
GenericLogCaptureMBean on devices MyDevice1 or MyDevice2. Each also supplies
capture arguments to be supplied to the GenericLogCaptureMBean when a capture is
invoked. Loosely worded, this application list translates to: "When a capture
notification is received that applies to the trigger list, invoke solicited captures onto
the GenericLogCapture MBeans on the devices MyDevice1 and MyDevice2.
Receiving Capture Completion Notifications

Capture completion notifications (of type
com.ibm.retail.si.mgmt.notifications.DataCaptureNotification) are sent by
data capture client MBeans (running on the General or Master Agents) when a
solicited or unsolicited capture completes. The easiest way of receiving all of these
events is by registering a single NotificationListener with the
MgmtNotificationControlMBean, described in“Retrieving Store Events (Notifications)”
on page 210.
Each DataCaptureNotification includes information about the capture, including

the capture ID, client paths to the capture files, and error code from the capture. To
determine the agent from which the event (and the capture) originated, examine the
MgmtDeviceInfo object returned from the getOriginatingDevice() method on the
DataCaptureNotification.
Querying Invocation History

The DataCaptureHistoryMBean provides an interface to the logs and capture history
for all registered policies. The capture history for each policy is contained in a
CaptureHistory object, which contain other objects that break down the capture
history in a hierarchical manner. An empty CaptureHistory object is created
whenever a policy is activated.
CapturePolicyInvocationRecords
A CaptureHistory object contains a CapturePolicyInvocationRecord for each time
the policy is invoked on an agent by a DataCaptureNotification or a manual
trigger. The key for an invocation record is its start date, which takes the form of the
Master Agent system timestamp when the invocation was manually triggered or
when an unsolicited capture notification was received. It also has a state that
represents an aggregation of all nested CaptureAgentRecords.
CaptureAgentRecords
A CapturePolicyInvocationRecord contains a CaptureAgentRecord for each agent
involved in each policy invocation. CaptureAgentRecord objects represent policy
activations on an agent, and are used to track the progress and status of a set of
MBean captures on an agent.
CaptureInstanceRecords
A CaptureAgentRecord object contains a CaptureInstanceRecord for each
DataCaptureMBean instance a capture is performed on. One CaptureInstanceRecord
instance contains a set of CaptureFile instances and CaptureLogMsg instances. The

CaptureFile instances contain information about each capture file, and whether it
has been transferred to the Master Agent. Two sets of CaptureLogMsg instances
detail the capture log and the transfer log for that capture. All CaptureLogMsg
instances 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 for
capture messages is com.ibm.retail.si.mgmt.resources.CaptureResources,
located in rma.jar. The parameters are message parameters used to format the
message using the MessageFormat class.
Terminating and Deleting a Data Capture Policy

When 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-active
policies can be removed, so a policy must be terminated before being deleted.
Invoke the terminatePolicy() method on the DataCaptureManagerMBean to
terminate a policy. Invoke the removePolicy() method on the
DataCaptureManagerMBean to remove a policy. The following example terminates and
removes a registered policy:
import com.ibm.retail.si.mgmt.capture.DataCaptureManagerMBean;
import com.ibm.retail.si.mgmt.capture.DataCapturePolicy;
public class TermDeleteCapturePolicy {
public void terminateAndDeletePolicy() {

DataCapturePolicy policy = createAndActivateCapturePolicy();
// Query for ObjectName of the policy manager MBean

ObjectName captureMgrName = MgmtUtils.getObjectName(agentConnection, DataCaptureManagerMBean.OBJECT_NAME_ID);
if(captureMgrName == null) {
// Error
} else {
// MBean found, terminate and delete the policy
try {
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()});
// ..
// ..
// ..
// ..
}
}
}
Managing software distribution policies

RMA provides a RMASWPackageDistributorMBean that automates the creation and
termination of software policies by processing properly formatted JAR files. This
method of distribution takes much of the work from you. The details of using this
MBean are described in “RMA Package Distributor MBean” on page 174.

Applications that require control over the activation and termination of software
policies can do so programmatically. The remainder of this section describes the
actions involves in managing software policies.
Managing software policies programmatically requires a policy XML file and

resource files residing on the Master Agent. This file must be created before
creating and activating policies. For details on the format and content of the policy
XML file, refer to “Software Distribution Policy” on page 178.
All classes related to software distribution policies are in the

com.ibm.retail.si.mgmt.swdist package. The following are the actions involved in
managing software policies:
v Registering a draft policy with the SWDistPolicyRegistryMBean.
v Registering for state and completion notifications with the
MgmtSWPolicyMasterMBean.
v Activating the draft policy.
v Querying the SWDistPolicyHistoryMBean for distribution status and history
information.
v Terminating and deleting a policy.
Registering draft policies

All software polices (active or inactive), are represented as SWPolicy objects.
Before a SWPolicy can be activated, a draft must be registered with the
SWDistPolicyRegistryMBean. The addSWPolicy() method is used to add a draft
SWPolicy on the SWDistPolicyRegistryMBean. From this MBean, it can be updated
or copied using the updateSWPolicy() or copySWPolicy() methods before being
activated. The following is an example of creating and registering a SWPolicy:

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.xfer.stream.RMAFileTransferConnection;
import com.ibm.retail.si.mgmt.xfer.stream.RMAFileTransferConstants;
public class CreateSWPolicy {
public SWPolicy createAndRegisterSWPolicy() {

// Create File Transfer Information

String 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 files

xferInfo.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 immediately
long 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 devices

policy.addAppliedDevice("device1");
policy.addAppliedDevice("device2");
// Set the destination directory on the client

policy.setClientTargetPath("C:\\temp\\mypolicytmp");
// Query for ObjectName of the policy registry MBean

ObjectName swPolicyRegName = MgmtUtils.getObjectName(agentConnection, SWDistPolicyRegistryMBean.OBJECT_NAME_ID);
if(swPolicyRegName == null) {
// Error
} else {
// MBean found, add the policy
try {
Boolean rc = (Boolean) agentConnection.invoke(swPolicyRegName, "addSWPolicy",
new Object[]{policy}, new String[]{SWPolicy.class.getName()});
// ..
// ..
// ..
// ..
}
}
return policy;
}
State and progress notifications

Notifications of type
com.ibm.retail.si.mgmt.notifications.MgmtSWPDeviceStateNotification are
emitted by clients at the start of, during, and at the completion of distributions.
These Notifications can be accessed through the MgmtNotificationControlMBean.

See “MgmtNotificationControlMBean” on page 162.). To ensure that all notifications
are received, NotificationListeners should be added before activating a policy.
The message in each MgmtSWPDeviceStateNotification (by way of

javax.management.Notification.getMessage()) is a formatted message that
contains progress information for the policy invocation on the client. Creating an
instance of com.ibm.retail.si.mgmt.DeviceStateMessage with the message String
will cause the information not be parsed and accessible.
The MgmtSWPDeviceStateNotification also exposes log information in the form of

SWLogMsg instances. Included is log information from standard error, standard out,
and the client during policy invocation. The MgmtSWPDeviceStateNotification also
exposes progress information (number of commands completed, total number of
commands, etc.).
Activating a draft policy

Activating a draft policy requires the activateSWPolicy() method to be called on
the MgmtSWPolicyMasterMBean. The policy ID from a registered draft policy is
required. When activated, a SWPolicy is no longer available to be edited from the
SWDistPolicyRegistryMBean. The following example activates a policy:
import com.ibm.retail.si.mgmt.swdist.MgmtSWPolicyMasterMBean;
public class ActivateSWPolicy {

public void activateSWPolicy(SWPolicy policy) {
// Query for ObjectName of the policy master MBean

ObjectName swPolicyMasterName = MgmtUtils.getObjectName(agentConnection, MgmtSWPolicyMasterMBean.OBJECT_NAME_ID);
if(swPolicyMasterName == null) {
// Error
} else {
// MBean found, activate the policy
try {
agentConnection.invoke(swPolicyMasterName, "activateSWPolicy", new Object[]{new Integer(policy.getPolicyID())},
new String[]{Integer.TYPE.getName()});
// ..
// ..
// ..
// ..
}
}
}
}
Policy invocation history and status

The SWDistPolicyHistoryMBean provides an interface to the logs and distribution
history for all registered policies. The history for each policy is contained in a
SWPolicyHistory object, which contain DeviceSWPolicyRecord objects for each
agent that applies to the policy. The policy ID is the primary means for tracking a

software policy in the SWDistPolicyHistoryMBean, where the getPolicyHistory()
method returns the SWPolicyHistory for a policy.
Terminating and deleting a Policy

When a software policy no longer needs to be in effect, it should be terminated and
then removed. Only non-active policies can be removed, so a policy must be
terminated before being deleted. Invoke the terminatePolicy() method on the
MgmtSWPolicyMasterMBean to terminate a policy. Invoke the removePolicy() method
on the SWDistPolicyRegistryMBean to remove a policy. The following example
terminates and removes a registered policy:
import com.ibm.retail.si.mgmt.swdist.MgmtSWPolicyMasterMBean;
import com.ibm.retail.si.mgmt.swdist.SWDistPolicyRegistryMBean;
public class TermDeleteSWPolicy {

public void terminateAndDeletePolicy() {
// Create and register policy

SWPolicy policy = createAndRegisterSWPolicy();
// Activate the policy

activateSWPolicy(policy);
// Query for ObjectName of the policy master MBean

ObjectName swPolicyMasterName = MgmtUtils.getObjectName(agentConnection, MgmtSWPolicyMasterMBean.OBJECT_NAME_ID);
if(swPolicyMasterName == null) {
// Error
} else {
// MBean found, terminate the policy
try {
agentConnection.invoke(swPolicyMasterName, "terminateSWPolicy", new Object[]{new Integer(policy.getPolicyID())},
new String[]{Integer.TYPE.getName()});
// ..
// ..
// ..
// ..
}
}
// Query for ObjectName of the policy registry MBean

ObjectName swPolicyRegName = MgmtUtils.getObjectName(agentConnection, SWDistPolicyRegistryMBean.OBJECT_NAME_ID);
if(swPolicyRegName == null) {
// Error
} else {
// MBean found, remove the policy
try {
Boolean rc = (Boolean) agentConnection.invoke(swPolicyRegName, "removeSWPolicy", new Object[]{policy},
new String[]{SWPolicy.class.getName()});

// ..
// ..
// ..
// ..
}
}
}
}
SystemStateManager
The SystemStateManager and SystemStateManagerMBean are singleton components
that manage system state transitions during the invocation of a software distribution
policy. The software distribution client uses this functionality in order to change the
system into a certain state before executing a policy and back into the previous
state after executing a policy. The state that it will change to is defined in the
SWPolicy object on the Master Agent.
There are a set of predefined states. The NOOP state does nothing and cannot be
overridden. 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. For
example, it might be desirable for the SW_MAINT state to stop the running POS
Application before actually doing the update to follow. Registration of an instance of
SystemStateHandler to handle the SW_MAINT state is how this task is accomplished.
By default all system state transitions do nothing, so nothing will happen without
any registered SystemStateHandlers.
SystemStateChangeListener and SystemStateChange Notifications

When issuing a state change request, an instance of SystemStateChangeListener is
supplied. For state changes that return Yes or No, this instance is ignored. For a
state change request that is deferred, this instance is the means to notify the
original caller that the state change has completed. For most state change
requests, the listener will be the SystemStateManger itself. When called back by the
handler for a successful state change, the SystemStateManager will send a
SystemStateChangeNotification, which will include the request state. For failed
state changes, a SystemStateChangeErrorNotification will be sent, which will
include the target state, and an error message describing why the state change
failed.
SystemStateHandler
The details of transferring into/out of states is handled by an instance of
SystemStateHandler. 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 the
state change can be performed but it will take a long time, then DEFER should be
returned and the state change executed in a separate thread. The supplied
SystemStateChangeListener provides a way to notify the original caller when the
state change completes.
There is only one SystemStateHandler per agent, with the ability to override the
agent's instance provided by the setSystemStateHandler() method in the singleton
SystemStateManager. Thus, all that needs to be done in order provide a custom set
of system state changes is to implement and register a SystemStateHandler.
Coding best practices

This section describes the task of using error logging and the functions of logging
levels.
Using error logging

Error logs are critical in detecting and correcting application errors. The more
information about what the application was doing at the time of the problem, the
easier it is to resolve the problem. Unfortunately, logging too much information can
have a negative impact on performance. Therefore, finding the right amount of
information to log is important. This task shows you how to log errors in a way that
is consistent with the rest of the IBM Remote Management Agent code. Topics such
as error log entry contents, APIs, and correct use of logging levels are discussed.
Logging levels
Because of the negative impact of logging too much information on the system, it is
important to use logging levels consistently. This enables you to know what kind of
information is logged at each level. Using this knowledge, you can set the logging
level 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 situations
that might require attention.
INFO Interesting runtime events (such as startup and shutdown). Expect
these to be immediately visible in the logs, so be conservative and
keep 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 be
no lower than info. That is, by default debug and trace messages
should not be seen in the logs. You want to have exception and
problem information available for first-pass problem determination in
a production level enterprise application without turning on debug or
trace as default log levels. Too much information is available in these
levels to be appropriate for day-to-day operations. This level is used
for:
v Method entry
v Exit tracing
Logging APIs
Table 38 shows the list of APIs and their effect after factoring and including
differences for both Jakarta Commons Logging and Sun's JDK 1.4. These are the
APIs that Store Integrator uses. The idea behind the Jakarta Commons Logging API
is to be logging implementation independent. So you should treat log.fatal() and
log.error() differently even though they look the same in the error logs. That way
if your logging implementation changes to one that distinguishes between error and
fatal 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: error
text
Log.error() SEVERE Apr 21, 2006 8:10:48 AM Test main SEVERE: error
text
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: error
text
Log.debug() FINE Apr 21, 2006 8:10:48 AM Test main FINE: error
text
Log.trace() FINEST Apr 21, 2006 8:10:48 AM Test main FINEST: error
text
Controlling error log output

The 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 information
is included in the error logs. See “Logging configuration” on page 47 for more
details.
Because logging an error involves some processing time, it is recommended that

you do a test before an error is logged. This way if the error log is just going to be
thrown away, the processing time is avoided. Specifically, it is recommended that
you 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 contents

There are two versions of the log APIs for each logging level. One takes a String
and one takes a String and an exception as a parameter. In order to standardize
the log entries, it is recommended that any errors including exceptions, should be
logged using the two-parameter version of the API, which provides a consistent
appearance in the log entries.

Appendix A. Javadoc pdf file
For API information, refer to the IBM Remote Management Agent Javadoc pdf file
that is associated with this user guide. The Javadoc pdf files for all versions of RMA
can be obtained by going to the IBM Retail Store Solutions Web site at
www.ibm.com/solutions/retail/store/support. Click Publications. Then scroll down to
Remote Management Agent.

Appendix B. Inventory tables
The RMA inventory collection provides a limited subset of the information that IBM
Director can provide. The following table lists the inventory information that IBM
Director 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 inventory
information of each device. The peripheral information is categorized into three
groups of information, with each group representing a database table.
General Properties Table

The first table defined for each device is a general properties table. All devices will
have 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 the
attribute information is defined.
Device Capabilities Tables

The second set of tables defined for each device is the capabilities tables, which
supports all devices. The capabilities tables defines the capabilities of each device,
and includes capabilities that are common for all device types and those capabilities
that are specific to that device. The following tables list the table definitions for each
device. If a device is not listed, it has no device specific capabilities and its table
consists 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 Tables

The third set of tables defined for each device is the properties tables. Not all
devices will have this table, which defines the properties of the device. All properties
in this table are specific to that device. The following tables list the table definitions
for each device that has a properties table. If a device is not listed, that indicates it
has 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 into
the JMX Browser to enhance or limit the functionality. For RMA, there are currently
two special plug-ins that help simplify use of the designated JMX instances: the
Monitor Manager and the RMA Software Package Distributor plug-ins.
The creation of JMX monitors has been replaced with integration into IBM Director
monitoring. Configuration of the RMASWPackageDistributorMBean is only required for
distributing software to agents prior to V2R2.
Create a JMX Monitor Policy

A monitor policy can be created in one of the following ways. From the JMX
browser screen (shown in Figure 119) :
v Right-click in the Object Tree panel on an instance or group and select the
Create Monitor menu option.
v Right-click in the Instance panel on an attribute displayed in the Properties tab
and select Create Monitor.
Figure 119. Create Monitor menu option from the Instance panel
This will start the Monitor Policy Wizard, a dialog to assist with creating monitor
policies.
Monitor Policy Wizard

The purpose of the Monitor Policy Wizard (as shown in Figure 120 on page 250) is
to aid in the creation and modification of policies for the Monitor Manager. The
Monitor Policy Wizard contains two pages in the creation of the policy. The first
page helps to collect the data required to create the policy, and the second page
contains advanced options that can be set for the monitor policy.

Figure 120. Monitor Policy Wizard
The first page of the wizard contains all the main settings for the policy.
Description
Specifies the name of the policy.
Mbean Class
Specifies the name of the class of MBean that the policy is to be geared
towards. When selecting the MBean Class, there is a class of MBean called
CIMProxyMBean. This kind of bean has a special field that is displayed when
selected. This field is CIM Class, where you will specify the type of CIM
Class to be monitored. After selecting the CIM Class or after selecting a
non-CIMProxyMBean bean, the MBean field is ready.
Mbean
Specifies a specific MBean or you can select the '*' to mean any MBean.
Following the selection of the MBean, select the attribute.
Attribute
Monitors a specific attribute of an MBean. By selecting an attribute, you can
narrow down the type of monitor policy to create, which will be visible in the
next drop-down field, which is the monitor type field.
Initial Threshold Number
Indicates the specific fields needed by the selected monitor type.
After you complete the fields in Figure 120, click Finish to save the policy. To select
advanced options, click Next to continue to the next page.
If you check Apply policy when finished, the Apply Monitor Policy dialog is
displayed.

Counter Monitor advanced options
There are three advanced options for the Counter Monitor (Figure 121). These
option are not the same for all the monitor types, so complete these carefully. The
default values are entered for you.
Granularity Period
Specifies the frequency in which the monitor will check for changes.
Offset Number
Specifies to the monitor the value to be added to the monitor's threshold
after the observed attribute exceeds the current threshold value.
Modulus Number
Specifies to the monitor what the counter's maximum value can be before
rolling over to 0.
Figure 121. Counter Monitor Advanced Options panel
Gauge Monitor advanced options

There are three advanced options for the Gauge Monitor (as shown in Figure 122
on page 252):
Notify High
Notifies the monitor to generate an event when the value being monitored
changes and becomes higher than the range entered in the high and low
thresholds.
Notify Low
changes and becomes lower than the range entered in the high and low
thresholds.
Granularity Period
Appendix D. JMX Browser Plug-Ins 251

Figure 122. Gauge Monitor Advanced Options panel
String Monitor advanced options

There are three advanced options for the String Monitor (as shown in Figure 123 on
page 253):
Notify Match
changes and it matches the compare string.
Notify Differ
changes and it does not match the value being compared.
Granularity Period

Figure 123. String Monitor Advanced Options panel
Boolean Monitor advanced options

There are three advanced options for the Boolean Monitor (as shown in Figure 124
on page 254):
Notify True
changes and it is equal to True.
Notify False
changes and it is equal to False.
Granularity Period
Specifies the frequency in which the monitor will check for changes to the
value.

Figure 124. Boolean Monitor Advanced Options panel
Apply Monitor Policy dialog

Clicking Apply opens the Apply Monitor Policy dialog (as shown in Figure 125 on
page 255). You must choose the target to which to apply to the monitor:
Device Type
Applies the monitor to all systems of a specific device type, which is the
default. If you select this option, you must also must select a Target
Identifier from the drop-down list, indicating the device type.
Individual Device
Applies the monitor to all agents on a specific target system. If you select
this option, you must also select a Target Identifier from the drop-down list,
indicating the name of the device.
Individual Agent
Applies the monitor to a specific agent on a specific target system. If
selected, you also must select a Target Identifier from the drop-down list,
indicating the device name and port.

Figure 125. Apply Monitor Policy frame
After you select the target type and chose the target identifier, click Apply to
complete the application of the monitor policy to the chosen system or systems.
Monitor Manager plug-in

The Monitor Manager plug-in provides a way to apply a Monitor Policy instance and
register 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 Monitor
Manager plug-in, there are two tabs. The first tab, Policies, displays all the policies
on the Managed Objects. The Applied Policies tab shows all the policies that have
been applied.
Policies tab
The Policies tab provides a table that is used to display all policies. The table
displays the name of the policy and the ID of the monitor bean that it is
representing (as shown in Figure 126 on page 256).

Figure 126. Policies tab
On the Policies tab, you can manage all policies:

v Click Edit to modify the selected policy. If more than one policy is selected, the
Edit 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 Apply
opens the Apply Monitor Policy dialog. See “Apply Monitor Policy dialog” on page
254 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 when
multiple policies are selected.
Applied Policies tab

On 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 of
the 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 127. Applied Policies tab

Notices
References in this publication to IBM products, programs, and services do not imply
that IBM intends to make these available in all countries in which IBM operates. Any
reference 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, or
service that does not infringe any of IBM's intellectual property rights can be used
instead of the IBM product, program, or service. Evaluation and verification of
operation in conjunction with other products, except those expressly designated by
IBM, are the user's responsibility.
IBM might have patents or pending patent applications covering the subject matter
in this document. The furnishing of this document does not give you any license to
these patents. You can send license inquiries, in writing, to:
IBM Director of Licensing
IBM Corporation
North Castle Drive
Armonk, NY 10504-1785
U.S.A.
The following paragraph does not apply to the United Kingdom or any other country
where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS
MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT
WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. Some states
do 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 be
incorporated in new editions of the publication. IBM might make improvements
and/or changes in the product(s) and/or program(s) described in this publication at
any time without notice.
Any references in this information to non-IBM Web sites are provided for
convenience only and do not in any manner serve as an endorsement of those
Web sites. The materials at those Web sites are not of the materials for this IBM
product and use of those Web sites is at your own risk.
Information concerning non-IBM products was obtained from the suppliers of those
products, their published announcements or other publicly available sources. IBM
has not tested those products and cannot confirm the accuracy of performance,
compatibility or any other claims related to non-IBM products. Questions on the
capabilities of non-IBM products should be addressed to the suppliers of those
products.
This product includes software developed by the MX4J project

(mx4j.sourceforge.net) and by the Apache Software Foundation (www.apache.org/).
Trademarks
IBM, ThinkVantage, Tivoli, Wake on LAN, and WebSphere are trademarks of
International Business Machines in the United States or other countries, or both.

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in
the United States or other countries, or both.
Microsoft, Windows and the Windows logo are trademarks of Microsoft Corporation
in the United States or other countries, or both.
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.

Index
Numerics coding best practices 228
common properties 215
4690 OS installation 30
component JVM registration 202
components, description 154
configuration
A CIM 167
accessing General Agent MBeans 208 configuration, agent 41
accessing MBean instrumentation 208 configuration, client 162
advanced options configuration, logging 162
boolean monitor 253 configuration, security 43
counter monitor 251 configuration, SSL 44
gauge monitor 251 content, software policy 181
string monitor 252 conventions xvi
agent application roles 155 counter monitor advanced options 251
agent class path and environment 46
agent configuration 41, 51
agent configuration file 41
agent JVM diagnostics 143
D
data
agent properties 41
capturing 185
agent roles 52
data capture 184
agent startup sequence 50
data capture implementations
agent Windows event log integration 52
deleting 131
AgentStartupMBean 51
data capture policies 131
architecture 147
associating 132
architecture, understanding 153
capture bundle
associated policy manager
retrieving 137
invoking associated subtasks 134
deleting from capture history 136
associations 65
managing 219
attributes, managed objects 64
manipulating associated 133
refreshing displayed capture history 135
removing associations 134
B status frame 134
best practices 228 viewing associated 132
boolean monitor advanced options 253 viewing capture history 135
data capture policy 188
activating 219
C adding 219
capture bundle directory 191 creating 219
capture completion notifications deleting 222
receiving 221 terminating 222
capture file processing 193 data capture policy manager
capture file transfer 192 data capture implementations
capture history cleanup 193 adding 129
capture history information 193 creating 129
capture policy application 191 editing 130
capture processing 186 removing 129
CaptureAgentRecords 221 right pane 129
CaptureInstanceRecords 221 data capture implementations Pane (right
CapturePolicyInvocationRecords 221 pane) 129
capturing data 185 data capture policy 124
CD-ROM xvi creating 123
CHXI 199 deleting 124
CIM Adapter MBean 164 finding in tree 127
CIM configuration 167 renaming 123
CIMEventMapper interface 165 Data Capture Policy Group
class creating 121
RMAfile 199 deleting 122
client configuration 162 renaming 122

data capture policy manager (continued) extensions, IBM Director 59
data collection 118 extensions, installing 33
device types extrinsic event registrations 166
adding 127
removing 127
device types pane (center pane) 129 F
exporting policies to file 125 file transfer 95, 168
file menu 119 file transfer error handling 193
help menu 121 file transfer implementations 170
importing policies from file 126 file transfer overview 6
menu bar 119 files
policies pane (left pane) 121 RMAfile class 199
policy group files, OS settings 82
moving 124 FileTransferConnection 169
removing 124 FileTransferConnection interface
tasks 117 FileTransferConnection interface, using 214
Data Capture Policy Manager task 66 forwarding, log 162
data capture properties 43 FTPConnection properties 215
DataCaptureManagerMBean 189 FTPSConnection properties 216
DataCaptureMBean 185
DataCaptureMBeanSupport 187
DataCapturePolicy class 190 G
delete package 93 gauge monitor advanced options 251
Deploying package 94 General Agent 153, 154
deployment scenarios overview 9 General Agent MBeans, accessing 208
destination directory, OS settings 82 General Agent service registration 203
development environment 197 general properties table 235
device capabilities tables 235 Getting package files to the Master Agent 175
device properties tables 242 Groups 60
diagnostic data capture overview 6 groups, security 19
Director Console 60 guide, using xv
disciplines, RMA 149
disconnect() 216
discovery 67
Discovery Preferences panel 67
H
handler levels
distributing the MBean classes 204
adjusting using JMX Browser 102
distribution, software 78
hardware requirements 17
draft policies
health checking 154
activating 225
registering 223
dynamic groups 62
I
IBM Director
E events per minute 144
troubleshooting 144
Edit Package 93
high log collection 144
Editing a software package 80
JVM diagnostics 145
editor, software package 79
log collection settings 144
Embedded Agent 153
RAS logging 144
error log entry contents 230
IBM Director Console 60
error log output 229
IBM Remote Management Agent xv, 149
error logging 228
import file format table 70
event action plans 75
import package 93
event fetching properties (Master Agent only) 43
importing, threshold plans 113
event infrastructure, RMA 159
in-store processor 17
event log 75
indications
event properties 42
MSStorageDriver_FailurePredictEvent 166
EventControlMBean 161
RSS_SpNumericSensorAlert 166
events overview 5
UPOS 166
examples, programming 199
infrastructure overview 7
executable commands, OS settings 83
infrastructure, event 159
export package 94

installation 21, 33
CD 21
M
making a remote JMX connection to the Master
interactive 21
Agent 204
Linux 27, 29
managed object attributes 64
installation procedure
managed object groups 60
interactive 21
Managed Object groups 61
installation roles, IBM Director 18
managed object states 64
installation, SFCB 27, 28
managed object types 63
installing 21
managed objects 62
installing extensions 33
management agent discovery 154
installing IBM Director extensions 59
management interface, exposing 199
installing Remote Management Agent 13
Management model 151
instance panel
Master Agent 153, 154
methods 98
Master Agent, adding 67
Instance panel 97
Master Agent, editing 69
properties 97
Master Agent, exporting list 71
interactive installation 27
Master Agent, importing list 69
interactive installation procedure 29
Master Agent, removing 69
interactive installation, Linux 34
MBean instrumentation, accessing 208
interactive installation, Windows 33
MBean object naming 200
interactive uninstallation
MBean registration 202
procedure 37
MBeans
introducing Remote Management Agent 1
registering 199
inventory 74, 163
writing 199
inventory collection 74
MBeans, locating agent MBeans 209
inventory overview 6
method execution dialog 99
inventory tables
MgmtClientHealthMBean 154
inventory tables, RMA 233
MgmtMasterHealthMBean 154
inventory, viewing 74
MgmtNotificationControlMBean 162
invocation history
Mid-level management 150
querying 221
monitor manager plug-in 255
monitor policies, managing 218
monitor policy
J creating 249
JAR files 197 wizard 249
Java 2 requirements 17 Monitor policy 171
Java class path 46 monitor policy dialog
JAVA Management Extensions 149 applying 254
Javadoc pdf file 231 monitor policy wizard 249
JMX Browser 95 monitoring overview 6
JMX Browser task 66 MonitorPolicy object 218
JMX connection, remote MonitorPolicyAction 218
Master Agent, making a remote JMX MSStorageDriver_FailurePredictEvent indications 166
connection 204
JMX tree panel 96
N
notices 257
L notification listeners 210
Linux uninstallation notification processor
procedure 39 using 211
locating agent MBeans 209 NotificationProcessor 162
log directories 143 notifications
log forwarding 162 progress 224
log, event 75 retrieving 210
logging APIs 229 state 224
logging configuration 47, 162 SystemStateChange 227
logging levels 48, 228 SystemStateChangeListener 227
adjusting using JMX Browser 102
logging parameters 49
Index 261
O Remote Management Agent, installing 13
Remote Management Agent, introducing 1
object naming, MBean 200
Remote Management Agent, using 13
objectives 147
Remote Management General Agent 21
operating system settings 81
Rename Package 93
Outer tags and attributes 181
resource monitors 103
overview 149
threshold monitor 104, 108
overview, deployment scenarios 9
retail devices 63
overview, diagnostic data capture 6
Retail Extensions for IBM Director uninstallation
overview, events 5
notes 39
overview, file transfer 6
Retail Extensions silent installation 35
overview, infrastructure 7
retail peripheral management 113
overview, inventory 6
console 114
overview, monitoring 6
retail peripheral management overview 6
overview, power management 5
Retail Peripheral Management task 66
overview, retail peripheral management 6
retries 193
overview, RMA 5
RMA data capture
overview, software distribution 5
policy invocation
invoking 137
RMA events 160
P RMA overview 5
package creation 85 RMA package distributor MBean 174
package creation for update 31 RMA Software Distribution 172
package editor, software 79 RMA Software Distribution task 66
package general information 80 RMADataCaptureMBean 189
package JAR file format 175 RMAfile class 199
package staging 176 RMI Properties 42
Package Wizard 80 roles, agent 52
Peripheral Type, description 115 RSS_SpNumericSensorAlert indications 166
plug-ins RtlNotifications 160
monitor manager 255
Policy invocation 192
policy invocation history 225
policy invocation status 225
S
Security configuration 43
policy XML variables 184
security groups 19
post capture file processing 192
security modes 19
post capture file transfer 192
setting up development environment 197
post installation
severity mapping 78
Linux 29
SFCB installation 27, 28
Windows 26
silent installation 30
post-distribution action, OS settings 85
silent uninstallation
power management 138
procedure 38
power management overview 5
software distribution 78
problem determination
Software Distribution 4690 Command Wizard 87
solutions 146
software distribution overview 5
symptoms 146
software distribution policies 222
problem symptoms 146
Software Distribution Policy 178
product
software distribution, RMA 172
overview 149
software package creation 85
programming 195
software package editor 79
programming examples 199
software package, editing 80
programming IBM Remote Management Agent 199
software policy
progress notifications 224
deleting 226
publications, related xvi
terminating 226
software policy content 181
software policy target device content 182
R Software Policy XML file structure 180
RAS log collection 144 software requirements 17
registration, MBean 202 SSL configuration 44
related xvi starting Discovery 71
related publications and diskettes xvi state notifications 224

states, managed object 64 Windows installation 21
Storage 171 Windows PATH 47
Store Authorization Management task 66, 72 wizard, package 80
store events writing MBeans 199
retrieving 210
Store Integration Framework 154
string monitor advanced options 252 X
subtasks, software package 87 XML variables, policy 184
delete package 93
Deploying package 94
Edit Package 93 Z
export package 94 zip files 197
import package 93
Rename Package 93
summary of changes xix
supported operating systems 17
SystemStateChange
SystemStateChange 227
SystemStateChangeListener 227
SystemStateChangeListener 227
SystemStateHandler 227
SystemStateManager 227
T
tasks 65
threshold plans, importing 113
trademarks 257
Transfer progress 217
Transfer types 216
troubleshooting 143
logs 143
problem 143
solution 143
U
uninstallation 37
uninstallation notes, Retail Extensions for IBM
Director 39
uninstallation result 39
uninstallation, Linux 39
uninstallation, silent 38
updating RMA 30
UPOS 113
UPOS indications 166
UPOS inventory tables
inventory tables, UPOS 235
user-defined monitors 110
using JMX Browser 102
using Remote Management Agent 13
V
viewing inventory 74
W
Web site xvi
Windows event log integration, agent 52
Index 263
Readers’ Comments — We'd Like to Hear from You
User's Guide
Version 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 the
information 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 IBM
business partner, or your authorized remarketer.
When you send comments to IBM, you grant IBM a nonexclusive right to use or distribute your comments in any
way it believes appropriate without incurring any obligation to you. IBM or any other organizations will only use the
personal 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 You Cut or Fold
GC30-4106-10 Along Line
_ _ _ _ _ _ _Fold
_ _ _and
_ _ _Tape
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Please
_ _ _ _ _do
_ _not
_ _ staple
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _Fold
_ _ _and
_ _ Tape
______
NO POSTAGE
NECESSARY
IF MAILED IN THE
UNITED STATES
BUSINESS REPLY MAIL

FIRST-CLASS MAIL PERMIT NO. 40 ARMONK, NEW YORK
POSTAGE WILL BE PAID BY ADDRESSEE
IBM Corporation
Retail Store Solutions Information Development, Dept ZBDA
P. O. Box 12195
RESEARCH TRIANGLE PARK NC 27709-9990
_________________________________________________________________________________________
Fold and Tape Please do not staple Fold and Tape
Cut or Fold
GC30-4106-10 Along Line

Program Number: 5639-FF1
GC30-4106-10

IBM RMA Userguide

Caricato da

Informazioni sul documento

Descrizione originale:

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

IBM RMA Userguide

Caricato da

Copyright:

Formati disponibili

Remote Management Agent

About this guide . . . . . . . . . . . . . . . . . . . . . . . . xv

Summary of changes . . . . . . . . . . . . . . . . . . . . . . xix

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

Chapter 1. Retail systems management . . . . . . . . . . . . . . . 3

Chapter 2. RMA Overview . . . . . . . . . . . . . . . . . . . . . 5

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

Chapter 4. Deployment scenarios. . . . . . . . . . . . . . . . . . 9

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

Chapter 5. RMA Requirements . . . . . . . . . . . . . . . . . . 17

© Copyright IBM Corp. 2004, 2010 iii

| Chapter 6. Understanding RMA Security . . . . . . . . . . . . . . 19

Chapter 7. Installing the Remote Management General Agent and Master

Chapter 8. Installing Retail Extensions for IBM Director . . . . . . . . 33

Chapter 9. Uninstalling IBM Remote Management Agent . . . . . . . . 37

Chapter 10. Agent configuration . . . . . . . . . . . . . . . . . . 41

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

iv RMA V2R6 User's Guide

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

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

Chapter 13. Architecture overview and objectives . . . . . . . . . . 149

Chapter 14. Understanding the architecture . . . . . . . . . . . . . 153

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

Chapter 15. Development environment . . . . . . . . . . . . . . . 197

Chapter 16. Programming examples . . . . . . . . . . . . . . . . 199

vi RMA V2R6 User's Guide

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

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

Appendix C. UPOS Inventory Table Definitions . . . . . . . . . . . 235

Appendix D. JMX Browser Plug-Ins . . . . . . . . . . . . . . . . 249

x RMA V2R6 User's Guide

xiv RMA V2R6 User's Guide

Who should read this guide

How this guide is organized

© Copyright IBM Corp. 2004, 2010 xv

Conventions used in this guide

xvi RMA V2R6 User's Guide

About this guide xvii

Web-only update of GC30-4106-08

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

Web-only update of GC30-4106-07

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

Web-only update of GC30-4106-06

© Copyright IBM Corp. 2004, 2010 xix

Web-only update of GC30-4106-05

Web-only update of GC30-4106-04

xx RMA V2R6 User's Guide

Chapter 2. RMA Overview . . . . . . . . . . . . . . . . . . . . . 5

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

Chapter 4. Deployment scenarios. . . . . . . . . . . . . . . . . . 9

© Copyright IBM Corp. 2004, 2010 1

The need for systems management

Systems management is usually thought of as covering some portion or all of the

All of these functional disciplines, working together, form a comprehensive

The importance of standards

4 RMA V2R6 User's Guide

© Copyright IBM Corp. 2004, 2010 5

Inventory and Asset tracking

Monitoring Retail Systems

Diagnostic data capture

Retail peripheral management

6 RMA V2R6 User's Guide

WebSphere Custom IBM Director