RMA V3R2.2 Users Guide

Toshiba Global Commerce Solutions
Remote Management Agent
User's Guide
Version 3.2.2
GC30-4106-17
1
Note:
Before using this information and the product it supports, be sure to read the general information under “Notices” on page
393.
September 2017
This edition applies to Version 3.2.2 of the licensed program Remote Management Agent (program number 5639-TK4) and to
all subsequent releases and modifications until otherwise indicated in new editions.
If you send information to Toshiba Global Commerce Solutions (Toshiba), you grant Toshiba a nonexclusive right to use or
distribute whatever information you supply in any way it believes appropriate without incurring any obligation to you.
© Copyright Toshiba Global Commerce Solutions, Inc. 2017
Contents
Figures.......................................................7 Java..................................................................................... 30
Supported operating systems......................................... 30
Tables...................................................... 13 POS sensor drivers........................................................... 30
Touch screens ...................................................................31
UPOS Peripherals.............................................................31
About this guide..................................... 15 Compatibility with prior versions of RMA.........................31
Who should read this guide.................................................. 15 RMA Master and General agents...................................31
Where to find more information...........................................15 RES/Director......................................................................31
Additional references............................................................. 15 Network requirements........................................................... 31
Conventions used in this guide............................................ 16 Discovering General Agents that are on different
Notice statements....................................................................16 subnets than the Master Agent............................................. 33
Summary of changes............................. 17 Chapter 4. Installation Overview........... 35

September 2017........................................................................17 Step 1 - Downloading IBM Systems Director Server 6...... 36
Web-only update of GC30-4106-16.......................................17 Step 2 - Downloading RMA and the Retail
Update of GC30-4106-15........................................................ 17 Extensions for IBM Systems Director...................................37
Step 3 – Installing IBM Systems Director Server 6............. 38
Step 4 - Install IBM Systems Director Hotfixes...................38
Part I. Introducing Remote Step 5 – Installing RMA Retail Extensions for IBM
Management Agent................................ 19 Systems Director Server......................................................... 38
Step 6 – Installing RES............................................................39
Step 7 – Verify Retail Extensions for IBM Systems
Director and RES Installation ............................................... 39
Chapter 1. RMA Overview...................... 21 Step 8 - Installing RMA MA.................................................. 39
Event Management and Health Status................................ 21
Step 9 - Installing RMA GA................................................... 39
Power Management of POS Systems................................... 21
Step 10 - Launch RMA Store Manager.................................40
Monitoring Retail Systems.....................................................21
Step 11 - Configure RMA Store Manager to Discover
Retail peripheral management..............................................21
RMA MA.................................................................................. 40
Inventory.................................................................................. 21
Step 12 - Authenticating to Agents Running
Software distribution..............................................................22
Enhanced Security from Director UI....................................40
Chapter 2. Infrastructure Chapter 5. Installing IBM Systems

components............................................ 23 Director Server 6.....................................41
Installing for Windows ........................................................ 41
™
Installing on Linux..................................................................47
Part II. Installing and using the 32/64 bit libraries during Director installation ...................48
Remote Management Agent.................. 25
Chapter 6. Installing and upgrading
Chapter 3. RMA Requirements.............. 27 Retail Extensions and RES on
Hardware requirements.........................................................27
IBM Systems Director Server hardware
Windows.................................................. 49
requirements .................................................................... 27 Installing and upgrading Retail Extensions for IBM
IBM Systems Director / Retail Enterprise Service Systems Director on Windows..............................................49
software requirements............................................................28 Verify RMA Retail Extensions for IBM Systems
Java..................................................................................... 28 Director Server Installation.............................................55
Supported Operating Systems........................................29 Installing RES on Windows................................................... 55
IBM Systems Director Server..........................................29 Upgrading Retail Extensions on the Windows
Director Server database requirements.........................29 platform ................................................................................... 62
Browser Requirements.................................................... 29 Upgrading RES on Windows platform................................63
RMA software requirements................................................. 30
© Copyright Toshiba Global Commerce Solutions, Inc. 2017 3

Chapter 7. Installing and upgrading Chapter 10. Uninstalling Retail
Retail Extensions and RES on Linux.... 65 Extensions for IBM System Director.. 113
Installing Retail Extensions for IBM Systems Director
on Linux....................................................................................65
Post installation................................................................ 69 Chapter 11. Uninstalling Toshiba
Execution logs................................................................... 70
Upgrading Retail Extensions for IBM Systems Director... 70
Retail Enterprise Service..................... 115
Interactive uninstallation for Windows.............................115
Installing RES for Linux......................................................... 71
Uninstallation result............................................................. 115
Post installation - Linux...................................................75
Un-installing Retail Enterprise Service on Linux ............ 116
Execution logs - Linux..................................................... 76
Upgrading RES on Linux ............................................... 76
Chapter 12. Understanding RMA

Chapter 8. Installing RMA (MA and Security ................................................ 117
Master Agent Security Modes.............................................117
GA)........................................................... 79 Installation and upgrades............................................. 117
Default Installation Location for RMA V3.......................... 79
Security groups...............................................................117
SI_HOME and RMA_ROOT Environment Variables........79
General Agent Security........................................................ 119
Interactive installation on Windows.................................... 79
4690OS Whitelisting Support for RMA............................. 119
Installation procedure......................................................79
Silent installation of RMA on Windows.............................. 91
Using Update Manager for transferring JRE to RMA
systems..................................................................................... 92 Chapter 13. RMA Agent
Using Update Manager for the Remote Management configuration.........................................121
Agent.........................................................................................92 Directory structure................................................................121
Interactive installation on Linux ..........................................92 Agent configuration file................................................ 121
Linux Support in RMA V3.............................................. 92 Overriding Store Id in 4690 Master Agent................. 124
Linux prerequisites.......................................................... 92 Security configuration................................................... 125
Small Footprint CIM Broker........................................... 93 SSL configuration........................................................... 126
SFCB Installation.............................................................. 93 Updating SSL.protocol property using Software
SFCB configuration.......................................................... 94 Distribution..................................................................... 127
Starting SFCB on startup................................................. 95 MD5 algorithm support................................................ 127
Configuring RMA for SFCB Connection...................... 95 New SSL/TLS certificate................................................ 128
SFCB troubleshooting...................................................... 95 Updating SSL certificates.............................................. 128
Upgrading from RMA V2............................................... 96 Agent class path and environment.............................. 139
Installation and Upgrade Procedures ................................. 96 Logging configuration................................................... 140
Upgrade............................................................................. 96 Agent startup sequence................................................. 143
Installation.........................................................................96 Agent roles...................................................................... 144
Post installation - installation and upgrade Agent Windows event log integration........................ 145
procedures......................................................................... 97
RMA on 4690 .......................................................................... 97
Interactive fresh installation of RMA on OS 4690....... 98 Chapter 14. Retail Enterprise Service
Post installation................................................................ 99
Interactive Upgrade of RMA on OS 4690................... 100
................................................................153
The RMA Store Manager..................................................... 153
Upgrade RMA on OS 4690 through ASM.................. 101
Launching RMA Store Manager using Java WebStart.... 154
Setting up RMA on 4690 ...............................................101
Troubleshooting launch in context tasks...........................158
Verifying your 4690 RMA setup.................................. 107
Application Blocked by Security Settings......................... 159
JNLP workaround for Linux/JWS/Firefox ........................159
Launching RMA Store Manager from a command
Chapter 9. Uninstalling Remote prompt.................................................................................... 159
Management Agent ............................. 109 Using the RMA Store Manager........................................... 160
Interactive uninstall for Windows......................................109 Adding Store Connection entries.................................160
Silent uninstall on Windows............................................... 111 Viewing the status of Store Connections.................... 162
Uninstall result...................................................................... 111 Authorizing Store Connections.................................... 163
Uninstall for Linux................................................................111 Editing Store Connection entries................................. 165
Searching for Store Connections.................................. 167
Exporting Store Connection entries.............................169
4 RMA 3.2.2 User's Guide

Importing Store Connection entries............................ 171
Diagnosing Connection Issues from the RMA Store
Manager..................................................................................172 Chapter 18. Introduction to Health
Managing data captures.......................................................173
Viewing data captures................................................... 173
Status.....................................................279
Event log view....................................................................... 279
Saving data captures...................................................... 175
Various views of the Health Status: .................................. 280
Cancelling the data capture transfers..........................178
Welcome summary page:..............................................280
Deleting the data capture bundles...............................178
Health Summary view...................................................281
Resource Navigator view.............................................. 282
Resource Properties view..............................................283
Chapter 15. RMA and IBM Systems Active Status view..........................................................283
Director basics......................................181 Problems view................................................................ 284
Introduction to RMA and IBM Systems Director basics. 181 Actions on problem/active status entries....................284
Access states of managed end points in IBM
Systems Director ............................................................181
Resources......................................................................... 182 Chapter 19. Agent Monitoring ............ 289
Using the IBM Systems Director Console......................... 182 System Events........................................................................290
Logging into the Director Console...............................182 System LED monitoring.......................................................290
Resource Explorer.......................................................... 184 Event types - LED monitoring......................................290
Custom groups - dynamic and static................................. 190 Hardware sensor monitoring.............................................. 291
Director Groups.............................................................. 190 Event types listing.......................................................... 291
Creating a criteria-based dynamic group................... 190 Resource Monitoring............................................................ 292
Creating a static group.................................................. 193 Event Types - Resource monitoring................................... 292
Discovery................................................................................199 SSD Life Monitoring on 4690 OS........................................ 292
Retail Store Authorization............................................ 205 Event type listing............................................................292
Query/Verify Connection..............................................209 Peripheral Monitoring..........................................................293
MEP Deletion.................................................................. 211 End of Life monitoring of POS Printer attributes......294
End of life monitoring of RSS display......................... 296
Generic (User defined) monitoring.................................... 298
Chapter 16. Using inventory................ 213 MBean/CIM specification.............................................. 300
Collecting Inventory............................................................. 213 Configuration........................................................................ 301
Inventory Performance Tip...........................................219 MonitorPolicies.xml property definitions:................. 301
Viewing inventory................................................................ 220 GenericMonitorPolicies.xml property definitions.....303
Report Terminal Sales Version inventory......................... 225
ACE PIN PAD inventory..................................................... 226
Exporting inventory data.....................................................227 Chapter 20. Software Distribution.......309
Add and position Serial Number to the Resource RMA Package Overview......................................................309
Explorer columns displayed in the Director RES Software Package Manager ................................. 309
Console.............................................................................228 Using Update Manager................................................. 326
Chapter 17. Event management.......... 233 Chapter 21. Power Management......... 359
Introduction to Event management................................... 233
Event management resources.......................................234
Using the Director Event Log ...................................... 234 Chapter 22. Troubleshooting
Configuring the event Log............................................ 238
Managing event filters..........................................................255 problems............................................... 367
Managing event types.......................................................... 255 Logs......................................................................................... 367
Defining an event action plan............................................. 256 RMA Agents....................................................................367
Using the event action plan builder............................ 256 Agent JVM diagnostics.................................................. 368
Associating the event action plan................................ 258 IBM Systems Director information.............................. 368
Activating the event automation plan.........................264 Troubleshooting.................................................................... 370
Verifying the event automation plan.......................... 266 RMA utilities..........................................................................372
Event management for 4690 operating systems............... 266
Event severity override in 4690.................................... 276
Event severity overrides file on IBM Systems Appendix A. Stopping and starting
Director............................................................................ 277 RMA Director RES................................ 375
System event config file on Master Agent ................. 277
Contents 5
Appendix B. Agent Monitoring
Support..................................................377
Appendix C. SLEPOS Server-Client

setup...................................................... 379
SLEPOS 11 SP3 Server-Client Setup...................................379
SLEPOS Installation:...................................................... 379
Creating an image with RMA package:...................... 379
Creating image with Java POS:.................................... 380
Creating image with Hardware Sensors.....................380
Appendix D. Using Update Manager

for transferring JRE to RMA systems.381
For Windows Agents............................................................381
For Linux Agents...................................................................386
Notices....................................................................................393
Trademarks............................................................................ 394

Figures
1. RMA infrastructure.............................................................23 40. After installing RES - part 1.............................................61
2. Recommended hardware requirements for IBM 41. After installing RES - part 2.............................................61
Systems Director Server......................................................... 28
42. RES directory structure.................................................... 62
3. General Agents that are on different subnets................. 33
43. Upgrading Retail Extensions for IBM Systems
4. IBM Systems Director ........................................................36 Director.....................................................................................63
5. IBM Systems Director sign in............................................ 37 44. Upgrade RES from 3.1.x to 3.2.x..................................... 64
6. Initial Setup..........................................................................37 45. Linux ISD directory.......................................................... 66
7. Download package............................................................. 38 46. Step 3 - installation............................................................66
8. Starting the installation - Welcome.................................. 41 47. Step 4 - installation............................................................67
9. Database information......................................................... 42 48. Step 5 - installation............................................................67
10. Selecting IBM Systems Director Server..........................42 49. Step 6 - installation............................................................67
11. Installing IBM Systems Director Server.........................43 50. Step 7 - installation............................................................68
12. Accepting the License Agreement..................................44 51. Step 8 - installation............................................................68
13. Selecting the option for product updates...................... 44 52. Step 9 - installation............................................................68
14. Selecting features for a custom install location.............45 53. Step 10- installation...........................................................69
15. Standard setup that installs Director Server................. 45 54. Post installation - Retail directory.................................. 69
16. Entering an administrative user ID and password......46 55. Retail eclipse plugins........................................................69
17. Beginning installation.......................................................47 56. Retail Extension for IBM Systems Director -
Upgrade Confirm....................................................................70
18. Green triangle clock indicator......................................... 47
57. Retail Extension for IBM Systems Director -
19. Green circle clock indicator............................................. 47 Prerequisite for an upgrade check........................................70
20. Expanding the Windows ISD directory.........................49 58. Expanding Linux RES x64............................................... 71
21. Welcome screen for Install Anywhere Launcher......... 50 59. Launching the Console Mode Installer..........................72
22. Software License Agreement page................................. 51 60. Systems requirements panel - Linux..............................72
23. IBM Systems Director Server page................................. 51 61. Software license agreement - Linux............................... 72
24. Summary page ..................................................................52 62. Valid Java VM Available..................................................73
25. Installation continues....................................................... 53 63. Select Java Virtual Machine............................................. 73
26. Restarting IBM Systems Director Server....................... 54 64. Invalid Java Home............................................................ 73
27. Verifying the IBM Systems Director Server 65. Invalid Java Selection....................................................... 74
stopped successfully...............................................................54
66. Summary panel................................................................. 74
28. Verifying the IBM Systems Director Server
restarted successfully - part 1................................................54 67. Installation progress - Linux........................................... 74
29. Verifying the IBM Systems Director Server 68. Installation complete - Linux...........................................75
restarted successfully - part 2................................................54
69. RES directory structure - Linux...................................... 75
30. Retail Plugins Deployment status - part 2.....................55
70. RES Services - Linux......................................................... 75
31. Expanding the Windows RES x64 directory................. 56
71. Retail Enterprise Service - Upgrade Confirm............... 76
32. Software License Agreement...........................................56
72. Retail Enterprise Service - Prerequisite for
33. Valid Java VM Available..................................................57 Upgrade Check........................................................................76
34. Invalid Java Home............................................................ 58 73. Installation complete - Linux ..........................................77
35. Select Java Virtual Machine............................................. 59 74. License Agreement........................................................... 80
36. Choose Install Folder........................................................59 75. Valid Java VM Available..................................................81
37. Summary page...................................................................60 76. Select Java Virtual Machine............................................. 81
38. Installation continues....................................................... 60 77. Invalid JVM selection....................................................... 82
39. Installation complete........................................................ 61 78. Choose RMA installation location..................................83

79. Select agent type ...............................................................84 120. Verifying Application window ..................................157
80. Enter Store ID.................................................................... 85 121. RMA Store Manager window..................................... 158
81. Select Security Mode.........................................................85 122. Application blocked by security setting.................... 159
82. Select the Ethernet Interface IP Address........................86 123. Command prompt with the launch details...............160
83. Summary panel................................................................. 87 124. RMA Store Manager - Add Entry command............ 160
84. Installation complete........................................................ 88 125. Define Master Agent pane........................................... 160
85. Choose the RMA installation location........................... 89 126. Hostname field ............................................................. 160
86. Post installation window................................................. 90 127. IP address field.............................................................. 161
87. RMA directory structure..................................................91 128. Port number field.......................................................... 161
88. Package content.................................................................98 129. Event filter drop-down menu..................................... 161
89. License agreement screen................................................ 98 130. Store Connection Information window..................... 162
90. Installation in progress.....................................................99 131. Initial Connection status pane ....................................162
91. Installation Complete screen........................................... 99 132. Store entry status...........................................................162
92. Report Module Level......................................................100 133. Store Connection Information status bar window...163
93. Remote Management Agent Ver3 details....................100 134. Authorizing a Store in unauthenticated state........... 164
94. Consent to proceed with the installation ....................101 135. Authorizing single or multiple stores........................ 164
95. Example only ... defining the HOSTNAME 136. Store Authorization Management window.............. 165
logical name (each controller needs this logical name
defined with the controller node ID)................................. 103 137. Store Connection status window................................165
96. Example only ... HOSTS file with localhost and 138. Edit Port command.......................................................166
each controller node ID........................................................ 104 139. Edit Port command with filters...................................166
97. Example only ... TCP/IP bat file for an enhanced- 140. Restarting connection to any Store ............................166
mode controller (each controller requires a file
similar to this one)................................................................ 105 141. Finding a specific store in the Store Connection
Information tab......................................................................167
98. Store number................................................................... 106
142. Find a store by Entry Name.........................................167
99. System management.......................................................107
143. Finding a store by Hostname/IP Address ................ 168
100. Uninstall Welcome screen (Windows).......................109
144. Close the Find Store Pane............................................ 168
101. Remove installation directory..................................... 110
145. Select all the Store entries at one time........................169
102. Remove configuration directory.................................110
146. Exporting Store entries ................................................169
103. Uninstall complete........................................................ 111
147. Exported Store entry confirmation window ............ 169
104. Check RPM.....................................................................112
148. Deselecting all Store entries ........................................170
105. Uninstall ........................................................................ 112
149. Removing Store entries ............................................... 170
106. Retail Enterprise Service Uninstaller Summary
Panel........................................................................................115 150. Removing Store entries confirmation window.........170
107. Lock icon........................................................................ 118 151. Importing Store entries................................................ 171
108. rmauser.properties file with store id key in 4690 152. Import Master Agent List window.............................171
MA...........................................................................................125 153. Stores Imported Successfully...................................... 172
109. Enable/Disable MD5 algorithm...................................128 154. Connection Log window..............................................172
110. Java logging hierarchy................................................. 140 155. Connection Log Window.............................................173
111. Sample Windows Application event..........................150 156. Viewing data capture window (1 of 3)...................... 174
112. Sample Windows Application event viewed in 157. Viewing data capture window (2 of 3)...................... 174
IBM Systems Director...........................................................151
158. Viewing data capture window (3 of 3)...................... 175
113. Retail Enterprise Service architecture........................ 153
159. Saving data capture window (1 of 4)......................... 176
114. Launch RMA Store Manager.......................................154
115. Launching RES Config US Java Webstart window..155
116. "Warning - Hostname Mismatch" window .............. 155
117. Security Warning window...........................................156
163. Cancelling data capture transfer window................. 178
118. "Security Information window .................................. 156
164. Deleting capture bundles window (1 of 2)................179
119. "Launching Task window............................................157
165. Deleting capture bundles window (2 of 2)................179

166. Access State: OK............................................................181 211. Director-specific Retail Service Access point............ 204
167. Access State: No Access............................................... 181 212. RSAP for the MEP......................................................... 205
168. Access State: Offline......................................................181 213. Retail store in a locked state........................................ 205
169. Access State: Unknown................................................ 181 214. Security ---> Request Access - part 1.......................... 206
170. Admin user ID and password.....................................183 215. Security ---> Request Access - part 2.......................... 206
171. IBM Systems Director home page.............................. 183 216. Request Access tab........................................................207
172. Resource Explorer tab.................................................. 184 217. Authorization process.................................................. 207
173. Resource Explorer menu..............................................184 218. Access state.................................................................... 208
174. Managed end points groups........................................185 219. Closing the Request Access tab...................................208
175. Retail groups .................................................................185 220. An authorization attempt failure................................209
176. Retail groups view ....................................................... 186 221. Verify Connection......................................................... 210
177. Retail Agents MEPs icon.............................................. 186 222. Retrieve and update MEP attributes.......................... 210
178. Store MEPs icon ............................................................186 223. Deleting MEPs displayed in Director 6 UI................ 211
179. RES MEP icon ............................................................... 186 224. Confirming an MEP deletion...................................... 211
180. All Retail Client Systems .............................................187 225. View and Collect Inventory Selection on Home
Page......................................................................................... 213
181. Lists of systems in Director .........................................187
226. View and Collect Inventory selection in Director
182. Lists of grouping by categories .................................. 188 navigation area...................................................................... 214
183. 4690 Controller Groups ............................................... 188 227. View and Collect Inventory page............................... 214
184. 4690 Terminal Groups ................................................. 188 228. Context Chooser - view 1.............................................215
185. Agent MEP Properties page - General Tab .............. 189 229. Context Chooser - view 2.............................................215
186. Agent MEP Properties page - Event Log Tab........... 189 230. Select a valid target - add to the selected list............ 215
187. Agent MEP Properties page - Inventory Tab............190 231. Selecting a target system to add..................................216
188. Create Group screen..................................................... 191 232. Selecting a target system to add - view 1...................216
189. Group Type List - Dynamic.........................................191 233. Selecting a target system to add - view 2...................216
190. Define page - Add Criterion window........................ 192 234. Click OK to finish..........................................................217
191. Define page - displaying selections............................ 193 235. View by list - inventory profile................................... 217
192. Define page - displaying selections............................ 193 236. Run - Collect Inventory page...................................... 218
193. Selecting the type of member...................................... 194 237. Setting up functions and options - inventory
194. Selecting the parent group...........................................195 collection task........................................................................ 218
195. Verifying the details of the group...............................195 238. Click OK to create and Inventory collection job ......219
196. Resource Explorer view............................................... 196 239. Active and Scheduled Jobs page ................................219
197. Resource Explorer view - selecting columns............ 196 240. View and Collect Inventory Selection on Home
page ........................................................................................ 220
198. Columns Order view.................................................... 197
241. View and Collect Inventory selection in Director
199. Adding a column from the Available columns navigation area ..................................................................... 221
options box.............................................................................197
242. Content Chooser - list of systems - view 1................ 221
200. Selecting where you want a column to appear.........198
243. Content Chooser - list of system groups - view 2 ....222
201. Selecting where you want a column to appear.........198
244. Selecting groups and individual target systems ..... 222
202. Selected columns for the Resource Explorer view... 199
245. Adding target systems ................................................ 222
203. Logging into IBM System Director.............................199
246. Target systems added - view 1....................................223
204. IBM Systems Director Home page............................. 200
247. Target systems added - view 2....................................223
205. Resource Explorer launch............................................ 200
248. Target systems added - click OK to Finish................223
206. Resource Explorer with Retail Extensions.................201
249. View by - select inventory profile to use................... 224
207. Resource Explorer Retail Groups............................... 201
250. Refresh View - view 1...................................................224
208. RES MEP on loop back address.................................. 202
251. Refresh View - view 2...................................................225
209. Locked GA's...................................................................203
252. ACE EFIX Level.............................................................225
210. System Discovery - Discovered Manageable End
Points...................................................................................... 203 253. Terminal Sales Version.................................................226
Figures 9
254. ACE Pin Pad inventory................................................ 227 298. Edit Event Filter created window...............................254
255. Export All - view 1........................................................ 227 299. View Summary of Event filter created window.......254
256. Export All - view 2........................................................ 228 300. View event filter window............................................ 255
257. Saving exported inventory data..................................228 301. Event Actions tab.......................................................... 256
258. Resource Explorer > Groups > All Retail Client 302. Create Action wizard....................................................257
Systems window................................................................... 229
303. Create Action wizard....................................................258
259. Selecting Columns from the Actions drop down
menu....................................................................................... 229 304. Event Automation tab.................................................. 258
260. Columns Order view.................................................... 229 305. Create Event Automation wizard...............................259
261. Selecting the SerialNumber attribute......................... 230 306. Name and Description window..................................259
262. Saving and closing the Columns window.................230 307. Target window.............................................................. 260
263. New column in IBM Systems Director Console....... 231 308. Event window............................................................... 260
264. Flow of events from CIM to RMA to Director.......... 233 309. Common event types window....................................261
265. Store Event filter window............................................ 235 310. Advanced Event Filters window................................ 261
266. Events table window.................................................... 235 311. Start Saving History window......................................262
267. General tabs window....................................................236 312. Event Actions window ................................................262
268. IBM System Director Console window..................... 236 313. Time range window - default view............................ 263
269. Event entries listed in the agent MEP Properties 314. Time range window - customized view.................... 263
window...................................................................................237 315. Event automation Summary window........................264
270. Event entries.................................................................. 237 316. Event Automation Plans window ............................. 265
271. Define Master Agent window.....................................238 317. Event Automation Plans confirmation message...... 265
272. Event log view............................................................... 239 318. Resource Explorer window......................................... 266
273. Agent Offline Event...................................................... 239 319. Event Filters window................................................... 268
274. Agent Online Event...................................................... 240 320. Create Events window................................................. 269
275. Both Master Agent and General Agent offline......... 240 321. Create Events filter type window...............................270
276. Both Master Agent and General Agent online......... 240 322. Types of events to include........................................... 271
277. Agent offline event properties.................................... 241 323. 4690 message groups displayed..................................272
278. Agent online event properties.....................................242 324. Searching the 4690 message groups .......................... 273
279. The LHS pane of Director............................................ 243 325. List of event numbers and filters ............................... 274
280. The Welcome page of Director....................................243 326. Severity and Category Window..................................275
281. Edit event window........................................................244 327. Wizard Summary Window......................................... 275
282. Filter Type window ..................................................... 244 328. Created event log filters............................................... 276
283. Event Type wizard .......................................................245 329. Event Log View............................................................. 279
284. List of Component Categories.....................................245 330. Navigation: Home -->Status Manager....................... 280
285. Component Types for each category......................... 246 331. Aggregate Health of Systems...................................... 280
286. Severity and Category pane - Custom view............. 247 332. Systems with Warning State........................................281
287. Event Sender window - Default view........................ 247 333. Scoreboard view............................................................281
288. Event Sender window - Custom view....................... 248 334. Problems screen.............................................................282
289. Event Text window - Default view............................ 249 335. Problems detail page.................................................... 282
290. Event text window - Custom view.............................249 336. Resource Navigator view.............................................283
291. Time Range window - All view.................................. 250 337. Resource Properties View............................................283
292. Time Range window - Custom view..........................250 338. Active Status view........................................................ 284
293. Summary Window........................................................251 339. Problems view............................................................... 284
294. Events Filter tab window.............................................251 340. Ignore Problems............................................................ 285
295. Copy event filter - filter name..................................... 252 341. Scope of Ignore Operation........................................... 285
296. Create Event filter from existing event window...... 253 342. Problem Status View after events being ignored..... 286
297. Create Simple Event Filter window........................... 253 343. Ignored Events Tab.......................................................286

344. Reactivate Events.......................................................... 286 385. Import Job status........................................................... 331
345. Activate Confirmation..................................................287 386. Active and Scheduled Jobs window.......................... 331
346. Problem View with Reactivated Alerts......................287 387. Show and Install Updates............................................ 332
347. Delete Selected Problems............................................. 287 388. List of selected systems................................................ 332
348. Problem View after Deleting Alerts........................... 288 389. Error message................................................................ 333
349. SSD Life Monitoring Critical event properties......... 293 390. List of applicable updates............................................ 334
350. PaperCutCount threshold reached warning event.. 295 391. Install or Installation Staging...................................... 335
351. Resolution event for POS printer attributes..............295 392. Install or Installation Staging options........................ 336
352. Warning event for HoursPoweredCount 393. Staging job summary....................................................337
threshold reached..................................................................297
394. Show and install updates.............................................338
353. RSS Display resolution event for
HoursPoweredCount attribute........................................... 297 395. Restart options...............................................................338
354. Generic (user defined) warning event for 396. Install wizard summary page..................................... 339
PowerState attribute............................................................. 299 397. Active and Scheduled Job status.................................340
355. Generic (user defined) Resolution event for 398. Software Distribution status........................................340
PowerState attribute............................................................. 300
399. Update Manager summary page................................ 342
356. Agent Monitoring......................................................... 301
400. Compliance policy page...............................................343
357. Launching RES Software Package Manager............. 310
401. Create and configure compliance policies page....... 343
358. RES Authorization Management window................ 310
402. Optional list of systems................................................ 344
359. RES Software Package Manager application user
interface.................................................................................. 311 403. Show compliance policies............................................344
360. Create Package in RES Software Package Manager.312 404. Compliance policies......................................................345
361. Enter General Information for package..................... 313 405. Critical or high update severity level icon................ 346
362. Enter staging destination directory for package...... 314 406. Unknown or inapplicable update severity level
icon.......................................................................................... 346
363. Enter installation destination directory for
package................................................................................... 315 407. In compliance icon........................................................ 346
364. Select package files........................................................316 408. Medium or low severity level icon.............................346
365. Enter first command..................................................... 316 409. Inaccessible system or no inventory collected icon. 346
366. Enter second command................................................317 410. Update compliance section..........................................347
367. Package Commands window......................................317 411. Table of systems............................................................ 347
368. Installation Target State and Post Installation 412. View all compliance issues.......................................... 348
Action......................................................................................318 413. Expanded and filtered list of systems with
369. Update Manager Product Information window...... 319 compliance issues..................................................................348
370. Save Package window..................................................320 414. Compliance issues page............................................... 348
371. Newly created package visible in application.......... 320 415. Compliance status.........................................................349
372. View of existing packages in RES Software 416. Recommended compliance actions............................ 349
Package Manager.................................................................. 322 417. Show and install updates page................................... 350
373. Edit package in RES Software Package Manager.....322 418. List of systems to be scanned for update view......... 351
374. Edit package wizard..................................................... 323 419. Show and install updates error message................... 352
375. Finish and save edits to package................................ 324 420. List of applicable updates............................................ 353
376. Remove package........................................................... 325 421. Install tab view.............................................................. 354
377. Delete package...............................................................325 422. Installation wizard welcome page..............................354
378. Importing Packages using Update Manager............ 326 423. Restart options...............................................................355
379. Check for updates......................................................... 327 424. Summary page...............................................................355
380. Select and add packages to be updated.....................328 425. Launch job page............................................................ 356
381. Job scheduling options................................................. 328 426. Active and scheduled job page - job status............... 356
382. Import updates from file system................................ 329 427. Software Distribution status........................................357
383. Browse to directory containing package files........... 330 428. Power Management Options available for
384. Import Job window.......................................................330 General agent Managed End points(MEP)....................... 360
Figures 11
429. Complete job creation...................................................361
430. Job Created Successfully.............................................. 361
431. Active and Scheduled Jobs.......................................... 362
432. General tab..................................................................... 362
433. Targets tab......................................................................363
434. Logs tab.......................................................................... 363
435. RES Software Package Manager................................. 381
436. Create Package.............................................................. 381
437. Enter package information.......................................... 382
438. Enter Windows installation information...................382
439. Select files to distribute................................................ 383
440. Set JAVA_HOME to valid JRE location..................... 384
441. Set RMA_JAVA_PATH to valid JRE location...........384
442. Package Commands..................................................... 385
443. Enter Update Manager product information............385
444. New JRE package.......................................................... 386
445. RES Software Package Manager (Linux)................... 386
446. Create Package (Linux)................................................ 386
447. Enter package information (Linux)............................ 387
448. Enter Linux installation information..........................387
449. Select files to distribute (Linux).................................. 388
450. Set executbale permissions (Linux)............................ 389
451. Set RMA_JAVA_PATH (Linux)..................................389
452. Delete shell script.......................................................... 390
453. Set file access permission (Linux)............................... 390
454. Linux package commands........................................... 391
455. Enter Update Manager product information
(Linux).................................................................................... 391
456. New JRE package (Linux)............................................392

Tables
1. Network ports used by the RMA GA.............................. 32
2. Network ports used by the RMA MA..............................32
3. Network ports used by RES.............................................. 32
4. Network ports used by IBM Systems Director............... 32
5. Configuration subdirectory descriptions...................... 121
6. Agent properties............................................................... 121
7. RMI properties...................................................................122
8. Event properties................................................................ 123
9. Event fetching properties (Master Agent only)............ 123
10. Data capture properties..................................................123
11. Phone Home Connection Properties............................124
12. Java logging levels.......................................................... 141
13. Configurable logging parameters.................................142
14. XML definition of the agent configuration file for
Windows event log integration...........................................146
15. Mapping Windows event log definitions to RMA
Notifications...........................................................................148
16. Event type to severity mapping....................................149
17. Connection status pane.................................................. 167
18. Define page - Add Criterion .........................................191
19. Refining Define page criteria.........................................192
20. LED Monitoring Event Types....................................... 290
21. Sensor Monitoring Event Types....................................291
22. Resource Monitoring Event Types............................... 292
23. Event types monitored under SSD Life
monitoring for 4690.............................................................. 293
24. End of life thresholds for POS printer attributes........294
25. Details for Resolution event for POS printer
attributes.................................................................................296
26. Supported power management options...................... 359
27. Common symptoms....................................................... 370
28. Support for hardware and resource monitoring........ 377

About this guide
This guide contains information to help you install, use, and configure the 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 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.
Where to find more information

Current versions of Toshiba publications are available on the Toshiba Global Commerce
Solutions website at www.toshibacommerce.com/support/publications.
The publications listed under the General tab are available to the public.
To access a specific Toshiba product publication:
1. Click on the Hardware, Applications, OS, Integration, or Other tab.
2. Scroll to the desired product, and click Publication Library.
Note: Access to the product publications requires valid user credentials. For information on
obtaining a user ID and password, click Learn More.
3. Enter your user ID and Password.
4. Click Submit.
Accessing the TGCS Knowledgebase site

Toshiba Global Commerce Solutions has developed a variety of Knowledgebase articles to assist
you in using the Toshiba product set. To access the TGCS Knowledgebase articles:
• Login to the Toshiba Global Commerce Solutions website at www.toshibacommerce.com/
support.
• Click Support.
• Click KNOWLEDGEBASE.
• Select a product from the Hardware or Software drop-down list.
Additional references
The following publications provide additional information on using the Remote Management
Agent.
• 4690 OS User's Guide
• 4690 OS Programming Guide
• 4690 OS Communications Programming Reference
• Store Integrator User's Guide
• Store Integrator Programming Guide
• Store Integrator Graphical Interface Programming Guide
• Data Integration Facility User's Guide
• Unified Point of Sale (UPOS) publications at http://www-1.ibm.com/support/search.wss?
rs=219&q=PUBUPOS.

• IBM Systems Director publications at http://www-01.ibm.com/support/knowledgecenter/
SSAV7B_635/com.ibm.director.main.helps.doc/directorwelcome.html?cp=SSAV7B_635%2F0
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.
Notice statements
Notices in this guide are defined as follows:
Notes
These notices provide important tips, guidance, or advice.
Important
These notices provide information or advice that might help you avoid inconvenient or
problem situations.
Attention
These notices indicate potential damage to programs, devices, or data. An attention notice
is placed just before the instruction or situation in which damage could occur.
CAUTION
These statements indicate situations that can be potentially hazardous to you. A caution
statement is placed just before the description of a potentially hazardous procedure step
or situation.
DANGER
These statements indicate situations that can be potentially lethal or extremely hazardous
to you. A danger statement is placed just before the description of a potentially lethal or
extremely hazardous procedure step or situation.

Summary of changes
September 2017
This publication includes updates for Version 3.2.2 of Remote Management Agent. The
following is new for this release:
• 4690OS installer section
• Whitelisting section
• Windows 10 2016 and CBB support
• 6145- 2TN/2TC support
Web-only update of GC30-4106-16
This update documents the changes to the Remote Management Agent User's guide for RMA
Version 3.2.1.
Update of GC30-4106-15
This update documents the changes to the Remote Management Agent User's guide for RMA
Version 3.2.0.

Part I. Introducing Remote Management Agent
Introducing Remote Management Agent

Chapter 1. RMA Overview
RMA Overview
Remote Management Agent (RMA), along with IBM® Systems Director, allows you to view,
track and control your retail hardware and software environment. RMA includes the following
key functions:
• System health status
• Power management of POS systems
• POS hardware monitoring
• System monitoring of system performance and availability
• Event management to track and respond to various error conditions
• Asset tracking and inventory management of hardware and software systems
• Software distribution system for application or device driver updates
Event Management and Health Status

The RMA agent listens for alerts that occur on retail systems and peripherals, which can be
forwarded to IBM Systems Director. Once received, events will be logged and can be viewed for
each system. Event action plans can be created to act on events when they are received.
Events are also used to determine the health status of the system. Alert and resolution events
will automatically change the health status indicator to/from red (Critical), yellow (Warnings), or
green (Ok).
Power Management of POS Systems

RMA provides support for managing the power states of POS systems in an 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 6 console.
Monitoring Retail Systems

RMA supports active monitoring of retail systems. This includes hardware monitoring
(temperatures, fan speeds) as well as resource monitoring (CPU, memory, and disk utilization).
Starting in RMA V3, systems are automatically monitored by default without any setup or
configuration required. Immediately after installing RMA, your systems are being monitored
and generating alerts if problems occur.
Retail peripheral management

The RMA agent includes JMX MBeans that provide access to UPOS peripheral instrumentation
as well as device generated alerts. These alerts can be reflected in the health status summary in
IBM Systems Director.
Inventory
RMA and IBM Systems Director support the collection of hardware and software inventory
information, including retail-specific information for peripherals. This information is stored in
the IBM Systems Director database, where it can be monitored or queried (even when not
connected).

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 facilitates the
deployment of packages to multiple clients on various platforms in the store from the Master
Agent. Packages can be built and edited using the RES Software Package Manager Application.
RMA software packages can be imported into IBM Systems Director's Update Manager. The
imported package(s) is compared against existing installed software inventory to determine
which systems do not have the imported package software. An optional user created compliance
policy is used to identify which systems require the imported package software. Packaged
software can be staged only or staged and installed.

Chapter 2. Infrastructure components
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:
Figure 1. RMA infrastructure
IBM Systems 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 Systems 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 Systems Director Server

Using RES, communicates with one or more in-store Master Agents to provide a
consolidated view of many stores.
IBM Systems Director Console

Connects to the IBM Systems Director Server to provide a user interface for managing the
IT infrastructure, including retail devices. The IBM Systems Director 6 Console is a web
application and runs in a web browser. Some tasks use the IBM Systems Director Launch
in Context framework, and are invoked using Java WebStart.
Retail Extensions for IBM Systems Director

Must be installed on the IBM Systems Director Server, provides extensions for managing
retail systems.
Retail Enterprise Service (RES)

This service is installed on the same system which runs IBM Systems Director Server, and
is required for the Retail Extensions for IBM Systems Director. This service provides an
integration/support layer for not only IBM Systems Director, but potentially any
management application. Among the functionality RES provides are maintaining the
connections to each store Master Agent and event transport.

Part II. Installing and using the Remote Management Agent
Installing and using the Remote Management Agent

Chapter 3. RMA Requirements
RMA Requirements
This section describes the hardware and software requirements for all of the systems in RMA-
Director solution. This includes in-store systems running the Master Agent (MA) or General
Agent (GA), as well as the enterprise systems running the IBM Systems Director server or
console.
Hardware requirements
The MA runs on the in-store processor. The in-store processor is a Microsoft® Windows®, Linux®,
or 4690 V7 Enhanced system that runs the RMA 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 2 GB of RAM. The MA 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 GA runs as a system service on a Windows or Linux system, or on a 4690 controller, or as an
embedded agent in a Java virtual machine (JVM). The MA and GA services cannot be installed
on the same computer. The GA 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 or
4690 environment.
The RMA agent (Master or General) running on the 4690 Master Controller is used to manage
each terminal in the store. This will require additional memory for each terminal.
IBM Systems Director Server hardware requirements

For the most up-to-date hardware and software requirements for IBM Systems Director 6.3.7, go
to www.ibm.com/support/knowledgecenter/SSAV7B_6.3.7/com.ibm.director.plan.helps.doc/
fqm0_r_supported_hardware_and_software_requirements.html .
The Retail-Director solution only supports IBM x86-based servers. In general, the system
running IBM Systems Director must be a server class system with at least two processors and
greater than 4GB of memory. While a 32 bit system will work for small deployments (100 or
fewer stores, 500 total retail endpoints), a 64 bit system is recommended. For large deployments,
see the IBM Systems Director Performance and Tuning Guide.
The Systems Workload Estimator, accessed from the IBM Systems Director InfoCenter, is a tool
that will provide a set of recommended servers to run the IBM Systems Director Server. The tool
bases its recommendations on a series of questions about the target environment (server
operating system, location of database, number of managed endpoints). The Systems Workload
Estimator can be accessed from within the IBM Systems Director InfoCenter:

Figure 2. Recommended hardware requirements for IBM Systems Director Server
Note: When using the Systems Workload Estimator, the number of Operating Systems should be
zero (0) when considering the number of retail endpoints. Retail extensions do not expose
separate endpoints for the operating system. The tool limit is 10,000. Update when the final
scalability numbers are determined.)
IBM Systems Director / Retail Enterprise Service software requirements

This section outlines the software requirements for running IBM Systems Director and the
accompanying console web application. The most up-to-date information about IBM Systems
Director can be obtained in the IBM Systems Director Infocenter located at: www.ibm.com/
support/knowledgecenter/SSAV7B_6.3.7/com.ibm.director.main.helps.doc/
directorwelcome.html.
Java
The Java requirements to run RES are as follows:
An appropriate Java Run time Environment (JRE) for the Platform should be present on the
system to run RES.
Note: For RMA 3.2.2 onwards, JRE will not be shipped/bundled along with RES. The user will
need to provide the JRE.
The JRE required to run RES should meet the following criteria:

1. JRE version should be of 8.
2. JRE version should be of 64 bit.
3. JRE should be at least compliant with the Java SE standards for Java 8.
JRE should be present on the system before the installation process is initiated.
Supported Operating Systems

The RES and Retail Extensions for IBM Systems Director must be installed on the same system as
IBM Systems Director. Following are the operating systems currently supported for the Director
server with the RMA Extensions and RES:
• Microsoft Windows Server 2008 R2 Standard or Enterprise (64-bit)
• Microsoft Windows Server 2012 R2 Standard (64- bit)
• RHEL 6.4 and 6.5 (64-bit)
IBM Systems Director Server

The currently supported version of IBM Systems Director for RMA is 6.3.7.
Director Server database requirements

IBM Systems Director 6 requires a database in order to install and run, as was the case with IBM
System Director 5.20. Also as before, you can use your own database or use the database
embedded with Director. IBM Systems Director 6 provides an instance of DB2 as the embedded
database, while version 5.20 provided Apache Derby. During the IBM Systems Director Server
installation, the option for this database is called "Managed DB2". After installing with this
option, you will not be able (or allowed) to use the embedded DB2 database for any other
purpose and will have no access to any of the administrative tools, such as, the DB2 Control
Center. IBM also recommends not installing Director with managed DB2 on a server with the
full version of DB2 also installed.
For improved performance and scalability in larger deployments, IBM Systems Director
recommends running the database such that the database data is located on a separate drive.
This might be a separate RAID array or a separate physical drive. This guide focuses only on
installing Director with managed DB2. Information on installing Director with other types of
separate databases is located at www.ibm.com/support/knowledgecenter/SSAV7B_6.3.7/
com.ibm.director.plan.helps.doc/fqm0_t_selecting_the_ibm_director_database_application.html.
Browser Requirements
The following link provides a list of the supported web browsers for the IBM Systems Director
console web application: http://www-01.ibm.com/support/knowledgecenter/SSAV7B_635/
com.ibm.director.plan.helps.doc/fqm0_r_supported_web_browsers.html?
cp=SSAV7B_635%2F2-1-4-4-3
A Java 6 or later JRE must be installed on the system running the IBM Systems Director console
in order to run RMA Store Manager or RES Software Package Manager through Java Webstart.
Chapter 3. RMA Requirements 29

RMA software requirements
This section describes the software requirements for RMA.
Java
An appropriate JRE for the Windows or Linux Platform should be present on the system to run
Master Agents and General Agents.
Note: The JRE will not be shipped/bundled along with RMA version 3.2.2 and later. The user
will need to provide the JRE. For OS4690 Remote Management Agents, the user will not need to
provide the JRE as the OS will facilitate the same.
The JRE required to run RMA software should meet the following criteria:
• JRE version should be of 8.
• JRE should be of 32 bit/64bit basing on system type.
• JRE should at least be compliant with the Java SE standards for Java 8.
JRE should be present on the system before installation process is initiated.
Supported operating systems

RMA 3.2.2 is supported on the following operating systems:
• Microsoft Windows Server 2012 R2 (64 bit) Standard
• Microsoft Windows 2008 Server with Service Pack (SP) 2 (64 bit)
• Microsoft Windows 7 Professional (32 bit)
• Microsoft Windows 7 Ultimate (64 bit)
• Microsoft Windows 8.1
• Microsoft Windows 10 (Enterprise LTSB 2015 (64 bit), IoT Enterprise LTSB 2016(64 bit) and
CBB (32 bit))
• Microsoft Windows Embedded POSReady 7
• Windows Embedded Point of Service (WePOS) Preload V1.1
• 4690 OS V7
• Microsoft Windows Embedded POSReady 2009
• SUSE Linux Enterprise Desktop (SLED) 11 SP3
• SUSE Linux Enterprise Server (SLES) 11 SP3
• SUSE Linux Enterprise Point Of Service (SLEPOS) 11 SP3 (Refer to Appendix C, SLEPOS
Server-Client setup on page 379)
RMA 3.2.2 supports communication with previous levels of the GA. Refer to “Compatibility
with prior versions of RMA” on page 31 for more information.
POS sensor drivers

To support hardware monitoring on Windows and Linux systems, the correct version of the POS
Sensor Drivers must be installed. Please refer to this link to obtain the correct package for each
hardware platform: https://tgcs04.toshibacommerce.com/cs/idcplg?
IdcService=FLD_BROWSE&path=%2fDownloads%2fDrivers
%2fPOSSensorDrivers&doMarkSubscribed=1

Touch screens
To support the inventory of the touch screens on systems, the inventory drivers must be
installed. Refer to the following web address to obtain the drivers on the Toshiba support site:
https://www.toshibacommerce.com/?urile=wcm:path:/en/home/support/product-support/
support-hardware/support-displays-sitearea
UPOS Peripherals
To support peripheral inventory and events, the UPOS drivers must be installed with systems
management enabled.
The following peripheral is supported by RMA 3.2.2:
• 6145-2TC/2TN (Printer)
Compatibility with prior versions of RMA
RMA Master and General agents

The RMA Master and General Agents are backwards compatible with prior versions of RMA.
An RMA 3.2.2 MA system can connect to a GA system running RMA 3.2.2 and latest prior two
versions of RMA. It is recommended that the RMA versions on MA systems be greater or equal
to the versions of RMA running on GA systems.
RES/Director
The RES is backwards compatible with prior versions of RMA, supporting the ability to connect
to MA systems running the latest version of RMA V3 (3.2.1, 3.2.0).
Network requirements
If you are setting up a lab environment or a single-store scenario with no outside internet
connectivity, you can install the RMA MA on the same system as the Director Server, although
this is generally not desirable for a production environment.
Network infrastructure can sometimes be complex, but the basic rules are as follows:
• The RMA MA system must be able to communicate with the RMA GA system IP address,
and vice-versa. (You can usually test this by using the "ping" command – try to ping the IP
address of the MA from the GA, and vice-versa.) More specifically, multicast traffic on UDP
port 31200 must be able to flow between subnets. See “Discovering General Agents that are
on different subnets than the Master Agent” on page 33.
• The Director Server system must be able to communicate with the RMA MA system’s IP
address, and vice-versa. (Again, you can usually test using the ping command.)
The network ports used by the RMA GA are shown in the following table:

Table 1. Network ports used by the RMA GA
Network Port Direction Description
10151 (TCP) Incoming RMA MA to RMA GA (RMI)
10152 (TCP) Incoming RMA MA to RMA GA (SOXS)
10190 (TCP) Incoming Used for RMA file transfers, Director to MA and MA to
GA
31200 (UDP) Outgoing Discovery messages for MA and GA
The network ports used by the RMA MA are shown in the following table:
Table 2. Network ports used by the RMA MA

10149 (TCP) Incoming Director Server to RMA MA (SOXS)
10151 (TCP) Outgoing RMA MA to RMA GA (RMI)
10152 (TCP) Outgoing RMA MA to RMA GA (SOXS)
10190 (TCP) Incoming Used for RMA file transfers, Director to MA and MA to
Outgoing GA
10521 (TCP) Outgoing RMA V3 MA to RES (Store Discovery)

31200 (UDP) Incoming Discovery messages for MA and GA
The network ports used by the RES are shown in the following table:
Table 3. Network ports used by RES

10000 (TCP) Inbound Software Distribution file transfer server on RES
10149 (TCP) Outgoing Director Server to RMA MA (SOXS)
10190 (TCP) Outgoing Used for RMA file transfers, Director to MA and MA to
GA
10520 (TCP) Incoming Director to RES (Non-SSL, loopback only)
loopback only
10521 (TCP) Incoming RMA V3 MA to RES (Store Discovery)

10530 (TCP) Incoming RES (SSL)
The network ports used by IBM Systems Director Server 6.3 are shown in Table 4. The list
supplied is intended to be a guide and may not be current. For the most accurate information,
see to the following link in the Director publications: www.ibm.com/support/knowledgecenter/
SSAV7B_6.3.7/com.ibm.director.plan.helps.doc/fqm0_r_ports_for_the_management_server.html.
Table 4. Network ports used by IBM Systems Director

Network Port Description
8421 (TCP) HTTP (Configurable during installation)
8422 (TCP) HTTPS (Configurable during installation)

Network Port Description
9510 (TCP) Communication with Director Common Agent
9511-9513 (TCP) IBM Systems Director Agent Manager
9514-9515 (TCP) Director Server Nonstop service ports
50010 (TCP) Embedded Managed DB2
Discovering General Agents that are on different subnets than the Master
Agent
Typically, the MA and GA will be on the same subnet within the store. If they are not on the
same subnet and are connected by an in-store router, there is an additional configuration step to
set the TCP/IP time-to-live parameter on the RMA agents.
First, use the tracert command to identify the number of hops between the MA and GA systems.
This command could be executed from either system and should use the IP address of the other
system (similar to the ping command).
Figure 3. General Agents that are on different subnets
The number of hops returned by the tracert command is what you will need to set as the time
to live for each of your general agents.
To set the time to live, add the following property to the rmauser.properties file on each of
your general agents (simgmt.pro on V2R6 or earlier agents):
com.ibm.retail.si.mgmt.generalagent.discovery.ttl=<hops returned by tracert>
The rmauser.properties and simgmt.pro files are found in the following locations:
• Windows: C:\Program Files\Toshiba\RMA\user\rma\
• 4690 Classic: m:\rma\user\rma\
• 4690 Enhanced: f:\rma\user\rma\
Note: The routers in between the systems must also pass the necessary RMA traffic between the
systems in addition to just the time to live properly.

Chapter 4. Installation Overview
Installation Overview
The following instructions describe the steps required to install the RMA GA, the RMA MA,
RES, and IBM Systems Director Server. The instructions serve as a summary for installing all
components of the solution. The detailed installation and configuration instructions for each
component are located in other chapters in this guide. These instructions are for RMA 3.2.2 and
IBM Systems Director 6.
It is possible to set up a mixed environment in which one or more of the components is running
on a different operating system with IBM Systems Director Server on a Windows or Linux
platform, and each agent on a Windows, Linux, or 4690 platform. To learn about using RMA in
these other environments, you should first read and understand this chapter, then refer to
“Setting up RMA on 4690 ” on page 101.
The following systems are involved in the solution. With the exception of RES and IBM Systems
Director server, these components are installed on separate systems, as follows:
• The RMA GA should be installed on all the POS systems in a particular store. These systems
can have DHCP or static IP addresses.
• The RMA MA should be installed on a single system within each store that will act as the
RMA entry-point for the store. The system may have either a static IP address or a dynamic
IP address provided the hostname can be resolved by DNS to the correct IP address for the
MA. This system does not need to be a server-class system.
• The IBM Systems Director Server should be installed on a system residing outside the store -
typically, it will be installed at the corporate I/T headquarters or data-center. When you
install the Director Server, the installation program automatically installs the Director Agent
(to monitor the server on which it is installed) along with Director Server. The Director Server
should run on a dedicated server-class computer according to the recommendations set forth
by their publications. See “IBM Systems Director Server hardware requirements ” on page 27
for more information. Also see “Director Server database requirements” on page 29 for more
information about options and requirements for the IBM Systems Director database.
• The RES is a service used to support the Retail Extensions for IBM Systems Director. It must
be installed on the same system as the IBM Systems Director Server.
• The IBM Systems Director Console is a web application, so the console application runs
through a web browser. Unlike Director 5.20, there is no separate installation for the console.
Certain tasks (such as the RMA Store Manage and RES Software Package Manager) are
launched through Java WebStart, and require a JRE supporting Java WebStart to be installed
in order to run. See the “Browser Requirements” on page 29 for more details.
Note: Please make sure the appropriate Java is present on the system to run RES and RMA
agents.
To understand the Java requirements for RES and agents refer to:
• “Java” on page 28, under "IBM Systems Director / Retail Enterprise Service software
requirements."
• “Java” on page 30, under "RMA software requirements".
The overall installation process is as follows:
1. Download IBM Systems Director Server 6, see “Step 1 - Downloading IBM Systems Director
Server 6” on page 36.
2. Download RMA (which includes the Retail Extensions for IBM Systems Director), see “Step
2 - Downloading RMA and the Retail Extensions for IBM Systems Director” on page 37.

3. Install the IBM Systems Director Server 6 on a system (typically on a system outside the
store), see “Step 3 – Installing IBM Systems Director Server 6” on page 38.
4. Apply the Service Update for IBM Systems Director Server on the same system, see “Step 4 -
Install IBM Systems Director Hotfixes” on page 38.
5. Install Retail Extensions for IBM Systems Director on the same system, see “Step 5 –
Installing RMA Retail Extensions for IBM Systems Director Server” on page 38.
6. Install the RES on the same system, see “Step 6 – Installing RES” on page 39.
7. Log into the Director Server using a web browser and verify the server and RES
installations, see “Step 7 – Verify Retail Extensions for IBM Systems Director and RES
Installation ” on page 39.
8. Install the RMA MA on a system within a store, see “Step 8 - Installing RMA MA” on page
39.
9. Install the RMA GA on a different POS system within the same store (or on all the POS
systems in the store), see “Step 9 - Installing RMA GA” on page 39.
10. “Step 10 - Launch RMA Store Manager” on page 40.
11. Configure the discovery settings to discover the MA in the RMA Store Manager, see “Step
11 - Configure RMA Store Manager to Discover RMA MA” on page 40.
12. “Step 12 - Authenticating to Agents Running Enhanced Security from Director UI” on page
40.
Step 1 - Downloading IBM Systems Director Server 6

Use the following process to download IBM Systems Director Server 6:
1. Go to the following website: https://www-01.ibm.com/marketing/iwm/iwm/web/reg/
download.do?source=isdd-SysDir6Serv-
DVD&S_TACT=600AA0ZW&S_PKG=SysDir_recov_media&lang=en_US&cp=UTF-8.
2. Select the supported version of IBM Systems Director 6 (System x) from the drop down list.
Figure 4. IBM Systems Director

3. Enter your name, company, address, server serial number, and email address and then click
Submit .

Note: If you do not have your serial number handy, you can enter in any number to proceed
to the next steps.
4. Sign in with your IBM ID. (If you do not have an IBM ID, you can select "register here" to
obtain one.)
Figure 5. IBM Systems Director sign in

5. Select the operating system version to download and click Continue.
6. Select the destination to download the files and the download process begins.
Figure 6. Initial Setup
Step 2 - Downloading RMA and the Retail Extensions for IBM Systems
Director
1. Go to the following website: http://www.toshibacommerce.com/?urile=wcm:path:/en/home/
support/product-support/support-software/support-remote-management-agent
Note: Credentials are required to access Toshiba downloads.
2. Download the latest version of RMA ISO Image by clicking on Download Options.
Chapter 4. Installation Overview 37

Figure 7. Download package
3. Enter in your user name and password.
4. Depending on your choice of web browser, you may be required to select Yes when
prompted with a security alert.
5. Save the ISO image to the hard drive.
6. When the download completes, burn the ISO image to a DVD using the DVD-burning
software of your choice.
Step 3 – Installing IBM Systems Director Server 6

Note: These instructions are for installing IBM Systems Director Server 6 with the embedded
managed DB2 database. More advanced installations, such as installing with a different
database, is outlined in the Director publications. The link www.ibm.com/support/
knowledgecenter/SSAV7B_6.3.7/com.ibm.director.plan.helps.doc/
fqm0_r_supported_hardware_and_software_requirements.html has more information about
these installations.
Step 4 - Install IBM Systems Director Hotfixes

On the installation DVD, the isd_la_fixes directory contains patches for IBM Systems Director
that must be applied before using the retail extensions. The directory contains subdirectories for
each version of Director 6. The files contained in the directory whose name matches the version
of Director installed should be applied.
Step by step instructions on installing the hot fixes are located in isd_la_fixes
\LA_fixes_windows.pdf.
Step 5 – Installing RMA Retail Extensions for IBM Systems Director Server
Retail Extensions for IBM Systems Director must be installed on the same system as the Director
Server. See Chapter 6, Installing and upgrading Retail Extensions and RES on Windows on page

49 and Chapter 7, Installing and upgrading Retail Extensions and RES on Linux on page 65
for installing or upgrading Retail Extensions for IBM Systems Director on and Linux
respectively.
Step 6 – Installing RES

Note: RES must be installed on the same system as the Director Server.
See “Installing RES on Windows” on page 55 and Chapter 7, Installing and upgrading Retail
Extensions and RES on Linux on page 65 for Installing RES on Windows and Linux
respectively.
Step 7 – Verify Retail Extensions for IBM Systems Director and RES
Installation
The following steps verify that Retail Extensions for IBM Systems Director and RES is installed
through Director Console.
1. Create user IDs for Director Console users:
a. Add user IDs as members of the appropriate Director user group, such as smadmin for
authority to login and perform various Director Console functions.
b. Also add user IDs as members of the RESAdmin group for each user that needs access
to launch the RES Configuration Console and the RES Software Package Manager from
the Director Console.
2. Browse to the Director Server using: https://ip_address:8422/ibm/console/logon.jsp - where
ip_address is the IP address of the Director Server machine.
3. Log into the Director Console with an authorized Director Console user ID.
4. On the Resource Explorer window, click Retail Groups, then click All RES Systems. Verify
that RES:127.0.0.1:10520 is displayed with OK access.
Step 8 - Installing RMA MA

Note: RMA MA is usually installed on a single system within the store, that is, not at the
enterprise.
• For complete details to install the MA on Windows, refer to Chapter 8, Installing RMA (MA
and GA) on page 79.
• For complete details on how to install agents (MA or GA) on Linux refer to “Interactive
installation on Linux ” on page 92.
• For complete details on how to install MA on 4690, refer to “RMA on 4690 ” on page 97.
Step 9 - Installing RMA GA

Note: The GA must be installed within the store on a different system from the master agent.
You can install multiple General Agents within a single store - all connecting to a single MA.
• For complete details to install the GA on Windows, refer to Chapter 8, Installing RMA (MA
and GA) on page 79.
• For complete details to install GA on Linux, refer to “Interactive installation on Linux ” on
page 92.
• For complete details to install GA on 4690, refer to “RMA on 4690 ” on page 97.
Chapter 4. Installation Overview 39

Step 10 - Launch RMA Store Manager
See Chapter 14, Retail Enterprise Service on page 153, then scroll to “Launching RMA Store
Manager using Java WebStart” on page 154 and “Launching RMA Store Manager from a
command prompt” on page 159 for more information.
Step 11 - Configure RMA Store Manager to Discover RMA MA

See Chapter 14, Retail Enterprise Service on page 153, then scroll to “Adding Store Connection
entries” on page 160 for more information.
Step 12 - Authenticating to Agents Running Enhanced Security from

Director UI
See Chapter 15, RMA and IBM Systems Director basics on page 181, then scroll to “Retail Store
Authorization” on page 205 for more information.

Chapter 5. Installing IBM Systems Director Server 6
Installing IBM Systems Director Server 6
Installing for Windows™

This section describes the procedure for installing IBM Systems Director Server 6 on Windows.
1. Unzip the IBM Systems Director Server installation package to any location on your system,
or burn the ISO image to DVD if you downloaded a DVD image.
2. To start the installation, insert the DVD or launch the executable "launchpad.exe"
("launchpad64.exe" on a 64 bit system). You will be presented with the following screen:
Figure 8. Starting the installation - Welcome

3. Click Database Information on the left side of the window, and review the information
presented. If you plan on using managed DB2, then do nothing.

Figure 9. Database information
4. Click on the IBM Systems Director Server link on the left side. You can optionally run the
Pre-Installation Utility to check the system for any missing prerequisites. This will take a
few minutes. Once it completes, you will be presented with an HTML report of your system,
identifying any potential issues.
Figure 10. Selecting IBM Systems Director Server

5. Click the Install IBM Systems Director Server link to begin the server installation. It may
take some time for the following welcome screen to appear:
Figure 11. Installing IBM Systems Director Server

6. On the Welcome page, the pre-installation report shows if there were problems found. If no
problems were found, click Next to continue.
7. Read and accept the License Agreement, and then click Next .
Chapter 5. Installing IBM Systems Director Server 6 43

Figure 12. Accepting the License Agreement
8. On the screen that follows, check the option to include product updates and click Next .
Figure 13. Selecting the option for product updates

9. Select the features to install and optionally supply a custom install location and click Next .

Figure 14. Selecting features for a custom install location
10. For a standard setup that installs Director Server with standard options and managed
(embedded) DB2, select Basic.
Figure 15. Standard setup that installs Director Server

11. Enter an administrative user ID and password, and then select Next .
Note: It is very important that this be accurate when installing Director.
Figure 16. Entering an administrative user ID and password

12. Click Install to begin the installation.

Figure 17. Beginning installation
13. The Director Server installation will then proceed, installing the common agent, server, and
other components. It can take a long time (one or more hours) for the installation to
complete.
14. If you selected the install option to start the Director Server after the installation completes,
there will be a green triangle by the clock indicating IBM Systems Director Server is starting.
Figure 18. Green triangle clock indicator

15. Once Director Server has started, there will be a green circle by the clock.
Figure 19. Green circle clock indicator
Installing on Linux
The instructions for installing IBM Systems Director Server 6 on Windows shows the type of
input that would also be required for installing on Linux. You can use the instructions for
installing on Windows as guidelines for what input to expect to provide for installing on Linux.
The standard RHEL 6.4 and 6.5, 64 bit installation does not include some 32 bit packages that
IBM Systems Director 6.3.x requires. When you run the Director installation, a pre-installation
check is run and the install stops if the prerequisites are not met. Consult the summary report
that is specified in the output when the install stops (//tmp/checkds/reports/check
DS_Summary_<yyyymmdd>_<hhmmss>.html).

32/64 bit libraries during Director installation
To install IBM System Director on Linux, use the following link: www.ibm.com/support/
knowledgecenter/SSAV7B_6.3.7/com.ibm.director.main.helps.doc/directorwelcome.html.
Reference the following link to ensure that the prerequisite 32bit/64bit libraries on Linux for IBM
System Director installation: www.ibm.com/support/knowledgecenter/SSAV7B_6.3.7/
com.ibm.director.main.helps.doc/directorwelcome.html.
Use the following for help with installing libraries: www.ibm.com/support/knowledgecenter/
SSAV7B_6.3.7/com.ibm.esa.director.help/esa_kickoff.html.

Chapter 6. Installing and upgrading Retail Extensions and RES on
Windows
Installing and upgrading Retail Extensions and RES on Windows
This sections includes information to help you install and upgrade Retail Extensions and RES on
Windows.
Installing and upgrading Retail Extensions for IBM Systems Director on

Windows
1. Insert the RMA DVD.
Note: This DVD should have been created from the ISO image that was downloaded in
“Step 2 - Downloading RMA and the Retail Extensions for IBM Systems Director” on page
37
2. For Windows, expand the Windows > ISD directory:
Figure 20. Expanding the Windows > ISD directory

3. Run setup.exe.
4. After a few minutes, the Welcome page for the Retail Extensions for IBM Systems Director
Installer displays.

Figure 21. Welcome screen for Install Anywhere Launcher
5. Click Next on the Welcome page - after some time has elapsed, the Software Licence
Agreement page displays. Select I accept the terms in the Licence Agreement and click
Next .

Figure 22. Software License Agreement page
6. The IBM Systems Director Server page displays. Select Yes, restart IBM Systems Director
Server and click Next .
Figure 23. IBM Systems Director Server page
Chapter 6. Installing and upgrading Retail Extensions and RES on Windows 51

7. The Summary page displays. Click Install to begin the installation.
Figure 24. Summary page

8. Installation continues.

Figure 25. Installation continues
9. The installation will optionally restart the IBM System Director Server.

Figure 26. Restarting IBM Systems Director Server
10. The IBM Systems Director Server is stopped. You should verify that the server stopped
successfully by ensuring there is a "red diamond" in the task bar.
Figure 27. Verifying the IBM Systems Director Server stopped successfully
11. Select Done when the installation is completed.
12. Verify that the IBM Systems Director is restarted successfully. You should verify that the
server is started successfully by ensuring there is a "green circle" in the task bar. This may
take several minutes.
Figure 28. Verifying the IBM Systems Director Server restarted successfully - part 1
Figure 29. Verifying the IBM Systems Director Server restarted successfully - part 2

Verify RMA Retail Extensions for IBM Systems Director Server
Installation
Traverse to the path under the IBM Systems Director home directory, \IBM\Director\lwi
\bin, and execute the following command: lwiplugin.bat -status|find "retail". The
following Retail Plugins should be seen with the appropriate status:
• Retail Common - RESOLVED
• RES CHEC JMX Console Launch In Context Extension - Initial status LAZY
• RES CHEC JMX UI Console Task Extension - RESOLVED
• RES Config Console Launch In Context Extension - Initial status LAZY
• RES Configuration Console Task Extension - ACTIVE
• RES Software Package Manager Console Launch In Context Extension - Initial status LAZY
• RES Software Package Manager Console Task Extension - ACTIVE
• Retail Discovery Module Extension - ACTIVE
View builddate in /Director/Retail/RetailPlugin.properties for the build date of
Retail Extensions for Director.
Figure 30. Retail Plugins Deployment status - part 2
Note: The installation log for Retail Extension is placed under C:\temp folder.
Installing RES on Windows

Before you begin, Java/JRE for Windows platform should be present on the system. Refer to
“Java” on page 28 under IBM Systems Director/ Retail Enterprise service software requirements
to understand the Java requirements to run RMA agents.
The system Environment Variable JAVA_HOME can be set to the same JRE, if there is no impact
on other Java applications. As an alternative, JRE can be configured with agent installer as well,
as explained in the steps below.
Complete the following steps to install RES on Windows.
Note: This DVD should have been created from the ISO image that was downloaded in
37.
2. For Windows, expand the Windows > RES > x64 (64 bit) directory.
Note: RES is supported only on 64 bit systems. Support on 32 bit systems is discontinued.

Figure 31. Expanding the Windows > RES > x64 directory
Note: On Windows 2012 OS, right click on setup.exe and set the compatibility mode to
Windows 8.
3. Run setup.exe.
4. After a few minutes elapse, the Toshiba Retail Enterprise Service Installer screen is
displayed.
5. Click Next on the Welcome page. After some time elapses, the Software License Agreement
page displays. Select I accept the terms in the License Agreement, and click Next.
Figure 32. Software License Agreement

6. The installer software will read the system Environment Variable JAVA_HOME and will
check whether the JRE defined is valid (as per the criteria mentioned in Java Requirements).
If a valid JRE is found, a Valid Java VM Available panel will be displayed. User will be
prompted to confirm using the JRE/Java set for Environment Variable JAVA_HOME or
choose another valid JRE.

Figure 33. Valid Java VM Available
7. If user selects the No, Choose different Java VM option and clicks Next, the Select Java
Virtual Machine panel from Step 9 will be shown, which allows the user to choose a
different JRE.
8. If JRE provided at JAVA_HOME is not valid, as per the criteria mentioned in Java
Requirements, the Invalid Java Home panel will be displayed and the user must choose a
different valid JRE on the system.

Figure 34. Invalid Java Home
9. Select JRE/Java VM for use by RES. Click Choose Java Executable and select java.exe
executable on the system. Alternatively, the user can click Search another Location and
specify the location for performing java vm search and then choose the desired java vm
from the search result. Click Next.
If user wants to go ahead with java in JAVA_HOME or wants to specify other java, in either
case, the Java executable path is parsed and set to environment variable RES_JAVA_PATH.
An internal search will be performed for jvm library file (jvm.dll for windows and
libjvm.so for linux) in jre folder. If jvm library file is found after search, then the absolute
location path (excluding jvm.dll or libjvm.so) of jvm library file is set against
environment variable LIB_JVM_PATH. If jvm library file is not found, an appropriate
warning message will be thrown and installation process will not proceed.

Figure 35. Select Java Virtual Machine
10. The Choose Install Folder panel displays. Optionally supply a custom install location and
click Next.
Figure 36. Choose Install Folder

11. The Summary page appears. Click Install to start the installation.

12. The installation continues.
Figure 38. Installation continues

13. The installation is complete. Click Done and allow the computer to restart.

Figure 39. Installation complete
After installing RES, you should see the RES added and started in services.msc.
Figure 40. After installing RES - part 1
Figure 41. After installing RES - part 2

The following directory structure should be seen:
Figure 42. RES directory structure
Note: RMA RES installation log placed under C:\temp folder.
Upgrading Retail Extensions on the Windows platform

Retail extensions for IBM Systems Director can be upgraded to a higher version. The installer
provided for installation has to be used for upgrading as well. Installer will detect if Retail
extensions for IBM Systems Director is already installed on the machine and prompts the
Upgrade panel to upgrade.
Note: Downgrading Retail Extensions to a lower version than the version installed is not
supported.

Figure 43. Upgrading Retail Extensions for IBM Systems Director
Upgrading RES on Windows platform

RES can be upgraded to a higher version. The installer provided for installation has to be used
for upgrading as well. Installer will detect if RES is already on the machine and prompts the
Upgrade panel to upgrade.
Note: Downgrading RES to a lower version than the version installed is not supported.

Figure 44. Upgrade RES from 3.1.x to 3.2.x

Chapter 7. Installing and upgrading Retail Extensions and RES on
Linux
Installing and upgrading Retail Extensions and RES on Linux
This sections includes information to help you install and upgrade Retail Extensions and RES on
Linux.
The following procedure has to be done before installing Retail Extensions and RES on the Red
Hat Linux Platform. This is to increase the limit on the number of open file handles in the
operating system, which is needed for smooth functioning of RMA and to support scalability.
Make the following system changes:
1. Edit the /etc/security/limits.conf file by adding the following lines:
* hard nofile 64000

* soft nofile 64000
root hard nofile 64000
root soft nofile 64000
2. Save and close the /etc/security/limits.conf file. This updates the system limits to
increase the number of open file handles.
3. Reboot the system.
Installing Retail Extensions for IBM Systems Director on Linux

This section describes the procedure for interactively installing the Retail Extensions for IBM
Systems Director for Linux.
Note: This DVD should have been created from the ISO image that was downloaded in the
37.
2. Log on as a user with root privilege and expand the Linux > ISD directory from the DVD
image and copy setup.bin to the local machine.

Figure 45. Linux ISD directory
3. From the location where the setup.bin is placed, open a terminal and type the
command ./setup.bin -i console, and press Enter. This launches the console
installer in the console installation of Retail Extensions for the IBM Systems Director in a
new window.
Note: If ./setup.bin command is typed, the GUI launcher will be launched. This is not
recommended for use on the Linux platform.
A minimum disk space of 275 MB should be available for the console launcher to launch
successfully.
Figure 46. Step 3 - installation
It takes a few seconds to display the next panel.

4. Next a Welcome console panel will be displayed with the description of the product. Press
Enter to continue, or type Quit to quit the installation. It takes a few seconds to display the
next console panel.

5. The Systems requirements console panel will be displayed. This console panel provides the
status whether system requirements are met or not.
Press Enter to continue.

6. Next the Software License Agreement console is displayed. You must read the license
agreement and type and press Enter to accept the terms, then continue with the installation.
The License file is now in the license folder.
It takes a few seconds to display the next console panel.

7. The Start IBM Systems Director Server panel is displayed. This console panel provides the
current status of the IBM Systems Director whether it is running/active or inactive/stopped.
Chapter 7. Installing and upgrading Retail Extensions and RES on Linux 67

The Start IBM Systems Director Server panel asks you whether or not you want to start
IBM Systems Director Server after installation completes. Make the appropriate selection
and press Enter.
8. A summary page is displayed with the following details: product name, install folder,
required disk space, free disk space, and disk space information.

9. A console panel that shows the installation process progress displays.
Note: If you have chosen to restart the IBM Systems Director after installation in Step 7, the
installer will wait until the ISD start state is reached. If there is an issue with starting the
IBM Systems Director and if the state does not reach the starting state, the installer will retry
every 3 minutes for 10 minutes to restart, then will stop the installation.

10. The Installation Complete or Installation Failed console panel will be shown based on the
installation status as shown in Figure 53. Press Enter to complete the installation process.
Figure 53. Step 10- installation
Post installation
A post installation Retail folder will be created at opt/ibm/director/Retail. Following is
the contents of the Retail folder:
Figure 54. Post installation - Retail directory
The opt/ibm/director/Retail/eclipse/plugins will have the following jar files which

are necessary for running Retail extensions in IBM Systems Director 6:
Figure 55. Retail eclipse plugins
A retail folder with the contents, the folders events,healthstatus,inv and retail-
isd.properties, will be placed in /opt/ibm/director/proddata. The folders,

events,healthstatus,inv and retail-isd.properties will have configuration
information related to the events: Health status, Inventory, and Retail extensions functionalities.
Refer to the specifications of the events, Health status, Inventory and Retail extensions for more
details. The logging.properties in opt/ibm/director/lwi/conf/overrides will be
updated and appended to a configuration to enable INFO level of logging from the Retail
Enterprise Service and Retail Extensions.
Execution logs
At the time of installation, the debug level of the execution logs will be created at /tmp/
Retail_Inst_Debuglog.txt. The install command execution log will be placed at /tmp/
ISD_RetailPlugin_installLog.txt.
Upgrading Retail Extensions for IBM Systems Director

Retail Extensions for IBM Systems Director can be upgraded to an equal or higher version.
Downgrading to a lower version is not supported. An upgrade of Retail Extensions for IBM
Systems Director is similar to installing Retail Extensions for IBM Systems Director on Linux
(RHEL). See Chapter 7, Installing and upgrading Retail Extensions and RES on Linux on page 65
for more details.
Use the following steps for additional upgrade information:
1. The Retail Extensions for IBM Systems Director Upgrade panel is displayed to confirm the
upgrade.
Figure 56. Retail Extension for IBM Systems Director - Upgrade Confirm
2. The Retail Extensions for IBM Systems Director Upgrade panel is displayed confirming that
the prerequisite for an upgrade is met.
Figure 57. Retail Extension for IBM Systems Director - Prerequisite for an upgrade check

Installing RES for Linux
Java/JRE for RHEL platform should be present on the system. Refer to “Java” on page 28, under
"IBM Systems Director/Retail Enterprise Service software requirements" for more information.
Follow the steps below to interactively install the RES for Linux:
Note: This DVD should have been created from the ISO image that was downloaded in the
37.
Expand the Linux > RES > x64 directory from the DVD image and copy setup.bin to the
local machine.
Figure 58. Expanding Linux RES x64

2. Log on as a user with root privilege and from the location where the setup.bin is placed,
open a terminal and type the command ./setup.bin -i console, and press Enter. This
launches the console installer of RES.
A minimum disk space of 20 MB must be available for the Installer to launch successfully. It
takes a few seconds to display the next panel.

Figure 59. Launching the Console Mode Installer
3. Next, a Welcome console panel will be displayed with the description of the product. Press
Enter to continue, and type Quit to quit the installation. It takes a few seconds to display the
next console panel.
4. The Systems Requirements console panel will be displayed. This console panel provides the
status whether system requirements are met or not. Press Enter to continue.
Figure 60. Systems requirements panel - Linux

5. Next the Software License Agreement console panel is displayed. You must read the license
agreement and type and press Enter to accept the terms, then continue with the installation.
The License file is now in the license folder.
Figure 61. Software license agreement - Linux

6. The Installer software will read the system Environment Variable JAVA_HOME and will
check whether the JRE defined is valid (as per the criteria mentioned in Java Requirements).
If a valid JRE is found, a Valid Java VM Available panel will be displayed. User will be
prompted to confirm using JRE/Java set for Environment Variable JAVA_HOME or choose
another valid JRE.

7. If the No, Choose a different Java VM option is chosen, on pressing Enter the Select Java
Virtual Machine panel will be shown.
User must provide the complete Java executable location.
Note: The text, “Unable to install the Java Virtual machine included with this installer” will
be displayed in the panel. Please ignore this as this will not affect the functionality and it is a
limitation from the dependent Install Anywhere application.
8. If the JRE provided at JAVA_HOME environment variable or user selected JRE is not valid,
as per the criteria mentioned in Java Requirements, the Invalid Java Home panel will be
displayed.
Figure 64. Invalid Java Home
Press Enter.

Figure 65. Invalid Java Selection
Type 1 and press Enter. Now, specify the absolute path to the Java VM executable.
9. The Select Java Virtual Machine panel will be displayed. User has to provide the
appropriate complete Java executable location as explained in Step 8.
10. A Summary panel is displayed with the following details: Product Name, Install Folder,
Java VM selected, Disk Space Information etc.
Figure 66. Summary panel

11. A console panel that shows the installation process progress displays.
Figure 67. Installation progress - Linux

12. The Installation Complete or Installation Failed console panel will be shown based on the
installation status as shown in the figure below. Press Enter to complete the installation
process.

Figure 68. Installation complete - Linux
Post installation - Linux

After installing RES, traverse to the /opt/toshiba/res directory to view the directory
structure.
Figure 69. RES directory structure - Linux
After the installation, a RES Services should be listed in System --> Administration --> Services.
Figure 70. RES Services - Linux

Execution logs - Linux
At the time of installation, the debug level of the execution logs will be created at /tmp/
RES_Inst_DebugLog.txt. The install command execution log will be placed at /tmp/
RES_Install_Log.txt. Retail Enterprise Service Log: -/opt/toshiba/res/logs/res.0
and /opt/toshiba/res/logs/res_m.0 RES Service log:- /var/log/
resserver.log
Upgrading RES on Linux

RES can be upgraded to an equal or higher version. Downgrading to a lower version is not
supported. Ugrading RES is similar to Installing RES on Linux. (See Chapter 7, Installing and
upgrading Retail Extensions and RES on Linux on page 65.) The following are additional steps
necessary for an upgrade scenario.
1. The Toshiba Retail Enterprise Service Upgrade panel is displayed to confirm the upgrade.
Figure 71. Retail Enterprise Service - Upgrade Confirm

2. The Toshiba Retail Enterprise Service Upgrade panel is displayed confirming that the
prerequisite for the upgrade is met.
Figure 72. Retail Enterprise Service - Prerequisite for Upgrade Check

3. Press Enter to complete the installation.

Figure 73. Installation complete - Linux

Chapter 8. Installing RMA (MA and GA)
Installing RMA (MA and GA)
RMA is delivered on a single DVD, which includes the Remote Management GA and MA.
Before attempting to install the RMA software, read all the installation instructions in this
chapter.
The installation software uses InstallAnywhere installer on Windows. To install RMA, follow the
procedures described in “Interactive installation on Windows” on page 79, “Silent installation
of RMA on Windows” on page 91, or “Interactive installation on Linux ” on page 92.
Default Installation Location for RMA V3

The default installation directory for RMA V3 on Windows is C:\<Program Files or
Program Files(x86)>\Toshiba\RMA, which differs from the default location from V2R6
and earlier, C:\Program Files\IBM \StoreIntegrator.. The new default install location
only applies when installing a new instance of RMA. When upgrading from previous versions to
latest version, the previous install location will be maintained.
SI_HOME and RMA_ROOT Environment Variables

RMA V3 discontinued the use of the %SI_HOME% environment variable. For RMA V3.2.2 the
use of variable %RMA_ROOT% will be discontinued, as it is no longer necessary. These
variables will not be set or reused. Any scripts or packaging that refers to %SI_HOME% should
be replaced with %RMA_HOME%.
Interactive installation on Windows

The following sections describe RMA installation and post-installation procedures for a
Windows system.
Installation procedure
The steps below detail how to install RMA on Windows.
“Java” on page 30, under "RMA software requirements".
1. Log on with Administrator authority.
2. Insert the installation DVD into the DVD drive.
3. To run the installation program, open a command prompt window and issue the D:
\windows\rma\<xxx>\setup.exe command, where D is the DVD drive and xxx is the
RMA installer type (i.e. x86 or x86_64).
4. On the Welcome panel of the InstallAnywhere wizard for RMA, verify the version and click
Next.
5. On the Software License Agreement panel, read the license document and select I accept the
terms in the License Agreement. Installation cannot continue until you read and agree to
the license terms. Click Next.

Figure 74. License Agreement
6. A valid Java/JRE should be present on the system for successful installation of RMA, as
mentioned in “Java” on page 30. Refer to this section to understand the Java requirements
for running RMA Master and General Agents.
The Installer software will read the system Environment Variable, JAVA_HOME, and will
check whether the JRE defined is valid.
If a valid JRE is found, a Valid Java VM Available panel will be displayed. User needs to
confirm using JRE/Java set for Environment Variable, JAVA_HOME, or choose another
valid JRE.

If the user selects No, select a different Java VM, the next panel shown will allow the user
to choose a diferent JRE.
7. Select the valid java executable on the machine by clicking Choose Java Executable or
Search Another Location.
Chapter 8. Installing RMA (MA and GA) 81

8. If the JRE set in JAVA_HOME or JRE chosen is invalid, an appropriate error message will be
displayed. The Select Java Virtual Machine panel will be shown again to allow the user to
select another valid JRE.
Select an appropriate JRE and click Next.
Figure 77. Invalid JVM selection

9. For the first instance of Agent installation only: To install RMA in default location, C:
\<Program Files or Program Files(x86)>\Toshiba\RMA, click Next.
Otherwise, click Choose to select an alternative directory, and then click Next.
Note: If Store Integrator (SI) is installed on the system, install RMA to that file location.
If agent is already installed, the installer will install the agent in the previous installation
location.

Figure 78. Choose RMA installation location
10. For the first instance of Agent installation only: A list of agent types is displayed, as shown
in the Figure below. Select the radio button for the agent that you want to install and click
Next.
Note: The Master Agent is usually installed on a single system within the store, that is, not
at the enterprise. The General Agent must be installed within the store on a different system
from the Master Agent. You can install multiple General Agents within a single store, all
connecting to a single Master.

Figure 79. Select agent type
11. For the first instance of Agent installation and for Master Agent installation only: Enter
youre store ID and click Next.
Note: The store number can be a number or string identifier of your choice. However, the
store ID cannot contain the comma (,), equals (=), colon (:), quotation ('), asterisk (*), pipe (|),
or question mark (?) characters.

Figure 80. Enter Store ID
12. For the first instance of Agent installation and for Master Agent installation only: Select a
security mode option and click Next.
Figure 81. Select Security Mode
Note: If the Master Agent is running in enhanced security mode, then the IBM Systems
Director Server/Management application will need to supply credentials before it will gain

remote access to the system. Enhanced security mode is the recommended setting. These
security settings can be modified after installation by modifying the %RMA_HOME%\user
\rma\security\security.properties file.
13. For the first instance of Agent installation and for Master Agent installation only: Select
the interface (IP Address) for RMA to communicate with and click Next.
Figure 82. Select the Ethernet Interface IP Address

14. A summary panel is displayed with the information pertaining to the installation. If any of
the information is not correct, click Previous to return to a previous panel and change your
selection. When all selections are correct, click Install. Please note the installation process
takes several minutes.

Figure 83. Summary panel
15. A restart option page will be presented next. It is highly recommended to restart the system
post agent installation.
Note: When an agent is migrated from a previous version, certain configuration and data
files in the %RMA_HOME%user/rma directory could be migrated to new formats.

Figure 84. Installation complete
RMA 64 bit Installation

RMA V3.2.2 64 bit installer is supported on the 64 bit Windows® operating system. Similar to the
RMA 32 bit installer, the RMA V3.2.2 64 bit installer will not bundle JRE as a part of the
installation. The RMA 64 bit agent supports the user provided 64 bit JRE.
The RMA 64 bit Master Agent and General Agent installation flow is the same as the RMA 32 bit
installer. The default path for the RMA 64 bit installer location is C:\Program Files
\Toshiba\RMA\.

Figure 85. Choose the RMA installation location
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 RMA service starts running. There is an entry for
the Toshiba Remote Management Agent Service in the Windows Services Applet from the
Control Panel.
For information on how to configure the MA or GA after your installation is complete, see
Appendix on Custom RMA Agent Configuration.

Figure 86. Post installation window
Note:
1. If a MA 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 117.
2. If there are any additional security applications (other than Firewall) installed on any of the
agent machines (for eg. Symantec Endpoint protection), the respective application should be
configured to allow RMA.
RMA installation folder structure

RMA Windows Agent folder structure is revamped and the high level directory organization is
as shown in the figure below.
Note: Applications already using RMA and referring to a directory or files of previous version
should check and verify the correctness of the directory/file paths.

Figure 87. RMA directory structure
Silent installation of RMA on Windows

“Java” on page 30, under "RMA software requirements" for more information.
For silent installation, perform the following procedure:
1. The system variable, JAVA_HOME, needs to be set to the JRE location.
2. If JAVA_HOME cannot be set to the Java required by RMA agents, for reasons such as other
applications running on the system have different Java requirements than RMA, then the
user can set the system Environment Variable, RMA_JAVA_PATH, to the JRE required by
RMA.
If the Java set at system Environment Variable RMA_JAVA_PATH is valid, then this Java
will be used to run RMA agents.
5. See the installation section of the sample response file on the DVD (windows
\responseW.txt) to prepare your own response file.
6. Change to the Windows directory.
Note: On Windows 8.1 Embedded OS platform, execute the steps below before performing
a silent installation in order to overcome the installer limitation.
1. Right-click the installation file (i.e. setup.exe) and select Properties.
2. Click the Compatibility tab (change this setting for all users also).
3. Check the box next to Run this program in compatibility mode for and select
Windows 7 from the drop-down menu.

4. Click Apply.
7. Issue the silent.bat <full path to response file> command.
Using Update Manager for transferring JRE to RMA systems

Using RMA Update manager, JRE can be transferred to the agent system prior to RMA upgrade.
Note: For RMA 3.2.2, it is a pre-requisite to provide JRE for RMA agents to run.
The process to transfer user preferred JRE to agent systems is explained in Appendix D, Using
Update Manager for transferring JRE to RMA systems on page 381.
Using Update Manager for the Remote Management Agent

Using Update Manager in IBM Systems Director, you can upgrade the RMA agents. Package
files located directly on the installation DVD (i.e. dirpkgs\rma\<OS Type>) can be imported into
IBM Systems Director, creating RMA Software packages that can then be deployed to all
Windows or Linux systems running RMA. As for 4690 OS V6, RMA is included in the base 4690
OS. You must upgrade 4690 OS in order to upgrade RMA.
Note:
1. It is important to upgrade Master Agents first and then General Agents for a particular
store.
2. Refer to “Example: Updating RMA via RMA software distribution” on page 350 to upgrade
RMA using update manager.
3. The upgrade is not supported from the RMA 32 bit agents to the RMA 64 bit V3.2.2 agents.
It is only supported from the RMA V3.2.2 64 bit agents to the RMA V3.2.2 64 bit agents and
above versions.
Interactive installation on Linux

You can install the Remote Management Agent on a Linux system. The RMA agent is installed
and upgraded via an RPM package. On the installation DVD there are two RPM files: one for a
Master Agent, the other for a General Agent.
Linux Support in RMA V3

Only the basic RMA functionality is supported in RMA V3, including:
• Agent Discovery
• Software distribution
• Data capture
• Hardware Inventory
• Hardware and performance monitoring
• Events
• Power Management
Linux prerequisites
The list below details the prerequisites for installing RMA on Linux.
1. A Linux JRE with the following specifications should be present on the system.

• JRE should be of 32 bit for running RMA agents.
• JRE version should be of 8.
• RE should at least be compliant with the Java SE standards for Java 8.
Note: For RMA 3.2.2, JRE will not be bundled with agent installations.
Installer will check for valid Java before proceeding with the installation. If Java is not valid,
installation will be aborted and an appropriate error message will be displayed.
2. The system variable JAVA_HOME needs to be set to the JRE location.
3. If JAVA_HOME cannot be set to the Java required by RMA agents, for reasons such as other
applications running on the system have different Java requirements than RMA, then the
user can set the system Environment Variable RMA_JAVA_PATH to the JRE required by
RMA.
If the Java set at system Environment Variable RMA_JAVA_PATH is valid, then this Java
will be used to run RMA agents.
The RMA_JAVA_PATH variable can be set in the/etc/bash.bashrc.local file (for ex:
export RMA_JAVA_PATH=/usr/java/jdk1.8.0_45/jre or export
RMA_JAVA_PATH=/usr/java/jre).
4. The BIOS level should be updated to the latest version before OS installation.
This is required for getting Common Information Model (CIM) information from the
system.
RMA relies on access to 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 lost or is only available in a limited fashion.
The following features are dependent on CIM:
• Inventory collection
• Monitoring
• Retail peripheral management, including peripheral inventory, monitoring, and events.
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 Suse Linux Enterprise distribution, provide SFCB
support on a SUSE Linux Enterprise system:
• sblim-sfcb (minimum version sblim-sfcb-1.3.2-18.10.1)
• sblim-sfcc
• cim-schema
• cmpi-bindings-pywbem
• cmpi-provider-register
• libRaTools0
• libsblim-cmpiutil1
• sblim-cim-client2
• sblim-cmpi-base
• sblim-cmpi-dhcp

• sblim-cmpi-fsvol
• sblim-cmpi-network
• sblim-cmpi-nfsv3
• sblim-cmpi-params
• sblim-cmpi-smbios
• sblim-cmpi-sysfs
• sblim-indication_helper
• sblim-wbemcli
On Suse Linux Enterprise Point of Service (SLEPOS) clients, following additional packages are
needed:
• toshiba_upos_sblim-cmpi-upos-server-sled
• posIBM_XML4C
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:
• sblim-sfcb
• sblim-sfcc
• cim-schema
• cmpi-provider-register
5. Click Patterns -> Switch back to Groups.
6. Select All and search on sblim.
7. Install the following packages:
• libRaTools0
• libsblim-cmpiutil1
• sblim-cim-client2
• sblim-cmpi-base
• sblim-cmpi-dhcp
• sblim-cmpi-fsvol
• sblim-cmpi-network
• sblim-cmpi-params
• sblim-cmpi-sysfs
• sblim-indication_helper
• 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.
Configuring RMA for SFCB Connection

During startup, RMA tries to connect to SFCB. This connection has a default timeout value of
two minutes. This can be overridden as below:
1. Create a configuration file with name "sblim-cim-client2-ext.properties" in directory <RMA
Installation path>../user/rma/config/cim.
2. Add a property sblim.wbem.httpTimeout=<timeout value in milliseconds> in this file.
3. Restart the RMA service.
Note: If for some reason SFCB is not running when RMA starts, the RMA service will wait
to connect to the SFCB for a time specified in the above property. During this period, if a
user tries to stop the RMA service, an error will be thrown saying the RMA service could
not be stopped.
SFCB troubleshooting
Issue: While querying a class instance using wbemcli command, the command halts even
though SFCB service status shows running.
Resolution: This may happen if the 64 bit libraries' configuration is not correct. To overcome the
issue below steps may help.
• Check the "lib" folder name in /var path. It will have either only "lib" or both "lib" and "lib64"
folder
• If only /var/lib folder is present then edit the/etc/sfcb/sfcb.cfg file.
• Point all /var/lib64 path in sfcb.cfg file to /var/lib.
• Restart the SFCB service

Upgrading from RMA V2
The RPM package files in RMA V3 have a different base name, toshibaRMA. Because the names
of the RPM packages are different than RMA V2, the normal process for upgrading RPMs (using
the rpm -Uvh command ) cannot be used. As a result, the RMA V2 package must be manually
uninstalled (using the rpm -e command) before installing the RMA V3 package.
Installation and Upgrade Procedures

The following instructions describe how to manually upgrade and install RMA on a Linux
system.
Upgrade
To upgrade an RMA Agent from RMA V2 on a Linux system, perform these steps:
1. Log in as root.
2. Find the current version of RMA installed by issuing the command:
rpm -qa | grep RMA
3. If RMA is installed, the command will return a set of package names, one of which will
correspond to RMA.
Example: posIBM-GA-2.6-1027
4. Issue the command to uninstall the RMA RPM package:
--> rpm -e <package name>
Using the package name above, the command would be:
rpm -e posIBM-GA-2.6-1027
To upgrade RMA V3 from one release version to another, issue the command below:
--> Master Agent: rpm -Uvh toshiba_RMA-MA-X.Y.Z-xxxx.i586.rpm

--> General Agent: rpm -Uvh toshiba_RMA-GA-X.Y.Z-xxxx.i586.rpm
Note: If RMA V3 release is already installed, the below command can be used to install a
later version of the V3 release:
MA: rpm -Uvh toshiba_RMA-MA-X.Y.Z-xxxx.i586.rpm

GA: rpm -Uvh toshiba_RMA-GA-X.Y.Z-xxxx.i586.rpm
Installation
To install an RMA Agent onto a Linux system, perform these steps:
1. Log in as root.
2. Insert the installation DVD.
3. Make sure the DVD is mounted. If the DVD is not mounted, mount it using the mount
command. For example, issuing the mount /dev/cdrom/media/cdrom command as root
mounts the DVD to the /media/cdrom directory.

4. Change to the /media/cdrom/linux/rma directory.
5. Install the RMA Agent by issuing one of these commands:
• Master Agent: rpm -ivh toshiba_RMA-MA-X.Y.Z-xxxx.i586.rpm
• General Agent: rpm -ivh toshiba_RMA-GA-X.Y.Z-xxxx.i586.rpm
Post installation - installation and upgrade procedures

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).
Before running either of the agents for the first time, either after fresh installation or manual
upgrade 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.
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
This example supplies the value eth1 for the network interface option and myStoreId for the
store ID:
/opt/toshiba/rma/rma-config -n eth1 -s myStoreID -u enhanced
Note: The myStoreId string cannot contain any of the characters comma (,), equals (=), colon (:),
quote ('), asterisk (*), pipe (|), or question mark (?).
To supply new values for the configuration properties, the script can be run any time following
installation. After running the script, the RMA agent must be restarted for the changes to be
reflected.
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 117.
The ssl.properties file, that defines the set of SSL parameters to be applied to the socket
factory is loaded via the classpath. You can override this file by adding your own modified file
to the classpath.
Note: When a fresh install of agent rpm gets killed due to any reason, there is a likelihood of the
rpm database getting corrupted. Use the rpm --rebuilddb command to clean up the database
post which the install could be attempting again. When an rpm upgrade gets killed, the lower
version needs to be uninstalled and the higher version needs to be reinstalled.
RMA on 4690
Prior to OS4690 V7 and RMA V3R2.2, RMA was distributed as part of OS4690. Beginning with
OS4690 V7, RMA will not be bundled and distributed as part a of OS. RMA will be distributed as
a separate installable.

Interactive fresh installation of RMA on OS 4690
Customer can start fresh installation of RMA to the system where there is no RMA installed
previously. This is only applicable for OS4690 V7 or above and RMA V3R2.2 or above. See the
following:
1. Remote Management Agent installable on OS4690 will be distributed as ISO
(i.e.OS4690RMA_xxxx.iso). The inside content of the package would look like the
following:
Figure 88. Package content

2. Burn the ISO to a DVD and insert the DVD to a DVD drive on OS4690.
3. Go to P:\ and start install.bat, the license agreement screen is displayed.
Figure 89. License agreement screen

4. Press ESC to exit the installation.
5. Press ENTER to start the installation.

Figure 90. Installation in progress
6. Post successful installation, the Installation Complete screen is displayed.
Figure 91. Installation Complete screen

The Installation Complete screen gives information to the user on where to find the installation
log and the steps to follow before re-IPLing the controller(s).
Post installation
Post installation, you must restart the controller(s) for a new installation to take effect. Once the
restart begins, RMA service starts running. There will be an entry in the Report Module Level of
the controller named Remote Management Agent Ver3.

Figure 92. Report Module Level
After selecting the option above and pressing ENTER to get into the Remote Management
Agent Ver3 option, you will see the following details:
Figure 93. Remote Management Agent Ver3 details
Interactive Upgrade of RMA on OS 4690

Interactive upgrade is only applicable for those cases where prior to OS 4690 V7 i.e., V6R4 or
V6R5 is migrated to OS4690 V7, but still RMA is in V3R1.4/V3R2.0/ V3R2.1.
All of the previous steps are similar except for the initial screen, which will ask for your consent
to go ahead with upgrade.

Figure 94. Consent to proceed with the installation
Upgrade RMA on OS 4690 through ASM

RMA upgrade through Applied Software Maintenance (ASM) on OS4690 is applicable for a
OS4690 controller installed with RMA V3R2.2 or higher, and can upgrade to same version higher
level or higher version.
Please refer to the OS 4690 User's Guide for detailed steps on the ASM procedure.
Setting up RMA on 4690

Setup overview
After you have installed the operating system, you can enable RMA in the system configuration.
By default, RMA is not enabled on 4690 OS. The most important choice you should make is to
determine if and where to run the RMA master agent. See the following guidelines:
• If you select None, then each controller will run an instance of the RMA general agent. The
Master Agent must be installed on a separate system within the store (Windows or Linux).
The controller(s) and terminals in your store will appear within IBM Systems Director as
general agents.
• If you are running V7 in "enhanced" mode, you can decide whether to run the Master Agent
on 4690, or on another system in the store (Windows or Linux). If you choose to run the
Master Agent on 4690, you must select which controller will run the Master Agent. In a
multiple controller configuration, you should run the Master Agent on the Alternate Master
controller, unless the Alternate Master controller is also running as a Controller/Terminal. (It
is not generally recommended that you choose the master controller, for performance
reasons.) In a single controller configuration, you must evaluate for yourself whether the
performance impact is significant enough to warrant a separate system for the RMA Master
Agent.
• If you select to run the Master Agent on one of your controllers, then that controller will
appear within IBM Systems Director as the RMA master agent. Any other controllers in your
environment will appear within IBM Systems Director as general agents.

Note: The RMA Master Agent does not automatically "failover" if the controller that it is running
on goes down. If the controller running the Master Agent goes down, the entire store will appear
offline within IBM Systems Director.
The POS terminals are considered "virtual general agents", and they appear as general agents
within IBM Systems Director. The manageability of the terminals is not affected by your choice
of where to run the Master Agent.
Setup instructions
After you have installed and properly configured the 4690 operating system using the
instructions in the 4690 Planning, Installation, and Configuration Guide, use the following
instructions to prepare the OS for RMA and to enable RMA on the system.
1. As you go through the steps in the 4690 Planning, Installation, and Configuration Guide, do the
following:
• Define a HOSTNAME logical name (on each controller).
• Ensure the system HOST file has mappings for "localhost" and for each controller's node
ID.
• Update the TCP/IP batch file for each controller to include the local loopback address.
• For each "enhanced" mode controller, update the TCP/IP batch file to include the
appropriate "eloopaddr" statements.
Note: The "eloopaddr" address is essentially an external loopback address; specify last or
choose an unused address within the subnet of the controller.
The following screen shots illustrate these configuration settings. In the examples, the
controller node IDs are VM and VZ:

Figure 95. Example only ... defining the HOSTNAME logical name (each controller needs this logical
name defined with the controller node ID)

Figure 96. Example only ... HOSTS file with localhost and each controller node ID

Figure 97. Example only ... TCP/IP bat file for an enhanced-mode controller (each controller requires a
file similar to this one)
2. If you are planning to manage multiple stores within IBM Systems Director and you plan to
run the Master Agent on 4690, then it is very important to set the store number (in system
configuration) to a unique value for each store.

Figure 98. Store number
3. The next step is to enable RMA within system configuration. On this screen you will need to
choose whether to run the master agent on 4690 (and specify which controller will be used).

Figure 99. System management
4. Save your setting within system configuration, then "activate" your new system
configuration (and reboot).
5. Ensure TCP/IP is enabled for any terminals you want to manage using RMA by checking
the Enable TCP/IP check-box within the terminal load definition for each terminal. The
terminal might use DHCP or static IP. You can select legacy TCC or TCP/IP. After enabling
TCP/IP, do not forget to activate your configuration and reboot the controller and terminals.
6. Verify your setup using the instructions found in “Verifying your 4690 RMA setup” on page
107.
Verifying your 4690 RMA setup

At this point, your 4690 controller(s) and terminals should be running RMA, but you have not
yet verified that it is working properly. Follow these steps to complete the solution, and verify
everything is working as it should be:
1. You may want to double-check the following:
• Java and VFS support must be enabled on the controllers
• HOSTNAME logical name is defined for each controller
• adxhsihf.dat (that is, the HOSTS file) has an entry for each controller node ID, and an
entry for localhost
• adxipXXz.bat (that is, where XX is the node ID) is set up correctly for each controller –
it should have an entry for “lan0”, “lo0”, and a “default route” command.
• For enhanced-mode controllers, adxipXXz.bat contains the “eloopaddr” parameter for
lan0.

• RMA is enabled in system configuration
• Terminals have TCP/IP enabled
• If using certain Bladecenter network modules, “IGMP Snooping” must be disabled
Note: As a sanity check, it is a good idea to try to “ping” the IP address of each controller
and terminal from outside the system, just to make sure your TCP/IP settings are correct.
2. You can verify that RMA appears to be working OK, by examining the RMA log file. To do
that, open the following file using “xe” (or any text editor):
On Classic:
M: \ rma \ logs \ simgmt . 0
On Enhanced:
F: \ rma \ logs \ sigmgmt . 0
Scroll through the file, making sure there are no severe messages or java exceptions in the
file. (Warning messages are generally OK, but may be of interest if problems arise later in
your use of RMA.)
Note: If the log file does not exist, RMA is not running. (Make sure you “activated” your
system configuration!) If the Controller in question is a Controller/Terminal, then RMA will
not start until the Terminal side of the Controller/Terminal is up and running. Verify that
the terminal side is running before looking for the RMA logs.
3. If you are not running the master agent on one of the 4690 controllers, make sure you have
installed the RMA master agent on a separate system within the store. You should make
sure the master agent can “ping” the controller.

Chapter 9. Uninstalling Remote Management Agent
Uninstalling Remote Management Agent
The following sections provide information on uninstalling RMA.
Interactive uninstall for Windows

Follow the steps below to interactively uninstall RMA on Windows.
1. Log on as Administrator.
2. Run the %RMA_HOME%/uninstall/uninstall.exe program to uninstall RMA. A
welcome panel will be shown to uninstall RMA. Click Next.
Note: To uninstall RMA, InstallAnywhere uses the JRE provided by user to run RMA.
Figure 100. Uninstall Welcome screen (Windows)

3. To delete all contents of the installation folder, select Yes, click Uninstall and continue to
step 5. Otherwise, select No to retain the User configuration directory and all configuration
data. Click Uninstall and continue to step 4.

Figure 101. Remove installation directory
4. On the next panel, select No to retain the User configuration directory/files and logs.
Otherwise, select Yes.
Figure 102. Remove configuration directory

5. An Uninstaller summary panel is displayed, which confirms if the uninstallation was
successful. Choose to reboot now or later. After uninstalling RMA from a Windows system,
you need to reboot the system so that Environment Variables can be updated.
Click Done to complete the uninstall process.

Figure 103. Uninstall complete
Silent uninstall on Windows

Follow the steps below to perform a silent uninstall of RMA on Windows.
3. See the installation section of the sample response file on the DVD (windows
\responseW.txt) to prepare your own response file.
4. Change to the %RMA_HOME%/uninstall directory.
5. Issue the uninstall.exe –i silent -f <full path to response file>
command.
Uninstall result
After uninstalling RMA for Windows:
• The installation or root installation directory %RMA_HOME% remains.
• The %RMA_HOME%/logs and %RMA_HOME%/user folders remain as per user's decision at the
time of uninstallation.
• The RMA service is removed.
• The Environment Variables are updated or removed.
Uninstall for Linux

You can uninstall the agent RPM using the rpm -e command. To uninstall, first check the rpm
installed on the machine using rpm -qa | grep RMA.
Chapter 9. Uninstalling Remote Management Agent 111

Figure 104. Check RPM
Start the uninstall using rpm -e <rpm-name>
Figure 105. Uninstall
The DoNotDelete file, located in /opt/toshiba/rma/user/rma, determines whether or not

the /opt/toshiba directory is completely empty after uninstallation or if the data and
configuration files will remain. If the DoNotDelete file exists (default) during uninstallation,
the following directories will remain after uninstallation:
• /opt/toshiba/rma/user/rma
• /opt/toshiba/rma/silogs
• /opt/toshiba/rma/pd
The idea is that DoNotDelete will exist for normal upgrades, so anything we want to keep
moving forward should be left when DoNotDelete exists. The primary case for deleting the
DoNotDelete file is when permanently uninstalling RMA from the system.
During uninstallation, the rmauser.properties file is backed up to path /tmp/
rmaUninstall/. If the agent is installed again after uninstalling, this file is restored from the
above location and when you run the rma-config script to configure the agent, the values from
this restored file are used as default suggested values.

Chapter 10. Uninstalling Retail Extensions for IBM System
Director
Uninstalling Retail Extensions for IBM System Director
This chapter describes the steps to uninstall Retail Extensions for IBM System Director. Complete
the following to manually uninstall Retail Extensions for IBM System Director on Windows and
Linux:
1. Log in as Administrator (windows) / root (linux) user.
2. Stop the IBM Systems Director server.
3. Delete the Retail plugins placed under Windows: C:\Program Files\IBM\Director
\Retail\eclipse\plugins for Windows server Linux: /opt/ibm/director/
Retail/eclipse/plugins for RHEL server.
4. Remove Uninstall entry from Windows registry (This step is not applicable for linux)
Computer\HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows
\CurrentVersion\Uninstall\Retail Extensions for IBM Systems Director.
5. Start the IBM Systems Director server.
6. Reinstall required version of Retail Extensions for IBM Systems Director.

Chapter 11. Uninstalling Toshiba Retail Enterprise Service
Uninstalling Toshiba Retail Enterprise Service
This section explains how to uninstall the Toshiba Retail Enterprise Service.
Interactive uninstallation for Windows

This section describes the procedure for interactively uninstalling the Toshiba Retail Enterprise
Service (RES) on Windows.
1. Log on as Administrator.
2. Run the %RES_HOME%\uninstall\unistall.exe program to uninstall RES or go to
Control panel > Programs and Features > Toshiba Retail Enterprise Service and right-click
Uninstall/Change.
3. The Uninstaller panel displays, click Next.
4. The Uninstaller panel displays the status of the uninstallation operation. RES is removed
and environment variables are updated as needed.
Figure 106. Retail Enterprise Service Uninstaller Summary Panel

5. An uninstaller summary panel is displayed that confirms if the uninstallation was
successful. Choose to restart the computer now or later. Click Done to complete the
uninstall process.
After uninstalling RES from a Windows system, you will need to reboot so that environment
variables can be updated.
Uninstallation result
After uninstalling RES for Windows:

• The installation or root installation directory %RES_HOME% remains.
• The %RES_HOME%/logs folder remains.
• The %RES_HOME%/data folder remains.
• The %RES_HOME%/uninstall folder remains and it contains uninstallation log in the
following location: %RES_HOME%/uninstall/Logs/uninstallLog.txt.
• The Toshiba Retail Enterprise Service is removed
• The environment variables is removed.
Un-installing Retail Enterprise Service on Linux

Following are the steps to manually uninstall Retail Enterprise Service on Linux:
1. Log in as a root user.
2. Stop RES Service (if it is running) using the command: /etc/init.d/resserver stop
3. Remove RES service using this command: /sbin/chkconfig --del resserver
4. Remove RES Directory structure
5. Remove the file resserver under the path /etc/init.d/
6. Remove the file resenv under the path /etc/sysconfig/

Chapter 12. Understanding RMA Security
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
prevented unauthorized access to General Agents within a store.
Master Agent Security Modes

The RMA 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 require 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. This is
applicable to Windows.
For Linux and 4690OS, the security mode setup is done as a post installation setup.
The security mode can be changed after installation from one mode to another by changing the
security configuration file on the Master Agent system (see “Security configuration” on page
125).
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: You must have a valid username and password when connecting to a Master Agent in
enhanced security mode. You should have an Administrator username (added to RMAAdmin
group) and password to connect to a Master Agent on Windows. On Linux, it has to be 'root'
user (added to RMAAdmin group) and password.
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.
4690 OS
To use RMA enhanced security mode for a Master Agent running on 4690 V6R4 or V6R5, enable
4690 Enhanced Security in System Configuration > Enhanced Security.

A user ID also must be configured in the Enhanced Security > Authorization Manager with
User Defined Attribute #8 enabled. This user ID allows the IBM Systems Director Server to
authenticate with the 4690 Master Agent. Refer to the 4690 OS publications on the Toshiba
Global Commerce Solutions Web site: www.toshibacommerce.com for more details.
Linux
Enhanced security mode is the default mode for Linux MAs.
The rma-config script which is run post installation, allows the user to specify the store id, the
network interface, and the desired mode.
To change it manually to the desired mode, the com.ibm.retail.si.mgmt.security.mode
property in ../user/rma/security/security.properties must be edited.
IBM Systems Director

When IBM Systems Director (using Director plugin/RES) connects to a store/Master Agent that is
running in enhanced security mode, a username and password is required to authenticate with
that store. In Director UI, the Store Managed End points representing the stores/Master Agents
that require authentication are denoted with a lock icon:
Figure 107. Lock icon
Authenticating with the store, as described in “Retail Store Authorization” on page 205, will
remove the lock icon, discover the managed end points in the store, and allow them to interact.
RMA Store Manager

When RMA Store Manager is launched remotely on a different machine from the Director
console using Launch In Context, you are required to enter a username and password to
authenticate. If you are launching the RMA Store Manager using Launch In Context or
rmaStoreManager.bat on the same system running RES service, no authentication is required.
RMA Package Manager

When you launch the RMA Package Manager, regardless of the mode of launch (local or
remote), you are required to authenticate.

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 %RMA_HOME%\user\rma\security\keys_ma.dat
file on the Master Agent.
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 %RMA_HOME%
\user\rma\security\keys_ga.dat file on each General Agent, and restarting the General
Agent service.
4690OS Whitelisting Support for RMA

Whitelisting is a security function provided by 4690OS in enhanced mode. Whitelisting
specifically refers to a security configuration where 4690OS is only allowed to access or execute
files that are on a list of “trusted” files. It helps prevent modified or compromised files from
being used. Files are hashed as they are accessed by the system. The file hashes are compared
with the whitelist(s) installed on the system. If a file is not found in the whitelist, the system may
log an error or prevent access to the file depending on configuration.
For detail on Whitelisting please refer 4690OS User Guide Chapter/Section for Whitelisting (i.e.
Chapter 15).
At present RMA will distribute master list of whitelist file in zip format i.e. RMAWL322.zip.
User can modify the file according to their convenience.
Chapter 12. Understanding RMA Security 119

Chapter 13. RMA Agent configuration
RMA Agent configuration
This section explains how to configure the General Agent or Master Agent after installation is
complete.
Directory structure
The configuration files and extensions for the installed RMA agents are in the %RMA_HOME%/
user/rma directory. Under this directory is a set of subdirectories (listed in Table 5), each
containing configuration, data, or extension files.
Table 5. 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 files for RMA.
/update Directory containing program files and scripts for updating RMA.
/data Directory containing stored data.
/security Directory containing RMA security configuration and Secure Sockets Layer
(SSL) keystores.
Agent configuration file

The RMA agents store configuration data in a base configuration file, rma.properties, with
any overridden properties stored in a separate file, rmauser.properties. The
rma.properties file should never be edited. It will be replaced whenever RMA is updated.
Any values supplied in rmauser.properties will override the base values in
rma.properties. The rma.properties and rmauser.properties files are stored in the
following locations:
• Windows: %RMA_HOME%\user\rma
• 4690 Classic: M:\rma\user\rma
• 4690 Enhanced: F:\rma\user\rma
• Linux: (RMA V3 new install) /opt/toshiba/rma/user/rma
• Linux: RMA V3 update to V2 RMA) /opt/ibm/StoreIntegrator/rma/user/rma
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 6. 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.

Agent property and description
com.ibm.retail.si.mgmt.storeId
(Master Agent) The store ID. On 4690 OS, if valid store id value exists in rmauser.properties,
this property will be set from rmauser.properties. Otherwise this value will be set to the store
number configured in 4690 System Configuration..
com.ibm.retail.si.mgmt.remote.interface
Name of the network interface (such as eth0) that is used for management (General Agent) or
is exposed to management applications (Master Agent).
com.ibm.retail.si.mgmt.generalagent.protocol
(General Agent) Name of the protocol to use for the General Agent's JMXConnectorServer
(soxs). This should not be changed. RMI is the default protocol for OS 4690 and soxs is the
default for Windows and Linux platforms.
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.
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.
rma.security.disable.md5.algorithm=false
Property for explicitly enabling MD5 algorithm for certification path processing and TLS
handshake. RMA by default sets this property to false to enable MD5 algorithm, as the latest
JRE's by default disable MD5 algorithm. RMA enables MD5 by default to facilitate migration
scenarios and backward compatibility. Users can ensure security by using custom certificates
generated with secure algorithms such as SHA256WithRSA. It is highly recommended to
change value of this property to true once all components of RMA are upgraded to version
3.2.2.
Table 7. 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 property and description
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 8. Event properties

Event property and description
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 10000 on a Master Agent and 1000 on a General Agent ). If storeandforward.maxevents is
set to a value less than storeandforward.buffersizethreshold, the default value will be used.
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffersizethreshold
The number of events that are buffered (default is 200).
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 (default is 300000).
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.eventExpirationCleanupFreq
uency
The number of hours between checks for expired events.
Table 9. 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 Notification Processor's incoming event queue
before it will begin to buffer events to disk (the default is 1000).
Table 10. 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
Chapter 13. RMA Agent configuration 123

Data capture property and description
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).
Table 11. Phone Home Connection Properties
Phone Home connection Property and description
com.ibm.retail.rma.phome.connectionTimeout
The time in seconds (s), minutes (m), hours (h), or days (d) (e.g., 3h) that reconnection attempts
will stop if communication with the server (RES) side is not re-established. The default value is
1d.
com.ibm.retail.rma.phome.reconnectFrequency
The time in seconds (s), minutes (m), hours (h), or days (d) (e.g., 3h) between re-connection
attempts with the server (RES) side. The default value is 30s.
com.ibm.retail.rma.phome.newClientReconnectFrequency
The time between attempts to establish an initial connection with the server (RES) side. The
default is 30 minutes. This property only comes into play when the RES information is
complete in the phonehome.properties file located in the %RMA_HOME%/user/rma/config/
phonehome directory.
Overriding Store Id in 4690 Master Agent

For Windows and Linux Master Agent, Store id will be set as part of agent installation. This store
id value will be added in rmauser.properties (this is not applicable for 4690 MA).
For 4690 MA, Store number will be set in system configuration during RMA fresh installation
(See “Setting up RMA on 4690 ” on page 101). By default, store id key will be present in the
rmauser.properties file with an empty value. On agent start up, Store id value will be read from
rmauser.properties. If key exists and has a valid store id value, this store id value will be set.
Otherwise Store number, which is configured in system configuration, will be populated as Store
Id.
Follow the steps below to override store id value for 4690 Master Agent:
1. Stop RMA service in 4690 OS (See Appendix A, Stopping and starting RMA Director RES on
page 375).
2. Edit rmauser.properties and add the following line:
com.ibm.retail.si.mgmt.storeId=StoreIdValue

3. If Store id key is not present in rmauser.properties, user can add it manually by referring
rmauser.def in same location.
4. Save rmauser.properties and start RMA service.
5. If given store id value is valid, then it will be read during agent start up and will be set as
store id.
6. If it is invalid, by default, Store number will be read from system configuration and will be
set as store id.
Figure 108. rmauser.properties file with store id key in 4690 MA
Note: The store ID value can be a number or string identifier of your choice. However, the
Store ID cannot contain the comma (,), equals (=), colon (:), quotation ('), asterisk (*), pipe (|),
or question mark (?) characters.
The store ID value will be taken only if it is valid. It will be invalid if store id key does not exist
or store id value is blank or contains invalid special characters.
Security configuration
The security configuration file is called security.properties. This file is located in directory
%RMA_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.
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 Systems 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:
• Windows: %RMA_HOME%\user\rma\classes
• Linux: /opt/toshiba/rma/user/rma/classes
• 4690 Classic: M:\rma\user\rma\classes
• 4690 Enhanced: F:\rma\user\rma\classes
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.
The components that rely on the SSL configuration are RMI/SOXS, File Streaming. The SSL
configuration controls whether sockets are SSL enabled when making remote JMX connections
using SOXS/RMI. The RMA alias determines the use of SSL for connections between a Master
Agent and a General Agent, and for connections between any management application
(including IBM Systems Director) and the Master Agent. When the RMA alias is 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.
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.
RMA 3.2.2 supports TLSV1.2 protocol as well. TLSv1 support will be continued to facilitate
migration scenarios and backward compatibility. TLSv1 and TLSv1.2 protocol support will be
enabled by RMA by default, with the following property in the ssl.properties file:
• SSL.protocol=TLSv1,TLSv1.2
It is highly recommended to use the TLSv1.2 protocol for security purposes only. Hence post
successful migration, user can remove the TLSv1 protocol option from the SSL.protocol
varaible (i.e. SSL.protocol=TLSv1.2) across the RMA solution stack. This can be done
manually by updating the ssl.properties file and restarting the RMA service or by
performing the RMA Software Distribution process. Refer to “Updating SSL.protocol property
using Software Distribution” on page 127 for more information.
Note:
1. In case of SSL connection between Client and Server, the common highest version of TLS
protocol will be considered. See the example scenarios below in which RES is the Client of
SSL connection and Master Agent is the Server of SSL connection.
a. When the configured protocol in the ssl.properties file is both TLSv1 and TLSv1.2
(SSL.protocol=TLSv1,TLSv1.2) on RES and is only TLSv1 on the Master Agent
(which it typically will be during migration scenario), the highest common protocol,
TLSv1 will be used.
b. When the configured protocol in the ssl.properties is both TLSv1 and TLSv1.2
(SSL.protocol=TLSv1,TLSv1.2) on both the RES and Master Agent, the highest
common protocol, TLSv1.2 will be used.
2. 4690 Classic Controller does not support TLSv1.2. Therefore, the MA in stores that have a
classic controller needs to have both TLSv1 and TLSv1.2 as the configured protocol in the
ssl.properties file, so that TLSV1 connection can be established with classic controller.

3. In the latest JRE versions, MD5 algorithm is disabled by default for certification path
processing and TLS handshaking to address a security vulnerability. RMA, to support
migration to newer version and backward compatibility, enables MD5 algorithm by default
for certification path processing and TLS handshaking. By default, the property
rma.security.disable.md5.algorithm in rma.properties/res.properties is
set to false, which means MD5 algorithm is enabled. MD5 algorithm can be enabled (by
setting the property to false) or disabled (by setting the property to true) with this property.
On configuring the above property, RMA modifies the java security properties
jdk.certpath.disabledAlgorithms and jdk.tls.disabledAlgorithms for
disabling/enabling MD5 algorithm as configured.
Post successful migration to RMA newer version across the RMA solution stack (Director
plugin, RES, master Agents and General Agents), the MD5 algorithm can be disabled as
mentioned above. The updated rma.properties can be distributed (via SWD as well) to
General Agents first and then to Master Agents. Post changes on agents, RES can be
updated with updated res.properties.
Users can ensure security by using custom certificates generated with secure algorithm like
SHA256WithRSA.
4. RMA uses SSL sockets for communication so that data is encrypted when transmitted. A
default RMA SSL certificate is installed with each system, providing an initial level of
security. The RMA truststore has two alias/entries, the rmacert and rsscert. The rmacert is
signed with SHA256withRSA algorithm and rsscert is signed with MD5withRSA algorithm.
The validity of rmacert is from Fri Apr 01 08:43:20 IST 2016 until: Sat Mar 20 08:43:20 IST
2066. The validity of rsscert is from Fri Mar 07 22:30:27 IST 2014 until: Sun May 24 22:30:27
IST 2065. RMA KeyStore will have one private key entry re-signed with SHA256WithRSA
algorithm.
Updating SSL.protocol property using Software Distribution

Follow the procedure below to update the SSL.protocol property in the ssl.properties
file, using Software Distribution.
1. Using Software Package Manager, create a package for installing the updated
ssl.properties file.
2. While creating the package, choose Restart Computer as post installation action.
3. After creating the package, perform software distribution on the target machine.
MD5 algorithm support

To provide backward compatibility, the MD5 algorithm is enabled by default for certification
path processing and TLS handshaking. Initially, the property
rma.security.disable.md5.algorithm in rma.properties/res.properties is set to
false, which means MD5 algorithm is enabled. As per the requirement, MD5 algorithm can be
enabled (by setting the property to false) or disabled (by setting the property to true). The java
security properties jdk.certpath.disabledAlgorithms and
jdk.tls.disabledAlgorithms are modified for disabling/enabling MD5 algorithm.

Figure 109. Enable/Disable MD5 algorithm
New SSL/TLS certificate

RMA uses SSL sockets for communication so that data is encrypted when transmitted. A default
RMA SSL certificate is installed with each system, providing an initial level of security. The
RMA keystore has two alias/entries, the rmacert and rsscert. The rmacert is signed with
SHA256withRSA Algorithm and rsscert is signed with MD5withRSA Algorithm. The validity
of rmacert is from Fri Apr 01 08:43:20 IST 2016 until: Sat Mar 20 08:43:20 IST 2066. The validity
of rsscert is from Fri Mar 07 22:30:27 IST 2014 until: Sun May 24 22:30:27 IST 2065.
Updating SSL certificates

RMA uses SSL sockets for communication so that data is encrypted when transmitted. The
certificate used for SSL is also used by RMA to authenticate connections between IBM Systems
Director servers and Master Agents running in standard security mode.
Note: Master Agents running in enhanced security mode do not use an SSL certificate for
authentication. Instead, the connection between IBM Systems Director and the Master Agent is
authenticated using a user ID and password entered for the Master Agent in RMA Store
Manager.
A default RMA SSL certificate is installed with each system, providing an initial level of security.
Replacing the default certificate with a custom generated certificate will provide an increased
level of security and is highly recommended.
Creating new custom keystore and truststore files

Below are the steps to create a new keystore and truststore. The keystore will contain the new
trusted certificate and the truststore will contain both the current and new certificates.
Note: The aliases "rss", "rsscert", and "rmacert" must not be changed when entering the
commands shown in the steps below. Also, do not change custkey1, custkey2, custstore1,
and custstore2 when entering the commands.
1. Select the system to use for creating the new keystore and truststore files:
• For an enterprise that does not have any RMA agents on 4690 Classic controllers,
perform the steps below on the IBM Systems Director system.
• For an enterprise that has some RMA agents on 4690 Classic controllers, perform the
steps below on any 4690 Classic controller that has an RMA agent running.
2. Determine if the enterprise is currently using the default RMA SSL certificate or a custom
RMA SSL certificate.
1. Change to the following directory:
For Windows Director Server: %res_home%\classes
For Linux Director server: /opt/toshiba/res/classes

For 4690 Classic controller: M:/rma/user/rma/classes
2. View the contents of userssl.properties. If userssl.properties does not exist,
then view the contents of ssl.properties.
3. If the SSL.KeyFileName property is assigned the fully qualified path to "rsskeys" and
the SSL.TrustFileName property is assigned the fully qualified path to "rssstore", then
the default RMA SSL certificate is currently being used. Otherwise, a custom SSL
certificate is currently being used.
3. Change to the following directory:
For Windows Director server: %res_home%\ security
For Linux Director server: /opt/toshiba/res/security
For 4690 Classic controller: M:/rma/user/rma/security
4. If the default RMA SSL certificate is currently being used in the enterprise as determined in
step 2:
Copy the rsskeys file and name the copy custkey1 in the security folder.
5. If a custom RMA SSL certificate is currently being used in the enterprise as determined in
step 2:
1. Rename the current custom keystore file to custkey1 in the security folder.
Note: The current custom keystore file is the file specified by the SSL.KeyFileName
property in userssl.properties, or ssl.properties if userssl.properties does not exist.
2. Rename the current custom truststore file to custstore1 in the security folder.
Note: The current custom truststore file is the file specified by the SSL.TrustFileName
property in userssl.properties, or ssl.properties if userssl.properties
does not exist.
6. When doing the keytool commands in the steps below, use the following path for the
<keytool_path> in the keytool commands:
For Windows Director server: "%DIR_HOME%\jre\bin\"
For Linux Director server: /opt/ibm/director/jre/bin/
For 4690 Classic controller: java2bin:
7. Export the current RMA SSL certificate to a temporary file by running the following
command from the directory shown in step 3 above:
• <keytool_path>keytool -export -alias rss -keystore custkey1 -rfc
-file custkey1.cer
• When prompted to "Enter keystore password:", press Enter.
Note: custkey1.cer file is created in the security folder.
Note: If a custom SSL certificate is currently being used in the enterprise, then some later
steps can be skipped if the same password is used for creating the new keystore and
truststore in steps 8-10 below and the same filenames are assigned in step 13 as the current
custom keystore and truststore. A NOTE in the later steps will indicate if a section or step
can be skipped.
8. Generate a new custom keystore file with a single key by running:
Note: In the following command, enter the password of your choice for Custom_PW.
• On the Director server:

<keytool_path>keytool -genkeypair -alias rss -keyalg RSA -keysize
2048 -sigalg SHA256withRSA -validity 365 -keystore custkey2 -
storepass Custom_PW
• On the 4690 Classic controller:
java2bin:keytool -genkey -alias rss -keyalg RSA -keysize 1024 -
validity 365 -keystore custkey2 -storepass Custom_PW
• Answer prompts appropriately.
• When prompted to "Enter key password for <rss>:", press Enter.
Notes:
1.custkey2 file is created in the security folder.
2.The command creates a certificate that will be valid for 365 days. The certificate can
be created with a different validity period if desired.
3. 1024-bit certificate size is the size limit for the SSL certificate in an enterprise with
Classic controllers since Classic controllers have Java 1.4.2 JVM.
4. Save the password in a secure place. It will be needed in the future for the next time
these instructions are followed to create and deploy a new RMA SSL certificate.
5. You can view the contents of the new custom keystore file by running:
<keytool_path>keytool -list -v -keystore custkey2 -storepass
Custom_PW
9. Export the new custom RMA SSL certificate to a temporary file by running:
• <keytool_path>keytool -export -alias rss -keystore custkey2 -rfc
-file custkey2.cer -storepass Custom_PW
Note: custkey2.cer is created in the security folder.
10. Generate a new custom truststore file with current and new keys by running:
• <keytool_path>keytool -import -alias rsscert -file custkey1.cer -
keystore custstore2 -storepass Custom_PW
• When prompted to "Trust this certificate? [no]:", type y for "yes" and press Enter.
• <keytool_path>keytool -import -alias rmacert -file custkey2.cer -
keystore custstore2 -storepass Custom_PW
• When prompted to "Trust this certificate? [no]:", type y for "yes " and press Enter.
Note: custstore2 file is created in the security folder.
11. Verify the new custom truststore file contains the current and new RMA SSL certificates by
running:
• <keytool_path>keytool -list -v -keystore custstore2 -storepass
Custom_PW
The current certificate with current validity period should be shown with alias rsscert
and the new custom certificate with new validity period should be shown with alias
rmacert.
12. Delete the custkey1.cer and custkey2.cer files. Delete the custkey1 and
custstore1 files after saving your own backup of these files.
13. Rename the new keystore and truststore files to desired names:
1. Rename custkey2 file to any 8 character name for the custom keystore. Use the new
name in place of New_Custom_Keystore in the following sections.
2. Rename the custstore2 file to any 8 character name for the custom truststore. Use the
new name in place of New_Custom_Truststore in the following sections.

Note: You can use the same filenames as the previous custom keystore and custom
truststore files. If you choose to select new filenames, the names are limited to eight
characters due to filename limitations on OS 4690.
WARNING: Do NOT use the names of the default keystore, rsskeys, and default
truststore, rssstore, as these files are overwritten during an RMA upgrade.
14. If the new custom keystore and truststore files were created on a 4690 Classic controller,
copy the new files to the Director server into the security folder as shown in step 3 above.
Create override SSL properties file with new custom filenames and
password
For the new custom keystore and truststore files to be used, it is necessary to create or update the
user SSL properties file on the IBM Systems Director Server and on each RMA Master Agent and
General Agent with the new keystore and truststore filenames and password.
The following steps are used to create a different version of userssl.properties for each platform
that RMA agents run on and for the Retail Enterprise Service on the Director server since the
paths specified in userssl.properties to the keystore and truststore files are different for each
platform.
The steps to deploy the new versions of the userssl.properties file are done later in “Deploying
new custom SSL related files to RMA Agents” on page 137.
1. If userssl.properties exists in the classes directory on the Director server (refer to step
2 in previous section for location of the classes directory) and the filenames and password of
the new keystore and truststore created in the previous section are the same as already
specified for the current custom keystore and truststore in userssl.properties, then
this section can be skipped.
Note: In userssl.properties, the SSL.KeyFileName property specifies the current
custom keystore filename and the SSL.TrustFileName property specifies the current custom
truststore filename.
2. Select any RMA agent to use in the steps below to create a version of
userssl.properties with the new keystore and truststore filenames and password.
Note: These steps should be done on an agent in a test store instead of a real store if
possible.
3. On the selected RMA agent system, change to the following directory:
For Windows agent: %RMA_HOME%\user\rma\classes
For 4690 Enhanced controller: F:\rma\user\rma\classes
For 4690 Classic controller: M:\rma\user\rma\classes
For Linux agent: /opt/toshiba/rma/user/rma/classes
4. Save a backup copy of the current ssl.properties file in the classes folder.
5. Modify the following properties in ssl.properties to the names of the new keystore file
and the new truststore file:
SSL.ServerKeyFileName=<path>New_Custom_Keystore
SSL.KeyFileName=<path>New_Custom_Keystore
SSL.ServerTrustFileName=<path>New_Custom_Truststore
SSL.TrustFileName=<path>New_Custom_Truststore
where <path> is the following fully qualified path:

For Windows agent: c:/Program Files/Toshiba/rma/user/rma/security/
For 4690 controller: C:/adx_idt1/
For Windows Director: C:/Program Files/Toshiba/RES/security/
For Linux Director: /opt/toshiba/res/security/
For Linux agent: /opt/toshiba/rma/user/rma/security/
Note: The above paths for Windows assume the default location for RMA or Retail
Enterprise Service (RES) installations. The paths for the above properties should include the
actual installed location if different from the default, or if installed on Windows 2012 which
has the default installation location of c:/Program Files (x86)/Toshiba/RES for RES
and c:/Program Files (x86)/Toshiba/rma for an RMA agent.
6. Remove the "_encrypted" portion from the name of the following properties:
SSL.ServerKeyPassword_encrypted
SSL.KeyPassword_encrypted
SSL.ServerTrustPassword_encrypted
SSL.TrustPassword_encrypted
7. Replace the encrypted password with the unencrypted value of Custom_PW for the
following properties:
SSL.ServerKeyPassword=Custom_PW
SSL.KeyPassword=Custom_PW
SSL.ServerTrustPassword=Custom_PW
SSL.TrustPassword=Custom_PW
8. Restart the RMA agent to encrypt the password in ssl.properties. Refer to Appendix A,
Stopping and starting RMA Director RES on page 375 for how to stop/start RMA agent.
Note: The Custom_PW password will be encrypted in ssl.properties when RMA starts.
9. Create a copy of ssl.properties named userssl.properties.<platform> for each
of the platforms with an RMA agent in the enterprise:
For Windows Agent: userssl.properties.windows
For 4690 controller: userssl.properties.4690
For Windows Director: userssl.properties.WinDirector
For Linux Director: userssl.properties.LinuxDirector
For Linux agent: userssl.properties.Linux
10. Repeat step 5 for each userssl.properties.<platform> file created in step 9. The fully
qualified path to specify when doing step 5 is the path for the platform the file is for.
11. Save the userssl.properties.<platform> files to use later in “Deploying new custom
SSL related files to RMA Agents” on page 137 and “Creating res-ssl.jar with new custom
SSL related files” on page 135.
12. Restore the agent back the way it was before doing step 4 above by deleting the
ssl.properties file, copying the original ssl.properties that was saved in step 4
into the classes folder, and restarting RMA.
In the case where custom ssl has already been deployed on RMA ( prior to version 3.2.2), there
will be two ssl configuration properties files, ssl.properties and userssl.properties.
Upgrading from RMA 3.2.1/3.2.0 to 3.2.2 will replace the original ssl.properties file with the
file that has SSL.protocol=TLSv1,TLSv1.2 and SSL.provider=IBMJSSE2.
However, the userssl.properties file will not change. In this case, the value for the above
properties needs to be set in the userssl.properties file, and the property file needs to be
manually deployed on RES to the respective agents by Software Distribution.

In addition to this, the userssl.properties file in the jar, res-ssl.jar, needs to be
updated and the ISD plugins also need to be updated, as described in “Creating res-ssl.jar with
new custom SSL related files” on page 135.
Create jar file for remote embedded agents with new custom SSL
related files
For the new keystore and truststore files to be used by RMA remote embedded agents, a jar file
with those files and an updated ssl properties file must be deployed to each system that has an
application that starts a remote embedded agent. This section explains the steps to create the jar
file with custom SSL files.
Note: The following steps do not apply to local embedded agents. Only a remote embedded
agent will be discovered and appear in Director as a separate agent. A local embedded agent will
be discovered locally by the RMA service agent that is running on the same system, therefore a
local embedded agent will not appear in Director as a separate agent.
1. Select any RMA agent to perform the steps below. It is recommended to use an agent in a
test store instead of a real store.
2. Create a temporary directory on the agent called EA-tmp.
3. Copy the New_Custom_Keystore and New_Custom_Truststore files from the following
directory on Director to the EA-tmp directory:
From Windows Director: %res_home%\ security
From Linux Director:/opt/toshiba/res/security
4. If the default RMA SSL certificate is currently being used in the enterprise as determined in
step 2 of “Creating new custom keystore and truststore files” on page 128:
1. In command window, change to following directory where simgmt.jar is located:
On Windows agent: %RMA_HOME%
On 4690 controller: F:\rma\lib (M: for Classic controller)
On Linux agent: /opt/toshiba/rma/jar
2. Get a copy of rma-ea-ssl.properties from simgmt.jar by running:
On Windows or Linux system:
<path>jar xf simgmt.jar rma-ea-ssl.properties
where <path> is location to jar command for JDK (may need to install JDK)
On 4690 controller:
java2sdk:jar -xf simgmt.jar rma-ea-ssl.properties
3. Move the copy of rma-ea-ssl.properties to the EA-tmp directory.
4. Skip step 5.
5. If a custom RMA SSL certificate is currently being used in the enterprise as determined in
step 2 of the “Creating new custom keystore and truststore files” on page 128 section:
From Windows Director: %res_home%\security
From Linux Director /opt/toshiba/res/security
1. For an application that starts a remote embedded agent, determine what jar file contains
the current custom SSL related files for the embedded agent to communicate with the
Master Agent.

2. Get a copy of the jar file with the current custom SSL related files for embedded agents
and put the copy in the EA-tmp directory and change the name to EA-SSL.jar.
3. Get a copy of rma-ea-ssl.properties from EA-SSL.jar by running the following
command from the EA-tmp directory:
<path>jar xf EA-SSL.jar rma-ea-ssl.properties
On 4690 controller:
java2sdk:jar -xf EA-SSL.jar rma-ea-ssl.properties
4. Delete EA-SSL.jar from the EA-tmp directory.
5. If the new custom keystore and truststore have the same filename and password as the
current custom keystore and truststore specified in rma-ea-ssl.properties, then
steps 6 through 9 can be skipped.
6. Edit rma-ea-ssl.properties in the EA-tmp directory and modify the following
properties to the name of the new keystore file and the new truststore file:
SSL.ServerKeyFileName=*New_Custom_Keystore
SSL.KeyFileName=*New_Custom_Keystore
SSL.ServerTrustFileName=*New_Custom_Truststore
SSL.TrustFileName=*New_Custom_Truststore
7. Remove the "_encrypted" portion from the name of the following properties:
SSL.ServerKeyPassword_encrypted
SSL.KeyPassword_encrypted
SSL.ServerTrustPassword_encrypted
SSL.TrustPassword_encrypted
8. Replace the encrypted password with the unencrypted value of Custom_PW for the
following properties:
SSL.ServerKeyPassword=Custom_PW
SSL.KeyPassword=Custom_PW
SSL.ServerTrustPassword=Custom_PW
SSL.TrustPassword=Custom_PW
9. Encrypt the password in rma-ea-ssl.properties

1. Save a backup copy of ssl.properties in the following directory:
For Windows agent: %RMA_HOME%\user\rma\classes
For 4690 controller: F:\rma\user\rma\classes (M: for Classic)
For Linux agent: /opt/toshiba/rma/user/rma/classes
2. Copy rma-ea-ssl.properties which was modified in steps 6 through 8 to the
classes directory and name the copy ssl.properties.
3. Restart the RMA agent to encrypt the password. Refer to Appendix A, Stopping and
starting RMA Director RES on page 375 for how to stop/start RMA agents.
Note: The Custom_PW password will be encrypted in ssl.properties when RMA
starts.
4. Rename ssl.properties to rma-ea-ssl.properties, then move the file to the
EA-tmp directory, overwriting the version of rma-ea-ssl.properties with the
unencrypted passwords in that directory.
5. Restore the original version of ssl.properties in the classes directory which was
saved in step 9a.

10. Create a jar file named EA-SSL.jar with the contents of the EA-tmp directory:
<path>jar cvf EA-SSL.jar rma-ea-ssl.properties
On 4690 controller:
java2sdk:jar -cvf EA-SSL.jar rma-ea-ssl.properties
11. Save a copy of EA-SSL.jar to use later in “Deploying new custom SSL related files to RMA
Agents” on page 137.
Creating res-ssl.jar with new custom SSL related files

The new keystore and truststore files with the new certificate and updated (or new)
userssl.properties file must be in the res-ssl.jar file on the Director server machine in
order to successfully launch the RMA Store Manager and Package Manager from the IBM
Systems Director web interface on a remote machine.
1. On the Director server, copy the following file saved in step 11 of “Create override SSL
properties file with new custom filenames and password” on page 131 to the classes folder
and name the copy userssl.properties:
For Windows Director: userssl.properties.WinDirector
For Linux Director: userssl.properties.LinuxDirector
Note: Refer to step 2 of “Creating new custom keystore and truststore files” on page 128 for
the location of the classes folder.
2. Create a temporary folder on the Director server named res-ssl-tmp.
3. Copy the following files into the res-ssl-tmp folder.
1. The New_Custom_Keystore and New_Custom_Truststore files from the security folder
2. The default ssl.properties file from the classes folder
3. The userssl.properties file from the classes folder
Note: The path to the classes folder is shown in step 2 of “Creating new custom
keystore and truststore files” on page 128. The path to the security folder is shown in
step 3 of the same section.
4. In the res-ssl-tmp folder, edit userssl.properties and modify the following
properties to replace the path with the asterisk character as shown below.
SSL.ServerKeyFileName=*New_Custom_Keystore
SSL.KeyFileName=*New_Custom_Keystore
SSL.ServerTrustFileName=*New_Custom_Truststore
SSL.TrustFileName=*New_Custom_Truststore
5. Create a res-ssl.jar file by issuing the following command from the res-ssl-tmp
folder:
For Director server on Windows: "%dir_home%\db2\java\jdk\bin\jar" -cvf res-
ssl.jar New_Custom_Keystore New_Custom_Truststore userssl.properties
ssl.properties
For Director server on Linux: /opt/ibm/director/db2/java/jdk64/bin/jar -cvf
res-ssl.jar New_Custom_Keystore New_Custom_Truststore
userssl.properties ssl.properties

6. Copy the new res-ssl.jar file into following directory in place of the original one:
For Windows Director: %res_home%\jars
For Linux Director: /opt/toshiba/res/jars
7. Save a backup copy of the new unsigned res-ssl.jar file.
In the future when RMA is upgraded, the backup copy will be needed to restore the custom
version of res-ssl.jar since res-ssl.jar is overwritten during an upgrade of the
Retail Enterprise Service.
8. Sign the res-ssl.jar file by issuing the following command from the res-ssl-tmp
folder:
For Director server on Windows: "%dir_home%\db2\java\jdk\bin\jarsigner" -
keystore New_Custom_Keystore -keypass Custom_PW -storepass Custom_PW
res-ssl.jar rss
For Director server on Linux: /opt/ibm/director/db2/java/jdk64/bin/jarsigner
-keystore New_Custom_Keystore -keypass Custom_PW -storepass
Custom_PW res-ssl.jar rss
Note: To verify the jar is signed, you can run: <path>jarsigner -verify res-
ssl.jar
9. Save a backup copy of the new signed res-ssl.jar file.
In the future when RMA is upgraded, the backup copy will be needed to restore the custom
version of res-ssl.jar in the three jar files that are overwritten during an upgrade of the
Retail Extensions for Director.
10. Create a "lib" folder in the plugins folder shown below and copy the signed res-ssl.jar
from the res-ssl-tmp folder to the lib folder:
For Windows Director: %dir_home%\Retail\eclipse\plugins\
For Linux Director: /opt/ibm/director/Retail/eclipse/plugins/
11. Save a backup copy of the following jar files in the plugins folder:
com.ibm.retail.isd.console.checjmx.lic.task_3.2.2.jar
com.ibm.retail.isd.console.resconfig.lic_3.2.2.jar
com.ibm.retail.isd.console.swpkgmgr.lic_3.2.2.jar
12. The signed res-ssl.jar must be placed into the above jar files in place of the existing
res-ssl.jar in the lib folder of each jar by running the following command from the
plugins directory:
<path>jar uf com.ibm.retail.isd.console.checjmx.lic.task_3.2.2.jar lib/res-ssl.jar

<path>jar uf com.ibm.retail.isd.console.resconfig.lic_3.2.2.jar lib/res-ssl.jar
<path>jar uf com.ibm.retail.isd.console.swpkgmgr.lic_3.2.2.jar lib/res-ssl.jar
Where <path> is the following:

On Windows Director: %DIR_HOME%\db2\java\jdk\bin\
On Linux Director: /opt/ibm/director/db2/java/jdk64/bin/
Note: Please stop the IBM System Director before executing above commands.
13. Restart the Retail Enterprise Service on the Director server. Refer to Appendix A, Stopping
and starting RMA Director RES on page 375 for how to stop/start the service.
14. Restart the IBM Systems Director service. Refer to Appendix A, Stopping and starting RMA
Director RES on page 375 for how to stop/start the service.
15. Verify all stores are still online in Director and inventory can be successfully collected for an
RMA agent in any store.

16. Verify that the RMA Store Manager can be successfully started, then close RMA Store
Manager.
17. Delete the temporary res-ssl-tmp directory.
Deploying new custom SSL related files to RMA Agents

The new keystore and truststore files with the new certificate, the new userssl.properties, and the
modified simgmt.jar, must be put on each system in the enterprise network. The files can be
deployed using manual steps or using software distribution packages.
Deploying using manual steps

1. Copy the New_Custom_Keystore and New_Custom_Truststore files to the following location on
the agents:
For Windows agents: %RMA_HOME%\user\rma\security
For 4690 controllers: C:\adx_idt1
For Linux agents: /opt/toshiba/rma/user/rma/security
Note: For 4690, the files can be copied to the 4690 Master controller then distributed to the
other controllers using the adxcsu0l command.
2. Copy each userssl.properties.<platform> file that was saved in step 11 of “Create
override SSL properties file with new custom filenames and password” on page 131 to each
RMA agent the files apply to and rename to userssl.properties at the following
location on the agent:
For Windows agents: %RMA_HOME%\user\rma\classes
For 4690 Enhanced controllers: F:\rma\user\rma\classes
For 4690 Classic controllers: M:\rma\user\rma\classes
For Linux agents: /opt/toshiba/rma/user/rma/classes
Note: If steps 2 through 12 of “Create override SSL properties file with new custom
filenames and password” on page 131 was skipped, then userssl.properties did not
require changes, therefore, this step can be skipped.
3. Restart RMA on the Master Agents. Refer to Appendix A, Stopping and starting RMA
Director RES on page 375 for how to restart agents.
4. Once the Master Agents have restarted, then restart RMA on the General Agents. Refer to
Appendix A, Stopping and starting RMA Director RES on page 375 for how to restart
agents.
Deploying using Software Distribution packages

Note: If steps 2 through 12 of “Create override SSL properties file with new custom filenames
and password” on page 131 was skipped, then userssl.properties did not require changes,
therefore, you can skip the parts of the instructions below related to userssl.properties.
1. Start RES Software Package Manager. Refer to “Software distribution” on page 22 for how
to start and use the RES Software Package Manager.

2. Create a separate software distribution package for each of the following type of agents
applicable to your enterprise:
• Windows agents
• 4690 Enhanced controllers
• 4690 Classic controllers
• Linux agents
3. Enter the following location in the "Installation Destination" field:
For Windows agents: C:\Program Files\Toshiba\rma\user\rma\security
For 4690 controllers: C:\adx_idt1
For Linux agents: /opt/toshiba/rma/user/rma/security
Note: The Window path above assumes a default location for the RMA agent installations.
Enter the actual installed location in the path if different from the default, or if installed on
Windows 2012 which has the default installation location of c:/Program Files (x86)/
Toshiba/rma.
4. Put the following files in each package.
• New_Custom_Keystore
• New_Custom_Truststore
• userssl.properties - the file for a Windows or Linux package which is a renamed
copy of the userssl.properties.<platform> file saved in step 11 of “Create
override SSL properties file with new custom filenames and password” on page 131
• userssl.pro - the file for a 4690 package which is a renamed copy of the
userssl.properties.4690 file saved in step 11 of “Create override SSL properties
file with new custom filenames and password” on page 131
5. For a Windows or Linux package:
1. Add a command in the package to move userssl.properties from the location of
the package Installation Destination shown in step 3 above to the following location:
For Windows agents: %RMA_HOME%\user\rma\classes
For Linux agents: /opt/toshiba/rma/user/rma/classes
Example for a Windows package:
Path: cmd.exe
Arguments: /c move /Y "%RMA_HOME%\user\rma\security
\userssl.properties" "%RMA_HOME%\user\rma\classes"
6. For a 4690 package for Enhanced controllers or Classic controllers:
1. Create a 4690 batch file to include a command to move userssl.pro from c:
\adx_idt1 to the following location with the name changed to
userssl.properties:
For 4690 Enhanced controllers: F:\rma\user\rma\classes
For 4690 Classic controllers: M:\ rma\user\rma\classes
Note: A current 4690 limitation with RCP does not allow adding a command to the
package to do rename or copy with the above path specified.
2. Add the batch file to the 4690 package.
3. Add a command to the package to run the batch file for any 4690 controller.
7. Select Post Distribution action to reboot when distribution of the package is finished.
8. Acquire the packages in Director. Refer to “Using Update Manager” on page 326.

9. Use Update Manager (on the IBM Systems Director web interface, select Release
Management > Update) to install the applicable packages to the Master Agents.
10. Once the Master Agents are updated, use Update Manager to install the applicable packages
to the General Agents.
For RMA remote embedded agents:
The new RMA SSL certificate must be used by the remote embedded agents to successfully
communicate with the RMA Master Agent. The location to deploy EA-SSL.jar that was saved in
step 11 of “Create jar file for remote embedded agents with new custom SSL related files” on
page 133 depends on the type of application that starts the embedded agent.
1. For 4690 terminals with an RMA remote embedded agent:
1. Copy EA-SSL.jar to the same location on the 4690 controllers where simgmt.jar is
loaded from. The location may be in a 4690 preload bundle.
2. For a Store Integrator application, rename EA-SSL.jar to a jar filename that is in the
current classpath, for example, siuser.jar, which is not currently being used, or
merge the files from EA-SSL.jar into a file like siuser.jar. Otherwise, add EA-SSL.jar
to the application classpath in 4690 Terminal Configuration and activate Terminal
Configuration.
3. If a 4690 preload bundle was changed, then run adxpldrb to rebuild the preload
bundles, and run adxrtccl to rebuild the terminal load-shrink file.
4. Reload the 4690 terminals with embedded agents.
2. For each Window or Linux system with an RMA remote embedded agent:
1. Copy EA-SSL.jar that was saved in step 11 of “Create override SSL properties file with
new custom filenames and password” on page 131 to the same location as
simgmt.jar.
2. Add EA-SSL.jar to the application classpath.
3. Restart the application to restart the embedded agent on each system with an RMA remote
embedded agent.
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 %RMA_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 %RMA_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:
• Windows: %RMA_HOME%\mgmt_log.pro
• 4690 Classic: M:\rma\lib\mgmt_log.pro
• 4690 Enhanced: F:\rma\lib\mgmt_log.pro
• Linux: /opt/toshiba/rma/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 %RMA_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 the Java 1.4.2
Documentation found at http://www.oracle.com/technetwork/java/archive-139210.html
diagrams this hierarchy.
Figure 110. 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 110, 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 in Figure 110, 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 12 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, FINER, and FINEST, accordingly.
Note: The Java logging levels are used when setting up the logging configuration files.
Table 12. 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.
When a SEVERE error has occurred, RMA will
Note: Push level will trigger on that level and most likely not be functioning properly.
above (for example, SEVERE would 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.

Java logging level (Commons-Logging level) Description
FINE (DEBUG) Debug level of logging used for determining

the cause of more serious errors by evaluating
This is the default configured logging level for the events leading up to the error.
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. 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 %RMA_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 13. Configurable logging parameters

Property Description
com.ibm.retail.si.mgmt.logging.RMALogHandle Pattern (file name and path) used for the output
r.pattern memory logging file
Default:
• %RMA_HOME%/logs/rma_m on Windows
• f:/rma/logs/simgmt_m on 4690 Enhanced
• m:/rma/logs/simgmt_m on 4690 Classic
• /opt/toshiba/rma/silogs/simgmt_m on
Linux
com.ibm.retail.si.mgmt.logging.RMALogHandle File size limit in bytes (size of file before wrapping

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

r.count purging oldest file)

Property Description
Default: 10
Minimum: 1
Maximum: ? (disk-dependent)
com.ibm.retail.si.mgmt.logging.RMALogHandle Default logging output formatter (file that formats

r.formatter logging data; in almost all cases leave this as the
default)
Default:
com.ibm.retail.si.mgmt.logging.RMALogFormatter
com.ibm.retail.si.mgmt.logging.RMALogHandle Logging output level (defined using Java logging

r.level levels)
Default: ALL
Valid values: OFF, SEVERE, WARNING,
INFO, FINE, FINER, FINEST, ALL
com.ibm.retail.si.mgmt.logging.RMALogHandle Number of log records to keep in memory buffer

r.size (15000 records was approximately 4.5 MB in
testing)
Default: 15000
Minimum: 1
Maximum: ? (memory-dependent)
com.ibm.retail.si.mgmt.logging.RMALogHandle Trigger level at which to write logs (defined using

r.push 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:
• 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

• Changes made to the configuration can be persisted through calls to operations on this
MBean.
• 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:
• Windows: %RMA_HOME%\user\rma\config\startup
• Linux: /opt/toshiba/rma/user/rma/config/startup
• 4690 Classic: M:\rma\user\rma\config\startup
• 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 Toshiba 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 %RMA_HOME%/
user/rma/config/roles directory. In order to add additional roles, XML files containing
information about the new roles needs to be added to the %RMA_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 Systems 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.
The agent configuration file

At startup, the RMA service looks in the %RMA_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 Systems 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 14 shows the tags and attributes supported by the configuration file.
Table 14. 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)
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.

XML tag Attributes
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.
Note:
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:
• A value of ERROR indicates that Error-level events will create an RtlNotification in RMA.
• A value of WARNING indicates that Warning-level events will create an RtlNotification in
RMA.
• A value of INFO indicates that Information-level events will create an RtlNotification in
RMA.
• If SUCCESS AUDIT is included in the string, then those events will create an RtlNotification
in RMA.
• If FAILURE AUDIT is included in the string, then those events will create an RtlNotification
in RMA.
• 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 Systems 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 15 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 15. Mapping Windows event log definitions to RMA Notifications

Windows event log record field RMA Notification field
TimeGenerated TimeStamp

Windows event log record field RMA Notification field
EventQualifiers
LogType
SourceName
EventCategory
EventType NotificationType
Strings MessageText
Data UserData
ComputerNameDeviceID of the GA that OriginatingDevice
originates the log
The Event Type is mapped using the scheme in Table 16. Note that the RMA Notification type is
the go between bridging the Windows event log event type to the IBM Systems Director severity,
which is why the configuration parameter is expressed in terms of the IBM Systems Director
severity level.
Table 16. Event type to severity mapping

IBM
Systems
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 111 is the properties view of a sample Windows Application event:

Figure 111. 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 Systems Director event log for the system that
originated the event:

Figure 112. Sample Windows Application event viewed in IBM Systems Director
Phone Home configuration file

RMA V3 R1.2 has a feature that will enable the Master Agent to be automatically discovered in
the Store Manager user interface (UI). User's will not be required to explicitly add a store entry
in the Store Manager UI. Create a phonehome.properties file in the %RMA_HOME%\user
\rma\config\phonehome directory. This file can be created by making a copy of the
phonehome.properties.sample file, which is in the %RMA_HOME%\user\rma\config
\phonehome directory, and renaming it. The phonehome.properties file will have the
information required about the Retail Enterprise Service (RES) server for the store to be
discovered. The attributes remoteIPAdress and entryName should be verified and edited, if
required, as discussed below. The remotePort attribute should not be edited. The value 10521 is
the correct discovery port. The eventFilterFlag may be changed.
See the following format for the Phonehome.properties configuration file:
remoteIPAddress=<IP address of RES>

remotePort=<port>
entryName=<storeName>
eventFilterFlag=<numeric eventFilterFlag>
where
remoteIPAddress:The IP address of the server where Retail Enterprise Service is
running. If this IP is changed at a later time to point to a different RES Server,
then the store entry in the previous RES Server will not automatically be deleted
from the Store Manager UI. If the entry in previous RES server is no longer needed,
then it needs to be explicitly deleted.
remotePort: The port on which the RES is listening for a phone home connection.
Default value is 10521 entryName: It is the name of the store as the user wants it
to appear on the Store Manager UI in the "Entry Name" column. The Store Manager UI
will display the name in the format "storeName-<StoreID> (Auto)" where storeName is
as given in the configuration file, <storeID> denotes the store identifier as given
in the agent configuration file rmauser.properties. If no name is
specified, then the entry will be of the form <Store IPaddress>-<StoreID> (Auto)
where <Store IPaddress> denotes the IP address of the store.

eventFilterFlag: The event filter flag can be one value from the different filter
values that can be specified in Store Manager UI. Below are the numeric values for
the event filter flags that can be set.
Fatal : 3
Fatal, Critical: 15
Fatal, Critical, Minor: 31 (This is the default filter value in UI)
Fatal, Critical, Minor, Warning: 127
Fatal, Critical, Minor, Warning, Harmless: 1023
All: 2047
This is one time configuration which will be read every time the master agent is restarted. The
Master Agent will retry every 30 minutes to ensure that the entry in the Store Manager UI gets
recreated if it is accidentally removed. If the store entry is to be permanently removed from the
Store Manager UI then, the phonehome.properties file needs to be removed from the
configuration directory along with deletion of the store entry in the UI. The reconnect interval
can be overridden by adding following entry to the agent configuration file
(rmauser.properties)
com.ibm.retail.rma.phome.newClientReconnectFrequency=<XX><s/m/h/d>, where
XX represents the numeric value and s/m/h/d represents the time unit - second/minute/hour/day.
Any invalid value to this property will be ignored and the default interval of 30 minutes will be
used.

Chapter 14. Retail Enterprise Service
Retail Enterprise Service
The Retail Enterprise Service is a supporting background service that provides access to all RMA
resources in the enterprise. RES establishes and maintains communications with each RMA
Master Agent, and hides the details of other functions like event transport and software
distribution. Management applications can interact with the resources in each store using the
high level services provided by RES. IBM Systems Director 6 with Retail Extensions is an
example of a management application that utilizes RES. Figure 113 includes an illustration of
this architecture.
Figure 113. Retail Enterprise Service architecture
The RMA Store Manager

The RMA Store Manager must be configured with the connection information of each RMA
Master Agent it connects to. The RMA Store Manager is the means by which the connection
information used by RES can be modified. The RMA Store Manager is similar to the Retail
Discovery Preferences tab in the Retail Extensions for IBM Director 5.20. Using the RMA Store
Manager, you can do the following:
• Import and Export of multiple store connection data.
• Edit one or more connection entries (IP Address, Port, Name, and Event (Severity) Filter).
• Remove one or more connection entries.
• View the connection log of a single connection.
• Re-connect to one or more store connections.
• Authenticate one or more stores.
• Manage Log Captures
The RMA Store Manager can be launched in one of the following ways:
• Locally on the Director Server System
• From within the Director Console using Java WebStart

Launching RMA Store Manager using Java WebStart
To launch the RMA Store Manager using Java WebStart, complete the following steps:
Note: If not already installed, install a JRE that supports Java WebStart on the system before
proceeding.
1. After Installing RES on Director Server, launch the Director UI from the remote system and
click on Resource Explorer > Retail Groups > All RES Systems. Right-click the RES MEP
discovered in the Director UI, and then click System Configuration > Launch RMA Store
Manager. The Launch RMA Store Manager window is displayed (see Figure 114).
Figure 114. Launch RMA Store Manager

2. Select the check box at the Do this automatically for files like this from now on prompt.

Figure 115. Launching RES Config US Java Webstart window
3. Click OK and the Java launch window is displayed.
Depending on your system, you will be prompted with one of the following windows:
• If you are prompted with the Warning - Hostname Mismatch window, click Run.
Figure 116. "Warning - Hostname Mismatch" window

• If you are prompted with the Security Warning window, select the checkbox for Always
trust content from this publisher and click Yes.
Chapter 14. Retail Enterprise Service 155

Figure 117. Security Warning window
4. After processing, the Security Information window is displayed. Select the checkbox for
Always trust content from this publisher and click Run. The Launching Task window is
displayed with the Cancel Request button enabled.
Figure 118. "Security Information window

5. If you click Cancel Request, the Launching RMA Store Manager task is cancelled (see
Figure 119).

Figure 119. "Launching Task window
• If you are prompted with the Warning - Hostname Mismatch window (see Figure 116),
click Run and the Verifying Application window is displayed (see Figure 120).
• If you are prompted with the Security Warning window (see Figure 117), select the
checkbox for Always trust content from this publisher and click Yes and the Verifying
Application window is displayed (see Figure 120).
Figure 120. Verifying Application window

6. If you attempt to launch the RMA Store Manager UI from a different machine than where
the RES is installed (via browser), you will be prompted for authorization credentials. After
you provide valid credentials, the RMA Store Manager UI is displayed.
Note: If a new user is added with administrative privileges and also to RESAdmin and
SMAdmin groups on a RHEL server, RES service needs to be restarted before this user can
be used to authorize RES.
7. The RMA Store Manager launches and displays the List of Store Master agent configured.
The below figure shows the RMA Store Manager which doesn't have any Stores configured.

Figure 121. RMA Store Manager window
Troubleshooting launch in context tasks

The IBM Systems Director publications provide solutions to many common problems related to
launching Java Web Start tasks. See the following website for troubleshooting information:
publib.boulder.ibm.com/infocenter/director/pubs/topic/com.ibm.director.tbs.helps.doc/
fqm0_r_tbs_lic_launch_in_context.html
When your Director Server has multiple IP addresses (which will more than likely be the case),
you might encounter errors indicating that a file cannot be found when you try to launch a Java
Web Start Task. If the error has to do with the website using a private IP address, then you might
need to configure Director to supply a hostname or a public IP address for the website. To
configure Director, complete the following steps:
Note: If you have already configured IP address of server for some IBM system director version
using above step, then upgraded the IBM system director to higher version, to launch web Start
successfully you need to update the lic.properties of upgraded director in following path:
director\lwi\runtime\USMiConsole\eclipse\plugins
\com.ibm.usmi.console.lic_<NEW VERION>\ WEB-INF\classes.
1. In the director\lwi\runtime\USMiConsole\eclipse\plugins
\com.ibm.usmi.console.lic_<VERSION>\WEB-INF\classes directory, edit
lic.properties. Add or change the property serverIPAddress to be the hostname or IP,
(that is, serverIPAddress=192.168.1.2).
2. Click Save.
3. Restart IBM Systems Director.

Application Blocked by Security Settings
On some versions of JRE, the below exception will be thrown when launching RMA Store
Manager or RES Software Package Manager from Director console.
Figure 122. Application blocked by security setting
The workaround for this error is given in the https://www.java.com/en/download/help/

java_blocked.xml Java website.
JNLP workaround for Linux/JWS/Firefox

For a JNLP workaround for Linux, JWS, or Firefox, complete the following steps.
1. Install the Java plugin for Firefox.
2. Manually create the association in Firefox for JNLP files:
1. Create a .jnlp file on the Linux browser/client system and name it test.jnlp.
2. In Firefox, click File > Open and browse to the test.jnlp file.
3. When Firefox prompts you to open the .jnlp file, browse to the location of javaws
(/usr/java/latest/bin/javaws).
4. Optionally, view the checkbox to remember the answer and save the response. After
doing this, the JNLP association will appear in Preferences > Applications. Launching
the Director task will then work.
Launching RMA Store Manager from a command prompt

To launch RMA Store Manager from the command prompt, complete the following steps:
1. In the Director server where RES is installed, click Start -> Run.
2. Enter cmd in the prompt and click OK.
3. Navigate to the path RES_HOME\bin and type rmaStoreManager.bat.
4. Click Enter. The RMA Store Manager is launched with the Store Connection Information
tab selected and the Command prompt running in the background with the launch details.

Figure 123. Command prompt with the launch details
Using the RMA Store Manager

The following sections describe the features and functionality of the RMA Store Manager User
Interface (UI).
Adding Store Connection entries

To add store connection entries, complete the following steps:
1. To add Store entries in RMA Store Manager, click Connection -> Add Entry.
Figure 124. RMA Store Manager - Add Entry command

2. Enter a unique and valid Store Name in the Define Master Agent pane.
Figure 125. Define Master Agent pane

3. Enter a unique and valid hostname or IP ddress of the Store to be added.
Figure 126. Hostname field

Figure 127. IP address field
4. Enter a valid port number or retain the default port number populated in the Port Number
field.
Figure 128. Port number field

5. From the drop-down menu of Event Filter, select the category of Events that you want to see
in the Director UI.
Figure 129. Event filter drop-down menu

6. After you have completed all the required fields, click OK to add this Store in the Store
Connection Information tab of RMA Store Manager.

Figure 130. Store Connection Information window
Viewing the status of Store Connections

1. The initial connection status of a newly created store connection will be Undiscovered with
a red diamond indicator.
Figure 131. Initial Connection status pane

2. Click View -> Refresh to check the status of the Store entry.
Figure 132. Store entry status
Each connection status is updated automatically whenever it changes. The status will be one
of the following:
• Stores in Standard Security Mode - Connected Green Circle.
• Stores in Enhanced Security Mode - Unauthenticated Yellow Inverted Triangle.

• Already discovered Store in RES - Duplicate Entry Yellow Inverted Triangle.
• Connection to Store broke - Disconnected Red Diamond. If store was discovered/
connected before and for some reason connection to store is broken, the store status will
be shown as Disconnected. Some reasons for store connection going down may be
1. RMA agent service is down.
2. System is down/In Rebooting process.
A count of the Stores Selected and Connected is seen in the Status Bar. After adding a new
connection entry, the connection status will change to a connected state any where from
immediately to 5 minutes, depending on whether or not the Master Agent is running. When
connections enter the disconnected state (when Master Agents are restarted, for example),
they will go to the connected state within 30 seconds of a Master Agent restarting.
Figure 133. Store Connection Information status bar window
Authorizing Store Connections

The following section
1. The Authorize Store option is only available for the Stores in Unauthenticated State. To
authorize the Stores in Unauthenticated State (Enhanced Security mode), select the Store
entry and click Connection ->Authorize Stores. You can also authorize multiple Stores with
the same user name and password at the same time by selecting the Store entries and
clicking Connection -> Authorize Stores.

Figure 134. Authorizing a Store in unauthenticated state
2. For single or multiple store authorization, the Store Authorization Management pane is
displayed. Enter a valid user name and password to authorize the Stores and click OK.
Figure 135. Authorizing single or multiple stores

3. The Store Authorization Management pane is displayed with Entry Name and
Authorization Status columns for the respective Store entries selected. After authorization,
status messages will be shown for the Stores entries. Click ESC.

Figure 136. Store Authorization Management window
4. The connection status in the Store Connection Information tab will be updated
respectively. For those stores whose Authorization is successful, the status will be changed
to Connected. For the Stores whose Authorization status is not successful, they would be
retained in the Unauthenticated state.
Figure 137. Store Connection status window
Editing Store Connection entries

To edit store connection entries, complete the following steps.
1. To edit a store entry or multiple stores, select the Store entry or entries and click
Connection-> Edit Entry.
2. Edit Store Name, Hostname, IP Address and Port Number to restart the connection to the
Store. Edit the Event Filter to refresh the Store Entry.
3. Only Port Number and Event Filter can be changed while editing multiple stores.
a. To edit the Port Number for multiple stores, select the stores and click Connection-
>Edit Multiple Entries->Edit Port.

Figure 138. Edit Port command
b. To edit the Event Filter for multiple stores, select the stores and click Connection->Edit
Multiple Entries-> Edit Event Filter.
Figure 139. Edit Port command with filters

4. To restart connection to any Store, click Connection -> Reconnect. The Reconnect option is
applicable for single or multiple stores.
Figure 140. Restarting connection to any Store

Connection status of the Store will be set to a Disconnected state. After the Reconnect is
done, the status will be set to Connected.
Table 17. Connection status pane
Searching for Store Connections

The following sections describe how to search for store connections.
1. To find a specific Store entry in the list of store entries, click Edit -> Find and the Find
Master Agent pane is displayed.
Figure 141. Finding a specific store in the Store Connection Information tab
• To Find by Entry Name, select the Entry Name radio button and enter the valid entry
name and click Find.
Figure 142. Find a store by Entry Name

• To Find by hostname or IP Address, select the Hostname/IP Address radio button, enter
the valid Hostname, or IP Address and click Find.
Figure 143. Finding a store by Hostname/IP Address

• The Find Stores pane is displayed with a message stating how many stores were found
and the respective stores are highlighted.
2. Click OK to close the Find Store Pane.
Figure 144. Close the Find Store Pane

3. To select all the Store entries at one time, click Edit -> Select All.

Figure 145. Select all the Store entries at one time
Exporting Store Connection entries

The following section describes how to export Store entries.
1. To Export the Store entries, select all of the Store entries and click File -> Export.
Figure 146. Exporting Store entries
The Export Master Agent List pane is displayed. Select a location, enter a valid name to save
the list and click Save. The Export Master Agent List pane shows that the Store entries are
exported successfully with details of the location saved. Click OK to close the Export Master
Agent List pane.
Figure 147. Exported Store entry confirmation window

2. To deselect all the selected store entries, click Edit -> Deselect All.

Figure 148. Deselecting all Store entries
3. To remove single or multiple store entries from the RMA Store Manager, select those store
entries to be removed and click Connection -> Remove Entry.
Figure 149. Removing Store entries
The Remove Master Agent pane is displayed with a prompt to confirm the deletion of the
store entry. Click Yes to delete the store entry.
Figure 150. Removing Store entries confirmation window

Importing Store Connection entries
The following section describes how to import Store connection entries.
1. To import the Store entries in RMA Store Manager -> Store Connection Information, click
File -> Import.
Figure 151. Importing Store entries
The Import Master Agent List pane is displayed. Navigate to the location where the list is
saved. Select the list and click Open.
Figure 152. Import Master Agent List window
The Import Master Agent List is displayed and shows the store entries are imported
successfully from the selected location. Click OK.

Figure 153. Stores Imported Successfully
Diagnosing Connection Issues from the RMA Store Manager

If your newly added stores are not appearing in the IBM System Director console after running
Discovery, then there is a good chance that the IBM System Director Server at the enterprise
cannot connect to the Master Agent running on a system within a store.
To help diagnose these problems, a Connection Log is maintained for each store connection. To
view the connection log for a store entry, select the Store entry in the RMA Store Manager and
click View ---> Connection Log:
Figure 154. Connection Log window
The "Connection Log" will display connection specific history information for that store entry.
Messages here can indicate problems such as issues resolving the hostname, firewall issues, or
configuration problems. If you need to contact a support representative about a connection issue,
submit the Connection Log information.

Figure 155. Connection Log Window
Managing data captures

The RMA Master and General agents provide the capability of collection and transfer of
diagnostic data/log captures. When data is collected on a GA endpoint, the data is transferred to
the MA where it is saved in the %RMA_HOME%\user\rma\data\capture\completed folder.
When data is collected on the MA, it is also saved in this directory.
Viewing data captures

Data capture files stored on the Master Agent (MA) at %RMA_HOME%\user\rma\data
\capture\completed can be viewed from the RMA Store Manager UI. Store Manager
provides the capability through the Manage Log Captures function to transfer data collection
files from one or more MAs and view that data in Store Manager.

Figure 156. Viewing data capture window (1 of 3)
Click this menu item to display the details of the completed captures from each of the selected
stores as shown in Figure 157.
If any of the selected stores are not in the 'Connected' state, a message window is displayed as
shown in Figure 158.

For V2R6 agents the timestamp used in the data capture filename is the UTC time. For V3 agents,
the data capture filename will contain the time and timezone of the agent where capture is
generated. The Data Capture Occurred column in the Log Captures UI converts the time, which
is part of the capture file name, to the corresponding local time of the RMA Store Manager
remote session..
Deleting the data capture manually from MA under location %RMA_HOME%\user\rma\data
\capture\completed will still show the capture in Store Manager for the specific Store since
the data capture lists are retrieved from the DCH_*.xml file from directory %RMA_HOME%\user
\rma\config\capture in MA. These captures can be deleted from the UI using the Delete
Capture From Store option from the Edit menu of the Log Captures window.
Saving data captures

Data capture files, stored on the Master Agent (MA) in %RMA_HOME%\user\rma\data
\capture\completed, can be transferred and saved to a user-specified location on the local
file system (from where you launched the store RMA Store Manager). Selecting the RMA Store
Manager -->View-> Manage Log Captures displays the Log Captures window. The Log
Captures window lists the captured data files from the MAs select on the RMA Store Manager
window and provides the means to Save them to a user-specified location on the local file
system.
To do this perform one of the following:
1. Select one or multiple captured data files, right click, and select Save Data Capture.
2. Select one or multiple captured data files. From the Log Captures menu select File then
select Save Data Capture.

Figure 159. Saving data capture window (1 of 4)
Selecting Save Data Capture creates a pop-up window for you to select a location for saving the
log captures. Select a location, then click Save. See Figure 160.
After you select the location for saving, a progress window displays showing the transfer
progress Figure 161.

Note: The progress bar is calibrated on the total number of files to be transferred from the
Master Agent to the local file system (from where the user has launched the store Manager UI),
not on the size of the file to be transferred. When the Single File transfer is selected at the start of
the transfer, a progress bar displays and is completed when the file is transferred completely.
Once the data capture file is transferred successfully from the MA to the user-specified location
on the local system, a status window is shown that summarizes the status for the file transfer for
each of the files you have selected.

Cancelling the data capture transfers
Cancelling the data capture transfers is supported. Users can cancel the data Capture transfer at
any point of time. The ongoing file transfer, if any, will be aborted and will therefore fail. If any
other data capture file transfers are pending, they will be cancelled.
When all data captures are completed, the Transfer result window displays summarizing the
data capture file transfer for all the files.
Figure 163. Cancelling data capture transfer window
Deleting the data capture bundles

The completed capture bundles are stored on the Master Agent at RMA_HOME%\user\rma
\data\capture\completed and can be deleted from the Master Agent using the Delete
Capture From Store command on the Edit menu of the Log Captures window.

Figure 164. Deleting capture bundles window (1 of 2)
The status and progress of the capture bundles being deleted displays a pop-up window as
shown Figure 165.
Figure 165. Deleting capture bundles window (2 of 2)
When the capture bundles have been successfully been deleted, the capture list is updated
accordingly.

Chapter 15. RMA and IBM Systems Director basics
RMA and IBM Systems Director basics
This chapter will provide the basics of IBM Systems Director Server 6 (IBM Systems Director),
along with some of the core features of RMA 3.2.2 and IBM Systems Director that will be used
throughout this book. For example, we introduce core concepts such as managed end points and
groups, and discuss how to use:
• Retail Agents Discovery, Authorization to Stores
• Collecting inventory on agents
• Viewing and managing events from agents
Introduction to RMA and IBM Systems Director basics

What is a managed end point?
A managed end point (MEP) is a Director object that represents a remote manageable entity—
for retail systems there are MEPs for:
• Each store
• Each RMA Service Agent (General or Master)
• Each RMA Remote Mode Embedded Agent
Access states of managed end points in IBM Systems Director

The following are access states of the managed end points (MEPs) in IBM Systems Director.
Access State: OK:
Figure 166. Access State: OK
The MEP is online and accessible to users.

Access State: No Access
Figure 167. Access State: No Access
This state is applicable only to retail store MEPs. Enter your user name and password to access
and view properties, and to perform operations on retail stores.
Access State: Offline
Figure 168. Access State: Offline
The MEP is in a disconnected or offline state.

Access State: Unknown
Figure 169. Access State: Unknown

An unexpected error occurred and the MEP is in an unknown state.
Resources
Although this chapter provides "survival skills" for using IBM Systems Director and RMA, it is
not a replacement for the existing documentation for these products.
For more comprehensive information, see IBM Systems Director 6.3 Best Practices: Installation and
Configuration on http://www.redbooks.ibm.com/abstracts/redp4932.html?Open.
Using the IBM Systems Director Console

Use the following information for the IBM Systems Director Console (Director Console).
Logging into the Director Console

After "Installing the RMA Retail Extensions for the IBM Systems Director Server", launch the
IBM Systems Director Console:
1. If the Director Console is launched on the system where IBM Systems Director Server is
installed, then go to: https://localhost:8422/ibm/console/logon.jsp
2. If the Director Console is launched on the system where the IBM Systems Director Server is
not installed, then go to: https://<SeverIP/Hostname>:8422/ibm/console/logon.jsp, where
ServerIP/Hostname is the IPAddress or hostname of the system where IBM Systems
Director is installed.
3. Enter a valid administration user name and password, and click Log in.

Figure 170. Admin user ID and password
Figure 171. IBM Systems Director home page
Chapter 15. RMA and IBM Systems Director basics 183

Resource Explorer
Use the following steps to access Resource Explorer.
1. Click the Resource Explorer tab (next to the Home tab) or use the Resource Explorer web
address in the left pane, on the login home page of the IBM Systems Director.
Figure 172. Resource Explorer tab

2. When you select Resource Explorer from the menu in the left pane, the right pane lists all
the different groups available.
Figure 173. Resource Explorer menu

3. Click on each of the groups to show the list of all the managed end points in the group, see
Figure 174.

Figure 174. Managed end points groups
There are two kinds of groups that are important for our purposes:
• Static groups - The members of the group must be explicitly added or removed from the
group.
• Dynamic groups - Group membership is based on configurable criteria. Managed end points
are automatically added to dynamic groups if their inventory data meets the defined criteria.
When RMA agents are discovered by IBM Systems Director, a number of predefined dynamic
groups become visible in the Director Console. See these predefined dynamic groups, also
known as Retail Groups, in the following figure:
Figure 175. Retail groups
Each of the Retail Groups listed may have subgroups within them organizing the RMA agents
based on various criteria.
Viewing Systems
See the following for viewing systems:
1. All the Retail-related systems can be seen under three main categories:

• All Retail Client Systems
• All Systems
• Retail Groups
Figure 176. Retail groups view

2. All the Retail Agents managed end points (MEPs) will be represented by the following icon:
Figure 177. Retail Agents MEPs icon

3. All store MEPs will be represented by the icon:
Figure 178. Store MEPs icon

4. RES MEP will be represented by the icon:
Figure 179. RES MEP icon

5. All Retail Client Systems: Click All Retail Client Systems in the Groups table. This group
has all of the retail agents listed.

Figure 180. All Retail Client Systems
• Name of the Agent MEP is defined by "StoreId.DeviceId". Device Id represents the host
name of the machine.The MEP agents corresponding Store ID will be prefixed with
Device ID.
• Every agent MEP has the reference of the store that it is tied to listed in the first column
"Retail Store ID".
• For all the Agent MEPs listed, the "Type" will be Generic.
• All the Agent MEPs will have their respective IP address listed under the IP Address
column.
6. All Systems: Lists all the systems that are discovered in Director -- All Retail Agents
(Type=Generic), Retail Enterprise Service MEP (Type=Generic), All Retail Stores
(Type=Retail Store) and Director native agents. Retail Store entries will have only "Store ID"
set as its name.
Figure 181. Lists of systems in Director

7. Retail Groups: Lists the grouping of the systems based on categories.

Figure 182. Lists of grouping by categories
• Each categorized group will have the respective agents listed under it.
• 4690 Controller groups have nested groups, subcategorizing 4690 Alternate Controllers,
4690 Master Controllers and All 4690 Controllers.
Figure 183. 4690 Controller Groups

• 4690 Terminals groups have nested groups, sub-categorizing 4690 Classic Terminals,
4690 Enhanced Terminals and All 4690 Terminals.
Figure 184. 4690 Terminal Groups

8. To view the Detailed states of any MEP, click on the MEP and the MEP Properties page
displays.
• Agent MEP Properties page ---> General Tab:

Figure 185. Agent MEP Properties page - General Tab
Agent MEP Properties page ---> Event Log Tab:
Figure 186. Agent MEP Properties page - Event Log Tab

• Agent MEP Properties page (post Inventory Collection) ---> Inventory Tab:

Figure 187. Agent MEP Properties page - Inventory Tab
Note: Once hardware is inventoried on a system, it will remain in the inventory

information even after the hardware is removed.
Custom groups - dynamic and static
Director Groups
Apart from the predefined groups listed under Resource Explorer, you can use IBM Systems
Director to organize logical sets of resources into Custom groups. These can be dynamic or static.
Creating a criteria-based dynamic group

Dynamic groups are based on specified system criteria. You can create a dynamic group by
specifying criteria that the attributes and properties of the systems must match. IBM Systems
Director automatically adds or removes systems to or from the group when their attributes and
properties change and affect their matches to the group criteria.
The criteria available for selection are derived from inventory. For example, you can quickly
group existing systems by creating a dynamic group using the criterion Windows operating
system.
To create a dynamic group, complete the following steps:
1. In the IBM Systems Director navigation area, click Resource Explorer and click Create
Group.

Figure 188. Create Group screen
2. In the Group Editor wizard, the Welcome page is displayed. Click Next. On the Name page,
type a unique descriptive name for the group that you are creating. Optionally, you also can
type a description of the group. Click Next. On the Type and Location page, select Dynamic
from the Group type list.
Figure 189. Group Type List - Dynamic

3. From the Member Type list, select the type of member that you want included in the group.
A member type acts like a filter. Only resources of the specified type can be part of the
group you are creating.
Any
Group membership is unlimited. Any resource can be in the group, including
systems, software, and management applications.
Managed System
Group membership is limited to system types such as different types of servers,
fabric, farms, hardware control points, controllers, operating systems, chassis,
switches, and storage.
Update
Group membership is limited to update types such as for firmware, IBM Systems
Director, and operating systems.
4. From the Location list, select the parent group to contain the group that you are creating. In
Resource Explorer, a parent group is created and is located under Personal Groups. Click
Next.
Table 18. Define page - Add Criterion

Define page - add criterion

Option Description
If you selected Any or Managed System The Define page is displayed. Continue to
the next step.
5. On the Define page, click Add. The Add Criterion window is displayed.
Figure 190. Define page - Add Criterion window

6. Following is the "Refine" criteria you can select.
Table 19. Refining Define page criteria

Refining Define page criteria
Option Description
If you selected Any: In the "Resource category", select the type of
resource with the criteria that you want to
evaluate.
If you selected Any: In the "Type of device to add", select the
device type to further refine the available
criteria.
If you selected Managed System: In the "Type of system to add list", select the
system type to further refine the available
criteria.
In the "Select criteria to refine group contents list", expand the tree and select a criterion for
the dynamic group to evaluate. Your selection is displayed below the list. Click Operators to
select how you want the criterion evaluated by the value you provide.
Click Value to select the value to use to evaluate the criterion. If you want to specify a
custom value, select Use from below and type the custom value in the field.
Note: Important: The custom value must match the value stored in the IBM Systems
Director Server database. Partial matches are not accepted. If the value does not match,
nothing is returned for this criterion.
Click OK. On the Define page, the criterion is displayed in the Criteria preview field.
Similarly, you can add additional criteria.
7. After adding another criterion, the Define page displays the logical AND and the logical OR
selections. These selections determine how the criterion that you create now will affect the
criterion you created previously.

Figure 191. Define page - displaying selections
If you want to change a criterion, select the criterion from the Criteria list and click Edit. The
Edit Criterion window is displayed with the settings for the selected criterion. Change the
settings and click OK.
If you want to delete a criterion, select the criterion from the Criteria list and click Delete. A
confirmation window is displayed; click Delete and the selected criterion is deleted from the
list.
On the Summary page, verify the details of the group. If you need to make changes, click
Back; otherwise, click Finish.
Figure 192. Define page - displaying selections
The dynamic group is created and is displayed in Resource Explorer. A confirmation

message about the group creation is also displayed.
Creating a static group

To make working with a set of resources easier, you can create a static group. For example, you
can create a static group for all the servers that you are responsible for in your systems-
management environment.

To create a static group, complete the following steps:
1. In the IBM Systems Director navigation area, click Resource Explorer, then click on Create
Group. In the Group Editor wizard, the Welcome page is displayed. Click Next.
2. On the Name page, type a unique descriptive name for the group that you are creating.
Optionally, you also can type a description of the group. Click Next. On the Type and
Location page, select Static from the Group type list.
3. From the Member type list, select the type of member that you want included in the group.
A member type acts like a filter. Only resources of the specified type can be a part of the
group you are creating.
Figure 193. Selecting the type of member
Any
Group membership is unlimited. Any resource can be in the group, including
systems, software, and management applications.
Managed System
Group membership is limited to system types such as different types of servers,
fabric, farms, hardware control points, controllers, operating systems, chassis,
switches, and storage.
Update
Group membership is limited to update types, such as for firmware, IBM Systems
Director, and operating systems.
Group
Group membership is limited to other existing groups.
4. From the Location list, select the parent group to contain the group that you are creating. In
Resource Explorer, a parent group is created and is located under Personal Groups. Click
Next.

Figure 194. Selecting the parent group
.
5. In the Define window, select one or more groups of resources from the Available list and
click Add. You also can drill down into a group and select one or more resources. If you
want to remove a group or resource, select it from the Selected list and click Remove.
Note:
1. You cannot add a group's parent to itself. For example, if you define the parent group
location for Group 1 to be Personal Groups, then you cannot add Personal Groups to
Group 1.
2. If you select a resource to add, but the Add button is unavailable, then the selected
resource is not a valid selection due to its member type.
6. On the Summary page, verify the details of the group. If you need to make changes, click
Back; otherwise, click Finish.
Figure 195. Verifying the details of the group

The static group is created and is displayed in Resource Explorer. A confirmation message
about the group creation is also displayed.
Customizing columns
The default columns shown in the various tables contained within the views (Resource Explorer,
Inventory, Event Log and Groups for Retail Client Managed End Points) of IBM Systems
Director are of limited usefulness. Fortunately, you can customize these columns to add retail-
specific information about the MEP's attributes, inventory data, event information and group
attributes by using the following steps in the respective views.
The following is an example for the Resource Explorer view:
1. Navigate to Resource Explorer---> All Retail Client Systems
Figure 196. Resource Explorer view

2. Click Actions, and then select Columns from the drop down menu.
Figure 197. Resource Explorer view - selecting columns

3. The Columns Order view displays.

Figure 198. Columns Order view
4. Select the column that you want to add from the Available Columns option box, then click
Add. This moves the column to the Selected Columns box.
Figure 199. Adding a column from the Available columns options box
5. You then have the ability to select where you want the column to appear. This is done by
clicking the Up or Down options.

Figure 200. Selecting where you want a column to appear
6. Once you are satisfied with columns added and position of the columns, click OK to save
and close the Columns window.
Figure 201. Selecting where you want a column to appear

The columns you have added now appear in the position selected in the Resource Explorer view.

Figure 202. Selected columns for the Resource Explorer view
Discovery
RES, retail stores and their associated Master Agents and General Agents can be discovered by
IBM Systems Director using the following steps.
1. Log into IBM Systems Director Server.
Figure 203. Logging into IBM System Director

2. The IBM Systems Director Home page after logging in with the valid user name and
password with administrative privileges

Figure 204. IBM Systems Director Home page
3. There are two ways to launch Resource Explorer - from the left hand pane navigation and
also the tab present next to Home page
Figure 205. Resource Explorer launch

4. Clicking on Resource Explorer link shows the Groups and this Group list will have the
Retail specific groups as shown below.

Figure 206. Resource Explorer with Retail Extensions
5. Clicking on Retail Groups link displays the list of Retail Groups as shown below
Figure 207. Resource Explorer Retail Groups

6. Click on Groups -> Retail Groups -> All RES Systems, the RES MEP will already be
discovered on loop back address as shown below.

Figure 208. RES MEP on loop back address
Notes:
1. Once the Master Agent for a store is configured and authorized in the RES Config Console
and the store is online, then all retail-managed end points for that store (the retail store and
the associated Master Agent and General Agents) will be discovered by IBM Systems
Director and listed in Resource Explorer.
2. Once the General Agent is discovered and connected to a Master Agent, if another (new)
Master agent is configured in the same subnet, then one more retail-managed end point for
the same general agent will be listed for the new Master Agent in Resource Explorer. This
new retail-managed end point for the General Agent will have locked access state and can
not be used for performing operations like Inventory, Software Distribution etc.
3. If a new Master Agent is introduced in the same subnet where a Master Controller is
configured as Master Agent and has its terminals discovered as Virtual General Agents,
then these Virtual General Agents will not be discovered for the new Master Agent. Also,
additional retail managed end point with locked access state will not be created for these
Virtual General Agents.

Figure 209. Locked GA's
Figure 210. System Discovery - Discovered Manageable End Points

The managed end points (MEPs) created for RES, Retail store, Master agents, and General agents
can be seen on the Resource Explorer page.
Each MEP created in Figure 210 will have a Director-specific Retail Service Access point created.
See Figure 211 and the following steps.
Note: Do not delete this access point; doing so will result in unexpected errors.
Figure 211. Director-specific Retail Service Access point
1. Right-click on MEP and select Security ---> Configure Access.

2. The RSAP for the MEP will be listed in this table.
Note: Do not delete this access point, doing so will result in unexpected problems.

Figure 212. RSAP for the MEP
Retail Store Authorization

To authorize a retail store that is in a locked (unauthorized) state, see Figure 213.
Figure 213. Retail store in a locked state
1. Right-click on the store, and select Security ---> Request Access.

Note: If multiple locked or unauthorized stores need to be authorized by same user name
and password, then multiple unauthorized stores can be selected.
Figure 214. Security ---> Request Access - part 1
Figure 215. Security ---> Request Access - part 2

2. The Request Access tab opens.

Figure 216. Request Access tab
3. Enter your user name and password, then click Request Access. This will carry out the
authorization process.
Figure 217. Authorization process

4. After a successful authorization, the access state will change to OK.

Figure 218. Access state
5. Click Close to close the Request Access tab.
Figure 219. Closing the Request Access tab

6. During an authorization attempt failure, the store status will remain unauthorized or
locked. You can retry authorization by entering your user name and password, and by
clicking the Retry On Failed button.

Figure 220. An authorization attempt failure
Query/Verify Connection
Director 6 provides the Verify Connection function. Verify Connection queries RES and retrieves
and updates the current attributes of MEP which triggers the query.
1. Verify Connection can be initiated on any MEP by right clicking on MEP, and selecting
Security ---> Verify Connection.

Figure 221. Verify Connection
2. Click Verify Connection to query RES, and to retrieve and update the MEP attributes.
Figure 222. Retrieve and update MEP attributes

3. Click Close.

MEP Deletion
MEPs displayed in Director 6 UI can be deleted by:
1. Selecting the MEPs and right click to select Remove.
Figure 223. Deleting MEPs displayed in Director 6 UI

2. Click OK if an MEP should be deleted.
Figure 224. Confirming an MEP deletion

Chapter 16. Using inventory
Using inventory
This chapter describes the inventory data, a collection of mostly static information about the
remote system, including hardware and software information.
Some examples of inventory data are:
• Serial number, manufacturer, model
• BIOS version
• Memory and hard drives installed/capacity
• CPU type
• Operating system type, version
• Installed software packages (only available on Windows with RMA 2.5 and higher)
Inventory is collected and stored in the database on the IBM Systems Director Server, which
allows inventory information to be viewed even when the remote systems are offline.
Inventory collection is the process by which IBM Systems Director Server establishes connections
with Retail Client managed end points that have already been discovered and collects data about
the hardware and software that is currently installed on those resources.
Note: Inventory collection is not supported on embedded agents.
Collecting Inventory
To collect inventory for one or more systems, complete the following steps:
1. Open the View and Collect Inventory page using either of these two methods:
a. On the Home page, click View and Collect Inventory under Optional tasks.
Figure 225. View and Collect Inventory Selection on Home Page

b. In the IBM Systems Director page navigation area, expand Inventory and then click
View and Collect Inventory.
Figure 226. View and Collect Inventory selection in Director navigation area
The View and Collect Inventory page displays.
Figure 227. View and Collect Inventory page
Note:
The View and Collect Inventory tab can also be displayed by using one of the following
methods:
1. From the Resource Explorer tab, select one or more target systems or groups, right click
to display a dropdown menu, select the Inventory option, then select View and Collect
Inventory.
2. From the Resource Explorer tab select one or more target systems or groups, click the
Action button to display a dropdown menu, select the Inventory option, then select
2. In the Target Systems list, select the system you want to view or collect inventory data. If the
target system that you want to view is not in the Target Systems list, complete the following
steps to add the system to the list.
1. Click Browse to open the Context Chooser screen. The Context Chooser displays a list
of Target Systems.

Figure 228. Context Chooser - view 1
Note: The Show field dropdown allows you to select Target Systems, All Targets,
Groups, or Recent Targets.
Figure 229. Context Chooser - view 2

2. Select one or more items from displayed list then click the Add button to move them to
the Selected list.
Note: Items in the Selected may be removed by selecting them and clicking the Remove
button.
Figure 230. Select a valid target - add to the selected list

3. Select one or more list items to add.
Chapter 16. Using inventory 215

Figure 231. Selecting a target system to add
4. Click Add. The selected target systems are displayed in the Selected list.
Figure 232. Selecting a target system to add - view 1
Figure 233. Selecting a target system to add - view 2

5. Click OK.

Figure 234. Click OK to finish
3. In the View by list, select the inventory profile that you want to use: All Inventory, All
Hardware Inventory, All Software Inventory, or Basic System Information.
Figure 235. View by list - inventory profile

4. Click Collect Inventory. The Launch Job page is displayed.

Figure 236. Run - Collect Inventory page
5. Use the Launch Job page to set up optional functions and options of your inventory
collection task:
Figure 237. Setting up functions and options - inventory collection task
Schedule
Use the Schedule tab to set the inventory collection task to run immediately or at a
specified time and date in the future. You can also schedule the task to repeat at a
specified frequency.
Notification
Use the Notification tab to choose options for an email notification that you can
receive as the inventory collection process progresses.
Options
Use the Options tab to specify the time to use for the system time and how to handle
unavailable systems.
6. When you are finished with the Launch Job page, click OK. An inventory collection job is
created and a message is displayed with buttons and information about the job.

Figure 238. Click OK to create and Inventory collection job
Note: Click Display Properties if you want to view the job status and progress.
7. The Active and Scheduled Jobs page is displayed and provides information about the job
including status, progress, a list of targets, a history, and job logs.
Figure 239. Active and Scheduled Jobs page
When inventory collection has completed on all managed objects, the inventory data is
viewable from the View and Collect Inventory tab by clicking the Refresh View button.
Inventory Performance Tip

To minimize the time it takes to run inventory collection on more than a few MEPs
simultaneously, you can manage the number of threads in the inventory thread pool. To manage
the number of threads, create a file with the extension .javaopt (for example,
invthreadpool.javaopt) in %dir_home%/lwi/conf/overrides. Include the following
line in the file:
-Dperf.extended.discovery.poolsize=30

This specifies that inventory is run for 30 MEPs at a time instead of just 5 MEPs, which is the
default.
Note: On a Windows server machine, after adding the above mentioned details, check the file
type of invthreadpool.javaopt by right clicking on the file and selecting Properties. Type
of file: should be JAVAOPT File (.javaopt).
If inventory needs to be collected for a large number of MEP's, set the following configuration
parameters appropriately.
1. Configuration variable INVENTORY_RES_CMD_TIMEOUT_VALUE is available in retail-
isd.properties at location %dir_home% \proddata\retail. This is the inventory
collection request/response timeout value. The value should be in terms of milliseconds.
2. Configuration variable perf.extended.discovery.timeout is available in
USMIKernel.properties at location %dir_home%\lwi\conf \overrides. This is Director
inventory extension timeout value. The value should be in terms of minutes.
Director server and RES have to be restarted after changing the settings. Refer to Appendix
A, Stopping and starting RMA Director RES on page 375.
Following is the default value that is recommended for Inventory collection of a group having
500 MEPs: perf.extended.discovery.timeout=60 and
INVENTORY_RES_CMD_TIMEOUT_VALUE=3600000.
Viewing inventory
To display inventory data for a resource, complete the following steps:
1. Open the View and Collect Inventory tab using either of the following two methods:
a. On the Home page, click View and Collect Inventory under Discovery Manager tasks.
Figure 240. View and Collect Inventory Selection on Home page

b. In the IBM Systems Director navigation area, expand Inventory, and then click View
and Collect Inventory. The View and Collect Inventory tab is displayed.

Figure 241. View and Collect Inventory selection in Director navigation area
Note:
The View and Collect Inventory tab can also be displayed by using one of the following
methods:
1. From the Resource Explorer tab select one or more target systems or groups, right click
to display a dropdown menu, select the Inventory option, then select View and Collect
Inventory.
2. From the Resource Explorer tab select one or more target systems or groups, click the
Action button to display a dropdown menu, select the Inventory option, then select
2. In the Target Systems list, select the system(s) to view or collect inventory data. If the target
system that you want to view is not in the Target Systems list, complete the following steps
to add the system to the list.
a. Click Browse to open the Context Chooser. The Context Chooser displays a list of the
most recently inventoried systems.
Figure 242. Content Chooser - list of systems - view 1

Figure 243. Content Chooser - list of system groups - view 2
b. Select one or more items from displayed list and click the Add button to move them to
the selected list.
Note: Items in the selected list may be removed by selecting them and clicking the
Remove button.
Figure 244. Selecting groups and individual target systems

c. Select one or more target systems that you want to add.
Figure 245. Adding target systems

d. Click Add. The selected target systems are displayed in the selected list.

Figure 246. Target systems added - view 1
Figure 247. Target systems added - view 2

e. Click OK
Figure 248. Target systems added - click OK to Finish

3. In the View by list, select the inventory profile that you want to use: All Inventory, All
Hardware Inventory, All Software Inventory, or Basic System Information.

Figure 249. View by - select inventory profile to use
4. Click Refresh View. The inventory data for the selected resource is displayed.
Note: If you click Refresh View before any inventory has been collected by IBM Systems
Director Server, an empty table is displayed and the Last collected value will be None.
Before you try to view inventory, ensure you find the applicable resources and collect the
inventory for them.
Figure 250. Refresh View - view 1
To view the inventory report for a target system, select (from the left Action pane) Resource
Explorer > All Retail Client Systems > Select the target system > Select Inventory tab and
click Refresh View.

Figure 251. Refresh View - view 2
For RMA V3 R1.4 and above Retail Extensions and RES, the EFIX level for Toshiba SurePOS
ACE and Toshiba SurePOS ACE EPS applications will be reported as seen in the screen shot
below (highlighted). The EFIX level will be reported for all supported RMA agents as well.
Figure 252. ACE EFIX Level
Report Terminal Sales Version inventory
With RMA V3 R1.4, Terminal Sales Version details will be shown as part of the 4690 terminal
Inventory under system software.
ACE version will be reported for a 4690 terminal. The ACE version should be V7R4 or higher.
The c:\adx_idt1\ACETSVER.DAT file is automatically created, if it doesn't already exist,
when the master controller is rebooted.
File ACETSVER.DAT should be present on acting master controller at location C:\ADX_IDT1, to
populate the inventory data.

Figure 253. Terminal Sales Version
ACE PIN PAD inventory
With RMA V3 R1.4, PIN Pad details will be shown as part of the 4690 terminal Inventory.
Pin pad inventory data will be reported for a 4690 terminal. The ACE version should be V7R5 or
higher.
The file c:\adx_idt1\EPSTRMPP.DAT is automatically created, if it doesn't already exist,
when the master controller is rebooted.
The EPSTRMPP.DAT file should be present on acting master controller in C:\ADX_IDT1 to
populate the inventory data.

Figure 254. ACE Pin Pad inventory
Exporting inventory data

You can export collected inventory data to a file in a comma-separated value (CSV), HTML, or
XML format. Be sure to turn off the web browser option to block pop-up windows for the URL
that you use to log into IBM Systems Director Server.
Complete the following steps to export your collected inventory data:
1. In the IBM Systems Director navigation area, click Inventory -> View and Collect
Inventory.
2. Ensure you collect and view the inventory data that you want to export. For more
information about collecting and viewing inventory data, see “Collecting Inventory” on
page 213 and “Viewing inventory” on page 220.
3. Click Export All. The browser either opens a file download window or it displays the
exported data.
Figure 255. Export All - view 1

Figure 256. Export All - view 2
4. Save the file.
a. If the Web browser opens a file download window, save the file. If the web browser
requires a location selection, provide it and click Save.
b. If the web browser displays the exported inventory data, from the File menu, click Save
As, navigate to the location where you want to save the file, and then click Save.
Figure 257. Saving exported inventory data

Note: You can only save the file to a file system that is accessible from the system running
IBM Systems Director Server.
Add and position Serial Number to the Resource Explorer columns

displayed in the Director Console
Add the Serial Number inventory attribute as a column in the table view of the Retail Client
managed end point (MEP) properties.
1. Navigate to Resource Explorer > Groups > All Retail Client Systems.

Figure 258. Resource Explorer > Groups > All Retail Client Systems window
2. Click Actions, and then select Columns from the drop down menu.
Figure 259. Selecting Columns from the Actions drop down menu
3. The Columns popup view displays.
Figure 260. Columns Order view

4. Select the SerialNumber attribute from the Available Columns option box and click Add.
This moves the column to the Selected Columns box.

Figure 261. Selecting the SerialNumber attribute
5. Click OK to save and close the Columns window.
Note: The position of the column is set using the Up/Down buttons to the right of the
Selected Columns list.
Figure 262. Saving and closing the Columns window

6. Verify the new column in the IBM Systems Director Console.

Figure 263. New column in IBM Systems Director Console

Chapter 17. Event management
Event management
This chapter gives a basic introduction to the event management capabilities of RMA and IBM
Systems Director, along with examples of using event management with RMA/Director in an
IBM POS environment.
Introduction to Event management

In the RMA/Director solution, "events" represent alerts that are forwarded from RMA to IBM
Systems Director, and can be handled by Director in a variety of ways. Events sometimes
originate within RMA itself (that is, resource monitoring thresholds trigger events internally
within RMA), but usually the source of the event is external to RMA.
For example, many events on a Windows system are forwarded to RMA via the Windows
Management Instrumentation (WMI) event forwarders within the RMA agent. On 4690
operating systems, events are created by MBeans that are monitoring the 4690 event logs.
When an event is created in RMA, the event becomes a "JMX Notification", which is ultimately
forwarded to IBM Systems Director and converted into a Director Event. RMA ensures that these
events are never lost. For example, if the master agent or the Director Server is offline, then the
events will be saved locally to make sure they are saved until the upstream systems are back
online (this feature is called store and forward).
Figure 264 illustrates the flow of events from CIM to RMA to Director:
Figure 264. Flow of events from CIM to RMA to Director
The following sources of events are included in the IBM POS solutions:

UPOS event
On Windows and Linux, all UPOS status update events are forwarded from CIM to RMA
to IBM Systems Director. This allows such events as "receipt near end" (that is, the paper-
low sensor for the 4610-2CR/2NR printers) to be handled by Director. UPOS Events are
not supported on OS4690 platform as CIM is not supported on OS4690 platform.
Sensor driver events

On Windows only, the systems with sensor drivers and light-path management via the
service processor have the status of the LED lights forwarded from CIM to RMA to IBM
System Director. This allows management of these LED status lights from the enterprise.
SMART events
On Windows, selected additional CIM events, such as SMART events (that is, predicting
hard drive failure) are also forwarded from CIM to RMA to IBM Systems Director.
Inventory alerts
These are generated within IBM Systems Director in response to inventory alerts that
have been configured.
Director status events

These events do not originate from RMA, and are created at the Director Server --- for
example, RMA agent online/offline.
4690 event logs

In a 4690 environment, the MBeans for 4690 monitor the 4690 event logs and forward
these events to RMA (and ultimately to Director). This allows remote management of the
4690 system and application event logs.
Windows event logs

On Windows, RMA has the ability to forward events from the Windows Event Logs
(Application, System, and Security events) to IBM Systems Director. To configure which
events will get forwarded, you need to set up the Win32EventLogConfig.xml found
in %RMA_HOME%\user\rma\config\events. See below for more details.
Application-specific events
For example, the IBM CHEC self-checkout software automatically forwards a number of
events to RMA. In the case of CHEC, it is done via application-specific MBeans within
RMA, but it is also possible to send application events via CIM forwarding.
Event management resources

This section provides the most critical information you need to begin working with events via
RMA. For a more thorough discussion of event management within Director, refer to the IBM
Systems Director documentation at http://pic.dhe.ibm.com/infocenter/director/pubs/index.jsp
and also to the IBM Systems Director Redbook at www.redbooks.ibm.com/abstracts/
sg247694.html.
Using the Director Event Log

This section describes the procedures to review all Events or Retail MEP Events.

Viewing All Events
To review all Events using the Director Event log, complete the following steps:
1. After logging into IBM Systems Director on the left pane, expand the System Status and
Health node, click the Event Log option and the Event Log tab is displayed. Events are
listed in the IBM Systems Director Console depending on the Event Filter selection in RMA
Store Manager for the respective store.
Figure 265. Store Event filter window

2. Click Refresh to view the events in the Events table.
Figure 266. Events table window

3. Click on the event entry link to display the respective event properties under the General
tab, along with Event Text and Severity.
Chapter 17. Event management 235

Figure 267. General tabs window
Viewing Retail MEP Events

1. After logging into IBM System Director, traverse to the Agent MEP with one of the
following commands:
• Resource Explorer ---> Groups ---> All Systems
• Resource Explorer ---> Groups ---> All Retail Client Systems
• Resource Explorer ---> Groups ---> Retail Groups ---> All Retail Client Systems
2. The Events will be listed in the IBM Systems Director Console depending on the Filter
selection in RMA Store Manager for the respective Store.
Figure 268. IBM System Director Console window

3. Click on the Agent MEP to see the Agent MEP Properties. Click the Event Log tab and then
click Refresh to see the event entries.

Figure 269. Event entries listed in the agent MEP Properties window
4. Click the Event Entry to see the respective event properties under the General tab, along
with Event Text and Severity.
Figure 270. Event entries

Configuring the event Log
There are a number of configuration settings that have an impact on what events are collected
and what events are displayed in the event log viewer.
The Event Filter field option in the RMA Store Manager controls which events are forwarded
from RMA to RES and in turn to IBM System Director. If you are experiencing too many events
at the Director Server, you might consider changing the event filter setting in RMA Store
Manager by selecting the Store.
Figure 271. Define Master Agent window
In Director console, click on System Status and Health in the left pane and select Event Log to
view the events logged for all systems discovered in Director. Figure 272 shows the Event Log
page.

Figure 272. Event log view
Agent Online & Offline Event

If an agent goes offline, an offline critical event will be logged against the specific MEP and the
Health Status of the specific MEP will turn red.
Figure 273. Agent Offline Event
If an agent comes back online, an online resolution event will be logged against the specific MEP
and the Health Status of the specific MEP will turn green.

Figure 274. Agent Online Event
If a Master Agent goes offline then an offline critical event will be logged against the specific
Master Agent as well as against the General Agents that are associated with it.
Figure 275. Both Master Agent and General Agent offline
If a Master Agent comes back online then an online information event will be logged against the
specific Master Agent as well as against the General Agents that are associated with it.
Figure 276. Both Master Agent and General Agent online
The online/offline event that is logged for the MEPs will have the following event properties:
• Component Category = Retail/mgmt
• Component Type = connection
• Condition Type = status

• Condition Value = "offline" (for offline event) or "online" (for online event)
Figure 277. Agent offline event properties

Figure 278. Agent online event properties
The offline and online events are system events which are not persisted. The property
com.ibm.retail.si.mgmt.eventcontrol.storeandforward.buffertimeoutthresh
old in rmauser.properties file should not be set to a value lower than 300000 (which is the
default value).
The store and forward mechanism for events exists between:
• Master Agent and RES
• Master agent and Real General agents
• Master agent and terminals (Virtual (General) agents) running on/with 4690 Master
Controller with GA configured on it.
However, there is no store and forward mechanism between:
• RES and Director, hence the events that are generated in RES when Director is down will be
lost.
• Master agent running on Master Controller and terminals (Virtual (General) agents) running
on it.
Creating event filters

Event filters allow you to sift through the events in the event log, selecting only the events that
meet your criteria. This is different from the discovery preferences event filter. Event filters are
most useful in event action plans that allow you to select which events will trigger the actions in
your event action plan. There are two ways you can create an event filter from scratch or by
using an existing event as a template.

Creating an event filter from scratch
Complete the following steps to create an event filter from scratch:
1. Click Automation -> Event Filters in the left pane of Director.
Figure 279. The LHS pane of Director

2. Click Create to create new event filters.
3. Click Next in the Welcome page for the Create Event Wizard.
Figure 280. The Welcome page of Director

4. Enter a valid name for the Event Filter Name field and enter the description for the Event
Filter and click Next.
Figure 281. Edit event window

5. From the drop-down menu on the Filter Type page (Figure 282) of the wizard, choose Filter
Type. See “Managing event types” on page 255 for a description of the filter types.
Figure 282. Filter Type window

6. In the Event Type wizard, choose Custom and Event Types from the dropdown menu and
then click Retail entry.
Figure 283. Event Type wizard

7. The Component Category table is displayed with the list of the component categories for the
Retail event group selected. From the list of Component categories, select the component
categories of each event type that you want to add to the filter. Clicking each link will
navigate to a subcategory. For example, click the UPOS option as shown in Figure 284:
Figure 284. List of Component Categories

Note: If a retail event type is not listed in the list, then it can be pre-published or published
automatically when it is first received. See the section: "Managing Event Types" for further
information.
8. The Component Type table is displayed with the list of component types for the respective
Component Category. Select the cash drawer (Component Type) and click Add. Make sure
Retail.upos.cashdrawer is listed under the Selected table in the right pane, as shown
in Figure 285.
9. Click Next.
Figure 285. Component Types for each category

10. From the Severity and Category pane, you can choose between Default and Custom.
• If you select Default, the filter will have all the severity levels for the filter that is created.
• If you select Custom, choose from a list of severity levels to create the filter.

Figure 286. Severity and Category pane - Custom view
11. Click Next and the Event Sender window is displayed.
12. Select Default or Custom from the Event sender to include field:
• If you select Default, the filter will include events that are sent by all event senders.
Figure 287. Event Sender window - Default view

• If you select Custom, only events that are sent by specific event senders are displayed.
Use the following naming convention for the event sender:
StoreId-DeviceId

Populate the event sender (using the naming convention) in the Additional sender field,
and then click the Add button to move the event sender to the "Selected senders"
window (see Figure 288).
Note: Do not use systems that are present in the left pane when selecting event sender.
Device Id can be gotten from MEP name as MEP name is defined as "StoreId.DeviceId".
Event sender should be given as "StoreId-DeviceId"
Figure 288. Event Sender window - Custom view

13. Click Next and the Event Text pane is displayed.
14. Select Default or Custom from the Event text to include field:
• If you select Default, the filter will include all the event text.

Figure 289. Event Text window - Default view
• If you select Custom, you can specify which event text to include.
Figure 290. Event text window - Custom view

15. Click Next and the Time Range window is displayed.
16. Select All or Custom from the Time range to include field:
• If you select All, the filter will include events that occur during any date and time.

Figure 291. Time Range window - All view
• If you select Custom, you can specify the time range for included events. You can add
more than one day or time range.
Figure 292. Time Range window - Custom view

17. Click Next and the Summary window is displayed.

Figure 293. Summary Window
18. After you review the summary page, click Finish to complete the Event Filter Creation.
19. To see the event filter that you created, click on the Events Filter tab.
Figure 294. Events Filter tab window

Creating an event filter from an existing event filter
To create an event filter using an existing event filter, there must already be at least one event
created.
1. Click Automation -> Event Filters in the left pane of Director.
2. Select the event filter template that you want to copy and then click Create Like to copy an
event filter template.
3. Click Next on the Welcome page of the Copy Event Filter wizard to display the Filter Name
page.
Figure 295. Copy event filter - filter name

4. To change and save the Filter Name, Event Type, Severity and Category, Event Sender,
Event Text, or Time Range, follow the steps in “Creating an event filter from scratch” on
page 243.
Note: You cannot change the Filter Type when the event filter is created from an existing
event filter.
Creating an event filter from an existing event

To create an event filter from an existing event, complete the following steps:
1. From Resource Explorer, select an MEP and click on the Events tab.
2. Select an event and click Create Filter. The Create Simple Event filter window is displayed.

Figure 296. Create Event filter from existing event window
3. Enter the filter name and description and click OK to save the event filter.
Note: The event type is picked up from the event selected.
Figure 297. Create Simple Event Filter window

4. Click Automation -> Event Filters.
5. Select the filter created and click the Edit button.

Figure 298. Edit Event Filter created window
6. The Edit Event filter wizard is displayed, which shows the Summary the Event filter
created.
Figure 299. View Summary of Event filter created window

7. Click System Status and Health -> Event log and select the Event filter created.
8. Click Refresh to view the events filtered.

Figure 300. View event filter window
Managing event filters

When creating an event filter in the Event Filter wizard, the list of available retail event types
comes from a set of XML files read during Director server startup. These files are located in
Director\proddata\retail\events. The file RetailEventTypeData.xml contains the
base set of retail event types. This file is updated with the Retail Extensions for IBM Systems
Director and should not be edited.
The retail extensions provide a mechanism for users to publish their own event types by creating
their own XML files in Director\proddata\retail\events. Up to 5 separate files are
supported, each with a file name of the format RetailEventTypesX.xml, where X represents
the numbers 1 through 5 (for example, RetailEventTypes1.xml,
RetailEventTypes2.xml). The files may be created in any order. The file
EventPublishingSample.txt, located in Director\proddata\retail\events,
provides examples of the XML format used to publish new event types.
Additionally, any event that is received whose event type is not present in any of the event type
XML files (base or extension) will be automatically published. The information about these event
types will be persisted in Director\proddata\retail\events
\UnknownEventTypes.xml to be read during server startup.
Note: Publishing unknown events applies only to events starting with "Retail" as their first
component category or qualifier.
Managing event types

You can choose to create several types of filters from the Filter Type window (as shown in
Figure 282):
Simple Event Filter

Allows you to specify which events match the filter based on any event attributes (type,
severity, text, etc). All other events are filtered out (that is, ignored). This forms the basis
for the other filter types.
Threshold Event Filter

Allows you to require a certain number of duplicates before matching (within a specified
period of time).

Duplication Event Filter
Allows you to ignore duplicate events (within a specified period of time).
Exclusion Event Filter

Allows you to specify additional event types to exclude from your filter.
Defining an event action plan

The Event action plan task allows you to define how Director will react to events. To define an
event action plan:
1. Define an event filter that matches the events you want to react to, then you can test your
event filter independently before creating the event action plan.
2. Select and customize the actions you want to execute in response to the event.
3. Drag-and-drop to build your plan.
Using the event action plan builder

To use the event action plan builder, complete the following steps:
1. In the left pane of the IBM Systems Director user interface, expand the Automation option.
2. Click Event Actions to display the Event Actions tab.
Figure 301. Event Actions tab

3. Open the tab and click Create to display the Create Action wizard.
The following actions are not currently supported by RMA:
• Start a program on the system that generated the event
• Start a program on a system
• Start a task on a specified system
• Start a task on a system that generated the event

Figure 302. Create Action wizard
4. Select the type of action that needs to be created and then click OK to display the Create
Action details (see Figure 303).
• Complete each field. For additional information on the selected action, click Learn more.
• Click Test to check if the values entered are valid.
• Once validated, click OK. The Event Actions tab is displayed and the created Event
Action is listed in the table.

Figure 303. Create Action wizard
Associating the event action plan

To associate the event action plan, complete the following steps:
1. In the left pane of the IBM Systems Director user interface, expand the Automation option.
2. Click Event Automation plans to display the Event Automation tab.
Figure 304. Event Automation tab

3. Click Create to display the Create Event Automation wizard.

Figure 305. Create Event Automation wizard
4. Click Next and the Name and Description window is displayed.
5. Enter a valid name and description for the event automation plan.
Figure 306. Name and Description window

6. Click Next and the Target window is displayed.

Figure 307. Target window
7. Select the entries from the table you need to create event actions and click Add.
8. Click Next and the Events window is displayed, with Common as the default for Events
drop-down.
Figure 308. Event window

9. Select the event types from the list and click Next (see Figure 309).

Figure 309. Common event types window
10. If you selected the Advanced Event Filters option, select an event filter that you have
already created and click Next.
Figure 310. Advanced Event Filters window

11. The Event Actions window is displayed with the event action that you created. To start
saving the events history:
a. Select the event action required.
b. Right click on the event action.

c. Click Start Saving History.
Figure 311. Start Saving History window

12. Select the event action and click Next.
Figure 312. Event Actions window

13. The Time Range window is displayed, with All the time (24x7) selected as the default.

Figure 313. Time range window - default view
14. To customize the time range and select a range of times to receive events, click Custom.
Figure 314. Time range window - customized view

15. After selecting the Time Range, click Next to display the Summary window.

Figure 315. Event automation Summary window
16. Confirm your selection and then click Finish. The Event Automation tab is displayed with
the Event Automation Plan you created listed in the table.
Activating the event automation plan

To activate the event automation plan, complete the following steps:
1. From the Event Automation Plans table, select an existing event automation plan and click
Activate.

Figure 316. Event Automation Plans window
2. After the Event Automation Plan is activated, a confirmation message is displayed (see
Figure 317).
Figure 317. Event Automation Plans confirmation message

3. To cross-check the event action plan, click Resource Explorer.

Figure 318. Resource Explorer window
4. Select the Group or Agent on which this Event Automation Plan is created.
5. Click on the MEP within the Group (for Group case) or MEP.
6. Click the Applied Activities tab and the Event Automation plan listed for the specific MEP
is displayed.
Verifying the event automation plan

The configured event action is executed when an event (which falls under the configuration
defined in the Event page of Event Automation Plan) is generated for the target systems selected
in the Event Automation Plan. The event action selected is a " Log to a log file" type with a log
file generated in the install_root\log directory of the IBM Systems Director server
machine with the entry of the event and the log comment included in the event action.
Event management for 4690 operating systems

Events logged to the 4690 event logs (including system and application events) are forwarded to
RMA and are available within the IBM System Director Console. You can use event action plans
to react to specific events from 4690.
There are many 4690 events available, but the most important events to a particular retailer vary
depending on the 4690 features used and how the stores are operated. The system events that
might be logged are listed and described in the 4690 Operating System Messages Guide.
Examining current 4690 event logs and the history of event logs might help you identify the
types of events experienced in a particular environment. It is not necessary to have event action
plans for every event that suggests a problem. Frequently, problems log multiple events
providing different details of what occurred. Create event action plans for events that are
representative of the types of problems of interest. You can then investigate the event log to get
more details for the problem that occurred.

The following is a list of 4690 controller events that might be used to trigger Event Action Plans.
Some or all of these events might make a good starter set in determining the event action plans
you should create. Add others to suit your particular interests and needs.
• W889 FTP connection from <IP Address>
• W893 Telnet connection from <IP Address>
• W619 PROGRAM COMMAND WAS STARTED
• W312 CHECKOUT SCANNER PROBLEM
• W598 STORE CONTROLLER STORAGE DUMP OCCURRED
• W599 NORMAL STORE CONTROLLER IPL
• W610 PROGRAM CANCELED DUE TO INSUFFICIENT STORAGE
• W619 PROGRAM xxxxxxxx WAS STARTED
• W620 PROGRAM xxxxxxxx HAS ENDED
• W638 APPLY SOFTWARE MAINTENANCE FAILED
• W650 PROGRAM xxxxxxxx HAS ENDED ABNORMALLY
• W762 TERMINAL xxx DOES NOT RESPOND
• W806 HOST COMMUNICATIONS PROBLEM ON LINE xxxxxxxx
• W901 NO ACTING MASTER CONTROLLER FOUND
• W902 NO ACTING FILE SERVER CONTROLLER FOUND
• W907 UPDATE FROM ACTING FILE SERVER WAS UNSUCCESSFUL
• W947 CONTROLLER xx HAS LEFT LAN SYSTEM
The Retail Extensions for IBM Systems Director 6 include all 4690 events pre-published in order
to make it easy to create event filters based on 4690 events.
To create a filter:
1. Go to Automation->Event Filters.
2. Click Create to open the wizard.

Figure 319. Event Filters window
3. Enter a name and description for the filter and click Next.

Figure 320. Create Events window
4. Select Simple Event Filter for the event filter type and click Next.

Figure 321. Create Events filter type window
5. In the Event Type window, select Custom from the Types of events to include dropdown
menu (see Figure 322). This view presents the high level list of event component categories.
The selection box on the left side of the table allows you to select that component category
and any events and subcategories beneath it.

Figure 322. Types of events to include
6. Click Add or Remove to add and remove selections at any time.
7. For 4690 events, click the Retail link in the table, and then click the OS4690 link. A list of all
the 4690 message groups is displayed (that is, W795):

Figure 323. 4690 message groups displayed
8. Select one or more message groups by checking the selection box and clicking Add. Adding
a message group will add all event IDs in that group. You can also search for a specific
message by entering part or all of the message group name in the search field and clicking
Search.

Figure 324. Searching the 4690 message groups
9. Click each message group link if you would like a list of event numbers and filters on
specific event numbers.

Figure 325. List of event numbers and filters
10. Click Next to navigate through the Severity, Event Sender, and Time Range windows. Use
the default options, which can be customized if required.

Figure 326. Severity and Category Window
11. At the end of the wizard, click Finish.
Figure 327. Wizard Summary Window

12. You can now use the filter to create event action plans or to filter events in one of the Event
Log views.
Figure 328. Created event log filters
Event severity override in 4690

In 4690 agents with OS version V6R4 and higher, the OS4690EventSeverities.properties file in
f:\rma\user\rma\config\events (M: on classic controllers) can be configured to override
the severity of the events set by OS4690.
Mentioned below are the severity levels that can be set to a OS4690 event.
# RTL_CRITICAL_NOTIFICATION = 1 (4690 Sev 1, Fatal severity in Director)
# RTL_EMERGENCY_NOTIFICATION = 2 (4690 Sev 2, Critical severity in Director)
# RTL_ERROR_NOTIFICATION = 3 (4690 Sev 3, Minor severity in Director)
# RTL_WARNING_NOTIFICATION = 12 (Error severity in Director)
# RTL_INFORMATION_NOTIFICATION = 5 (4690 Sev 4 and 5, Harmless severity in Director)
In the below example, event severity for W650 event with condition value E008 is set to Minor
severity in Director.
W650.E008 = 3
This file will by default contain events with severity overridden.

Event severity overrides file on IBM Systems Director
The config file for overriding the event severity of events on IBM Systems Director is located at
%DIR_HOME\proddata\retail\events\SeverityOverride.properties, as shown in
the following example:
Retail.mgmt.connection.status.offline=1
# OFF = 100;
# RTL_ALERT_NOTIFICATION = 1;
# RTL_CONSUMER_NOTIFICATION = 2;
# RTL_CRITICAL_NOTIFICATION = 3;
# RTL_DEBUG_NOTIFICATION = 4;
# RTL_EMERGENCY_NOTIFICATION = 5;
# RTL_ERROR_NOTIFICATION = 6;
# RTL_INFORMATION_NOTIFICATION = 7;
# RTL_NOTICE_NOTIFICATION = 8;
# RTL_TRACE_POINT_NOTIFICATION = 9;
# RTL_WARNING_NOTIFICATION = 10;
In this example, the offline event is set to '1' which make the event appear as CRITICAL severity
in Director.
Setting the event severity to '100' will suppress this event from being logged in Director
System event config file on Master Agent

In Master Agents, you can flag certain events as system events so that they are not filtered out by
the RES event filter on the RMA Store Manager UI. As events with the system flag set
(RtlNotification.FILTER_MASK_SYSTEM_EVENT) always pass through the severity filters,
there is a provision to flag certain events as a System event with a related entry in the
syseventcfg.properties at %RMA_HOME%/user/rma/config/events directory. For
example, as all events are transferred from GA to MA, you do not need to override anything on
the GA. In the following example, all EXXX values for W951 will be set to system events:
Retail.OS4690.W951=system
Retail.OS4690.W123.E001=system
Retail.mgmt.capture.solicited=system

Chapter 18. Introduction to Health Status
Introduction to Health Status
The Health Status component in Systems Director helps the user to manage the health of
resources configured. In the RMA/Director solution, “events” represents alerts/resolutions sent
from store (RMA ) to IBM Systems Director, which shows the health status of the MEPs on the
IBM Systems Director. Events received by Systems Director determine the status of resource.
Severity and category are used to determine the status. All alert events can cause red, yellow and
blue status of the resource where as a corresponding resolution event would bring the system
back to its OK (green) state.
Event log view

The Severity column in the event log view (click Left Action Pane -> System Status and Health
-> Event Log) decides the severity of the event on the health status view.
Figure 329. Event Log View

Various views of the Health Status:
Welcome summary page:
Figure 330. Navigation: Home -->Status Manager
The Welcome Summary page shows the aggregate health of the systems being managed.
Figure 331. Aggregate Health of Systems
Clicking the red /yellow/blue/green area on the pie chart or clicking on the line items beside it
will open a view of systems under that particular category. For instance, the above pie chart
shows 174 systems in OK state and two systems in warning state. Clicking on the warning
systems will show the two systems with warnings.

Figure 332. Systems with Warning State
Health Summary view

• Scoreboard: This shows the number of systems with problem or compliance alerts. The
Scoreboard view at the top right shows the number of unique problems or compliance alerts.
• Systems with Problems (View Members): This shows the list of systems with problems.
Figure 333. Scoreboard view
Clicking on problems in the Scoreboard view will show all alerts associated with the different
systems.
Chapter 18. Introduction to Health Status 281

Figure 334. Problems screen
Clicking on each problem would take us to the detail page:
Figure 335. Problems detail page
Resource Navigator view

In the Resource Navigator view, the health status of systems can be monitored with problem or
compliance columns. In the following example, the 192.168.1.104 system has a critical Alert
event, and the other two systems have none.

Figure 336. Resource Navigator view
Resource Properties view

The Active Status tab, under the Resource Properties view will show all active Alert events
associated with the resource selected.
Figure 337. Resource Properties View
Active Status view

The Active Status view allows the user to view the status of all discovered systems.

Figure 338. Active Status view
Problems view
Note: The Problems view does not include compliance alerts
The Problems view allows the user to view active problems reported for all discovered systems.
Figure 339. Problems view
Actions on problem/active status entries

Ignore
Ignore current and future occurrences of selected problem(s) for single resource or all resources.

Figure 340. Ignore Problems
Events can be ignored on a particular selected resource or on all resources by using the radio
button.
Figure 341. Scope of Ignore Operation
The following figure shows the Problem Status view after events being ignored:

Figure 342. Problem Status View after events being ignored
Reactivate
Ignored events can be reactivated by selecting them from the Ignored Status page. To reactivate
an ignore event, complete the following steps:
1. Click the Ignored Status... button to load the Ignored Status page.
2. Click the Activate button.
Figure 343. Ignored Events Tab
Figure 344. Reactivate Events

Figure 345. Activate Confirmation
The following figure shows the Problem View after reactivating the alerts and sends alert if the
average value of readings have crossed the configured threshold. Resolution event will be sent
when the average value comes below the threshold.
Figure 346. Problem View with Reactivated Alerts
Note: Resolution event is not applicable for 4690 Terminal.
Delete
Delete the current occurrence of the selected problem(s). Future events will update status
accordingly.
Figure 347. Delete Selected Problems
The following figure shows the Problem View after deleting alerts.

Figure 348. Problem View after Deleting Alerts
Note: Once deleted, an alert cannot be brought back.
Health Status config file details

The HealthStatusConfigData.xml config file for health status is located in the
%DIR_INSTALL_FOLDER\proddata\retail\healthStatus\config directory (for
example, C:\Program Files\IBM\Director\proddata\retail\healthStatus
\config). In the configuration file, map the component category, component type, condition
type, and conditionValue of each event in the "set" to a common component type, condition type
and conditionValue. The following is an example of a node as it appears in the config file.
<MappedStatusSetData>
<EventKeys>


<key>Retail.OS4690.W950</key>
<key mode="Resolution">Retail.OS4690.W951</key>
</EventKeys>
<ComponentType>OS4690</ComponentType>
<ConditionType>W950</ConditionType>
<ConditionValue>E001</ConditionValue>
</MappedStatusSetData>
In this example, the event Retail.OS4690.W951 will resolve the Critical event
Retail.OS4690.W950.E001 that was previously included.

Chapter 19. Agent Monitoring
Agent Monitoring
The monitoring functionality for RMA is redesigned in RMA V3 to:

1. Monitor systems by default using a local, agent side configuration. Systems are now
monitored immediately after installation and configuration or setup is no longer required to
begin monitoring (which was the case in IBM Systems Director 5.20).
2. Enable Generic (user defined) monitoring. With this, user can monitor any MBean/CIM
attribute conforming to the specification mentioned in “Generic (User defined) monitoring”
on page 298. The MBean/CIM attributes to be monitored should be provided/configured by
user in the GenericMonitorPolicies.xml configuration file, located at $
(RMA_INSTALL_LOC)\rma\user\rma\config\monitor on agent. On startup, RMA
reads the GenericMonitorPolicies.xml configuration file, applies all configuration
mentioned as part of the monitor/policy and starts monitoring this MBean/CIM attribute as
per the configuration.
The use of monitoring is based on monitor type:
• For system events - The events received from the system when they occur.
• For System LED Monitors - The events are sent based on the change in the LED states.
• For Hardware Sensor Monitoring and Resource Monitoring - The monitor parameters are
monitored based on the threshold values configured in the MonitorPolicies.xml file,
which can be overridden in a user configured MonitorPolicies-user.xml file.
• For SSD Life Monitor on 4690 OS - The events are sent based on the configured Threshold
that matches or exceeds the Solid State Drive's percentage of use.
• For Peripheral Monitoring - Retail POS peripherals such as POS printer and RSS Display
attributes can be monitored on agent start up. The policies (parameters) for the POS
peripherals are provided in the MonitorPolicies.xml file. The threshold values can be
overridden in a user configured MonitorPolicies-user.xml file.
• For Generic (User Defined Monitoring) - Monitor any MBean/CIM attribute conforming to
the specification mentioned in “Generic (User defined) monitoring” on page 298. The MBean
or CIM attributes to be monitored should be provided/configured by user in the
GenericMonitorPolicies.xml configuration file, located at $(RMA_INSTALL_LOC)
\rma\user\rma\config\monitor on agent.
The monitors calculate the values based on continuous observation of the respective parameter.
The values are observed continuously at an interval specified as
SamplingFrequencyInterval in the MonitorPolicies.xml file. An average of the most
recent values observed over a specified period of time is calculated to compare with the
threshold value. This period is specified by the attribute MinimumThresholdDuration in the
MonitorPolicies.xml file.
For example, in the case of a CPU Utilization monitor, the value of the
MinimumThresholdDuration is one hour (3600000 milliseconds). Each time a new value is
read, the oldest value in the set of 1-hour values is discarded, adding the current value to
calculate the average. An average of the values observed over the most recent one hour is
calculated each time a new value is read. If the average is above the threshold limit, a warning
event is sent to the IBM Systems Director. If a warning event has occurred earlier and if the
current average is below the threshold value, a resolution event is sent.
Note: SFCB has to be installed to use Monitoring on Linux Systems. The SFCB configuration
details are given in “Linux prerequisites” on page 92.

System Events
This type of monitoring exists in all versions of RMA, even prior to RMA V3. It involves the
RMA agent listening for certain types of events from the system. In RMA V3/Director 6, these
events will change the health indicator status of the system in the Director console.
Examples of the types of events RMA listens for:
• Predictive failure indications for SMART hard drives (WMI only,
MSStorageDriver_FailurePredictEvent)
• 4690 system events
• State change indications emitted by the service processors on POS systems
(RSS_SpNumericSensorAlert)
• UPOS peripheral events
• SSD Life time monitoring events (not supported on V1 Hardware Sensor driver supported
Linux systems.)
System LED monitoring

RMA V3 and later will monitor the hardware status of the hardware LEDs. The agent sends
alerts and resolution events when the LEDs change state.
Notes:
1. This type of monitoring is only supported on certain hardware and operating systems (see
Appendix B, Agent Monitoring Support on page 377).
2. On Windows and Linux systems, this type of monitoring requires the appropriate version of
the POS Sensor Drivers be installed. See “RMA software requirements” on page 30.
3. LED Monitoring is supported by Hardware Sensor Driver Version 2.
Event types - LED monitoring

Table 20 lists the different event types that are monitored under LED monitoring.
Table 20. LED Monitoring Event Types
Component Component
Event Type Categories Type Condition Type Condition
CPU Fan Retail, HW LED CPUFanFailure On, Off
Failure
Motherboard Retail, HW LED MotherboardFailure On, Off
Failure
Hard Drive 0 Retail, HW LED HDD0Failure On, Off
Failure
Power Supply Retail, HW LED PowerSupplyFailure On, Off
Failure
Info LED Retail, HW LED Info On, Off
Hard Drive 1 Retail, HW LED HDD1Failure On, Off
Failure

Hardware sensor monitoring
This type of monitoring involves monitoring hardware sensors and sending alerts if the readings
are above a configured threshold for a consecutive amount of time. Resolution events are sent
when the readings are below the threshold for a consecutive amount of time.
Some or all of the following aspects of the system are monitored:
• CPU Temperature
• CPU Fan Speed
• Enclosure Ambient Temperature
• Power Supply Fan Speed
• SSD Temperature
The threshold and configuration information for these monitors is specified in the agent
monitoring configuration (See “Configuration” on page 301).
Notes:
1. This type of monitoring is only supported on certain hardware and operating systems (see
Appendix B, Agent Monitoring Support on page 377).
2. On Windows and Linux systems, this type of monitoring requires that the appropriate
version of the POS Sensor Drivers be installed. See “RMA software requirements” on page
30.
3. System Event log monitoring is supported only on Windows machines installed with V3
Hardware Sensor Driver. The Toshiba POS System Event Log is a motherboard level storage
device that contains a record of critical system events such as POST errors, disk check errors,
etc. The System Event log monitor feature enables the agent to send events to Director
whenever there is a new log entry available in the BIOS. The events sent are Critical,
Warning, or Resolution based on the severity of the log entry. System Event log monitoring
is not supported on Linux Systems.
4. Hardware Sensor monitoring is supported on a system which supports and has installed
either the V3 or V1 version of sensor driver.
Event types listing

Table 21 lists the different event types that are monitored under sensor monitoring.
Table 21. Sensor Monitoring Event Types
Component Component
CPU Retail, HW CPU Temp Ok, Critical
Temperature
CPU Fan Retail, HW CPU Fan Ok, Critical
Enclosure Retail, HW Enclosure Temp Ok, Critical
Ambient
Temperature
Power Supply Retail, HW PowerSupply Fan Ok, Critical
Fan
Voltage Retail, HW System Voltage Ok, Critical
SSD Retail, HW SSD Temo Ok, Critical
Temperature
Chapter 19. Agent Monitoring 291

| SSD Temperature | Retail, HW | SSD | Temp | Ok, Critical |
Resource Monitoring
RMA monitors the following aspects of system performance:
• CPU Utilization
• Memory Utilization
• Disk space Utilization
The threshold and configuration information for these monitors is specified in the agent
monitoring configuration (See “Configuration” on page 301).
Note: CPU Utilization monitoring is not supported for all version of 4690 OS.
• 4690 Disk Space Monitor only monitors "FIXED" disks (C:, D:, F:) and by default is not
enabled for 4690 Terminals.
• By default, Linux Disk Space Monitor only monitors the space under "Root" File System. It is
not user configurable.
Event Types - Resource monitoring

Table 22 lists the different event types that are monitored under Resource monitoring.
Table 22. Resource Monitoring Event Types
Component Component
CPU Utilization Retail, Monitor CPU Utilization Warn, Normal
Memory Retail, Monitor Memory Utilization Warn, Normal
Utilization
Disk Space Retail, Monitor Disk Available Disk Warn, Normal
Utilization Space
SSD Life Monitoring on 4690 OS
With this feature, the user will have the ability to monitor end of life of SSD on 4690 enhanced
Controller, enhanced Terminal and enhanced Controller/Terminal machine from the time RMA
agent starts.
A critical event is logged in the Director UI when SSD needs to be replaced as its usage
percentage reaches the configured threshold value. This event will change the health indicator
status of the system in the Director console.
Event type listing
Table 23 lists the event type that is monitored under SSD Life monitoring for 4690.

Table 23. Event types monitored under SSD Life monitoring for 4690
Component Component Condition Condition Event
Event Type Category type Type Value Severity
SSD Life Retail, hw, ssd writepercenta failureimmine Critical
Monitoring storage ge nt
Notes:
1. SSD End of Life monitoring is not supported for all version of 4690 OS. The SSD Life
Monitor MBean was created only from 4690 build number V6R3 0CD0 (Dec. 2012 CSD).
2. No resolution event will be supported.
3. MinimumThresholdDuration attribute is not applicable for this monitor as the Threshold
is not calculated based on the average values over the interval. The monitors checks for the
Threshold at an interval specified as SamplingFrequencyInterval. If the observed
Threshold is equal to or more than the configured Threshold, then a Critical Event is logged
in Director UI.
Figure 349. SSD Life Monitoring Critical event properties
Peripheral Monitoring
End of life monitoring of Toshiba Global Commerce Solutions Retail POS peripherals, such as
POS Printers and RSS Displays, is supported.
Pre-requisites:

• Appropriate drivers (UPOS driver or Specific device driver) need to be installed and
configured properly. For Ex: For POS printers, UPOS driver needs to be installed and
configured. For RSS Displays, "Monitor Inventory drivers" needs to be installed.
• In Windows, POS Control Center needs to be configured and enabled. User needs to
explicitly do "start statistics" to claim the device/POS Printer.
• On attaching the printers/Display, it is advised to run inventory in Director 6 for the MEP to
which these devices are attached. Post successful inventory collection, verify POS printers or
display are listed under the "Hardware Devices" section of the inventory report.
• POS System/RMA has to be stopped before attaching/unplugging the peripherals. Once
peripherals have been attached/unplugged, POS System/RMA can be started.
End of Life monitoring of POS Printer attributes

End of Life monitoring of POS Printer attributes is supported on Windows and OS4690
platforms. The POS printer attributes that will be monitored and their End of life threshold
values are provided below.
Table 24. End of life thresholds for POS printer attributes
POS printer Attribute End of life threshold

ReceiptLineFeedCount 36 Million
SlipLineFeedCount 5 Million Lines
SlipCharacterPrintedCount 200 Million Chars
PaperCutCount 1.5 Million counts
ReceiptCoverOpenCount 5000
Note: Pre-defined monitor policies for the end of life monitoring of the POS printer attributes
mentioned above will be provided in the existing MonitorPolicies.xml file for an agent.
When RMA starts, the monitor will be started with default attribute values.
When the attribute values listed in the table above meet the threshold criteria value (as per the
policy set in the MonitorPolicies.xml file), a warning event (as per the configuration in
policy file) will be sent to Director and will be logged against the agent to which the POS printer
is attached. The warning events will be reflected in the health status of the MEP and will be
shown in the Active Status tab of the MEP as well.
A snapshot of the warning event that will be sent when the PaperCutCount POS Printer
attribute reaches the threshold value is provided below.

Figure 350. PaperCutCount threshold reached warning event
Resolution events will be sent:

• When the attribute values comes back to the normal range.
• When a printer, for which a warning event was sent (for any of the attributes monitored
crossing the threshold), is replaced by another printer. The warning events for the old printer
are no longer relevant and will be resolved with the resolution (info) event shown below. The
resolution event will display the same event text and a Trigger value of 0. Monitoring will be
freshly started on the newly attached printer.
Figure 351. Resolution event for POS printer attributes
The event details are provided in the table below.

Table 25. Details for Resolution event for POS printer attributes
Event type Component categories Component type Condition type Condition value
POS Printer attribute Retail, Monitor POS Printer Serial Number PaperCutWarn Warn/Normal
PaperCutCount For Ex: 41-ZKLPX
POS Printer attribute Retail, Monitor POS Printer Serial Number ReceiptLineFeedCountWarn Warn/Normal
ReceiptLineFeedCount For Ex: 41-ZKLPX
POS Printer attribute Retail, Monitor POS Printer Serial Number SlipCharacterPrintedCountWarn Warn/Normal
SlipCharacterPrintedC For Ex: 41-ZKLPX
ount
POS Printer attribute Retail, Monitor POS Printer Serial Number SlipLineFeedCountWarn Warn/Normal
SlipLineFeedCount For Ex: 41-ZKLPX
POS Printer attribute Retail, Monitor POS Printer Serial Number ReceiptCoverOpenCountWarn Warn/Normal
ReceiptCoverOpenCount For Ex: 41-ZKLPX
Notes:
1. When OS 4690 controller/terminal is configured on the same machine, monitor will run only
on the controller and all the events will be shown against the controller MEP. If controller
and terminal are configured on different machines then monitor will run wherever the
printers are attached, i.e. on terminal.
2. Only one POS Printer can be attached to the terminal/POS system at a time.
End of life monitoring of RSS display

End of Life monitoring of RSS Displays is supported on Windows Platform. Multiple RSS
Displays can be attached to the POS System and all can be monitored for End of Life. The RSS
Display attribute that will be monitored and it's End of life value is provided below.
• HoursPoweredCount - 60000
When the value of the HoursPoweredCount attribute crosses the threshold value 60000, End of
life of RSS Display can be inferred.
A pre-defined monitor policy for end of life monitoring of the HoursPoweredCount RSS
Display attribute will be provided in the existing MonitorPolicies.xml file for an agent.
Note: Monitoring of the RSS Display will start approximately 3 minutes after agent start up. This
delay is to account for the two instances in which the RSS Display registers with the RMA
MBeanServer. This delay is configurable with the InitialSampleDelay parameter, which will
be present as part of the WinRSSDisplayEOLMonitor policy provided in
MonitorPolicies.xml.
When the above attribute value meets the threshold Criteria value (as per the policy set in
MonitorPolicies.xml), a warning event (as per the configuration in policy file) will be sent
to Director and will be logged against the agent to which the RSS Display is attached. The
warning events will be reflected in the health status of the MEP and will be also shown under
the Active Status tab of the MEP.
A snapshot of the warning event that will be sent when the HoursPoweredCount RSS Display
attribute reaches the threshold value is provided below.

Figure 352. Warning event for HoursPoweredCount threshold reached
If the RSS display for which the warning event was sent is replaced by another RSS Display or if
the monitored value of the RSS_Display MBean attribute HoursPoweredCount is below 60 K, a
resolution event will be sent and displayed in the Event Log tab of the Director 6. This resolution
or info event will resolve/remove the earlier warning event in the Active status tab of Director 6,
which will also reflect the health status of the MEP.
Figure 353. RSS Display resolution event for HoursPoweredCount attribute

Generic (User defined) monitoring
With Generic (user defined) monitoring, the user can monitor any CIM or MBean attribute on
Windows and OS4690 platforms. The CIM/MBean attributes to be monitored should conform to
the specification explained in “MBean/CIM specification” on page 300.
Generic (user defined) monitoring will be applicable to monitoring the following CIM/MBean
attribute types:
• Numeric (int, long, double values)
• String
• Boolean
The MBean or CIM attribute to be monitored should be provided/configured by user in the
GenericMonitorPolicies.xml configuration file, located at RMA_INSTALL_LOC)\rma
\user\rma\config\monitor on agent. A sample file, by name
GenericMonitorPolicies_Sample.xml, will be provided by RMA and located at
%RMA_HOME%\user\rma\config\monitor. Users can refer to the sample file to create a
monitor/policy of their own to monitor any CIM/MBean attributes.
A unique monitor/policy needs to be created for each CIM/MBean attribute to be monitored. The
GenericMonitorPolicies.xml file can contain multiple policies, each one monitoring a
single attribute of an MBean or CIM class.
On startup, RMA reads the GenericMonitorPolicies.xml configuration file, applies all
configuration mentioned as part of the monitor/policy and starts monitoring this MBean/CIM
attribute as per the configuration.
When the monitored attribute value reaches or crosses the threshold value, a warning or critical
event, as configured by the user, will be sent from the agent.
A snapshot of the warning event generated by the RMA Generic Monitoring infrastructure when
the PowerState POS Key Board attribute crosses the threshold value of 2000 is shown below.

Figure 354. Generic (user defined) warning event for PowerState attribute
Resolution event will be sent under the conditions mentioned below:

1. Monitored attribute value goes below the threshold value. When an error condition is
resolved, a resolution event will be sent from the agent. This will clear the existing critical
event under the Active Status tab of the respective MEP. When a warning condition is
resolved, a resolution event will be sent from the agent. This will clear the warning event
already existing in the "Active Status" tab of the respective MEP.
2. When CIM/Mbean instances that were being monitored are removed or not available, and a
critical/warning event was sent previously for these instances, a resolution event will be sent
with a "Trigger" value of 0. The resolution event semantics remain the same as in case 1
shown above.
A snapshot of the resolution event generated by the RMA Generic Monitoring infrastructure
when the PowerState POS Key Board attribute value goes below the threshold value of 3000 is
shown below.

Figure 355. Generic (user defined) Resolution event for PowerState attribute
MBean/CIM specification
The MBeans provided by RMA and OS4690 conform to the JMX MBean specification and have
the below mandatory Key value pairs.
If the user wants to monitor other third party MBeans, the MBean has to conform to the JMX
specification and needs to have the below mandatory key value pairs in the MBean Object
Name.
SIFType=TestMBean
Where SIFType is the key name and TestMBean is the MBean name. All RMA and OS4690
MBeans have this Key Value pair.
OR
AnyKey=TestMBean
Where AnyKey is the key name and TestMBean is the MBean name. This is to support any third
party MBeans.
DeviceId=hostname
Where DeviceId is the key name and hostname should be the name of the host where agent is
running.
For Ex: The Memory MBean object Name will be as follows:
masteragent:Id=Memory,SystemId=ma-NR.
10150,SIFType=Memory,SIFMBean=true,SIFComponent=JAVA,DeviceId=NR
Note: MBean and MBean attribute names are case sensitive. User should provide the appropriate
values, else monitors will not start.

For monitoring CIM class/attributes, Windows wbemtest.exe has to be executed first. The
availability of the CIM classes/instances and attributes that need to be monitored has to be
confirmed first with this application.
Configuration
The configuration for RMA agent monitors is stored in %RMA_HOME%\user\rma\config
\monitor. There is a base file, MonitorPolicies.xml, which specifies the default
configuration. The base file should never be edited or deleted. It will be updated each time the
RMA agent is upgraded. Deleting the base file will result in disabling Monitor functionality in
the agent. To override the defaults, create a file named MonitorPolicies-user.xml. In this file you
can disable monitors, change application criteria, or specify override values for thresholds and
parameters.
Example:
Figure 356. Agent Monitoring
MonitorPolicies.xml property definitions:

The following describes property definitions:
Warning Threshold
The value, which when crossed either above or below, is dependent on the monitor for
which a warning condition is valid. The units for the threshold depend on the specific
monitor.
Error Threshold
The value which when crossed either above or below dependent on the monitor for
which a error condition is valid. The units for the threshold depend upon the specific
monitor.

SamplingFrequencyInterval:
The periodic rate, in milliseconds, for which a monitor will request a refresh of data from
the device. If the SamplingFrequencyInterval is 120000, then the monitor will request data
every two minutes.
MinimumThresholdDuration/MinimumDurationForWarningThreshold:
The amount of time, in milliseconds, for which the average of the samples must cross the
WarningThreshold before a warning event is sent.
Given a sampling frequency of two minutes and a minimum threshold duration of one
hour, there would be 30 samples taken before an average of the samples is calculated.
This average value is then compared against the warning threshold and an event is
generated when the average value crosses the warning threshold. When a new sample is
collected, the oldest sample will be dropped from the collection before recalculating the
average of the samples. The trigger value which is the average value of samples will be
shown in Event Properties in Director Console.
MinimumDurationForErrorThreshold
The amount of time, in milliseconds, for which all sample values must cross the
ErrorThreshold before a critical event is sent.
Given a sampling frequency of two minutes and a minimum duration for error threshold
of one hour, there would be 30 samples taken before checking the criteria to send error
event. These 30 samples are then compared against the error threshold and error event is
generated only when these 30 samples cross the error threshold value. When a new
sample is collected, the oldest sample will be dropped from the collection before
comparing the samples for error criteria. Unlike Warning event, Error event is not
triggered for a single average value since a set of samples need to be compared against
Error Threshold. So Trigger value will not be shown in Event Properties in Director
Console. Instead Trigger Criteria will be shown with details as "Sustained high
temperature".
PersistedMonitorValidityPeriod:
When the agent is restarted, the monitors are initialized with their previous state. If a
monitor previously sent a warning event, then when the agent is restarted it would keep
a persistent setting and not send another event. The PersistedMonitorValidityPeriod is
the value, in milliseconds, which determines how long the last monitor state will persist.
For OS4690, this value pertains to controllers only. Event status is not persisted for
terminals.
ResendDelay (in milliseconds):

The period of time, in milliseconds, that must elapse after sending an event before the
event will be resent. This will occur regardless of the value provided for the Persisted
Monitor Validity Period.
InitialSampleDelay
Applicable if a policy is intended to monitor an MBean class/attribute. This is an optional
tag. The delay (amount of time in milliseconds) for the initial sampling trigger to kick off
from the agent start time. This tag applies to the first sample only. If this tag is not
provided, then the first sampling trigger happens on the agent start up.
Tag is required when multiple instances are present for an MBean and it takes a couple of
minutes for all instances to register with RMA MBeanServer. The InitialSampleDelay
value can be approximately 2 to 3 minutes, by which time all instances of MBean being
monitored register with MBeanServer and when the first sampling trigger occurs, all
instances will be available. User can configure InitialSampleDelay value appropriately
based on the number of new MBeans/instances that get registered with the RMA
Mbeanserver.

InitialSampleDelay will also give enough time for event control listener registration and
will avoid losing terminal startup events.
<Parameter name="InitialSampleDelay" type="java.lang.Long>180000</
Parameter>
Notes on the resending of events:

Sensor monitors (cpu temp, cpu fan, power supply fan, etc) events will be resent if the
threshold is exceeded at the next threshold duration expiration.
Events from LED monitors and utilization monitors (cpu, disk, memory, etc) will not be
resent. The exception to this is the Windows disk utilization monitor that applies to the
re-send delay.
Note: If any invalid value is present for the above attributes (except
PersistedMonitorDataValidityPeriod), that corresponding monitor will not be started and a
warning event will be sent to Director. For PersistedMonitorDataValidityPeriod, Monitor will be
continued by setting default value for this and a warning event will be sent to Director.
GenericMonitorPolicies.xml property definitions

To enable Generic (user defined) monitoring, the configuration shown below is necessary.
AgentMonitor id
Identifier for the Monitor or policy. A unique and concise identifier should be given. This
Id will be used as key and will be part of the generic monitor events sent to the
management application.
Since monitor id is used to persist the event in the file system, OS file name validation
check will be applicable. In all of the attributes and parameters, only these characters are
valid: a-z A-Z 0-9 . _ @ # $ ! - and space
Criteria
Tag can be used if this monitor needs to be applied, only if the given criteria is met. The
criteria tag is optional. If this tag is not mentioned, the policy will apply to any system.
The Criteria tag is a combination of OSType, DeviceType, HardwareTypes, MachineType,
Model, and ModelPattern tags which are explained below.
• OSType specifies the Operating System on which this monitor needs to be run. Valid
options for this are : Windows or 4690.
• DeviceType is applicable only for 4690 and is used to differentiate between the
controller and terminal. Valid Options : EnhancedController, EnhancedTerminal,
ClassicController, ClassicTerminal.
• HardwareTypes are checked against the machine model number on which agent is
running. Ex:
<HardwareTypes>
<MachineType name="4800">
<Model>723</Model>
<ModelPattern>[7,C,F]43</ModelPattern>
</MachineType>
</HardwareTypes>
Description
The description of the monitor functionality. This tag is optional.

DataObjectName
CIM Class name or MBean class name which needs to be queried to get the attribute
value (e.g. UPOS_POSPrinter). This value is case sensitive and user needs to provide
the appropriate value. If the MBean is not available or not registered with RMA, RMA
will register a listener with MBeanserver for its availability and keep waiting until it is
available. Monitors will not be started until MBean is available.
This tag is mandatory.
DataObjectType
Represents the type of class mentioned in DataObjectName tag. Values can be either
MBean or CIM. If type value is CIM, a CIM query will be made to get the class mentioned
in DataObjectName. If type value is MBean, the DataObjectName class will be queried
in the MBean server.
This is a Mandatory tag.
UniqueAttributeName
A Unique attribute name of CIM class or MBean class, which should be key differentiator
between multiple instances of the MBean class or CIM class. For ex: Attribute
SerialNumber of MBean UPOS_POSPrinter will be the key differentiator between
multiple instances of POS printers.
This tag is mandatory if monitoring multiple devices of the same type attached to the
POS System. In this case, multiple MBean instances corresponding to multiple devices
will be available for the same MBean / CIM Class. This tag is needed in order for events
from these instances to be uniquely identified.
For example: Consider two RSS Displays (MBean representing RSS Display will be
RSS_Display) are attached to the POS machine. On RMA start up, for RMA
MBeanServer, two instances of the RSS_Display MBean will be available. To monitor
both (multiple) RSS Displays, the UniqueAttributeName tag should be provided and
the value can be "SerialNumber," as each RSS Display will have a unique serial number.
UniqueAttributeValue
The value of UniqueAttributeName, which is explained above. This value must be
used when there are multiple instances of an MBean and one instance among them needs
to be monitored.
For example: Consider 2 RSS Displays, Display1 and Display2, attached to the POS
system (The MBean for RSS Display will be RSS_Display). On the agent start up, the
corresponding MBean instances for these 2 RSS Displays will be available. The MBean
attribute HoursPoweredCount needs to be monitored for only Display2. The
UniqueAttributeName can be "SerialNumber," as this attribute value will be different
for each Display. The UniqueAttributeValue can be the value of the serial number of
RSS Display2 (i.e. 41-zdcfh). A snippet of the monitor policy for this example is provided
below.
<Parameter name="DataObjectName" type="java.lang.String">RSS_DisplayRSS</

Parameter>
<Parameter name="DataObjectType" type="java.lang.String">MBean</Parameter>
<Parameter name="ObservedAttributeType" type="java.lang.String">Numeric</
Parameter>

<Parameter name="UniqueAttributeName" type="java.lang.String">SerialNumber</
Parameter>
<Parameter name="UniqueAttributeValue" type="java.lang.String">41-zdcfh</
Parameter>

ObservedAttributeType
The type of the MBean or CIM Class attribute to be monitored (ObservedAttribute).
This tag is Mandatory. The value can be either Numeric" or "String.
• "Numeric", if the ObservedAttribute value is of type: int, long, double, float, Byte.
String with Numeric value in it is also supported. In this case, the Numeric value will
be inferred and will be used in numeric sample value calculations as applicable (such
as taking average when MininumThreshodDuration tag is set).
• "String", if the ObservedAttribute value is of type String.
<Parameter name="ObservedAttributeType"
type="java.lang.String">Numeric</Parameter>
NameSpace
CIM Namespace value. This is applicable only to policies where CIM class/attribute
monitoring will be done. This is an optional tag.
If user doesn't provide this tag, and a policy is provided for CIM class/attribute
monitoring, by default RMA Generic monitoring infrastructure will use the CIM
Namespace as root\cimv2, which holds good for Windows platform.
HostName
The host name to use for CIM Connection. This is applicable only to policies where CIM
class/attribute monitoring will be done. This is an optional tag.
If user doesn't provide this tag, and a policy is provided for CIM class/attribute
monitoring, by default RMA Generic monitoring infrastructure will assume the value as
"localhost", i.e. it will try to connect to CIM Server on the same machine.
<Parameter name="HostName" type="java.lang.String">localhost</
Parameter>
ThresholdTestCondition
This is the test condition applicable if observed attribute value is of type Numeric. The
test conditions can be either "above" or "below". This is an optional tag and if not
provided, a value of "above" is assumed for this tag.
If a value of "below" is given, event will be generated when the samples reach or come
below the specified threshold value. If "above" is given, event will be generated when the
samples reach or cross the specified threshold value.
TestWarningThreshold
Enables monitoring for warning thresholds. This tag is mandatory if a "Warning" event
needs to be sent from the agent on crossing the threshold value provided in the
WarningThreshold tag). The boolean value "true" must be provided for this tag.
If this tag is not provided, a "false" value will be assumed.
<Parameter name="TestWarningThreshold"
type="java.lang.Boolean>false</Parameter>
TestErrorThreshold
Enables monitoring for error thresholds. This tag is mandatory if a "Critical" event needs
to be sent from the agent on crossing the error threshold value provided in the
ErrorThreshold tag). The boolean value "true" must be provided for this tag.
If this tag is not provided, a "false" value will be assumed.
<Parameter name="TestErrorThreshold"
type="java.lang.Boolean>true</Parameter>

InitialSampleDelay
tag.
The delay (amount of time in milliseconds) for the initial sampling trigger to kick off from
the agent start time. This tag applies to the first sample only. If this tag is not provided,
then the first sampling trigger happens on the agent start up.
Tag is required when multiple instances are present for an MBean and it takes a couple of
minutes for all instances to register with RMA MBeanServer. The
InitialSampleDelay value can be approximately 2 to 3 minutes, by which time all
instances of MBean being monitored register with MBeanServer and when the first
sampling trigger occurs, all instances will be available.
User can configure InitialSampleDelay value appropriately based on the number of
new MBeans/instances that get registered with the RMA Mbeanserver.
InitialSampleDelay will give enough time for event control listener registration and will
avoid losing terminal startup events.
<Parameter name="InitialSampleDelay" type="java.lang.Long>180000</
Parameter>
MBeanUniqAttrValInstanceAvailRetryCount
tag.
The number of sampling intervals RMA must retry for the required MBean instances to
be available. If this tag is not specified, the default value will be 5 sampling intervals. If
the InitialSampleDelay parameter is provided with an appropriate value, by the
time first sampling trigger happens all MBean instances will be available and retries may
not be needed.
Note: RMA starts monitoring only when at least one MBean instance of the MBean to be
monitored, as part of the policy, gets registered with MBeanServer. When multiple
instances are present for an MBean it takes a couple of minutes for all of them to get
registered with RMA MBeanServer.
<Parameter name="MBeanUniqAttrValInstanceAvailRetryCount"
type="java.lang.Integer>5</Parameter>
CIMConnectRetryCount
Parameter is applicable if a policy is intended to monitor a CIM class/attribute. This is an
optional tag/parameter.
Specifies the number of sampling frequencies the monitor will retry to get the value of the
ObservedAttribute from the CIM. This will be utilized by RMA only in a scenario
where the instance of the CIM class to be monitored is not available when RMA starts.
If not specified, a default value of 10 will be assumed.
<Parameter name="CIMConnectRetryCount" type="java.lang.Integer"
type="java.lang.Integer>10</Parameter>
DefaultMonitorState
Applicable if a policy is intended to monitor an attribute of type String. This is an
optional tag/parameter.
Indicates the type of event to be sent if observed attribute value has a value other than the
one specified in tags ErrorStrings, WarningStrings, NormalStrings. By default,
this will be taken as normal if not specified. Tag is useful when user knows only normal

string values and wants a warning/error event to be sent for any string other than
specified NormalStrings. Scenario is explained in the section below.
ErrorStrings, WarningStrings, NormalStrings

Attributes ErrorStrings, WarningStrings and NormalStrings are applicable for
monitoring MBean/CIM class attributes of type String.
The attribute ErrorStrings can be configured if Critical events are configured/needed.
The String values that represent error value can be provided here. The values must be
separated by comma and enclosed in square brackets.
<Attribute name="ErrorStrings"
type="[Ljava.lang.String">[errString1,errString2]</Attribute>
The attribute WarningStrings can be provided if Warning events are configured/
needed. String values that represent warning value must be provided here. The values
must be separated by comma and enclosed in square brackets.
<Attribute name="WarningStrings"
type="[Ljava.lang.String">[warnString1,warnString2]</Attribute>
The attribute NormalStrings can be provided with values that represent resolution
values. The values must be separated by comma and enclosed in square brackets.
<Attribute name="NormalStrings" type="[Ljava.lang.String">[]</
Attribute>
If the observed attribute has a string value other than the values mentioned in
WarningStrings, ErrorStrings and NormalStrings, action will be taken based on
parameter DefaultMonitorState.
Notes:
1. At least one of the WarningStrings, ErrorStrings or NormalStrings
attributes must be provided based on user requirements.
2. If attributes ErrorStrings and WarningStrings are not specified, the
DefaultMonitorState parameter should not be Normal.
The semantics of the other attributes mentioned as part of the <AttributeList> tag remains
the same as explained in “MonitorPolicies.xml property definitions:” on page 301.

Chapter 20. Software Distribution
Software Distribution
IBM Systems Director with retail extensions provides the capability to create and manage retail
software packages that can be installed on Retail managed systems, as well as, facilitate and
schedule these packages for delivery and installation on the systems.
The Director Update Manager feature provides the ability to scan the software inventory of
systems to find systems that are not up to date.
This section describes the tools and functionality required to create and manage software
packages.
RMA Package Overview

RMA Packages in V3 still use the same package jar format used in previous versions. There will
be a single RMA Director package for both MA and GA. The integration with Update Manager
provides some new features, conventions and requirements.
In RMA V3, RMA packages support separate staging and installation phases when distributed
using the Update Manager feature in IBM Systems Director.
RES Software Package Manager

RES Software Package Manager application provides the capability to create and manage the
software distribution packages. This section describes the following features and uses of the
package manager:
• Launching the Package Manager
• Creating Packages
• Managing Packages
Launching the RES Software Package Manager

Users can launch the RES Package Manager in one of two ways:
• Locally from the RES/Director Server
• Remotely from the Director Console using Java WebStart
Launching locally
The resSwPkgMgr.bat file in %RES_HOME%\bin will allow users to launch the
application locally. It will connect to the locally running RES.
Launching from IBM Systems Director Console

A targeted task on the RES MEP in the Director Console will allow users to launch the
package manager using Java WebStart. The Java WebStart application will connect
directly to RES and will require a separate authentication.
To launch the RES Software Package Manager from the Director Console using Java WebStart,
follow these steps:
1. On the Director console, in the left navigation pane, click Resource Explorer. On the
Resource Explorer page, right click on RES MEP. In the menu, click Release Management
and then Launch RES Software Package Manager.

Figure 357. Launching RES Software Package Manager
2. RES Software Package Manager, on connecting to RES, will present a "RES Authorization
Management" pop-up, prompting for user authorization. Provide system log in credentials.
Note: If a new user is added with administrative privileges and also to RES Admin and
SMAdmin groups on a RHEL server using command prompt, RES service needs to be
restarted before this user can be used to authorize RES.
Figure 358. RES Authorization Management window

3. On successful authorization, RES Software Package Manager application user interface will
be presented.

Figure 359. RES Software Package Manager application user interface
Creating packages using the RES Software Package Manager

Example:
This example explains how to create a custom package ( with a sample.txt file and simple
commands) with RES Software Package manager. The packages created can be later distributed
to the MA or GA using Director Update Manager.
1. On the Director Server machine, create a simple text file (using the Microsoft Notepad
application). Type "hello" in the text file, and save it as C:\sample.txt.
2. Launch the RES Software Package Manager. On the Menu bar of the application, click File >
Create Package to start creating a package.
Chapter 20. Software Distribution 311

Figure 360. Create Package in RES Software Package Manager
3. A screen to provide general information about the package to be created will be presented.
Provide the package name, package description, and select the appropriate OS on which the
package has to be installed. If only performing installation, select Installation Only. If the
staging and installation process has to be separated, select Separate Staging and
Installation. If Installation only is selected then the Windows Installation Information form
will be presented first. Otherwise, the Windows staging information form will be presented
first, followed by the Windows Installation Information.
Note: Windows, Linux and 4690 Operating Systems are currently supported. The package
manager will present the appropriate form to the user depending on the 'Target OS'
selected.

Figure 361. Enter General Information for package
4. In the Windows Staging Information or Windows Installation Information window, provide
the Staging Destination Directory or Installation Destination Directory details as to which
location the package has to be staged or installed on target agent. For example, enter c:
\temp.

Figure 362. Enter staging destination directory for package

Figure 363. Enter installation destination directory for package
5. Click Files and select the files that should comprise the package, for ex: sample.txt. Click the
right arrow button to add the file to the list of selected files on the right. Click OK. Folders
may also be selected. If all subfolders are to be staged or installed then the Include
subfolders option must be checked.

Figure 364. Select package files
6. Click Commands and then Add to enter your first command. For Windows command, use
cmd.exe /c to execute your command (you can use ${client.target.path} instead
of c:\temp for the target directory). See “Package environment” on page 321.
Note: Path and Arguments values need to be appropriately entered depending on the
chosen 'Target OS'.
Figure 365. Enter first command

7. Click Add again to enter a second command to remove the target directory using cmd.exe
also. Click OK.
Figure 366. Enter second command

8. The entered two commands will look like the following. Click OK.
Figure 367. Package Commands window

9. Select the appropriate Installation Target State and Post Installation Action and click Next.
Note: For the 'Restart Computer with Return File' option, the RMA start up service start
must be manual (not automatic) on the target system. After the system restarts as part of
command execution (prior to starting the service), create the Return Code (text) File in the
specified path. Make sure the Return Code File contains the expected Return Code. If this in
not done, an error is logged in the job log file.

Figure 368. Installation Target State and Post Installation Action
10. The Update Manager Product Information window will be presented next. Select the
appropriate product name from the drop down box. Otherwise, select Supply Product
Name Manually and enter the custom name of the product. Provide the product version.
Click Next.

Figure 369. Update Manager Product Information window
11. The Save Package window will be presented next. Click Finish to create the package. The
created package will be stored in %RES_HOME%\data\swpkgs.

Figure 370. Save Package window
12. The newly created package will show up in the application as shown below.
Figure 371. Newly created package visible in application

Package environment
When commands are processed on the RMA agent, they are invoked as child processes from
within the RMA service. They run in the background under the same user account as the RMA
Service itself (the LocalSystem account on Windows). The environment will not be the same as if
running as a normal user.
The default PATH for the RMA Service on Windows is:
%RMA_JAVA_PATH%\\bin\\classic;%RMA_JVM_DLL_PATH%;%RMA_JAVA_PATH%\\bin\
\server;%RMA_JAVA_PATH%\\bin\\client;%RMA_JAVA_PATH%\\bin;%RMA_HOME%\
\lib;%RMA_HOME%;%SystemRoot%\\System32;%SystemRoot%\\System32\\WBEM;
%SystemRoot%;%RMA_PATH_EXT%
The RMA_PATH_EXT system environment variable can be used to extend the RMA path. This
environment variable needs to be explicitly set and extended as needed.
Please follow these recommendations when creating/testing packages:
• Before attempting to run packages/commands using an RMA software distribution package,
you should test the commands on a real command line in order to work out command
sequences, response files, and return codes.
Note: Since RMA runs as a background service, the command used should be non-
interactive.
• For testing return codes on Windows, echo the %ERRORLEVEL% variable after your command
runs. You may need to use exit /B if running a .bat file.
• The commands/processes created run in the background (can be viewed in Windows Task
Manager) and cannot assume any interactive user input. If they do, the package will appear
to be hung because it is running in the background waiting for user input. For this reason,
you should always prefix commands with cmd.exe /c on Windows and command.286 -C
on 4690.
• With the exception of system commands like cmd.exe, specify the full path to any
commands /.bat files.
• The directory where commands are run is %RMA_HOME%.
Staging and installation of packages on target systems

Software distribution packages created by RES Package Manager can be staged and installed on
managed systems using the IBM Systems Director Update Manager or any other management
application that can connect to RES. See “Using Update Manager for staging and installing
updates” on page 334 .
RES Software Package Manager: managing packages

RES Software Package Manager provides the capability to manage, edit and remove the
packages.
When RES Software Package Manager is launched, you are presented with a list of preexisting
software packages (obtained from RES).

Editing pre existing packages
1. Launch the RES Software Package Manager. The preexisting/saved packages will show up
in the user interface.
Figure 372. View of existing packages in RES Software Package Manager

2. Select the package that needs to be edited and select Edit in the menu bar. Click Edit
Package.
Figure 373. Edit package in RES Software Package Manager

3. Change the necessary attributes using the wizard.

Figure 374. Edit package wizard
4. Click Finish to complete the edit.

Figure 375. Finish and save edits to package
Note: After a package is edited, it has to be re-imported into Director for distribution. At
present, an edited package with the same Product Name and Product Version can be re-
imported/acquired by Director, but cannot be staged or installed. A clean-up command,
smcli cleanupd -m -F -v <package name> must be executed in a command window on the
Director server first (Special characters, such as a $, must be escaped on the Linux command
line). The edited package can then be imported and staged or installed into Director using
Update Manager. (Refer to the “Using Update Manager to import packages” on page 326
section). To see names of imported packages execute the following command: smcli lsupd.
If a package is edited and either the Product Name or Product Version is changed, the
package can be successfully acquired and staged or installed using Update Manager.
Removing the packages

1. Select the package to be removed. Select Edit from the menu bar and click Remove Package
to delete the package.

Figure 376. Remove package
2. Click Yes to delete the package.
Figure 377. Delete package

Using Update Manager
This section describes how to use the Update Manager feature to manage software updates for
retail systems in IBM Systems Director.
Using Update Manager to import packages

This section describes how a software package can be imported into the Director directory
system using Director Update Manager.
Director Update Manager can be used to import and distribute software packages to target
agents. In the Director console, in the left navigation pane click Release Management and select
Updates.
Figure 378. Importing Packages using Update Manager
The process of importing and distributing software packages using Update Manager is
comprised of two steps:
1. Acquire updates
2. Show and install updates

Step 1- Acquire Updates
Click onAcquire Updates and the Acquire Updates window displays.
There are two ways in which updates can be acquired:
from the internet

This method is used for packages created using the RES Package Manager. Even though
the Director Console states an Internet connection is required, packages created using the
RES Package Manager will be visible.
from the server's file system

This method of acquisition will only be used for packages created outside of the RES
Package Manager. Examples would be RMA Agent updates included on the RMA DVD,
IBM Systems Director updates, or any other package where the descriptor files have been
supplied. It involves selecting an update file or directory from the server's file system to
be imported into Director.
From the Internet

Update Manager connects to the RES machine and gets the updates created by the RES Software
Package Manager, and shows the retail updates available under the Retail Updates folder.
1. Select Check for updates (Internet connection required).
Figure 379. Check for updates

2. Select the package (or multiple packages) under Retail Updates and click Add. This moves
the selected package to the right panel. Then click OK.

Figure 380. Select and add packages to be updated
3. Update Manager launches Import Job and provides you with job scheduling options.
Figure 381. Job scheduling options

4. Select Run Now if Job has to be run immediately or select Schedule if Job has to be
scheduled later. Provide the appropriate schedule timings.
5. Click OK.
The import process copies the files into the Update Manager directories and adds information
about the updates to the Director database. When importing from RES, the files are copied from
their location in RES into a separate location in Update Manager (Director_install_Dir\data
\updateslib\Retail). As part of the acquisition process, a compliance check job will be spawned.

Depending on the number of online end points in the system, this job could take a considerable
amount of time.
Locally from the server’s file system

1. In the Acquire Updates window, select Import update from the file system.
Note: Only one package at a time can be selected for import.
Figure 382. Import updates from file system

2. Provide the absolute path or click Browse and browse to the directory on the server
containing the package files. This should be the directory containing the .dd and .sdd
descriptor files, as well as, all other package files. Click OK.

Figure 383. Browse to directory containing package files
3. Import Job will be launched. You can select Run Now if you want to run the import
immediately, or select Schedule if you want to schedule the import job for later. Click OK.
The import process copies the files into the Update Manager directory
(Director_install_Dir\data\updateslib\Retail) and adds information about the
updates to the Director database.
Figure 384. Import Job window

4. To check the Job status click Display Properties.

Figure 385. Import Job status
5. The Active and Scheduled Jobs window will be presented with the status of the import job.
As part of the acquisition process, a compliance check job will be spawned. Depending on
the number of online end points in the system, this job could take a considerable amount of
time.
Figure 386. Active and Scheduled Jobs window
Using Update Manager for scanning systems for updates

Acquiring a package in Update Manager triggers a compliance check for a successful post
acquisition. This might take several minutes to complete. Do not click the Show and Install
Updates link until compliance checking is complete.
1. Go to the Update Manager home page and click the Show and Install Updates link. The
"Show and Install Updates" page will open.

Figure 387. Show and Install Updates
2. The selected systems dropdown list will either be empty or will have the selection from a
previous invocation. Clicking the Browse button allows the you to change the list of systems
or groups that will receive the updates.
Figure 388. List of selected systems

3. After a set of systems has been selected, click Add and click OK.
4. Click Show And Install Updates on the Show And Install Updates page and Update
Manager initiates the scanning for available and applicable updates for a MEP or group of
MEPs. Make sure inventory is up-to-date for the chosen MEPs. This process scans a selected
group of systems for optional and required updates/packages by comparing the versions of
the imported updates with the versions in software inventory.
Note: When Show and Install Updates is clicked, the system determines which updates
apply to each of the selected targets. If one or more targets have not been inventoried, the
following error message is displayed.
Figure 389. Error message
As the error message explains, inventory must be collected on the selected systems in order
for the scan to proceed. The reason for this is that the scanning process compares the
information for each update with the information in software inventory.
After the inventory on all selected systems are up-to-date, the scanning process will list the
set of applicable updates.

Figure 390. List of applicable updates
5. Select the updates from the table to be staged or installed. You can click the link of updates
in the table to get more information about the update.
Note: Non-inventoried custom packages created using RES SW Package Manager will
always be shown under "Updates Needed By MEP..." even though those packages are
already installed.
Using Update Manager for staging and installing updates

From the list of updates for a group of systems, packages/updates can be staged or installed.
Staging is an optional step which allows package files to be transferred to the target systems
before initiating the installation/update. This can be used to stage large updates in preparation
for an after hours installation.
Selecting Installation Staging will stage the updates to the systems, only transferring the files to
the target MEP(s). The files transferred are those specified in the staging portion of the package
in the RES Software Package Manager. The Installation, which will run when the Install option
is selected, will attempt to stage and then install the updates to the systems at the same time in a
single job.
1. Select one or more updates and then select the Install option or the Installation Staging
option from the actions menu.

Figure 391. Install or Installation Staging
2. The resulting screen will be a short wizard. The second screen will display any dependent
updates that can be staged before the currently selected update.

Figure 392. Install or Installation Staging options
3. Click Next. A summary is displayed to the user before the staging job is created and started.

Figure 393. Staging job summary
4. For actual installation of a package on the target MEP, select one or more updates and select
the Install option from the actions menu in the Show and Install Updates page. This would
internally do the package staging followed by package install.

Figure 394. Show and install updates
5. A short wizard will be shown. This first screen allows the user to change the restart options
for the package. However, this option is not implemented for Retail packages. Click Next.
Note: The "Restarts Required" column will always display a value of "No" regardless of
what is defined in the package.
This option is not implemented for Retail packages.
Figure 395. Restart options

6. A summary is displayed to you before the installation job is created and started. Click
Finish.
Figure 396. Install wizard summary page

7. Click Display Properties to show the software distribution job status. The Active and
Scheduled Job page shows up with a job status.

Figure 397. Active and Scheduled Job status
8. Click the Logs or Job steps to see the status of Software Distribution.
Figure 398. Software Distribution status

Note: Installation Staging action should be used only for packages created with separate
Staging and Install selection while creating the package. If the Installation Staging action is
triggered on a Install only package (i.e. which only has Installation.jar - package without any
Staging.jar), process will complete without any action occurring.
Updating a package in Director

Update Manager does not support updating a package that has already been imported. To
update a package, it must be removed and re-imported.
Deleting a package from Director

Director Update Manager stores all imported packages for distribution at
Director_install_location\data\updateslib\Retail.
You can remove a package from Update Manager using an available cleanupd command line
utility. Here is a sample usage:
smcli cleanupd -m -F -v "Remote Management Agent"
You can remove all packages from Update Manager using the command:
smcli cleanupd -ma
The list of update names to supply to the smcli cleanupd command can be obtained by running
the following command:
smcli lsupd.
Compliance policies
Compliance policies can be used to monitor systems and inform users when systems are missing
specific updates.
The Update Manager summary page provides information about compliance policies for
systems. It provides a quick view of the number of systems that are monitored by compliance
policies and the number of systems that are out of compliance. All compliance policy tasks are
initiated from the Update compliance section on this page.

Figure 399. Update Manager summary page
Create and configure compliance policies

The Create and Configure Compliance Policies task is used to configure compliance policies on
systems that are monitored for missing updates. Each compliance check is listed on a separate
line.
The target system or system group is checked against its associated compliance policy
automatically when the system or update inventory changes.
To create/modify compliance policies, complete the following steps:
1. On the Update Manager summary page, under Updates, click Create and configure
compliance policies. The Compliance Policy page is displayed.

Figure 400. Compliance policy page
2. Browse to select a system or system group. Optionally, you can click Browse to see a list of
systems.
Note: You can only select a single system or a single group. The Director UI does not allow a
selection of multiple systems or multiple groups. The best way to create a compliance policy
to scan multiple systems is to first create a group containing all of the systems, and then
create a compliance policy targeted to that group.
Figure 401. Create and configure compliance policies page
Optional: Click Browse to see a list of systems.

1. Select system or system group.
2. Click Add to add a system or system group.
3. Click Remove to remove a system or system group.
4. Click OK.

Figure 402. Optional list of systems
3. Click Show Compliance Policies.
Figure 403. Show compliance policies

4. Select one of the following policies to create or, if it already exists, configure it:
"Policy to ensure that the latest released updates are always applied"
"Policy to ensure that specific version levels of updates are maintained"

Figure 404. Compliance policies
Important: If a policy already exists and you select and configure the other policy, the
existing policy and its compliance checks are removed when you save the new policy. If the
chosen policy already exists, the table displays all associated compliance checks. If the
chosen policy does not already exist, the table is empty.
5. Choose a task to perform on the selected compliance policy:
Create a new compliance check. Complete the following steps:
1. In the displayed table, click Add. The Add page is displayed.
2. In the Show list, select the type of updates to display in the table.
Note: If you are adding a compliance check to the "Policy to ensure that the latest
released updates are always applied" policy, you can choose from among only dynamic
update groups. When a dynamic update group is examined, the compliance policy
indicates an 'out of compliance' situation only when updates that are needed by the
systems are not installed. This situation is verified by examining the needs relationship
on the update. If you are adding a compliance check to the "Policy to ensure that
specific version levels of updates are maintained" policy, you can choose from among
only individual updates or static update groups. When a static update group is
examined, each update contained within the group that is applicable to the system must
be found to be installed; otherwise, the compliance policy indicates an 'out of
compliance' situation. This situation is verified by examining what applies to
relationship on the update.
3. Choose the updates or update groups to include in the compliance policy.
4. Click OK to add the updates or update groups to the compliance policy.
6. Click Save to save the changes to the compliance policy. This will activate the selected
compliance policy and any compliance checks that you set up for it, and will remove any
previously existing compliance policies and compliance checks.

Note: Compliance status changes after inventory is collected and after updates are imported
from an acquire updates task. This status change can take up to ten minutes after the acquire
updates task or inventory completes.
Identifying systems that are out of compliance

This section explains how to identify systems (only that are monitored by compliance policies)
that are out of compliance so that you can take recommended corrective action.
The system-compliance status indicator represents the highest severity among all of the
compliance policy updates that are not installed on the system. There are five compliance
categories, represented by icons.
The following icon indicates a missing update severity of critical or high:
Figure 405. Critical or high update severity level icon
The icon below indicates a missing update severity that is not known or not applicable:
Figure 406. Unknown or inapplicable update severity level icon
This icon indicates systems that are in compliance (no missing updates):
Figure 407. In compliance icon
The following icon indicates a missing update severity of medium or low:
Figure 408. Medium or low severity level icon
This icon indicates systems that are not accessible or do not have inventory collected:
Figure 409. Inaccessible system or no inventory collected icon
To identify systems that are out of compliance according to an active compliance policy,
complete the following steps:
1. On the Update Manager summary page, find the Update Compliance section.

Note: Compliance Policy of Packages for MEPs with different operating systems will list the
MEPs as compliant with respect to the package.
Figure 410. Update compliance section
2. Examine the pie chart and icons to its right. The number of systems in each compliance
category is displayed.
Note: The compliance pie chart is visible only if you have already created a compliance
policy for your system.
3. If one or more system is in need of updates, click one of the systems links next to the
severity icons (which are next to the pie chart). This displays a table of systems.
Figure 411. Table of systems

4. Optional: You can also click the View all issues link to the bottom right of the pie chart to
view all compliance issues for all systems that are in a policy and are in need of updates.
5. Examine the Compliance column to find which systems are in need of updates. The highest
severity of all the missing updates is displayed.
6. Select one or more systems.
7. Right click, and in the resulting drop down menu, select System Status and Health and
then Compliance Issues. The View All Issues page is displayed. Those systems that have
the same compliance issues are grouped, and the total number of systems is displayed.

Figure 412. View all compliance issues
8. Click a compliance issue to expand and filter the list of individual systems. Otherwise, each
system with each particular issue and recommendation is listed.
Figure 413. Expanded and filtered list of systems with compliance issues
9. The “Compliance issues” page is presented with an issue description and recommendation
for resolving it.
Figure 414. Compliance issues page

Resolving compliance issues
When a compliance policy indicates that there are updates that are required on one or more
systems, examine the severity of the updates, and plan to install them considering your system's
availability, workload, and scheduling factors.
Use this procedure only if one or more of your systems is out of compliance, as indicated by the
Compliance column in the list of monitored systems, or as indicated by the pie chart on the
Update Manager summary page.
Note: The compliance pie chart is visible only if you have already created a compliance policy
for your system.
The Compliance column visually indicates that a system is not in compliance. The status severity
is the highest severity of all the updates needed by the system.
To correct an out-of-compliance situation, complete the following steps:
1. Click the compliance status in the Compliance column to see the Issues and
Recommendations panel.
Figure 415. Compliance status

2. Read the recommended action. Make sure that you understand the proposed actions.
Figure 416. Recommended compliance actions

3. Choose the issues that you want to resolve and then click either Install or Uninstall,
according to the recommendation. The appropriate wizard starts. You can choose to resolve
all issues at once instead of resolving them individually

Example: Updating RMA via RMA software distribution
These instructions describe how the RMA Master Agent and/or General Agent can be updated
using RMA software distribution and the IBM Systems Director Console. The RMA software
DVD includes packages that are available to be imported into IBM Systems Director. These
packages contain all the files and commands needed to update RMA automatically.
It is important to update Master Agents and General Agents separately, in separate jobs and at
separate times. Since the RMA package will restart RMA and the system, updating a General
Agent while the Master Agent is restarting can prevent the status from the General Agent job
from being reported.
The recommended approach for updating RMA is to update Master Agents group and General
Agents separately when scanning for updates and creating compliance policies.
1. Logon to the IBM Systems Director Console.
2. It is a pre-requisite that JRE be present on the system to run RMA. Refer to Chapter 3, RMA
Requirements on page 27 to know more about Java requirements for running RMA agents.
Using RES Software package manager, a package can be created for JRE. Using Update
manager, the JRE package can be transferred to the agents prior to upgrading RMA. Refer to
Appendix D, Using Update Manager for transferring JRE to RMA systems on page 381 for
more information.
3. On the Director Server, insert the RMA software DVD
4. Complete the steps in “Using Update Manager to import packages” on page 326 to import
the RMA update package using the server's local file system. Import the package from the
dirpkgs\rma\windows directory from the RMA DVD. The RMAupdate package for the
Linux platform can be imported from the dirpkgs\rma\Linux directory from the RMA
DVD.
5. After import of RMA package is successful, go to the Update Manager home page, click the
Show and Install Updates link. The Show and Install Updates page will open.
Figure 417. Show and install updates page

6. The selected systems drop down list will either be empty or will have the selection from a
previous invocation. Clicking Browse allows you to change the list of systems or groups
that will be scanned for update applicability and finally where updates will be installed.
Figure 418. List of systems to be scanned for update view

7. After a set of systems has been selected, click Add and click OK.
8. Click Show And Install Updates in the Show And Install Updates page and Update
Manager initiates the scanning for available and applicable updates for a MEP or group of
MEPs. This process scans a selected group of systems for optional and required updates/
packages by comparing the versions of the imported updates with the versions in software
inventory. Make sure inventory is up-to-date for the chosen MEPs.
Note: When you click Show And Install Updates to scan the selected systems for updates, it
is possible that you will get the following error message when scanning:

Figure 419. Show and install updates error message
As the error message explains, inventory must be collected on the selected systems in order
for the scan to proceed. The reason for this is that the scanning process compares the
information for each update with the information in software inventory.
After the inventory on all selected systems are up to date, the scanning process will list the
set of applicable updates.

Figure 420. List of applicable updates
9. Select the Remote Management Agent updates from the table to either be staged or
installed. You can click the link of updates in the table to get more information about the
update.
10. On selecting the Remote Management Agent updates from the table, the Install tab will be
activated. Click the Install tab or alternatively from Actions menu, click Install. This is to
stage and install the package onto the target MEP.

Figure 421. Install tab view
11. An installation wizard Welcome page will be presented. click Next.
Figure 422. Installation wizard welcome page

12. The next screen will provide you with restart options. At present, this does not bear any
significance on agent restart after installation. Click Next.

Figure 423. Restart options
13. A summary is displayed to you before the installation job is created and started. Click
Finish.

14. The installation job details will be presented on the Launch Job page. Select Run Now if
installation has to be triggered immediately or schedule the job at the appropriate time by
selecting Schedule

Figure 425. Launch job page
15. A job will be created. Click Display Properties to show the software distribution job status.
The Active and scheduled Job page opens up and shows the job status.
Figure 426. Active and scheduled job page - job status

16. Click the Logs or Job steps tab to see the status of Software Distribution.

Figure 427. Software Distribution status

Chapter 21. Power Management
Power Management
RMA provides support for managing the power states of POS systems in an 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 6 console.
Power management options supported on Retail agents are Restart((S5 + S0), Shutdown and
Power Off(S5), Suspend(S3) and Power On (Wake On LAN).
The Power management options are available and can be triggered only on Retail systems ie
Master agents and General agents. These agents will show up as Managed end points(MEP) in
"All Retail Client Systems" group in Resource Explorer page of IBM Systems Director 6. The
power management options available for a retail MEP will be different based on both the type of
the managed object as explained in the table below.
The below table outlines the supported power management options for Retail agents.
Table 26. Supported power management options

Shutdown and Power On (Wake
Agent Power Off Restart Suspend on LAN)
Linux General Yes Yes No Yes
Agent
Windows Yes Yes Yes Yes
General Agent
Master Agent No (If the in- Yes No No (Wake on
store Master LAN packets are
Agent is sent from the
powered off, all Master Agent to
communication other systems in
is lost with the the store. The
other agents in Master Agent
the store.) must be online
for this to work.)
4690 Controller Yes Yes No No
General Agent
4690 Classic Yes Yes Yes No
Terminal
4690 Enhanced Yes Yes Yes Yes
Terminal
Embedded No No No No
agents
To utilize power management, select one or more MEP in "All Retail Client Systems" group,
right-click and select a Power management option like "Restart" from the "Power Management"
category in the context menu.

Figure 428. Power Management Options available for General agent Managed End points(MEP)
Upon clicking the appropriate power management option like "Restart", Director will initiate a
power management job creation and shows a "Launch Job" page. This allows the user to
schedule the power management job as per their requirements. The user can choose to run the
job immediately or schedule later for execution.

Figure 429. Complete job creation
Click OK to complete the Job creation and Director displays the Job status and details.
Figure 430. Job Created Successfully
Chapter 21. Power Management 361

User can execute either one of the following steps:
1. Click "Display Properties". The power management request Job page "Active and Scheduled
Jobs" will be displayed.
2. Click "Close Message". On the left hand navigation pane, select "Task Management" and
click "Active and scheduled Jobs" . The Power management job details and Status will be
shown. Click on the job and the power management request Job page. "Active and
Scheduled Jobs" will be displayed.
Figure 431. Active and Scheduled Jobs
The "General" tab of "Active and scheduled Jobs" displays the Job details and status.
Figure 432. General tab
The "Targets" tab displays the Retail Managed End Points(MEP's) on which the power
management request is triggered.

Figure 433. Targets tab
The logs tab displays the power management request Job logs. The job log delineates the power
management request status step by step.
Note: If user schedules the power management Job for later execution, then the "Logs" page will
be empty. Only when Director initiates execution at the scheduled time, job logs will be
populated.
Figure 434. Logs tab
Note:
1. Power management operations like Restart, Shutdown and Power Off, Suspend is not
supported when MEP is already in offline/Online+Locked state. If user executes these power
management operations on MEP's which are offline/online+Locked state, then the power

management operation will fail with an error message in the Job log, which explains that
Power Management is not supported on MEP as the MEP is offline/Not Accessible.
2. Power management operations like Power On is not supported when MEP is already in
online state. If user executes this power management operation on MEP's which are online
state, then the power management operation will fail with an error message in the Job log,
which explains that Power Management is not supported on MEP as the MEP is already
online.
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.
7. Cancellation of any power management functionality once initiated is not supported.
8. When a power management request is already getting executed for an MEP, for Ex: Restart,
if user tries to execute the same function or any other power management function on the
same MEP again, then an error message will be displayed in the job log to inform user that
the functionality is already getting executed and to retry later. The second Job will be
terminated with the error message in the Job log.
9. User can configure the time out period for Power Management operations like Restart,
Suspend, shutdown and PowerOn with the config file, retail-isd.properties, which is placed
in Director install location C:\Program Files\IBM\Director\proddata\retail.
The default values are as explained below.
#Param to specify the timeout value for Power management operation Suspend to
complete
# 1 sec = 1000 milliseconds, 1 min = 60 msecs 10 mins =600000
SUSPEND_PWR_TASK_TIMEOUT_VALUE=600000
#Param to specify the timeout value for Power management operation Shutdown to
complete
SHUTDOWN_PWR_TASK_TIMEOUT_VALUE=600000
#Param to specify the timeout value for Power management operation Restart to
complete
RESTART_PWR_TASK_TIMEOUT_VALUE=1200000
#Param to specify the timeout value for Power management operation PowerOn(Wake
On LAN) to complete
POWER_ON_PWR_TASK_TIMEOUT_VALUE=600000
#Param to specify the minimum size of the Thread pool for processing power
management status
PWR_MGMT_THREAD_POOL_CORE_SIZE=10
#Param to specify the maximum size of the Thread pool for processing power
management status
PWR_MGMT_THREAD_POOL_MAX_SIZE=60
#Param to specify the time out period for getting response for commands sent to
RES for power
#management related functionality.
#value should be provided in terms of milli secs
# 1 sec = 1000 milliseconds, default value is 5 min = 300000 milliseconds
POWER_MGMT_RES_CMD_TIMEOUT_VALUE=300000

10. User can configure the number of threads that handle the power management tasks on RES
in the res.properties file that reside on RES at location $RES_INSTALL_LOC$\RES\conf.
The configuration variables and default values are
# The maximum size of the Power Management thread pool
pwr.mgmt.task.threadPool.max.size= 50
# The core, or minimum size of the Power Management thread pool

pwr.mgmt.task.threadPool.core.size=10
11. Director plugin Downgrade scenario is not supported . If user needs to downgrade to a
lower version which doesn't support Power Management feature, then they need to just
delete the existing MEP's in the Director UI Resource Explorer and re-discover them.
Warning: Power management in the below scenarios is not recommended, due to the
Director 6 Architecture limitation. This may lead to power management request failure.
• User selecting and executing a power management operation on both Master agent and 1
or more GA' s from the same store.
• User selecting and executing a power management operation on both OS4690 terminals
and their associated controller GA/MA.
• User selecting and executing a power management operation on both OS4690 controller
and terminal configured on the same machine.

Chapter 22. Troubleshooting problems
Troubleshooting problems
This section helps you find information about troubleshooting problems with the Toshiba
Remote Management Agent or the Retail Extensions for IBM Systems Director.
Logs
Log data is produced for the Master Agent, General Agent, and Retail Extensions for IBM
Systems Director.
Note: If you are facing any issue related to discovery from General Agent to Master Agent, you
should check RMA logs of both General Agent as well as Master Agent to get more details
RMA Agents
Problem Determination Bundle Collection
The rmaCollect program creates a single .zip file with all of the information needed to send to
open a PMR. It includes add agent logs plus configuration and data files. This program is
available on RMA V3 and later.
This program is located at:
• Windows: %RMA_HOME%\bin\rmaCollect.bat
• 4690 Classic: M:\rma\rmaCollect.bat
• 4690 Enhanced: F:\rma\rmaCollect.bat
• Linux: %RMA_HOME%\bin\rmaCollect.sh
The program will create .zip files in the following directories:
• Windows: %RMA_HOME%\pd
• 4690 Classic: M:\rma\pd
• 4690 Enhanced: F:\rma\pd
• Linux: %RMA_HOME%\pd
Files captured as part of RMA collect utility are:
• Values of environment variables (Classpath, RMA_HOME etc)
• Versions of RMA jars (from Version classes)
• All logs in $RMA_HOME\silogs
• Java core dump.txt files and heap dump .phd files from %RMA_HOME%
• A recursive directory listing of $RMA_HOME
• $RMA_HOME\User\rma\rma.properties, rmauser.properties
• All files from user\rma (excluding swd/pkgdist/pkgExtract, swd/pkgdist/
pkgJars, capture)
• Service logs for Linux agent /var/log/rmsvc-ma or rmsvc-ga
• Install logs for windows agent.
The logs for RMA 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 logs directory is as
follows:
• Windows: %RMA_HOME%\logs
• 4690 Classic: M:\rma\logs
• 4690 Enhanced: F:\rma\logs
• Linux: %RMA_HOME%\silogs

The log files are named rma.x, with rma.0 being the most recent for Windows Agents and
simgmt.x, with simgmt.0 being the most recent for Linux and OS4690 agents. The memory log
files are named rma_m.x, with rma_m.0 being the most recent file on Windows Agents and
simgmt_m.x, with simgmt_m.0 being the most recent file on Linux and OS4690 agents. 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:
• Windows: C:\Program Files\Toshiba\RMA on 32 bit Windows OS
• Linux: /opt/ibm/StoreIntegrator/RMA
• V3 and Later Linux: /opt/toshiba/rma
• 4690 Classic: M:\rma\lib
• 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 140.
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 logs Directory on Windows
platform and silogs Directory on Linux and OS4690 platforms.
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. The MBean interface has 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:
• Windows: %RMA_HOME%\
• Linux: /opt/toshiba/rma
• CoreDump Location: M:\adxetc\java2\core
• HeapDump Location: M:\adxetc\java2\heap
• 4690 Enhanced: F:\rma
IBM Systems Director information

IBM Systems Director server logs are located in Director\lwi\logs. The logging
configuration file is located in Director\lwi\conf\overrides\logging.properties.
IBM Systems Director 6 uses JDK (Java) logging.
Problem Determination Bundle Collection

The resCollect program creates .zip files, one each for RES and Director, with all of the
information needed to send to open a PMR. It includes all RES and Director log files plus
configuration and data files. The file names have the format <res>_<date>_<time>.zip and
<isd>_<date>_<time>.zip. This program is located at:
Windows: %RES_HOME%\bin\resCollect.bat
Linux: /opt/toshiba/res/bin/resCollect.sh

The program will create .zip files in the following directories:
Windows: %RES_HOME%\pd
Linux: /opt/toshiba/res/pd
Separate files are created for RES and Director logs. These files are not cleaned up automatically.
The information that is collected in these separate files is listed below.
Director information
Following is the Director information:
• Values of environment variables (PATH, RES_HOME, etc)
• Versions of RES and Director plugin jars (This and above will be in the EnvInfo.txt file in
the EnvInfo folder)
• Director version information (version.srv file): (This will go in the EnvInfo folder in the
zip file)
• All files from Director/lwi/logs
• The logging.properties file from DIR_HOME/lwi/conf/overrides
• Java core dump .txt files from DIR_HOME/lwi/runtime/core (This will go in the dumps
folder in the zip)
• Heap dump .phd files from DIR_HOME/lwi/runtime/core. (This will go in the dumps
folder in the zip)
• ISD Plugin version information: DIR_HOME/Retail/RetailPlugin.properties (This will go in
the EnvInfo folder in the zip file)
• The director debug info in the folder DIR_HOME/lwi/runtime/core/RCSDebug
RES information
This is the RES information:
• All logs from RES_HOME/logs
• A recursive directory listing of RES_HOME
• Java core dump .txt files and heap dump .phd files
• All files from RES_HOME/conf (There will be folder conf in the zip file where these files can
be found)
• Contents of the folder RES_HOME/data
• On Linux platform, the file /etc/sysconfig/resenv (This will go in the EnvInfo folder in
the zip file)
• RES_HOME/RES_Install_Log.txt (This will go in the EnvInfo folder in the zip file)
• On Linux platform, the file /tmp/RES_Inst_DebugLog.txt (This will go in the
EnvInfo folder in the zip file)
JVM Diagnostics
IBM Systems Director provides a command line interface for invoking tasks, using the smcli
program. This interface can be used for producing Java core dumps or Java heap snapshots of
the IBM Systems Director Server JVM to help diagnose problems. To produce a Java core dump,
issue the smcli dumpjava command. To produce a heap dump, issue the smcli dumpheap
Chapter 22. Troubleshooting problems 369

command. Java core text files and heap snapshot files (.phd) are produced in the Director
\lwi\runtime\core directory.
Troubleshooting
Use Table 27 to determine the action to take due to symptoms of common problems.
Table 27. Common symptoms

Problem or symptom Solution
RMA devices do not 1. Check the store connection settings in the RMA Store
display in the IBM Systems Manager and verify settings for Master Agent are correct.
Director Console. 2. Check the Connection Log for the Master Agent's entry in the
RMA Store Manager.
3. Verify that there is an active network connection between the
Master Agent and the IBM Systems Director Servers.
4. Check the General Agent logs to see if there were errors
starting the General Agent.
5. Check the Master Agent logs to see if there were errors
making a connection to the General Agent.
6. 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
Console
Master Agent, verify that the property
com.ibm.retail.si.mgmt.generalagent.discovery
.ttl is set accordingly in rma.properties on each
General Agent.
4. If the firewall is enabled either on General Agent or Master
Agent and if the General Agent is of type "Linux", make sure
the property
com.ibm.retail.si.mgmt.generalagent.protocol
in General Agent is set to soxs.
On Windows the RMA 1. Check the Windows Application and System logs in the
Agent service is not started Windows Event Viewer for detailed error messages.
or returns an error 2. Check whether RMA system environment variable
message when starting. RMA_JAVA_PATH is set to valid JRE path required for
running agents.
On Windows the RES Check whether system environment variable RES_JAVA_PATH is

service is not started or set to valid JRE path required for running RES.
returns an error message
when starting.
Silent installation and This problem may occur if one of the following scenarios is true.
Software Distribution of Correct them accordingly.
Windows Agent fails with
error code and description. 1. 101: If user has not set one of the Environment Variables
JAVA_HOME or RMA_JAVA_PATH variable.

Problem or symptom Solution
2. 102: If user has provided 64 bit JRE in JAVA_HOME or

RMA_JAVA_PATH variable. RMA windows Agents are
supported only on 32 bit JRE.
3. 103: The JRE selected by user is not valid.
4. 104: If version of the JRE provided at JAVA_HOME or
RMA_JAVA_PATH variable is less than Version 6.
5. 105: Cannot find the file jvm.dll on the path indicated by
the RMA_JAVA_PATH or JAVA_HOME environment
variables.
6. -3: If a higher version of RMA is already installed,
downgrade/rollback to the lower version is not allowed.
Hence uninstall the higher version and try installation again.
7. -4: Agent security mode configured by user is invalid. The
valid values are "Standard" or "Enhanced".
8. -5: This error code will be thrown at the time of silent
Windows agent upgrade scenario. If the previous installed
agent type data is corrupted this issue can happen. Please
uninstall the old version and try installing the new version.
9. -6: If the store ID configured by user has unsupported
characters this error will be thrown. Please do provide the
supported characters for store ID as mentioned in the
documentation.
10. -7: If the JRE configured for running RMA is invalid, this
error will be thrown. Please configure the appropriate JRE as
mentioned in the RMA requirements section.
11. 1001: The installation includes an invalid command line
option.
Software Distribution of This problem may occur if one of the following scenarios is true.
Linux Agent fails with Correct them accordingly.
error code 127.
1. If user has provided 64 bit JRE in JAVA_HOME or
RMA_JAVA_PATH variable.
2. If version of the JRE provided at JAVA_HOME or
RMA_JAVA_PATH variable is less than Version 6.
3. If user has not set one of the Environment Variables,
RMA_JAVA_PATH or JAVA_HOME.
4. If JRE is not valid.
SSL Handshake error If the Linux agent is running on OpenJDK1.7 and is trying to
between RES and Linux connect to RES, an error might be thrown with respect to SSL
Agents running on Handshake and connectivity to RES will not succeed. This issue
OpenJDK 1.7. can be addressed by installing the Network security package on
Linux machine and restarting the agent service.
For Windows RES and Prior to installation, an environment variable JAVA_HOME
Agent installation, user should be set, pointing to the installed location of OpenJDK.
selected OpenJDK's java
validation might fail at
Select Java Virtual
Machine panel.

RMA utilities
RMA includes some supported utilities/commands that can be helpful when debugging
problems. The utility for RMA agents is rmaCli and its usage is as explained below.
Usage: RMACLI <Command> <Argument>*, where:
<Command>: RMA CLI Command (list of supported commands provided below)
<Argument>: Command arguments for commands that require them
Supported CLI commands:
• coreDump: Produces a Java core dump of the local agent JVM. Alternatively, the coreDump
can also be set to be auto-generated on service stop by adding the property
rma.javacore.onShutdown=true in the rmauser.properties file. (This applies to
only Linux and Windows agents/RES).
• heapDump: Produces a Java heap dump of the local agent JVM.
• garbageCollect: Invokes the Java System.gc() call on the local agent JVM.
• memLogDump: Dumps the contents of the trace memory log.
• setLoggerLevel <Logger><Level>: Dynamically changes the logging level for a JDK
Logger.
• <Logger> is a class name to collect logging on e.g.
com.ibm.retail.si.mgmt.MgmtMasterHealth.
• <Level> is one of SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST.
• enableNativeTrace <component mask>: Dynamically enable logging of native code
components. Mask values can be combined.
For example, to get CIM and Master Agent authentication logging, use a <component mask>
of '5'
component mask values: CIM = 1; Win32 Event Log = 2; Master Agent authentication = 4;
Power management = 8
General and Master Agent Common Commands:
• lsmbeans <query>: Lists all MBeans given the optional JMX ObjectName query. If not
supplied, the query will default to *:* (all MBeans).
• lsobjnames <query>: Lists all MBean ObjectNames given the optional JMX ObjectName
query. If not supplied, the query will default to *:* (all MBeans).
Command to find RMA version:
• Run rmaJava com.ibm.retail.si.mgmt.Version in %rma_home%/bin directory.
The utility for RES is resDiag.bat and its usage is as explained below.
• Usage: RESDiagCLI <Command> <Argument>*, where:
<Command>: RES Diag command (see list of supported commands below).
<Argument>: Command arguments for commands that require them.
Supported commands:
• coreDump: Produces a Java core dump of the RES(local) JVM. Alternatively, the coreDump
can also be set to be auto-generated on service stop by adding the property
rma.javacore.onShutdown=true in the rmauser.properties file. (This applies to
only Linux and Windows RES).
• heapDump: Produces a Java heap dump of the RES(local) JVM.
• garbageCollect: Invokes the Java System.gc() call on the RES (local) JVM.
• memLogDump: Dumps the contents of the trace memory log.

• setLoggerLevel <Logger><Level>: Dynamically changes the logging level for a JDK
Logger.
• <Logger> is a class name to collect logging on, for example:
com.ibm.retail.si.mgmt.MgmtMasterHealth.
• <Level> is one of SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST.

Appendix A. Stopping and starting RMA Director RES
Stopping and starting RMA Director RES
To stop RMA on windows (or use the Services window):
net stop remotemgmtagent
To start RMA on windows (or use the Services window):
net start remotemgmtagent
To stop RMA on Linux:
/etc/init.d/rmsvc-ma stop (for MA)

/etc/init.d/rmsvc-ga stop (for GA)
To start RMA on Linux:
/etc/init.d/rmsvc-ma start (for MA)

/etc/init.d/rmsvc-ga start (for GA)
To stop RMA on 4690:
adxssp0l RMA -C
To start RMA on 4690:
adxssp0l RMA -R
To query the status of RMA on 4690:
adxssp0l RMA -Q
To stop IBM Systems Director on windows (or use the Services window):
net stop dirserver
To start IBM Systems Director on windows (or use the Services window):
net start dirserver
To stop IBM Systems Director on linux
smstop
To start IBM Systems Director on linux
smstart
To query the status of IBM Systems Director on Windows/Linux:
smstatus

To stop RES on windows (or use the Services window):
net stop retailenterpriseservice
To start RES on windows (or use the Services window):
net start retailenterpriseservice
To stop RES on Linux:
/etc/init.d/resserver stop
To start RES on Linux:
/etc/init.d/resserver start

Appendix B. Agent Monitoring Support
Agent Monitoring Support
The following table outlines the support for hardware and resource monitoring by operating
system and hardware models. The table assumes that the system is running RMA V3 or later.
Note:
• W = Windows
• L = Linux
• E = 4690 Enhanced
• C = 4690 Classic
Table 28. Support for hardware and resource monitoring
Hardware
System LED Sensor Service
Machine Type Models Monitoring Monitoring Processor Events
6140 100 W, E, L
6140 120 L
6140 x3x W
6140 x4x W
4900 x45, x75, x85, W, E, L
4900 786, 746 W, E
4852 566 W, L W, L
4852 526, 570 W, L
4852 580 W
4846 5x5 W
4838 (All Models) W, L W, L
4810 33x W
4810 34x W, L
4810 350 W, E, L
4810 360 W, E
4810 370, 380 W,E
4800 784, C84 W, E, L E W, L
4800 7x3, F43 W, E, C, L E, C W, L
4800 EU3 W, L E, C W, L
4800 782, C42, 742 W, E, C
4800 722 E, C

Appendix C. SLEPOS Server-Client setup
SLEPOS Server-Client setup
SLEPOS 11 SP3 Server-Client Setup
SLEPOS Installation:
Instructions Reference link: https://www.toshibacommerce.com/?urile=wcm:path:/en/home/
support/product-support/support-software/support-remote-management-agent
• Configuration-Step4-> Change the parameter in 01setupAdminServerLdap.sh according to
your network and configuration(i.e. Password, ipNetworkNumber, ipNetmaskNumber
ipHostNumber etc)
• On SLEPOS server machine, with firewall ON - configure the following DNS ports:
53 TCP UDP Domain Name System (DNS) Official

90 TCP UDP dnsix (DoD Network Security for Information Exchange) Security
Attribute Token Map Official
135 TCP UDP Microsoft EPMAP (End Point Mapper), also known as DCE/RPC Locator
service,[15] used to remotely manage services including DHCP server,
DNS server and WINS. Also used by DCOM Unofficial
953 TCP UDP Domain Name System (DNS) RNDC Service Unofficial
1337 TCP UDP Men and Mice DNS Official
5353 UDP Multicast DNS (mDNS) Official
• Prepare Server for POS Terminal Boot-Step2-> Before running 03addPOS.sh make sure there
is a line entered for controller type of SLEPOS terminal.
• Default user name and password for booted SLEPOS client is "root" and "linux".
Creating an image with RMA package:

For installation please refer to the SLEPOS Configuration Guide which can be found at
www.toshibacommerce.com/support/publications.
• Step 3: On Image Preparation screen, give path of Output Directory as /var/lib/SLEPOS/
system/<Image name>
• Step 13: Normally Image configuration > Scripts > Cleanup Script section is disabled. To
over come this, add below scripts in Image Configuration window > Scripts tab > Studio
Custom Build section before "exit 0".
# Commands for the RMA General Agent
/opt/toshiba/rma/rma-config -n eth0
chkconfig sfcb 235
/etc/init.d/sfcb start
/etc/init.d/rmsvc-ga start
• Preparing the server to boot the POS Terminal

• Step13: At times, the status of /etc/init.d/posleases2ldap command could be -
image2ldap service was not running, but still could be able to boot from image.

• It is good to switch off the terminal while creating the image - from which you want to boot
the image after creation.
• After successful boot from RMA image, user can check whether RMA is running or not in
terminal using /etc/init.d/rmsvc-ga status.
Creating image with Java POS:

Download the JPOS Drivers by following the link: http://www.toshibacommerce.com >
Support > Support Overview In the "Hardware" pull down, select Common Packages:
Diagnostics, UPOS, RMA & Others.
• Include the following rpms as well while creating the image:
• posIBM_XML4C
• toshiba_upos_sblim-cmpi-upos-server-sled
• After client gets booted from newly created java pos image using above link, when user tried
to launch POS Control Center, it was not launching. Later found that java command is not
working. To make the Java command working do following steps from SLEPOS client:
• Delete existing java soft link from /user/bin using rm /usr/bin/java command.
• Create a new symbolic link for java using ln - s /opt/ibm/java-
i386-60/jre/bin/java /usr/bin/ java command
Creating image with Hardware Sensors

Download the Hardware Sensor Drivers by following the link: http://
www.toshibacommerce.com > Support > Support Overview In the "Hardware" pull down,
select Common Packages: Diagnostics, UPOS, RMA & Others.
Note: Must follow the file attached in the Information section of the above link and download
accordingly.
Similar to RMA and JavaPOS image creation, you need to select the hardware sensor driver
rpms while creating the image and register the image for the client to boot with hardware sensor
drivers.

Appendix D. Using Update Manager for transferring JRE to RMA
systems
Using Update Manager for transferring JRE to RMA systems
A custom package containing the user preferred JRE can be created using RES Software Package
Manager and transferred to agent systems using IBM System Director Update manager
(Software distribution) prior to RMA upgrade.
Note: For RMA 3.2.2, it is a pre-requisite to provide JRE for RMA agents to run.
The process to transfer user preferred JRE to Windows and Linux Agent systems is explained in
the sections below.
For Windows Agents

Follow the steps below to transfer user preferred JRE to Windows Agents.
1. Launch the RES Software package manager. Refer to “Launching the RES Software Package
Manager” on page 309 for instructions.
Figure 435. RES Software Package Manager

2. On the menu bar of the application, click File > Create Package to start creating a package.
Figure 436. Create Package

3. Provide required information and select the Target OS. Click Next.

Figure 437. Enter package information
4. In the Windows Installation Information window, provide the Installation Destination
Directory details as to which location the package is to be staged/installed on target agent.
Figure 438. Enter Windows installation information

5. Now, click Files and select the files that should comprise the JRE package.
Select the JRE folder to be packaged and click the right arrow button to add the file to the
list of selected files on the right. Click the Include subfolders checkbox shown in the figure
below and click OK.

Figure 439. Select files to distribute
6. Set JAVA_HOME Environment Variable to the new JRE location.
If setting JAVA_HOME variable is not preferred (for reasons such as other applications on
the target system are using it and the Java requirements of those applications are different
than RMA), then user can skip this step and set RMA_JAVA_PATH Environment Variable
to the new JRE location.
Note: Either the JAVA_HOME or RMA_JAVA_PATH Environment Variable needs to be set
to the valid JRE location for RMA to run on the agent system.
Path : cmd.exe
Arguments : /c SETX JAVA_HOME "${client.target.path}\jre1.8.0_51" /M
Click OK.
Appendix D. Using Update Manager for transferring JRE to RMA systems 383
Figure 440. Set JAVA_HOME to valid JRE location
7. This step is optional. If JAVA_HOME is set in step 6 this step can be skipped.
Click Add button to add command to set RMA_JAVA_PATH Environment Variable.
Path : cmd.exe
Arguments : /c SETX RMA_JAVA_PATH "${client.target.path}
\jre1.8.0_51" /M
Figure 441. Set RMA_JAVA_PATH to valid JRE location
The set of commands added shows up on the Package Commands screen. Click OK.

Figure 442. Package Commands
8. Provide the Product/Package name and details in the Update Manager Product Information
screen.
Click Next and Finish to save the Package.
Figure 443. Enter Update Manager product information
The custom JRE package will show up on the RES screen as below.
Figure 444. New JRE package
9. Transfer the above created JRE package to the agent system using Update Manager. Refer to
“Using Update Manager” on page 326.
For Linux Agents

Follow the steps below to transfer user preferred JRE to Linux Agents.
1. Launch the RES Software package manager. Refer to “Launching the RES Software Package
Manager” on page 309 for details on launching RES Software package manager.
Figure 445. RES Software Package Manager (Linux)

2. On the Menu bar of the application, click File > Create Package to start creating a package.
Figure 446. Create Package (Linux)

3. Provide required information and select the Target OS. Click Next.

Figure 447. Enter package information (Linux)
4. In the Linux Installation Information window, provide the Installation Destination
Directory details as to which location the package is to be staged/installed on target agent.
Figure 448. Enter Linux installation information

5. Now, click Files and select the files that should comprise the JRE package.
Select JRE folder to package and click the right arrow button to add the file to the list of
selected files on the right. Check the Include subfolders check box.
6. Set the JAVA_HOME Environment Variable to the new JRE location using Linux shell
scripts or via the command option available with RES Package Manager.
If setting JAVA_HOME variable is not preferred (for reasons such as other applications on
the target system are using it and the Java requirements of other application are different
than RMA), then user can set RMA_JAVA_PATH Environment Variable to the new JRE
location.
Note: Either the JAVA_HOME or RMA_JAVA_PATH Environment Variable needs to be set
to the valid JRE location for RMA to run on the agent system.
A sample script jre_pkg.sh is provided to set the RMA_JAVA_PATH Environment
Variable.
Content of the jre_pkg.sh file:
#!/bin/bash
#Checking for bash.bashrc.local file
if [ ! -e /etc/bash.bashrc.local ]
then echo "file does not exist"
touch /etc/bash.bashrc.local
fi;
#checking for RMA_JAVA_PATH, if exists then override else append to end of the
file
if grep -q "RMA_JAVA_PATH" "/etc/bash.bashrc.local"
then
echo "RMA_JAVA_PATH variable exists"
sed -i '/RMA_JAVA_PATH/d' /etc/bash.bashrc.local
fi;
echo "export RMA_JAVA_PATH=/usr/java/jre1.8.0_51" >> /etc/bash.bashrc.local
7. Select the script jre_pkg.sh if needed. Click the right arrow button to add the file to the
list of selected files on the right. Click OK.
Figure 449. Select files to distribute (Linux)

8. Click Commands and then click Add to enter the below command to provide executable
permissions to jre_pkg.sh.
Path : chmod 777 ${client.target.path}/jre_pkg.sh
/usr/java can be replaced with ${client.target.path}.
Click OK.

Figure 450. Set executbale permissions (Linux)
9. Click Add button and enter second command mentioned below to run the shell script which
sets the RMA_JAVA_PATH on the agent machine.
Path : ${client.target.path}/jre_pkg.sh
/usr/java can be replaced with ${client.target.path}
Click OK.
Figure 451. Set RMA_JAVA_PATH (Linux)

10. Click Add button and enter third command mentioned below, which deletes the shell script
after execution.
Path : rm ${client.target.path}/jre_pkg.sh
/usr/java can be replaced with ${client.target.path}
Click OK.
Figure 452. Delete shell script

11. Click Add button and enter fourth command mentioned below which sets the file access
permission to the transferred JRE folder.
Path : chmod -R 777 ${client.target.path}/jre1.8.0_51
Click OK.
Figure 453. Set file access permission (Linux)

A screen showing all the commands entered will appear.
Figure 454. Linux package commands

12. Provide the Product/Package name and details in the Update Manager Product Information
screen. Click Next and Finish to save the Package.
Figure 455. Enter Update Manager product information (Linux)
Newly created package will show up on the RES screen as shown below.
Figure 456. New JRE package (Linux)
13. Transfer the above created JRE package to the agent system using Update Manager. Refer to
“Using Update Manager” on page 326.

Notices
This information was developed for products and services offered in the U.S.A.
Toshiba Global Commerce Solutions may not offer the products, services, or features discussed
in this document in other countries. Consult your local Toshiba Global Commerce Solutions
representative for information on the products and services currently available in your area. Any
reference to a Toshiba Global Commerce Solutions product, program, or service is not intended
to state or imply that only that Toshiba Global Commerce Solutions product, program, or service
may be used. Any functionally equivalent product, program, or service that does not infringe
any Toshiba Global Commerce Solutions intellectual property right may be used instead.
However, it is the user's responsibility to evaluate and verify the operation of any non-Toshiba
Global Commerce Solutions product, program, or service.
Toshiba Global Commerce Solutions may 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:
Toshiba Global Commerce Solutions

Attn: General Counsel
3901 South Miami Blvd.
Durham, NC 27703
United States of America
The following paragraph does not apply to the United Kingdom or any other country where
such provisions are inconsistent with local law: TOSHIBA GLOBAL COMMERCE SOLUTIONS
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 may 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. Toshiba Global Commerce Solutions may make improvements and/or
changes in the product(s) and/or program(s) described in this publication at any time without
notice.
Toshiba Global Commerce Solutions may use or distribute any of the information you supply in
any way it believes appropriate without incurring any obligation to you.
Any references in this information to non-Toshiba Global Commerce Solutions 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 part of the materials for this Toshiba Global
Commerce Solutions product and use of those Web sites is at your own risk.
Information concerning non-Toshiba Global Commerce Solutions products was obtained from
the suppliers of those products, their published announcements or other publicly available
sources. Toshiba Global Commerce Solutions has not tested those products and cannot confirm
the accuracy of performance, compatibility or any other claims related to non-Toshiba Global
Commerce Solutions products. Questions on the capabilities of non-Toshiba Global Commerce
Solutions products should be addressed to the suppliers of those products.
This information is for planning purposes only. The information herein is subject to change
before the products described become available.

Trademarks
The following are trademarks or registered trademarks of Toshiba, Inc. in the United States or
other countries, or both:
Toshiba
The Toshiba logo
The following are trademarks of Toshiba Global Commerce Solutions in the United States or
other countries, or both:
AnyPlace
SureMark
SurePoint
SurePOS
TCxWave
TCxFlight
TCx
The following are trademarks of International Business Machines Corporation in the United
States or other countries, or both:
DB2
DB2 Universal Database
IBM and the IBM logo
PS/2
Wake on LAN
WebSphere
Linux is a trademark of Linus Torvalds in the United States, other countries, or both.
Magellan is a registered trademark of Datalogic Scanning, Inc.
SYMBOL a registered trademark of Symbol Technologies, Inc.
Microsoft, Windows, Windows NT, and the Windows 95 logo are trademarks of Microsoft
Corporation in the United States, other countries, or both.
Celeron and Intel are trademarks of Intel corporation in the United States, or other countries.
Java and all Java-based trademarks and logos are trademarks of Oracle, Inc. in the United States,
or other countries, or both.
Other company, product, or service names may be trademarks or service marks of others.

Index
generic monitoring (continued)
4690OS Whitelisting Support for RMA 119 property definitions 303 K
groups, security 117
keystore 128
A
agent class path and environment 139
H L
agent configuration 121, 144 hardware requirements 27
agent configuration file 121 log directories 367
agent JVM diagnostics 368 logging configuration 140
Agent Monitoring Support 377 logging levels 141
agent properties 121, 122
I logging parameters 142
agent roles 144
IBM systems director 28
agent startup sequence 143
agent Windows event log integration 145
AgentStartupMBean 143
troubleshooting M
JVM diagnostics 369
IBM Systems Director Server 6 41 MBean/CIM specification 300
in-store processor 27 monitoring overview 21
C infrastructure overview 23
installation
compatibility with prior versions of
RMA 31
DVD 79 N
interactive 79
configuration, agent 121 installation procedure notices
configuration, security 125 interactive 79 Toshiba 393
configuration, SSL 126 installing 79
conventions 16 installing for
Create jar file for remote embedded
agents 133
procedure 41
installing IBM Systems Director Server 6 38,
O
Creating res-ssl.jar with new custom SSL 41 overview, infrastructure 23
related files 135 installing Retail Enterprise Service on overview, inventory 21
Linux 65 overview, monitoring 21
installing Retail Enterprise Service on overview, retail peripheral management 21
D Windows 49 overview, RMA 21
installing Retail Extensions and RES on overview, software distribution 22
data capture properties 123, 124 Linux 65
downloading IBM Systems Director Server installing Retail Extensions and RES on
6 36 Windows 49
downloading RMA 37 installing RMA general agent 35
P
Installing/Upgrading Retail Extensions for peripheral monitoring 293
IBM Systems Director on post installation
E Windows
procedure 55
Windows 89
Post installation 99
embedded agents 133, 139 Interactive fresh installation of RMA on OS problem determination
end of life monitoring 4690 98 solutions 370, 371
POS printer attributes 294 interactive uninstallation symptoms 370
RSS display 296 procedure 109 problem symptoms 370
event fetching properties (Master Agent Interactive Upgrade of RMA on OS
only) 123 4690 100
event management introducing Remote Management Agent
introduction 233 Remote Management Agent, introducing 19
R
event properties 123 Introduction to Health Status Health Status
Remote Management Agent 15
Health 279
Remote Management General Agent 79
inventory overview 21
RES director 31
F retail peripheral management overview 21
rma agent on 4690 97
For RMA remote embedded agents 139 J RMA Director Basics 181
RMA overview 21
Java 2 requirements 30, 31 RMA utilities
G Java class path 139 utilities 372
JRE 30 RMI Properties 122, 123
generic monitoring roles, agent 144

S
Security configuration 125
security groups 117
security modes 117
setup instructions 102
silent installation 91
SLEPOS 11 SP3 Server-Client Setup 379
SLEPOS Server-Client setup 379
software distribution overview 22
Software Distribution Software 309
software requirements 30
SSD 292
SSD life monitoring 292
SSL configuration 126
step 1 36
step 2 37
step 4 - Install IBM Systems Director
Hotfixes 38
step 5 - installing RMA retail extensions for
IBM Systems Director Server 38
step 6 - installing retail enterprise service
(RES) 39
step 7 - Verify Retail Extensions for IBM
Systems Director and Retail Enterprise
Service (RES) Installation 39
step 8 - installing RMA MA 39
step 9 installing RMA GA 39
Stopping and starting RMA Director
RES 375
supported operating systems 30
T
trademarks 394
troubleshooting
logs 367
problem 367
solution 367
truststore 128
U
uninstallation 109
uninstallation result 111
Upgrade RMA on OS 4690 through
ASM 101
using inventory 213
Using Update Manager for transferring JRE
to RMA systems 381
W
Whitelisting (4690OS) Support for RMA 119
Windows event log integration, agent 145
Windows installation 79
Windows PATH 140

GC30-4106-17

RMA V3R2.2 Users Guide

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

RMA V3R2.2 Users Guide

Uploaded by

Copyright:

Available Formats

Toshiba Global Commerce Solutions

Remote Management Agent

Summary of changes............................. 17 Chapter 4. Installation Overview........... 35

Chapter 2. Infrastructure Chapter 5. Installing IBM Systems

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 3

Chapter 12. Understanding RMA

4 RMA 3.2.2 User's Guide

Appendix C. SLEPOS Server-Client

Appendix D. Using Update Manager

6 RMA 3.2.2 User's Guide

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 7

8 RMA 3.2.2 User's Guide

267. General tabs window....................................................236 312. Event Actions window ................................................262

10 RMA 3.2.2 User's Guide

12 RMA 3.2.2 User's Guide

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 13

Who should read this guide

Where to find more information

Accessing the TGCS Knowledgebase site

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 15

Conventions used in this guide

16 RMA 3.2.2 User's Guide

Web-only update of GC30-4106-16

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 17

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 19

Event Management and Health Status

Power Management of POS Systems

Monitoring Retail Systems

Retail peripheral management

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 21

22 RMA 3.2.2 User's Guide

Figure 1. RMA infrastructure

RMA General Agent

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 23

IBM Systems Director Server

IBM Systems Director Console

Retail Extensions for IBM Systems Director

Retail Enterprise Service (RES)

24 RMA 3.2.2 User's Guide

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 25

IBM Systems Director Server hardware requirements

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 27

IBM Systems Director / Retail Enterprise Service software requirements

28 RMA 3.2.2 User's Guide

Supported Operating Systems

IBM Systems Director Server

Director Server database requirements

Chapter 3. RMA Requirements 29

Supported operating systems

POS sensor drivers

30 RMA 3.2.2 User's Guide

Compatibility with prior versions of RMA

RMA Master and General agents

Chapter 3. RMA Requirements 31

Table 2. Network ports used by the RMA MA

10521 (TCP) Outgoing RMA V3 MA to RES (Store Discovery)

Table 3. Network ports used by RES

10521 (TCP) Incoming RMA V3 MA to RES (Store Discovery)

Table 4. Network ports used by IBM Systems Director

32 RMA 3.2.2 User's Guide

Figure 3. General Agents that are on different subnets

com.ibm.retail.si.mgmt.generalagent.discovery.ttl=<hops returned by tracert>

Chapter 3. RMA Requirements 33

© Copyright Toshiba Global Commerce Solutions, Inc. 2017 35