IBM Tivoli Network Manager IP Edition: Discovery Guide

Network Manager IP Edition
Version 4 Release 2
Discovery Guide
IBM
R4.2 E3
Network Manager IP Edition
Version 4 Release 2
Discovery Guide
IBM
R4.2 E3
Note
Before using this information and the product it supports, read the information in “Notices” on page 523.
This edition applies to version 4.2 of IBM Tivoli Network Manager IP Edition (product number 5724-S45) and to all
subsequent releases and modifications until otherwise indicated in new editions.
© Copyright IBM Corporation 2006, 2017.
US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contract
with IBM Corp.
Contents
Tables . . . . . . . . . . . . . . . vii
Chapter 4. Classifying network
devices . . . . . . . . . . . . . . 245
About this publication . . . . . . . . xi
Changing the device class hierarchy . . . .
Listing the existing device classes . . .
Creating and editing AOC files . . . .
Applying AOC changes to the topology and
the reports . . . . . . . . . . .
AOC file samples . . . . . . . . . .
EndNode class . . . . . . . . . .
NetworkDevice class . . . . . . . .
AOC specific to device class . . . . .
Audience . . . . . . . . . .
What this publication contains . . .
Publications . . . . . . . . .
Accessibility . . . . . . . . .
Tivoli technical training . . . . . .
Support and community information .
Conventions used in this publication .
.
.
.
.
.
.
.
.
. xi
. xi
. . . . . xii
. . . . . xv
. . . . xvii
. . . . xvii
. . . . xviii
Chapter 1. About discovery . . . . . . 1
About types of discovery . .
Scopes . . . . . . . .
Types of scoping . . . .
Defining discovery zones to
Seeds . . . . . . . .
Device access . . . . . .
Agents . . . . . . . .
Device filters . . . . . .
SNMP interface filtering . .
Domain Name System . . .
Network address translation.
Advanced settings . . . .
Context-sensitive discovery .
Helpers. . . . . . . .
Collectors . . . . . . .
Specialized discoveries . .
. . . . . . .
. . . . . . .
. . . . . . .
restrict discovery .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. . . . . . .
. 1
. 2
. 3
. 3
. 13
. 13
. 14
. 14
. 16
. 17
. 18
. 18
. 18
. 19
. 19
. 20
Chapter 2. Configuring network
discovery . . . . . . . . . . . . . 21
Planning for discovery. . . . . . . . . . . 21
Configuring standard discoveries . . . . . . . 22
Discovering the network using the wizard . . . 22
Discovering the network using the GUI . . . . 27
Discovering the network using the command-line
interface . . . . . . . . . . . . . . 56
Configuring specialized discoveries . . . . . . 104
Configuring a context-sensitive discovery . . . 104
Configuring EMS discoveries . . . . . . . 105
Configuring MPLS discoveries. . . . . . . 182
Configuring NAT discoveries . . . . . . . 194
Configuring cross-domain discoveries . . . . 208
Configuring geographical discoveries . . . . 219
Chapter 3. Monitoring network
discoveries . . . . . . . . . . . . 227
Monitoring network discovery from the GUI .
Monitoring full and partial discoveries . .
Monitoring discovery agent progress . .
Monitoring discovery from the command line.
Monitoring full and partial discoveries . .
© Copyright IBM Corp. 2006, 2017
.
.
.
.
.
.
.
.
.
.
227
227
230
233
233
.
.
.
to
.
.
.
.
.
. 245
. 245
. 246
.
.
.
.
.
247
249
249
250
251
Chapter 5. Keeping discovered
topology up-to-date. . . . . . . . . 253
Scheduling discoveries . . . . . . .
Viewing discovery status for a device . .
Manually discovering a device or subnet .
Manually discovering a device or subnet
the GUI . . . . . . . . . . .
Manually discovering a device or subnet
the command line . . . . . . . .
Removing a device from the network . .
Setting the linger time for a device . .
. .
. .
. .
using
. .
from
. .
. .
. .
. 253
. 254
. 255
. 255
. 259
. 260
. 260
Chapter 6. Troubleshooting discovery
261
Troubleshooting discovery with reports. . . .
Monitoring discovery status . . . . . . .
Process flow for creating discovery events . .
Monitoring discovery status messages . . .
NCIM entity ID retrieval failure . . . . .
Troubleshooting discovery agents. . . . . .
Troubleshooting an unusually long discovery
Identifying failed agents . . . . . . . .
Troubleshooting missing devices . . . . . .
Troubleshooting an idle discovery . . . . .
Repairing a corrupted discovery . . . . . .
Removing discovery cache files . . . . . .
Troubleshooting illegal characters. . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
261
262
262
263
263
265
265
266
267
268
268
269
270
Chapter 7. Discovering and using
custom data . . . . . . . . . . . . 271
Reasons for adding custom data . . . . . .
Discovering custom data . . . . . . . .
Adding name-value pairs to entities using the
File finder . . . . . . . . . . . .
Developing agents or collectors to retrieve
custom data . . . . . . . . . . . .
Adding data manually using custom tag tables
Storing custom data as name-value pairs in the
entityDetails table . . . . . . . . . . .
Importing name-value pairs into the DNCIM
discovery database . . . . . . . . .
Preserving custom name-value pairs between
discoveries . . . . . . . . . . . .
. 271
. 272
. 272
. 274
275
. 281
. 282
. 283
iii
Storing custom data in new database tables . . .
Creating new tables in the NCIM topology
database . . . . . . . . . . . . . .
Updating dNCIM to store custom data . . . .
Mapping retrieved data to DNCIM custom data
tables . . . . . . . . . . . . . . .
Using custom data to enrich events . . . . . .
Visualizing custom data in the Structure Browser
Using custom data in polling . . . . . . . .
Visualizing custom data in the topology views . .
284
284
285
286
288
290
291
291
Appendix A. Discovery databases . . 293
Discovery engine database . . . . . . . .
disco.agents table . . . . . . . . . .
disco.config table . . . . . . . . . .
disco.convergedTopologies table . . . . .
disco.dynamicConfigFiles table . . . . .
disco.events table . . . . . . . . . .
disco.filterCustomTags table . . . . . .
disco.ipCustomTags table . . . . . . .
disco.managedProcesses table . . . . . .
disco.NATStatus table . . . . . . . .
disco.profilingData table. . . . . . . .
disco.status table . . . . . . . . . .
disco.tempData table . . . . . . . . .
Example configuration of the disco.agents table
Example configuration of the disco.config table
Example configuration of the
disco.managedProcesses table . . . . . .
Discovery scope database . . . . . . . .
disco.scope database schema . . . . . .
Example scope database configuration . . .
Access databases . . . . . . . . . . .
snmpStack database . . . . . . . . .
telnetStack database . . . . . . . . .
Process management databases . . . . . .
Configuring the data flow: starting stitchers
on-demand . . . . . . . . . . . .
agents database schema . . . . . . . .
Stitchers database schema . . . . . . .
Subprocess databases . . . . . . . . . .
finders database schema . . . . . . . .
CollectorDetails database schema . . . . .
Details database schema . . . . . . . .
Finders databases . . . . . . . . . . .
collectorFinder database . . . . . . . .
dbEntryFinder database . . . . . . . .
fileFinder database . . . . . . . . .
pingFinder database . . . . . . . . .
The Helper Server databases . . . . . . .
ARPhelper database . . . . . . . . .
DNSHelper database . . . . . . . . .
PingHelper database . . . . . . . . .
snmpHelper database . . . . . . . .
snmpFilter database . . . . . . . . .
TelnetHelper database . . . . . . . .
XmlRpcHelper database . . . . . . . .
Tracking discovery databases . . . . . . .
translations database . . . . . . . . .
instrumentation database schema. . . . .
workingEntities database . . . . . . .
iv
.
.
.
.
.
.
.
.
.
.
.
.
.
293
293
295
304
305
305
306
307
307
307
308
309
312
312
313
.
.
.
.
.
.
.
.
314
314
314
322
325
325
329
331
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
331
332
334
335
336
339
342
344
345
347
349
350
354
354
357
360
364
370
371
375
378
379
382
385
IBM Tivoli Network Manager IP Edition: Discovery Guide
dbModel database . . . . . . . . . .
dbModel.access table . . . . . . . .
dbModel.entityDetails table. . . . . .
dbModel.entityMap table . . . . . .
Working topology databases . . . . . .
fullTopology database schema . . . . .
dNCIM schema. . . . . . . . . .
rediscoveryStore database . . . . . . .
rediscoveryStore.dataLibrary table . . .
rediscoveryStore.rediscoveredEntities table
Topology manager databases . . . . . .
ncimCache database . . . . . . . .
model database schema . . . . . . .
Failover database . . . . . . . . . .
Ignored cached data . . . . . . . .
The failover database schema . . . . .
Example failover database configuration .
Agent Template database . . . . . . .
Discovery agent despatch table . . . .
Discovery agent returns table . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
388
388
390
391
392
392
392
393
393
393
393
394
411
413
414
414
416
417
418
419
Appendix B. Discovery process . . . 421
Discovery subprocesses . . . . . . . . .
Discovery timing . . . . . . . . . . .
Discovery stages and phases . . . . . . .
Data processing stage . . . . . . . .
Data collection stage . . . . . . . . .
Advantages of staged discovery . . . . .
Criteria for multiphasing . . . . . . .
Managing the phases . . . . . . . . .
Discovery cycles . . . . . . . . . . .
Discovering device existence . . . . . .
Discovering device details (standard) . . .
Discovering device details (context-sensitive)
Discovering associated device addresses . .
Discovering device connectivity . . . . .
Creating the topology . . . . . . . .
Advanced discovery configuration options . .
Configurable discovery data flow. . . . .
Partial matching . . . . . . . . . .
Discovery process with EMS integration . . .
Discovering device existence with collectors .
Discovering basic device information . . .
Discovering detailed device information . .
Rediscovery . . . . . . . . . . . . .
Full and partial rediscovery . . . . . .
Rediscovery completion . . . . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
421
423
425
426
426
428
429
430
430
431
432
433
434
436
437
438
438
439
439
440
441
442
443
443
445
Appendix C. Discovery agents . . . . 447
Agents . . . . . . . . . . . . . .
Details agent . . . . . . . . . . .
Associated Address (AssocAddress) agent . .
Interface data retrieved by agents . . . .
Discovery agent definition file keywords . .
Types of agents. . . . . . . . . . . .
Discovery agents that discover connectivity
among Ethernet switches . . . . . . .
Connectivity at the layer 3 network layer . .
Topology data stored in an EMS . . . . .
Discovering connectivity among ATM devices
.
.
.
.
.
.
447
448
448
449
449
455
. 455
. 460
. 464
464
Agents for discovering MPLS devices .
Multicast agents . . . . . . . .
Discovering NAT gateways. . . . .
Discovering containment information .
Discovery agents for wireless networks.
Discovery agents on other protocols . .
Context-sensitive discovery agents . .
Task-specific discovery agents . . . .
Discovery agents for IPv6 . . . . .
Service Level Agreement agents . . .
Guidance for selecting agents . . . . .
Which IP layer agents to use . . . .
Which standard agents to use . . . .
Which specialized agents to run . . .
Suggested agents for a layer 3 discovery
Suggested agents for a layer 2 discovery
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
466
467
468
469
472
472
474
475
481
481
481
482
482
482
483
484
Appendix D. Helper System . . . . . 485
Helpers . . . . . .
Helper System operation
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
Dynamic timeouts .
.
.
.
.
.
.
.
.
.
.
. 486
Appendix E. Discovery stitchers . . . 487
Main discovery stitchers .
DNCIM stitchers . . .
Cross-domain stitchers .
.
.
.
.
.
.
.
.
.
.
.
.
Appendix F. Types of traps
.
.
.
.
.
.
.
.
.
.
.
.
. 487
. 505
. 514
. . . . . 517
Appendix G. Network Manager
glossary . . . . . . . . . . . . . 519
Notices . . . . . . . . . . . . . . 523
Trademarks .
.
.
.
.
.
.
.
.
.
.
.
.
. 525
Index . . . . . . . . . . . . . . . 527
. 485
. 486
Contents
v
vi
IBM Tivoli Network Manager IP Edition: Discovery Guide
Tables
1. Ping response times for IPv6 subnet masks
2. Schemas and tables to which the discovery
parameters are mapped . . . . . . .
3. User-editable discovery configuration files
4. Commands used to control the ncp_trapmux
process
. . . . . . . . . . . .
5. Default Java collectors . . . . . . .
6. Default Perl collectors. . . . . . . .
7. Components of EMS integration . . . .
8. Collecting topology data from EMS during
discovery . . . . . . . . . . . .
9. . . . . . . . . . . . . . . .
10. Java CSV Collector properties file . . . .
11. Data file properties . . . . . . . .
12. Data mappings . . . . . . . . . .
13. Data types . . . . . . . . . . .
14. Data source configuration . . . . . .
15. Explanation of command-line options
16. Explanation of command-line options
17. Explanation of command-line options
18. Configuring the blackbox collector . . .
19. Example of a blackbox.xml file . . . .
20. Number of pseudowires for an enhanced
Layer 2 VPN . . . . . . . . . . .
21. AsAgent agent . . . . . . . . . .
22. Format of ASMap.txt file . . . . . . .
23. Defining MPLS scoping requirements
24. NAT information added to a device record
25. Quick reference for NAT discovery
configuration . . . . . . . . . .
26. Format of NATGateways.txt file . . . .
27. Discovery phase status . . . . . . .
28. Ping finder status . . . . . . . . .
29. Agent states . . . . . . . . . . .
30. Entity states . . . . . . . . . . .
31. Query results . . . . . . . . . .
32. . . . . . . . . . . . . . . .
33. Report categories to use for discovery
troubleshooting . . . . . . . . . .
34. Agent states . . . . . . . . . . .
35. Entity states . . . . . . . . . . .
36. Methods for retrieving data . . . . . .
37. . . . . . . . . . . . . . . .
38. . . . . . . . . . . . . . . .
39. Data added to entities . . . . . . .
40. Line-by-line description of an example
GetCustomTag stitcher . . . . . . .
41. Example of name-value pair tags . . . .
42. Description of the insert . . . . . . .
43. Description of the insert . . . . . . .
44. Lines of code relevant to the interface name
example . . . . . . . . . . . .
45. disco.agents database table schema . . .
46. disco.config database table schema . . .
47. disco.convergedTopologies database table
schema . . . . . . . . . . . .
© Copyright IBM Corp. 2006, 2017
32
. 55
57
. 99
. 106
. 109
. 110
.
.
.
.
.
.
.
111
115
155
156
156
157
157
174
175
175
. 178
. 180
. 183
. 187
. 187
192
197
.
.
.
.
.
.
.
.
197
204
228
230
231
232
245
248
.
.
.
.
.
.
.
261
265
266
274
275
277
279
.
.
.
.
280
282
287
288
. 290
. 294
. 295
. 304
48. disco.dynamicConfigFiles database table
schema . . . . . . . . . . . . .
49. disco.events database table schema . . . .
50. disco.filterCustomTags database table schema
51. disco.ipCustomTags database table schema
52. disco.managedProcesses database table
schema . . . . . . . . . . . . .
53. disco.NATStatus database table schema
54. disco.profilingData database table schema
55. disco.status database table schema . . . .
56. disco.tempData database table schema
57. scope.detectionFilter database table schema
58. scope.inferMPLSPEs database table schema
59. scope.instantiateFilter database table schema
60. scope.zones database table schema . . . .
61. scope.multicastGroup database table schema
62. scope.multicastSource database table schema
63. scope.special database table schema . . . .
64. scope.zones database table schema . . . .
65. snmpStack.accessParameters database table
schema . . . . . . . . . . . . .
66. snmpStack.multibyteObjects database table
schema . . . . . . . . . . . . .
67. snmpStack.conversionCfg database table
schema . . . . . . . . . . . . .
68. snmpStack.verSecurityTable database table
schema . . . . . . . . . . . . .
69. telnetStack.passwords database table schema
70. agents.definitions database table schema
71. agents.sourceInfo database table schema
72. agents.status database table schema
73. agents.victims database table schema
74. stitchers.triggers database table schema
75. stitchers.status database table schema
76. stitchers.actions database table schema
77. finders.despatch database table schema
78. finders.returns database table schema
79. finders.pending database table schema
80. finders.processing database table schema
81. finders.rediscovery database table schema
82. CollectorDetails.despatch database table
schema . . . . . . . . . . . . .
83. CollectorDetails.returns database table
schema . . . . . . . . . . . . .
84. Details.despatch database table schema
85. Details.returns database table schema
86. Description of the finders . . . . . . .
87. collectorFinder.collectorRules database table
schema . . . . . . . . . . . . .
88. collectorFinder.configuration database table
schema . . . . . . . . . . . . .
89. dbEntryFinder.configuration database table
schema . . . . . . . . . . . . .
90. dbEntryFinder.dbQueries database table
schema . . . . . . . . . . . . .
91. fileFinder.configuration database table schema
305
305
306
307
307
307
308
309
312
315
315
317
317
318
319
320
321
326
327
327
328
330
332
332
333
334
334
335
335
336
337
337
338
339
340
340
342
343
344
345
347
348
348
349
vii
92. fileFinder.parseRules database table schema
93. pingFinder.configuration database table
schema . . . . . . . . . . . . .
94. pingFinder.pingFilter database table schema
95. pingFinder.pingRules database table schema
96. pingFinder.scope database table schema
97. ARPhelper.ARPHelperConfig database table
schema . . . . . . . . . . . . .
98. ARPHelper.ARPHelperTable database table
schema . . . . . . . . . . . . .
99. ARPHelper.configuration database table
schema . . . . . . . . . . . . .
100. DNSHelper.DNSHelperTable database table
schema . . . . . . . . . . . . .
101. DNSHelper.DNSHelperConfig database table
schema . . . . . . . . . . . . .
102. DNSHelper.configuration database table
schema . . . . . . . . . . . . .
103. DNShelper.methods database table schema
104. PingHelper.configuration database table
schema . . . . . . . . . . . . .
105. PingHelper.PingHelperConfig database table
schema . . . . . . . . . . . . .
106. PingHelper.PingHelperTable database table
schema . . . . . . . . . . . . .
107. snmpHelper.configuration database table
schema . . . . . . . . . . . . .
108. snmpHelper.dependentInstanceFilter database
table schema . . . . . . . . . . . .
109. snmpHelper.instanceFilter database table
schema . . . . . . . . . . . . .
110. snmpHelper.SnmpHelperConfig database
table schema . . . . . . . . . . . .
111. snmpHelper.SnmpHelperTable database table
schema . . . . . . . . . . . . .
112. snmpFilter.instances database table schema
113. TelnetHelper.configuration database table
schema . . . . . . . . . . . . .
114. TelnetHelper.deviceConfig database table
schema . . . . . . . . . . . . .
115. TelnetHelper.telnetHelperconfig database
table schema . . . . . . . . . . . .
116. TelnetHelper.telnetHelperTable database table
schema . . . . . . . . . . . . .
117. XmlRpcHelper.configuration database table
schema . . . . . . . . . . . . .
118. XmlRpcHelper.XmlRpcHelperConfig database
table schema . . . . . . . . . . . .
119. XmlRpcHelper.XmlRpcHelperTable database
table schema . . . . . . . . . . . .
120. translations.ipToBaseName database table
schema . . . . . . . . . . . . .
121. translations.vlans database table schema
122. translations.NAT database table schema
123. translations.NATtemp database table schema
124. translations.NATAddressSpaceIds database
table schema
. . . . . . . . . . .
125. specialManagementIPs table . . . . . .
126. instrumentation.ipAddresses database table
schema . . . . . . . . . . . . .
127. instrumentation.name database table schema
viii
350
351
352
352
353
354
356
357
357
358
359
359
361
361
363
364
365
366
368
369
371
371
372
373
375
376
376
378
379
380
380
381
381
381
383
383
IBM Tivoli Network Manager IP Edition: Discovery Guide
128. instrumentation.subNet database table
schema . . . . . . . . . . . . .
129. instrumentation.vlan database table schema
130. instrumentation.frameRelay database table
schema . . . . . . . . . . . . .
131. instrumentation.ciscoFrameRelay database
table schema
. . . . . . . . . . .
132. instrumentation.hsrp database table schema
133. instrumentation.pnniPeerGroup database
table schema
. . . . . . . . . . .
134. instrumentation.fddi database table schema
135. workingEntities.finalEntity database table
schema . . . . . . . . . . . . .
136. workingEntities.containment database table
schema . . . . . . . . . . . . .
137. workingEntities.interfaceMapping database
table schema
. . . . . . . . . . .
138. dbModel.access database table schema
139. dbModel.entityDetails database table
schema . . . . . . . . . . . . .
140. dbModel.entityMap database table schema
141. fullTopology.entityByNeighbor database table
schema . . . . . . . . . . . . .
142. rediscoveryStore.dataLibrary database table
schema . . . . . . . . . . . . .
143. rediscoveryStore.rediscoveredEntities
database table schema . . . . . . . .
144. ncimCache.collects database table schema
145. ncimCache.connectActions database table
schema . . . . . . . . . . . . .
146. ncimCache.connects database table schema
147. ncimCache.contains database table schema
148. ncimCache.dependency database table
schema . . . . . . . . . . . . .
149. ncimCache.domainMembers database table
schema . . . . . . . . . . . . .
150. ncimCache.entityActions database table
schema . . . . . . . . . . . . .
151. ncimCache.entityData database table
schema . . . . . . . . . . . . .
152. ncimCache.hostedService database table
schema . . . . . . . . . . . . .
153. ncimCache.lingerTime database table
schema . . . . . . . . . . . . .
154. ncimCache.managedStatus database table
schema . . . . . . . . . . . . .
155. ncimCache.networkPipe database table
schema . . . . . . . . . . . . .
156. ncimCache.pipeComposition database table
schema . . . . . . . . . . . . .
157. ncimCache.protocolEndpoint database table
schema . . . . . . . . . . . . .
158. model.config database table schema
159. model.profilingData database table schema
160. model.statistics database table schema
161. failover.config database table schema
162. failover.status database table schema
163. failover.findRateDetails database table
schema . . . . . . . . . . . . .
164. failover.doNotCache database table schema
383
383
384
384
384
385
385
385
387
388
388
390
391
392
393
393
394
395
396
397
399
400
401
402
405
406
407
408
409
410
411
412
413
414
415
415
416
165. failover.restartPhaseAction database table
schema . . . . . . . . . . . .
166. agentTemplate.despatch database table
schema . . . . . . . . . . . .
167. agentTemplate.returns database table schema
168. Discovery components . . . . . . .
169. Data collection and data processing stages
170. Ethernet switch discovery agents . . . .
171. Layer 3 network layer agents . . . . .
172. Routing protocol discovery agents . . .
173. ATM discovery agents . . . . . . .
174. MPLS discovery agents . . . . . . .
175. Multicast discovery agents . . . . . .
176. NAT gateway agents . . . . . . . .
. 416
. 418
419
. 421
424
. 455
. 460
. 464
. 464
. 466
. 467
. 468
177. Discovery agents that discover containment
information . . . . . . . . . . .
178. Discovery agents on wireless networks
179. Discovery agents on other protocols . . .
180. Context-sensitive discovery agents
181. Task-specific discovery agents . . . . .
182. IPv6 agent template . . . . . . . .
183. SLA agents . . . . . . . . . . .
184. Helpers available with Network Manager
185. List of main discovery stitchers . . . .
186. List of DNCIM discovery stitchers . . .
187. Cross-domain stitchers . . . . . . .
188. Types of traps . . . . . . . . . .
189. IBM trademarks. . . . . . . . . .
Tables
. 469
472
. 472
474
. 475
. 481
. 481
485
. 487
. 505
. 514
. 517
. 525
ix
x
IBM Tivoli Network Manager IP Edition: Discovery Guide
About this publication
IBM Tivoli Network Manager IP Edition provides detailed network discovery,
device monitoring, topology visualization, and root cause analysis (RCA)
capabilities. Network Manager can be extensively customized and configured to
manage different networks. Network Manager is tightly integrated with IBM Tivoli
Netcool/OMNIbus. When installed together with the IBM Netcool Operations
Insight infrastructure and operations management solution, then Network Manager
is a key component within that solution, where it is also tightly integrated with
Netcool/Impact, and IBM Operations Analytics - Log Analysis. Network Manager
also provides extensive reporting features, and integration with other IBM
products, such as IBM Tivoli Application Dependency Discovery Manager, IBM
Tivoli Business Service Manager and IBM Tivoli Monitoring.
The IBM Tivoli Network Manager IP Edition Discovery Guide describes how to
administer and use Network Manager to perform network discoveries.
Audience
This publication is for users and system and network administrators who configure
IBM Tivoli Network Manager IP Edition.
IBM Tivoli Network Manager IP Edition works in conjunction with IBM Tivoli
Netcool/OMNIbus; this publication assumes that you understand how IBM Tivoli
Netcool/OMNIbus works. For more information on IBM Tivoli Netcool/OMNIbus,
see the publications described in “Publications” on page xii.
What this publication contains
This publication contains the following sections:
v Chapter 1, “About discovery,” on page 1
Describes the concept of discovery, and the parameters that can be set to
discover a network.
v Chapter 2, “Configuring network discovery,” on page 21
Describes the prerequisites that must be met before a discovery can be
configured and launched.
Also describes how to run discoveries using:
– The Discovery Wizard for performing an initial discovery, and for setting
basic discovery parameters.
– The Discovery Configuration GUI for setting advanced discovery parameters.
– The CLI and the configuration files to configure the discovery process.
There is also information on how to set complex discovery parameters, for
example using Element Management Systems, MPLS and NAT.
v Chapter 3, “Monitoring network discoveries,” on page 227
Describes how to monitor the state and progress of your network discovery
using the GUI or the command line.
v Chapter 4, “Classifying network devices,” on page 245
Describes how to change the way network devices are classified following
discovery.
© Copyright IBM Corp. 2006, 2017
xi
v Chapter 5, “Keeping discovered topology up-to-date,” on page 253
Describes how to schedule a discovery, manually discover devices, and remove
devices.
v Chapter 6, “Troubleshooting discovery,” on page 261
Describes how to troubleshoot both the discovery process, and the network that
you want to discover.
v Chapter 7, “Discovering and using custom data,” on page 271
You can enrich the topology by adding custom data to the information
discovered by the discovery process.
v Appendix A, “Discovery databases,” on page 293
Describes the databases used by ncp_disco, the component that discovers
network device existence and connectivity, and by ncp_model, the component
that manages, stores, and distributes the discovered network topology.
v Appendix B, “Discovery process,” on page 421
Describes how IBM Tivoli Network Manager IP Edition produces a network
topology that includes connectivity and containment data.
v Appendix C, “Discovery agents,” on page 447
Describes the discovery agents available to run as part of your discovery. There
is also guidance on the agents to select, based on the characteristics of your
network.
v Appendix D, “Helper System,” on page 485
Provides background information on the helpers, which are specialized
applications that retrieve information from the network on demand.
v “Main discovery stitchers” on page 487
Describes the stitchers supplied with IBM Tivoli Network Manager IP Edition.
v Appendix F, “Types of traps,” on page 517
Describes the different types of traps that might be encountered by the Trap
finder.
Publications
This section lists publications in the Network Manager library and related
documents. The section also describes how to access IBM publications online and
how to order publications.
Your Network Manager library
The following documents are available in the Network Manager library:
v IBM Tivoli Network Manager IP Edition Release Notes, GI11-9354-00
Gives important and late-breaking information about IBM Tivoli Network
Manager IP Edition. This publication is for deployers and administrators, and
should be read first.
v IBM Tivoli Network Manager Getting Started Guide, GI11-9353-00
This guide describes how to set up IBM Tivoli Network Manager IP Edition after
you have installed the product. This guide describes how to start the product,
make sure it is running correctly, and discover the network. Getting a good
network discovery is central to using Network Manager successfully. This guide
describes how to configure and monitor a first discovery, verify the results of the
discovery, configure a production discovery, and how to keep the network
topology up to date. Once you have an up-to-date network topology, this guide
describes how to make the network topology available to Network Operators,
xii
IBM Tivoli Network Manager IP Edition: Discovery Guide
and how to monitor the network. The essential tasks are covered in this short
guide, with references to the more detailed, optional, or advanced tasks and
reference material in the rest of the documentation set.
v IBM Tivoli Network Manager IP Edition Product Overview, GC27-2759-00
Gives an overview of IBM Tivoli Network Manager IP Edition. It describes the
product architecture, components and functionality. This publication is for
anyone interested in IBM Tivoli Network Manager IP Edition.
v IBM Tivoli Network Manager IP Edition Installation and Configuration Guide,
SC27-2760-00
Describes how to install IBM Tivoli Network Manager IP Edition. It also
describes necessary and optional post-installation configuration tasks. This
publication is for administrators who need to install and set up IBM Tivoli
Network Manager IP Edition.
v IBM Tivoli Network Manager IP Edition Administration Guide, SC27-2761-00
Describes administration tasks for IBM Tivoli Network Manager IP Edition, such
as how to administer processes, query databases and start and stop the product.
This publication is for administrators who are responsible for the maintenance
and availability of IBM Tivoli Network Manager IP Edition.
v IBM Tivoli Network Manager IP Edition Discovery Guide, SC27-2762-00
Describes how to use IBM Tivoli Network Manager IP Edition to discover your
network. This publication is for administrators who are responsible for
configuring and running network discovery.
v IBM Tivoli Network Manager IP Edition Event Management Guide, SC27-2763-00
Describes how to use IBM Tivoli Network Manager IP Edition to poll network
devices, to configure the enrichment of events from network devices, and to
manage plug-ins to the Tivoli Netcool/OMNIbus Event Gateway, including
configuration of the RCA plug-in for root-cause analysis purposes. This
publication is for administrators who are responsible for configuring and
running network polling, event enrichment, root-cause analysis, and Event
Gateway plug-ins.
v IBM Tivoli Network Manager IP Edition Network Troubleshooting Guide,
GC27-2765-00
Describes how to use IBM Tivoli Network Manager IP Edition to troubleshoot
network problems identified by the product. This publication is for network
operators who are responsible for identifying or resolving network problems.
v IBM Tivoli Network Manager IP Edition Network Visualization Setup Guide,
SC27-2764-00
Describes how to configure the IBM Tivoli Network Manager IP Edition network
visualization tools to give your network operators a customized working
environment. This publication is for product administrators or team leaders who
are responsible for facilitating the work of network operators.
v IBM Tivoli Network Manager IP Edition Management Database Reference,
SC27-2767-00
Describes the schemas of the component databases in IBM Tivoli Network
Manager IP Edition. This publication is for advanced users who need to query
the component databases directly.
v IBM Tivoli Network Manager IP Edition Topology Database Reference, SC27-2766-00
Describes the schemas of the database used for storing topology data in IBM
Tivoli Network Manager IP Edition. This publication is for advanced users who
need to query the topology database directly.
v IBM Tivoli Network Manager IP Edition Language Reference, SC27-2768-00
About this publication
xiii
Describes the system languages used by IBM Tivoli Network Manager IP
Edition, such as the Stitcher language, and the Object Query Language. This
publication is for advanced users who need to customize the operation of IBM
Tivoli Network Manager IP Edition.
v IBM Tivoli Network Manager IP Edition Perl API Guide, SC27-2769-00
Describes the Perl modules that allow developers to write custom applications
that interact with the IBM Tivoli Network Manager IP Edition. Examples of
custom applications that developers can write include Polling and Discovery
Agents. This publication is for advanced Perl developers who need to write such
custom applications.
v IBM Tivoli Monitoring for Tivoli Network Manager IP User's Guide, SC27-2770-00
Provides information about installing and using IBM Tivoli Monitoring for IBM
Tivoli Network Manager IP Edition. This publication is for system
administrators who install and use IBM Tivoli Monitoring for IBM Tivoli
Network Manager IP Edition to monitor and manage IBM Tivoli Network
Manager IP Edition resources.
Prerequisite publications
To use the information in this publication effectively, you must have some
prerequisite knowledge, which you can obtain from the following publications:
v IBM Tivoli Netcool/OMNIbus Installation and Deployment Guide, SC23-9680
Includes installation and upgrade procedures for Tivoli Netcool/OMNIbus, and
describes how to configure security and component communications. The
publication also includes examples of Tivoli Netcool/OMNIbus architectures and
describes how to implement them.
v IBM Tivoli Netcool/OMNIbus User's Guide, SC23-9683
Provides an overview of the desktop tools and describes the operator tasks
related to event management using these tools.
v IBM Tivoli Netcool/OMNIbus Administration Guide, SC23-9681
Describes how to perform administrative tasks using the Tivoli
Netcool/OMNIbus Administrator GUI, command-line tools, and process control.
The publication also contains descriptions and examples of ObjectServer SQL
syntax and automations.
v IBM Tivoli Netcool/OMNIbus Probe and Gateway Guide, SC23-9684
Contains introductory and reference information about probes and gateways,
including probe rules file syntax and gateway commands.
v IBM Tivoli Netcool/OMNIbus Web GUI Administration and User's Guide SC23-9682
Describes how to perform administrative and event visualization tasks using the
Tivoli Netcool/OMNIbus Web GUI.
Accessing terminology online
The IBM Terminology Web site consolidates the terminology from IBM product
libraries in one convenient location. You can access the Terminology Web site at the
following Web address:
http://www.ibm.com/software/globalization/terminology
xiv
IBM Tivoli Network Manager IP Edition: Discovery Guide
Accessing publications online
IBM posts publications for this and all other products, as they become available
and whenever they are updated, to the IBM Knowledge Center Web site at:
http://www.ibm.com/support/knowledgecenter/
Network Manager documentation is located under the Cloud & Smarter
Infrastructure node on that Web site.
Note: If you print PDF documents on other than letter-sized paper, set the option
in the File > Print window that allows your PDF reading application to print
letter-sized pages on your local paper.
Ordering publications
You can order many IBM publications online at the following Web site:
http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss
You can also order by telephone by calling one of these numbers:
v In the United States: 800-879-2755
v In Canada: 800-426-4968
In other countries, contact your software account representative to order IBM
publications. To locate the telephone number of your local representative, perform
the following steps:
1. Go to the following Web site:
http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss
2. Select your country from the list and click Go. The Welcome to the IBM
Publications Center page is displayed for your country.
3. On the left side of the page, click About this site to see an information page
that includes the telephone number of your local representative.
Accessibility
Accessibility features help users with a physical disability, such as restricted
mobility or limited vision, to use software products successfully.
Accessibility features
Network Manager includes the following major accessibility features:
v Operations that use a screen reader.
Network Manager uses IBM Installation Manager to install the product. You can
read about the accessibility features for IBM Installation Manager at
http://www-01.ibm.com/support/knowledgecenter/SSDV2W/
im_family_welcome.html.
Network Manager uses the latest W3C Standard, WAI-ARIA 1.0
(http://www.w3.org/TR/wai-aria/), to ensure compliance to US Section 508
(http://www.access-board.gov/guidelines-and-standards/communications-and-it/
about-the-section-508-standards/section-508-standards), and Web Content
Accessibility Guidelines (WCAG) 2.0 (http://www.w3.org/TR/WCAG20/). To take
About this publication
xv
advantage of accessibility features, use the latest release of your screen reader in
combination with the latest web browser that is supported by this product.
The Network Manager online product documentation in IBM Knowledge Center is
enabled for accessibility. The accessibility features of IBM Knowledge Center are
described at https://www.ibm.com/support/knowledgecenter/v1/content/about/
releasenotes.html#accessibility.
Keyboard navigation
This product uses standard navigation keys.
Interface information
Network Manager provides the following features suitable for low vision users:
v All non-text content used in the GUI has associated alternative text.
v Low-vision users can adjust the system display settings, including high contrast
mode, and can control the font sizes using the browser settings.
v Color is not used as the only visual means of conveying information, indicating
an action, prompting a response, or distinguishing a visual element.
Network Manager provides the following features suitable for photosensitive
epileptic users:
v The Network Manager user interfaces do not have content that flashes more
than two times in any one second period.
The Network Manager web user interface includes WAI-ARIA navigational
landmarks that you can use to quickly navigate to functional areas in the
application.
Extra steps to configure Internet Explorer for accessibility
If you are using Internet Explorer as your web browser, you might need to
perform extra configuration steps to enable accessibility features.
To enable high contrast mode, complete the following steps:
1. Click Tools > Internet Options > Accessibility.
2. Select all the check boxes in the Formatting section.
If clicking View > Text Size > Largest does not increase the font size, click Ctrl +
and Ctrl -.
Related accessibility information
In addition to standard IBM help desk and support websites, IBM has established
a TTY telephone service for use by deaf or hard of hearing customers to access
sales and support services:
TTY service
800-IBM-3383 (800-426-3383)
(within North America)
xvi
IBM Tivoli Network Manager IP Edition: Discovery Guide
IBM and accessibility
For more information about the commitment that IBM has to accessibility, see IBM
Accessibility (www.ibm.com/able).
Tivoli technical training
For Tivoli technical training information, refer to the following IBM Tivoli
Education Web site:
http://www.ibm.com/software/tivoli/education
Support and community information
Use IBM Support, Service Management Connect, and Tivoli user groups to connect
with IBM and get the help and information you need.
IBM Support
If you have a problem with your IBM software, you want to resolve it quickly. IBM
provides the following ways for you to obtain the support you need:
Online
Go to the IBM Software Support site at http://www.ibm.com/software/
support/probsub.html and follow the instructions.
IBM Support Assistant
The IBM Support Assistant (ISA) is a free local software serviceability
workbench that helps you resolve questions and problems with IBM
software products. The ISA provides quick access to support-related
information and serviceability tools for problem determination. To install
the ISA software, go to http://www.ibm.com/software/support/isa
Tivoli User Community
The Tivoli User Community is an independent, user-run membership organization
that provides Tivoli users with information to assist them in the implementation of
Tivoli Software solutions. Through these groups, members can share information
and learn from the knowledge and experience of other Tivoli users. Access the link
for the Tivoli Users Community at www.tivoli-ug.org.
Service Management Connect
Access Service Management Connect at https://www.ibm.com/developerworks/
servicemanagement/nsa/index.html. Use Service Management Connect in the
following ways:
v Become involved with transparent development, an ongoing, open engagement
between other users and IBM developers of Tivoli products. You can access early
designs, sprint demonstrations, product roadmaps, and prerelease code.
v Connect one-on-one with the experts to collaborate and network about Tivoli
and the community.
v Read blogs to benefit from the expertise and experience of others.
v Use wikis and forums to collaborate with the broader user community.
About this publication
xvii
Conventions used in this publication
This publication uses several conventions for special terms and actions and
operating system-dependent commands and paths.
Typeface conventions
This publication uses the following typeface conventions:
Bold
v Lowercase commands and mixed case commands that are otherwise
difficult to distinguish from surrounding text
v Interface controls (check boxes, push buttons, radio buttons, spin
buttons, fields, folders, icons, list boxes, items inside list boxes,
multicolumn lists, containers, menu choices, menu names, tabs, property
sheets), labels (such as Tip:, and Operating system considerations:)
v Keywords and parameters in text
Italic
v Citations (examples: titles of publications, diskettes, and CDs
v Words defined in text (example: a nonswitched line is called a
point-to-point line)
v Emphasis of words and letters (words as words example: "Use the word
that to introduce a restrictive clause."; letters as letters example: "The
LUN address must start with the letter L.")
v New terms in text (except in a definition list): a view is a frame in a
workspace that contains data.
v Variables and values you must provide: ... where myname represents....
Monospace
v Examples and code examples
v File names, programming keywords, and other elements that are difficult
to distinguish from surrounding text
v Message text and prompts addressed to the user
v Text that the user must type
v Values for arguments or command options
Bold monospace
v Command names, and names of macros and utilities that you can type
as commands
v Environment variable names in text
v Keywords
v Parameter names in text: API structure parameters, command
parameters and arguments, and configuration parameters
v Process names
v Registry variable names in text
v Script names
xviii
IBM Tivoli Network Manager IP Edition: Discovery Guide
Operating system-dependent variables and paths
This publication uses environment variables without platform-specific prefixes and
suffixes, unless the command applies only to specific platforms. For example, the
directory where the Network Manager core components are installed is represented
as NCHOME.
On UNIX systems, preface environment variables with the dollar sign $. For
example, on UNIX, NCHOME is $NCHOME.
About this publication
xix
xx
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 1. About discovery
Configure discovery by setting the parameters that govern how the discovery is
performed.
About types of discovery
Different terms are used to describe network discovery, depending on what is
being discovered and how the discovery has been configured. You can run
discoveries, rediscoveries, and full and partial discoveries.
Discovery and rediscovery
Discovery
The term discovery is used generally to mean any kind of discovery.
Technically, only the first discovery that is run after the discovery engine,
ncp_disco, is started can properly be called a discovery, and every
discovery after that is a rediscovery. Because there is no discovery data in
memory yet, discoveries take slightly longer than rediscoveries.
Rediscovery
After a discovery has been run, any further discoveries that are run are
rediscoveries. Rediscoveries use a different data flow to discoveries, with
some different stitchers and database tables. If ncp_disco is restarted, the
next discovery is again just a discovery, and further discoveries after that
are rediscoveries. Unless you are running advanced discoveries or
modifying the discovery data flow, the difference between a discovery and
a rediscovery is not usually important, and, for ease of reading, the
instructions in this information do not distinguish between discovery and
rediscovery unless it is necessary.
Full and partial discovery
Full discovery
A full discovery is a discovery run with a large scope, intended to discover
all of the network devices that you want to manage. Full discoveries are
usually just called discoveries, unless they are being contrasted with partial
discoveries.
Partial discovery
A partial discovery is a subsequent rediscovery of a section of the
previously discovered network. The section of the network is usually
defined using a discovery scope consisting of either an address range, a
single device, or a group of devices. A partial discovery relies on the
results of the last full discovery, and can only be run if the discovery
engine, the ncp_disco process, has not been stopped since the last full
discovery. A partial discovery is, therefore, actually a type of rediscovery.
Scheduled discovery
You can schedule a full discovery to start at a certain time. For example, you can
schedule a full discovery to run at the same time every night, or at the same time
on the same day every week, or at the same time every day of the month.
Related concepts:
© Copyright IBM Corp. 2006, 2017
1
“Full and partial rediscovery” on page 443
By modifying the stitchers, you can configure the way DISCO treats devices that
are found in the rediscovery mode.
Related tasks:
“Scheduling discoveries” on page 253
After a full discovery completes, you can schedule further discoveries by inserting
the time, date, and day for discoveries to run in the FullDiscovery.stch stitcher
file.
“Starting a discovery” on page 52
After you configure a discovery, you can start and, if necessary, stop the discovery.
“Starting partial discovery from the GUI” on page 257
Starting a partial discovery involves defining a seed and scopes.
Scopes
Define the zones of the network (that is, subnet ranges) that you want to include
in the discovery, and the zones that you want to exclude. The areas of the network
to be included in the discovery process, or excluded from the discovery process are
collectively known as the discovery scope.
There are several benefits to limiting the discovery scope:
v It is important to limit discovery scope because the range of IP addresses
considered by the default discovery process is potentially unlimited. Without a
scope, the discovery attempts to recognize every network device. By limiting the
scope, you can concentrate on the important areas of your network.
Attention: If there are routes out of your network to the Internet, then an
unscoped discovery will find these routes and proceed to discover parts of the
Internet.
v You might also want to restrict the scope of the discovery to control the
discovery of sensitive devices that you do not want to poll. A device might be
considered sensitive because there is a security risk involved in polling the
device, or because polling might overload the device. You can specify that
particular devices are discovered but not instantiated to an AOC definition (such
devices are discovered but are not represented in the network topology and their
details are not sent to MODEL). You can also restrict devices from being
discovered (SNMP access to any such device is not attempted).
v Another reason for scoping the discovery is that it restricts the amount of data
Network Manager tries to download from the routing tables of individual
routers. Without this restriction, if Network Manager finds a router that knows
the routing table for the whole Internet, then discovery takes a very long time to
complete.
Restriction: Network Manager does not support the IPv4–mapped IPv6 format
and expects all IPv6 addresses to be in standard colon-separated IPv6 format. For
example, Network Manager does not aupport an IPv4–mapped IPv6 address such
as ::ffff:192.0.2.128. Instead this address must be entered as ::ffff:c000:280
(standard colon-separated IPv6 format).
2
IBM Tivoli Network Manager IP Edition: Discovery Guide
Types of scoping
Network Manager offers several types of scoping.
You can enable the following types of scoping:
v You can include or exclude areas of your network (either subnet ranges or
specific devices) in the discovery. Each configured area is referred to as a zone.
Tip: If your subnet is sparsely populated, including individual routers is likely
to result in a faster discovery than including the whole subnet.
v Zones can be specified within zones: within a given inclusion zone, you can
specify devices or subnets that are not to be detected. These devices are not
pinged by the Ping finder or interrogated by the discovery agents. For example,
you can define an include scope zone consisting of the Class B subnet 1.2.0.0/16,
and within that zone you can specify an exclude scope zone consisting of the
Class C subnet 1.2.3.0/24. Finally, within the exclude scope zone you could
specify an include scope zone 1.2.3.128/26.
v You can include or exclude non-IP devices, such as layer 1 optical devices, using
a filter.
v You can configure a filter that determines whether a discovered device is
interrogated for connectivity information.
v You can configure multicast scoping. This enables you to configure which
multicast subnets to use as scopes for your multicast discovery.
Defining discovery zones to restrict discovery
To restrict the discovery, you must define discovery zones. You can define
discovery zones in several ways.
Choose one of the following methods to define a discovery zone:
v Define discovery zones using the Discovery Configuration GUI.
v Construct zones by appending an OQL insert into the scope.zones table with the
DiscoScope.cfg configuration file. This method is for more experienced users.
Note: If nothing is specified in the scope.zones table then everything is considered
to be in scope.
For each zone you must specify the following information:
v The type of network protocol used by the zone, although currently only IP is
supported. You can define as many zones as necessary. Multiple zones can also
be defined within the same insert.
v The action to be taken for the zone, where m_Action=1 means include in the
discovery, and m_Action=2 means exclude. You can define both inclusion and
exclusion zones. The action to be taken in the smallest zone overrides the actions
in the larger zones.
v A list of varbinds (name=value) that define the present discovery zone.
Related tasks:
“Defining multiple inclusion zones” on page 10
You can define multiple inclusion zones in the scope.zones table.
“Scoping discovery” on page 27
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
Chapter 1. About discovery
3
Examples of discovery zones
Use this information to understand how inclusion and exclusion zones define
which devices are included in and excluded from the discovery. The diagrams in
this section show that the smallest zone takes priority.
Inclusion zone:
Use this information to understand how an inclusion zone works.
The following figure shows an inclusion zone, 172.18.1.0/24.
v An entity with IP address 172.18.1.33 is within the inclusion zone and is
therefore discovered.
v An entity with IP address 172.18.2.33 is outside the inclusion zone and is
therefore not discovered.
172.18.1.0/24
172.18.1.33
172.18.2.33
Figure 1. Inclusion zone, with device inside and outside the zone.
Exclusion zone within inclusion zone:
Use this information to understand how scoping works for an exclusion zone
within an inclusion zone.
The following figure shows an exclusion zone within an inclusion zone.
v An entity with IP address 172.18.1.33 is within the exclusion zone and is
therefore not discovered.
v An entity with IP address 172.18.2.33 is within the inclusion zone and is
therefore discovered.
v An entity with IP address 172.19.3.2 is outside of the inclusion zone and is
therefore not discovered.
4
IBM Tivoli Network Manager IP Edition: Discovery Guide
172.18.0.0/16
172.18.1.0/24
172.18.1.33
172.18.2.33
172.19.3.2
Figure 2. Exclusion zone within an inclusion zone
Inclusion, exclusion, and inclusion zone:
Use this information to understand how device scoping works for an inclusion
zone within an exclusion zone within an inclusion zone.
The following figure shows an inclusion zone within an exclusion zone within an
inclusion zone.
v An entity with IP address 172.18.1.33 is within the inclusion zone and is
therefore discovered.
v An entity with IP address 172.18.2.33 is within the exclusion zone and is
therefore not discovered.
v An entity with IP address 172.19.3.2 is within the inclusion zone and is therefore
discovered.
v An entity with IP address 172.19.3.2 is outside of the inclusion zone and is
therefore not discovered.
Chapter 1. About discovery
5
172.0.0.0/8
172.18.0.0/16
172.18.1.0/24
172.18.1.33
172.18.2.33
172.19.3.2
173.20.1.5
Figure 3. Inclusion zone within an exclusion zone within an inclusion zone
Exclusion zone:
Use this information to understand how scoping works for an exclusion zone
works.
The following figure shows an exclusion zone, 172.18.1.0/24.
v An entity with IP address 172.18.1.33 is within the exclusion zone and is
therefore not discovered.
v An entity with IP address 172.18.2.33 is outside of the exclusion zone and is
therefore discovered.
6
IBM Tivoli Network Manager IP Edition: Discovery Guide
172.18.1.0/24
172.18.1.33
172.18.2.33
Figure 4. Exclusion zone
Inclusion zone within exclusion zone:
Use this information to understand how scoping works for an inclusion zone
within an exclusion zone.
The following figure shows an inclusion zone within an exclusion zone.
v An entity with IP address 172.18.1.33 is within the inclusion zone and is
therefore discovered.
v An entity with IP address 172.18.2.33 is within the exclusion zone and is
therefore not discovered.
v An entity with IP address 172.19.3.2 is outside of the exclusion zone and is
therefore discovered.
Chapter 1. About discovery
7
172.18.0.0/16
172.18.1.0/24
172.18.1.33
172.18.2.33
172.19.3.2
Figure 5. Inclusion zone within an exclusion zone
Exclusion, inclusion, and exclusion zone:
Use this information to understand how device scoping works for an exclusion
zone within an inclusion zone within an exclusion zone.
The following figure shows an exclusion zone within an inclusion zone within an
exclusion zone.
v An entity with IP address 172.18.1.33 is within the exclusion zone and is
therefore not discovered.
v An entity with IP address 172.18.2.33 is within the inclusion zone and is
therefore discovered.
v An entity with IP address 172.19.3.2 is within the exclusion zone and is therefore
not discovered.
v An entity with IP address 172.19.3.2 is outside of the exclusion zone and is
therefore discovered.
8
IBM Tivoli Network Manager IP Edition: Discovery Guide
172.0.0.0/8
172.18.0.0/16
172.18.1.0/24
172.18.1.33
172.18.2.33
172.19.3.2
173.20.1.5
Figure 6. Exclusion zone within an inclusion zone within an exclusion zone
Defining a single inclusion zone
Use this information to understand how to define a single inclusion zone.
An inclusion zone is any zone that you want to be discovered by the Discovery
engine, ncp_disco. The following example insert defines a single inclusion zone for
the IP protocol and associates the zone with a subnet. This zone applies to every
device within the specified subnet address.
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[
{
m_Subnet="172.16.1.0",
m_NetMask=24
}
]
);
The above insert defines an IP inclusion zone for the 172.16.1.0 subnet with a
netmask of 24.
Chapter 1. About discovery
9
Defining multiple inclusion zones
You can define multiple inclusion zones in the scope.zones table.
In the following example, three different IP inclusion zones are defined within a
single insert.
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[
{
m_Subnet="172.16.1.0",
m_NetMask=24
},
{
m_Subnet="172.16.2.*"
},
{
m_Subnet="172.16.3.0",
m_NetMask=255.255.255.0
}
]
);
The above example defines three different IP inclusion zones each using a different
syntax to define the subnet mask. Network Manager discovers:
v Any device that falls within the 172.16.1.0 subnet (with a subnet mask of 24, that
is, 24 bits turned on and 8 bits turned off, which implies a netmask of
255.255.255.0).
v Any device with an IP address starting with "172.16.2", that is, in the 172.16.2.0
subnet with a mask of 255.255.255.0.
v Any device that falls within the 172.16.3.0 subnet with a mask of 255.255.255.0.
Related concepts:
“Defining discovery zones to restrict discovery” on page 3
To restrict the discovery, you must define discovery zones. You can define
discovery zones in several ways.
Defining exclusion zones
Use this information to understand how to define exclusion zones.
An exclusion zone is any zone that you do not want to be discovered by the
Discovery engine, ncp_disco. Multiple exclusion zones can be created within the
same insert in the same way as inclusion zones. The following example insert
defines a single exclusion zone for the IP protocol, and associates the zone with a
subnet.
insert into scope.zones
(m_Protocol, m_Action, m_Zones)
values (1, 2,[{m_Subnet="172.16.1.0", m_NetMask=24]);
10
IBM Tivoli Network Manager IP Edition: Discovery Guide
Defining zones for NAT address spaces
Use this information to understand how to define zones for NAT address spaces.
Inclusion and exclusion zones can be customized for individual NAT domains,
using the m_AddressSpace column of the scope.zones table. The following example
insert defines an inclusion zone within a particular NAT domain.
insert into scope.zones
(
m_Protocol, m_Action, m_Zones, m_AddressSpace
)
values
(
1,
1,
[
{
m_Subnet="172.16.2.*",
}
],
"NATDomain1"
);
Restricting detection of specific devices
You can specify individual devices or subnets that the Ping finder is not to ping.
Since the Ping finder has not detected their existence, these devices or subnets are
not interrogated by the discovery agents.
Restricting interrogation of specific devices
You can exclude specific devices from the discovery by specifying that after their
initial detection those devices are not to be interrogated further for connectivity
information.
In order to specify devices that must not be detected, you must append an OQL
insert into the scope.detectionFilter table to the DiscoScope.cfg configuration file.
There must only be one insert into the scope.detectionFilter table per protocol.
Multiple conditions must be defined within a single insert.
Within the detectionFilter table you must specify:
v The type of network protocol. Currently only IP is supported.
v The filter condition(s). Only devices that pass this filter, that is, for which the
filter evaluates true, are further investigated. If no filter is specified, all devices
are passed through the detection filter.
A stitcher tests each discovered device against the filter condition in the
scope.detectionFilter table, and the outcome of this test determines whether the
device is discovered. Since the process flow of the discovery is fully configurable,
you can configure this stitcher to act at any time during the discovery process. By
default, the stitcher performs the conditional test on the device details returned by
the Details agent. Your filter must therefore be based on the columns of the
Details.returns table. The following examples show how you might configure the
detection filter.
Attention: Multiple examples are shown for illustrative purposes only. In practice
you must ensure that there is only one insert into the scope.detectionFilter table
per protocol.
Chapter 1. About discovery
11
Preventing the Interrogation of a Device Based on the IP Address
In this example only devices that do not have the IP address 10.10.63.234
are interrogated further.
insert into scope.detectionFilter
(
m_Protocol, m_Filter
)
values
(
1,
"( ( m_UniqueAddress <> ’10.10.63.234’ ) )"
);
Interrogation Restriction Based on Object ID
The following example shows how you would prevent the further
interrogation of devices that match a given Object ID. The OQL not like
clause indicates that only devices that pass the filter (that is, devices for
which the OID is not like 1.3.6.1.4.1.*) are interrogated further.
insert into scope.detectionFilter
(
m_Protocol,
m_Filter
)
values
(
1,
"(
( m_ObjectId not like ’1\.3\.6\.1\.4\.1\..*’ )
)"
);
The backslash must be used in the above insert to escape the ., which
would otherwise be treated as a wildcard.
Combining Multiple Filter Conditions
The following example shows how you can combine filter conditions
within a single OQL insert. This example ensures that only devices that do
not have the specified OID and do not have the specified IP address are
detected.
insert into scope.detectionFilter
(
m_Protocol,
m_Filter
)
values
(
1,
"(
( m_ObjectId not like ’1\.3\.6\.1\.4\.1\..*’ )
AND
( m_UniqueAddress <> ’10.10.63.234’ )
)"
);
Configuring the Filter Condition
Although you can configure the filter condition to test any of the columns
in the Details.returns table, you may need to use the IP address as the
basis for the filter if you need to restrict the detection of a particular
device. If the device does not grant SNMP access to the Details agent, the
Details agent may not be able to retrieve MIB variables such as the Object
ID. However, you are guaranteed the return of at least the IP address when
the device is detected.
12
IBM Tivoli Network Manager IP Edition: Discovery Guide
Seeds
Configure seeds to specify the locations from which to begin discovering devices.
Discovery seeds can be IP addresses, or subnet addresses.
You can specify seeds in several ways:
v Using the Ping finder: You specify the IP addresses or subnet addresses to
discover first.
v Using the File finder: You provide one or more files that each contain a list of IP
addresses or subnet addresses.
v Using the Database finder: You specify connection details for an internal or
external database that contains details of devices to discover. You also specify an
SQL query to run to retrieve the device details from the database. An advantage
of using the Database finder over the File finder is that you can extract device
data directly from a third-party database, without having to extract the device
data as a flat file.
Note: The Database finder method is only configurable from the command line
v Using the Collector finder: You specify one or more ports used to access
independent collector processes.
Tip: To restrict discovery to a list of specific devices, seed the discovery with a list
of devices using the File finder or the Ping finder, and disable feedback in the
Advanced tab of the Network Discovery Configuration GUI.
Related tasks:
“Seeding an EMS discovery” on page 176
Seed the EMS discovery by seeding the Collector finder. This is typically a
one-time setup task required when a new collector is added to your installation.
Related reference:
“Advanced discovery parameters” on page 46
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
Device access
Configure device access by specifying SNMP community strings and Telnet
parameters so that the system can access network devices.
Configure device access as follows:
v Specify SNMP community strings so that Network Manager can access and
interrogate the network devices that use SNMP. Network Manager supports
SNMP v1, v2, and v3,
v Specify Telnet parameters so that Network Manager can access and interrogate
the network devices that use Telnet.
Chapter 1. About discovery
13
Agents
Use discovery agents to retrieve information about devices on the network. Select
the right agents for your discovery depending on your network type.
Discovery agents retrieve device details and investigate device connectivity. They
can also report the existence of new devices by finding new connections when
investigating device connectivity. The discovery agents can be used for specialized
tasks. For example, the ARP Cache discovery agent populates the Helper Server
database with IP address to MAC address mappings.
Default agents are provided for the type of discovery you want to perform, for
example a layer 2 or layer 3 discovery. You can select different sets of agents for
full discoveries and for partial discoveries. The agents vary because connectivity
information varies with the technology of the hardware in the network.
Device filters
Use prediscovery filters to increase the efficiency of discovery.
After you have defined the scope of your discovery using the Scope tab, it is
possible to restrict the scope using filters. For example, you might want to
maintain the scope zones that you defined earlier but restrict the scope based on
location (for example, New York hardware only) or based on hardware supplier
(for example, Cisco devices only).
You can filter out devices based on a variety of criteria, including location,
technology, and manufacturer.
By default, the discovery filters do not filter out the Network Manager host
because it usually also serves as the polling station for root cause analysis. For root
cause analysis to work correctly, the polling station, and hence the Network
Manager host machine, must be part of the topology.
For more information on root cause analysis, see the IBM Tivoli Network Manager IP
Edition Administration Guide and the IBM Tivoli Network Manager IP Edition Network
Troubleshooting Guide.
If you do need to filter out the Network Manager host, then you need to modify
the following stitchers and remove the sections of code, indicated by comments,
that prevent the Network Manager host from being filtered. The stitchers are
DetectionFilter.stch and InstantiationFilter.stch.
Prediscovery filter
You might want to apply this filter to sensitive devices that you do not want to
poll. A device might be considered sensitive because there is a security risk
involved in polling the device, or because polling might cause the device to
overload.
Prediscovery filters prevent the discovery from retrieving detailed data or
connectivity data from the device and prevent discovered devices from being
polled for connectivity information. Only devices matching the prediscovery filter
are fully discovered. If no prediscovery filter is defined, then all devices within the
scope are discovered.
14
IBM Tivoli Network Manager IP Edition: Discovery Guide
Prediscovery filters provide a mechanism to base discovery on complex IP ranges
that cannot be easily defined in the Scope tab. It can be used to filter out devices
based on their sysObjectId value. Default filters exist to filter out end nodes,
printers, and similar devices. You can create quite complex multiple filters, which
makes this feature very powerful but try to ensure that filters are designed so that
they can be easily maintained. The filter acts on the fields of the Details.returns
OQL table in the discovery (Disco) service, so you can use fields other than IP
addresses, such as m_ObjectId (equivalent to sysObjectId). A device must pass all
filters to be discovered.
Important: Design the filter logic so that you do not need to modify the
prediscovery filters every time you add new scopes.
You can configure the filter condition to test against any of the columns in the
Details.returns table. But, you might need to use the IP address
(m_UniqueAddress) as the basis for the filter to restrict the detection of a particular
device. If the device does not grant SNMP access to the Details agent, the Details
agent might not be able to retrieve MIB variables such as the Object ID. However,
you are guaranteed the return of at least the IP address when the device is
detected.
You can define multiple prediscovery filters. Filters are combined automatically
using a Boolean AND expression. All criteria defined in all filters must be
matched.
Post-discovery filter
The post-discovery filter is not available when discovery is running in dNCIM
mode.
Related concepts:
“Creating the topology” on page 437
The creation of the topology is carried out in several steps.
Related tasks:
“Setting discovery filters” on page 37
Use filters to filter out devices either before discovery or after discovery. You can
filter out devices based on a variety of criteria, including location, technology, and
manufacturer. Filters provide additional restrictions to those defined in the scope
zones.
“Scoping discovery” on page 27
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
Related reference:
“Main discovery stitchers” on page 487
This topic lists the main discovery stitchers.
Appendix A, “Discovery databases,” on page 293
There are various specialized databases that are used by ncp_disco, the component
that discovers network device existence and connectivity, and by ncp_model, the
component that manages, stores, and distributes the discovered network topology.
Chapter 1. About discovery
15
SNMP interface filtering
You can filter the SNMP data retrieved from devices by the discovery process by
configuring SNMP interface filters. You can configure SNMP interface filters only
on the command line.
Why use SNMP interface filtering
Sometimes a device or a class of devices returns too much MIB data. For example,
if virtual devices have a large number of interfaces, discovering them can take a
long time. In order to speed up discovery of such devices, you can use SNMP
interface filters to reduce the number of interfaces that are retrieved by the SNMP
helper.
How SNMP interface filtering works
When discovery agents, Perl scripts, or the SNMP MIB Browser request SNMP
information, the SNMP helper retrieves the information from network devices.
SNMP interface filters define rows in MIB tables that the SNMP helper retrieves.
The SNMP helper retrieves a subset of the information that would have been
returned without a filter, and sends it to the process that requested the SNMP
information. SNMP interface filters can also define entire tables that are not to be
retrieved by the SNMP Helper.
SNMP interface filters are only applied to requests for full walks of MIB tables.
SNMP Get or GetNext requests for specific interfaces within a MIB table are not
filtered.
The devices that should have the filter applied to them are defined in the device
filter. If a device filter is defined, any request for SNMP information for a device is
first checked against the device filter. Only devices which pass the filter are then
checked for interface filtering.
The filter can filter on multiple rows of a table. The first time that a filtered table is
accessed, one or more columns in the table are walked. All subsequent requests for
SNMP walks of that table return only interfaces that match the filter.
Including multiple tables with dependent filters
You can also define dependent filters. If an SNMP interface filter Filter 1 is defined
on Table A, then a second, dependent filter Filter 2 can be defined on Table B.
SNMP information in Table B that relates to the same interface is also retrieved.
In order to define a dependent filter, in addition to a filter being defined on Table
A, one or more of the following conditions must be true:
v Table A and Table B have equivalent indexes.
v The index of Table A is a value in Table B.
If Table A and Table B have exactly the same index, then you do not need to define
a dependent filter. Information from Table B is automatically retrieved according to
the filter defined on Table A.
16
IBM Tivoli Network Manager IP Edition: Discovery Guide
When you can use SNMP interface filtering
You can use SNMP interface filtering on any SNMP MIB table that is keyed on
ifIndex. For example, you filtering on ifTable or ifXTable allows filtering on values
such as ifType and ifDescr.
Restriction: Filtering on any SNMP MIB variable other than interfaces is not
supported. You can, however, block access to any table using the
m_InstanceFilterTable option.
The following example extract shows the definition for the ipAddrTable from the
NCHOME/precision/mibs/RFC1213.mib file:
-- the IP address table
-- The IP address table contains this entity’s IP addressing
-- information.
ipAddrTable OBJECT-TYPE
SYNTAX SEQUENCE OF IpAddrEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION
"The table of addressing information relevant to
this entity’s IP addresses."
::= { ip 20 }
The syntax "SEQUENCE OF" defines this as a table. You can find out what tables
are defined in the MIB by searching for this string. The following example shows
the output of a search run on UNIX:
% grep ’SEQUENCE OF’
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
RFC1213.mib
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
IfEntry
AtEntry
IpAddrEntry
IpRouteEntry
IpNetToMediaEntry
TcpConnEntry
UdpEntry
EgpNeighEntry
For more information about how to configure SNMP interface filters, see “SNMP
interface filtering” on page 16,
Domain Name System
Configure DNS to enable the discovery to access DNS services that are used to
perform domain name lookups.
You can configure three types of Domain Name System:
DNS server
A server on the network that is dedicated to performing domain name
resolution.
File
The name of a file held on the Network Manager host that contains IP
addresses and host names in lookup table format.
System
The local DNS system on the Network Manager machine.
Chapter 1. About discovery
17
Network address translation
Configure data for NAT gateways in your network.
NAT gateways provide mappings between private IP address in your network and
public device IP addresses. You can enable the system to discover devices within
private address spaces by configuring data for NAT gateways.
Advanced settings
Configure advanced discovery settings to increase the speed of the discovery, and
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server. Advanced settings control features of the
discovery such as concurrent processes and timeouts.
Note: Modify the advanced settings only if you are an experienced Network
Manager user.
You can configure the following advanced discovery settings:
Finder parameters:
Finders are discovery subsystems that discover devices on the network.
You can configure parameters such as timeouts, number of retries, and
number of threads for the finders.
Helper parameters
Helpers are discovery applications used by agents to retrieve information
from devices. You can configure parameters such as timeouts, number of
retries, and number of threads for the helpers.
Other parameters
You can configure complex discovery settings, such as enabling caching of
discovery tables, VLAN modeling, File finder verification, and parameters
that affect the speed of partial discovery.
Most of the advanced discovery parameters are optional.
Context-sensitive discovery
If you need to discover devices that support multiple contexts, you must run a
context-sensitive discovery. For example, a device that uses separate SNMP
contexts to provide access to its virtual routers. Context-sensitive discovery ensures
correct representation of context-accessible virtual devices. Always check that your
particular device type is supported for discovery.
In a context-sensitive discovery, information about a device is passed from the
returns table of the Details agent to the despatch table of the relevant Context
agent.
The Context agents use the filters in the .agnt files of the agents to determine
which devices to process. This approach is true for all discovery agents. If the
device is not of a type that supports context-accessible virtual devices, that is, does
not need context-sensitive processing, it is passed directly to the Associated
Address agent.
Related concepts:
“Discovering device details (context-sensitive)” on page 433
The discovery of context-sensitive device details is carried out in several steps.
18
IBM Tivoli Network Manager IP Edition: Discovery Guide
Related reference:
“Context-sensitive discovery agents” on page 474
There are several agents that take part in a context-sensitive discovery.
Helpers
The helpers are specialized applications that retrieve information from the network
on demand. The default helper configuration is sufficient for most networks.
However, you might decide to alter the configuration for several reasons.
Configuring the Helper System can speed up network discovery, but is
recommended for experienced users.
Although the discovery agents retrieve connectivity information, they do not have
any direct interaction with the network. Instead, they retrieve connectivity
information through the Helper System, which consists of a Helper Server and
various helpers.
Reasons to configure the helpers include:
v To speed up the discovery process, you could reduce the helper timeouts and
number of retries.
v If you have a very reliable network in which devices respond quickly, you can
specify a small default timeout.
v You might want to change the default timeouts for the SNMP and Telnet helpers
if you have many devices that either do not respond to SNMP and Telnet or that
are set up not to respond to Telnet or SNMP access. A large default timeout
would therefore mean that the helpers wait for a long time for responses they
never receive.
v To reduce the amount of network traffic caused by a discovery, you could
increase the timeout and disable broadcast and multicast pinging.
Collectors
Collectors are like agents, except they do not discover information from devices,
but collect it from Element Management Systems (EMSs). Enable and configure the
right collectors for your discovery if you use an EMS.
Collectors are separate processes that are started independently of the ncp_disco
process. Collectors connect to an EMS or parse files from an EMS to collect data
about the devices managed by the EMS.
Each Collector that you need to run must be configured to connect to the
appropriate EMS.
Related concepts:
“About EMS integration” on page 105
The Network Manager EMS integration enables Network Manager to collect
topology data from Element Management Systems.
Related tasks:
“Configuring an EMS discovery” on page 113
Configure an EMS discovery to collect topology data from Element Management
Systems and integrate this data into the discovered topology.
Chapter 1. About discovery
19
Specialized discoveries
You can configure the system to perform more complex discoveries, such as
Multiprotocol Label Switching (MPLS) and Network Address Translation (NAT)
discovery.
Specialized discoveries include:
Element Management System (EMS) discoveries
Collect topology data from Element Management Systems and integrates
this data into the discovered topology.
MPLS discoveries
Discover layer 3 virtual private networks (VPNs) and enhanced layer 2
VPNs running across MPLS core networks.
NAT discoveries
Discover NAT gateway devices to retrieve data on devices in private
address spaces.
Third-party discoveries:
Discover intervening provider networks as a "third-party" object on
multiple networks that run across a provider network (for example,
enterprise VPNs across a provider MPLS core network).
20
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 2. Configuring network discovery
Configure how your network is discovered, including which kinds of devices you
want to discover, and where the boundaries of the discovery should be.
Network Manager provides tools for discovering your network using a phased
approach.
v Use the Discovery Configuration Wizard to perform initial discoveries. The
wizard provides a guided discovery and makes configuration choices for you
based on the answers that you provide as you work through the wizard.
v Use the Discovery Configuration GUI to perform subsequent discoveries. Using
the GUI you can configure detailed discovery settings, including scope, seeds,
community strings, agent selection and many other configuration settings.
Note: You can also configure a discovery using the discovery configuration files
and the command line. However, you should configure discovery this way only if
you are an experienced Network Manager user and you understand the different
aspects of discovery, including the discovery processes, phases, stages, Helpers,
agents, stitchers and traps.
For information on how to manually edit a discovered topology following
discovery, see the IBM Tivoli Network Manager IP Edition Network Visualization Setup
Guide.
Planning for discovery
Before configuring and running a discovery, you should check several system
settings, parameters, and requirements.
The following notes help you plan for the discovery.
Saving changes in the Network Discovery Configuration GUI
To save configuration changes that you have made during a session,
remember to click the Save button before you log out, close the browser
window, or close the Network Discovery Configuration tab. It is good
practice to click Save as you move from tab to tab.
Operating system
Ensure that the host on which Network Manager is running is fully
patched with the latest patches.
Discovery scope
Consider the following questions and points related to the discovery scope:
v Is the positioning of the Network Manager host within the network?
v Is the host positioned to interrogate all devices that you want to include
in your discovery?
v Consider all necessary networks, subnetworks and determine the
associated netmasks.
v Are there any parts of the network that you want to exclude?
v Gather all relevant SNMP community strings for the devices within the
scope
© Copyright IBM Corp. 2006, 2017
21
Routing
Ensure that each of the networks and subnetworks to be discovered is
reachable using the ICMP process. If necessary, add routes to Network
Manager host machine using the route add command.
Access control lists
Network Manager uses several protocols that might need to pass through
firewalls. These protocols are ICMP, SNMP, DNS, ARP, SSH, and TELNET.
To ensure that Network Manager can access devices behind these firewalls,
advise the relevant firewall administrators to prepare the firewalls.
Root cause analysis
To perform root cause analysis on devices within a topology, the discovery
must identify all the devices on which you might want to perform root
cause analysis. In addition, the Network Manager polling station must be
known. If the polling station, usually the Network Manager server, is not
within the scope of your network domain, then, to enable the RCA plug-in
to perform isolated suppression, the IP address or DNS name of the
ingress interface must be specified as the poller entity. This is the interface
within the discovery scope from which network packets are transmitted to
and from the polling station. For more information on root cause analysis,
see the Network Manager Monitoring and RCA Guide.
Configuring standard discoveries
You can configure discovery using the Discovery Configuration Wizard, using the
Discovery Configuration GUI, or using the command line.
Discovering the network using the wizard
The discovery configuration wizard is for users who have limited experience in
configuring discoveries.
Important: If you want to keep discovery configuration settings that you made
previously using the GUI, do not use the wizard. The discovery configuration
wizard overwrites all previous settings.
Related tasks:
“Monitoring network discovery from the GUI” on page 227
From the Active Discovery Status page, you can monitor the status and progress of
the current full or partial discovery, investigate the work of the discovery agents,
and view details of the last full discovery.
Launching the wizard
Select a domain and launch the wizard to start configuring and running a
discovery.
To launch the wizard, complete these steps.
1. Click the Discovery icon and select Network Discovery Configuration.
2. At the top left of the Network Discovery Configuration tab, select the domain
in which you want to run a discovery from the Domain menu.
3. Click the wizard button to the right of the Domain menu.
22
IBM Tivoli Network Manager IP Edition: Discovery Guide
Choosing a scoped or unscoped discovery
The Discovery Scope window provides the option of a scoped or unscoped
discovery.
To choose a scoped or unscoped discovery, complete these steps.
Restriction: Network Manager does not support the IPv4–mapped IPv6 format
and expects all IPv6 addresses to be in standard colon-separated IPv6 format. For
example, Network Manager does not aupport an IPv4–mapped IPv6 address such
as ::ffff:192.0.2.128. Instead enter this address as ::ffff:c000:280 (standard
colon-separated IPv6 format).
1. Select Scoped or Unscoped.
Scoped
A scoped discovery restricts the discovery to a certain part of your
network. To specify a scoped discovery, tell the wizard which area of
the network to restrict the discovery to, and assign IP addresses or
subnets as seeds to ping to begin the discovery.
Unscoped
An unscoped discovery attempts to discover your entire network.
However, you still need to assign IP addresses or subnets as seeds to
ping to begin the discovery.
Attention: If there are routes out of your network to the Internet, an
unscoped discovery will find these routes and start to discover parts of
the Internet.
2. If you selected Scoped, specify which area of the network to which to restrict
the discovery.
Specify one or more subnets to use for both scoping and seeding by clicking
New and typing an IP address and a netmask.
Restriction: For performance reasons, only IPV4 addresses will be pinged. To
ping IPV6 addresses use the Seed tab in the Discovery Configuration GUI.
3. If you selected the Unscoped option, specify the seeds to use for your
unscoped discovery.
Click New... and specify one or more IP addresses.
Configuring SNMP access using the wizard
Specify address-specific, network-specific, or global community strings on the
SNMP Community Strings window.
For SNMP version 3, you can also specify passwords for community strings.
To configure SNMP access, complete these steps.
1. For each SNMP community string and associated password that you want to
define:
a. Click the New icon above the SNMP Community Strings table to display
the SNMP Password Properties window.
b. Specify address-specific, subnet-specific, or global SNMP community
strings, and supply passwords for these community strings in the case of
SNMP V3.
You might need to enter a community string more than once. For example,
enter a string for SNMP V1, enter another string for SNMP V2, and another
string for SNMP V3.
Chapter 2. Configuring network discovery
23
Specifying community strings by subnets results in a more efficient and
faster discovery.
Restriction: It is best practice not to use the at symbol (@) in community
strings. Using this symbol in a community string can cause problems
connecting to devices at discovery time.
2. Use the up and down arrow keys to put the community strings in order of
most frequently expected use. Put more frequently used community strings at
the top.
Configuring Telnet access using the wizard
On the Telnet Access window, set the Telnet access parameters.
To configure Telnet access, complete these steps.
1. After you have specified SNMP community strings, click the New icon on the
Telnet Access window.
2. For each set of Telnet-accessible devices for which you want to define prompts
and passwords, click New.
3. On the Telnet Passwords window, specify a set of Telnet-accessible devices (all
devices, all devices within a specified subnet or a single IP address) together
with prompts, login IDs, and login passwords for this set of devices.
Specifying type of discovery
On the Discovery Type window, specify the type of discovery: a Layer 3 or a Layer
2 discovery.
A Layer 3 discovery is quicker, but the results of a Layer 3 discovery cannot be
used for root cause analysis. A Layer 2 discovery is more detailed and the results
can be used for root cause analysis.
To specify discovery type, complete these steps.
1. On the Discovery Type window, specify a Layer 2 or Layer 3 discovery.
2. If you selected Layer 3, the End Node Discovery window is displayed.
On the End Node Discovery window, you can filter out end node devices such
as workstations and printers. You can also filter out devices with no SNMP
access.
Tip: Filtering out all end nodes in networks that have large numbers of end
nodes can lead to speed and performance improvements in your discovery.
3. If you selected Layer 2 and Layer 3, the VLAN Modelling window is
displayed.
In the VLAN Modelling window, you configure the discovery to model VLANs
in the resulting topology. This enables VLANs to be considered when
performing root cause analysis. VLANs are a Layer 2 concept and VLAN
modelling is required for Layer 2 discoveries only. Specify whether you want to
model VLANs. When you have specified an option, click Next to display the
End Node Discovery window.
24
IBM Tivoli Network Manager IP Edition: Discovery Guide
Optimizing the discovery
On the Discovery Optimization window, optimize the discovery for connectivity,
richness of information, and speed.
To optimize the discovery, complete these steps.
1. Provide varying amounts of connectivity information by selecting one of these
options.
Best possible connectivity accuracy and richness of information
This option provides comprehensive connectivity information between
switches, end nodes and routers as well as detailed information on each
device discovered. However, the discovery might require a significant
amount of time to complete.
Best possible connectivity accuracy but prefer speed to richness of
information
This option provides comprehensive connectivity information.
However, the discovery provides less detailed information on each
device discovered in order to provide a faster discovery.
Rich device information but prefer speed to accurate connectivity
This option provides detailed information on each device discovered.
However, the discovery provides less detailed connectivity information
to provide a faster discovery. For example, the discovery might provide
information on how switches are connected to each other, but it might
not provide information on connectivity between switches and end
nodes or between switches and routers.
Note: This option is more suitable if you want to gather inventory data
instead of perform root cause analysis (RCA). RCA is dependent on
accurate connectivity data.
Fastest discovery time
This option focuses on the speed of the discovery. However, limited
connectivity information is provided as well as less detailed
information on each single device.
2. If you select either of the first two options, this means that accurate
connectivity is important. The Network Reliability window is displayed.
3. If you select either of the last two options, this means that you are willing to
compromise on the accuracy of connectivity information to ensure a faster
discovery. In this case, the wizard asks how much of your network is made up
of Cisco devices. If a large proportion of the network is made up of Cisco
devices, then the wizard can switch off agents that discover connectivity for
non-Cisco devices, thereby speeding up the discovery significantly. The Cisco
Hardware window is displayed.
a. Specify how much of your network is made up of Cisco hardware by
selecting one of these options.
All of it
This option directs the wizard to run the Cisco Discovery Protocol
(CDP).
Most of it, Some of it, Don't know
This option directs the wizard to run the CDP. However, if you
chose a Layer 2 and Layer 3 discovery or if you indicated that you
want to exclude end nodes from the discovery, then this option
invokes the Spanning Tree Protocol (STP) as well as CDP.
Chapter 2. Configuring network discovery
25
None of it
This option specifies that neither the CDP nor the STP protocol is
used.
b. When you have selected one of these options, click Next.
c. If your response to the Cisco hardware question was All of it or None of it,
then the Network Reliability window is displayed.
d. If your response to the Cisco hardware question was Most of it, Some of it,
or Don't know, then the Spanning Tree Protocol window is displayed, on
which you specify whether the spanning tree protocol is enabled on all
network switches.
Indicating the reliability of your network
On the Network Reliability window, select a description of the reliability of your
network in responding to pings and SNMP requests. The description directs the
wizard to establish the length of timeouts.
To describe the reliability of your network, choose one of these options that
correspond to the reliability of your network when responding to ping and SNMP
requests.
Very reliable
This description states that the network must be reliable when responding
to ping and SNMP requests. Select this option to allow the wizard to apply
very short timeouts, without any retries. This option is appropriate for a
very reliable network and results in fast discoveries. If you requested
Fastest possible discovery time in the Discovery Optimization window,
then the timeouts set by this option are even shorter.
Quite reliable
This description states that the network must be reliable for the most part
when responding to ping and SNMP requests. Select this option to allow
the wizard to apply slightly longer timeouts, with a single retry for both
SNMP and ping requests.
Not very reliable
This description states that the network does not necessarily need to be
reliable when responding to ping and SNMP requests. Select this option to
allow the wizard to apply longer timeouts and two retries for SNMP
requests and ping requests. Longer timeouts are suitable for less reliable
networks.
Reviewing the configuration
On the Configuration Summary window, review your settings. You can also save
the settings here, and, optionally, start the discovery with the settings that you
configured.
To review your configuration settings, complete these steps.
1. Review the settings on the Configuration Summary window.
Click any of the links to return to the relevant window to modify the settings
as appropriate.
2. When you are satisfied with the discovery settings, select one of these options.
v Select Start Discovery, to use the discovery configuration settings that you
specified, and then click Finish to start the discovery.
v If you do not select Start Discovery, the discovery settings are saved when
you click Finish.
26
IBM Tivoli Network Manager IP Edition: Discovery Guide
Related tasks:
“Monitoring network discovery from the GUI” on page 227
From the Active Discovery Status page, you can monitor the status and progress of
the current full or partial discovery, investigate the work of the discovery agents,
and view details of the last full discovery.
Discovering the network using the GUI
To perform a custom discovery, complete the tabs on the Network Discovery
Configuration page. On these tabs, you can configure more complex discovery
parameters than by using the Discovery Configuration Wizard.
Remember: To save configuration changes that you have made during a session,
click the Save button before you log out, close the browser window, or refresh or
navigate away from the Network Discovery Configuration tab. It is good practice
to click Save as you move from tab to tab.
The parameters that you can set on the tabs of the Network Discovery
Configuration are described in the topics that follow.
Most of the parameters that you can set on the Network Discovery Configuration
page are optional.
For the discovery to run, at a minimum you must specify the following
parameters:
v One seed device
v The correct SNMP community strings for the network to be discovered.
If any of the tabs contain data, this data is from earlier configurations. The data is
held in the relevant discovery configuration file.
Scoping discovery
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
You can define as many zones as necessary. You can add new zones, or edit or
delete existing zones. Zones can be specified within zones: within a given inclusion
zone, you can specify devices or subnets that are not to be detected. These devices
are not pinged by the Ping finder or interrogated by the discovery agents. For
example, you can define an include scope zone consisting of the Class B subnet
1.2.0.0/16, and within that zone you can specify an exclude scope zone consisting
of the Class C subnet 1.2.3.0/24. Finally, within the exclude scope zone you could
specify an include scope zone 1.2.3.128/26.
Note: This procedure can only be used to configure scoping for IP-based entities.
Non-IP entities such as layer 1 optical devices and certain radio access network
devices must be scoped by configuring a prediscovery filter in the Filters tab.
To scope the discovery:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click Scope.
Chapter 2. Configuring network discovery
27
4. To add a new scope zone, click New
. The Scope Properties page is
displayed.
5. Complete the fields as follows and then click OK.
Scope By:
Select one of the following options:
Subnet
Type the required subnet and specify the number of netmask
bits. The Netmask field is automatically updated.
You can specify a subnet or an individual IP address using
these fields.
v For example, to specify an IPv4 Class C subnet 10.30.2.0, type
10.30.2.0/24, where 10.30.2.0 is the subnet prefix, and 24 is
the subnet mask.
v To specify an individual device, type an IPv4 IP address and
a subnet mask of 32. For example, type 10.30.1.20/32.
v If you are using IPv6, use a subnet mask of 112 or higher, in
order to avoid excessive discovery times.
Wildcard
Use an asterisk (*) as a wildcard.
For example, to specify a scope of all IP addresses that begin
with the 10.30.200. subnet prefix, type 10.30.200.*.
Restriction: Network Manager does not support the IPv4–mapped IPv6
format and expects all IPv6 addresses to be in standard colon-separated
IPv6 format. For example, Network Manager does not support an
IPv4–mapped IPv6 address such as ::ffff:192.0.2.128. Instead enter
this address as ::ffff:c000:280 (standard colon-separated IPv6
format).
Protocol
Select the required Internet protocol: IPv4 or IPv6.
Action
Define the subnet range as an inclusion zone or exclusion zone. If the
subnet range is an inclusion zone that you intend to ping during the
discovery, click Add to Ping Seed List. Clicking this option
automatically adds the devices in the scope zone as a discovery seed
devices.
Restriction: The Add to Ping Seed List option is not available for IPv6
scope zones. This prevents ping sweeping of IPv6 subnets, which can
potentially contain billions of devices to be pinged. Ping sweeping of
IPv6 subnets can therefore result in a non-terminating discovery.
6. To edit an existing scope zone, click the required row. On the Scope Properties
page, edit the properties as described in step 5.
7. To delete an existing scope zone, select the Select check box next to the
required row or rows and click Delete
8. Click Save
.
.
If you are performing NAT address mapping, you must configure the NAT
gateways and return to the Scope tab to set the address mapping.
28
IBM Tivoli Network Manager IP Edition: Discovery Guide
Related concepts:
“Defining discovery zones to restrict discovery” on page 3
To restrict the discovery, you must define discovery zones. You can define
discovery zones in several ways.
“Device filters” on page 14
Use prediscovery filters to increase the efficiency of discovery.
“Scopes” on page 2
Define the zones of the network (that is, subnet ranges) that you want to include
in the discovery, and the zones that you want to exclude. The areas of the network
to be included in the discovery process, or excluded from the discovery process are
collectively known as the discovery scope.
“Types of scoping” on page 3
Network Manager offers several types of scoping.
Related tasks:
“Troubleshooting missing devices” on page 267
If a device that you expect to find in your network topology is not present, follow
these steps to troubleshoot the problem.
“Configuring a multicast discovery” on page 43
Configure a multicast discovery by enabling the required agents and scoping the
discovery.
Related reference:
“Main discovery stitchers” on page 487
This topic lists the main discovery stitchers.
Appendix A, “Discovery databases,” on page 293
There are various specialized databases that are used by ncp_disco, the component
that discovers network device existence and connectivity, and by ncp_model, the
component that manages, stores, and distributes the discovered network topology.
“DiscoScope.cfg configuration file” on page 75
The DiscoScope.cfg configuration file can be used to configure the scope of a
discovery.
“Quick reference for NAT discovery configuration” on page 197
Use this information as a step-by-step guide to configuring a NAT discovery..
Seeding discovery
To seed the discovery, provide the starting points from which to look for devices.
For the discovery to run, at a minimum you must specify the following
parameters:
v One seed device
v The correct SNMP community strings for the network to be discovered.
Use the following methods to seed the discovery:
Ping finder
Seed the Ping finder with a device or subnet address at which the finder
begins looking for devices. You can specify seeds for the Ping finder and
save these seeds. You can separately decide whether to activate the Ping
finder for the discovery.
File finder
Seed the File finder with a text file on the Network Manager host to which
you have read access. This file must be a structured text file that contains
the seeds in the form of IP addresses and device names in columns. You
usually use a file that already exists on the Network Manager host.
Chapter 2. Configuring network discovery
29
However, if you want to create a new file to hold the seeds, you need to
have write permissions for the directory where you want to write the file.
Note: It is also possible to seed the discovery using the Database finder; however,
this method is only available from the command line. Seed the Database finder by
specifying a query that reads a database in order to retrieve a list of devices to find
on the network.
When running an IPv6 discovery, ensure that the following conditions are met:
v There is at least one IPv6 seed device within each IPv6 scope.
v If you specify an IPv6 subnet as a seed, then ensure that the subnet is small by
specifying a high value for the netmask.
By default, the Ping finder and File finder are switched on.
To seed the discovery:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click Seed.
4. Optional: To switch off the Ping finder or File finder clear the Use Ping
Finder in Discovery or Use File Finder in Discovery check boxes.
5. Add or edit a ping seed:
v To add a new ping seed, click New
.
v To edit an existing ping seed, click the required entry in the list.
The Ping Seed Properties page is displayed.
6. Complete the fields as follows and click OK.
Seed by:
Select one of the following options:
IP
Type an IP address.
Subnet
Specify a subnet and type the number of netmask bits. The
Netmask field is automatically updated.
Restriction: Network Manager does not support the IPv4–mapped
IPv6 format and expects all IPv6 addresses to be in standard
colon-separated IPv6 format. For example, Network Manager does not
support an IPv4–mapped IPv6 address such as ::ffff:192.0.2.128.
Instead enter this address as ::ffff:c000:280 (standard
colon-separated IPv6 format).
Timeout
Specify the time in milliseconds to wait for a reply from a pinged
address before timing out.
Retries
Specify the number of times a device is to be repinged.
7. To delete an existing ping seed, select the Select check box next to the
required row and click Delete
.
8. Add or edit a file seed:
v To add a new file seed to the File finder, click New
30
IBM Tivoli Network Manager IP Edition: Discovery Guide
.
v To edit an existing file seed, click the required entry in the list.
The File Seed Properties page is displayed.
9. Complete the fields as follows and click OK.
Filename
Specify the path to the file on the host workstation that contains the
seed data.
Delimiter
Specify the column delimiter. Use a regular expression if required. For
example, if the Name and IP columns are separated by one or more
tabs, then insert [ tab_space ]+, where tab_space is an actual tab
character. To produce this tab character, create a tab in a text editor,
copy the tab and paste it into the field.
IP Column
Type the column number of the column that contains the IP addresses
of the seed devices.
Name Column
Type the column number of the column that contains the device
names of the seed devices.
10. To delete an existing file seed, select the Select check box next to the required
row and click Delete
11. Click Save
.
.
You can also seed a discovery by using the Collector finder. The collector finder
retrieves topology data from an EMS. Topology data is collected by EMS collectors,
which are software modules that retrieve topology data held in an EMS database,
convert this data to XML format and pass this data to Network Manager to stitch
into the topology. You must seed the Collector finder to enable Network Manager
to find one or more EMS collectors.
Related reference:
“DiscoPingFinderSeeds.cfg configuration file” on page 71
The DiscoPingFinderSeeds.cfg configuration file is used for seeding the Ping finder
and restricting device detection.
“DiscoCollectorFinderSeeds.cfg configuration file” on page 65
The DiscoCollectorFinderSeeds.cfg configuration file defines how topology data
is acquired from Element Management System (EMS) collectors during discovery.
“DiscoDBEntryFinderQueries.cfg configuration file” on page 66
The DiscoDBEntryFinderQueries.cfg file is used to specify the a database query to
be run against a specified database in order to retrieve a list of IP addresses of
devices to discover on the network.
“Advanced discovery parameters” on page 46
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
Chapter 2. Configuring network discovery
31
IPv6 subnet mask sizes:
There are potentially billions of devices to be pinged within a single IPv6 subnet.
To ensure that discovery completes, you must specify a sufficiently large netmask
if you specify an IPv6 subnet as a ping seed.
The following table provides examples of IPv6 subnet mask sizes configured
within ping seeds and the corresponding estimated time required to ping the
devices in the subnet. The estimated times are based on spacing the pings by 100
ms between pings. This table shows that it is best to limit the size of IPv6 subnet
masks in your subnet seeds.
Table 1. Ping response times for IPv6 subnet masks
IPv6 subnet mask size
Number of IPv6 addresses
in subnet
Estimated ping time for
subnet
120
256
26 seconds
112
65536
1 hour 48 minutes
100
268 million
Approximately 8.5 years
The time estimates shown in the table refer to time taken to ping all the seeds in a
subnet seed specified for the Ping finder. It would take longer to complete the
discovery as there will be many more devices to ping within the discovery scope.
Configuring device access
Specify SNMP community strings and Telnet access information to enable helpers
and Network Manager polling to access devices on your network.
Note the following information about the SNMP helper and Telnet helper:
SNMP helper
You must specify SNMP community strings for the SNMP helper and
polling operations to access devices on your network. You might need to
enter a community string more than once. For example, once for SNMP V1,
once for SNMP V2, and once for SNMP V3.
Telnet helper
Enter the relevant device prompts, login ID, and password for the Telnet
helper and the discovery agents that use Telnet. You can configure
Telnet-privileged access properties. The privileged access mode allows
commands to be run that might change the configuration of the device. By
default, when the discovery accesses the device using Telnet, access is
granted in user mode. This mode allows the running of basic commands
only, such as those commands that show the status of the system. This
default access mode is a safety feature to prevent the discovery making
any device configuration modifications without an explicit change to
privileged mode.
Community strings and Telnet access data can be global, which means that the
discovery tries the community string for every device it encounters, or restricted to
specific subnets (that is, used only on devices within a specific subnet), or even
restricted to specific devices. Specifying community strings and Telnet access data
by subnet results in a more efficient and faster discovery. In general, the more
specific the credentials, the faster the discovery will determine the correct
credentials.
32
IBM Tivoli Network Manager IP Edition: Discovery Guide
Note: Speed of discovery related to community string settings in the GUI only
affects the initial discoveries. Once Network Manager has identified the correct
community strings, it stores this information in the NCMONITOR relational
database. Subsequent discoveries access this database for SNMP cmmunity strings
and other SNMP-related device access information.
For the discovery to run, at a minimum you must specify the following
parameters:
v One seed device
v The correct SNMP community strings for the network to be discovered.
You can also configure the SNMP Helper to use the GetBulk operation when
SNMP v2 or v3 is used. Use of the GetBulk operation improves discovery speed.
For more information, see the IBM Tivoli Network Manager Entry Edition Installation
and Configuration Guide
To configure device access:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click Passwords.
4. To add a new SNMP community string, click New
Properties page is displayed.
. The SNMP Password
5. Complete the fields as follows and then click OK:
Community String
Type a name. When you save the community string, the name is
encrypted, but on the GUI, the value is always displayed
unencrypted. For speed of discovery, order the SNMP strings by
frequency, with the most common strings first.
Restriction: It is best practice not to use the at symbol (@) in
community strings. Using this symbol in a community string can
cause problems connecting to devices at discovery time.
Apply to
The discovery completes more quickly if you specify the correct scope
of the community strings. Select one of the following options:
All Devices
Select this option if the community string is global.
IP Address
Select this option if the community string is specific to an IP
address, and type the IP address.
Subnet
Select this option if the community string is specific to a
subnet. Type the required subnet and specify the number of
netmask bits. The Netmask field is automatically updated.
SNMP Version
Specify the version of SNMP for this SNMP community. If you specify
SNMP V3, complete the following additional fields:
Security Name
Type a name.
Chapter 2. Configuring network discovery
33
Level
Specify the required level of authentication and privacy.
NoAuthNoPriv,
Select this option for SNMP communities that have no
authentication or private key. In this case there is no
need to specify any passwords.
AuthNoPriv
Select this option for SNMP communities that have an
authentication key but no private key. Then specify a
password in the Auth Password field.
AuthPriv
Select this option for SNMP communities that have
both an authentication and a private key. Then specify
passwords in the Auth Password and Private
Password fields.
Auth Type
Specify the type of encryption for the authentication
password.
Restriction: The MD5 encryption option is not available if
you are running a FIPS 140–2 installation of Network
Manager.
Priv Type
Specify the type of encryption for the privacy password.
Restriction: The DES encryption option is not available if you
are running a FIPS 140–2 installation of Network Manager.
SNMP Port
Specify the required port.
Timeout
Specify the time in milliseconds to wait for a reply before timing out.
Retries
Specify how many times you want the SNMP helper and polling
operations to attempt to access a device.
6. Click Move Up
and Move Down
to arrange the SNMP
community strings. Put the most frequently used strings at the top of the list.
7. Click Save.
8. To add Telnet access information, click New.
Properties page is displayed.
The Telnet Password
9. Complete the fields as follows:
Apply to
Select one of the following options:
All devices
Select this option if the data applies globally.
IP address
Select this option if the string is specific to a device, and type
the IP address of the device.
Subnet
Select this option if the string is specific to a subnet. Type the
34
IBM Tivoli Network Manager IP Edition: Discovery Guide
required subnet and specify the number of netmask bits. The
Netmask field is automatically updated.
Username prompt
Type the prompt that you want to be displayed at login. If you do not
know the exact format of the prompt. use a regular expression.
Username
Type the user name.
Password prompt
Type the prompt that you want to be displayed when the password is
required at login. If you do not know the exact format of the prompt,
use a regular expression.
Password
Type the password.
Console prompt
Type the prompt that is displayed when you log in. If you do not
know the exact format of the prompt, use a regular expression.
Access port
Specify the port on which the Telnet helper and discovery agents
attempt to access devices.
Timeout
Specify the time in milliseconds to wait for a reply before timing out.
Use SSH
Select this option to configure the Telnet Helper to use the Secure
Shell (SSH) program.
10. Optional: To configure Telnet-privileged access mode properties:
a. Click Advanced. The Telnet Privileged Access Mode Properties page is
displayed.
b. Complete the fields as follows and then click OK:
Command
Type the command required to enter Telnet-privileged access
mode. This command is typically enable.
Password Prompt
Type the prompt that you want to be displayed when the
password is required at login. If you do not know the exact format
of the prompt, use a regular expression.
Password
Type the required password for privileged mode.
Console Prompt
Type the prompt that is displayed when you log in. If you do not
know the exact format of the prompt, use a regular expression.
Commands requiring mode:
Specify the commands that you want to make accessible from
privileged mode. To add new commands, click New... and type the
command in the Priv command field. The following commands
are required to run in enable mode:
v show run
v show mac-address-table
v show ip nat translation
Chapter 2. Configuring network discovery
35
11. Click OK. Click Save
.
When you save the Telnet password settings, the following passwords are
automatically encrypted:
v Telnet password
v Telnet privileged mode password (if specified)
When you save the password settings, the following passwords are automatically
encrypted:
v SNMP community string
v SNMP authentication password
v SNMP private password
If required, change the SNMP and Telnet encryption settings. For example, you can
change the encryption key file, or switch off encryption.
Related tasks:
“Enabling the StandardMPLSTE agent” on page 191
To discover MPLS TE tunnels, you must enable the StandardMPLSTE agent and
add the relevant SNMP community strings.
Related reference:
“Advanced discovery parameters” on page 46
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
“Connectivity at the layer 3 network layer” on page 460
There are a number of discovery agents that retrieve connectivity information from
OSI model layer 3 (the Network Layer). Layer 3 is responsible for routing,
congestion control, and sending messages between networks.
Activating agents
You must enable the appropriate agents for the discovery you want to perform.
You can specify agents for a full discovery or for a partial discovery.
You can speed up the time taken for a partial discovery by selecting only those
agents essential to discover the new or modified devices. You might want to run a
partial discovery if you know that new devices have been added to the network or
that engineers have been working on a device and have added or removed
components of this device.
Note: The more agents you run, the more data is retrieved from the network, and
the slower the discovery.
To activate agents:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click one of the following tabs, based on your requirements:
36
Tab
Description
Full Discovery Agents
Select agents from this tab to run a full
discovery.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Tab
Description
Partial Discovery Agents
Select agents from this tab to run a partial
discovery.
Note: The Reset button in the Partial
Discovery Agents window sets the partial
agents to match the settings defined in the
Full Discovery Agents window.
The Agents List is displayed, showing all available discovery agents for the
selected discovery option.
4. Select the check boxes next to the required agents. For descriptions of the
agents, select an agent name.
To select all agents required for a layer 3 discovery, select the Layer 3 checkbox.
To select all agents required for a layers 2 and 3 discovery, select the Full Layer
2 and Layer 3 Discovery checkbox.
5. Click Save
. If you have selected a invalid combination of agents, or a
combination that might result in an inefficient discovery, a warning is
displayed.
6. If applicable, follow the steps displayed in the warning:
v If you selected an agent that must be run in conjunction with another agent
or agents, the warning indicates that the additional agents will be selected as
applicable. Click OK to select the agents, or click Cancel.
v If you selected an agent that cannot be run in conjunction with another agent
or agents, the warning indicates that the redundant agents will be
automatically deselected. Click OK to deselect the recommended agent or
click Cancel.
Related tasks:
“Configuring MPLS agents” on page 185
As part of MPLS discovery configuration you must enable one or more MPLS
agents. You can also resolve the problem of duplicate IP addresses in different
Virtual Private Networks (VPNs) by configuring the AsAgent agent.
Related reference:
Appendix C, “Discovery agents,” on page 447
Use this information to support the selection of discovery agents to run as part of
your discovery.
Setting discovery filters
Use filters to filter out devices either before discovery or after discovery. You can
filter out devices based on a variety of criteria, including location, technology, and
manufacturer. Filters provide additional restrictions to those defined in the scope
zones.
A filter is made up of one or more filter conditions. Filter conditions are defined in
Object Query Language (OQL). You can add the following types of filter:
Prediscovery filters
Prediscovery filters prevent discovered devices from being polled for
connectivity information.
Note: Use prediscovery filters to configure scope for non-IP devices in the
network, as shown in the examples below.
Chapter 2. Configuring network discovery
37
Post discovery filters
Post-discovery filters prevent discovered devices from being passed to
MODEL.
Note: To ensure that alerts are not raised for interfaces that are excluded
by the post discovery filter, you must set the
RaiseAlertsForUnknownInterfaces variable. To this, perform the following
steps:
1. Edit the $NCHOME/etc/precision/NcPollerSchema.cfg configuration file.
2. Add the following line to the file:
update config.properties set RaiseAlertsForUnknownInterfaces = 0;
The steps for adding, editing, and deleting filters are identical for both types.
To set the discovery filters:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click Filters.
4. To use a filter in the discovery, select a filter from the Available filters list and
click Select Filter. The filter is added to the Selected Pre-discovery Filter field
or the Selected Post-discovery Filter field, depending on the type of filter.
5. To remove a filter, select a filter from the Selected Pre-Discovery Filters or
Selected Post-Discovery Filters list and click Deselect Filter.
6. To add a new filter, or edit an existing filter, click Filter Library. The Filter
Library page is displayed.
7. Add or edit the filter as follows:
Action
Instructions
Add a new filter
Click Add and type the required name in
the Name field.
Edit an existing filter
Select the required filter from the list.
8. On the Basic tab, build the filter conditions as follows:
a. Select the required field and comparator.
b. Type the value for comparison with the selected field. See “Configuring
discovery filters” on page 39 for an example.
c. Click Add New Row
or Delete This Row
to add or remove rows.
d. Select All to combine multiple conditions in an AND relationship, or Any
combine the conditions in an OR relationship.
e. Click Save.
9. Optional: On the Advanced tab, type the required SQL WHERE clauses. For
multiple conditions, use an AND or an OR relationship as appropriate. Click
Save.
Note: The filter is actually based on standard OQL formatting, though the
GUI refers to the SQL clause.
10. Click Close to close the Filter Library, then click Save to save your filter
settings.
38
IBM Tivoli Network Manager IP Edition: Discovery Guide
Configuring discovery filters
You can use a prediscovery filter to refine scoping. The prediscovery filter applies
to chassis and interfaces, whereas the postdiscovery filter applies to all entities.
Take care when defining postdiscovery filters so that you do not inadvertently
filter out objects such as VPNs, cards, or subnets.
Only pass non-IP devices to discovery
The following example filter is provided by default. It ensures that only
non-IP devices are passed to discovery and interrogated further. This filter
would exclude all IP-based devices.:
m_Protocol = 4
Only pass non-IP devices to discovery and exclude the non-IP devices with a
specified unique key
The following example insert ensures that only non-IP devices are passed
to discovery and the non-IP devices that are passed must not include the
specified string in their unique Element Management System (EMS) key.
( m_Protocol = 4 )
AND
( m_UniqueAddress NOT LIKE ’LONDON’ )
Exclude devices with a specified object ID
The following example shows a filter condition for a prediscovery filter
that excludes devices with a specified object ID.
m_ObjectId not like ’1\.3\.6\.1\.4\.1\.2\.3\.1\.’
Restricting instantiation of a chassis based on entity name
The following example postdiscovery filter restricts instantiation of a
chassis and its contents.
BASENAME != ’jane’
Restricting instantiation of multiple chassis
The following example postdiscovery filter restricts instantiation of a
chassis and its contents.
snmpSystem->SYSDESCR NOT LIKE ’ device’
For more information on OQL syntax, see the IBM Tivoli Network Manager IP
Edition Language Reference.
Related concepts:
“Device filters” on page 14
Use prediscovery filters to increase the efficiency of discovery.
Related tasks:
“Troubleshooting missing devices” on page 267
If a device that you expect to find in your network topology is not present, follow
these steps to troubleshoot the problem.
Related reference:
“Main discovery stitchers” on page 487
This topic lists the main discovery stitchers.
Appendix A, “Discovery databases,” on page 293
There are various specialized databases that are used by ncp_disco, the component
that discovers network device existence and connectivity, and by ncp_model, the
component that manages, stores, and distributes the discovered network topology.
Chapter 2. Configuring network discovery
39
Available filter values:
Use this reference information to familiarize yourself with the permissible values
when you set discovery filters on the Network Discovery Configuration page.
Prediscovery filter values
When constructing a prediscovery filter, you can filter based on any of the fields in
the Details.returns table. These fields are as follows:
m_AddressSpace
The name of the NAT address space to which the device belongs. This value is
set in the translations.NATAddressSpaceIds table. If the discovery is not using
NAT, or if the device is in the public domain, this value is NULL.
m_Description
Value of sysDescr MIB variable of the entity.
m_ExtraInfo
Any extra information.
m_HaveAccess
Flag indicating whether there is SNMP access to the device:
v 1: Have access
v 0: No access
m_LastRecord
A flag indicating whether this is the last record for this entity (that is, whether
the entity has been completely processed):
v 1: True
v 0: False
m_ManagerId
Identifies the manager of the device. Takes the value "" if device is accessed
directly.
m_Name
Unique name of an entity on the network.
m_ObjectId
Textual representation of the device class (an ASN.1 address).
m_Protocol
An integer representation of the IP protocol used by the presently-defined
zone:
v 1: IPv4
v 2: IPv4 that has been through network address translation (NAT)
v 3: IPv6
m_UniqueAddress
The IP address of the discovered network entity.
m_UpdAgent
The agent that updated this device.
40
IBM Tivoli Network Manager IP Edition: Discovery Guide
In addition, by using the Advanced tab, you can construct filter rows using any of
the fields from within the m_ExtraInfo field.
Postdiscovery filter values
When constructing a post-discovery filter, you can filter based on any of the fields
in the ncimCache database.
Configuring Domain Name System
You can specify the methods that the Domain Name System (DNS) Helpers use to
perform domain name lookups.
Helpers are specialized applications that retrieve information from and about
network devices for the discovery agents.
Each of method that you specify uses one of the following three domain methods:
DNS Server
A server on the network that is dedicated to performing domain name
resolution.
File
The name of a file held on the Network Manager host that contains IP
addresses and host names in lookup table format.
System
The local DNS system on the Network Manager host.
Tip: You can define as many methods as is necessary. You can change the order in
which these methods are retrieved by the DNS Helper so that the most commonly
accessed method is retrieved first. This enables a more effective use of resources
during the discovery.
To configure DNSs:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click the DNS tab.
4. Add a new DNS helper, or edit an existing helper as follows:
v To add a new DNS helper, click New
.
v To edit an existing helper, click the name of the required helper.
The DNS Service Properties page is displayed.
5. Complete the fields as follows and then click OK.
Service Name
Type the name of the method.
Type
Select one of the following options:
System
Choose this option to use the local DNS system on the Network
Manager server. This is the default option.
DNS Server
Type the IP address of the required DNS server. In the Timeout
field, specify the number of seconds to wait for a response from
the DNS Server before timing out.
File
Type the name of the file that contains the domain lookup
Chapter 2. Configuring network discovery
41
information. Specify the order in which this information
appears in the lookup table by selecting one of the radio
buttons:
v Name then IP
v IP then Name
Domain Suffix
Specify the suffix to append to each device name after the name is
looked up. The specified domain suffix is only added if no domain
suffix is present in the device name.
Note: If you expect the discovery to return some or all devices names
with domain suffixes already appended, then you can specify a list of
expected domain suffixes. The domain suffix value specified in the
Domain Suffix field is not appended to any device names returned by
the discovery with these expected suffixes. To specify a list of expected
domain suffixes, you must configure the DiscoDNSHelperSchema.cfg
configuration file from the command line.
6. Repeat steps 4 on page 41 to 5 on page 41 to add or edit the required methods.
7. In the Move column, click Move Up
and Move Down
to arrange
the methods in the order of most frequently-expected use, with the most
frequently-used methods at the top.
8. Click Save
.
Related reference:
“Advanced discovery parameters” on page 46
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
“DiscoDNSHelperSchema.cfg configuration file” on page 67
The DiscoDNSHelperSchema.cfg configuration file defines access to DNS, which
enables the discovery to do domain name lookups, by configuring the DNS helper.
Configuring NAT translation
To configure NAT translation to discover NAT environments, map the
address-space identifier for a NAT domain to the IP address of the associated NAT
gateway device.
After activating NAT, you must map the discovery scope zones to the NAT
address spaces. You do this on the Scope tab.
If you select Enable Network Address Translation (NAT) Support in the NAT tab
then you must configure at least one NAT gateway.
To configure NAT gateways:
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click NAT.
4. Add a new NAT gateway, or edit an existing gateway:
v To add a new NAT gateway, click New
42
IBM Tivoli Network Manager IP Edition: Discovery Guide
.
v To edit an existing NAT gateway, click the IP address in the required row.
The NAT Gateway page is displayed.
5. Complete the fields as follows and click OK:
IP Address
Type the public IP address of the NAT gateway device.
Address Space
Type the address space identifier that you want to use for the
associated NAT domain.
6. Click Save
.
7. To activate NAT translation for the discovery, select Enable Network Address
Translation (NAT) Support. Click Save and then map the discovery scope
zones to the NAT address spaces:
a. Click Scope.
b. Click a scope zone to edit it. The Scope Properties page is displayed.
c. In the Address Space field, enter the NAT address space and click OK. The
Address Space field appears on the Scope Properties only after the Enable
Network Address Translation (NAT) Support has been selected.
d. Repeat the previous two steps for all the required scope zones.
e. Click Save
.
NAT Address Spaces Dynamic Distinct view is created automatically if Enable
Network Address Translation (NAT) Support is turned on. Once discovery is
complete, use the Network Views to visualize the NAT Address Spaces
network view.
Related tasks:
“Scoping discovery” on page 27
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
“Configuring NAT discoveries” on page 194
Configure a Network Address Translation (NAT) discovery to discover NAT
environments, by mapping the address-space identifier for a NAT domain to the IP
address of the associated NAT gateway device.
Related reference:
“Quick reference for NAT discovery configuration” on page 197
Use this information as a step-by-step guide to configuring a NAT discovery..
Configuring a multicast discovery
Configure a multicast discovery by enabling the required agents and scoping the
discovery.
Related concepts:
“Types of scoping” on page 3
Network Manager offers several types of scoping.
Related tasks:
“Scoping discovery” on page 27
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
Chapter 2. Configuring network discovery
43
Related reference:
“scope.multicastSource table” on page 319
The scope.multicastSource table defines which IPM routes to discover. This is
particularly useful if you have multiple IPM route sources, since you can scope
multicast discovery by IPM route source to focus on the sources of interest.
“scope.multicastGroup table” on page 318
The scope.multicastGroup table defines which multicast groups to discover and
which details to retrieve from these groups.
Enabling the multicast agents:
To discover multicast groups, you must enable the appropriate agents and add the
relevant SNMP community strings.
To enable the agents, complete the following steps.
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click the Full Discovery Agents tab. The Agents List is displayed, showing all
available discovery agents for the selected discovery option.
4. Click Full Layer 2 and Layer 3 Discovery > Multicast.
5. Select the check box next to the agents you want to enable.
a. Enable the StandardPIM agent to discover protocol-independent multicast
groups compliant with the RFC2934 PIM MIB.
b. Enable the StandardIPMRoute agent to discover IP multicasting networks
compliant with the RFC2932 IPMRoute MIB.
c. Enable the StandardIGMP agent to discover multicast groups running the
Internet Group Membership Protocol (IGMP).
6. Click Save
.
7. Optional: If you want to rediscover multicast groups, also enable the
appropriate agents for partial discoveries.
8. Ensure that the SNMP community strings are configured correctly to access the
devices in the multicast groups.
Related reference:
“Multicast agents” on page 467
Multicast agents retrieve data from devices participating in multicast groups and
routes.
Scoping a multicast discovery:
Configure which multicast groups and sources to discover using the Multicast tab.
To configure a multicast discovery, complete the following steps.
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click Multicast.
4. In the Multicast Groups section, create a new multicast group or edit an
existing group:
v To create a new group to discover, click New
v To edit an existing group, click the group name.
44
IBM Tivoli Network Manager IP Edition: Discovery Guide
.
The Multicast Group Properties page is displayed.
5. Define the scope properties using the following fields:
Group Name
Specify a name for this multicast group.
PIM Mode
Select whether to include or exclude Protocol Independent Multicast
(PIM) data from the discovery. By default, PIM data is included.
IPM Route Mode
Select whether to include or exclude Internet Protocol Multicast (IPM)
group data from the discovery. By default, IPM Group data is
included.
IGMP Mode
Select whether to include or exclude Internet Group Management
Protocol (IGMP) data from the discovery. By default, IGMP data is
included.
Protocol
Only IPv4 is supported.
Specify which Group subnets to add to Multicast Groups
Use the following fields and buttons to add and delete group subnets:
Subnet
Enter a subnet and netmask for a group subnet to add to the
multicast groups.
Add
Click Add the add this group.
Delete Select a group subnet from the adjacent list and click Delete
to delete the selected group.
Note: Reserved multicast addresses are excluded from the scope by default.
6. Click OK.
7. To delete one or more groups, select the groups you want to delete and click
the Delete button
or Deselect All
. To select or deselect all groups, click the Select All
button.
8. In the Multicast Sources section, create a new multicast source or edit an
existing source.
v To create a new source to discover, click New
.
v To edit an existing source, click the source name.
The Multicast Source Properties page is displayed.
9. Define the source properties using the following fields:
IPM Route Mode
Select whether to include or exclude the group:
v Unknown - use default
v Include source
v Exclude source
Protocol
Only IPv4 is supported.
Chapter 2. Configuring network discovery
45
Specify which Group subnets to add to Multicast Sources
Use the following fields and buttons to add and delete group subnets:
Subnet
Enter a subnet and netmask for a group subnet to add to the
multicast sources.
Add
Click Add the add this group.
Delete Select a group subnet from the adjacent list and click Delete
to delete the selected group.
Specify which Source subnets to add to Multicast Sources
Use the following fields and buttons to add and delete group subnets:
Subnet
Enter a subnet and netmask for a sources subnet to add to the
multicast sources.
Add
Click Add the add this group.
Delete Select a source subnet from the adjacent list and click Delete
to delete the selected soource.
10. Click OK.
11. To delete one or more groups, select the groups you want to delete and click
the Delete button
or Deselect All
12. Click Save
. To select or deselect all groups, click the Select All
button.
.
Advanced discovery parameters
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
Set the advanced parameters on the Advanced tab of the Network Discovery
Configuration page. After you have set the advanced parameters, click Save
.
Attention: Modify the advanced settings only if you are an experienced Network
Manager user. If you modify the advanced parameters and the discovery does not
work as expected, click Reset to restore the default settings.
“Advanced
“Advanced
“Advanced
“Advanced
“Advanced
“Advanced
“Advanced
Finder Configuration”
Ping Finder Configuration” on page 47
Discovery Configuration” on page 48
Telnet Helper Configuration” on page 47
SNMP Helper Configuration” on page 48
DNS Helper Configuration” on page 48
Discovery Configuration” on page 48
Advanced Finder Configuration
To set advanced parameters for the File finder, use the following field:
Concurrent File Finders
Specify the number of threads to be used by the File finder. Each thread
46
IBM Tivoli Network Manager IP Edition: Discovery Guide
can process a different seed file simultaneously. If you have many seed
files and spare resources on the discovery server, more threads might result
in a faster discovery. If you have only one seed file, increasing the number
of threads has no effect.
Advanced Ping Finder Configuration
To set the advanced parameters for the Ping finder, use the following fields:
Concurrent Ping Finders
Specify the number of threads to be used by the Ping finder. Each thread
processes one pingFinder.pingRules insert at a time. Increasing the number
of threads does not speed up a single large ping sweep but might speed
up feedback of many addresses. However, you must balance speed against
the resources of your machine and the ability of the ping receiver to
process the ping responses in a timely manner. If the number of threads is
too high, the ping receiver will fall behind, resulting in false ping failures
and a loss of device discovery.
Studies have shown that the default number of 10 threads is optimal for
most situations. You can gradually increase the number of threads and
monitor the number of ping failures and make a note of time savings.
Depending on the resources available, at a certain point the benefits start
to decrease as resources are overloaded.
Default Timeout
Specify the maximum time, in milliseconds, to wait for a reply from a
pinged address. If you know that network latency is low, a reduced wait
time might result in a faster discovery. A value that is too low for your
network might result in devices not being discovered.
Default Number of Retries
Specify the number of times a device is to be pinged again following a
failed initial ping.
Inter-Ping Time
Specify the interval in milliseconds between ping attempts made against
the devices contained in a list or subnet. If network traffic resulting from
the discovery is not an issue, this value can be reduced.
Allow Broadcast Pinging
To enable broadcast address pinging, select this check box.
Allow Multicast Pinging
To enable multicast address pinging, select this check box.
Advanced Telnet Helper Configuration
To set advanced parameters for the Telnet helper, use the following fields:
Concurrent Telnet Helpers
Specify the number of threads to be used by the Telnet helper. If you have
many devices from which you want to access data using Telnet or SSH
then increasing this value might result in a faster discovery. Typical
examples of such devices are Catalyst switches, MPLS devices, and NAT
gateways. If you change this value, be sure that your system is configured
to allow at least this number of concurrent Telnet sessions.
Default Timeout
Specify the maximum time, in milliseconds, to wait for access to a device.
Chapter 2. Configuring network discovery
47
Number of Retries
Specify the number of times to try to connect to the device following a
failed initial connection attempt.
Tip: You can also configure some other advanced settings in the
DiscoTelnetHelperSchema.cfg file.
Advanced SNMP Helper Configuration
To advanced parameters for the SNMP helper, use the following fields:
Concurrent SNMP Helpers
Specify the number of threads to be used by the helper. If you have many
devices with SNMP access and spare resources on the discovery server,
more threads might result in a faster discovery. If you change this value,
make sure that your system is configured to allow at least this number of
concurrent SNMP sessions. This value must be more than the number of
threads used by the Details discovery agent.
Timeout
Specify the maximum time, milliseconds, to wait for access to a device.
Number of Retries
Specify the number of attempts to retrieve one or more SNMP variables
from a device after a failed initial attempt.
GetNext Slowdown
Specify the delay, in milliseconds, between each SNMP GetNext request.
The m_GetNextSlowDown parameter is applied when the number of separate
GetNext requests issued in order to retrieve a non-scalar SNMP variable
exceeds the value of the m_GetNextBoundary parameter.
GetNext Boundary
Specify the minimum number of GetNext requests to be issued when a
non-scalar SNMP variable is retrieved from a device. The
m_GetNextBoundary parameter is applied before the delay specified by the
m_GetNextSlowDown parameter is introduced.
Advanced DNS Helper Configuration
To set advanced parameters for the DNS helper, use the following fields:
Concurrent DNS Helpers
Specify the number of threads to be used by the helper. If you change this
value, be sure that your system is configured to allow at least this number
of concurrent DNS sessions.
Default Timeout
Specify the maximum time, in milliseconds, to wait for a response from a
device.
Advanced Discovery Configuration
To specify advanced feedback control, ping verification, and further advanced
discovery parameters, use the following fields:
Enable Feedback Control
Specify whether to enable feedback control. Feedback means that the data
returned by agents is used by the discovery to find other devices.
48
IBM Tivoli Network Manager IP Edition: Discovery Guide
Examples of feedback data include the IP addresses of remote neighbors,
and addresses in the subnet within which a local neighbor exists.
No Feedback
Feedback is switched off for all discoveries and rediscoveries. Only
the devices specified to the finders are discovered. This option
means that discoveries and rediscoveries complete in the quickest
possible time. However, the resulting network topology is
incomplete unless you specify all devices that you want to discover
as seeds.
Tip: Switch feedback off if you want to discover only a list of
certain devices. Specify the devices you want to discover as seeds.
Feedback
Feedback is switched on for full discoveries, full rediscoveries, and
partial rediscoveries. This option provides a complete topology in
all situations but takes the longest.
Feedback Only on Full
This setting is on by default. Feedback is switched on for full
discoveries and full rediscoveries, but switched off for partial
rediscoveries.
Enabling Ping Verification
Specify whether the discovery checks for pingable interfaces. If a device is
not pingable, the device is not polled for alerts.
Don't Check Pingability
None of the discovered interfaces are checked for whether they can
be pinged. Interfaces are polled regardless of whether they are
pingable at discovery.
Check Pingability
After discovery, every discovered interface is checked for whether
they can be pinged. The check is run against the details.returns
table. Interfaces that have an entry in this table are pingable.
Interfaces that do not have an entry in this table are not pingable.
The pingable interfaces are marked to be polled.
Detect Best Setting
This setting is on by default. If feedback control has been enabled,
after discovery, every discovered interface is checked for whether
they can be pinged. The check is run against the details.returns
table. Interfaces that have an entry in this table are pingable.
Interfaces that do not have an entry in this table are not pingable.
The pingable interfaces are marked to be polled.
Restriction: This option works only when you select one of the
following options from the Enable Feedback Control list: Feedback
or Feedback only on Full.
Enable 'Allow Virtual'
Specify how you want the discovery to handle virtual IP addresses:1 .
1. Devices are typically discovered using IP addresses retrieved by the AssocAddress agent. If a device is discovered using an IP
address that was not retrieved by the AssocAddress agent, then the IP address is probably non-standard. This type of IP address
is called a virtual IP address. Examples of virtual IP addresses are HSRP and VRRP addresses, which are shared by multiple
devices for fault tolerance. Other examples include certain management interfaces that might be on a single device but do not
appear in the IP table for security reasons. Virtual IP addresses include management addresses. A management address is an IP
Chapter 2. Configuring network discovery
49
Don't Allow Virtual
Does not discover virtual IP addresses.
Allow Virtual
Discovers virtual IP addresses. This setting is on by default.
Allow if in scope.special
Discovers virtual IP addresses only if the address is defined in the
scope.special table. This table defines management IP addresses.
Enable VLAN Modelling
Enable this setting to model VLANs in this discovery. If you enable VLAN
modeling, then you can partition discovered topologies based on VLAN
membership. Disabling VLAN modeling reduces discovery time.
Enable SysName Naming
Enable this setting to name devices using the value of the SNMP sysName
variable as the main source of naming information. The sysName variable
must be set and must be unique within the network. Enabling this setting
has no impact on the discovery time, because the sysName variable is
retrieved by the Details agent by default.
Important:
If devices have previously been discovered with SysName naming
disabled, duplicate devices can be displayed on the next discovery. For
example, the same device can appear twice, once with the IP address and
once with the new name. To avoid duplicate device entries, set the
LingerTime of all devices in the topology to zero before running your next
discovery. Log into the OQL Service Provider using the following
command: ncp_oql -domain NCOMS -service Model
Run the following command to set the LingerTime to zero:
update ncimCache.lingerTime set lingerTime = {LINGERTIME=0};
go
Enable Caching of Discovery Tables
Enable this setting to cache data during the discovery process in order to
enable data recovery if the Discovery engine, ncp_disco, fails. A discovery
running in this mode is slower than a standard discovery, because of the
extra time required to store data on the disk throughout the discovery
process.
Enable File Finder Verification
Enable this setting to use the Ping finder to verify the existence of devices
specified in the files used by the File finder. If you enable this setting,
ensure that the Ping finder is enabled. Enable this setting if you are not
sure that the devices are still connected to the network. For example, you
might want to enable this setting if your network is rapidly changing.
Enable Rediscovery Rebuild Layers
Enable this setting to rebuild the topology layers following a partial
rediscovery. If you specify that topology layers are rebuilt following partial
rediscovery, the result is an accurate topology showing all connectivity.
However, the process of adding new devices takes longer.
address whose only role is to manage the device. Management addresses are often on a separate network isolated from the
customer traffic. These addresses are defined in the scope.special table.
50
IBM Tivoli Network Manager IP Edition: Discovery Guide
Tip: To configure a partial rediscovery to run as quickly as possible,
disable this option.
Enable Rediscovery of Related Devices
By default the remote neighbors of a device are not rediscovered, even if
the rediscovery of that device indicates that the remote neighbors have
changed. The remote neighbors can be rediscovered on the next full
rediscovery. Enable this setting if you want to change this default behavior
and rediscover any changed remote neighbors when rediscovering that
device. If new neighboring devices are discovered during the blackout
phase, another partial rediscovery is triggered after the blackout phase. If
your network connectivity changes often, for example if you are
rediscovering devices with switch forwarding database tables, enabling
rediscovery of related devices can cause several discoveries to run one
after another. Multiple consecutive discoveries are more likely to happen if
the partial discovery takes longer, for example, if the Enable Rediscovery
Rebuild Layers setting is enabled.
Tip: To configure a partial rediscovery to run as quickly as possible,
disable this option.
Enable ifName/ifDescr Interface Naming
Changes the default naming convention for discovered interfaces. Names
interfaces using data from the SNMP interfaces table ifName and ifDescr
fields as appropriate. For example, Fa0/0, Gi 1.0.2:0, Gigabit Ethernet
4/1. If you change the default naming convention for discovered interfaces,
you must change the BuildInterfaceName stitcher to specify your naming
convention.
Tip: Some devices might report interface names and descriptions that are
too long to display properly in the topology display. If there are devices
that report long or incorrect interface names and descriptions, disable this
setting.
Enable Inference of PEs using BGP data on CEs
Discovers intervening provider networks as a “third-party” object on
multiple networks that run across a provider network. Examples of this
type of network include enterprise VPNs across a provider MPLS core
network. Select this option if you want to link all your networks in a single
topology and perform root cause analysis (RCA) across your networks.
This option infers the existence of inaccessible provider-edge (PE) devices
by using the BGP data on the customer-edge (CE) devices that point to the
PE devices. In order to discover this BGP data, the BGP discovery agents
must be enabled. If you want to use the cross-domain discovery function,
clear this option. If this option is selected, errors are generated during the
cross-domain discovery.
You can also optionally specify which of the inferred PE devices are valid
devices, by populating the scope.inferMPLSPEs table, using standard
format scope entries, as in the scope.zones table. If populated this table
allows you to define which IP addresses you see on CE devices that you
consider valid PE devices. Use this option when you have inaccessible
devices that are connected by BGP but which are not actually PE devices.
Enable Inference of MPLS CE routers on /30 subnets
Generates Service-Affected Events on customer VPNs. Select this option if
you are a service provider without access to customer CE routers.
Related concepts:
Chapter 2. Configuring network discovery
51
“About Service Affected Events” on page 184
A Service Affected Event (SAE) alert warns operators that a critical customer
service has been affected by one or more network events.
“Option to rebuild topology layers” on page 445
You can specify whether to rebuild the topology layers following a partial
rediscovery. Using this option, you can increase the speed of partial rediscovery.
Related tasks:
“Inferring the existence of CE routers” on page 188
You can infer the existence of your customers’ CE routers by making specifications
in the advanced discovery configuration options within the Discovery
Configuration GUI.
Related reference:
“Main discovery stitchers” on page 487
This topic lists the main discovery stitchers.
“Failover database” on page 413
Failover recovery with the failover database is not to be confused with agent and
finder failover recovery, which are configured directly from the disco.config table.
When selected, agent and finder failover recovery operate regardless of whether
recovery with the failover database is implemented.
“disco.config table” on page 295
The config table configures the general operation of the discovery process.
“scope.inferMPLSPEs table” on page 315
Use the scope.inferMPLSPEs table when enabling inference of inaccessible
provider-edge (PE) devices by using the BGP data on the customer-edge (CE)
devices. This table enables you to optionally specify which zones to process to
determine which of the inferred PE devices are valid devices.
Starting a discovery
After you configure a discovery, you can start and, if necessary, stop the discovery.
Make any required discovery configuration changes before you launch the
discovery.
You can start the following types of discovery:
Discovery
Run a full discovery to discover your network for the first time, or to
refresh the network topology if you know the network has changed.
Partial discovery
Run a partial discovery if you know that the changes to your network are
limited to a small number of devices. You need to configure scoping and
seeding as part of starting each partial discovery. If the relationship of the
devices that are in scope with their neighboring devices has changed, then
the neighboring devices may also be discovered. If the partial discovery
needs to discover a large amount of devices based on connectivity
information, then a full discovery is started.
Note: If you stop a running discovery, you must then do a full discovery before
you are able to do a partial discovery.
To start a discovery, complete the following steps.
1. Click the Discovery icon and select Network Discovery Status.
52
IBM Tivoli Network Manager IP Edition: Discovery Guide
2. Select the domain in which you want to run a discovery from the Domain
menu. You can start to type the name of the domain, and matching domains
are listed below the Domain field.
3. Start a full or partial discovery:
v To start a full discovery, click Start Discovery
only. The discovery
starts.
v To start a partial discovery, click the downward-facing arrow next to the
Start Discovery button
and select Start Partial Discovery from the
menu (if a full discovery has not been run since the last time that the
discovery engine, ncp_disco, was started, the option to start a partial
discovery is grayed out). The Partial Discovery window is displayed. Specify
the IP addresses and subnets that contain the devices to be discovered:
a. Under Partial Discovery, select the required nodes and subnets.
b. To add a new subnet or node, click New.
c. Complete the fields as follows and click OK:
Discover
Select one of the following options:
Identifier
Type the required IP address.
Subnet
Type the required subnet and specify the number of
netmask bits. The Netmask field is automatically updated.
EMS Device Name
Type the name of a device that was discovered through an
Element Management System (EMS). You can type the
nativeID, entity name, sysName, or display name.
Note: When running a partial discovery of an EMS collector
from the Discovery Status GUI, within the New Partial
Discovery Node/Subnet window you must specify the EMS
identifier value in the EMS Device Name field and not in
the Identifier field. The Identifier field only accepts IP
addresses.
d. To add new scope zones, click Scope.
e. To add a new discovery scope zone click New
zone, click the required entry in the list.
f. Complete the fields as follows and click OK:
. To edit an existing scope
Scope By:
Select one of the following options:
Subnet
Type the required subnet and specify the number of netmask
bits. The Netmask field is automatically updated.
You can specify a subnet or an individual IP address using
these fields.
Chapter 2. Configuring network discovery
53
v For example, to specify an IPv4 Class C subnet 10.30.2.0,
type 10.30.2.0/24, where 10.30.2.0 is the subnet prefix,
and 24 is the subnet mask.
v To specify an individual device, type an IPv4 IP address
and a subnet mask of 32. For example, type
10.30.1.20/32.
v If you are using IPv6, use a subnet mask of 112 or higher,
in order to avoid excessive discovery times.
Wildcard
Use an asterisk (*) as a wildcard.
For example, to specify a scope of all IP addresses that begin
with the 10.30.200. subnet prefix, type 10.30.200.*.
Restriction: Network Manager does not support the IPv4–mapped
IPv6 format and expects all IPv6 addresses to be in standard
colon-separated IPv6 format. For example, Network Manager does
not support an IPv4–mapped IPv6 address such as
::ffff:192.0.2.128. Instead enter this address as ::ffff:c000:280
(standard colon-separated IPv6 format).
Protocol
Select the required Internet protocol: IPv4 or IPv6.
Action
Define the subnet range as an inclusion zone or exclusion zone. If
the subnet range is an inclusion zone that you intend to ping during
the discovery, click Add to Ping Seed List. Clicking this option
automatically adds the devices in the scope zone as a discovery seed
devices.
Restriction: The Add to Ping Seed List option is not available for
IPv6 scope zones. This prevents ping sweeping of IPv6 subnets,
which can potentially contain billions of devices to be pinged. Ping
sweeping of IPv6 subnets can therefore result in a non-terminating
discovery.
g. Click OK then click Go. When a full or partial discovery is running, the
Start Discovery button is toggled off
.
4. To stop a discovery, click Stop Discovery
. The discovery might take a
short time to stop, during which time both the Start Discovery and Stop
Discovery buttons are toggled off. If you stop a discovery, you cannot then do
a partial discovery until after the next full discovery.
Note: When you stop a discovery, the discovery cache is lost. This is why you
must wait for the completion of the next full discovery before being able to
perform a partial discovery. It is possible to configure the Discovery engine to
save the discovery cache as the discovery is running, which would enable you
to run a partial discovery immediately following the manual stop of a
discovery. You can configure the Discovery engine to save the discovery cache
by clicking Enabling Caching of Discovery Tables in the Advanced tab.
While the discovery is running, you can monitor the progress of the discovery.
54
IBM Tivoli Network Manager IP Edition: Discovery Guide
Note: You cannot stop the discovery from the GUI in the correlating connectivity
phase. Stopping the discovery process from the command line while the topology
is being created can corrupt the discovery.
After the discovery is complete, the Start Discovery button is toggled on, and you
can run another full or partial discovery at any time. If the Event Gateway Disco
plug-in is enabled, then a new discovery can be triggered automatically when a
reboot event (event ID of NmosSnmpReboot triggered by the rebootDetection poll
policy) is received.
Related concepts:
“About types of discovery” on page 1
Different terms are used to describe network discovery, depending on what is
being discovered and how the discovery has been configured. You can run
discoveries, rediscoveries, and full and partial discoveries.
Related tasks:
“Monitoring network discovery from the GUI” on page 227
From the Active Discovery Status page, you can monitor the status and progress of
the current full or partial discovery, investigate the work of the discovery agents,
and view details of the last full discovery.
“Repairing a corrupted discovery” on page 268
If the discovery stops in an unusual way, for example, if the ncp_disco process is
stopped forcibly from the command line, or exits unexpectedly, you might need to
repair the discovery before running another discovery.
“Starting partial discovery from the GUI” on page 257
Starting a partial discovery involves defining a seed and scopes.
“Troubleshooting an idle discovery” on page 268
If you start the discovery, and after some minutes no devices have been
discovered, follow these troubleshooting steps.
Schemas and tables for GUI discovery parameters
Use this reference information to learn to which schemas and table the settings
made on the tabs of the Network Discovery Configuration page are saved.
The following table describes the tables to which the settings made on each tab of
the Network Discovery Configurationpage are saved. In these tables,
DOMAIN_NAME represents the name of the network domains in your
deployment, for example NCOMS.
Table 2. Schemas and tables to which the discovery parameters are mapped
Network
Discovery
Configuration
tab
Description
Schema or table name
Scope
The zones of the network (that is, subnet
ranges) that you want to include in the
discovery, and the zones that you want to
exclude.
DiscoScope.DOMAIN_NAME.cfg
Seed
The location from which to begin discovering
devices. This might be one or more IP
addresses, or subnet addresses. To seed the
discovery, the following finders are used: Ping
finder and File finder.
Ping finder:
DiscoPingFinderSeeds.DOMAIN_NAME.cfg
File finder:
DiscoFileFinderParseRules.DOMAIN_NAME.cfg
Chapter 2. Configuring network discovery
55
Table 2. Schemas and tables to which the discovery parameters are mapped (continued)
Network
Discovery
Configuration
tab
Description
Schema or table name
Full Discovery
Agents and
Partial
Rediscovery
Agents
The discovery agents to be used to investigate DiscoAgents.DOMAIN_NAME.cfg
device connectivity. Default agents are
provided for the type of discovery you want to
perform, for example a layer 2 or layer 3
discovery. You can select different set of agents
for full discoveries and for partial discoveries.
The agents vary because connectivity
information varies with the technology of the
hardware in the network.
Device Access
SNMP community strings and Telnet
parameters that Network Manager uses to
interrogate devices that use SNMP and Telnet.
SNMP community strings:
SnmpStackSecurityInfo.cfg
Telnet access: TelnetStackPasswords.cfg
Filters
Use filters to filter out devices either before
DiscoSchema.DOMAIN_NAME.cfg
discovery or after discovery. You can filter out
devices based on a variety of criteria, including
location, technology, and manufacturer.
Prediscovery filters prevent discovered devices
from being polled for connectivity information.
Post-discovery filters prevent discovered
devices from being passed to MODEL.
DNS
Access to DNS services that are used to
perform domain name lookups.
NAT
The data that provides the discovery mappings DiscoSchema.DOMAIN_NAME.cfg
between address space data and real device IP
addresses to facilitate further discovery.
Multicast
Multicast groups and sources used by the
DiscoScope.DOMAIN_NAME.cfg
Discovery engine to configure multicast scopes.
Advanced
Advanced settings control features of the
DiscoSchema.DOMAIN_NAME.cfg
discovery such as concurrent processes and
time-outs. Use these parameters to increase the
speed of the discovery, but balance the speed
with the load on the server. Generally, a faster
discovery results in more memory usage on the
server.
DiscoDNSHelperSchema.cfg
Discovering the network using the command-line interface
As an experienced user, you can configure and track a network discovery using
configuration files and database queries.
Related tasks:
“Monitoring discovery from the command line.” on page 233
When the ncp_disco process is running, you can monitor the progress of the
discovery by using the OQL Service Provider, the ncp_oql process, to query the
discovery databases to determine what is happening at any time.
56
IBM Tivoli Network Manager IP Edition: Discovery Guide
Discovery configuration files
Experienced users can configure the discovery by editing the discovery
configuration files.
To configure the discovery using the command-line interface (command line), edit
the discovery configuration files and create or edit inserts into the databases of the
discovery processes.
Note: The DiscoSchema.cfg configuration file contains the schemas for all the
discovery databases. Unlike the files listed below, the DiscoSchema.cfg
configuration file contains no insert statements. You can view this file but it must
not be edited.
When ncp_disco is running, it periodically scans the agents and stitchers
directories and loads any new or modified stitcher and discovery agent definitions.
Table 3 shows which configuration files to edit to configure the discovery, and
whether the configuration can also be done using the Discovery Configuration
GUI.
Table 3. User-editable discovery configuration files
Discovery configuration taska Configuration file
GUI tab
Scoping discovery
Defining inclusion and
exclusion zones
DiscoScope.cfg
Scope
Ignoring discovery scope
DiscoScope.cfg
Scope
DiscoPingFinderSeeds.cfg
Seed
Configuring broadcast and
multicast address pinging
DiscoPingFinderSeeds.cfg
Advanced
Using and configuring the
File finder
DiscoFileFinderParseRules.cfg
Seed
Seeding discovery
Using and configuring the
Ping finder
Running multiple instances
of a finder
Enabling File finder device
verification
Enabling Ping verification
DiscoConfig.cfg
Advanced
DiscoConfig.cfg
Using and configuring the
Database finder
DiscoDBEntryFinderQueries.cfg
Using and configuring the
Collector finder
DiscoCollectorFinderSeeds.cfg
SNMP
Configuring SNMP
community strings and
passwords
SnmpStackSecurityInfo.cfg
Passwords
Configuring the SNMP
helper
DiscoSnmpHelperSchema.cfg
Advanced
Chapter 2. Configuring network discovery
57
Table 3. User-editable discovery configuration files (continued)
Discovery configuration taska Configuration file
GUI tab
Overriding SNMP helper
settings for specific devices
and subnets
Telnet
Configuring Telnet access to TelnetStackPasswords.cfg
network devices
Passwords
Configuring the Telnet
helper
Advanced
DiscoTelnetHelperSchema.cfg
Configuring a context-sensitive
DiscoConfig.cfg
discovery
Agents
Enabling and disabling
discovery agents
DiscoAgents.cfg
Filtering devices sent to the
agents
Discovery agent definition files
Filtering topology data
returned by an agent
Discovery agent definition files
Filtering topology data
returned by all agents
DiscoAgentReturns.filter
Changing the number of
threads used by an agent
DiscoAgents.cfg
Enabling multi-threaded
operation for Perl agents
Discovery agent definition files
Enabling and disabling
partial matching
Full Discovery
Agents
Partial
Rediscovery
Agents
Filters
IpForwardingTable.agnt agent definition
file (for modern devices that use
RFC2096)
IpRoutingTable.agnt agent definition file
(for older devices that use RFC1213).
Restricting discovery
Restricting device detection
Restricting device
interrogation
Restricting device
instantiation
Scope
Seed
DiscoScope.cfg
SNMP interface filtering
DiscoSnmpHelperFilters.cfg
Configuring the DNS helper
services
DiscoDNSHelperSchema.cfg
DNS
Configuring a NAT discovery
NATTextFileAgent agent
NATGateway agent
NAT
Setting advanced configuration
58
DiscoScope.cfg
DiscoPingFinderSeeds.cfg
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 3. User-editable discovery configuration files (continued)
Discovery configuration taska Configuration file
Advanced File Finder
Configuration
DiscoFileFinderParseRules.cfg
Advanced Ping Finder
Configuration
DiscoDNSHelperSchema.cfg
Advanced DNS Helper
Configuration
DiscoTelnetHelperSchema.cfg
GUI tab
Advanced
DiscoPingFinderSeeds.cfg
DiscoSnmpHelperSchema.cfg
Advanced SNMP Helper Note: As an experienced user, you can
set more advanced configuration
Configuration
parameters in the configuration files
Advanced Telnet Helper
than are available in the Advanced tab
Configuration
of the GUI.
Discovery agent definition files:
The discovery agent definition files define the operation of the discovery agents.
Filtering devices using the definition files
Note: Network Manager kills all discovery agents at the end of data collection
stage 3. This ensures that the next discovery restarts the agents and forces the
agents to reread their configuration files at the beginning of a discovery, thereby
detecting any changes to the configuration files.
You can apply a filter to a discovery agent by editing the supported devices filter
within the DiscoAgentSupportedDevices( ); section of the discovery agent
definition file ($NCHOME/precision/disco/agents/*.agnt). All discovery agents
have a definition file in this directory, regardless of whether the agent is text-based
or precompiled.
The supported devices filter is a filter against the attributes of the
agentTemplate.despatch table.
The DiscoAgentSupportedDevices( ); section accepts full OQL comparison tests
using comparison operators such as like, < , > , = , and <>. Detailed information
about comparison tests in OQL can be found in the IBM Tivoli Network Manager IP
Edition Language Reference.
Tip: Altering agent definition files can introduce parse errors. To check your agent
for parse errors, run the agent in debug mode and examine the debug output.
Example: filtering devices sent to the CDP agent
The following example shows the DiscoAgentSupportedDevices(); section of the
CDP.agnt agent definition file. Only network entities that match the specified
Object IDs are processed by the CDP agent, that is, only devices that use the Cisco
Discovery Protocol. The CDP agent does not process devices with the Object ID
1.3.6.1.4.1.9.1.226.
DiscoAgentSupportedDevices
(
" (
( m_ObjectId like ’1\.3\.6\.1\.4\.1\.9\..*’ )
Chapter 2. Configuring network discovery
59
AND
( m_ObjectId <> ’1.3.6.1.4.1.9.1.226’ )
) "
);
Example: using wildcards in device filters
The following example shows the use of wild cards in the IP address column. The
agent only accepts devices with an IP address beginning 10.10.2.
DiscoAgentSupportedDevices
(
" ( m_UniqueAddress like ’10\.10\.2\..*’ ) "
);
Example: using multiple device filter conditions
The following example shows the combination of multiple filter conditions. The
agent accepts only devices that have the Object ID 1.3.6.1.4.1.9.5.7.. have an IP
address starting with 10.10.. and do not have the name clandestine.
DiscoAgentSupportedDevices
(
"(
( m_ObjectId = ’1.3.6.1.4.1.9.5.7’ )
AND
( m_UniqueAddress like ’^10\.10\..*’ )
AND
( m_Name not like ’.*[cC]landestin[eE].*’ )
)"
);
Enabling multi-threaded operation for Perl discovery agents
The number of threads used by discovery agents is set in the DiscoAgents.cfg
configuration file. Perl agents must have multi-threaded operation enabled before
the setting in the DiscoAgents.cfg configuration file has any effect.
To enable multi-threaded operation for a Perl discovery agent, add the following
line to its definition file:
DiscoAgentDefaultThreads( 10 );
The insert above specifies that the agent uses 10 threads by default. If you set a
different number of threads in the DiscoAgents.cfg configuration file, that value
overrides the value in the agent definition file.
Restriction: Many of the add-on CPAN modules often used with Perl are not
thread safe. Perl discovery agents using such modules might need to be restricted
to a single thread.
Filtering topology data returned by a discovery agent
To filter topology data returned by a single agent, define a filter within the relevant
agent (.agnt) file.
Example: filtering out subscriber cable-modem interfaces
The CMTS.agnt agent file retrieves data from cable modems connected to a cable
modem terminating services device. This example describes a filter added to the
60
IBM Tivoli Network Manager IP Edition: Discovery Guide
CMTS.agnt file which filters out subscriber cable modem interfaces from topology
data returned for the CMTS devices. The example filter is as follows:
DiscoAgentReturnsFilterList
{
DiscoReturnsFilter
{
"(
m_LocalNbr->m_IfType = 229
)"
}
};
Sample: defining multiple topology filters
The following example illustrates how to define multiple topology data filters
within an agent. The first filter specifies that each time a record is returned where
the interface ifIndex value is 4, then the m_Name, m_HaveAccess,
m_LocalNbr->m_SubnetMask, and m_RemoteNbr->m_RemoteNbrPhysAddr fields
must be deleted from the record. The second filter deletes records returned when
the interface ifIndex value is 5.
DiscoAgentReturnsFilterList
{
DiscoReturnsFilter
{
"(
m_LocalNbr->m_IfIndex = 4
)"
DiscoDeleteFields {
"m_Name",
"m_HaveAccess",
"m_LocalNbr->m_SubnetMask",
"m_RemoteNbr->m_RemoteNbrPhysAddr",
}
}
DiscoReturnsFilter
{
"(
m_LocalNbr->m_IfIndex = 5
)"
}
};
Example: Disabling partial matching
The following example could be appended to the IpForwardingTable.agnt
definition file to ensure that if a router with m_ObjectId='1.3.6.1.4.1.9.1.48' is
discovered (that is, a Cisco 7505 router), partial matching is attempted only when
the router is running IOS version 12.2 or higher.
DiscoRouterPartialMatchRestrictions
(
"(m_ObjectId=’1.3.6.1.4.1.9.1.48’, m_OSVersion>=’12.2’,
m_MibVar=’sysDescr’)"
);
Example: Disabling partial matching using wildcards
The following example ensures that partial matching is not used on Cisco 2600
routers, Cisco 7505 routers running an IOS revision lower than 12.2, and Redstone
routers.
Chapter 2. Configuring network discovery
61
DiscoRouterPartialMatchRestrictions
(
"(m_ObjectId=’1.3.6.1.4.1.9.1.209’),
(m_ObjectId=’1.3.6.1.4.1.9.1.48’, m_OSVersion>=’12.2’,
m_MibVar=’sysDescr’),
(m_ObjectId like ’1\.3\.6\.1\.4\.1\.2773\..*’)"
);
Related reference:
“disco.agents table” on page 293
The agents table specifies the discovery agents that ncp_disco uses for the
discovery. Every agent that you want to run must have an insertion into the
disco.agents table within the DiscoAgents.cfg configuration file that enables that
agent (set m_Valid=1). If m_Valid=0, the agent is not run.
“Agent Template database” on page 417
The databases of each discovery agent are based on a template called the
agentTemplate database.
DiscoAgents.cfg configuration file:
The DiscoAgents.cfg configuration file defines which agents run during a
discovery.
Database table used
The DiscoAgents.cfg configuration file can be used to configure inserts into the
disco.agents database table.
Sample: enabling the IpRoutingTable discovery agent
The following example activates the IpRoutingTable discovery agent.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’IpRoutingTable’, 1, 0, 0, 2
);
Sample: enabling the Details and Associated Address agents
The following example OQL inserts activate the Details and Associated Address
agents.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’Details’, 1, 0, 0, 1
);
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’AssocAddress’, 1, 0, 0, 2
);
62
IBM Tivoli Network Manager IP Edition: Discovery Guide
Sample: enabling the ARP cache agent
The ARP Cache agent assists in MAC address-to-IP address resolution during the
discovery. You must enable this agent to run during a layer 2 discovery. The
following example shows how to ensure that the ARP Cache agent runs during a
discovery.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’ArpCache’, 1, 0, 0, 2
);
Sample: deactivating the StandardSwitch and SuperStack3ComSwitch agents
The following example deactivates the StandardSwitch and the
SuperStack3ComSwitch discovery agents.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’StandardSwitch’, 0, 1, 1, 3
);
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’SuperStack3ComSwitch’, 0, 1, 1, 3
);
Sample: changing the number of threads used by the IpRoutingTable discovery
agent
The following example sets the number of threads used by the IpRoutingTable
discovery agent to 50. Increasing the number of threads used by an agent allows
the agent to process more devices at once, and can speed up discovery. However,
increasing the number of threads used by an agent also uses more memory.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence, m_NumThreads
)
values
(
’IpRoutingTable’, 1, 0, 0, 2, 50
);
Sample: changing the number of threads used by the NMAPScan Perl discovery
agent
The following example sets the number of threads used by the NMAPScan Perl
discovery agent to 50. To define the number of threads used by a Perl discovery
agent, you must first enable multiple threads for that agent in the discovery agent
definition file.
Chapter 2. Configuring network discovery
63
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence, m_NumThreads
)
values
(
’NMAPScan’, 1, 0, 0, 2, 50
);
Related reference:
“disco.agents table” on page 293
The agents table specifies the discovery agents that ncp_disco uses for the
discovery. Every agent that you want to run must have an insertion into the
disco.agents table within the DiscoAgents.cfg configuration file that enables that
agent (set m_Valid=1). If m_Valid=0, the agent is not run.
DiscoAgentReturns.filter configuration file:
The DiscoAgentReturns.filter configuration file allows you to apply a topology
data filter to data returned by all discovery agents.
Filtering topology data returned by all agents
The $NCHOME/precision/disco/agents/DiscoAgentReturns.filter configuration
file filters the same topology data from all of the agent returns tables. The syntax
used in this file is the same as the syntax used in topology filters in the discovery
agent definition files.
Sample: filtering out subscriber cable-modem interfaces
The following example filters out subscriber cable modem interfaces from topology
data:
DiscoAgentReturnsFilterList
{
DiscoReturnsFilter
{
"(
m_LocalNbr->m_IfType = 229
)"
}
};
Related concepts:
“Agents” on page 447
Discovery agents retrieve information about devices in the network. They also
report on new devices by finding new connections when investigating device
connectivity. Discovery agents are used for specialized tasks. For example, the ARP
Cache discovery agent populates the Helper Server database with IP
address-to-MAC address mappings.
64
IBM Tivoli Network Manager IP Edition: Discovery Guide
DiscoARPHelperSchema.cfg configuration file:
The DiscoARPHelperSchema.cfg configuration file performs IP address to MAC
address resolution.
Database used
The DiscoARPHelperSchema.cfg configuration file defines inserts into the
ARPHelper.configuration database table.
Sample: Configuring the ARP helper
The following example insert configures the ARP helper to use one thread.
insert into ARPHelper.configuration
(
m_NumThreads
)
values
(
1
);
Related reference:
“ARPhelper database” on page 354
The ARPHelper database configures the operation of the ARP helper, stores
information about the requests the ARP helper makes from the network.
DiscoCollectorFinderSeeds.cfg configuration file:
The DiscoCollectorFinderSeeds.cfg configuration file defines how topology data
is acquired from Element Management System (EMS) collectors during discovery.
Database used
The DiscoCollectorFinderSeeds.cfg configuration file defines inserts into the
collectorFinder database.
Note that there is another file associated with the collectorFinder database, the
DiscoCollectorFinderSchema.cfg file, but you should not need to alter this file.
Sample: configuring a single collector
The following example seeds a single collector running on the local server. The
example does not specify values for other fields, such as m_DataSourceId and
m_NumRetries, and they automatically take the default values from the
configuration table.
insert into collectorFinder.collectorRules
( m_Port)
values
( 8082 );
Related reference:
“collectorFinder database” on page 345
The collectorFinder database defines the operation of the Collector finders.
Chapter 2. Configuring network discovery
65
DiscoDBEntryFinderQueries.cfg configuration file:
The DiscoDBEntryFinderQueries.cfg file is used to specify the a database query to
be run against a specified database in order to retrieve a list of IP addresses of
devices to discover on the network.
Database tables used
This configuration file can be used to configure inserts into the following database
tables:
v dbEntryFinder.configuration
v dbEntryFinder.dbQueries
Example: configuring the Database finder to use five threads
The following example insert configures the Database finder to use five threads.
insert into dbEntryFinder.configuration
( m_NumThreads )
values
( 5 );
Example: configuring the Database finder to use an external Tivoli Data
Warehouse database
The following example configuration instructs the Database finder to retrieve
device data from an external Tivoli Data Warehouse database.
insert into dbEntryFinder.dbQueries
(
m_DbId, m_TriggerType, m_Query, m_Parameters, m_Mapping
)
values
(
"TDW",
1,
"select DISTINCT MAC_Address , System_Name ,
Network_Interface_Name , Interface_Status ,
Device_Type , Interface_IP_Address
from ABC_Network where Linux_OS_Config = ?",
[ ’Redhat 6.5’ ],
[
{
FromDb = "eval(text,’&System_Name’)",
ToFinder = ’m_Name’
},
{
FromDb = "eval(text,’&Interface_IP_Address’)",
ToFinder = ’m_UniqueAddress’
},
{
FromDb = 23,
ToFinder = ’m_ExtraInfo->m_SourceId’
},
{
FromDb = "eval(text,’&Device_Type’)",
ToFinder = ’m_ExtraInfo->m_DeviceType’
}
]
);
The foregoing insert specifies that:
66
IBM Tivoli Network Manager IP Edition: Discovery Guide
v The database that hosts the device details has a database identifier (dbId) of TDW
in the DbLogins.DOMAIN.cfg configuration file.
v The trigger type is 1. This means that this query will be invoked during a full
discovery.
v The query to run against the TDW database must retrieve the following data for
each device:
– MAC address
– Device name
– Network interface name
– Interface status
– Device type
– IP address
v Using the optional parameter field, specify that the Linux operating system is
RedHat 6.5.
v Map device data retrieved by the query to relevant fields in the finders.returns
table.
Related reference:
“dbEntryFinder database” on page 347
The dbEntryFinder database defines the operation of the Database finder.
DiscoDNSHelperSchema.cfg configuration file:
The DiscoDNSHelperSchema.cfg configuration file defines access to DNS, which
enables the discovery to do domain name lookups, by configuring the DNS helper.
Database tables used
The DiscoDNSHelperSchema.cfg configuration file can be used to configure inserts
into the following database tables:
v DNSHelper.configuration
v DNShelper.methods
Sample: configuring the DNS helper
The following example inserts configure the DNS helper using the information in
the DNSHelper.configuration database table and the DNShelper.methods database
table. The example shows inserts into the DNShelper.methods database table
corresponding to the following method types:
v 0 - System
v 1 - DNS using m_NameDomain to specify a domain suffix to append to all
discovered device names.
v 1 - DNS using m_NameDomainList to specify a list of expected domain suffixes.
v 2 - File
insert into DNSHelper.configuration
(
m_NumThreads, m_MethodList, m_TimeOut
)
values
(
1, [’HostsFile’] , 5
);
insert into DNSHelper.methods
Chapter 2. Configuring network discovery
67
(
m_MethodName, m_MethodType
)
values
(
"HostService", 0
);
insert into DNSHelper.methods
(
m_MethodName, m_MethodType, m_NameServerAddr, m_TimeOut, m_NameDomain
)
values
(
"abcIPv6DNS", 1, "2222:15f8:106:203:250:4ff:fee8:6d75", 3,
"tivlab.raleigh.ibm.com"
);
insert into DNSHelper.methods
(
m_MethodName, m_MethodType, m_TimeOut, m_NameServerAddr, m_NameDomainList
)
values
(
"defIPv6DNS", 1, 3, "2222:15f8:106:203:250:4ff:fee8:6d75",
[’uk.eu.org’,
’fra.eu.org’,
’de.eu.org’,
’it.eu.org’,
’sp.eu.org’]
);
insert into DNSHelper.methods
(
m_MethodName, m_MethodType, m_FileName, m_FileOrder
)
values
(
’HostsFile’, 2, ’etc/hosts’, 1
);
Related reference:
“DNSHelper database” on page 357
The DNSHelper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
DiscoFileFinderParseRules.cfg configuration file:
The DiscoFileFinderParseRules.cfg file can be used to specify the files to be parsed
for a list of IP addresses of devices that exist on the network.
Database tables used
This configuration file can be used to configure inserts into the following database
tables:
v fileFinder.parseRules
v fileFinder.configuration
Note that there is another configuration file associated with the fileFinder database,
the DiscoFileFinderSchema.cfg file, but you should not need to alter this file.
68
IBM Tivoli Network Manager IP Edition: Discovery Guide
Sample: configuring the File finder to use five threads
The following example insert configures the File finder to use five threads.
insert into fileFinder.configuration
( m_NumThreads )
values
( 5 );
Example: configuring the File finder to parse /var/tmp/logged_hosts
The following example configuration instructs the File finder to parse an example
text file, logged_hosts, that has been saved in the /var/tmp directory. The contents
of the example file are shown below.
vi /var/tmp/logged_hosts
172.16.1.21 dharma
04:02:08
172.16.1.201 phoenix
19:07:08
172.16.1.25 lnd-sun-tivoli
15:10:00
172.16.2.33 ranger
19:07:07
~
"/var/tmp/logged_hosts" [Read only] 4 lines, 190 characters
The three columns in this example file respectively contain an IP address, the
device name, and a time value. The columns are separated by white space, which
can be multiple tabs, spaces, or a combination of both. You could configure the File
finder to parse this example text file using an insert similar to the example.
insert into fileFinder.parseRules
(
m_FileName, m_Delimiter, m_ColDefs
)
values
(
"/var/tmp/logged_hosts",
"[
]+",
[
{
m_VarName="m_UniqueAddress",
m_ColNum=1
},
{
m_VarName="m_Name",
m_ColNum=2
}
]
);
The above insert specifies that:
v The full path and name of the file is /var/tmp/logged_hosts.
v The source-file delimiter is white space. The column delimiter is indicated in the
insert using a simple regular expression, [ tab space ]+ . You must press the tab
and space keys rather than typing \t to represent the tab character.
v The first column contains IP addresses and must be mapped to the
m_UniqueAddress column of the finders.returns table.
v The second column contains host names and must be mapped to the m_Name
column of the finders.returns table.
Because the third column in the example text file is not relevant, it has not been
mapped to a column of finders.returns and is ignored by the File finder during the
discovery.
Chapter 2. Configuring network discovery
69
Example: configuring the File finder to parse the /etc/hosts file
The following insert instructs the File finder to:
v Parse /etc/hosts.
v Treat white space as the data separator.
v Use the following column definitions:
– m_UniqueAddress for the first column
– m_Name for the second column
insert into fileFinder.parseRules
(
m_FileName,
m_Delimiter,
m_ColDefs
)
values
(
"/etc/hosts",
"[
]",
[
{
m_VarName="m_UniqueAddress",
m_ColNum=1
},
{
m_VarName="m_Name",
m_ColNum=2
}
]
);
Sample: configuring the File finder to parse /etc/defaultrouter
The following insert instructs the File finder to:
v Parse /etc/defaultrouter.
v Treat one or more occurrences of white space as the data separator.
v Use m_UniqueAddress as the column definition.
insert into fileFinder.parseRules
(
m_FileName,
m_Delimiter,
m_ColDefs
)
values
(
"/etc/defaultrouter",
"[
]+",
[
{
m_VarName="m_UniqueAddress",
m_ColNum=1
}
]
);
Related reference:
“fileFinder database” on page 349
The fileFinder database defines the operation of the File finder.
70
IBM Tivoli Network Manager IP Edition: Discovery Guide
DiscoHelperServerSchema.cfg configuration file:
The DiscoHelperServerSchema.cfg configuration file defines the contents of the
several helper databases.
Database tables used
This configuration file can be used to configure inserts into the following database
tables.
ARP helper database tables:
v ARPHelper.ARPHelperTable
v ARPHelper.ARPHelperConfig
DNS helper database tables:
v DNSHelper.DNSHelperTable
v DNSHelper.DNSHelperConfig
Ping helper database tables:
v PingHelper.PingHelperTable
v PingHelper.PingHelperConfig
SNMP helper database tables:
v SnmpHelper.SnmpHelperTable
v SnmpHelper.SnmpHelperConfig
Telnet helper database tables:
v TelnetHelper.TelnetHelperTable
v TelnetHelper.TelnetHelperConfig
XMLRPC helper database tables:
v XmlRpcHelper.XmlRpcHelperTable
v XmlRpcHelper.XmlRpcHelperConfig
Related reference:
“The Helper Server databases” on page 354
When the Helper Server starts, it creates a database for each helper that is to be
run.
DiscoPingFinderSeeds.cfg configuration file:
The DiscoPingFinderSeeds.cfg configuration file is used for seeding the Ping finder
and restricting device detection.
Database tables used
The DiscoPingFinderSeeds.cfg configuration file can be used to configure inserts
into the following database tables:
v pingFinder.pingRules
v pingFinder.scope
Note that there is another configuration file associated with the pingFinder
database, the DiscoPingFinderSchema.cfg file, but you should not need to alter this
file.
Chapter 2. Configuring network discovery
71
Note: If you are seeding an IPv6 discovery, bear in mind that there are potentially
billions of devices to be pinged within a single IPv6 subnet. To ensure that
discovery completes, you must specify a sufficiently large netmask if you specify
an IPv6 subnet as a ping seed.
Sample: seeding the Ping finder with a single device address
The following example insert defines a single seed with IP address of 10.10.2.224.
This example does not specify values for m_NumRetries and m_TimeOut because
they automatically take the default values from the configuration table.
Restriction: Network Manager does not support the IPv4–mapped IPv6 format
and expects all IPv6 addresses to be in standard colon-separated IPv6 format. For
example, Network Manager does not aupport an IPv4–mapped IPv6 address such
as ::ffff:192.0.2.128. Instead enter this address as ::ffff:c000:280 (standard
colon-separated IPv6 format).
insert into pingFinder.pingRules
( m_Address, m_RequestType )
values
( "10.10.2.224", 1 );
Sample: seeding the Ping finder with a class B subnet address
The following example insert defines a single class B subnet as a seed.
insert into pingFinder.pingRules
( m_Address, m_RequestType, m_NetMask )
values
( "10.10.0.0", 2, "255.255.0.0" );
Sample: seeding the Ping finder with class C subnet addresses
The following example insert defines two Class 2 subnets as seeds.
insert into pingFinder.pingRules
( m_Address, m_RequestType, m_NetMask )
values
( "10.10.2.0", 2, "255.255.255.0" );
insert into pingFinder.pingRules
( m_Address, m_RequestType, m_NetMask )
values
( "10.10.47.0", 2, "255.255.255.0" );
Sample: restricting device detection
The following example insert configures the Ping finder to use the scope.zones
table and use the discovery scope.
insert into pingFinder.scope
( m_UseScope, m_UsePingEntries )
values
( 1, 1 );
Important: Other combinations of m_UseScope and m_UsePingEntries filters are
not recommended. Specifying values (0,0) results in an unbounded discovery,
while specifying values (0,1) results in devices that you do not want to discover
being needlessly pinged.
Related reference:
“pingFinder database” on page 350
The pingFinder database defines the operation of the Ping finder.
72
IBM Tivoli Network Manager IP Edition: Discovery Guide
“IPv6 subnet mask sizes” on page 32
There are potentially billions of devices to be pinged within a single IPv6 subnet.
To ensure that discovery completes, you must specify a sufficiently large netmask
if you specify an IPv6 subnet as a ping seed.
DiscoPingHelperSchema.cfg configuration file:
The DiscoPingHelperSchema.cfg configuration file defines how devices are to be
pinged.
Database table used
The DiscoPingHelperSchema.cfg configuration file can be used to configure inserts
into the pingHelper.configuration database table.
In this example configuration of the DiscoPingHelperSchema.cfg configuration file,
the parameters specify to:
v Use 20 threads of process execution.
v Wait a maximum of 250 ms for a reply from a device.
v Retry unresponsive devices a maximum of five times.
v Wait 50 ms between pinging devices in a subnet.
v Not use broadcast or multicast pinging.
insert into pingHelper.configuration
(
m_NumThreads,
m_TimeOut,
m_NumRetries,
m_InterPingTime,
m_Broadcast,
m_Multicast
)
values
(
20, 250, 5, 50, 0, 0
);
Related reference:
“Connectivity at the layer 3 network layer” on page 460
There are a number of discovery agents that retrieve connectivity information from
OSI model layer 3 (the Network Layer). Layer 3 is responsible for routing,
congestion control, and sending messages between networks.
“PingHelper database” on page 360
The PingHelper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
DiscoConfig.cfg configuration file:
The DiscoConfig.cfg configuration file is used to have the Ping finder automatically
check the devices discovered by the File finder, and to enable a context-sensitive
discovery.
Database table used
The DiscoConfig.cfg configuration file can be used to configure inserts into the
following tables:
v disco.config
Chapter 2. Configuring network discovery
73
v disco.managedProcesses
v disco.NATStatus
v translations.NATAddressSpaceIds
v disco.ipCustomTags
v disco.filterCustomTags
v translations.collectorInfo
v failover.restartPhaseAction
v failover.config
v failover.doNotCache
The following examples illustrate inserts into the disco.config database table.
Sample: pinging File finder devices
The following example command configures the discovery so that the devices
discovered by the File finder are automatically checked by the Ping finder.
update disco.config set m_CheckFileFinderReturns = 1;
Sample: enabling a context-sensitive discovery
Attention: Enabling a context-sensitive discovery automatically enables all the
Context agents. Disabling a context-sensitive discovery automatically disables all
the Context agents. You should not manually enable or disable Context agents,
either through the configuration files or through the Discovery Configuration GUI.
To enable a context-sensitive discovery, append the following insert to the
DiscoConfig.cfg file:
insert into disco.config
(
m_UseContext
)
values
(
1
)
Inserting the value 0 disables the context-sensitive discovery.
Enriching topology using custom tags
You can use the disco.ipCustomTags and disco.filterCustomTags tables to enrich
the discovered topology by associating one or more name-value pair tags with
discovered entities.
Related concepts:
“Discovering device details (context-sensitive)” on page 433
The discovery of context-sensitive device details is carried out in several steps.
Related reference:
“Context-sensitive discovery agents” on page 474
There are several agents that take part in a context-sensitive discovery.
“disco.config table” on page 295
The config table configures the general operation of the discovery process.
74
IBM Tivoli Network Manager IP Edition: Discovery Guide
DiscoScope.cfg configuration file:
The DiscoScope.cfg configuration file can be used to configure the scope of a
discovery.
Database tables used
This configuration file can be used to configure inserts into the following database
tables:
v scope.zones
v scope.detectionFilter
v scope.instantiateFilter
v scope.multicastGroup
v scope.multicastSource
v scope.special
Restriction: The scope.zones table can only be used to configure scoping for
IP-based entities. Non-IP entities such as layer 1 optical devices must be scoped
using the scope.detectionFilter table.
Sample: defining an inclusion zone
The following example insert defines the 10.10.2.* subnet as an inclusion zone.
Restriction: Network Manager does not support the IPv4–mapped IPv6 format
and expects all IPv6 addresses to be in standard colon-separated IPv6 format. For
example, Network Manager does not support an IPv4–mapped IPv6 address such
as ::ffff:192.0.2.128. Instead enter this address as ::ffff:c000:280 (standard
colon-separated IPv6 format).
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[
{
m_Subnet="10.10.2.*"
}
]
);
Sample: defining multiple inclusion zones
The following example defines three different IP inclusion zones each using a
different syntax to define the subnet mask. The following devices are discovered:
v Any device within the 172.16.1.0 subnet (with a subnet mask of 24, that is, 24
bits turned on and 8 bits turned off, which implies a netmask of 255.255.255.0).
v Any device within the 172.16.2.0 subnet with a mask of 255.255.255.0.
v Any device within the 172.16.3.0 subnet with a mask of 255.255.255.0.
Chapter 2. Configuring network discovery
75
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[
{
m_Subnet="172.16.1.0",
m_NetMask=24
},
{
m_Subnet="172.16.2.*"
},
{
m_Subnet="172.16.3.0",
m_NetMask="255.255.255.0"
}
]
);
Sample: defining an exclusion zone
The following example insert defines a single exclusion zone for the IP protocol,
and associates the zone with a subnet.
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
2,
[
{
m_Subnet="172.16.1.0",
m_NetMask=24
]
);
Sample: defining an inclusion zone within a NAT domain
The following example defines one inclusion zone. The inclusion zone includes any
device with an IP address starting with 172.16.2 that also belongs to the NAT
address space NATDomain1. The protocol is set to 1, that is, IP.
insert into scope.zones
(
m_Protocol, m_Action, m_Zones, m_AddressSpace
)
values
(
1,
1,
[
{
m_Subnet="172.16.2.*",
76
IBM Tivoli Network Manager IP Edition: Discovery Guide
}
],
"NATDomain1"
);
Sample: restricting device interrogation based on IP address
The following example shows how to prevent the further interrogation of devices
that match a given IP address. Only devices that do not have the IP address
10.10.63.234 are interrogated further. Within the scope.detectionFilter table, specify:
v The filter condition(s). Only devices that pass this filter, that is, for which the
filter evaluates true, are further investigated. If no filter is specified, all devices
are passed through the detection filter.
insert into scope.detectionFilter
(
m_Filter
)
values
(
"( ( m_UniqueAddress <> ’10.10.63.234’ ) )"
);
A stitcher tests each discovered device against the filter condition in the
scope.detectionFilter table, and the outcome of this test determines whether the
device is discovered.
Because the process flow of the discovery is fully configurable, you can configure
this stitcher to act at any time during the discovery process. By default, the stitcher
performs the conditional test on the device details returned by the Details agent.
Your filter must therefore be based on the columns of the Details.returns table.
Although you can configure the filter condition to test any of the columns in the
Details.returns table, you might need to use the IP address as the basis for the filter
to restrict the detection of a particular device. If the device does not grant SNMP
access to the Details agent, the Details agent might not retrieve MIB variables such
as the Object ID. However, you are guaranteed the return of at least the IP address
when the device is detected.
The following examples show how else you might configure the detection filter.
Sample: restricting interrogation based on Object ID
The following example shows how to prevent the further interrogation of devices
that match a given Object ID. The OQL not like clause indicates that only devices
that pass the filter (that is, devices for which the OID is not like 1.3.6.1.4.1.*) are
interrogated further.
The backslash must be used in the insert to escape the ., which would otherwise
be treated as a wildcard. A full explanation of the syntax of OQL can be found in
the IBM Tivoli Network Manager IP Edition Language Reference.
insert into scope.detectionFilter
(
m_Filter
)
values
(
Chapter 2. Configuring network discovery
77
"(
( m_ObjectId not like ’1\.3\.6\.1\.4\.1\..*’ )
)"
);
Sample: combining multiple filter restrictions
You can combine filter conditions within a single OQL insert. The following
example ensures that only devices that do not have the specified OID and do not
have the specified IP address are detected:
insert into scope.detectionFilter
(
m_Filter
)
values
(
"(
( m_ObjectId not like ’1\.3\.6\.1\.4\.1\..*’ )
AND
( m_UniqueAddress <> ’10.10.63.234’ )
)"
);
Restricting instantiation: limitation when filtering out interfaces
Note the following limitation when you restrict instantiation of interfaces.
Restriction: To ensure that alerts are not raised for interfaces that are excluded by
the instantiation filter, you must set the RaiseAlertsForUnknownInterfaces variable.
To this, perform the following steps:
1. Edit the $NCHOME/etc/precision/NcPollerSchema.cfg configuration file.
2. Add the following line to the file:
update config.properties set RaiseAlertsForUnknownInterfaces = 0;
Sample: restricting instantiation based on entity name
To restrict the devices that are instantiated, append an OQL insert into the
scope.instantiateFilter table. The instantiateFilter table requires a conditional test.
Only devices that pass the filter are sent to ncp_model. If no filter is defined, all
discovered devices are passed to ncp_model.
The conditional test must be based on the ncimCache data format.
The following example postdiscovery filter restricts instantiation of a chassis and
its contents.
insert into scope.instantiateFilter
(
m_Filter
)
values
(
"
(
BASENAME != ’jane’
)
"
);
78
IBM Tivoli Network Manager IP Edition: Discovery Guide
The following example postdiscovery filter restricts instantiation of a chassis and
its contents.
insert into scope.instantiateFilter
(
m_Filter
)
values
(
"
(
snmpSystem->SYSDESCR NOT LIKE ’ device’
)
"
);
Using scope.special to restrict device detection
Make entries in the scope.special table for network interfaces that can be accessed
through multiple IP addresses. The entries in the scope.special table control which
IP addresses Network Manager uses to monitor devices for NCMP and SNMP
polling policies.
The following sample shows an INSERT statement to the scope.special table. It
defines the IP address 192.168.1.3 as a potential management interface for chassis
and interfaces. It provides extra customer information that is added to the
ExtraInfo section of the entity in the model master.entityByName database table if
the IP address is discovered.
insert into scope.special
(
m_Zones,
m_Identifier,
m_Priority,
m_NonPingable,
m_AdminInterface,
m_ExtraInfo,
m_Protocol,
m_IsManagement,
m_OutOfBand,
m_IsValidVirtual
)
values
(
[
{
m_Subnet="192.168.1.3",
m_NetMask=32
}
],
"CustomerFacing",
99,
0,
1,
{
m_CustomerName = ’MyCompany’,
m_CustomerType = ’Internal’
},
1,
0,
1,
0
);
Chapter 2. Configuring network discovery
79
For a device that has 2 IP addresses, 172.20.1.1 and 192.168.1.3, the configuration
means that 172.20.1.1 is not chosen as the IP address through which to manage the
device. 192.168.1.3 is used instead. The following example shows what the final
topology entry in the master.entityByName looks like in this instance. The data
inside ExtraInfo that is prefixed with m_ScopeSpecial comes from the scope.zones
entry that matched the IP address of 192.168.1.3.
{
EntityName=’192.168.1.3’;
Address=[’’,’’,’192.168.1.3’];
EntityType=1;
EntityOID=’1.3.6.1.4.1.8072.3.2.10’;
IsActive=1;
Status=1;
ExtraInfo={
m_SysName=’SYS1’;
m_DNSName=’DNS1’;
m_time=1362486845;
m_DisplayLabel=’DNS1’;
m_AssocAddress=
[{m_IfIndex = 1, m_IpAddress = ’172.20.1.1’, m_Protocol = 1, m_IfOperStatus = 1 },
{m_IfIndex = 2, m_IpAddress = ’192.168.1.3’, m_Protocol = 1, m_IfOperStatus = 1 }];
m_ScopeSpecialIsManagement=1;
m_ScopeSpecialPriority=99;
m_ScopeSpecialIdentifier=’CustomerFacing’;
m_ScopeSpecialExtraInfo={
m_CustomerName = ’MyCompany’,
m_CustomerType = ’Internal’
};
m_DefinedMgmtIP=1;
m_IsOutOfBand=1;
m_BaseName=’192.168.1.3’;
m_AddressSpace=NULL;
m_AccessProtocol=1;
m_AccessAddress=’192.168.1.3’;
};
LingerTime=3;
ActionType=0;
CreateTime=1362486848;
ChangeTime=1362486848;
ClassName=’NetworkDevice’;
ClassId=5;
ObjectId=2272;
}
Related reference:
“Discovery scope database” on page 314
The scope database limits the extent or reach of a discovery. Using the scope
database, you can configure a range of protocols and attributes that define zones
that are to be included or excluded from the discovery process.
Scope configuration for non-IP devices:
Configure scope for non-IP devices by configuring inserts into the
scope.detectionFilter database table within the DiscoScope.cfg configuration file.
Note: The detection filter runs against the data returned by the agents, in the
Details.returns and CollectorDetails.returns tables, so scoping devices in this
way has minimal impact on the target devices.
80
IBM Tivoli Network Manager IP Edition: Discovery Guide
Sample: only pass non-IP devices for discovery
The following example insert ensures that only non-IP devices are passed to
discovery and interrogated further. This filter would exclude all IP-based devices.
insert into scope.detectionFilter
(
m_Filter,
)
values
(
"( m_Protocol = 4 )"
);
Sample: combining multiple filter restrictions for non-IP devices
The following example insert ensures that only non-IP devices are passed to
discovery and the non-IP devices that are passed must not include the specified
string in their unique Element Management System (EMS) key.
insert into scope.detectionFilter
(
m_Filter,
)
values
(
"(
( m_Protocol = 4 )"
AND
( m_UniqueAddress NOT LIKE ’LONDON’ )"
)"
);
Devices with out-of-scope interfaces:
A network might contain devices that are within the discovery scope but that
contain interfaces that are out of scope. Because the device is in scope, the default
behavior of the layer 3 discovery agents is to download the interface table of the
device and discover all the interfaces of a device, even if the interfaces themselves
are out of scope.
If this situation applies to your network, and you want to modify the way in
which the discovery process handles devices that are partially in scope, there are
several ways to modify the discovery and monitoring process to exclude these
interfaces from the discovery.
A possible configuration adjustment is to modify the insert into the
scope.instantiateFilter such that the out-of-scope interfaces are not instantiated.
This solution means that the out-of-scope interfaces are still discovered, but are not
passed to MODEL to be instantiated to an Active Object Class (AOC); therefore the
out-of-scope interfaces are not represented on the topology or monitored.
You could also configure an SNMP instance filter to prevent the downloading of
SNMP data for certain interfaces.
You could also filter the data returned by the discovery agents using the
DiscoAgentReturns.filter configuration file.
Chapter 2. Configuring network discovery
81
DiscoSnmpHelperFilters.cfg configuration file:
The DiscoSnmpHelperFilters.cfg configuration file defines SNMP interface filters
for the SNMP Helper. SNMP interface filters define the interfaces for which you
want the SNMP Helper to retrieve information.
Database table used
The DiscoSnmpHelperFilters.cfg configuration file can be used to configure inserts
into the snmpHelper.instanceFilter database table.
Example simple interface filter
The following example retrieves information for interfaces with a name like "Gi0"
on a specific kind of device.
insert into snmpHelper.instanceFilter
(
m_FilterName,
m_DeviceFilter,
m_InstanceFilter
)
values
(
"TESTFILTER",
"sysObjectID = ’1.3.6.1.4.1.4874.1.1.1.1.3’ OR sysDescr LIKE ’ERX-1440’",
"ifName like ’Gi0’"
);
Related tasks:
“Filtering SNMP information from devices” on page 99
You can filter out SNMP information when devices are queried by the SNMP
helper by configuring inserts into the SNMP helper database.
DiscoSnmpHelperSchema.cfg configuration file:
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
Database table used
The DiscoSnmpHelperSchema.cfg configuration file can be used to configure
inserts into the snmpHelper.configuration database table.
You can also configure the SNMP Helper to use the GetBulk operation when
SNMP v2 or v3 is used. Use of the GetBulk operation improves discovery speed.
For more information, see the IBM Tivoli Network Manager Entry Edition Installation
and Configuration Guide
Sample: Configuring timeouts and threads
The following example configuration causes the SNMP helper to behave as follows:
v 120 threads of program execution are started to process incoming requests for
SNMP data from the Helper Server. The SNMP helper processes a maximum of
120 such requests simultaneously.
v A three-second timeout period is specified for a device to respond to an SNMP
query issued by the SNMP helper. If the device has not responded after this
time, the helper issues the request again, one time.
82
IBM Tivoli Network Manager IP Edition: Discovery Guide
insert into snmpHelper.configuration
(
m_NumThreads,
m_TimeOut,
m_NumRetries,
)
values
(
120, 3000, 1
);
Related tasks:
“Filtering SNMP information from devices” on page 99
You can filter out SNMP information when devices are queried by the SNMP
helper by configuring inserts into the SNMP helper database.
Related reference:
“Discovery agents that discover connectivity among Ethernet switches” on page
455
Discovery agents that discover connectivity information between Ethernet switches
have three main operational stages: gain access to the switch and download all the
switch interfaces; discover VLAN information for the switch; download the
forward database table for the switch.
“Discovering connectivity among ATM devices” on page 464
Asynchronous Transfer Mode (ATM) is an alternative switching protocol for mixed
format data (such as pure data, voice, and video). Several types of discovery
agents can be used to discover ATM devices on a network.
“Discovering NAT gateways” on page 468
There are several agents that download Network Address Translation (NAT)
information from known NAT gateways.
“Discovering containment information” on page 469
An important principle used by the network model is containment. A container
holds other objects. You can put any object within a container and even mix
different objects within the same container.
“Discovery agents on other protocols” on page 472
Network Manager provides agents that discover devices that use other protocols
than ones previously described.
“Task-specific discovery agents” on page 475
There is a group of discovery agents that are task-specific.
“snmpHelper database” on page 364
The snmpHelper database configures the operation of the SNMP Helper. This
database is defined in NCHOME/etc/precision/DiscoSnmpHelperSchema.cfg.
DiscoTelnetHelperSchema.cfg configuration file:
The DiscoTelnetHelperSchema.cfg configuration file defines the operation of the
Telnet helper, which returns the results of a Telnet operation into a specified
device.
Database tables used
The DiscoTelnetHelperSchema.cfg configuration file can be used to configure
inserts into the following database tables:
v telnetHelper.configuration
v telnetHelper.deviceConfig
Chapter 2. Configuring network discovery
83
You can configure the Telnet helper to use the Secure Shell (SSH) program. SSH
enables authentication and provides more secure communications over the
network.
Sample: configuring the Telnet helper
The following insert can be appended to the DiscoTelnetHelperSchema.cfg
configuration file to configure the operation of the Telnet helper. The insert
configures the Telnet helper to:
v Use 20 threads of process execution
v Wait a maximum of 5000 ms for a reply from a device
v Try the request up to three times
insert into telnetHelper.configuration
(
m_NumThreads,
m_TimeOut,
m_Retries
)
values
(
20,
5000,
3
);
Configuring device-specific settings
The Telnet helper also accepts multiple inserts into the telnetHelper.deviceConfig
table within the DiscoTelnetHelperSchema.cfg configuration file that define the
interaction of the Telnet operation.
The following examples show how to configure Telnet device-specific settings. You
can configure device settings based on the sysObjectID MIB variable or based on IP
or subnet. The most effective way to set these options is based on the sysObjectID
MIB variable. This variable identifies the device vendor. Device-specific
configuration options typically vary with the device vendor. You can configure
values for all Cisco devices, for example, regardless of where these devices are in
the network.
Sample: configuring settings for devices from a specific vendor
The following typical configuration shows how to configure settings for all devices
from a specific vendor. The insert specifies:
v 1.3.6.1.4.1.9.1. as the sysObjectID MIB variable to match for this configuration
entry. All devices with object IDs of the form 1.3.6.1.4.1.9.1.* are matched. In
general, these are Cisco IOS devices, although there are exceptions.
v terminal length is the command that sets the output page length for Cisco
devices.
Note: This command varies with devices of different vendor types.
v No paging
v Prompt from remote device
v The response to send to the remote device for it to continue paged output.
insert into telnetHelper.deviceConfig
(
m_SysObjectId,
84
IBM Tivoli Network Manager IP Edition: Discovery Guide
m_PageLengthCmd,
m_PageLength,
m_ContinueMsg,
m_ContinueCmd
)
values
(
"1.3.6.1.4.1.9.1.", "terminal length", 0, ".*[Mm]ore.*", " "
);
The DiscoTelnetHelperSchema.cfg configuration file contains inserts with default
device-specific configuration settings for the following vendor types:
v Cisco IOS devices
v Cisco Cat OS devices
v Juniper JUNOS devices
v Juniper ERX devices
v Huawei devices
v Dasan devices
Sample: configuring device response settings based on IP address
If the output of the telnet command is longer than one page, the device sends a
message asking whether to display the next page. Configure the messages to be
expected and the responses to be given by the Telnet helper in the
DiscoTelnetHelperSchema.cfg configuration file.
Commands beginning m_Continue (such as m_ContinueMsg) and m_PageLength
(such as m_PageLengthCmd) are mutually exclusive: you must use one or the
other. If these settings are not configured correctly for your devices, data might be
lost.
The following example shows how to configure settings for devices based on the
IP address. The insert specifies:
v 192.168.112.0 as the IP address
v The prompt from the remote device is a regular expression containing "wish to
continue"
v The response to send to the remote device for it to continue paged output is "y"
insert into telnetHelper.deviceConfig
(
m_IpOrSubNet,
m_NetMaskBits,
m_Protocol,
m_ContinueMsg,
m_ContinueCmd
)
values
(
192.168.112.0,
24,
1,
".*wish to continue.*",
"y"
);
Related reference:
Chapter 2. Configuring network discovery
85
“Advanced discovery parameters” on page 46
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
“Discovery agents that discover connectivity among Ethernet switches” on page
455
Discovery agents that discover connectivity information between Ethernet switches
have three main operational stages: gain access to the switch and download all the
switch interfaces; discover VLAN information for the switch; download the
forward database table for the switch.
“Discovering NAT gateways” on page 468
There are several agents that download Network Address Translation (NAT)
information from known NAT gateways.
“Context-sensitive discovery agents” on page 474
There are several agents that take part in a context-sensitive discovery.
“TelnetHelper database” on page 371
The TelnetHelper database defines the operation of the Telnet helper.
DiscoXmlRpcHelperSchema.cfg configuration file:
The DiscoXmlRpcHelperSchema.cfg configuration file can be used to configure the
XML-RPC helper, which enables Network Manager to communicate with EMS
collectors using the XML-RPC interface.
Database table used
The DiscoXmlRpcHelperSchema.cfg configuration file can be used to configure
inserts into the xmlRpcHelper.configuration database table.
This example insert configures the XML-RPC helper to:
v Use one thread of process execution.
v Allow a maximum size of 1048576 bytes for an XML-RPC response.
insert into xmlRpcHelper.configuration
(
m_NumThreads,
m_MaxResponseSize
)
values
(
1, 1048576
);
Note: The default maximum response size might be too small when running a
Collector-based discovery against Collectors that result in very large responses. In
such cases, increase the maximum response size. To increase the maximum
response size, set the m_MaxResponseSize parameter to a higher value. Make sure
you set the same value for m_MaxResponseSize in both of the following files:
v NCHOME/etc/precision/DiscoCollectorFinderSchema.cfg
v NCHOME/etc/precision/DiscoXmlRpcHelperSchema.cfg
Related reference:
“XmlRpcHelper database” on page 375
The XmlRpcHelper helper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
86
IBM Tivoli Network Manager IP Edition: Discovery Guide
SnmpStackSecurityInfo.cfg configuration file:
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
Database tables used
This configuration file can be used to configure inserts into the following database
tables:
v snmpStack.configuration
v snmpStack.verSecurityTable
v snmpStack.accessParameters
Note that there is another configuration file associated with the snmpStack
database, the SnmpStackSchema.cfg file, but you should not need to alter this file.
You can also configure the SNMP Helper to use the GetBulk operation when
SNMP v2 or v3 is used. Use of the GetBulk operation improves discovery speed.
For more information, see the IBM Tivoli Network Manager Entry Edition Installation
and Configuration Guide
Sample: Configuring SNMP versions
If auto-versioning is turned on, the following configuration adjustment specifies
that a community string of ‘public' is used for devices that support SNMP version
1, and specific configuration is used for devices that support SNMP version 3.
Since no value has been specified for m_SnmpPort, this value defaults to the
standard SNMP 161 port.
insert into snmpStack.verSecurityTable
(
m_SNMPVersion,
m_Password,
m_SNMPVer3Level,
m_SNMPVer3Details,
m_SecurityName,
)
values
(
0,
’public’,
2,
{
m_AuthPswd="authpassword",
m_PrivPswd="privpassword"
},
’authPriv’
);
Sample: Defining community strings
The following inserts define the community strings public and crims0n for use to
access SNMP devices.
Chapter 2. Configuring network discovery
87
You can append as many inserts as there are passwords to the
SnmpStackSecurityInfo.cfg configuration file. All password and subnet
configurations are tried until a match is found.
Note: Only one SNMP community string, the public community string, is set up
by default.
insert into snmpStack.verSecurityTable
(
m_SNMPVersion,
m_Password,
m_SNMPVer3Level,
m_SNMPVer3Details,
m_SecurityName
)
values
(
0,
’public’,
2,
{
m_AuthPswd="authpassword",
m_PrivPswd="privpassword"
},
’authPriv’
);
insert into snmpStack.verSecurityTable
(
m_IpOrSubNetVer,
m_NetMaskBitsVer,
m_SNMPVersion,
m_Password,
m_SNMPVer3Level,
m_SNMPVer3Details,
m_SecurityName
)
values
(
"10.10.2.0",
24,
0,
’crims0n’,
2,
{
m_AuthPswd="authpassword",
m_PrivPswd="privpassword"
},
’authPriv’
);
Sample: Specifying an SNMP port
This example configures the same SNMP settings as in the previous example on all
devices within the subnet 192.168.64.0 and specifies the SNMP port as 6161 on all
devices within this subnet.
insert into snmpStack.verSecurityTable
(
m_IpOrSubNetVer,
m_NetMaskBitsVer,
m_SNMPVersion,
m_Password,
m_SNMPVer3Level,
m_SNMPVer3Details,
m_SecurityName,
m_SnmpPort,
88
IBM Tivoli Network Manager IP Edition: Discovery Guide
)
values
(
192.168.64.0,
24,
0,
’public’,
2,
{
m_AuthPswd="authpassword",
m_PrivPswd="privpassword"
},
’authPriv’
6161
);
Related reference:
“Discovery agents that discover connectivity among Ethernet switches” on page
455
Discovery agents that discover connectivity information between Ethernet switches
have three main operational stages: gain access to the switch and download all the
switch interfaces; discover VLAN information for the switch; download the
forward database table for the switch.
“Types of agents” on page 455
The agents supplied with Network Manager can be divided into categories
according to the type of data they retrieve or the technology they discover.
“Connectivity at the layer 3 network layer” on page 460
There are a number of discovery agents that retrieve connectivity information from
OSI model layer 3 (the Network Layer). Layer 3 is responsible for routing,
congestion control, and sending messages between networks.
“Discovering connectivity among ATM devices” on page 464
Asynchronous Transfer Mode (ATM) is an alternative switching protocol for mixed
format data (such as pure data, voice, and video). Several types of discovery
agents can be used to discover ATM devices on a network.
“Discovering NAT gateways” on page 468
There are several agents that download Network Address Translation (NAT)
information from known NAT gateways.
“Discovering containment information” on page 469
An important principle used by the network model is containment. A container
holds other objects. You can put any object within a container and even mix
different objects within the same container.
“Discovery agents on other protocols” on page 472
Network Manager provides agents that discover devices that use other protocols
than ones previously described.
“Task-specific discovery agents” on page 475
There is a group of discovery agents that are task-specific.
“snmpStack database” on page 325
The snmpStack database defines the operation of the SNMP helper.
Chapter 2. Configuring network discovery
89
TelnetStackPasswords.cfg configuration file:
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
You can use the TelnetStackPasswords.cfg configuration file to specify a Secure
Shell (SSH) connection when configuring Telnet device access. SSH enables
password encryption when performing Telnet access. SSH versions 1 and 2 are
supported (restrictions apply in FIPS mode).
Important: SSH within Network Manager currently supports password-based
authentication or no authentication. It does not support RSA signature
authentication.
Database table used
The TelnetStackPasswords.cfg configuration file can be used to configure inserts
into the telnetStack.passwords database table.
Note that there is another configuration file associated with the telnetStack
database, the TelnetStackSchema.cfg file, but you should not need to alter this file.
Sample: Configuring Telnet access parameters for a subnet
The following example insert configures the Telnet access parameters for a subnet.
The insert specifies:
v A subnet address of 192.168.200.0 with a netmask of 25.
v The password and username to use to access the device.
v The password, login and console prompts to expect from the device.
v The devices on this subnet support SSH.
insert into telnetStack.passwords
(
m_IpOrSubNet,
m_NetMaskBits,
m_Password,
m_Username,
m_PwdPrompt,
m_LogPrompt,
m_ConPrompt,
m_SSHSupport
)
values
(
’192.168.200.0’,
25,
’3v3rt0n’,
’user’,
’.*assword:.*’,
’.*ogin.*’,
’.*onsole>.*’,
1
);
Sample: Configuring Telnet access parameters for a device
The following example insert shows how you can configure the access parameters
for a single IP address. The insert specifies:
90
IBM Tivoli Network Manager IP Edition: Discovery Guide
v A single IP address of 172.16.1.21. The address is identified as a single address
by the fact that m_NetMaskBits=32.
v The password and username to use to access the device.
v The password, login and console prompts to expect from the device.
v This device does not support SSH.
insert into telnetStack.passwords
(
m_IpOrSubNet,
m_NetMaskBits,
m_Password,
m_Username,
m_PwdPrompt,
m_LogPrompt,
m_ConPrompt,
m_SSHSupport
)
values
(
’172.16.1.21’,
32,
’’,
’’,
’.*assword.*’,
’.*sername.*’,
’.*Morr.*’,
0
);
Sample: Configuring Telnet device-access for a subnet
The following example insert configures the Telnet access parameters for a subnet.
The insert specifies:
v A subnet address of 192.168.200.0 with a netmask of 25.
v The password and username to use to access the device.
v The password, login and console prompts to expect from the device.
v The devices on this subnet support SSH.
insert into telnetStack.passwords
(
m_IpOrSubNet,
m_NetMaskBits,
m_Password,
m_Username,
m_PwdPrompt,
m_LogPrompt,
m_ConPrompt,
m_SSHSupport
)
values
(
’192.168.200.0’,
25,
’3v3rt0n’,
’user’,
’.*assword:.*’,
’.*ogin.*’,
’.*onsole>.*’,
1
);
Chapter 2. Configuring network discovery
91
Sample: Configuring Telnet device-access for a single IP address
The following example insert shows how you can configure the access parameters
for a single IP address. The insert specifies:
v A single IP address of 172.16.1.21. The address is identified as a single address
by the fact that m_NetMaskBits=32.
v The password and username to use to access the device.
v The password, login and console prompts to expect from the device.
v This device does not support SSH.
insert into telnetStack.passwords
(
m_IpOrSubNet,
m_NetMaskBits,
m_Password,
m_Username,
m_PwdPrompt,
m_LogPrompt,
m_ConPrompt,
m_SSHSupport
)
values
(
’172.16.1.21’,
32,
’’,
’’,
’.*assword.*’,
’.*sername.*’,
’.*Morr.*’,
0
);
Related reference:
“Discovery agents that discover connectivity among Ethernet switches” on page
455
Discovery agents that discover connectivity information between Ethernet switches
have three main operational stages: gain access to the switch and download all the
switch interfaces; discover VLAN information for the switch; download the
forward database table for the switch.
“Types of agents” on page 455
The agents supplied with Network Manager can be divided into categories
according to the type of data they retrieve or the technology they discover.
“Connectivity at the layer 3 network layer” on page 460
There are a number of discovery agents that retrieve connectivity information from
OSI model layer 3 (the Network Layer). Layer 3 is responsible for routing,
congestion control, and sending messages between networks.
“Discovering NAT gateways” on page 468
There are several agents that download Network Address Translation (NAT)
information from known NAT gateways.
“Context-sensitive discovery agents” on page 474
There are several agents that take part in a context-sensitive discovery.
“telnetStack database” on page 329
The telnetStack database defines the Telnet access parameters for devices.
92
IBM Tivoli Network Manager IP Edition: Discovery Guide
Retrieving extra information
You can configure the discovery agents to retrieve extra information from devices
and store this information in the ExtraInfo column of the topology database.
To specify that extra information be retrieved by a given discovery agent, modify
the definition file of the agent ($NCHOME/precision/disco/agents/*.agnt). All
discovery agents have a definition file in the agents directory, regardless of
whether the agent is text-based or precompiled.
The changes that you must make to the agent definition are described in the
following topics.
Changing the agent type:
You can change the agent type in the agent definition file.
At the start of the discovery agent definition file, one of the following types of
agent is identified:
v DiscoCompiledAgent{}: Denotes a compiled discovery agent (with a
corresponding shared library in the $NCHOME/precision/lib directory).
v DiscoDefinedAgent{}: Denotes a text-based discovery agent (with no
corresponding shared library).
v DiscoCombinedAgent{}: Denotes a discovery agent that is a combination of
text-based and precompiled, where extra processing (such as the retrieval of
extra information from devices) is defined in the discovery agent definition file.
To retrieve extra information from devices, the agent type must either be
DiscoDefinedAgent{} or DiscoCombinedAgent{}. Therefore, if you are modifying an
existing compiled agent to retrieve extra information, the first step is to change the
type of agent from DiscoCompiledAgent{} to DiscoCombinedAgent{}.
Mediation and processing layers:
The retrieval of extra information from devices and the addition of the information
to the entity records is conducted in two layers: the mediation and processing
layers. In the mediation layer, the actual SNMP requests to retrieve the variables
are carried out. In the processing layer, the retrieved variables are added to the
appropriate entity records. There is also an optional filter on the mediation layer.
The following code segment is an overview of the structure of the mediation and
processing sections of the discovery agent definition file.
DiscoAgentMediationFilter
{
// Optional section containing filters for the mediation layer.
}
DiscoAgentMediationLayer
{
// Contains the SNMP Get and GetNext requests to be performed.
// In addition, an ICMP trace can be performed and SNMP access
// parameters can be retrieved in the mediation layer.
}
DiscoAgentProcessingLayer
{
// Adds the retrieved variables to the appropriate entity
// record(s).
}
Chapter 2. Configuring network discovery
93
The mediation layer:
The mediation layer is where the SNMP and ICMP requests are performed.
In the following code, the DiscoSnmpGetResponse(); rule performs an SNMP Get
request, and the DiscoSnmpGetNextResponse(); rule performs an SNMP Get Next
request. You can include as many of each type of request as necessary.
You can also include the DiscoSnmpGetAccessParameters(); rule, which retrieves
the SNMP access details for the device, and the DiscoICMPGetTrace(); rule, which
retrieves all the IP addresses in the path to the device.
DiscoAgentMediationLayer
{
DiscoSnmpRequests
{
DiscoSnmpGetResponse( ARGUMENT, VARIABLE );
DiscoSnmpGetNextResponse( ARGUMENT, VARIABLE, );
DiscoSnmpGetAccessParameters( VARIABLE );
}
DiscoICMPRequests
{
DiscoICMPGetTrace( VARIABLE );
}
}
DiscoSnmpGetResponse();:
DiscoSnmpGetResponse(); performs an SNMP Get request. The simple form of this
rule takes two arguments, separated by a comma. The first argument is the key to
assign to the response. This key is used in the processing layer. The second
argument is the OID (Object ID) to retrieve from the device.
The following example retrieves sysUpTime, assigning the key m_SysUpTime to
the value that is returned.
DiscoSnmpGetResponse( "m_SysUpTime", sysUpTime );
A more complex form of DiscoSnmpGetResponse(); takes a third argument, the
OID index. The following example retrieves ifDescr, assigns the key m_IfDescr to
the value returned, and uses the OID index 1.
DiscoSnmpGetResponse( "m_IfDescr", ifDescr, "1" );
DiscoSnmpGetNextResponse();:
DiscoSnmpGetNextResponse(); performs an SNMP GetNext request. This rule takes
the same arguments as DiscoSnmpGetResponse();.
The following example retrieves ipRouteIfIndex and assigns the key
m_IpRouteIfIndex to the value returned.
DiscoSnmpGetNextResponse( "m_IpRouteIfIndex", ipRouteIfIndex );
94
IBM Tivoli Network Manager IP Edition: Discovery Guide
DiscoSnmpGetAccessParameters();:
DiscoSnmpGetAccessParameters(); retrieves the SNMP access parameters for the
device.
If you configure the discovery agent to retrieve the access parameters in the
mediation layer, you must also configure the agent to add the information to the
database record in the processing layer.
DiscoSnmpGetAccessParameters( "m_AccessParam" );
DiscoICMPGetTrace();:
DiscoICMPGetTrace(); retrieves the IP addresses in the path to the device.
If you configure the discovery agent to retrieve the path to the device in the
mediation layer, you must also configure the agent to add the information to the
database record in the processing layer.
DiscoICMPGetTrace( "m_Trace" );
Mediation layer filter:
The mediation layer filter is an optional filter that restricts the SNMP requests for
extra information to specific devices. You can include a condition within the
DiscoMediationSnmpGetFilter{} section within the DiscoAgentMediationFilter{},
that only devices passing the filter are processed by the agent.
The following example ensures that only devices with an ipForwarding value of 1
are processed.
DiscoAgentMediationFilter
{
DiscoMediationSnmpGetFilter
{
"ipForwarding" = 1 ;
}
}
The processing layer:
The processing layer is where the retrieved information is added to the entity
records. Both the DiscoAgentProcLayerAddTags{} and
DiscoAgentProcLayerAddLocalTags{} sections are optional. However, if both
sections are omitted, no extra information is stored in the database records.
The structure of the processing layer is shown below.
DiscoAgentProcessingLayer
{
DiscoAgentProcLayerAddTags
{
DiscoAddTagSnmpGet( KEY );
DiscoAddTagSnmpGetNext( KEY );
DiscoAddTagSnmpGetAccessParameters( "m_AccessParam" );
DiscoAddTagTrace( "m_Trace" );
}
DiscoAgentProcLayerAddLocalTags
{
DiscoAddTagSnmpGet(
TAG FROM KEY WHERE CONDITION );
Chapter 2. Configuring network discovery
95
DiscoAddTagSnmpGetNext(
TAG FROM KEY WHERE CONDITION );
}
}
DiscoAgentProcLayerAddTags{}:
Within the DiscoAgentProcLayerAddTags{} section, you can include as many
DiscoAddTagSnmpGet(); or DiscoAddTagSnmpGetNext(); rules as necessary. These
rules add the retrieved variable to the database record for the discovered entity.
Each rule within the DiscoAgentProcLayerAddTags{} section takes a single
argument, which is the key assigned to the retrieved variable in the mediation
layer. The following example adds the value of m_SysUpTime, retrieved in the
mediation layer, to the entity record.
DiscoAddTagSnmpGet( "m_SysUpTime" );
If you configured the discovery agent to retrieve either the SNMP access
parameters or the path to the device during the mediation layer, you must include
either the DiscoAddTagSnmpGetAccessParameters(); or the DiscoAddTagTrace();
rule in the DiscoAgentProcLayerAddTags{} section to ensure that the retrieved
information is added to the MODEL database.
DiscoAgentProcLayerAddLocalTags{}:
Within the DiscoAgentProcLayerAddLocalTags{} section, you can include as many
DiscoAddTagSnmpGet(); or DiscoAddTagSnmpGetNext(); rules as necessary. These
rules add the retrieved variable to the database record for a local neighbor.
The structure of the rules is:
DiscoAddTagSnmpGet( TAG FROM KEY WHERE CONDITION );
DiscoAddTagSnmpGetNext( TAG FROM KEY WHERE CONDITION );
The arguments that determine the local neighbor to which the tag is added are:
v TAG specifies the field name of the tag to be added.
v KEY indicates the key assigned to the value returned in the mediation layer.
v CONDITION indicates a condition that determines whether or not the tag is
added.
The following example adds a field called m_IfDescr to the local neighbor object
(using the value returned in the mediation layer that was assigned the key
m_IfDescr) where m_IfIndex=1.
DiscoAddTagSnmpGet( "m_IfDescr" FROM "m_IfDescr"
WHERE ( "m_IfIndex" = "1" )
);
The following example adds a field called m_IfType to the local neighbor object
using the list of values returned by the GetNext request performed in the
mediation layer and assigned the key m_IfType. The WHERE clause indicates the
particular value required from the list of data. The value is retrieved by looking for
the entry where the value of the m_IfIndex field in the local neighbor object is
equal to SNMPINDEX(0), that is, the first value of the SNMP table entry.
DiscoAddTagSnmpGetNext( "m_IfType" FROM "m_IfType"
WHERE ( "m_IfIndex" = SNMPINDEX(0) )
);
96
IBM Tivoli Network Manager IP Edition: Discovery Guide
Configuring trap forwarding
The SNMP trap multiplexer, the ncp_trapmux process, listens to a single port and
forwards all the traps it receives to a set of host/socket pairs.
Restriction: The SNMP trap multiplexer does not forward SNMPv3 Inform
messages.
About trap management:
Trap management enables you to ensure that traps received from network devices
are forwarded to ports where they can be handled by Network Manager and other
network management systems.
In most networks, traps arrive on a single default port (usually port 162). This can
cause problems if you have Network Manager and another network management
system installed on the same server. Both of these systems might need to listen for
traps; however, only one process can bind to one port at a time.
The SNMP Trap Multiplexer is a Network Manager process that resolves this
problem: it listens to a single port and forwards all the traps it receives to a set of
host/socket pairs.
By default, the SNMP Trap Multiplexer listens for traps on port 162, but you can
change this by inserting an alternative port number into the trapMux.config
database table.
The ncp_trapmux process can also store trap events in a binary format file
(containing trap and timing information) that can be used to recreate the trap
events in the order they occurred at a later date. This is useful mainly for
debugging purposes.
Starting the SNMP trap multiplexer:
Although it is good practice to ensure that the ncp_ctrl process is configured to
launch and manage the SNMP Trap Multiplexer, you can also start it manually.
To start the ncp_trapmux process, use the following command:
ncp_trapmux -domain DOMAIN_NAME
Forwarding traps:
Using the SNMP Trap Multiplexer, you can forward traps to one or more servers.
To configure the SNMP Trap Multiplexer to forward traps to network management
systems running on host1 and host2:
1. Edit the schema file, $NCHOME/etc/precision/TrapMuxSchema.cfg, to contain a
set of host/socket pairs. For example, append the following lines to the file:
insert into trapMux.sinkHosts (host, port) values ("host1", 5999);
insert into trapMux.sinkHosts (host, port) values ("host2", 5999);
2. Start the SNMP Trap Multiplexer using the following commands:
ncp_trapmux -domain DOMAIN1
ncp_trapmux -domain DOMAIN2
In the above example, when a trap is sent to the server that is running the
ncp_trapmux process, it is forwarded to test-host1, port 5999 and test-host2, port
Chapter 2. Configuring network discovery
97
5999.
Starting trap capture:
You can start capturing traps by inserting commands into the SNMP Trap
Multiplexer database.
To instruct the SNMP Trap Multiplexer to start capturing traps:
1. Log into the TrapMux service using the OQL Service Provider or the
Management Database Access page.
2. Issue the following commands:
insert into trapMux.command
(command) values( "capture_start" );
go
Stopping trap capture:
You can stop capturing traps by inserting commands into the SNMP Trap
Multiplexer database.
To instruct the SNMP Trap Multiplexer to stop capturing traps:
1. Log into the TrapMux service using the OQL Service Provider or the
Management Database Access page.
2. Issue the following commands:
insert into trapMux.command
(command) values( "capture_stop" );
go
Printing traps to a file:
You can print traps to a file by inserting commands into the SNMP Trap
Multiplexer database.
To instruct ncp_trapmux to print traps:
1. Log into the TrapMux service using the OQL Service Provider or the
Management Database Access page.
2. Issue the following commands:
insert into trapMux.command
(command, fileName) values( "print", FILENAME );
go
Where FILENAME specifies the file to which the output is written. If the file is not
specified, $NCHOME/etc/precision/trapmux.out is used.
Replaying traps from a file:
If you have created a text-readable file for traps, you can use the ncp_trapmux
process to recreate the trap events in the order specified in this file.
The ncp_trapmux process can replay traps using a binary file or a human-readable
file, however, the ncp_trapmux process can only generate binary files.
To instruct ncp_trapmux to replay traps from a file:
1. Log into the TrapMux service using the OQL Service Provider or the
Management Database Access page.
98
IBM Tivoli Network Manager IP Edition: Discovery Guide
2. Issue the following commands:
insert into trapMux.command
(command, fileName) values( "replay", "trapmux.out" );
go
SNMP trap multiplexer commands:
You can issue commands to the SNMP trap multiplexer, the ncp_trapmux process,
to control its operation.
The commands used to control the ncp_trapmux process are described in the
following table:
Table 4. Commands used to control the ncp_trapmux process
Command
Function and Default Filename
capture_start
Begin logging traps to memory. The default filename is NULL (not
required).
capture_stop
Stop logging traps to memory. The default filename is NULL (not
required).
capture_continue
Continue logging traps to memory. The default filename is NULL
(not required).
capture_empty
Clear memory of all currently logged traps. The default filename is
NULL (not required).
rehash
Shut down the ncp_trapmux process and clear all memory. The
daemon then rereads the configuration file and starts up again.
The default filename is NULL (not required).
restart
Set the daemon to normal mode. The default filename is NULL
(not required).
replay
Either read the traps in memory or read the raw trap packet
information in the specified file and replay the traps with a small
delay between each. The default filename is NULL (play from
memory).
replay timed
Either read the traps in memory or read the raw trap packet
information in the specified file and replay the traps in the order
of the time they were received with the same delays between
traps. The default filename is NULL (play from memory).
print
Print the current traps in memory in a non-readable format to the
specified file. Time information is encoded with the trap. The
default filename is $NCHOME/etc/precision/trapmux.out.
Filtering SNMP information from devices
You can filter out SNMP information when devices are queried by the SNMP
helper by configuring inserts into the SNMP helper database.
Related reference:
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
“snmpHelper.instanceFilter database table” on page 366
The snmpHelper.instanceFilter database table configures SNMP interface filters for
the SNMP helper.
“DiscoSnmpHelperFilters.cfg configuration file” on page 82
The DiscoSnmpHelperFilters.cfg configuration file defines SNMP interface filters
for the SNMP Helper. SNMP interface filters define the interfaces for which you
Chapter 2. Configuring network discovery
99
want the SNMP Helper to retrieve information.
SNMP interface filtering:
You can filter the SNMP data retrieved from devices by the discovery process by
configuring SNMP interface filters. You can configure SNMP interface filters only
on the command line.
Why use SNMP interface filtering
Sometimes a device or a class of devices returns too much MIB data. For example,
if virtual devices have a large number of interfaces, discovering them can take a
long time. In order to speed up discovery of such devices, you can use SNMP
interface filters to reduce the number of interfaces that are retrieved by the SNMP
helper.
How SNMP interface filtering works
When discovery agents, Perl scripts, or the SNMP MIB Browser request SNMP
information, the SNMP helper retrieves the information from network devices.
SNMP interface filters define rows in MIB tables that the SNMP helper retrieves.
The SNMP helper retrieves a subset of the information that would have been
returned without a filter, and sends it to the process that requested the SNMP
information. SNMP interface filters can also define entire tables that are not to be
retrieved by the SNMP Helper.
SNMP interface filters are only applied to requests for full walks of MIB tables.
SNMP Get or GetNext requests for specific interfaces within a MIB table are not
filtered.
The devices that should have the filter applied to them are defined in the device
filter. If a device filter is defined, any request for SNMP information for a device is
first checked against the device filter. Only devices which pass the filter are then
checked for interface filtering.
The filter can filter on multiple rows of a table. The first time that a filtered table is
accessed, one or more columns in the table are walked. All subsequent requests for
SNMP walks of that table return only interfaces that match the filter.
Including multiple tables with dependent filters
You can also define dependent filters. If an SNMP interface filter Filter 1 is defined
on Table A, then a second, dependent filter Filter 2 can be defined on Table B.
SNMP information in Table B that relates to the same interface is also retrieved.
In order to define a dependent filter, in addition to a filter being defined on Table
A, one or more of the following conditions must be true:
v Table A and Table B have equivalent indexes.
v The index of Table A is a value in Table B.
If Table A and Table B have exactly the same index, then you do not need to define
a dependent filter. Information from Table B is automatically retrieved according to
the filter defined on Table A.
100
IBM Tivoli Network Manager IP Edition: Discovery Guide
When you can use SNMP interface filtering
You can use SNMP interface filtering on any SNMP MIB table that is keyed on
ifIndex. For example, you filtering on ifTable or ifXTable allows filtering on values
such as ifType and ifDescr.
Restriction: Filtering on any SNMP MIB variable other than interfaces is not
supported. You can, however, block access to any table using the
m_InstanceFilterTable option.
The following example extract shows the definition for the ipAddrTable from the
NCHOME/precision/mibs/RFC1213.mib file:
-- the IP address table
-- The IP address table contains this entity’s IP addressing
-- information.
ipAddrTable OBJECT-TYPE
SYNTAX SEQUENCE OF IpAddrEntry
ACCESS not-accessible
STATUS mandatory
DESCRIPTION
"The table of addressing information relevant to
this entity’s IP addresses."
::= { ip 20 }
The syntax "SEQUENCE OF" defines this as a table. You can find out what tables
are defined in the MIB by searching for this string. The following example shows
the output of a search run on UNIX:
% grep ’SEQUENCE OF’
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
SYNTAX
RFC1213.mib
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
SEQUENCE OF
IfEntry
AtEntry
IpAddrEntry
IpRouteEntry
IpNetToMediaEntry
TcpConnEntry
UdpEntry
EgpNeighEntry
For more information about how to configure SNMP interface filters, see “SNMP
interface filtering” on page 16,
Configuring SNMP interface filters:
You can configure one or more interface filters per device type.
To configure one or more interface filters, complete the following steps:
1. Ensure that the Entity agent is enabled. You can enable the Entity agent in the
Discovery Configuration GUI.
2. Back up and edit the following file: NCHOME/etc/precision/
DiscoSnmpHelperFilters.DOMAIN_NAME.cfg
3. Specify an insert in the snmpHelper.instanceFilter table. You can use the
examples given later in this procedure or copy another example insert from
this documentation.
4. Give this filter a name. Locate the value of m_FilterName and give the filter a
descriptive name, enclosed in double quotes.
5. Configure which devices should have this interface filter applied to them by
defining a device filter. Locate the value of m_DeviceFilter and define a filter,
Chapter 2. Configuring network discovery
101
enclosed in double quotes. You can use any Object Identifiers (OIDs) to
construct the filter. Use Object Query Language (OQL) syntax.
The filter must be in the following form:
mibVariableName expression values
[ optional_Boolean_operator expression optional_Boolean_operator .. ]
For example, the following are all valid filters:
// Apply the interface filter to only a specific type of device
sysObjectID = ’1.3.6.1.4.1.4874.1.1.1.1.3’
// More complex example of the above
sysObjectID = ’1.3.6.1.4.1.4874.1.1.1.1.3’ OR sysDescr LIKE ’ERX-1440’
// Apply the interface filter only to devices in certain locations
sysLocation in ( ’location1’, ’location2’ )
//Apply the interface filter to all types of device.
sysObjectID != ’’
6. Define the SNMP interface filter expression to be applied to the MIB tables.
Only rows that match this filter, that is, for which this expression evaluates
true, are retrieved. Locate the value of m_InstanceFilter and define a filter,
enclosed in double quotes. You can use any Object Identifiers (OIDs) to
construct the filter. Use Object Query Language (OQL) syntax. You can define
more than one interface filter per named filter.
The filter must be in the following form:
mibVariableName expression values
[ optional_Boolean_operator expression optional_Boolean_operator .. ]
For example, the following are all valid filters:
// Only interfaces with names like this are returned
ifName like ’Gi0’
// This filter is against 2 distinct tables (ifTable and ifXTable)
with the requirement that these share a common index (ifIndex)
ifName like ’Gi0’ or ifDescr like ’FastEthernet’
// Filter out interfaces of these types
ifType not in ( 1, 53, 166 )
7. Optional: If you want to filter out information that relates to the same
interface in related MIB tables that are not explicitly defined with the same
index, specify which tables to include using a dependent filter. Copy and edit a
default insert into the snmpFilter.dependentInstances table from the
NCHOME/etc/precision/DiscoSnmpHelperFilters.DOMAIN_NAME.cfg file or copy
an example insert from this documentation.
The syntax of the filter is
MIB_variable_name in
(eval(list_type,’&MIB_table.MIB_entry’))
where MIB_variable_name must exist in MIB_table, and a filter on MIB_table has
been defined in the snmpHelper.instanceFilter table.
8. Run the following command to instruct the SNMP helper, ncp_dh_snmp, to
re-read its configuration files:
kill -HUP PID
9. You can configure more than one SNMP interface filter in the
NCHOMENCHOME/etc/precision/DiscoSnmpHelperFilters.DOMAIN_NAME.cfg file. If
more than one interface filter is configured, a table row that matches any filter
is retrieved.
102
IBM Tivoli Network Manager IP Edition: Discovery Guide
10. If one or more interface filters are configured, ensure that the the
RaiseAlertsForUnknownInterfaces property in the NCHOME/etc/precision/
NcPollerSchema.cfg file is set to 0. This setting ensures that alerts are not
raised against interfaces that were not discovered, for example, because they
were filtered out of the discovery by interface filters.
Example simple interface filter
The following example retrieves information for interfaces with a name like "Gi0"
on a specific kind of device.
insert into snmpHelper.instanceFilter
(
m_FilterName,
m_DeviceFilter,
m_InstanceFilter
)
values
(
"TESTFILTER",
"sysObjectID = ’1.3.6.1.4.1.4874.1.1.1.1.3’ OR sysDescr LIKE ’ERX-1440’",
"ifName like ’Gi0’"
);
Example dependent SNMP interface filter:
You can create dependent filters that use the results of previous filters to filter
additional tables.
In the following example, the ipNetToMediaTable is indexed on
ipNetToMediaIfIndex, which is equivalent to ifIndex. The ifTable table is also
indexed on ifIndex. This relationship is written into the MIB definition, but cannot
be programmatically determined. Entering the relationship as a dependent filter
ensures that matching entries in the ipNetToMediaTable are also included.
insert into snmpHelper.dependentInstanceFilter
(
m_InstanceFilter
)
values
(
"ipNetToMediaIfIndex in ( eval(list type int, ’&ifTable.ifEntry’) )"
)
;
In the following example, the ipAddrTable is indexed on IP address, but each row
contains ipAdEntIfIndex, whose value is equivalent to ifIndex. The ifTable table is
also indexed on ifIndex. This relationship is written into the MIB definition, but
cannot be programmatically determined. Entering the relationship as a dependent
filter ensures that matching entries in the ipAddrTable are also included.
insert into snmpHelper.dependentInstanceFilter
(
m_InstanceFilter
)
values
(
"ipAdEntIfIndex in ( eval(list type int, ’&ifTable.ifEntry’) )"
)
;
Chapter 2. Configuring network discovery
103
Both these example filters return rows that match the filter. If a row in the MIB
table does not have a valid value, it is not retrieved. For example, if a row in the
ipAddrTable table does not contain a valid value for ipAdEntIfIndex, it is not
retrieved by the SNMP helper.
Both these example filters rely on an interface filter already being defined on
ifIndex. The matching results from the ipAddrTable and ipNetToMediaTable tables
are cached, so that the MIB is not queried again.
Both of the above filters are configured by default.
Related reference:
“snmpHelper.dependentInstanceFilter database table” on page 365
The snmpHelper.dependentInstanceFilter database table is used to define interface
filters that depend on other filters.
Configuring specialized discoveries
You can configure the system to perform more complex discoveries, such as MPLS
and NAT discovery.
Specialized discoveries include the following:
EMS discoveries
Collects topology data from Element Management Systems and integrates
this data into the discovered topology.
MPLS discoveries
Discovers layer 3 VPNs and enhanced layer 2 VPNs running across MPLS
core networks.
NAT discoveries
Discovers NAT gateway devices thereby enables you to retrieve data on
devices in private address spaces.
Configuring a context-sensitive discovery
If you need to discover devices that support multiple contexts, you must run a
context-sensitive discovery. For example, a device that uses separate SNMP
contexts to provide access to its virtual routers. Context-sensitive discovery ensures
correct representation of context-accessible virtual devicess. Always check that your
particular device type is supported for discovery.
In a context-sensitive discovery, information about a device is passed from the
returns table of the Details agent to the despatch table of the relevant Context
agent.
The Context agents use the filters in the files with an extension of .agnt to
determine which devices to process. This is true for all discovery agents. If the
device is not of a type which supports context-accessible virtual devices, that is,
does not need context-sensitive processing, it is passed directly to the Associated
Address agent.
Attention: Enabling a context-sensitive discovery automatically enables all the
Context agents. Disabling a context-sensitive discovery automatically disables all
the Context agents. Do not manually enable or disable Context agents, either
through the configuration files or through the Discovery Configuration GUI.
104
IBM Tivoli Network Manager IP Edition: Discovery Guide
To enable a context-sensitive discovery, append the following insert to the
DiscoConfig.cfg file:
insert into disco.config
(
m_UseContext
)
values
(
1
)
Inserting the value 0 disables the context-sensitive discovery.
Related concepts:
“Discovering device details (context-sensitive)” on page 433
The discovery of context-sensitive device details is carried out in several steps.
Related reference:
“Context-sensitive discovery agents” on page 474
There are several agents that take part in a context-sensitive discovery.
Configuring EMS discoveries
You can configure Network Manager to collect topology data from Element
Management Systems (EMS) and integrate this data into the discovered topology.
The following topics describe how to configure an EMS discovery.
For an overview of how Network Manager collects topology data from Element
Management Systems (EMSs) and integrates this data into the discovered topology,
see the IBM Tivoli Network Manager IP Edition Product Overview.
Related concepts:
“Discovery process with EMS integration” on page 439
Network Manager collects topology data from an EMS using collectors.
Related information:
Service Management Connect blogs
For related SMC blog entries, click here.
About EMS integration
The Network Manager EMS integration enables Network Manager to collect
topology data from Element Management Systems.
About collectors:
A collector is a software module that retrieves topology data from a data source,
such as an Element Management System (EMS) or a comma-separated value (CSV)
file, and makes this data available to the discovery process as a set of XML data.
Network Manager can then stitch this data into the discovered topology.
A collector translates the topology data from the format in which it is held in the
proprietary EMS into a standard XML structure that can be processed by Network
Manager. This means that a different collector must be developed for each different
EMS vendor and model. The predefined collectors provided with Network
Manager are written in either Java™ or Perl. However, collectors may be written in
any language, as long as that language can provide an XML-RPC server which the
ncp_disco process can query. Network Manager ships with Java and Perl modules
to support the development of collectors in those languages.
Chapter 2. Configuring network discovery
105
Collectors can run on the same host as the Network Manager. Collectors can also
run on a separate host.
All interaction between Network Manager and the collectors is conducted using
XML, and this interaction occurs over an XML-RPC interface.
Predefined collectors:
Network Manager ships with a set of default collectors that retrieve device data
from a variety of EMSs, including EMSs that manage radio access network (RAN)
and Optical devices.
Scripts and a plain-text configuration file for each collector are held in separate
directories named after the collector, within the $NCHOME/precision/collectors/
directory, as follows:
v Collectors written in Java are stored in the $NCHOME/precision/collectors/
javaCollectors/ directory.
v Collectors written in Perl are stored in the $NCHOME/precision/collectors/
perlCollectors/ directory.
For example, the CiscoLMS collector is stored in the directory
javaCollectors/CiscoLMS/, and the AlcatelNR8PLIooIsn collector is stored in the
perlCollectors/ AlcatelNR8PLIooIsn/ directory.
Each collector supplied with Network Manager downloads data from an EMS
using a Northbound Interface (NBI) protocol or uses data downloaded from the
EMS by the user. Each EMS manages devices that support certain technologies.
The default collectors are listed in the tables that follow:
Table 5. Default Java collectors
Collector
Description
Nokia5529Idm
Collector for the Nokia5529Idm EMS. SOAP
This Java collector retrieves the same
information as the Perl Nokia5529Idm
collector, and it additionally supports
the Bulk Network Export feature and
supports the Java Message Service
(JMS). The collector listens for JMS
notifications about entities that have
been added or removed from the
EMS. The collector pauses and then
rediscovers the EMS. During the next
discovery or partial discovery, the
NCIM topology database is updated
with the latest data from the collector.
106
IBM Tivoli Network Manager IP Edition: Discovery Guide
NBI Protocols
Technologies
Interface Inventory,
Physical Entity
Table 5. Default Java collectors (continued)
Collector
Description
NBI Protocols
Technologies
Alcatel5620Sam
Collector for the Alcatel 5620 SAM
EMS. This Java collector retrieves the
same information as the Perl
Alcatel5620SamSoapFindToFile
collector, and additionally supports
High Availability (HA) notifications,
Link Aggregation Group (LAG)
information, and Java Message
Service (JMS) subscriptions to device
inventory and layer 2 link changes.
SOAP
Long Term Evolution
(LTE), LAG, OSI Layer 2,
OSI Layer 3, Interface,
Inventory, Physical
Entity, VPN Layer 3 and
VPN Layer 2
JSON and XML over
REST WebSocket
protocol
Interface Inventory,
Physical Entity
In supporting the SAM 5620 High
Availability feature, the collector waits
for JMS notification that indicates a
loss of connection to the SAM 5630
primary server. The collector pauses
to allow time for the backup server to
become the primary server, and
attempts to reconnect to the primary
server. If after four reconnection
attempts the primary server is still
not available, the collector exits.
The collector retrieves LAG
containment data, which is modelled
and presented in the Structure
Browser.
The collector retrieves VLAN interface
information.
The collector retrieves address and
subnet information for ENodeB
elements, creates VLAN information
based on that information, and
mdoels Ethernet ports and control
boards.
The collector listens for JMS
notifications about device inventory
changes, where devices are added or
removed, and saves the device ID.
During the next user-triggered partial
discovery of the device, the collector
performs a SAM 5620 discovery
against only the devices that contain
the changes. For Layer 2 link changes,
the collector performs a Layer 2
discovery for all devices.
Starting from V4.2 FixPack 1,
LTE-related discovery data for the
SAM 5620 EMS is no longer
supported for Network Manager
partial discovery.
Cisco APIC REST
Collector for the Cisco Application
Policy Infrastructure Controller
(APIC) EMS.
Chapter 2. Configuring network discovery
107
Table 5. Default Java collectors (continued)
Collector
Description
NBI Protocols
Technologies
CiscoLMS
Collector for the CiscoWorks LMS
EMS. This collector uses the Cisco
Open Database Schema and Cisco
Data Extraction Engine to
communicate with the EMS.
JDBC and REST Web
services
Physical Entity, Interface
Inventory
csv
Generic CSV-based collector that
reads .csv files for input data. There
is a GenericCsv collector written in
Java, and a second GenericCsv
collector written in Perl.
N/A
Various
Huawei CORBA TMF
814
Collector for the Huawei CORBA
TMF 814 EMS. This collector collects
information from EMS systems that
use the CORBA TMF 814 interface,
such as Huawei T2000 and U2000.
CORBA TMF814
OSI Layer 1, Interface
Inventory, Physical
Entity, SONET, SDH
Huawei M2000
Collector for the Huawei M2000 EMS. N/A
This collector processes LTE 3G, 2G,
PSCore, and CSCore data by using
the configuration management XML
files generated from a Huawei M2000
EMS.
LTE - eNodeB , NodeB,
BTS, RNC, BSC, MGW,
UGW, USN, HIR, EIR,
HSS, CGNE, MSS
Place the XML files in a local
directory for access by the collector.
The Huawei M2000 EMS can produce
many different kinds of XML files.
This collector specifically supports the
following XML files:
v LNBI_XML_RT_*.xml
v SRANNBIExport_
XML_LTE_RT_*.xml
v CMExport_*.xml
v GNBIExport_XML_RT_*.xml
v UNBIExport_XML_RT_*.xml
The collector also processes any
available IM*.xml, AIM_*.xml and
W_OMC_*.xml files to supplement
the data from the XML files above.
MTOSISoap
108
Generic collector that discovers
MTOSI SOAP
Element Management Systems that
support the MTOSI Soap NBI, for
example, the Huawei U2000 iManager
EMS. Supported technologies: Layer 2
discovery, Layer 3 discovery, and
Physical Inventory discovery.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Physical Inventory, Layer
2, Layer 3
Table 5. Default Java collectors (continued)
Collector
Description
NBI Protocols
Technologies
NetActCMDump
Processes 2G, 3G and LTE RAN data
by using the configuration
management XML file for the NetAct
EMS collector. The collector needs to
connect to the NetAct EMS collector
in order to retrieve this XML file, and
it does this using either FTP or SFTP.
FTP or SFTP
LTE, RAN, SGSN,
eNodeB, MME, PGW,
BTS, RNC, SGW, BSC,
NodeB, MGW, TRX,
MSC, PCU
In order to use data from the NetAct
XML Interface for Configuration
Management collector in a network
discovery, you must configure the
collector properties file with the FTP
and SFTP connection details between
the NetAct EMS and Network
Manager.
NetViewer
Collector for the Nokia Solutions and
Networks (NSN) NetViewer EMS.
CORBA TMF814
OSI Layer 1, Interface
Inventory, Physical
Entity, SONET, SDH
Tellabs INM8000
Collector for the Tellabs INM8000
EMS.
Java API
OSI Layer 3, OSI Layer
2, Interface Inventory,
Physical Entity
Table 6. Default Perl collectors
Collector
Description
NBI Protocols
Technologies
Nokia5529Idm
Collector for the
Nokia5529Idm EMS.
SOAP
Interface Inventory,
Physical Entity
Alcatel5620SamSoap
Collector for the Alcatel
5620 SAM EMS.
SOAP
OSI Layer 2, OSI Layer 3,
Interface Inventory,
Physical Entity, VPN Layer
3, VPN Layer 2
Alcatel5620SamSoap
FindToFile
Collector for the Alcatel
5620 SAM EMS. The
collector retrieves the same
data as the
Alcatel5620SamSoap
FindToFile collector.
SOAP, FTP
LTE, OSI Layer 2, OSI
Layer 3, Interface Inventory,
PCRF, SGW, PGW, MME,
eNodeB, Physical Entity,
VPN Layer 3, VPN Layer 2
N/A
Interface Inventory,
Physical Entity
The collector stores the data
from the EMS in XML files
with the same name as the
objects queried. The
collector transfers the XML
files to the Network
Manager using FTP. You
must configure the FTP
connection details before
running the collector.
Alcatel5620SamCsv
Collector for the Alcatel
5620 SAM EMS. This
collector retrieves EMS
topology data from a CSV
dump of the Alcatel 5620
SAM EMS.
Chapter 2. Configuring network discovery
109
Table 6. Default Perl collectors (continued)
Collector
Description
NBI Protocols
Technologies
AlcatelNR8PLIooIsn
Collector for the Alcatel
Lucent 1353 NM and
Alcatel Lucent 1354 RM
components within the
AlcatelNR8PL EMS.
IOO (for the Alcatel Lucent 1353 NM, 1354 RM
1353 component), ISN (for
the Alcatel Lucent 1354 RM
component)
GenericCsv collector
Generic CSV-based collector N/A
that reads .csv files for
input data. There is a
GenericCsv collector
written in Java, and a
second GenericCsv collector
written in Perl.
Inventory
HuaweiU2000ImanagerTL1
Collector for the
HuaweiU2000Imanager
EMS.
TL1
Physical Entity, Interface
Inventory
HuaweiU2000iManager
TL1DumpExport
Collector for the
HuaweiU2000Imanager
EMS. This collector uses
XML files from the EMS.
N/A
Physical Entity, Interface
Inventory
OpticalBlackboxXml
Blackbox collector that
enables you to add passive
layer 1 entities to the
discovered network
topology.
N/A
Physical Entity, Interface,
Layer 1
Related tasks:
“Configuring an EMS discovery” on page 113
Configure an EMS discovery to collect topology data from Element Management
Systems and integrate this data into the discovered topology.
Other components of the EMS integration:
In addition to collectors, EMS integration is composed of several components that
assist in the collection of topology data.
The components of the EMS integration are described in Table 7.
Table 7. Components of EMS integration
Component
Description
Collector finder
The Collector finder reads the collector host seeds from
a seed table in the collectorFinder database. It then
queries the collectors specified in this table to get a list
of devices managed by the EMS associated with each
collector.
ncp_df_collector
110
Collector agents
Retrieve basic and detailed information about the
devices on the collector. Each agent makes use of the
Collector helper to retrieve this information.
CollectorDetails agent
Retrieves basic information about the devices on the
collector, including sysObjectId, sysDescr, and naming
data.
CollectorInventory agent
Retrieves local neighbor, entity and associated address
data for each of the devices on the collector.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 7. Components of EMS integration (continued)
Component
Description
CollectorLayer1 agent
Retrieves layer 1 and microwave connectivity
information for the devices on the collector.
CollectorLayer2 agent
Retrieves layer 2 connectivity information for the
devices on the collector.
CollectorLayer3 agent
Retrieves layer 3 connectivity information for the
devices on the collector.
CollectorLTE agent
Retrieves LTE-specific entity information for the
devices on the collector.
CollectorRan agent
Retrieves radio access network (RAN) information for
the devices on the collector.
CollectorVpn agent
Retrieves layer 2 and layer 3 VPN data for the devices
on the collector.
Collector helper
Enables Network Manager to communicate with the
collectors using the XML-RPC interface.
ncp_dh_xmlrpc
Related reference:
“Topology data stored in an EMS” on page 464
There are several discovery agents that retrieve information about devices
managed by an EMS.
EMS discovery data flow:
Use this information to understand the steps in an EMS discovery.
Standard EMS discovery data flow:
Use this information to understand how Network Manager collects topology data
from an EMS as part of a discovery or partial discovery.
The table below shows the steps involved in collecting topology data from EMS as
part of a discovery or partial discovery. After this data has been collected, Network
Manager stitches it together with the topology.
Table 8. Collecting topology data from EMS during discovery
Step
Data Flow
1
Using the Collector finder, the discovery system queries the collector to obtain a
list of devices managed by the EMS. In the case of a partial discovery, the
discovery might query for a single device or subnet only.
2
The Collector queries the EMS for the list of devices.
3
The EMS responds with list of managed devices.
4
The Collector responds by providing the list of devices.
Chapter 2. Configuring network discovery
111
Table 8. Collecting topology data from EMS during discovery (continued)
Step
5
Data Flow
Using a number of specialized collector discovery agents at different times during
the discovery, the discovery system queries the collector for basic and detailed
information about each of the devices in the list. Detailed information requested
includes the following:
v Inventory information.
v Layer 1 and microwave connection details.
v Layer 2 connection details.
v Layer 3 connection details.
v LTE information.
v Radio access network (RAN) information.
v VPN information.
6
The Collector responds by providing basic and detailed information as this is
requested.
Synchronization for multiple data sources:
If you run a discovery that includes collector and SNMP data sources, or multiple
collectors, you must synchronize the "Interrogating Devices" phase (phase 1) of the
discovery across all of the data sources. Synchronization of phase 1 reduces the
likelihood of excessive discovery cycling and ensures that the maximum amount of
data is available during topology building. Synchronization capability is provided
by the m_WaitForManagedProcs configuration setting. m_WaitForManagedProcs is set
to 0 (off) by default, which is more suited to SNMP-only discoveries.
During phase 1 of an IP discovery, discovery waits by default up to 90 seconds
between the discovery of one device and the next. If no further devices are found
after 90 seconds, then the discovery moves into phase 2. This time delay is
controlled by the m_NothngFndPeriod field in the disco.config discovery database
table, and is ideal for SNMP discoveries in which entities do not all respond at the
same time.
However, the behavior of collectors is different than SNMP. Collectors return all of
their devices in one go, potentially after a comparatively long initial delay, during
which the EMS is queried. Using only m_NothngFndPeriod when multiple collectors
or collector and SNMP discoveries are run under the same domain can lead to
undesired multiple discovery cycles. This effect happens because the interrogation
phase delay between each collector can be far in excess of 90 seconds. This delay
causes the discovery to continue to the next phase if the SNMP ping phase
completed.
To ensure that data from all collectors in a multiple data source discovery is
collected and stitched together in the same discovery cycle, you must configure the
following fields in the disco.config discovery database table:
m_WaitForManagedProcs
Set this field to 1. This setting ensures that the discovery process remains
in phase 1 until all the collectors finish processing data on their respective
EMSs.
By default this field is set to 0. This setting means that when the first
collector completes data processing and the number of seconds defined in
112
IBM Tivoli Network Manager IP Edition: Discovery Guide
the m_NothngFndPeriod field pass, then the discovery process moves to
phase 2 without waiting for the other collectors to start processing.
m_ManagedWaitTimeOut
Applicable when m_WaitForManagedProcs is set to 1. This field defines the
maximum time to wait for all collectors to complete retrieving data from
their EMSs. This setting is effectively a fail-safe mechanism to cover the
situation where one of the collectors never completes processing. Set this
setting to the maximum value in seconds to wait for all collectors to
complete data processing. When this timeout elapses, and the number of
seconds defined in the m_NothngFndPeriod field pass, then the discovery
process moves to phase 2.
By default, this value is set to 0, which means wait indefinitely.
Related tasks:
“Monitoring full and partial discovery progress” on page 227
You can use the Monitoring tab to monitor the progress of the current full or
partial discovery through each of the discovery phases.
Related reference:
“disco.config table” on page 295
The config table configures the general operation of the discovery process.
Configuring an EMS discovery
Configure an EMS discovery to collect topology data from Element Management
Systems and integrate this data into the discovered topology.
You configure an EMS discovery in the same way that you configure the discovery
of any other type of network. In addition to the standard discovery configuration
activities you must perform some EMS-specific discovery configuration activities.
To configure an EMS discovery, do the following activities in addition to standard
discovery configuration activities:
v Configure and start the EMS collectors
v Seed the EMS discovery by seeding the Collector finder
Note: Collector agents are enabled by default, so they will automatically run when
you configure the collector-based discovery.
These EMS-specific discovery configuration activities are described in the following
topics.
Configuring collectors:
The purpose of a collector is to gather and standardise EMS data based on requests
by the main Network Manager discovery process, for consumption by the
discovery process. Collector configuration governs how the collector interrogates
the EMS or data source in order to service requests from the Network Manager
discovery process, and how the collector listens for requests from the Network
Manager discovery process.
Collector configuration is made up of three areas:
v Collector to EMS or data source configuration: these settings define how the
collector interrogates the EMS or data source in order to service requests from
the Network Manager discovery process.
Chapter 2. Configuring network discovery
113
v Collector to Network Manager configuration: these settings define how the
collector listens for requests from the Network Manager discovery process.
v Miscellaneous configuration: these settings are optional and include settings
such as debug mode.
These configuration settings are typically held in a single file on a per-collector
basis inside the relevant collector directory.
Scripts and a plain-text configuration file for each collector are held in a separate
directories within the $NCHOME/precision/collectors/ directory, as follows:
v Collectors written in Java are stored in the $NCHOME/precision/collectors/
javaCollectors/ directory.
v Collectors written in Perl are stored in the $NCHOME/precision/collectors/
perlCollectors/ directory.
Note: To allow the collectors to be run in isolation, that is, on another machine in
a Network Manager installation, the collector directory can be moved to that
machine and the collectors can be run there provided that the following hold:
v For the Perl collector directory, Perl must be installed on the target machine.
v For the Java collector directory, a suitable Java Virtual Machine must be available
on the target machine.
Experienced users can develop new collectors to enable Network Manager to
interact with other EMSs. Configuration and executable files for each new collector
must be placed in an appropriately named directory within one of the directories
listed above, depending on whether the collector is written in Java or Perl. For
more information, see the EMS Collector Developer Guide.
Configuring Java collectors:
You can configure generic settings for all Java collectors. You can also configure
specific settings for each Java collector.
Configuring generic settings for Java collectors:
You can configure generic settings for all Java collectors in the generic
collector.properties file .
You can configure generic settings for all Java collectors by editing the
collector.properties file, located at: $NCHOME/precision/collectors/
javaCollectors/framework/. The file uses standard Java key value pair notation,
that is, key = value. Using this file you can configure the following parameters:
v Port on which to run the Java collectors.
v Logging details for the Java collectors.
Sample collector.properties file
The following code fragment presents sample settings from a
collector.properties file.
# Port on which to run the embedded collector server
port = 8080
# Log directory relative to the bin directory
log.directory = ../log/
# Name of the collector log file
114
IBM Tivoli Network Manager IP Edition: Discovery Guide
log.filename = collector.log
# Level of logging for the collector framework
log.level = INFO
# Name of the collector log file
trace.filename = collector-trace.log
# Level of logging for the collector framework
trace.level = FINEST
Generic properties file reference for Java collectors:
Use this information to understand how the generic properties file for Java
collectors is constructed.
The generic properties file for Java collectors contains the properties listed in the
following table.
Table 9.
Property
Description
port
Port on which to run the collector.
log.directory
Base directory where log files should be stored.
log.filename
Filename for the log file. Can also specify a pattern for the log
file name using a set of system-defined elements.
log.level
One of the following:
v NONE
v FINEST
v FINER
v FINE
v CONFIG
v INFO
v WARNING
v SEVERE
v ALL
log.maxsize
Maximum size of the log file. Once this maximum is reached, the
file is renamed and is kept as a backup.
log.count
Number of backup log files to keep.
log.messageprefix
Log message prefix.
trace.filename
Filename for the trace file. Can also specify a pattern for the trace
file name using a set of system-defined elements.
trace.level
One of the following:
v NONE
v FINEST
v FINER
v FINE
v CONFIG
v INFO
v WARNING
v SEVERE
v ALL
Chapter 2. Configuring network discovery
115
Table 9. (continued)
Property
Description
trace.maxsize
Maximum size of the trace file. Once this maximum is reached,
the file is renamed and is kept as a backup.
trace.count
Number of backup trace files to keep.
Configuring individual Java collectors:
You can configure specific settings for each Java collector by editing the
.properties file for that collector.
Configuring the Nokia5529Idm Java collector:
This collector uses the Bulk Network Export feature to retrieve data from the
Alcatel Lucent 5529 IDM EMS. Before running the Nokia5529Idm Java collector in
a network discovery, you must copy certain required files and configure the
connection details between the EMS and Network Manager.
You can also configure additional information to be collected from the EMS.
Restriction: The Nokia5529Idm Java collector is only supported on the 5529 IDM
EMS running on release 9.2.30.
To configure the collector, complete the following steps:
1. Before running the collector, copy the required .jar files from the EMS to the
server on which the collector is installed:
a. Log into the Schema page of the IDM using the credentials of an IDM NBI
user. The URL of the IDM Schema page is https://hostname:8443/idm/
schemadoc/html/index.html, where hostname is the name or IP address of
the IDM server.
b. Click on the Client sample URL and download the idm-oss-client.tar.gz
file to the server on which the collector is installed.
c. Uncompress the file.
d. Copy the following files to the $NCHOME/precision/collectors/
javaCollectors/lib directory:
v jnp-client-5.0.3.GA.jar
v jboss-logging-spi-2.1.0.GA.jar
v axs-mobject-remote-api-9.2.30-208518.jar
v log4j-1.2.13.jar
v jboss-messaging-client-1.4.6.GA.jar
v jboss-remoting.jar
v jboss-common-core-2.2.14.GA.jar
v trove-2.1.1.jar
v javassist-3.10.0.GA.jar
v jboss-mdr-2.0.1.GA.jar
v jboss-aop-2.1.1.GA.jar
v concurrent-1.3.4.jar
2. Change to the collector directory:
cd $NCHOME/precision/collectors/javaCollectors/Alcatel5529Idm/
116
IBM Tivoli Network Manager IP Edition: Discovery Guide
3. Within this directory, find the sample configuration file for the Nokia5529Idm
Java collector and copy it to the working configuration file using a command
similar to the following example:
cp Alcatel5529IdmCollector.properties.sample Alcatel5529IdmCollector.properties
4. The configuration file consists of the following sections:
Collector properties
General configuration parameters for the collector, such as port
number and log and trace details.
Data Source properties
Details of the EMS that the collector is connecting to. Data from these
fields is used by Network Manager to model the EMS.
Data Acquisition properties
Parameters that specify which data to collect from the EMS.
SOAP properties
SOAP-specific parameters.
FTP properties
FTP-specific parameters.
JMS properties
Properties relating to the Java Messaging System.
CSV properties
Properties relating to comma-separated value format files.
5. Configure the collector port and log and trace parameters:
port
The port on which to run the collector. The port must match the port
configured in the insert into the collectorFinder.collectorRules
table in the DiscoCollectorFinderSeeds.cfg file. The default value is
8080.
log.filename
Filename for the collector log file. You can also specify a pattern for
the log file name using a set of system-defined elements. The default
value is Alcatel5529IdmCollector.log.
log.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
trace.filename
Filename for the collector trace file. You can also specify a pattern for
the trace file name using a set of system-defined elements. The default
value is Alcatel5529Collector-trace.log.
trace.level
Takes one of the following values:
v NONE
Chapter 2. Configuring network discovery
117
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
6. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager
to model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following
values:
v unknown
v up
v down
v other
7. In the Data Acquisition properties section, configure data acquisition
parameters:
collectData
The default value is true.
118
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
IBM Tivoli Network Manager IP Edition: Discovery Guide
DataAcquisition.fullDiscoTimeout
The number of seconds that the collector waits for the Bulk Network
Export operation to be completed by the EMS. The default value is 30.
8. In the SOAP properties section, configure the SOAP properties:
soap.username
Username for the SOAP service.
soap.password
Password for the SOAP service.
soap.port
Port for the SOAP service.
9. In the FTP properties section, configure the FTP properties.
ftp.host
The IP address or hostname of the server on which the collector is
running.
ftp.username
The FTP session username. This user must be able to log in to the
server and have write permissions for the FTP directory.
ftp.password
The password for the username specified for the FTP session.
ftp.directory
The full path to the destination directory for files transferred from the
EMS. This directory is on the server on which the collector is running.
The default directory is /tmp.
ftp.compressed
The default is false.
True
Files are transferred in a compressed archive.
False
Files are not compressed.
10. In the JMS properties section, configure the properties that relate to the Java
Messaging Service:
jms.username
Username for the JMS service.
jms.password
Password for the JMS service.
jms.topic
The Topic name to listen for JMS messages.
jms.filter
Message filter to process specific messages. Leave blank for no
filtering.
jms.durable
Set as true to enable durable subscription. Default is false.
jms.unsubscribe
Set as true to unsubscribe from the Topic when durable subscription
is enabled. Default is false.
jms.clientId
JMS client identifier to be set for durable subscriptions.
11. Configure the CSV Properties section.
Chapter 2. Configuring network discovery
119
The data from the EMS is downloaded as a file in the Comma-Separated
Values (CSV) format. You can configure which values from the EMS for the
NE and NE System are exported to the CSV file. The first three values are
always mapped to the NE name (or NE System name), managed object type,
and object identifier. Because the exact order of the remaining values in the
CSV file can vary in different systems, you must configure the mapping so
that the values are mapped correctly by the collector.
Restriction: The values that you use for the following variables must match
exactly the attribute names exported by the EMS.
csv.NE.1
Specifies the mapping for the first unmapped variable for a line in the
CSV file that describes an NE, that is, for the fourth variable in the
line. For example:
csv.NE.1=IP Address
csv.NE.n
Specifies the mapping for the next unmapped variable, where n is an
integer that increases by 1 with each subsequent variable.
csv.NE_System.1
Specifies the mapping for the first unmapped variable for a line in the
CSV file that describes an NE System, that is, for the fourth variable in
the line. For example:
csv.NE_System.1=Contact
csv.NE_System.n
Specifies the mapping for the next unmapped variable, where n is an
integer that increases by 1 with each subsequent variable.
In the following example data for an NE, the NE name is ISAM123, the
managed object type is NE, and the object identifier is ISAM123.
ISAM123,NE,ISAM123,192.168.242.175
The value 192.168.242.175 is the IP address. So you must define the following
property:
csv.NE.1=IP Address
In the following example data for an NE System, the NE System name is
ISAM123, the managed object type is NE System, and the object identifier is
ISAM123.
ISAM123,NE System,ISAM123,Mike,Main UK ISAM system,R4.5.02,,00:80:C0:52:D4:8F,
"Administrators
office"/,3FE478262BNAA_E3.2.0.9,EX1234,LEUK,
10/9/14 3:11:26 AM
In order to correctly map the remaining values, you would define the
following properties:
csv.NE_System.1=Contact
csv.NE_System.2=Description
csv.NE_System.3=Ethernet DSL
csv.NE_System.4=ETSI Version
csv.NE_System.5=HUB MAC Address
csv.NE_System.6=Location
csv.NE_System.7=MIB Version
csv.NE_System.8=System ID
csv.NE_System.9=Type
csv.NE_System.10=Up Time
12. Save the collector configuration file.
120
IBM Tivoli Network Manager IP Edition: Discovery Guide
Configuring the Alcatel5620Sam Java collector:
To use data from the Alcatel5620Sam Java collector in a network discovery, you
must copy certain files from the EMS to the server where the collector is installed,
and configure the connection details between the EMS and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the Alcatel5620Sam Java collector, complete the following steps:
1. Required: Before running the collector for the first time, copy the file
/opt/5620sam/server/nms/integration/samOss.jar from the EMS server to the
/opt/IBM/netcool/core/precision/collectors/javaCollectors/lib/ directory.
You must use the samOss.jar file from the same version and release as the
Aclatel 5620 system.
2. Install the Oracle JRE on the Alcatel 5620 server.
3. Create a new script to run the collector.
a. Create a copy of the /opt/IBM/tivoli/netcool/precision/collectors/
javaCollectors/bin/collector.sh script in the same directory. This script
is used to start only the SAM 5620 collector. For example, name the script
collectorSAM5620Java.sh
b. Edit the new script and change the value for COLL_JAVA to point to the
newly installed JRE. For example, change COLL_JAVA=$JAVA to
COLL_JAVA=/usr/local/java/jre1.7.0_72/bin/java
4. Change to the directory that contains the collector files.
cd $NCHOME/precision/collectors/javaCollectors/Alcatel5620Sam/
5. Within this directory, find the sample configuration file for the collector and
copy it to the working configuration file.
cp Alcatel5620Sam.
properties.sample
Alcatel5620Sam.
properties
6. Edit the collector configuration file:
$NCHOME/precision/collectors/javaCollectors/Alcatel5620Sam/Alcatel5620Sam.
properties.
This file includes the following configuration sections:
v Collector properties. General configuration parameters for the collector, such
as port number and log and trace details.
v EMS connection properties. Details of the EMS that the collector is
connecting to. Data from these fields is used by Network Manager to model
the EMS.
v HTTPS properties. Properties for configuring the HTTPS communication
with the SAM 5620 EMS.
v FTP properties. Defines the file on the Network Manager server to which
the SAM 5620 EMS writes the generated SOAP XML response. You must
ensure that the FTP directory has public read/write permissions.
v JMS properties. Java Messaging System configuration parameters.
v Data Acquisition properties. Parameters that specify what data to collect
from the EMS.
The following steps list the configurable parameters. All other properties in
this file are collector system-based configurations and must not be changed.
7. Configure the collector port and log and trace parameters:
Chapter 2. Configuring network discovery
121
port
The port on which to run the collector. The port must match the port
configured in the insert into the collectorFinder.collectorRules
table in the DiscoCollectorFinderSeeds.cfg file.
log.filename
Filename for the collector log file. You can also specify a pattern for
the log file name using a set of system-defined elements.
log.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
log.maxsize
Maximum size of the collector log file in MB. The default is 50.
log.maxcount
Maximum number of generated collector log files. The default is 100.
trace.maxsize
Maximum size of the collector trace file in MB. The default is 50.
log.maxcount
Maximum number of generated collector trace files in MB. The default
is 100.
trace.filename
Filename for the collector trace file. You can also specify a pattern for
the trace file name using a set of system-defined elements.
trace.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
8. In the EMS Connection Configuration section, configure these parameters:
PrimaryEmsHost
Primary SAM 5620 host IP address.
PrimaryEmsPort
Primary SAM 5620 port accepting SOAP requests.
122
IBM Tivoli Network Manager IP Edition: Discovery Guide
RedundancyEnabled (High Availability)
Flag to indicate if the SAM server is running on redundancy mode. If
set to true, you must populate the SecondaryEmsHost and
SecondaryEmsPort fields.
SecondaryEmsHost
Secondary SAM 5620 host IP address.
SecondaryEmsPort
Secondary SAM 5620 port accepting SOAP requests.
Username
Username of a SAM 5620 OSS user with OSS Management privileges.
Password
The SAM 5620 password, in plain text. This property only takes effect
if the md5Password property is not used.
Md5Password
The SAM 5620 password as an MD5 hash. If both Password and
Md5Password are specified, Md5Password is used.
Secure
If set to true, the HTTPS protocol is used to communicate with the
EMS.
9. In the FTP Configurations section, configure the following parameters:
FtpUsername
The FTP username to use to connect to the EMS.
FtpPassword
The FTP password to use to connect to the EMS.
FtpHost
The IP address of the Network Manager host.
FtpDefaultDirectory
The default directory for the FTP service on the Network Manager
server.
FtpDirectory
Optional. A specific folder within the default directory to write files
to. If this parameter is not specified, files are written to the default
directory, as defined by the FtpDefaultDirectory parameter.
SecureFTP
If true, SFTP is used
10. In the HTTPS Configuration section, configure the following parameters:
HTTPSSecure
If true, HTTPS (instead of HTTP) is used to connect to the EMS.
TrustStore
The full path of SAM 5620 truststore file.
TrustStorePassword
The TrustStore Password.
HTTPSPort
HTTPS port for the SAM 5620. The default is 8443.
HTTPSProtocolHandler
Protocol handler for HTTPS connection. Because the SAM 5620 does
Chapter 2. Configuring network discovery
123
not support the IBM HTTPS protocol handler package, the collector
uses Oracle's HTTPS handler package by default.
11. In the JMS Properties section, configure the following parameters:
jms.topic
The JMS message topic name to listen for. The default is “”.
jms.clientId
JMS client identifier to be set for non-durable subscriptions. The ID
must be unique for each collector.
jms.sleep
The time, in minutes, that the collector waits before trying to reconnect
to the SAM 5620 if the High Availability feature is activated. This time
must be long enough for the secondary SAM 5620 to finish
initialization.
12. In the Data Acquisition configuration section, configure the following
parameters:
GetEntities
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
GetVplsVpns
1: Enable
Enables download of VPLS VPN data from the EMS.
0: Disable
Disables download of VPLS VPN data from the EMS.
GetVllVpns
1: Enable
Enables download of VLL VPN data from the EMS.
0: Disable
Disables download of VLL VPN data from the EMS.
GetLayer3Vpns
1: Enable
Enables download of Layer 3 VPN data from the EMS.
0: Disable
Disables download of Layer 3 VPN data from the EMS.
GetMplsInterfaces
1: Enable
Enables download of MPLS interface data from the EMS.
0: Disable
Disables download of MPLS interface data from the EMS.
GetLayer2Connections
1: Enable
Enables download of Layer 2 connectivity data from the EMS.
0: Disable
Disables download of Layer 2 connectivity data from the EMS.
124
IBM Tivoli Network Manager IP Edition: Discovery Guide
GetLteData
1: Enable
Enables download of LTE data from the EMS.
0: Disable
Disables download of LTE data from the EMS.
13. Save the collector configuration file.
Use the new script to start the collector. For example, use a command line similar
to the following:
./collectorSAM5620Java.sh -Xms512m -Xmx1024m
-jar Alcatel5620Sam/Alcatel5620SamCollector.jar
-propsFile Alcatel5620Sam/Alcatel5620Sam.properties
Configuring the Cisco APIC REST collector:
To use data from the Cisco APIC REST collector in a network discovery, you must
configure the connection details between the Cisco Application Policy
Infrastructure Controller (APIC) and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the Cisco APIC REST collector, complete the following steps:
1. Change to the Cisco APIC REST collector directory.
cd $NCHOME/precision/collectors/javaCollectors/CiscoAPICREST/
2. Within this directory, find the sample configuration file for the Cisco APIC
REST collector and copy it to the working configuration file.
cp CiscoApicRestCollector.properties.sample CiscoApicRestCollector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/CiscoAPICREST/CiscoApicRestCollector.properties. This file
includes the following configuration sections:
v Collector specific properties
v Data Acquisition properties
v Data Source properties
v REST Connection properties
The following steps list the configurable parameters. The remaining properties
in this file are collector system-based configurations and not meant to be
changed.
4. Configure the collector port and log and trace parameters:
port
The port on which to run the collector. The port must match the port
configured in the insert into the collectorFinder.collectorRules
table in the DiscoCollectorFinderSeeds.cfg file. The default value is
8080.
log.filename
Filename for the collector log file. You can also specify a pattern for
the log file name using a set of system-defined elements.The default
value is CiscoApicRestCollector.log.
log.level
Takes one of the following values:
v NONE
v FINEST
Chapter 2. Configuring network discovery
125
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
trace.filename
Filename for the collector trace file. You can also specify a pattern for
the trace file name using a set of system-defined elements. The default
value is CiscoApicRestCollector-trace.log
trace.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
5. Configure data acquisition parameters for the collector:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 1.
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
DataAcquisition.GetLayer1Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 1 connectivity data from the EMS.
0: Disable
Disables download of layer 1 connectivity data from the EMS.
DataAcquisition.GetLayer2Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 2 connectivity data from the EMS.
0: Disable
Disables download of layer 2 connectivity data from the EMS.
126
IBM Tivoli Network Manager IP Edition: Discovery Guide
DataAcquisition.GetLayer3Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 3 connectivity data from the EMS.
0: Disable
Disables download of layer 3 connectivity data from the EMS.
DataAcquisition.localDataDirectory
The location to store the output files generated from the Cisco APIC.
A relative or full path to the directory location is required. You can not
use $NCHOME. For example, /opt/IBM/netcool/core/precision/
collectors/javaCollectors/CiscoAPICREST/data/.
6. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager
to model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the Cisco APIC data source.
DataSource.emsHost
IP address or hostname of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsUserName
The username used to connect to the Cisco APIC.
DataSource.emsPassword
The password for the user specified by the DataSource.emsUserName
property.
DataSource.emsName
Name of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver. For the
Cisco APIC REST collector, this identifier must be set to
ciscoapicrest.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following
values:
Chapter 2. Configuring network discovery
127
v unknown
v up
v down
v other
7. Configure Web Services and REST connection properties for the collector.
enableSSL
Enable or disable SSL connectivity between the collector and the EMS
server. This property takes the following values: true or false. The
default is false.
keyStoreFileName
Specify the name of the keystore file that contains the SSL client
certificate and trusted authority certificate.
The keystore file must be placed in the directory specified in the
pathToKeyStoreFile parameter.
keyStorePassword
Specify the password required to access the certificate specified by the
keyStoreFileName property.
pathToKeyStoreFile
The full path to the keyStoreFileName directory. You must specifiy the
relative or full path to the directory location. You can not use
$NCHOME. For example, /opt/IBM/netcool/core/precision/
collectors/javaCollectors/CiscoApicRest/.
setResponseTimeout
Specify how long (in seconds) the collector waits for a response from
the EMS before timing out. The default is 300.
setHttpVersion
Specify the version of the HTTP protocol that the target system
supports. For Cisco APIC, this property must be set to 1.0.
setRefreshInterval
Specify the interval (in seconds) that the collector waits between
successive login refresh requests. The Cisco APIC session timeout
period is 300 seconds (or 5 minutes), so this value must be less than
300. The default is 180.
Tip: If your network has performance or stability issues, set a lower
value than 180.
8. Save the collector configuration file.
9. Optional: Set up SSL between the collector and Network Manager.
a. Obtain the required SSL certificates and the Trusted Authority certificate
from the Cisco APIC server administrator.
b. Add the certificates to a local Java keystore so that they can be referenced
by the KeyStore property.
c. If you have a key and a certificate from the server in separate files, you
must combine them into a single PKCS12 format file to load into a new
keystore. To convert the server certificate into PKCS12 format, use the
following OpenSSL toolkit command:
openssl pkcs12 -export -inkey key_file-in cert_file-out cert_pkcs12
128
IBM Tivoli Network Manager IP Edition: Discovery Guide
Where key_file is the key file retrieved from the server, cert_file is the
certificate retrieved from the server, and cert_pkcs12 is the combined file
in PKCS12 format for loading into the keystore.
10. To create a Java keystore using the Keytool utility, follow these steps:
a. Generate a keystore and self-signed certificate using the following
command:
keytool -genkey -keyalg RSA -alias alias_name -keystore keystore_file
-storepass keystore_password -validity 360 -keysize 2048
b. Import the SSL certificate from Cisco APIC into the newly created Java
keystore file using the following command:
keytool -import -trustcacerts -alias alias_name -file cert_file
-keystore keystore_file
c. Verify that the certificates are in a Java keystore using the following
command:
keytool -list -v -keystore keystore_file
d. Set the keyStoreFileName and keyStorePassword properties in the collector
property file.
e. Set the enableSSL property in the collector property file to true.
f. Ensure that the DataSource.emsPort property in the collector property file
is set to the HTTPS port.
g. Copy the generated keystore file into the directory specified in the
pathToKeyStoreFile property.
The collector stores retrieved data as .xml and .json files in the
$NCHOME/precision/collectors/javaCollectors/CiscoAPICREST/data/ directory.
This directory must have the appropriate permissions for files to be created in it.
Configuring the CiscoWorks LMS collector:
To use data from the CiscoWorks LMS collector in a network discovery, you must
configure the connection details between the CiscoWorks LMS EMS and Network
Manager.
In order to enable the Network Manager CiscoWorks LMS collector integration
with the CiscoWorks LMS EMS, you must first copy the jdbc driver. To do this,
and subject to your verification that you have the necessary permission or
authorization to do so, manually copy the jconn2.jar library from the CiscoLMS
server into the Network Manager Java collector library directory at
$NCHOME$NCHOME/precision/collectors/javaCollectors/lib.
Note: By default, the location of the jconn2.jar on the Cisco LMS EMS server is
/opt/CSCOpx/lib/classpath.
You can also configure additional information to be collected from the EMS. To
configure the CiscoWorks LMS collector, complete the following steps:
To use data from the CiscoWorks LMS collector in a network discovery, you must
configure connection parameters for Cisco Open Database Schema and Cisco Data
Extraction Engine used to communicate between the CiscoWorks LMS EMS and
Network Manager.
1. Change to the CiscoWorks LMS collector directory.
cd $NCHOME/precision/collectors/javaCollectors/CiscoLMS/
Chapter 2. Configuring network discovery
129
2. Within this directory, find the sample configuration file for the CiscoWorks
LMS collector and copy it to the working configuration file.
cp CiscoLMSCollector.properties.sample CiscoLMSCollector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/CiscoLMS/CiscoLMSCollector.properties. This file includes
the following configuration sections:
v A section containing parameters for interfacing to the Cisco Open Database
Schema, the Cisco Data Extraction Engine. This section also contains data
acquisition flag settings.
v A system configuration section.
The following steps list the configurable parameters. The remaining properties
in this file are collector system-based configurations and not meant to be
changed.
4. Configure the collector port and log and trace parameters:
port
The port on which to run the collector. The port must match the port
configured in the insert into the collectorFinder.collectorRules
table in the DiscoCollectorFinderSeeds.cfg file.
log.filename
Filename for the CiscoWorks LMS collector log file. You can also
specify a pattern for the log file name using a set of system-defined
elements.
log.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
trace.filename
Filename for the CiscoWorks LMS collector trace file. You can also
specify a pattern for the trace file name using a set of system-defined
elements.
trace.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
130
IBM Tivoli Network Manager IP Edition: Discovery Guide
5. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager
to model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following
values:
v unknown
v up
v down
v other
6. Configure parameters for interfacing to the Cisco LMS database:
DB.Host
IP address or hostname of the Cisco LMS database.
DB.Port
Port number of the database. The default value is 43455.
DB.DbName
The schema name of the Cisco LMS database (database schema). The
default value is rmengdb.
DB.UserName
The username used to connect to the database. The default value is
lmsdatafeed.
DB.Password
The password used to connect to the database. The default value is
lmsdatafeed.
7. Configure parameters for interfacing to the Cisco Data Extraction Engine:
Chapter 2. Configuring network discovery
131
webservice.host
IP address or hostname of the Cisco Data Extraction Engine.
webservice.port
Port of the Cisco Data Extraction Engine. The default value is 1741.
webservice.servicename
Web service for the Cisco Data Extraction Engine. The default value is
/campus/servlet/CMExportServlet.
webservice.username
User name for the Cisco Data Extraction Engine. The default value is
admin.
webservice.password
User password for the Cisco Data Extraction Engine. The default value
is admin.
8. Configure data processing parameters for the Cisco Data Extraction Engine.
The Cisco Data Extraction Engine can sometimes generate huge XML files for
the layer 2 topology. In order to manage XML processing, the CiscoWorks
LMS collector has the ability to read the XML envelope from the Cisco Data
Extraction Engine and process it right away, or spool it to a flat file for later
processing. By default, the Collector reads the XML envelope from the Cisco
Data Extraction Engine and processes it right away. Cisco Data Extraction
Engine processing parameters are as follows:
L2TopologyXML.inputStreamEnable
Takes one of the following values:
1: Enable
Collector reads from the input stream and consumes the XML
envelope.
0: Disable
Collector reads from the input stream, spools the XML
envelope to a file and consumes the XML envelope.
L2TopologyXML.outputdirectory
Output directory for the spooled XML envelope if
L2TopologyXML.inputStreamEnable = 1. The default value is
../CiscoLMS/tmp.
L2TopologyXML.outputfilename
Output file for the spooled XML envelope if
L2TopologyXML.inputStreamEnable = 1. The default value is
output.xml.
9. Configure data acquisition parameters for the collector:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the
CiscoWorks LMS EMS.
False
Disables the collector. The collector does not collect data from
the CiscoWorks LMS EMS.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 1.
132
IBM Tivoli Network Manager IP Edition: Discovery Guide
1: Enable
Enables download of physical entity data from the CiscoWorks
LMS EMS.
0: Disable
Disables download of physical entity data from the
CiscoWorks LMS EMS.
DataAcquisition.GetLayer2Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 2 connectivity data from the
CiscoWorks LMS EMS.
0: Disable
Disables download of layer 2 connectivity data from the
CiscoWorks LMS EMS.
10. Save the collector configuration file.
Configuring the Huawei M2000 collector:
To use data from the Huawei M2000 collector in a network discovery, you must
configure the collector to process the XML files.
You can also configure additional information to be collected from the EMS. To
configure the Huawei M2000 collector, complete the following steps:
1. Change to the Huawei M2000 collector directory.
cd $NCHOME/precision/collectors/javaCollectors/HuaweiM2K/
2. Within this directory, find the sample configuration file for the collector and
copy it to the working configuration file.
cp HuaweiM2KCollector.properties.sample HuaweiM2KCollector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/HuaweiM2K/HuaweiM2KCollector.properties.
The file includes the following sections:
Collector properties
General configuration parameters for the collector, such as port number
and log and trace details.
Data Source properties
Details of the EMS that the collector is connecting to. Data from these
fields is used by Network Manager to model the EMS.
Data Acquisition properties
Parameters that specify which data to collect from the EMS.
File processing properties
Parameters that specify the options for file processing.
4. In the Collector properties section, configure the general collector properties:
port
Port on which to run the embedded collector server. The port must
match the port configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file. The default value is 8080.
log.filename
Filename for the Huawei M2000 collector log file. The default value is
HuaweiM2KCollector.log.
Chapter 2. Configuring network discovery
133
log.level
Level of logging for the collector framework. Logging level takes one of
the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIG
v INFO
v WARNING
v SEVERE
v ALL
The default value is INFO.
trace.filename
Filename for the Huawei M2000 collector trace file. The default value is
HuaweiM2KCollector-trace.log.
trace.level
Level of trace for the collector framework. The default value is INFO.
5. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager to
model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following values:
v unknown
v up
v down
v other
134
IBM Tivoli Network Manager IP Edition: Discovery Guide
6. In the Data Acquisition properties section, configure data acquisition
parameters:
collectData
Set to true to acquire data or false to not acquire data.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 0.
1: Enable
Enables discovery of physical entity data from the XML file.
0: Disable
Disables discovery of physical entity data from the XML file.
7. In the File processing properties section, configure file processing parameters:
file.localDirectory
The local directory where the files to be processed by the collector are
located. Specify the full path to the directory location.
8. Save the collector configuration file.
Configuring the Huawei CORBA TMF 814 collector:
To use data from the Huawei CORBA TMF 814 collector in a network discovery,
you must configure the connection details between the Huawei CORBA TMF EMS
and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the Huawei CORBA TMF 814 collector, complete the following steps:
1. Change to the Huawei CORBA TMF 814 collector directory.
cd $NCHOME/precision/collectors/javaCollectors/HuaweiCorbaTMF814/
2. Within this directory, find the sample configuration file for the Huawei
CORBA TMF 814 collector and copy it to the working configuration file.
cp HuaweiCorbaTMF814Collector.properties.sample
HuaweiCorbaTMF814Collector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/HuaweiCorbaTMF814/HuaweiCorbaTMF814Collector.properties.
The file is made up of the following sections:
Collector properties
General configuration parameters for the collector, such as port
number and log and trace details.
Data Source properties
Details of the EMS that the collector is connecting to. Data from these
fields is used by Network Manager to model the EMS.
Data Acquisition properties
Parameters that specify which data to collect from the EMS.
ORB Initialization properties
CORBA ORB-specific parameters.
NameService properties
Naming service parameters.
EmsSessionFactory properties
Parameters that specify how the collector should obtain the
EMSSessionFactory object reference.
Chapter 2. Configuring network discovery
135
Manager properties
Parameters that specify the names of the manager interfaces.
Iterator properties
Parameters that define the behavior of the CORBA iterator.
Filtering properties
Parameters that define which devices should be excluded from
processing.
4. In the Collector properties section, configure the general collector properties:
port
Port on which to run the embedded collector server. The port must
match the port configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file. The default value is 8080.
log.filename
Filename for the Huawei CORBA TMF 814 collector log file. The
default value is HuaweiCorbaTMF814Collector.log.
log.level
Level of logging for the collector framework. The default value is
INFO.
trace.filename
Filename for the Huawei CORBA TMF 814 collector trace file. The
default value is HuaweiCorbaTMF814Collector-trace.log.
trace.level
Level of trace for the collector framework. The default value is INFO.
5. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager
to model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsHost
Hostname of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
136
IBM Tivoli Network Manager IP Edition: Discovery Guide
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following
values:
v unknown
v up
v down
v other
DataSource.emsUserName
Username of the EMS.
DataSource.emsPassword
Password of the EMS.
Note: The DataSource.emsHost and DataSource.emsPort fields are compulsory
if the nameService.useNameService variable is TRUE.
6. In the Data Acquisition properties section, configure data acquisition
parameters:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 0.
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
Fix Pack 2
DataAcquisition.GetEquipmentAdditionalInfo
Takes one of the following values. The default value is 0.
1: Enable
Enables download of equipment additional information from
the EMS.
0: Disable
Disables download of equipment additional information from
the EMS.
DataAcquisition.GetCTPs
Takes one of the following values. The default value is 0.
1: Enable
Enables download of ConnectionTP data from the EMS.
0: Disable
Disables download of ConnectionTP data from the EMS.
DataAcquisition.GetLayer1Connections
Takes one of the following values. The default value is 0.
Chapter 2. Configuring network discovery
137
1: Enable
Enables download of layer 1 connectivity data from the EMS.
0: Disable
Disables download of layer 1 connectivity data from the EMS.
7. In the ORB Initialization properties section, do not modify the following ORB
initialization properties unless directed by IBM® Support:
orbProp.1.name=org.omg.CORBA.ORBClass
orbProp.1.value=com.ibm.CORBA.iiop.ORB
Specifies the IBM ORB implementation to be activated.
orbProp.2.name=org.omg.CORBA.ORBSingletonClass
orbProp.2.value=com.ibm.rmi.corba.ORBSingleton
Specifies the IBM ORB implementation to be activated.
orbProp.3.name=com.ibm.CORBA.Debug.Output
orbProp.3.value=../log/orbtrc.log
Specifies the log file to which to write ORB error messages when the
collector fails to connect to the CORBA service on the EMS.
8. In the NameService properties section, configure the naming service
properties:
nameService.useNameService
Takes one of the following values. Default value is True.
True
Collector obtains the root naming context reference by
accessing the naming service using a corbaloc URL
False
Collector obtains the root naming context reference from the
specified IOR file and bypasses the naming service.
nameService.iorFile
The full filepath to the IOR file containing the NameService reference.
Supports local filepath and remote filepath; for example, HTTP, and
FTP.
nameService.nameServiceName
Service name for the naming service.
9. In the EmsSessionFactory properties section, configure the EmsSessionFactory
properties:
emsSessionFactory.useNameService
Takes one of the following values. Default value is True.
True
Collector obtains the EmsSessionFactory_I reference by using
the naming service and by resolving the specified naming
context properties.
False
Collector obtains the EmsSessionFactory_I reference from the
specified IOR file and bypasses the naming service.
emsSessionFactory.iorFile
Full filepath to the IOR file containing the EmsSessionFactory
reference. Supports local filepath and remote filepath; for example,
HTTP, FTP.
emsSessionFactory.namingContext.*
These naming context properties represent the naming context
bindings for resolving the EmsSessionFactory reference from the
138
IBM Tivoli Network Manager IP Edition: Discovery Guide
naming service. All entries must be in *.id and *.kind pairs and
specified in the correct sequence in order for the EmsSessionFactory
reference to be correctly resolved.
10. In the Manager properties section, configure the manager properties:
manager.emsMgr
Name for the EMSMgr interface. The default value is EMS.
manager.equipmentInventoryMgr
Name for the EquipmentInventoryMgr interface. The default value is
EquipmentInventory.
manager.managedElementMgr
Name for the ManagedElementMgr interface. The default value is
ManagedElement.
manager.multiLayerSubnetworkMgr
Name for the MultiLayerSubnetworkMgr interface. The default value
is MultiLayerSubnetwork.
11. In the Iterator properties section, configure the CORBA iterator properties:
iterator.resultSize
Specifies the maximum number of results returned for each set by the
CORBA Iterator. The default value is 20. Increase this value if you
want to decrease the number of iterations and increase the size of the
data response from the EMS.
iterator.destroyIterator
Set to true if you want the CORBA Iterator to destroy the
corresponding iterator object on the EMS side. The default value is
false. Enable this property only if the EMS does not automatically
perform memory garbage collection.
12. In the filtering properties section, configure the device filtering properties:
filter.enabled
Takes one of the following values:
v True: filter is enabled; the collector will exclude devices with the
specified filter.productName property.
v False: filter is disabled. This is the default value.
filter.productName
Specify here the model or type of device to excluded from processing.
This property has no default value, and may be left blank. For
multiple entries, separate the product names using commas. For
example;
filter.productName=Virtual NE,OptiX OSN 7500,OptiX DWDM OADM
During processing, the values specified in the filter.productName
property are compared with the contents of the entityData.Description
field.
13. Save the collector configuration file.
Chapter 2. Configuring network discovery
139
Configuring the MTOSISoap collector:
To use data from the MTOSISoap collector collector in a network discovery, you
must configure the connection details between the EMS and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the MTOSISoap collector collector, complete the following steps:
1. Change to the MTOSISoap collector collector directory.
cd $NCHOME/precision/collectors/javaCollectors/MTOSISoap/
2. Within this directory, find the sample configuration file for the MTOSISoap
collector collector and copy it to the working configuration file.
cp MTOSISoapCollector.properties.sample
MTOSISoapCollector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/MTOSISoap/MTOSISoapCollector.properties.
The file includes the following sections:
Collector properties
General configuration parameters for the collector, such as port number
and log and trace details.
Data Acquisition properties
Parameters that specify which data to collect from the EMS.
Data Source properties
Details of the EMS that the collector is connecting to. Data from these
fields is used by Network Manager to model the EMS.
4. In the Collector properties section, configure the general collector properties:
port
Port on which to run the embedded collector server. The port must
match the port configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file. The default value is 8080.
log.filename
Filename for the MTOSISoap collector collector log file. The default
value is MTOSISoapCollector.log.
log.level
Level of logging for the collector framework. Logging level takes one of
the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIG
v INFO
v WARNING
v SEVERE
v ALL
The default value is INFO.
trace.filename
Filename for the MTOSISoap collector collector trace file. The default
value is MTOSISoapCollector-trace.log.
140
IBM Tivoli Network Manager IP Edition: Discovery Guide
trace.level
Level of trace for the collector framework. The default value is INFO.
5. In the Data Acquisition properties section, configure data acquisition
parameters:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
DataAcquisition.MSLN
Value of the MultiLayer Subnetwork of the EMS. Default value is 1.
DataAcquisition.ManagementDomain
Name of the management domain of the EMS. Default value is
Huawei/U2000.
DataAcquisition.ManagedElementsBatchSize
Defines the maximum number of MTOSI objects that can be included in
a SOAP EMS response for a ManagedElementsRequest. The default
value is 4500 objects.
DataAcquisition.TopologicalLinksBatchSize
Defines the maximum number of MTOSI objects that can be included in
a SOAP EMS response for a TopologicalLinkRequest. The default value
is 6000 objects.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 0.
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
DataAcquisition.GetLayer2Connections
Takes one of the following values. The default value is 0.
1: Enable
Enables download of layer 2 connectivity data from the EMS.
0: Disable
Disables download of layer 2 connectivity data from the EMS.
DataAcquisition.GetLayer3Connections
Takes one of the following values. The default value is 0.
1: Enable
Enables download of layer 3 connectivity data from the EMS.
0: Disable
Disables download of layer 3 connectivity data from the EMS.
6. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager to
model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
Chapter 2. Configuring network discovery
141
DataSource.descr
Description of the EMS.
DataSource.emsHost
Hostname of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following values:
v unknown
v up
v down
v other
DataSource.emsUserName
Username of the EMS.
DataSource.emsPassword
Password of the EMS.
7. Save the collector configuration file.
Configuring the Nokia Solutions and Networks NetAct XML Interface for Configuration
Management collector:
The Nokia Solutions and Networks (NSN) NetAct XML Interface for Configuration
Management collector processes 2G, 3G and LTE RAN data by utilizing the
configuration management XML file for the NSN NetAct EMS. This XML file
contains the NetAct Configurator network configuration data, in RAML/CM2
format.
The collector can retrieve the configuration management XML file for the NSN
NetAct EMS in one of the following ways:
v By connecting to the NSN NetAct EMS. In this case the collector uses either FTP
or SFTP. Therefore if you want to use this method, you must configure the
collector properties file with the FTP and SFTP connection details between the
NSN NetAct EMS and Network Manager.
v By accessing the XML file in a designated local directory. If you want to use this
method, you must specify the local directory that will contain XML files
retrieved from the EMS.
142
IBM Tivoli Network Manager IP Edition: Discovery Guide
In either case, you must configure the relevant data acquisition properties within
the collector configuration file, as specified in the procedure that follows.
Note: The collector stores the operating system timestamp of each processed XML
file. If, during a discovery, the collector finds that the last modified timestamp of
the current XML file is the same as the timestamp recorded during the last
discovery, the file is not processed. This ensures that only files containing device
data updated since the last discovery are processed.
To configure the NSN NetAct XML Interface for Configuration Management
collector, complete the following steps:
1. Change to the NSN NetAct XML Interface for Configuration Management
collector directory.
cd $NCHOME/precision/collectors/javaCollectors/NetActCMDump/
2. Within this directory, find the sample configuration file for the collector and
copy it to the working configuration file.
cp NetActCMDumpCollector.properties.sample NetActCMDumpCollector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/NetActCMDump/NetActCMDumpCollector.properties. This file
includes the following configuration sections:
v Collector configuration properties
v Data acquisition properties
v Data source properties
Note: The following steps list the configurable parameters. The remaining
properties in this file are collector system-based configuration values and are
not meant to be changed.
4. Configure the following collector properties:
port
Port on which to run the collector. The port must match the port
configured in the insert into the collectorFinder.collectorRules table
in the DiscoCollectorFinderSeeds.cfg file. The default value is 8080.
log.filename
Filename for the collector log file. You can also specify a pattern for the
log file name using a set of system-defined elements.
log.level
Level of logging for the collector framework. Takes one of the following
values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
The default value is INFO.
trace.filename
Filename for the collector trace file. You can also specify a pattern for
the trace file name using a set of system-defined elements.
Chapter 2. Configuring network discovery
143
trace.level
Level of trace for the collector framework. Takes one of the following
values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
The default value is INFO.
5. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager to
model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsHost
Hostname of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following values:
v unknown
v up
v down
v other
DataSource.emsUserName
Username of the EMS.
144
IBM Tivoli Network Manager IP Edition: Discovery Guide
DataSource.emsPassword
Password of the EMS.
6. Configure data acquisition parameters for the collector:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 0.
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
DataAcquisition.getRanTopology
Takes one of the following values. The default value is 1.
1: Enable
Enables download of RAN connectivity data for the Net Act
EMS.
0: Disable
Disables download of RAN connectivity data for the Net Act
EMS.
DataAcquisition.localDataDirectory
Specifies the location of XML files retrieved from the EMS.
DataAcquisition.postProcessFlag
Defines how the collector handles the data file after processing. The
default valus is 0.
0 : Delete
Deletes the xml file after processing.
1 : Move
Moves the xml file after processing. Used in conjunction with
parameter DataAcquisition.moveLocation.
2 : Leave
Leaves the xml file in the data directory after processing. Used
in conjunction with parameter
DataAcquisition.localDataDirectory.
DataAcquisition.moveLocation
Specifies the location for the files to be moved post processing. This
parameter only takes effect if the variable
DataAcquisition.postProcessFlag has the value of 1.
DataAcquisition.loadFirstRun
Defines on whether to process XML files in the XML local data
directory upon start of the collector, without waiting for the XML-RPC
call from the GUI.
0
Do not process data directory upon collector start. Other values
will process the data directory immediately.
1
Process data directory upon collector start.
Chapter 2. Configuring network discovery
145
DataAcquisition.downloadFile
Defines on whether to download the XML file using FTP or SFTP
(secure FTP) from the upon discovery.
0
Do not download.
1
Download.
The default value is 1.
DataAcquisition.maskCredentials
Defines whether to mask the user credentials in the log when issuing
the FTP or SFTP command to transfer the XML file from the EMS.
0
Do not mask credentials.
1
Mask credentials.
DataAcquisition.remoteFtpHost
Hostname or IP of the EMS where the XML data is generated.
DataAcquisition.remoteDir
Remote directory containing the file or files to be processed.
DataAcquisition.remoteFile
Name of the XML file that contains the CM data. If retrieving files
using FTP or SFTP, then set this property to a wildcard value, such as
*.xml or *.xml.gz.
Note: If the remote directory configured using the
DataAcquisition.remoteDir property contains more than the current file,
and you have set DataAcquisition.remoteFile as a wildcard value, then
all files that match the wildcard will be transferred from the remote
directory and processed. To prevent the collector retrieving all
previously processed files the remote directory must only contain the
most recent XML file or files to be processed.
DataAcquisition.remoteFtpUser
Username to be used for the FTP or SFTP connection.
DataAcquisition.remoteFtpPassword
Password to be used for the FTP or SFTP connection.
DataAcquisition.remoteFtpPort
Port to be used for the FTP or SFTP connection.
DataAcquisition.secureConnection
Indicates on whether to use secure connection (SFTP) when retrieving
the cmdump files.
1
Use SFTP to connect to the EMS.
0
Use FTP to connect to the EMS.
Default is 0.
DataAcquisition.ftpTimeout
Timeout interval for the FTP process.
DataAcquisition.technologyType
Mobile technology that will be handled by the collector. Available
options are as follows:
v 2G3G
146
IBM Tivoli Network Manager IP Edition: Discovery Guide
v LTE
v ALL
Default is 2G3G.
7. Save the collector configuration file.
Configuring the Nokia Solutions and Networks NetViewer collector:
To use data from the Nokia Solutions and Networks (NSN) NetViewer collector in
a network discovery, you must configure the connection details between the NSN
NetViewer EMS and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the NSN NetViewer collector, complete the following steps:
1. Change to the NSN NetViewer collector directory.
cd $NCHOME/precision/collectors/javaCollectors/NetViewer/
2. Within this directory, find the sample configuration file for the NSN
NetViewer collector and copy it to the working configuration file.
cp NetViewerCollector.properties.sample NetViewerCollector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/NetViewer/NetViewerCollector.properties.
4. Configure the following collector properties:
port
Port on which to run the embedded collector server. The port must
match the port configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file. The default value is 8080.
log.filename
Filename for the NSN NetViewer collector log file. The default value
is NetViewerCollector.log.
log.level
Level of logging for the collector framework. The default value is
INFO.
trace.filename
Filename for the NSN NetViewer collector trace file. The default value
is NetViewerCollector-trace.log.
trace.level
Level of trace for the collector framework. The default value is INFO.
5. Configure data acquisition parameters for the collector:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 0.
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
Chapter 2. Configuring network discovery
147
DataAcquisition.GetLayer2Connections
Takes one of the following values. The default value is 0.
1: Enable
Enables download of layer 2 connectivity data from the EMS.
0: Disable
Disables download of layer 2 connectivity data from the EMS.
6. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager
to model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsHost
Hostname of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following
values:
v unknown
v up
v down
v other
DataSource.emsUserName
Username of the EMS.
DataSource.emsPassword
Password of the EMS.
7. Do not modify the following ORB initialization properties unless directed by
IBM Support: These properties are codified as name-value pair parameters.
148
IBM Tivoli Network Manager IP Edition: Discovery Guide
orbProp.1.name=org.omg.CORBA.ORBClass
orbProp.1.value=com.ibm.CORBA.iiop.ORB
Specifies the IBM ORB implementation to be activated.
orbProp.2.name=org.omg.CORBA.ORBSingletonClass
orbProp.2.value=com.ibm.rmi.corba.ORBSingleton
Specifies the IBM ORB implementation to be activated.
orbProp.3.name=com.ibm.CORBA.Debug.Output
orbProp.3.value=../log/orbtrc.log
Specifies the log file to which to write ORB error messages when the
collector fails to connect to the CORBA service on the EMS.
orbProp.4.name=com.ibm.CORBA.ORBWCharDefault
orbProp.4.value=UTF16
Indicates that character encoding set UTF16 is to be used for
integration with the NSN NetViewer EMS.
orbProp.5.name=com.ibm.CORBA.ListenerPort
orbProp.5.value=10005
Integration with the NSN NetViewer EMS uses a Corba Interoperable
Object Reference (IOR) file. Interfacing using an IOR file requires
bidirectional communication. To facilitate this, the ListenerPort
parameter is set to port 10005, and this is the port to be used for
communication from the NSN NetViewer EMS to the collector. This
parameter setting is especially important if you want to integrate the
collector to the NSN NetViewer EMS in a NAT or firewall
environment.
8. Configure the naming service properties:
nameService.useNameService
Takes one of the following values. Default value is True.
True
Collector obtains the root naming context reference by
accessing the naming service using a corbaloc URL
False
Collector obtains the root naming context reference from the
specified IOR file and bypasses the naming service.
nameService.iorFile
The full filepath to the IOR file containing the NameService reference.
Supports local filepath and remote filepath; for example, HTTP, and
FTP.
nameService.nameServiceName
Service name for the naming service.
9. Configure the EmsSessionFactory properties:
emsSessionFactory.useNameService
Takes one of the following values. Default value is True.
True
Collector obtains the EmsSessionFactory_I reference by using
the naming service and by resolving the specified naming
context properties.
False
Collector obtains the EmsSessionFactory_I reference from the
specified IOR file and bypasses the naming service.
emsSessionFactory.iorFile
Full filepath to the IOR file containing the EmsSessionFactory
reference. Supports local filepath and remote filepath; for example,
HTTP, FTP.
Chapter 2. Configuring network discovery
149
10. Configure the manager properties:
manager.emsMgr
Name for the EMSMgr interface. The default value is EMS.
manager.equipmentInventoryMgr
Name for the EquipmentInventoryMgr interface. The default value is
EquipmentInventory.
manager.managedElementMgr
Name for the ManagedElementMgr interface. The default value is
ManagedElement.
manager.multiLayerSubnetworkMgr
Name for the MultiLayerSubnetworkMgr interface. The default value
is MultiLayerSubnetwork.
11. In the Iterator properties section, configure the CORBA iterator properties:
iterator.resultSize
Specifies the maximum number of results returned for each set by the
CORBA Iterator. The default value is 20. Increase this value if you
want to decrease the number of iterations and increase the size of the
data response from the EMS.
iterator.destroyIterator
Set to true if you want the CORBA Iterator to destroy the
corresponding iterator object on the EMS side. The default value is
false. Enable this property only if the EMS does not automatically
perform memory garbage collection.
12. Configure the extraInfo mappings properties: These properties map the values
of the provided fields into the respective tables in the NCIM database.
Multiple values can be specified, but must be differentiated by a numeral in
the properties; for example, chassisData.2.extraInfo , shelfData.3.extraInfo ,
and so on.
v chassisData.1.extraInfo
v shelfData.1.extraInfo
v slotData.1.extraInfo
v moduleData.1.extraInfo
v ptpData.1.extraInfo
v ctpData.1.extraInfo
v topologyData.1.extraInfo
13. Save the collector configuration file.
Configuring the Tellabs INM8000 collector:
To use data from the Tellabs INM8000 collector in a network discovery, you must
configure the connection details between the Tellabs INM8000 EMS and Network
Manager.
In order to enable the Network Manager Tellabs INM8000 collector integration
with the Tellabs INM8000 EMS, you must first copy the following two files to the
Network Manager Tellabs INM8000 collector:
v tol.jar library file
v NbifAttributeValues.ini lookup file
To do this, and subject to your verification that you have the necessary permission
or authorization to do so, perform the following manual copy operations:
150
IBM Tivoli Network Manager IP Edition: Discovery Guide
v Copy the tol.jar library file from the Tellabs INM8000 server into the Network
Manager Java collector library directory at $NCHOME/precision/collectors/
javaCollectors/lib.
v Copy the NbifAttributeValues.ini lookup file from the Tellabs INM8000 server
into the Network Manager Java Tellabs INM8000 collector dat directory at
$NCHOME/precision/collectors/javaCollectors/TellabsINM8000/dat.
Note: You can obtain the tol.jar library file and the NbifAttributeValues.ini
lookup file from the Tellabs INM8000 EMS server, preferably from a server that is
running version INM SR4.0-SP1. These files are also available on the CD-ROM that
came with the Tellabs INM8000 installation and labelled: Tellabs 8000
Intelligent Network Manager SRxx-SPxx Inventory and PePerformance adapter,
JavaAPI and NBITestClient for Northbound Interface.
You can also configure additional information to be collected from the EMS. To
configure the Tellabs INM8000 collector, complete the following steps:
1. Change to the Tellabs INM8000 collector directory.
cd $NCHOME/precision/collectors/javaCollectors/TellabsINM8000/
2. Within this directory, find the sample configuration file for the Tellabs
INM8000 collector and copy it to the working configuration file.
cp TellabsINM8000Collector.properties.sample TellabsINM8000Collector.properties
3. Edit the collector configuration file: $NCHOME/precision/collectors/
javaCollectors/TellabsINM8000/TellabsINM8000Collector.properties. This
file includes the following configuration sections:
v Collector configuration properties
v Data acquisition properties
v Data source properties
v Mapping properties
The following steps list the configurable parameters. The remaining properties
in this file are collector system-based configurations and not meant to be
changed.
4. Configure the collector port and log and trace parameters:
port
The port on which to run the collector. The port must match the port
configured in the insert into the collectorFinder.collectorRules
table in the DiscoCollectorFinderSeeds.cfg file. The default value is
8080.
log.filename
Filename for the collector log file. You can also specify a pattern for
the log file name using a set of system-defined elements. The default
value is TellabsINM8000Collector.log.
log.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
Chapter 2. Configuring network discovery
151
v ALL
trace.filename
Filename for the collector trace file. You can also specify a pattern for
the trace file name using a set of system-defined elements. The default
value is TellabsINM8000Collector-trace.log.
trace.level
Takes one of the following values:
v NONE
v FINEST
v FINER
v FINE
v CONFIGINFO
v WARNING
v SEVERE
v ALL
5. Configure parameters for the Tellabs-specific region identifier.
regionId.enable
If the Tellabs INM8000 EMS supports region identifiers then user
should be able to collect data based on the region identifier configured
in the EMS. This parameter takes one of the following values:
v True
v False
The default value is True.
regionId.set
Defines the region identifier (regid) number to filter. This parameter
can take the form of a single region identifier, or a combination of
multiple region identifiers. For example:
v Single region identifier: regionId.set=5
v Multiple region identifier: regionId.set=5,10,11
6. Configure parameters for Tellabs-specific batch processing batch.trunk.size=20
By using batch processing, Network Manager is able to discover all nodes
from the EMS. If the parameter regionId.enable is set to False, then the series
of settings batch.entity.size applies, where entity can be any of the following:
v subrack
v unit
v module
v interface
v trunk
Define the batch size for each of the entities:
v batch.subrack.size
v batch.unit.size
v batch.module.size
v batch.interface.size
v batch.trunk.size
For example, defined each of these parameters for the getFilteredAllData
API usage. The batch size refers to number of nodes (nid) to be queried and
152
IBM Tivoli Network Manager IP Edition: Discovery Guide
processed by Network Manager at any one time. Each batch size value must
be greater than 1. Refer to the supported entities in the Tellabs NBI
information model. Some typical values are as follows:
v batch.subrack.size=100
v batch.unit.size=50
v batch.module.size=50
v batch.interface.size=20
v batch.trunk.size=20
7. Configure data acquisition parameters for the collector:
collectData
Takes one of the following values. The default value is True.
True
Enables the collector. The collector collects data from the EMS.
False
Disables the collector. The collector does not collect data from
the EMS.
DataAcquisition.GetEntities
Takes one of the following values. The default value is 1.
1: Enable
Enables download of physical entity data from the EMS.
0: Disable
Disables download of physical entity data from the EMS.
DataAcquisition.GetLayer1Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 1 connectivity data from the EMS.
0: Disable
Disables download of layer 1 connectivity data from the EMS.
DataAcquisition.GetLayer2Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 2 connectivity data from the EMS.
0: Disable
Disables download of layer 2 connectivity data from the EMS.
DataAcquisition.GetLayer3Connections
Takes one of the following values. The default value is 1.
1: Enable
Enables download of layer 3 connectivity data from the EMS.
0: Disable
Disables download of layer 3 connectivity data from the EMS.
8. You can optionally configure details about the source element management
system (EMS) in the Data Source properties section by configuring the
following generic fields. Data from these fields is used by Network Manager
to model the EMS.
DataSource.id
Unique identifier for the datasource, in the form of an integer. This
field takes the value 1, indicating that this is the primary data source.
Chapter 2. Configuring network discovery
153
DataSource.descr
Description of the EMS.
DataSource.emsHost
Hostname of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsPort
Port of the EMS.
DataSource.emsVersion
Version of the EMS.
DataSource.emsIdentifier
Identifier for the EMS and key to integrate the Network Manager
collector with the Netcool Configuration Manager driver.
DataSource.emsRole
Role of the EMS. This parameter can take one of the following values:
v unknown
v primary
v backup
v other
DataSource.emsStatus
Status of the EMS. This parameter can take one of the following
values:
v unknown
v up
v down
v other
DataSource.emsUserName
Username of the EMS.
DataSource.emsPassword
Password of the EMS.
Note: The default port for Tellabs NIMA is 2462. The EMS identifier for
Tellabs INM8000 must be set to tellabsinm8000. The default EMS username is
nbif and the default EMS password is tellabs8000.
9. Configure the mapping properties to reflect the true state of the Tellabs
interface state. The following parameters represent the mapping of the
Network Manager SNMP variable object ifOperStatus to the Tellabs interface
attribute ifState.
v map.ifoperstatus.undefined
v map.ifoperstatus.planned
v map.ifoperstatus.installed
v map.ifoperstatus.inuse
The descriptions of attribute values for the Tellabs entity interface,
Interface.ifstate, are as follows:
v 0: Undefined
v 1: Planned
v 2: Installed
154
IBM Tivoli Network Manager IP Edition: Discovery Guide
v 3: In use
The mapping for ifOperStatus is as follows:
v
v
v
v
1:
2:
3:
4:
up
down
testing
unknown
v 5: dormant
v 6: notPresent
v 7: lowerLayerDown
Default values for the mapping are as follows:
v map.ifoperstatus.undefined=6
v map.ifoperstatus.planned=3
v map.ifoperstatus.installed=5
v map.ifoperstatus.inuse=1
10. Save the collector configuration file.
Java CSV collector properties file reference:
Use this information to understand how the Java CSV collector properties file is
constructed.
The location of the Java CSV collector properties file within $NCHOME/precision/
collectors/javaCollectors/ is listed in Table 10. Using this .properties file you
can map the network data to one or more files.
Note: Properties specified in the collector-specific properties file override any
related properties specified in the generic Java collector properties file,
$NCHOME/precision/collectors/javaCollectors/framework/collector.properties.
Table 10. Java CSV Collector properties file
Collector
Location of properties file within
Java CSV
collector
csv/csvcollector.properties
Sample .properties file for the Java CSV collector
The following code fragment presents sample settings from a the Java CSV
collector .properties file. This code fragment defines the directory where the CSV
data files are located, and then proceeds to define formatting for CSV data in one
of those files, the devices.csv file, which defines main entity data.
# Directory containing CSV data
CSVDir = ../csv/exampleCsvData/
# Main entity data (device data) is in devices.csv
MainEntityData.file = devices.csv
# The delimiter for the file is a |
MainEntityData.delimiter = \\|
# There are 6 columns of data in the file
MainEntityData.numCols = 6
# Only read lines that start with 10.1.1.
Chapter 2. Configuring network discovery
155
MainEntityData.lineMatch = 10\\.1\\.1\\..+
# Map the first data column to the device management IP address (<ip>)
MainEntityData.1.name = ManagementIpAddress
MainEntityData.1.mapsTo = DEVICE_MANAGEMENT_IP_ADDRESS
# Arbitrary mapping of extra information
# Map column 6 to <extraInfo><systemInfo>...</systemInfo></extraInfo>
MainEntityData.6.name = AdditionalSystemInfo
MainEntityData.6.mapsTo = EXTRA_INFO.systemInfo
Properties and mappings
The Java CSV collector properties files includes the following properties:
Base directory
For the Java CSV collector, the base directory is defined in the CSVDir
property.
Data file properties
For the Java CSV collector, a set of properties are defined for the different
CSV data files used as input.
The following table lists the properties held in CSV data files. For each property,
data_type is one of the supported data types, listed in Table 13 on page 157.
Table 11. Data file properties
Property
Descriptions
data_type.file
File name containing the CSV data.
data_type.delimiter
Delimiter for the data in the CSV file. The
default delimiter is a comma ,.
data_type.lineMatch
Regular expression syntax pattern. This
instructs the collector to read only those
lines that start with the pattern.
data_type.numCols
Number of columns of data in the file.
data_type.useCols
If not all columns are needed, this
expression uses a comma separated list, for
example, 1,3, to indicate which columns of
data to use from the file.
The following table how data in CSV data files is mapped to attributes.
Table 12. Data mappings
156
Property
Descriptions
data_type.column_number.name
Human readable name for the column data.
data_type.column_number.description
Human readable description for the column
data.
data_type.column_number.mapsTo
Mapping to an attribute supported for the
data type.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Data types
The following table lists the supported data types.
Table 13. Data types
Property
Descriptions
MainEntityData
Main entity (device) data.
InterfaceData
Interface data.
EntityData
Entity data in ENTITY-MIB format.
GenericEntityData
Entity data in non-ENTITY-MIB format.
L1ConnectivityData
Layer 1 connectivity data.
L2ConnectivityData
Layer 2 connectivity data.
L3ConnectivityData
Layer 3 connectivity data.
L2VpnData
Layer 2 VPN data.
L3VpnData
Layer 3 VPN data.
L3VpnInterfaceData
Layer 3 VPN interface data.
L3VpnRTData
Layer 3 VPN route target data.
LabelSwitchPathData
Label switch path data.
MplsInterfaceData
MPLS interface data.
Data source configuration
You can optionally configure details about the originating element management
system (EMS) by configuring the fields listed in the following table. If you
configure this EMS information , then data from these fields will be used by
Network Manager to model the EMS.
Table 14. Data source configuration
Property
Descriptions
DataSource.id
This field takes the value 1, indicating that
this is the primary data source.
DataSource.descr
Description of the EMS.
DataSource.emsHost
Hostname of the EMS.
DataSource.emsName
Name of the EMS.
DataSource.emsVersion
Version of the EMS
DataSource.emsIdentifier
Identifier for the EMS
DataSource.emsRole
Role of the EMS. Takes one of the following
values:
v unknown
v primary
v backup
v other
Chapter 2. Configuring network discovery
157
Table 14. Data source configuration (continued)
Property
Descriptions
DataSource.emsStatus
Role of the EMS. Takes one of the following
values:
v unknown
v up
v down
v other
Configuring Perl collectors:
Use this information to configure settings for collectors written in Perl.
Configuring the Nokia5529Idm collector:
To use data from the Nokia5529Idm collector in a network discovery, you must
configure the connection details between the EMS and Network Manager.
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/Alcatel5529IdmSoap/Alcatel5529IdmSoap
Collector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file. Configure the following
properties:
158
Host
The hostname of the EMS.
Port
The port to connect to the EMS.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Username
The username to connect to the EMS.
Password
The password to use to connect to the EMS.
Timeout
The timeout for the SOAP communication between the collector and
the EMS.
Domain
The domain of the AMS system on which the Inventory Data Manager
is running.
GetEntities
A flag for discovery of physical entities such as racks, cards, and ports.
Set to 1 to discover physical entities. If this flag is set to 0, only chassis
information is discovered. The default value is 1.
GetOnt
A flag to configure whether the collector retrieves Optical Network
Terminal (ONT) information. Set to 1 to enable ONT module data
retrieval. Retrieval of ONT information relies on physical entity
information. Ensure that GetEntities is set to 1 if you want to set
GetOnt to 1.
The following example shows example and default values of these properties:
DataSource =>
{
Host => 192.168.1.2,
Port => 8080
Username => ’oss’,
Password => ’myPa55w0rd’
Timeout => 30
Domain => ’AMS’
GetEntities => 1
GetOnt => 0
,
4. Ensure that the Batchsize parameter is set to 500, unless otherwise advised by
IBM Support. This parameter controls the size of each SOAP/XML response.
5. Save the collector configuration file.
Configuring the Alcatel5620Csv collector:
To use data from the Alcatel5620Csv collector in a network discovery, you must
configure the connection details between the EMS and Network Manager.
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/Alcatel5620SamCsv/Alcatel5620SamCsv
Collector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Chapter 2. Configuring network discovery
159
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file and specify the filename of
the CSV loader module configuration file, as shown in the following example.
The CSV loader module configuration file in turn specifies the CSV files and
the .drv driver files that detail how each CSV file is parsed
DataSource =>
{
CsvCfg => ’exampleCsv.cfg’,
...
...
...
},
4. You can optionally configure details about the originating EMS by adding a
SourceInfo subsection to the DataSource section of the configuration file. If you
configure this EMS information , then data from these fields will be used by
Network Manager to model the EMS. To configure details about the EMS, set
values for the fields shown in the following code snippet:
SourceInfo =>
{
Id => 1,
Descr => ’Primary Data Source’,
# EmsHost => ’’,
# EmsName => ’’,
# EmsVersion => ’’,
# EmsIdentifier => ’’,
# EmsRole => ’’,
# EmsStatus => ’’,
},
5. Save the collector configuration file.
160
IBM Tivoli Network Manager IP Edition: Discovery Guide
Configuring the Alcatel5620SamSoap collector:
To use data from the Alcatel5620SamSoap collector in a network discovery, you
must configure the connection details between the EMS and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the Alcatel5620SamSoap collector, complete the following steps:
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/Alcatel5620SamSoap/Alcatel5620SamSoap
Collector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file. Configure the following
properties:
Host
The hostname of the EMS.
Port
The port to connect to the EMS.
Username
The username to connect to the EMS.
Password
The password to use to connect to the EMS.
Timeout
The timeout for the SOAP communication between the collector and
the EMS.
The following example shows example and default values of these properties:
DataSource =>
{
Host => 192.168.1.2,
Port => 8080
Chapter 2. Configuring network discovery
161
Username => ’oss’,
Password => ’myPa55w0rd’,
Timeout => 30,
...
...
...
},
4. Edit the DataAcquisition section of the configuration file and configure the
following properties:
GetEntities
A flag for discovery of physical entities such as racks, cards, and ports.
Set to 1 to discover physical entities. If this flag is set to 0, only the
following information is discovered: chassis, logical entities, and data
for the other enabled flags in the DataAcquisition section. The default
value is 1.
GetVplsVpns
A flag for discovery of VPLS-based Layer 2 VPN data. Set to 1 to
enable discovery of this data. The default value is 1.
GetVllVpns
A flag for discovery of VLL-based Layer 2 VPN data for epipes only.
Set to 1 to enable discovery of this data. The default value is 1.
GetLayer3Vpns
A flag for discovery of Layer 3 VPN data. Set to 1 to enable discovery
of this data. The default value is 1.
GetMplsInterfaces
A flag for discovery of MPLS interface data. Set to 1 to enable
discovery of this data. The default value is 1.
GetLayer2Connections
A flag for discovery of physical link data. Set to 1 to enable discovery
of this data. The default value is 1.
The following example shows the default values of these properties:
DataAcquisition =>
{
GetEntities => 1
GetVplsVpns => 1,
GetVllVpns => 1,
GetLayer3Vpns => 1,
GetMplsInterfaces => 1,
GetLayer2Connections => 1
},
5. 5. Edit the DataProcessing section of the configuration file. Configure the
ContainmentMethod property.
The ContainmentMethod property controls how the entity data is processed in
cases where containment is ambiguous due to missing or duplicate index data,
which can occur with module(card)/slot data.
The possible values of the ContainmentMethod property are:
0
162
Ignore duplicate indexes and prefer slots. Slot entities are stored, but
module (card) entities might be lost if they share the same data as the
slot.
IBM Tivoli Network Manager IP Edition: Discovery Guide
1
Ignore duplicate indexes and prefer cards. Module entities are stored,
but slot entities might be lost if they share the same data as the
module.
2
Keep card and slot entities. Generates a false index if duplicates are
encountered.
The default value is 2.
6. Optional: If you want to retrieve custom data from the EMS in addition to the
data retrieved by default, complete the following steps.
a. Create a new configuration file in the collector directory, or edit the default
file $NCHOME/precision/collectors/perlCollectors/Alcatel5620SamSoap/
extraInfo.cfg.
b. Specify the data to be retrieved, as in the following example:
Device =>
{
extraFields => [ { srcField => ’version’, destField =>
’m_Version’, typeField => ’string’ }]
},
Where srcField is the name of the attribute in the SAM object, destField is
the name of the field to which the data will be mapped within the extraInfo
field, and typeField is an optional type descriptor.
The attribute you want to retrieve must be part of one of the objects already
retrieved by the collector. The objects queried by the collector are:
v netw.NetworkElement
v equipment.PhysicalPort
v lag.Interface
v equipment.MediaAdaptor
v equipment.PhysicalPort
v equipment.DaughterCard
v equipment.Equipment
v equipment.Shelf
v vpls.L2AccessInterface
v vll.L2AccessInterface
v l3fwd.ServiceSite
v vprn.L3AccessInterface
v netw.PhysicalLink
v lldp.RemotePeer.
Valid types are int and string.
c. Save and close the configuration file.
d. Edit the CustomData section of the $NCHOME/precision/collectors/
perlCollectors/Alcatel5620SamSoap/Alcatel5620SamSoap
Collector.cfg collector configuration file. Specify the name and location of
the configuration file that defines the extra information to be collected, as in
the following example:
CustomData =>
{
ExtraInfoCfg => ’extraInfo.cfg’
},
7. Save the collector configuration file.
Chapter 2. Configuring network discovery
163
Configuring the Alcatel5620SamSoapFindToFile collector:
To use data from the Alcatel5620SamSoapFindToFile collector in a network
discovery, you must configure the connection details between the EMS and
Network Manager, and the FTP details using which the XML files can be sent to
the Network Manager server.
You can also configure additional information to be collected from the EMS. To
configure the Alcatel5620SamSoapFindToFile collector, complete the following
steps:
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/Alcatel5620SamSoap
FindToFile/Alcatel5620SamSoap
FindToFileCollector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file.
a.
Specify the hostname and port of the EMS, and the username and
password to connect to the EMS, as shown in the following example:
DataSource =>
{
Host => 192.168.1.2,
Port => 8080
Username => ’oss’,
Password => ’myPa55w0rd’,
Timeout => 30,
...
...
...
},
164
IBM Tivoli Network Manager IP Edition: Discovery Guide
b. Configure the following FTP parameters:
UseSFTP
Boolean flag to determine whether to use SSH FTP (SFTP) for
transfer of XML files.
v UseSFTP = 1: instructs the system to use SFTP.
v UseSFTP = 0: instructs the system to use FTP.
FtpUsername
The FTP username on the Network Manager server.
FtpPassword
The FTP password on the Network Manager server.
FtpHost
The IP address of the Network Manager server.
FtpDefaultDirectory
The default directory of the FTP service on the Network Manager
server.
FtpDirectory
A user-defined directory for the FTP service on the Network
Manager server. Leave this value blank if it is not used.
Tip: After a successful discovery, copy the generated XML files in the
specified FTP directory to another location before performing a new
discovery so that the XML files do not get overwritten.
4. Edit the DataAcquisition section of the configuration file and configure the
following properties:
GetEntities
A flag for discovery of physical entities such as racks, cards, and ports.
Set to 1 to discover physical entities. If this flag is set to 0, only the
following information is discovered: chassis, logical entities, and data
for the other enabled flags in the DataAcquisition section. The default
value is 1.
GetVplsVpns
A flag for discovery of VPLS-based Layer 2 VPN data. Set to 1 to
enable discovery of this data. The default value is 1.
GetVllVpns
A flag for discovery of VLL-based Layer 2 VPN data for epipes only.
Set to 1 to enable discovery of this data. The default value is 1.
GetLayer3Vpns
A flag for discovery of Layer 3 VPN data. Set to 1 to enable discovery
of this data. The default value is 1.
GetMplsInterfaces
A flag for discovery of MPLS interface data. Set to 1 to enable
discovery of this data. The default value is 1.
GetLayer2Connections
A flag for discovery of physical link data. Set to 1 to enable discovery
of this data. The default value is 1.
GetLteData
A flag for discovery of LTE data. Set to 1 to enable discovery of this
data. The default value is 1.
Chapter 2. Configuring network discovery
165
The following example shows the default values of these properties:
DataAcquisition =>
{
GetEntities => 1
GetVplsVpns => 1,
GetVllVpns => 1,
GetLayer3Vpns => 1,
GetMplsInterfaces => 1,
GetLayer2Connections => 1,
GetLteData => 1
}
5. Optional: If you want to retrieve custom data from the EMS in addition to the
data retrieved by default, complete the following steps.
a. Create a configuration file in the collector directory, or edit the default file
$NCHOME/precision/collectors/perlCollectors/Alcatel5620SamSoap/
extraInfo.cfg.
b. Edit the file and specify the data to be retrieved, as in the following
example:
Device =>
{
extraFields => [ { srcField => ’version’, destField =>
’m_Version’, typeField => ’string’ }]
},
Where srcField is the name of the attribute in the SAM object, destField is
the name of the field to which the data will be mapped within the extraInfo
field, and typeField is an optional type descriptor.
The attribute you want to retrieve must be part of one of the objects already
retrieved by the collector. The objects queried by the collector are:
v netw.NetworkElement
v equipment.PhysicalPort
v lag.Interface
v equipment.MediaAdaptor
v equipment.PhysicalPort
v equipment.DaughterCard
v equipment.Equipment
v equipment.Shelf
v vpls.L2AccessInterface
v vll.L2AccessInterface
v l3fwd.ServiceSite
v vprn.L3AccessInterface
v netw.PhysicalLink
v lldp.RemotePeer.
Valid types are int and string.
c. Save and close the configuration file.
d. Edit the CustomData section of the $NCHOME/precision/collectors/
perlCollectors/Alcatel5620SamSoap/Alcatel5620SamSoap
Collector.cfg collector configuration file. Specify the name and location of
the configuration file that defines the extra information to be collected, as in
the following example:
CustomData =>
{
ExtraInfoCfg => ’extraInfo.cfg’
},
166
IBM Tivoli Network Manager IP Edition: Discovery Guide
6. Save the collector configuration file.
Configuring the AlcatelNR8PLIOOISN collector:
To use data from the AlcatelNR8PLIOOISN collector in a network discovery, you
must configure the connection details between the EMS and Network Manager.
You can also configure additional information to be collected from the EMS. To
configure the AlcatelNR8PLIOOISN collector, complete the following steps:
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/AlcatelNR8PLIooIsn/AlcatelNR8PLIooIsn
Collector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file. The following default code
in that section allows Network Manager to communicate with the ISN and the
IOO agents running on the Alcatel NR8 PL EMS:
DataSource =>
{
Timeout => 30,
IOONBI =>
{
Host => ’192.168.1.2’,
IOOAgentPort => 5001,
Timeout => 10,
IOOPassword => ’alcatel’,
IOOInputStream => 4096
}
ISNNBI =>
{
Chapter 2. Configuring network discovery
167
Host => ’192.168.1.2’,
ISNAgentPort => 5002,
ISNUserName => ’ISNTest1’,
ISNReportUnprocessedDirectory => ’./ISNReport’,
ISNReportProcessedDirectory => ’./ISNReportProcessed’,
FtpUsername => ’ftpuser’,
FtpPassword => ’ftpuserpassword’,
FtpSourceDirectory => ’/tmp/report’,
GunzipPath => ’/usr/bin/gunzip’,
}
DataAcquisition =>
{
GetEntities => 1,
GetLayer1Connections => 1
}
}
Set GetEntities to 1 if you want to collect entity information from the collector.
Set GetLayer1Connections to 1 if you want to retrieve layer 1 data from the
collector.
4. You can optionally configure details about the originating EMS by adding a
SourceInfo subsection to the DataSource section of the configuration file. If you
configure this EMS information , then data from these fields will be used by
Network Manager to model the EMS. To configure details about the EMS, set
values for the fields shown in the following code snippet:
SourceInfo =>
{
Id => 1,
Descr => ’Primary Data Source’,
# EmsHost => ’’,
# EmsName => ’’,
# EmsVersion => ’’,
# EmsIdentifier => ’’,
# EmsRole => ’’,
# EmsStatus => ’’,
},
5. Save the collector configuration file.
Configuring the GenericCsv collector:
To use data from the GenericCsv collector in a network discovery, you must
configure the access details from the collector to the data source and configure the
collector to Network Manager listening port. Configuring the collector to data
source access details involves specifying how the collector loads and interprets
CSV files.
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/GenericCsv/GenericCsv
Collector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
168
IBM Tivoli Network Manager IP Edition: Discovery Guide
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file and specify the filename of
the CSV loader module configuration file, as shown in the following example.
The CSV loader module configuration file in turn specifies the CSV files and
the .drv driver files that detail how each CSV file is parsed
DataSource =>
{
CsvCfg => ’exampleCsv.cfg’,
...
...
...
},
4. Save the collector configuration file.
Configuring the HuaweiU2000Imanager collector:
To use data from the HuaweiU2000Imanager collector in a network discovery, you
must configure the connection details between the EMS and Network Manager.
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/HuaweiU2000iManagerTL1/HuaweiU2000iManagerTL1
Collector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 1 to turn debug on. The collector prints debug to the
display (stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Chapter 2. Configuring network discovery
169
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15
},
3. Edit the DataSource section of the configuration file. Specify the hostname and
port of the EMS, and the username and password to connect to the EMS, as
shown in the following example:
DataSource =>
{
Host => 192.168.1.2,
Port => 8080
Username => ’oss’,
Password => ’myPa55w0rd’
GetEntities => 1
DataAcquisition =>
{
StoreONTs => 1,
}
...
...
,
Set GetEntities to 1 if you want to collect entity information from the collector.
Set StoreONTs to 1 if you want to retrieve Optical Network Termination (ONT)
data.
4. You can optionally configure details about the originating EMS by adding a
SourceInfo subsection to the DataSource section of the configuration file. If you
configure this EMS information , then data from these fields will be used by
Network Manager to model the EMS. To configure details about the EMS, set
values for the fields shown in the following code snippet:
SourceInfo =>
{
Id => 1,
Descr => ’Primary Data Source’,
# EmsHost => ’’,
# EmsName => ’’,
# EmsVersion => ’’,
# EmsIdentifier => ’’,
# EmsRole => ’’,
# EmsStatus => ’’,
},
5. Save the collector configuration file.
170
IBM Tivoli Network Manager IP Edition: Discovery Guide
Configuring the HuaweiU2000iManagerTL1DumpExport collector:
To use data from the HuaweiU2000iManagerTL1DumpExport collector in a
network discovery, you must configure the connection details between the EMS
and Network Manager.
The HuaweiU2000iManagerTL1DumpExport collector processes data from Huawei
Access Devices using the Huawei U2000 EMS.
To get data for the collector, complete the following steps:
1. Export the XML file from the Huawei U2000 EMS by using the DMP-INVENTORY
command. Ensure that the EMS parameter name NBI_INVENTORY_DUMP_VERSION
is set to 3.
2. Check that the XML file is in the correct format. The collector supports XML
files with ME, SHELF, CARD, PORT, SERVICEPORT and PORTOFVLAN object
data, in DATAPACKET format. For reference, an example of an XML file used
by the collector is provided in the following location:$NCHOME/precision/
collectors/perlCollectors/HuaweiU2000iManagerTL1DumpExport/data/
sample.xml.
3. Copy the XML file from the EMS to the server where the collector is installed.
Copy the file to the location specified in the FtpDestinationDirectory
parameter in the collector configuration file, as described below. The default
directory is /opt/IBM/netcool/core/precision/collectors/perlCollectors/
HuaweiU2000iManagerTL1DumpExport/data.
To configure the collector, complete the following steps.
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/HuaweiU2000iManagerTL1DumpExport/
HuaweiU2000iManagerTL1DumpExportCollector.cfg
2. Edit the General section of the configuration file. Configure the following
properties:
Debug
The collector debug mode. Set the property to 0 to turn off debug. Set
the property to 4 to turn debug on. Setting this property to 1, 2, or 3 is
equivalent to setting it to 0. The collector prints debug to the display
(stdout).
Listen
The port that the collector listens on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses
to Network Manager. By default the port is 8081. The port must match
the port you have configured in the insert into the
collectorFinder.collectorRules table in the
DiscoCollectorFinderSeeds.cfg file when seeding the collector for a
first discovery.
Timeout
Timeout for the communication from the collector to Network Manager.
The timeout is measured in seconds. The default value is 15 seconds.
QueueSize
The size of the queue that holds XML-RPC requests received by the
collector that are yet to be processed. If the queue is full, that is, if the
collector is receiving requests faster than it can process them, then
Chapter 2. Configuring network discovery
171
requests may be dropped. This results in error messages in the
XML-RPC Helper log. The default value is 40.
The following example shows the default values of these properties:
General =>
{
Debug => 0,
Listen => 8081,
Timeout => 15,
QueueSize => 40
},
3. Edit the DataSource section of the configuration file. Specify the hostname and
port of the EMS, the username and password to connect to the EMS, and the
details of the XML file, as shown in the following example:
DataSource =>
{
Host => 192.168.1.2,
Port => 8080
Username => ’oss’,
Password => ’myPa55w0rd’
FtpDestinationDirectory =>
’/opt/IBM/netcool/core/precision/collectors/perlCollectors/
HuaweiU2000iManagerTL1DumpExport/data’,
XMLDumpFileName =>
’MA5610S.xml,MA5606T.xml’,
Timeout => 30,
DataAcquisition =>
{
GetEntities => 1,
}
...
...
,
Set GetEntities to 1 if you want to collect entity information from the collector.
Set FtpDestinationDirectory to the full directory path to the XML files that
you transfer from the EMS. The default directory is /opt/IBM/netcool/core/
precision/collectors/perlCollectors/HuaweiU2000iManagerTL1DumpExport/
data.
Set XMLDumpFileName to the file name of all the XML files from the EMS. If there
are multiple XML files, use commas to separate the file names. For example,
fileName1.xml,fileName2.xml. For single XML file names, the notation is
fileName1.xml. The default value is with multiple XML file names:
MA5606TN2000.xml,MA5606T.xml.
Set Timeout for the timeout for the communication from the collector to EMS.
The timeout is measured in seconds. The default value is 30 seconds.
4. You can optionally configure details about the originating EMS by adding a
SourceInfo subsection to the DataSource section of the configuration file. If you
configure this EMS information , then data from these fields will be used by
Network Manager to model the EMS. To configure details about the EMS, set
values for the fields shown in the following code snippet:
SourceInfo =>
{
Id => 1,
Descr => ’Primary Data Source’,
# EmsHost => ’’,
# EmsName => ’’,
172
IBM Tivoli Network Manager IP Edition: Discovery Guide
#
#
#
#
EmsVersion => ’’,
EmsIdentifier => ’’,
EmsRole => ’’,
EmsStatus => ’’,
},
5. Save the collector configuration file.
Configuring the Optical Blackbox collector:
To use data from the Optical Blackbox collector in a network discovery, you must
configure the connection details between the EMS and Network Manager.
1. Edit the collector configuration file: $NCHOME/precision/collectors/
perlCollectors/OpticalBlackboxXml/OpticalBlackboxXml
Collector.cfg.
2. Specify the port the collector must listen on for XML-RPC requests from
Network Manager.
This port is also used by the collector to provide XML-RPC responses to
Network Manager. By default the port is 8081. A default timeout of 15 seconds
is also configured. Find and edit the General section of the configuration file, as
shown in the following example:
General =>
{
Debug => 0,
Listen => 8081
Timeout => 15
},
The port must match the port you have configured in the insert into the
collectorFinder.collectorRules table in the DiscoCollectorFinderSeeds.cfg file
when seeding the collector for a first discovery.
3. Edit the DataSource section of the configuration file and specify the filename of
the XML file, as shown in the following example:
DataSource =>
{
BlackboxXml => ’./exampleXmlData/blackbox.xml’,
DataAcquisition =>
{
GetEntities => 1,
GetLayer1Connections => 1
}
}
4. You can optionally configure details about the originating EMS by adding a
SourceInfo subsection to the DataSource section of the configuration file. If you
configure this EMS information , then data from these fields will be used by
Network Manager to model the EMS. To configure details about the EMS, set
values for the fields shown in the following code snippet:
SourceInfo =>
{
Id => 1,
Descr => ’Primary Data Source’,
# EmsHost => ’’,
# EmsName => ’’,
# EmsVersion => ’’,
# EmsIdentifier => ’’,
# EmsRole => ’’,
# EmsStatus => ’’,
},
5. Save the collector configuration file.
Chapter 2. Configuring network discovery
173
Starting collectors:
Before discovery starts, all the collectors must be running. You must start the
collectors or make sure the collectors are running before starting a discovery that
includes collectors.
Starting Java collectors:
Use this information to start collectors written in Java.
You start a Java collector by going to the Java collector bin directory at
$NCHOME/precision/collectors/javaCollectors/bin and issuing a command-line
interface command. Issue the following command to start a Java collector (note
that the command is entered on one line; options are explained in Table 15):
collector.sh -jar [ -Xmsminimum_memory-sizem ] [ -Xmxmaximum_memory-sizem ]
jar_file -propsFile file_name -port port_number [ -bg ]
Table 15. Explanation of command-line options
Option
Explanation
-jar jar_file
Required: path to the jar file for the collector to be
run relative to the root Java collector directory; for
example, csv/csvcollector.jar.
-propsFile file_name
Optional: path to the properties file for the collector.
The default is specified by the collector; for
example, for the CSV collector the default is
../csvcollector.properties.
-port port_number
Optional: port on which to run the collector. Default
value is 8080.
Note: This value can also be specified in a collector
properties file.
-bg
Optional, and on UNIX only. Use this parameter to
run the collector in the background.
Note: Do not use the standard UNIX & parameter
to run a collector in the background. Use the -bg
option only.
[ -Xmsminimum_memory-sizem ]
Optional: the minimum heap size for the collector.
Increase the heap size settings if you receive errors
relating to the collector process being out of
memory. The default minimum heap size is 256M.
[ -Xmxmaximum_memory-sizem ]
Optional: the maximum heap size for the collector.
Increase the heap size settings if you receive errors
relating to the collector process being out of
memory. The default maximum heap size is 768M.
Example: starting the Java CSV collector
To start the Java CSV collector, perform the following steps:
1. Go to the following directory:
$NCHOME/precision/collectors/javaCollectors/bin
2. Run the following command to start the Java CSV collector with the default .jar
and property files, on port 8089, with minimum heap size of 512M and
maximum heap size of 1024M:
./collector.sh -Xms512m -Xmx1024m -jar csv/csvcollector.jar -propsFile
csv/csvcollector.properties -port 8089 -bg
174
IBM Tivoli Network Manager IP Edition: Discovery Guide
Stopping Java collectors:
Use this information to stop collectors written in Java.
You stop a Java collector by going to the Java collector bin directory at
$NCHOME/precision/collectors/javaCollectors/bin and issuing a command-line
interface command. A Java collector can be stopped on a local machine or on a
remote machine by issuing this command. Issue the following command to stop a
Java collector (note that the command is entered on one line; options are explained
in Table 16):
shutdown_collector.sh -port port_number -host host_name
Table 16. Explanation of command-line options
Option
Explanation
-port port_number
Required: port on which the collector to be shut
down is running.
-host host_name
Optional: hostname of the server on which the
collector to be shut down is running. Default value
is localhost.
Example: stopping a Java collector running on the local server on port 8080
To stop a Java collector running on the local server on port 8080, perform the
following steps:
1. Go to the following directory:
$NCHOME/precision/collectors/javaCollectors/bin
2. Run the following command:
shutdown_collector.sh –port 8080
Starting Perl collectors:
Use this information to start collectors written in Perl.
You start a collector by going to the relevant collector directory and issuing a
command-line interface command. Issue the following command to start a collector
(note that the command is entered on one line; options are explained in the table
below):
ncp_perl collector_script -cfg COLLECTOR_CONFIG_FILE
[ -csvcfg CSV_COLLECTOR_CONFIG_FILE ] [ -listen PRECISION_PORT ]
[ -debug DEBUG ] [ -logdir ] [ -nologdir DIRNAME ]
[ -help ] [ -version ]
Table 17. Explanation of command-line options
Option
Explanation
collector_script
The name of the perl script that implements the
collector; for example, main.pl.
-cfg COLLECTOR_CONFIG_FILE
Specifies the collector configuration file.
-csvcfg CSV_COLLECTOR_CONFIG_FILE
Use this optional parameter to specify the name of a
CSV file to use as a data source. You can also
specify this parameter within the collector
configuration file.
Restriction: This parameter is valid only when the
data source is a CSV file.
Chapter 2. Configuring network discovery
175
Table 17. Explanation of command-line options (continued)
Option
Explanation
-listen PRECISION_PORT
An alternative method to specify the port on which
the collector must listen for requests from Network
Manager. Only specify a value here if no port value
has been specified in the SOAP-based collector
configuration file or in the CSV-based collector
configuration file.
-debug DEBUG
The level of debugging output (1-4, where 4
represents the most detailed output).
-logdir DIRNAME
Directs log messages for each process started by
CTRL to NCHOME/log/precision.
-nologdir DIRNAME
Directs log messages for each process started by
CTRL to a separate file in the specified directory.
-help
All Network Manager components have a special
-help option that displays the command line
options. The component is not started even if –help
is used in conjunction with other arguments.
-version
All Network Manager components have a special
-version option that displays the version number of
the component. The component is not started even
if –version is used in conjunction with other
arguments.
Seeding an EMS discovery:
Seed the EMS discovery by seeding the Collector finder. This is typically a
one-time setup task required when a new collector is added to your installation.
To enable Network Manager to find the collectors, you must seed the Collector
finder. Seeding the Collector finder involves specifying for each collector:
v The hostname of the device on which the collector is running.
Note: The hostname is not required when the collector is running on the same
server as the Network Manager discovery.
v The port on that device on which the collector is listening.
If a collector is running on the same host as Network Manager, then you need only
specify the port.
Note: If you are rediscovering a device using the Collector finder, then specify the
IP address of the device or subnet to rediscover using the Discovery Configuration
GUI.
You can seed the Collector finder to perform a discovery or to perform a partial
rediscovery of a single device or subnet. If you seed the Collector finder to
perform a partial rediscovery, then you can also specify a single device or subnet
retrieved by the collector.
You must seed the Collector finder with the host name of the device on which the
collector is running, and the port on that device on which the collector is listening.
If the collector is running on the same host as Network Manager, then you need to
specify only the port.
176
IBM Tivoli Network Manager IP Edition: Discovery Guide
Seeding the Collector for a first discovery
You seed the Collector finder for a first discovery by appending an insert into the
collectorFinder.collectorRules table to the DiscoCollectorFinderSeeds.cfg
configuration file. The following insert seeds the Collector finder with a host name
of 172.16.25.1, and a port of 8082. This insert means that the collector is running on
a host with IP address 172.16.25.0, which is different to the host on which Network
Manager is running. The override number of retries for this collector is 5.
insert into collectorFinder.collectorRules
(
m_Host,
m_Port,
m_NumRetries
)
values
(
"172.16.25.1",
8082,
5
);
Related concepts:
“Seeds” on page 13
Configure seeds to specify the locations from which to begin discovering devices.
Discovery seeds can be IP addresses, or subnet addresses.
Discovering aggregated links:
As part of an EMS discovery, you can retrieve information about some links that
are logically aggregated.
Network Manager can discover and model link aggregation information from
devices running the Alcatel 5620 SAM EMS.
To discover aggregated link information, complete the following tasks:
1. Configure the Alcatel 5620Sam Java collector.
2. Run a discovery.
3. Open the Structure Browser and examine a device that contains aggregated
links. The aggregated links are shown within the device containment.
A Service Affected Event (SAE) is generated if any port that participates in an
aggregated link has an alert of severity 5 or higher.
Related tasks:
“Configuring collectors” on page 113
The purpose of a collector is to gather and standardise EMS data based on requests
by the main Network Manager discovery process, for consumption by the
discovery process. Collector configuration governs how the collector interrogates
the EMS or data source in order to service requests from the Network Manager
discovery process, and how the collector listens for requests from the Network
Manager discovery process.
Chapter 2. Configuring network discovery
177
Turning off isolated suppression for RCA:
To ensure that RCA works correctly for EMS discoveries, you must turn off
isolated suppression.
Network Manager applies an RCA model to the network that assumes a single
location from which polling is carried out. In EMS discoveries, there are,
effectively, multiple polling locations. In order for RCA to function correctly, you
need to turn off the RCA rule known as isolated suppression.
To turn off isolated suppression, complete the following tasks:
1. Edit the following file: $NCHOME/precision/eventGateway/stitchers/RCA/
ProcessProblemEvent.stch
2. Comment out the following line:
numberOfSuppressedEvents = ExecuteStitcher(’IsolatedEntitySuppression’);
3. Save and close the file.
4. Restart the Event Gateway, ncp_g_event.
Adding passive entities to the network
You can use the blackbox service to define passive layer 1 entities in your network
so that these unmanaged entities are represented in your network. Passive entities
are user-defined entities that are additional entities that you want to see in your
topology to have a complete picture of your network environment.
Restriction: You can only add layer 1 entities to the network using the blackbox
service.
About passive entities:
Passive layer 1 entities are user-defined entities that are additional entities that you
want to see in your topology to have a complete picture of your layer 1 network
environment. They are passive in that you cannot use Network Manager to
discover or manage them, but you can still see them represented in topology maps.
You can use passive entities in various ways. For example:
v To show unmanaged nodes in your network.
v To show devices that are unmanaged by Network Manager. For example, a cable
provider uses filters between network equipment to increase or modify signals.
In many cases, these filters are not manageable, but they can be added to the
blackbox service to show better granularity of the network.
Configuring the blackbox collector:
You must perform one-time configuration tasks before you can use the blackbox
collector to add passive entities to the network.
Table 18. Configuring the blackbox collector
Configuration task
Further information
Configure the blackbox collector.
“Configuring Perl collectors” on page 158
To do this, you must edit the blackbox
collector configuration file, which is located
at:$NCHOME/precision/collectors/
perlCollectors/OpticalBlackboxXml/
178
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 18. Configuring the blackbox collector (continued)
Configuration task
Further information
Seed the blackbox collector discovery by
“Seeding an EMS discovery” on page 176
configuring the $NCHOME/etc/precision/
DiscoCollectorFinderSeeds.cfg file for your
domain to use same port as stated in the
blackbox collector configuration file
OpticalBlackboxXmlCollector.cfg.
Adding passive entities:
Import data about passive devices and other entities by editing and loading the
blackbox.xml file.
Editing the blackbox.xml file:
Define passive devices and other entities by editing the blackbox.xml file.
1. Go to $NCHOME/precision/collectors/perlCollectors/OpticalBlackboxXml/
exampleXmlData directory.
2. Edit the blackbox.xml file and supply the data you want to import inside the
<blackbox> element. Use the appropriate tags inside the <blackbox>element for
the entity information you want to import. When editing the blackbox.xml file,
note the following rules:
3. Save and close the file.
Structure of blackbox.xml:
The blackbox.xml file is used to load passive (unmanageable) entities in your
network so that you can view them in a topology map.
Use this example of a blackbox.xml file to understand the syntax of statements
allowed in the file.
1]
<blackbox>
2]
3]
<ne name="Passive_NE1" ip="10.20.1.2" type="Passive">
4]
<properties>
5]
<property name="company" value="IBM"/>
6]
</properties>
7]
<entities>
8]
<entity tom_id="rack" type="FLEX_Bay" position="1" />
9]
<entity tom_id="shelf" type="FLEX_shelf" position="1-1" />
10]
<entity tom_id="shelf" type="FLEX_shelf" position="1-2" />
11]
<entity tom_id="card" type="OC12Card" position="1-2-1" />
12]
<entity tom_id="card" type="TRMTR_Slot_HS" position="1-9-1" />
13]
<entity tom_id="ptp" type="OC12_LS_PTP_V" position="1-2-1-1" />
14]
<entity tom_id="ptp" type="OC48_LINE_PTP_TRMTR_HS" position=
"1-9-1-1" />
15]
<entity tom_id="ctp" type="STS3_OC48_TRMTR_HS" position=
"1-9-1-1-25" />
16]
</entities>
17]
</ne>
18]
19]
<ne name="Passive_NE2" ip="10.11.1.30" type="ECI">
20]
<properties>
21]
<property name="Vendor" value="ECI"/>
22]
<property name="NeType" value="XDM100"/>
23]
<property name="LocationName" value="MELAKA"/>
24]
<property name="Address" value="THIRD FLOOR , COLLEGE ,
Chapter 2. Configuring network discovery
179
MELAKA , , Malaysia"/>
25]
<property name="City" value="MELAKA"/>
26]
<property name="State" value="ALOR GAJAH"/>
27]
</properties>
28]
<entities>
29]
<entity type="FLEXPort" tom_id="ptp" label="PORT" position=
"1-1-3021-1" />
30]
<entity type="FLEXPort" tom_id="ptp" label="PORT" position=
"1-1-3022-1" />
31]
</entities>
32]
</ne>
33]
34]
<ne name="Passive_NE3" ip="10.11.1.29" type="ECI">
35]
<properties>
36]
<property name="Vendor" value="ECI"/>
37]
<property name="NeType" value="XDM100"/>
38]
<property name="LocationName" value="ARAU KANGAR"/>
39]
<property name="Address" value="3 Ground , Sate Road ,
Arau, Kangar "/>
40]
<property name="City" value="KANGAR"/>
41]
<property name="State" value="PERLIS"/>
42]
</properties>
43]
<entities>
44]
<entity type="FLEXPort" tom_id="ptp" label="PORT" position=
"1-1-3036-2" />
45]
<entity type="FLEXPort" tom_id="ptp" label="PORT" position=
"1-1-3033-1" />
46]
</entities>
47]
</ne>
48]
49]
<tc>
50]
<aend ne="Passive_NE2" tp="1-1-3021-1"/>
51]
<zend ne="Passive_NE1" tp="1-9-1-1-25"/>
52]
</tc>
53]
54]
<tc>
55]
<aend ne="Passive_NE3" tp="1-1-3036-2"/>
56]
<zend ne="Passive_NE2" tp="1-1-3022-1"/>
57]
</tc>
58]
59]
</blackbox>
The table below describes this query.
Table 19. Example of a blackbox.xml file
Line numbers
Element
Description and attributes
1-59
<blackbox>
Blackbox. Does not take attributes.
3-17
<ne>
Network element. Takes the following attributes:
19-32
34-47
4-6
<properties>
20-27
35-42
180
IBM Tivoli Network Manager IP Edition: Discovery Guide
name
(Required) The name of the network element.
Example: name="Passive_NE1".
type
(Required) A value of type ="Passive" indicates
a passive entity.
ip
(Optional) IP address of the passive entity.
The properties of the entity to which the element applies.
Table 19. Example of a blackbox.xml file (continued)
Line numbers
Element
Description and attributes
5
<property>
A property of the entity. The entity might be a network
element or topological connection.
21-26
name
(Required) Name of the property. Example:
name="company".
value
(Required) The property value. Example:
value="IBM".
36-41
7-16
<entities>
The entities within a network element.
<entity>
An entity within a network element.
28-31
43-46
8-15
label
29-30
(Optional) Label for this entity.
position
44-45
(Required) The relative location of the entity
within the network element. Example:
position="1-2-1-1" means the first rack - second
shelf - first card, first PTP. As a best practice, list
the entity statements in a descending
hierarchical order.
tom_id (Required) The Telecom Object Model ID.
Example: tom_id="rack". Valid values are:
v rack
v shelf
v card
v ptp (physical termination point)
v ctp (connection termination point)
type
49-52
(Optional) The type of entity. Example:
type="FLEX_Bay".
<tc>
A topological connection.
<aend>
The notional start of a topological connection.
54-57
50
55
domain
(Optional) The name of the domain to which the
endpoint belongs (the domain name of the PTP
and the network element to which the PTP
belongs). You can use this attribute to specify
that one of the endpoints resides in some other
network domain. If the remote network element
exists in the database, a topological connection
is created. If it does not exist in the database, no
topological connection is created.
ne
(Required) The name of the network element.
tp
(Required) The relative location of the
termination point of the endpoint in the
topological connection. Example: tp="1-1-3021-1"
means the first rack - first shelf - card 3021 first termination point.
Chapter 2. Configuring network discovery
181
Table 19. Example of a blackbox.xml file (continued)
Line numbers
Element
Description and attributes
51
<zend>
The notional end of a topological connection.
56
domain
(Optional) The name of the domain to which the
endpoint belongs (the domain name of the PTP
and the network element to which the PTP
belongs). You can use this attribute to specify
that one of the endpoints resides in some other
network domain. If the remote network element
exists in the database, a topological connection
is created. If it does not exist in the database, no
topological connection is created.
ne
(Required) The name of the network element.
tp
(Required) The relative location of the
termination point of the endpoint in the
topological connection. Example: tp="1-1-3036-2"
means the first rack - first shelf - card 3036 second termination point.
Loading the blackbox.xml file:
Start the OpticalBlackboxXml collector to load the blackbox.xml file and import the
passive entities into the topology.
Make sure that there is no discovery currently running. However, the Discovery
engine ncp_disco can be running.
Start the OpticalBlackboxXml collector in the background by issuing the following
command:
ncp_perl main.pl -cfg OpticalBlackboxXmlCollector.cfg &
Collector Developer Guide
Advanced users can use the Collector Developer Guide to create custom discovery
collectors.
The Collector Developer Guide provides reference information to support creating
and troubleshooting your own discovery collector.
Access the Collector Developer Guide, and the Perl and Java Collector Framework
documentation, at this URL: https://www.ibm.com/developerworks/community/
wikis/home?lang=en#!/wiki/Tivoli%20Network%20Manager/page/Collector
%20Developer%20Guides
Configuring MPLS discoveries
Configure an MPLS discovery to discover core MPLS networks and the VPNs that
use these core networks. Advanced MPLS discovery configuration provides extra
customization facilities.
182
IBM Tivoli Network Manager IP Edition: Discovery Guide
About MPLS discovery
Administrators within service providers who offer Multiprotocol Label Switching
(MPLS) VPN services can discover MPLS core networks and MPLS VPNs to enable
NOCs within the service provider to monitor the health of customer VPNs.
Network Manager supports the discovery of the following VPNs running across
MPLS core networks:
v Layer 3 VPNs
v Enhanced Layer 2 VPNs
For the enhanced Layer 2 VPNs, Network Manager discovers point-to-point
pseudowires linking two provider edge (PE) routers.
The following sections specify the terminology and topology visualization
conventions used in Network Manager to refer to MPLS networks.
Note: The graphics shown in this section are conceptual representations of an
MPLS network only. You cannot see these conceptual views in the Network Views
graphical user interface (GUI).
Layer 3 MPLS VPNs:
Network Manager can visualize layer 3 MPLS VPN topologies in a core view or an
edge view.
The core view and edge view differ as follows:
v The core view shows the provider-edge (PE) routers, and provides visibility of
the provider core (P) routers and label switched path (LSP) data within the
MPLS core, for each of the VPNs running across the MPLS core.
v The edge view shows the PE routers and the MPLS cloud only. It does not
provide visibility of the devices in the core.
Enhanced Layer 2 MPLS VPNs:
For enhanced Layer 2 VPNs, Network Manager provides only an edge view of
your MPLS core network.
Network Manager displays an enhanced Layer 2 VPN as a collection of
point-to-point pseudowires. This means that if an enhanced Layer 2 VPN contains
more than two provider edge (PE) routers, then Network Manager displays that
VPN in multiple views, each view consisting of a single PE to PE point-to-point
connection.
Table 20 shows examples of enhanced Layer 2 VPNs with two and more than two
PEs. The table also provides the number of pseudowires, and hence the number of
views that Network Manager displays for each VPN.
Table 20. Number of pseudowires for an enhanced Layer 2 VPN
Number of PEs in an
Enhanced Layer 2 VPN
Number of point-to-point
pseudowires
Number of Views Network
Manager displays for this
VPN
2
1
1
3
3
3
4
6
6
Chapter 2. Configuring network discovery
183
Standard and advanced MPLS discovery configuration:
Configure a standard MPLS discovery to discover all of your MPLS network and
uses default naming convention for the VPNs discovered. The standard MPLS
discovery configuration also enables the display of service-affected events (SAEs)
in the Event Viewer. Advanced MPLS discovery configuration provides extra
customization facilities.
Configuration activities for an MPLS network include seeding, scoping, and the
other standard discovery activities.
Standard and advanced MPLS discovery configuration differ as follows:
v Standard MPLS discovery: discovers all of your MPLS network and uses default
naming convention for the VPNs discovered
v Advanced MPLS discovery: using the advanced configuration options you can:
– Restrict the scope of the discovery to a particular VPN or VRF
– Configure your own VPN naming conventions
– Add label data for MPLS discoveries
After you have configured and run an MPLS discovery, your operators can
monitor customer VPNs in the following ways:
v View topology maps of selected VPNs, showing the alert status of the VPNs and
of the devices in the VPNs .
v Identify service-affected events (SAEs) in the Event Viewer. An SAE is an alert
that warns operators that a critical customer service, for example, a customer
VPN, has been affected by one or more network events. The underlying network
events are on an interface on either a PE router or a CE router.
About Service Affected Events:
A Service Affected Event (SAE) alert warns operators that a critical customer
service has been affected by one or more network events.
An SAE is produced when one or more events occur on a Provider Edge (PE) or
Customer Edge (CE) interface in a Virtual Private Network (VPN) or Virtual
Private LAN Service (VPLS). The underlying network events are on an interface of
a PE router or a CE router, or on the link between them. You must configure the
MPLS discovery to infer the existence of CE routers so all possible SAEs are
generated for your customer VPNs.
The following list gives two examples of SAE events generated on two different
customer VPNs:
v SAE generated on customer-1 VPN because of an Mpls VRF Down trap on a PE
router interface
v SAE generated on customer-3 VPN because of a LinkDown trap on a CE router
interface
Each SAE appears as an alert in the Event Viewer. The appearance of the SAE
warns operators that a customer VPN has been affected, possibly critically, by one
or more network events. Operators can right-click the SAE and issue a command
to view the underlying events that caused the SAE.
184
IBM Tivoli Network Manager IP Edition: Discovery Guide
For more information about the Event Viewer, see the IBM Tivoli Netcool/OMNIbus
Web GUI Administration and User's Guide.
Configuring standard MPLS discovery
Configure an MPLS discovery to discover core MPLS networks and the VPNs that
use these core networks.
In addition to the standard discovery configuration activities, you must perform
some MPLS-specific discovery configuration activities:
v Configure MPLS agents
v Optional: set VPNs to be named by Route Targets rather than by VRFs
v Configure SNP and Telnet to ensure that the agents can access network devices
v Configure Network Manager to infer the existence of CE routers. This step is
necessary to enable operators to view service-affected events in the Event
Viewer.
These EMS-specific discovery configuration activities are described in the following
topics.
Configuring MPLS agents:
As part of MPLS discovery configuration you must enable one or more MPLS
agents. You can also resolve the problem of duplicate IP addresses in different
Virtual Private Networks (VPNs) by configuring the AsAgent agent.
The following MPLS agents and the corresponding agent definition (.agnt) files are
provided:
v Juniper Telnet agent (JuniperMPLSTelnet.agnt)
v Juniper ERX router agent (UnisphereMPLSTelnet.agnt)
v Cisco MPLS Telnet agent (CiscoMPLSTelnet.agnt)
v Cisco MPLS SNMP agent (CiscoMPLSSnmp.agnt)
v Laurel MPLS Telnet agent (LaurelMPLSTelnet.agnt)
Note: The Laurel MPLS Telnet agent is intended for RT- (RouteTarget) based
discoveries only.
These agents can discover MPLS VPN and Virtual Private LAN Service (VPLS)
data from devices in the network.
Tip: Agents that retrieve VPLS information can retrieve large amounts of data.
Enabling these agents can add significant processing time to the discovery process.
If you do not need to rediscover VPLS information, disable these agents for a faster
discovery.
Note: If you have an MPLS network that supports both Layer 3 and enhanced
Layer 2 VPNs, then the same MPLS agents discover both types of VPN. Network
Views can also partition both Layer 3 and enhanced Layer 2 VPNs simultaneously
on the same core MPLS network.
If your MPLS network contains Cisco equipment, enable both the Cisco MPLS
Telnet and Cisco MPLS SNMP agents. These two agents complement each other, as
follows:
v Cisco MPLS SNMP agent targets only devices with an Internetwork Operating
System (IOS) that fully supports SNMP-based MPLS discovery
Chapter 2. Configuring network discovery
185
v CiscoMPLSTelnet agent targets only devices running an IOS that does not fully
support an SNMP-based discovery
Attention: Use caution when altering the CiscMPLSSnmp.agnt file. Some network
devices might contain IOS versions that have a flaw that might affect the device
when certain MPLS SNMP data is requested. These IOS versions have been filtered
out by default in the CiscMPLSSnmp.agnt file.
In addition to these standard discovery configuration activities, you can also
change the scope of the MPLS discovery by restricting the scope to specific VPNs
or VRFs.
Related tasks:
“Defining the scope of an MPLS/VPN discovery” on page 192
When configuring the discovery of one or more Virtual Private Networks ( VPNs )
running across an MPLS core, you can restrict the scope of this discovery to a
particular VPN name or VPN Routing and Forwarding (VRF) table name.
Configuring MPLS Telnet agents:
The CiscoMPLSTelnet, JuniperMPLSTelnet, LaurelMPLSTelnet, and
UnisphereMPLSTelnet agents obtain data from devices primarily through Telnet.
You must enable these agents and configure Telnet access to ensure that MPLS
Telnet agents can access devices and can understand the output from devices.
Do the following to configure Telnet access for MPLS Telnet agents:
1. Populate the Telnet configuration file TelnetStackPasswords.cfg so the agents
can access the target devices.
2. Configure the Telnet Helper so that agents can understand the output from
devices.
Related tasks:
“Configuring device access” on page 32
Specify SNMP community strings and Telnet access information to enable helpers
and Network Manager polling to access devices on your network.
Related reference:
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
Configuring MPLS SNMP agents:
The CiscoMPLSSnmp agent obtains data from devices using SNMP. You must
enable this agent and configure SNMP access to ensure that this agent can access
devices and can understand the output from devices.
To configure SNMP access for MPLS SNMP agents:
Note: The CiscoMPLSSnmp.agnt attempts to retrieve the L2 VPNs using the telnet
'show' commands if the agent fails to retrieve the data via SNMP.
1. Configure SNMP access to devices.
2. Configure the SNMP Helper so that agents can understand the output from
devices.
Related tasks:
186
IBM Tivoli Network Manager IP Edition: Discovery Guide
“Configuring device access” on page 32
Specify SNMP community strings and Telnet access information to enable helpers
and Network Manager polling to access devices on your network.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
Configuring the AsAgent agent:
To resolve the problem of duplicate IP addresses in different VPNs, activate the
AsAgent agent and provide Network Manager with a mapping file, ASMap.txt, that
contains a complete list of devices in each VPN, together with an AddressSpace tag,
which defines which VPN the device belongs to.
During an MPLS discovery, Network Manager might discover devices in different
VPNs with identical IP addresses. In this case, Network Manager cannot
differentiate between these devices and might resolve device connectivity
incorrectly. The devices in question might be the CE routers at the edge of the
VPNs, or might be devices within the VPNs.
In the ASMap.txt mapping file, provide a complete list of devices in each VPN,
together with an AddressSpace tag, which defines which VPN the device belongs
to.
Table 21 provides a description of the AsAgent agent that you need to activate to
resolve the problem of duplicate IP addresses.
Table 21. AsAgent agent
Agent name
Function
AsAgent
Enables Network Manager to uniquely identify devices in different
VPNs with identical IP addresses, and thereby correctly resolve device
connectivity. This agent works in conjunction with the
ASRetprocessing.stch stitcher and with the ASMap.txt file in
NCHOME/precision/etc.
Table 22 provides the format of the ASMap.txt file by showing an example of the
content of this file. Fields in this text file must be separated by tabs.
Table 22. Format of ASMap.txt file
Base Name
Address Space
IP Address
CERouter-1
CUSTOMER-1
192.168.2.1
CEDevice-a
CUSTOMER-1
192.168.2.21
CEDevice-b
CUSTOMER-1
192.168.2.22
CEDevice-c
CUSTOMER-1
192.168.2.23
CERouter-2
CUSTOMER-2
192.168.2.1
CEDevice-a
CUSTOMER-2
192.168.2.31
CEDevice-b
CUSTOMER-2
192.168.2.32
Chapter 2. Configuring network discovery
187
Using RT values instead of VRF names:
By default, VPNs are named based on the familiar VRF names. You can choose to
use Route Targets instead to name VPNs.
Important:
If devices have previously been discovered with VRF naming, duplicate VPN
entities might be displayed on the next discovery. For example, the same VPN
entity can appear twice, once with the VRF name and once with the RT value. To
avoid duplicate device entries, set the LingerTime of all devices in the topology to
zero before running your next discovery. To do this, proceed as follows:
1. Log into the OQL Service Provider using the following command:
ncp_oql -domain NCOMS -service Model
2. Run the following command to set the LingerTime to zero:
update ncimCache.lingerTime set lingerTime = {LINGERTIME=0};
go
For MPLS networks, Network Manager uses Route Target (RT)-based discovery,
using VRF and RT information to determine which provider edge routers are
involved in a VPN. The core view consists of all MPLS-enabled devices, and VPNs
resolve based on RT information.
To use RT values instead of VRF names:
1. Exit all instances of the Discovery Configuration GUI.
2. Go to the NCHOME/etc/precision directory.
3. Edit the DiscoConfig.DomainName.cfg file and set the m_RTVPNResolution field
to 1 in the disco.config table. The default is 2 (use VRF).
4. Restart the ncp processes to read the configuration files again:
itnm_stop ncp
itnm_start ncp
Alternatively, restart the ncp_config process.
Note: RT-based discoveries do not require label data. However, you can retrieve
the label data as described in “Fine-tuning label data” on page 193.
Inferring the existence of CE routers:
You can infer the existence of your customers’ CE routers by making specifications
in the advanced discovery configuration options within the Discovery
Configuration GUI.
If the host on which Network Manager is installed has no access to your
customers’ CE routers, then Network Manager cannot discover these routers
directly. This situation typically occurs when the company providing MPLS
services owns the PE routers but has no access to CE routers, which are owned by
the customers running the VPNs.
Note: This situation does not occur if the company providing MPLS services owns
and manages both PE and CE routers and therefore has access to both sets of
devices.
To infer the existence of your customers’ CE routers, specify this in the advanced
discovery configuration options within the Discovery Configuration GUI.
188
IBM Tivoli Network Manager IP Edition: Discovery Guide
Note: You should do this only where the PE interface is on a /30 subnet. In this
case, the other device on the subnet must be the CE router, and the IP address of
the CE will be the other address on the /30 subnet.
Limitations on inferring CE routers:
v Avoid inferring the existence of CE routers if your PE routers are connected to
the CE routers by serial links and you know that there is IP address duplication
among the CE routers and devices within the MPLS core network. Network
Manager will remove from the topology any discovered MPLS core routers that
have the same IP address as an inferred CE IP address.
v If your PE routers are connected to the CE routers by Ethernet, you can infer the
existence of CE routers without needing to perform any other checks. In this
case, Network Manager can determine the MAC address of the CE router. If
Network Manager has discovered another device with the same MAC address,
then it must be the CE router. In this case, Network Manager uses the
discovered device data and does not infer the existence of the CE.
Related reference:
“Advanced discovery parameters” on page 46
Advanced settings control features of the discovery such as concurrent processes
and timeouts. Use these parameters to increase the speed of the discovery, but
balance the speed with the load on the server. Generally, a faster discovery results
in more memory usage on the server.
Configuring advanced MPLS discovery
Configure an advanced MPLS discovery for extra customization facilities not
included in the standard MPLS discovery.
When you configure an advanced MPLS discovery, you must perform the
following activities in addition to the activities required for a standard MPLS
discovery.
v Define the scope of the MPLS discovery: enables you to restrict the scope of this
discovery to a particular VPN or VRF.
v Specify a VPN name: enables you to configure your own VPN naming
convention
v Fine-tune label data discovery: enables you to manually retrieve label data for
MPLS discoveries
Configuring discovery of MPLS Traffic Engineered tunnels:
To discover MPLS Traffic Engineered tunnels, enable the StandardMPLSTE agent,
configure the information that is retrieved, and configure the scope of the
discovery.
MPLS Traffic Engineered tunnel discovery modes:
Set the discovery mode according to how much detail you want to retrieve.
A mode-switch is provided in the discovery agent configuration file that configures
specific tunnel instances, which can be wildcarded, to retrieve different amounts of
tunnel data. You can choose any of the following modes.
HeadEndHops (default)
In HeadEndHops mode, the agent retrieves head-end and tail-end of the
tunnel, and the transit LSRs and next-hop interfaces are identified by
Chapter 2. Configuring network discovery
189
querying the head-end LSR for computed and actual-route hop data. The
actual and computed route data is retrieved from the
mplsTunnelARHopTable and mplsTunnelCHopTable MIB tables
respectively. This discovery mode does not store transit and tail-end tunnel
instances against transit and tail-end LSRs. A connection is created in the
MPLS TE topology between the head-end and tail-end LSR interfaces via
transit device hops (if present) which are associated with the head-end LSR
tunnel object for the appropriate tunnel interface.
MPLS cross-connect pointers that are discovered and resolved on the head
tunnel will be resolved to the appropriate LSP ID where possible.
You can use this information to determine if the actual path taken by a
tunnel is different to the path computed by the Compute Shortest Path
First (CSPF) calculations. You can see the computed and actual path,
although there is no way to determine that an LSR is acting in a transit or
tail capacity without looking at the head-end LSR tunnel data.
Note: Actual route data is only available if the Record Route Option (RRO)
has been specified for the tunnel instance.
In the schema of the scope.mplsTe table, the HeadEndHops mode maps to
value 1 of m_Mode.
HeadTailEnd
In HeadTailEnd mode, only MPLS TE tunnel head-end and tail-end points
are resolved, by querying the head-end Label Switching Router (LSR). This
mode provides the minimal amount of information about the MPLS TE
tunnels. A connection in the MPLS TE topology is created between the
head-end and tail-end LSR interfaces. A tunnel resource instance is
associated with the head-end tunnel LSR entity.
In this mode, you cannot identify the transit LSRs, and computed and
actual route data is not retrieved.
MPLS cross-connect pointers that are discovered and resolved on the head
tunnel will be resolved to the appropriate LSP ID where possible.
In the schema of the scope.mplsTe table, the HeadTailEnd mode maps to
value 2 of m_Mode.
AllLSRTunnelsAndHops
In AllLSRTunnelsAndHops mode, the agent retrieves the head-end and
tail-end of the tunnel and identifies transit LSRs and next-hop interfaces by
querying the head-end LSR for computed and actual route hop data. The
actual and computed route data is retrieved from the
mplsTunnelARHopTable and mplsTunnelCHopTable MIB tables
respectively. This discovery mode stores transit and tail-end tunnel
instances against transit and tail-end LSRs. The mode creates a connection
in the MPLS TE topology between the head-end and tail-end LSR
interfaces that are associated with the head-end (for the tunnel interface)
and transit and tail-end LSR tunnel objects. Computed and actual-route
connections are associated with Computed and Actual connection entity
types, which are aggregated in sequence from the head-end LSR tunnel
entity. A tunnel resource instance is associated with the head-end tunnel
LSR entity.
You can use this information to determine if the actual path taken by a
tunnel is different to the path computed by the CSPF calculations. You can
190
IBM Tivoli Network Manager IP Edition: Discovery Guide
see the computed and actual path and determine the transit or tail-end role
of an LSR without looking at the headend LSR tunnel instance.
Note: Actual route data is only available if the Record Route Option (RRO)
has been specified for the tunnel instance.
MPLS cross-connect pointers that are discovered and resolved on the head
tunnel will be resolved to the appropriate LSP ID where possible.
In the schema of the scope.mplsTe table, the AllLSRTunnelsAndHops mode
maps to value 3 of m_Mode.
Related reference:
“scope.mplsTe table” on page 317
The scope.mplsTe table defines the scope of MPLS Traffic Engineered (TE) tunnel
discovery, and defines what information is retrieved.
Enabling the StandardMPLSTE agent:
To discover MPLS TE tunnels, you must enable the StandardMPLSTE agent and
add the relevant SNMP community strings.
To enable the StandardMPLSTE agent, complete the following steps.
1. Click the Discovery icon and select Network Discovery Configuration.
2. From the Domain list, select the required domain.
3. Click the Full Discovery Agents tab. The Agents List is displayed, showing all
available discovery agents for the selected discovery option.
4. Select the check box next to the StandardMPLSTE agent.
5. Click Save
.
6. Optional: If you want to rediscover MPLS TE tunnels, enable the
StandardMPLSTE agent for partial rediscoveries.
a. Click the Partial Rediscovery Agents tab.
b. Select the check box next to the StandardMPLSTE agent.
c. Click Save
.
7. Ensure that the SNMP community strings are configured correctly to access the
devices in the MPLS TE tunnels.
Related tasks:
“Configuring device access” on page 32
Specify SNMP community strings and Telnet access information to enable helpers
and Network Manager polling to access devices on your network.
Configuring the StandardMPLSTE agent:
Configure which tunnels to discover, and what details to retrieve.
To configure the StandardMPLSTE agent, complete the following steps.
1. Back up and edit the file NCHOME/etc/precision/DiscoScope.cfg.
2. Locate and edit the insert into the scope.mplsTe table, or create a new insert.
Create or edit an insert similar to the following:
insert into scope.mplsTe
(
m_Protocol,
Chapter 2. Configuring network discovery
191
m_Zones,
m_Mode,
m_TunnelFilter
)
values
(
1,
[{m_Subnet = ’192.168.1.0’, m_NetMask = 24 }],
2,
1
);
This insert configures the agent to behave in the following way:
v It uses IPv4.
v It includes (m_Tunnelfilter=1) the subnet 192.168.1.* in the discovery of
tunnel heads.
v It retrieves data for the head and tail of the tunnel but not for the transit
routers.
3. Save and close the file.
4. Stop and restart the discovery engine, the ncp_disco process, for your
configuration changes to take effect.
Related reference:
“scope.mplsTe table” on page 317
The scope.mplsTe table defines the scope of MPLS Traffic Engineered (TE) tunnel
discovery, and defines what information is retrieved.
Defining the scope of an MPLS/VPN discovery:
When configuring the discovery of one or more Virtual Private Networks ( VPNs )
running across an MPLS core, you can restrict the scope of this discovery to a
particular VPN name or VPN Routing and Forwarding (VRF) table name.
You restrict the scope by configuring the optional DiscoAgentDiscoveryScoping
section in the *.agnt file. The configurable options are described in Table 23.
Table 23. Defining MPLS scoping requirements
Option
Function
IncludeVRF
Allows the discovery of the named VRF
IncludeVPN
Allows the discovery of the named VPN
ExcludeVPN
Does not discover any VRFs within the named VPN
ExcludeVRF
Does not discover the specified VRF
The order of precedence for Exclude and Include within the
DiscoAgentDiscoveryScoping section is:
1. Exclude
2. Include
The order of precedence for VRF and VPN within the
DiscoAgentDiscoveryScoping is:
1. VRF
2. VPN
192
IBM Tivoli Network Manager IP Edition: Discovery Guide
For example, if you include a VPN, but another filter excludes a VRF in your VPN,
then the VRF is excluded. If a VPN is excluded, but another filter includes a VRF
within that VPN, then the VRF is included.
VRF names are case sensitive and an asterisk ( * ) represents a wildcard for any
VRF or VPN name when used in the name part of the configuration. The wildcard
can be used with any of the above options.
Scoping by VPN name works only when the VRF names configured on the devices
discovered by the MPLS agents are in the Cisco-recommended VRF format. A VRF
is named based on the VPN or VPNs serviced, and the topology type. The format
for the VRF names are:
V [number assigned to make the VRF name unique]: [VPN_name]
For example, in a VPN called precision, a VRF for a hub edge router would be:
V1:precision
A VRF for a spoke edge router in the precision VPN would be:
V1:precision-s
A VRF for an extranet VPN topology in the precision VPN would be:
V1:precision-etc
The following example scopes a discovery in a system where there are four VRFs:
V65:Precision-etc, V65:Precision-s, V65:Precision, and V44:AcmeSheds.
//2 VRFs are to be included
//
DiscoAgentDiscoveryScoping
{
IncludeVRF = “V65:Precision-etc”;
IncludeVRF = “V44:AcmeSheds”;
}
//All 4 VRFs are to be included
//
DiscoAgentDiscoveryScoping
{
IncludeVPN = “Precision”;
IncludeVRF = “V44:AcmeSheds”;
}
Related reference:
“disco.config table” on page 295
The config table configures the general operation of the discovery process.
Fine-tuning label data:
The MPLS agents used to discover MPLS networks do not retrieve label data by
default. However, you can set the agents to manually retrieve label data.
You can retrieve label data manually with the following insert in the
DiscoAgentDiscoveryScoping section of the appropriate MPLS agent's .agnt file:
DiscoAgentDiscoveryScoping
{
GetMPLSLabelData = 1;
}
Note: Not all MPLS agents support this setting. Check the description of the agent
for information about whether the specific agent supports this setting. If
Chapter 2. Configuring network discovery
193
supported, the agent retrieves label data in addition to the data used for MPLS
discovery. However, the additional label data is not used by any default stitchers
and is not stored in NCIM. Using this option to retrieve label data requires custom
data collection with custom stitchers set up to consume the label data. For more
information, see Adding custom data to the topology model. For help with writing
custom stitchers, contact IBM Support.
Configuring discovery of Huawei VPNs:
Fix Pack 2
To visualize VPN information from Huawei devices, you must configure the
discovery.
Network Manager can discover and visualize User-facing Provider Edge (UPE) and
Network Provider Edge (NPE) devices with pseudowire interfaces that are part of
a Huawei VPN. It can also build Virtual Switch Interface (VSI) instances for the
NPEs.
To configure discovery of Huawei VPNs, complete the following steps.
1. Ensure that the output of the UPE and NPE devices is set to display vsi
verbose.
2. Ensure that m_RTBasedVPNs in the disco.config database table is set to 1.
3. Ensure that the HuaweiMPLSTelnet discovery agent is enabled.
4. Back up and edit the following stitchers: BuildMPLSContainers.stch,
ResolveVPLSConnections.stch, and MPLSProcessing.stch.
5. Set the value of modelHuaweiVPN to 1 in each stitcher.
6. Run a discovery.
After discovery is finished, view the devices in a network view by filtering on VPLS
VPN.
Configuring NAT discoveries
Configure a Network Address Translation (NAT) discovery to discover NAT
environments, by mapping the address-space identifier for a NAT domain to the IP
address of the associated NAT gateway device.
About Network Address Translation
The number of available IP addresses in the current 32–bit format is not enough to
meet the growth in demand for access to the Internet. Network Address
Translation (NAT) was designed as a short-term solution to this problem by
providing a method of connecting multiple computers to an IP network using
either a single unique public IP address, or a small number of unique public IP
addresses.
NAT is commonly used in corporations, where a NAT router sits at the edge of the
private network (referred to in this context as a stub domain) and translates the IP
addresses attached to packets entering and leaving the stub domain. The NAT
router, which effectively acts as an agent between the Internet and the local
network, maintains a list of the mappings between public and private addresses.
Note: A stub domain is a local network using internal IP addresses. The network
can use unregistered, private, IP addresses for internal communication—these
addresses must be translated into unique, public, IP addresses when
communicating outside the network. The addresses used internally by a given stub
domain can also be used internally by any other stub domain.
194
IBM Tivoli Network Manager IP Edition: Discovery Guide
For example, when a computer within the private network requests information
from the public network, the NAT router automatically translates the private
address of that computer into the public address of the domain, which is the only
address that is transmitted to the public network. When the requested information
is returned, the NAT router consults its internal list of public to private address
mappings in order to forward the information to the appropriate computer.
There are a number of different ways to configure a NAT environment. The
following descriptions detail the most common types of NAT environment.
Static NAT Environments:
In a static NAT environment, the NAT router maps private and public addresses
on a one-to-one basis, that is, the private address of a given device always maps to
the same public address. This type of NAT environment is commonly used for
devices that need to be accessible to the public network.
Dynamic NAT environments:
In a dynamic NAT environment, the NAT router dynamically allocates public IP
addresses, from a group of addresses, to devices on the private network that wish
to communicate with the public network. A variation on dynamic NAT, overloading
or PAT (Port Address Translation), maps multiple private addresses to the same
public address using different ports.
Private Address Ranges:
The Internet Assigned Numbers Authority (IANA) has assigned several address
ranges to be used by private networks.
Address ranges to be use by private networks are:
v Class A: 10.0.0.0 to 10.255.255.255
v Class B: 172.16.0.0 to 172.31.255.255
v Class C: 192.168.0.0 to 192.168.255.255
An IP address within these ranges is therefore considered non-routable, as it is not
unique. Any private network that needs to use IP addresses internally can use any
address within these ranges without any coordination with IANA or an Internet
registry. Addresses within this private address space are only unique within a
given private network.
All addresses outside these ranges are considered public.
About NAT discovery
You can use Network Manager to manage NAT environments, though there are
some restrictions on the types of NAT environment that are currently supported.
Network Manager can interrogate known, supported NAT gateways to obtain a list
of public to private IP address mappings of devices in NAT domains. Alternatively,
these mappings can be supplied manually. Network Manager can then discover
those devices behind the NAT gateways that have a public IP address.
Each NAT domain has a unique address-space identifier. Each device in a NAT
domain has the appropriate address-space identifier appended to its record. This
enables the devices to be managed (for example, polled).
Chapter 2. Configuring network discovery
195
Restrictions on NAT discovery:
There are several restrictions on the management of NAT environments using
Network Manager.
Management of NAT environments using Network Manager is restricted by the
following conditions:
v Network Manager can discover one or more NAT environments, but they must
all use static NAT address mapping.
v Network Manager can discover devices in multiple NAT domains, regardless of
whether the private IP addresses of the devices are duplicated in other NAT
domains. However, the public IP address of each device in each domain must be
unique.
v Devices within a NAT domain that have only private IP addresses cannot be
discovered or managed by Network Manager.
v The discovery process must discover the NAT environment from outside, that is,
from the public network.
v Virtual IP addresses such as Hot Standby Routing Protocol (HSRP) addresses
cannot be mapped. The real physical address must be used.
v The following must be supplied before the discovery is run:
– The addresses of all supported NAT gateways.
– The NAT gateway translations must be discovered, either automatically or by
supplying the NATTextFileAgent discovery agent with a flat file of
public-to-private IP address mappings.
Differences in a NAT discovery process flow:
The process flow of a NAT discovery differs from the process flow of a normal
discovery.
Related concepts:
“Discovery cycles” on page 430
A discovery cycle has occurred when the discovery data flow for a particular cycle
has gone from start to finish. A full discovery might require more than one cycle.
Downloading translation information:
NAT translation information is downloaded by the NAT agents into the
translations.NATTemp database table before the finders process any other entities.
All other discovered devices are inserted into the finders.pending table while the
BuildNATTranslation.stch stitcher creates a global translation table and stores it in
the translations.NAT database table.
The finders, helpers, and other components that need to access devices can use this
table to look up the address of any device behind a NAT gateway.
196
IBM Tivoli Network Manager IP Edition: Discovery Guide
Creating the topology:
When the topology is created, the AddBaseNATTags.stch stitcher adds NAT
information to the topology record of each device in a NAT domain.
Table 24 shows the information that is added to the topology record for each
device.
Table 24. NAT information added to a device record
Column
Description
ExtraInfo->m_AddressSpace
The name of the NAT address space to which the
device belongs. This value is set in the
translations.NATAddressSpaceIds table. If the
discovery is not using NAT, or if the device is in
the public domain, this value is NULL.
ExtraInfo->m_NATTranslated
A Boolean integer indicating whether the device
lies behind a NAT gateway.
ExtraInfo->m_InsideLocalAddress
The private address of the device.
ExtraInfo->m_OutsideGlobalAddress
The public address of the device.
Configuring a NAT discovery
Configure a NAT discovery to discover NAT environments and to enable Network
Manager to manage NAT environments.
You set most of the NAT discovery settings from the Discovery Configuration GUI,
except for the following tasks:
v Configure the NATTextFileAgent agent to provides support for any unsupported
NAT gateway devices
v Configure the NATGateway agent to correct the potential problem of incorrect
connectivity when the NAT gateway is not in the public address space.
Quick reference for NAT discovery configuration:
Use this information as a step-by-step guide to configuring a NAT discovery..
The steps are described in the following table.
Table 25. Quick reference for NAT discovery configuration
Action
Using the GUI
Using the command line
1. Configure the discovery to use network address
translation. You can do this using the Discovery
Configuration GUI, or using the command line.
“Configuring NAT
translation” on page 42
“Enabling NAT translation”
on page 199
2. Define each NAT gateway device and its
corresponding address space. You can do this using the
Discovery Configuration GUI, or using the command
line.
“Defining address spaces
for NAT gateways” on page
199
Chapter 2. Configuring network discovery
197
Table 25. Quick reference for NAT discovery configuration (continued)
Action
Using the GUI
3. Seed the Ping finder with the IP address of each NAT “Seeding discovery” on
gateway device.
page 29
Using the command line
Guidance for seeding a
discovery
“DiscoPingFinderSeeds.cfg
configuration file” on page
71
Guidance for seeding a
NAT discovery
“Seeding discovery with
NAT gateway addresses” on
page 201
4. Define a scope zone for each NAT gateway device.
Note: You do not need to define a scope zone for any
NAT Gateway devices whose IP address is already
within any other scope zones defined for the discovery.
Note: Do not define an address space for the NAT
gateway devices or for public subnet scopes. Address
space can only be defined for private subnets.
“Scoping discovery” on
page 27
Guidance for scoping a
discovery
“DiscoScope.cfg
configuration file” on page
75
Example: how to define a
scope zone for a private
NAT subnet
“Defining a scope zone
within a NAT domain” on
page 200
5. Define scope zones for the public subnets associated
with each NAT address space.
Note: Do not define an address space for the NAT
gateway devices or for public subnet scopes. Address
space can only be defined for private subnets.
6. Where possible, define scope zones for the private
subnet associated with each NAT address space.
Restriction: You can only define a scope zone for a
private NAT address space where the subnet and
netmask combination of the private subnet is unique
within the discovery configuration.
Make the following settings when defining this scope:
1. Uncheck the Add to Ping Seed List option. You
must do this because private subnets are not
pingable.
2. Define an address space for this private subnet.
The advantages of adding a scope zone for each private
NAT address space are as follows:
v This ensures that only addresses in that private space
are fed back during the discovery.
v If the NAT Gateway device and the devices within
the associated NAT address space are routers. then
adding a scope zone for that private NAT address
space limits the download of unnecessary routing
data.
7. Enable NAT agents as follows:
v For supported NAT Gateway devices, enable the
CiscoNATTelnet or NATNetScreen agent.
“Activating agents” on page “Enabling agents for
36
supported NAT gateway
devices” on page 202
v For unsupported NAT Gateway devices, create a NAT
mapping file and enable the NATTextFileAgent agent
Related tasks:
198
IBM Tivoli Network Manager IP Edition: Discovery Guide
“Enabling agents for
unsupported NAT gateway
devices” on page 202
“Example: Configuring a NAT discovery” on page 204
This example illustrates how to define address spaces using the NATTextFileAgent
agent and how to set up associated discovery scopes.
Enabling NAT translation:
You can set the discovery system to use NAT translation by editing
$NCHOME/etc/precision/DiscoConfig.cfg to create or amend an insert into
disco.NATStatus to set m_UsingNAT to 1 and m_NATStatus to 0.
The completed insert must resemble the following:
insert into disco.NATStatus
(
m_UsingNAT,
m_NATStatus
)
values
(
1,
0
);
Related tasks:
“Configuring NAT translation” on page 42
To configure NAT translation to discover NAT environments, map the
address-space identifier for a NAT domain to the IP address of the associated NAT
gateway device.
“Enabling NAT translation”
You can set the discovery system to use NAT translation by editing
$NCHOME/etc/precision/DiscoConfig.cfg to create or amend an insert into
disco.NATStatus to set m_UsingNAT to 1 and m_NATStatus to 0.
Defining address spaces for NAT gateways:
To specify the IP address of your NAT gateways and the address space identifier
you want to use for each associated NAT domain, edit DiscoConfig.cfg to create
or amend an insert into translations.NATAddressSpaceIds.
Follow these guidelines when defining address spaces for NAT gateways:
v The IP address must be the public IP address that is accessible from the
management server.
v The address space field can be any descriptive string, but avoid special
characters such as quotes. Use the standard rules for DNS names for the address
space because the address space might make up part of the name of these
devices.
The following example insert configures the discovery system for two NAT
gateways.
insert into translations.NATAddressSpaceIds
(
m_NATGatewayIP,
m_AddressSpaceId
)
values
(
’172.16.1.112’,
’NATDomain1’
);
Chapter 2. Configuring network discovery
199
insert into translations.NATAddressSpaceIds
(
m_NATGatewayIP,
m_AddressSpaceId
)
values
(
’172.16.1.104’,
’NATDomain2’
);
Related tasks:
“Configuring NAT translation” on page 42
To configure NAT translation to discover NAT environments, map the
address-space identifier for a NAT domain to the IP address of the associated NAT
gateway device.
“Enabling NAT translation” on page 199
You can set the discovery system to use NAT translation by editing
$NCHOME/etc/precision/DiscoConfig.cfg to create or amend an insert into
disco.NATStatus to set m_UsingNAT to 1 and m_NATStatus to 0.
Defining a scope zone within a NAT domain:
You can customize inclusion and exclusion zones for individual NAT domains,
using the m_AddressSpace column of the scope.zones table.
The following example insert defines an inclusion zone for a private subnet
associated with a NAT domain.
insert into scope.zones
(
m_Protocol, m_Action, m_Zones, m_AddressSpace
)
values
(
1,
1,
[
{
m_Subnet="172.16.2.*",
}
],
"NATDomain1"
);
The above example defines one inclusion zone. Network Manager discovers any
device with an IP address starting with "172.16.2", that is, in the private
172.16.2.0 subnet with a mask of 255.255.255.0, and that also belongs to the
NAT address space NATDomain1. The protocol is set to 1, that is, IP.
Note: Do not define an address space for the NAT gateway devices or for public
subnet scopes. Address space can only be defined for private subnets.
Related tasks:
“Configuring NAT translation” on page 42
To configure NAT translation to discover NAT environments, map the
address-space identifier for a NAT domain to the IP address of the associated NAT
gateway device.
“Enabling NAT translation” on page 199
You can set the discovery system to use NAT translation by editing
$NCHOME/etc/precision/DiscoConfig.cfg to create or amend an insert into
200
IBM Tivoli Network Manager IP Edition: Discovery Guide
disco.NATStatus to set m_UsingNAT to 1 and m_NATStatus to 0.
Seeding discovery with NAT gateway addresses:
Seed a NAT discovery by inserting into the Ping finder the IP addresses of the
main routers within the system. Also seed the discovery with the IP addresses of
the NAT gateway IPs.
In a NAT-based discovery, the discovery must discover the NAT gateways before
discovering the rest of the network, so the NAT gateways must first be found with
a finder.
Network Manager is configured to trigger the seeding of all the NAT gateways if
NAT translation has been enabled. However, the triggering relies on the Ping
finder being active. If seeding is done, for example, using only the File finder, then
the NAT gateways are not pinged even if NAT translation has been enabled. It is
good practice, therefore, to seed the discovery with all the NAT gateways. You can
do this using the File finder, Ping finder, or any other method.
You can also seed the discovery with NAT gateways using the Discovery
Configuration GUI.
Related tasks:
“Configuring NAT translation” on page 42
To configure NAT translation to discover NAT environments, map the
address-space identifier for a NAT domain to the IP address of the associated NAT
gateway device.
“Enabling NAT translation” on page 199
You can set the discovery system to use NAT translation by editing
$NCHOME/etc/precision/DiscoConfig.cfg to create or amend an insert into
disco.NATStatus to set m_UsingNAT to 1 and m_NATStatus to 0.
Enabling NAT agents:
®
®
If you are running a NetScreen Firewall or a Cisco Router as a NAT gateway, you
must use either the CiscoNATTelnet agent or the NATNetScreen agent.
Ensure that you enable the appropriate NAT translation agents. These agents must
run to discover the NAT gateways. If they are not run, discovery cannot complete
as it cannot properly discover the network without first discovering the NAT
Gateways.
The NAT agents are currently CiscoNATTelnet, NATNetScreen and
NATTextFileAgent. The CiscoNATTelnet agent works on Cisco IOS routers
providing NAT translation and is not certified for PIX firewalls. The NATNetScreen
agent is for NetScreen firewalls.
If you are using a NAT gateway other than a NetScreen Firewall or a Cisco Router,
you must use the Perl agent NATTextFileAgent.pl, as described in “Enabling
agents for unsupported NAT gateway devices” on page 202.
Chapter 2. Configuring network discovery
201
Enabling agents for supported NAT gateway devices:
The CiscoNATTelnet and NATNetScreen agents connect directly to the NAT
gateways to download the address mappings. You can configure these agents.
Before running these agents, you must do the following tasks:
v Enable NAT translation
v Configure trap handling
To configure and run the agents:
1. Enable the agents. There is an insert into the disco.agents table in the
DiscoAgents.cfg configuration file for every installed discovery agent. To
activate an agent, you must alter the insert so that the m_Valid column for that
agent is set to 1. To deactivate an agent, ensure that m_Valid=0.
The following example insert activates the CiscoNATTelnet agent.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence,
m_DebugLevel, m_LogFile
)
values
(
’CiscoNATTelnet’, 1, 8, 0, 2, 4,
"$NCHOME/log/precision/CiscoNatTelnet.log"
);
2. Run a discovery.
Related tasks:
“Activating agents” on page 36
You must enable the appropriate agents for the discovery you want to perform.
You can specify agents for a full discovery or for a partial discovery.
Enabling agents for unsupported NAT gateway devices:
The NATTextFileAgent is provided as a backup if your NAT translation device is
unsupported. You can configure this agent.
Before running the NATTextFileAgent agent, you must do the following tasks:
v Enable NAT translation
v Configure trap handling
The NATTextFileAgent reads a flat file called NATTranslations.txt that contains the
NAT translations present on a particular NAT gateway. This allows the discovery
an avenue to support a network containing a currently unsupported NAT gateway.
This agent does not download its information from the NAT gateways, but reads a
list of private to public IP address mappings from a flat file.
To configure and run the agent:
1. Install the Perl API. All Perl agents require the API to run. The API is installed
by default in Network Manager.
To check whether the API is installed, check that the following file exists:
$NCHOME/precision/bin/ncp_perl
If the file is listed, then the Perl API is installed.
202
IBM Tivoli Network Manager IP Edition: Discovery Guide
2. Create a NAT mapping file to be read by the agent that contains the public to
private address mappings. Your NAT mapping file must be in a format that can
be read by the agent, that is, the values must be valid IP addresses specified in
columns separated by tabs.
By default, the agent uses the file $NCHOME/etc/precision/
NATTranslations.txt. If you want to create your own mappings, you must back
up and edit this default file. To make the agent use the non-default NAT
mapping file, edit the following line in $NCHOME/precision/disco/agents/
Perlagents/NATTextFileAgent.pl:
my $natFileName = "$ENV{$NCHOME}/etc/precision/NATTranslations.txt";
3. The NAT mapping file contains the following columns:
v The IP address of the NAT gateway of the NAT domain to which the device
belongs. You must specify mappings for all NAT gateways in the same file.
v The outside global address of the device, that is, the public address of the
device.
v The inside local address of the device, that is, the private address of the
device.
The following example shows a NAT mapping file for two gateways having
IP addresses of 1.2.3.4 and 1.2.3.9 respectively.
// NATGatewayIP
1.2.3.4
1.2.3.4
1.2.3.9
1.2.3.9
PublicIP
2.3.4.5
2.3.4.6
2.3.6.1
2.3.6.2
PrivateIP
10.10.1.1
10.10.1.2
10.10.1.1
10.10.1.2
Note: From the perspective of the management station, the public IP address
of a particular gateway translation is not necessarily the same as the public
address that the management stations sees. The public address is the IP address
that the gateway retrieves from one port and then translates and places on
another port. This difference is important to note when you have chained
gateways, where an IP address can be translated multiple times. The public IP
is effectively the IP address that is closer to the management domain.
4. Enable the agent. There is an insert in the disco.agents table in the
DiscoAgents.cfg configuration file for every installed discovery agent. To
activate an agent, alter the insert so that the m_Valid column for that agent is
set to 1. To deactivate an agent, ensure that m_Valid=0.
The following example insert activates the NATTextFileAgent agent.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence, m_IsPerl
)
values
(
’NATTextFileAgent’, 1, 8, 0, 2, 1
);
5. Ensure that the NATTimer.stch stitcher has been configured to trigger a
rediscovery against the NAT gateways. By default, the NATTimer.stch stitcher
runs every hour. You can alter this interval by locating the following line in the
stitcher file and changing the integer value:
ActOnTimedTrigger( ( m_Interval ) values ( 1 ) ; ) ;
6. Run a discovery.
Chapter 2. Configuring network discovery
203
Enable agent for NAT gateway devices in private address space:
When the NAT gateway is not in the public address space, you can enable the
NATGateway agent to correct the potential problem of incorrect connectivity.
The discovery assumes that the management interface of the NAT gateway is in
public address space. If this is not the case, Network Manager cannot identify the
address space of interfaces on the NAT gateway device, which might result in
incorrect connectivity. For example, when a VPN is used to access the management
interface, the NAT gateway management interface is not in the public address
space.
The NATGateway agent enables Network Manager to determine whether a given
interface on a NAT gateway device is on the public or private side of the NAT
gateway, and thereby correctly resolve device connectivity.
To overcome this problem, activate the NATGateway agent and provide Network
Manager with a mapping file, NATGateways.txt. In this file, provide a list of all
NAT gateway devices together with the interfaces on each device and a field to
indicate whether the interface is on the public or private side of the NAT gateway.
This agent works in conjunction with the NATGatewayRetProcessing.stch stitcher
and with the NATGateways.txt file in NCHOME/precision/etc
Table 26 provides the format of the NATGateways.txt file by showing an example
of the content of this file. Fields in this text file must be separated by tabs.
Table 26. Format of NATGateways.txt file
Base name
Inside or outside
Interface IP address
1.1.1.4
outside
172.16.4.10
1.1.1.4
inside
10.52.2.10
sca_T1ukP_16
outside
192.168.36.93
sca_T1ukP_16
outside
192.168.36.98
Example: Configuring a NAT discovery:
This example illustrates how to define address spaces using the NATTextFileAgent
agent and how to set up associated discovery scopes.
Do the following tasks before running through the steps in this example:
v Configure the discovery to use network address translation.
v Seed the Ping finder with the IP address of each NAT gateway device.
In this example the NAT gateway devices are unsupported. This means that the
NATTextFileAgent agent must be used in this NAT discovery.
The NATTextFileAgent agent uses a NAT mapping file, with the following content.
There are three NAT gateway devices, with mappings for each of the devices in the
associated address spaces.
//First NAT gateway and mappings
//NATGateway
PublicIP
201.201.201.201
61.61.61.1
201.201.201.201
61.61.61.2
201.201.201.201
61.61.61.3
204
IBM Tivoli Network Manager IP Edition: Discovery Guide
Private IP
192.168.1.1
192.168.1.2
192.168.1.3
201.201.201.201
201.201.201.201
201.201.201.201
61.61.61.4
61.61.61.5
61.61.61.6
192.168.1.4
192.168.1.5
192.168.1.6
//Second NAT gateway and mappings
//NATGateway
PublicIP
202.202.202.202
62.62.62.1
202.202.202.202
62.62.62.2
202.202.202.202
62.62.62.3
202.202.202.202
62.62.62.4
202.202.202.202
62.62.62.5
202.202.202.202
62.62.62.6
Private IP
192.168.1.1
192.168.1.2
192.168.1.3
192.168.1.4
192.168.1.5
192.168.1.6
//Third NAT gateway and mappings
//NATGateway
PublicIP
203.203.203.203
63.63.63.1
203.203.203.203
63.63.63.2
203.203.203.203
63.63.63.3
203.203.203.203
63.63.63.4
203.203.203.203
63.63.63.5
203.203.203.203
63.63.63.6
Private IP
192.168.3.1
192.168.3.2
192.168.3.3
192.168.3.4
192.168.3.5
192.168.3.6
For the first and second address spaces private IP address space is not unique. For
both of these address spaces, the private IP address space is defined by a subnet
and netmask combination of 192.168.1.0/29.
Based on this NAT gateway device and address space data, define discovery
scopes as follows.
1. Define each NAT gateway device and its corresponding address space. In this
example, the names of the three NAT address spaces are RTP1, RTP2, and
RTP3. For example, for the third NAT gateway device, the following insert
defines the NAT device and its associated address space, RTP3:
insert into translations.NATAddressSpaceIds
(
m_NATGatewayIP, m_AddressSpaceId
)
values
(
"203.203.203.203", "RTP3"
);
2. Define a scope zone for each NAT gateway device.
Note: You do not need to define a scope zone for any NAT Gateway devices
whose IP address is already within any other scope zones defined for the
discovery.
For example, for the first NAT gateway device, the following insert defines the
scope zone:
insert into scope.zones
(
m_Protocol, m_Action, m_Zones, m_AddressSpace
)
values
(
1,
1,
[
{
m_Subnet="201.201.201.201",
m_NetMask=32
Chapter 2. Configuring network discovery
205
}
],
""
);
3. Define scope zones for the public subnets associated with each NAT address
space. For example, for the third public subnet, the following insert defines the
scope zone:
insert into scope.zones
(
m_Protocol, m_Action, m_Zones, m_AddressSpace
)
values
(
1,
1,
[
{
m_Subnet="63.63.63.0",
m_NetMask=29
}
],
""
);
4. Define a scope zone for the private subnet associated with the third NAT
address space only.
Restriction: You can only define a scope zone for a private NAT address space
where the subnet and netmask combination of the private subnet is unique
within the discovery configuration. This excludes the first and second private
subnet.
For the third private subnet, the following insert defines the scope zone:
insert into scope.zones
(
m_Protocol, m_Action, m_Zones, m_AddressSpace
)
values
(
1,
1,
[
{
m_Subnet="192.168.3.0",
m_NetMask=29
}
],
"RTP3"
);
5. Enable the NATTextFileAgent agent.
Now you can launch the NAT discovery.
Related reference:
“Quick reference for NAT discovery configuration” on page 197
Use this information as a step-by-step guide to configuring a NAT discovery..
206
IBM Tivoli Network Manager IP Edition: Discovery Guide
Post-configuration NAT tasks
After you have configured NAT discoveries, you can complete several
post-configuration tasks.
Tracking the progress of a NAT discovery:
During the discovery of the NAT-translation devices, you can track the discovery
status in the disco.NATStatus values.
During the discovery, you initially see only the NAT-translating devices displayed
in the agent despatch and returns tables. All the other data returned from the
finders is stored in finders.pending database table while the discovery of the
NAT-translating devices takes place.
Issue the following OQL select statement to see the discovery status:
select * from disco.NATStatus;
This statement displays a value from 0 to 4. The meaning of the value is:
v 0: NAT discovery in initial state. NAT devices have not been processed.
v 1: NAT discovery initiated. NAT gateway IPs have been sent to the Ping finder
to verify their existence
v 2: NAT discovery is running.
v 3: NAT discovery processing. All the NAT gateways have been processed and
the discovery is now building the translations.NAT table. This table ensures the
correct discovery of the rest of the network.
v 4: NAT discovery complete. The entries in the finders.pending table have been
moved into the finders.processing table, and the discovery continues as normal.
Use the results of this query to debug a problematic NAT discovery. The value
indicates whether any discovery problems are caused by NAT or caused by the
standard (non-NAT) part of the discovery process.
Debugging a NAT discovery:
To analyze a NAT discovery, use ncp_oql to follow the data through the system
from the start (finders) to the end until you determine where the data is incorrect.
Incorrect data indicates whether the problem is with an agent, a device, or a
stitcher.
There are several queries that are useful when debugging a discovery, both
NAT-based and not NAT-based.
The following OQL query indicates which agents are currently either being started
(m_State=1), starting (m_State=2) or running (m_State=3):
select * from agents.status where m_State <> 0 AND m_State <> 4;
This query tells you which agents the current phase is waiting for in order to
complete. The discovery is waiting for the agents that are meant to complete in the
current phase and are in state 1, 2 or 3.
select * from <agentName>.despatch
where m_UniqueAddress NOT IN
((
select m_UniqueAddress from <agentName>.returns where m_LastRecord = 1
));
Chapter 2. Configuring network discovery
207
Using the first query, you can see which agents are still running in a particular
phase.
Using the following query, you can determine which entity that particular agent is
processing. This can be useful in determining a problem device within your
network:
select * from translations.ipToBaseName where m_IpAddress = ’<ip>’;
This second query shows you what base address and base name is being used for
a particular IP as well as whether this IP address is considered to be in scope.
Activating the Containment Model for use with NAT:
The NATAddressSpaceContainers.stch stitcher creates virtual objects for each
address space that contains the entities within that address space. You can activate
this stitcher by uncommenting the line, //
ExecuteStitcher("NATAddressSpaceContainers");, in the file $NCHOME/precision/
disco/stitchers/BuildContainment.stch.
Viewing NAT environments using Topoviz Network Views:
Using Topoviz Network Views, you can create network views based on the values
of any column in the topology record of an entity. A NAT Address Spaces Dynamic
Distinct view is created automatically if you activated NAT discovery as part of
your discovery configuration.
As an example of viewing NAT environments, you could created a filtered
network view or a Dynamic Distinct view on the following field in the NCIM
topology database:
v ipEndPoint table
v addressSpace field
Note: A NAT Address Spaces Dynamic Distinct view is created automatically if
Enable Network Address Translation (NAT) Support is turned on as part of your
discovery configuration.
Configuring cross-domain discoveries
To enable links between devices in different domains to be shown in the network
and topology views, you must configure and run cross-domain discoveries on the
different domains.
Configuring cross-domain discovery is an advanced procedure that requires
knowledge of the discovery data flow, the OQL query language, the database
structure, and details of your network connectivity and composition.
208
IBM Tivoli Network Manager IP Edition: Discovery Guide
About cross-domain discovery
Cross-domain discovery can be configured to join two or more discovered domains
together.
For performance or operational reasons, networks are often discovered in sections,
known as discovery domains. For example, if your network is so large that
discovering it in one discovery takes too long, you might choose to split network
discovery into different domains.
Discovering the network in domains can be more convenient and faster. You can
also choose to have different configuration options for different domains. For
example, each domain has its own poll policies. However, there are disadvantages
to discovering the network in pieces. If a device in domain A is connected to a
device in domain B, this connection is not represented in the topology database or
in the GUI. Domains must be viewed separately.
If you want to visualize multiple domains linked together in one network view,
you must enable, configure, and run cross-domain discoveries. Connections
between devices in different domains are found and added to the topology.
When all discovered domains have been aggregated, Network Views can be
composed of devices from all domains. In the Network Hop View, searches for
devices can span domains.
Note: Cross-domain network views can not be polled; only network views from
individual domains can be polled.
Considerations for splitting the network into domains
Links between devices in different domains are not as easy to discover as links
between devices within one domain.
It is important to scope your discovery domains to ensure the minimum of links
between domains. For example, you would not normally split the network such
that highly connected switches were in different domains. Natural splits for
domains are often along geographical lines.
Restriction:
However you split your network, you must ensure that any given device appears
in only one domain. That is, the discovery domains must not overlap if you want
to join them together using cross-domain discovery.
Enabling cross-domain linking
The first step of configuring cross-domain linking is to enable the links between
domains in the DiscoConfig.cfg configuration file. By default, cross-domain
linking is disabled.
1. Back up and edit the $NCHOME/etc/precision/DiscoConfig.domain.cfg file.
2. Make the following settings:
v Set m_EnableCrossDomainProcessing to 1.
v Set m_InferPEsUsingBGP to 0 to disable the inference of Provider Edge (PE)
devices. PE device inference is incompatible with cross-domain discoveries.
This setting can also be made in the Advanced tab of the Network Discovery
Configuration GUI by clearing Enable Inference of PEs using BGP data on
CEs.
Chapter 2. Configuring network discovery
209
3. Repeat these steps in the DiscoConfig.domain.cfg file of each domain that you
want to be linked.
4. In the LinkDomainsPopulateDomainAdjacencies.stch stitcher file, define the
adjacencies between domains in the tmpDomainAdj.adjacencies table. Use
INSERT statements to define the adjacencies. Sample INSERT statements are
provided in the file. Each INSERT statement defines only one adjacency. You
can put the INSERT statements in any order. For example, to define adjacencies
between two domains that are called NORTH and SOUTH use the following
INSERT statement:
insert into tmpDomainAdj.adjacencies values (’NORTH’, ’SOUTH’);
The following example shows the INSERT statements to use when you have
three domains: EUROPE, ASIA, and AMERICA. EUROPE is adjacent to both
ASIA and AMERICA.
insert into tmpDomainAdj.adjacencies values (EUROPE, ASIA);
insert into tmpDomainAdj.adjacencies values (EUROPE, AMERICA);
To define an extra adjacency between ASIA and AMERICA, use another
INSERT statement:
insert into tmpDomainAdj.adjacencies values (ASIA, AMERICA);
Configuring cross-domain links
To configure cross-domain links, decide which method of linking is appropriate for
your network and configure the relevant stitchers.
Configuring cross-domain links between Layer 1 devices:
You can enable cross-domain links between Layer 1 devices. You can enable or
disable the creation of links between devices in different domains that use Layer 1
protocols. You can also configure how the links are created.
1. Back up and edit the stitcher file NCHOME/precision/disco/stitchers/
LinkDomains.stch.
2. Locate the line that begins int linkViaLayer1NameInterface.
3. Set the value to 1 to enable connections between Layer 1 devices in different
domains to be created as links in the topology.
4. Optional: Configure the following advanced parameters, which apply to links
created using all enabled technologies and methods:
previewChanges
Set to 1 if you want the links not to be created but only saved to a log
file. To view previewed links, set the ncp_disco process to
-messagelevel debug before starting the discovery. Messages about the
connections that would have been created are logged to the
NCHOME/log/precision/ncp_disco.DOMAIN.log file. Set to 0 if you want
the links to be created.
lowLayerResolutionMode
If more than one type of connection exists between two ports, you can
choose at what level that connection is created. It is often more useful
to use the more specific, lowest level connection.
v Set to 0 to create only the connection that was found by the
cross-domain stitchers.
v Set to 1 to create the connection only between the ports that are
stacked at the lowest level under an interface. For example, where a
210
IBM Tivoli Network Manager IP Edition: Discovery Guide
POS interface is stacked over a SONET port, this option creates the
connection only between the SONET ports. If you enable this option,
the stitching takes longer.
v Set to 2 to create the connection between the interfaces and their
lowest stacked ports. For example, where a POS interface is stacked
over a SONET port, this option creates one connection between the
SONET ports and one connection between the POS interfaces. If you
enable this option, the stitching takes longer.
Related reference:
“Cross-domain stitchers” on page 514
Cross-domain stitchers look for links between devices in different domains and
create connections between them in the topology.
Configuring cross domain links between other device technologies:
You can create cross-domain links between devices using device technologies such
as /30 and pseudowire. You can also configure how the links are created.
1. Back up and edit the stitcher file NCHOME/precision/disco/stitchers/
LinkDomains.stch.
2. Optional: To enable /30 connections between devices in different domains to be
created as links in the topology, locate the line that begins int
linkViaSlash30Subnet and set the value to 1.
a. Configure the following parameters:
preventLinkPropagation
Set to 0 to add the /30 connection even if there is an existing Layer
2 connection between the two network entities. Set to 1 to prevent a
/30 connection being added if there is already an existing Layer 2
connection from the entity.
linkSlash30InLayer2
Set to 0 to prevent /30 links being added as Layer 2 links. Set to 1
to add /30 links as Layer 2 links. Setting both this property and
linkSlash30InLayer3 to 0 prevents /30 connections being created,
even though they are discovered, which can make the discovery
take longer. You can set both properties to 1 to add /30 links as
both Layer 2 and layer 3 links.
linkSlash30InLayer3
Set to 0 to prevent /30 links being added as Layer 3 links. Set to 1
to add /30 links as Layer 3 links. Setting both this property and
linkSlash30InLayer2 to 0 prevents /30 connections being created,
even though they are discovered, which can make the discovery
take longer. You can set both properties to 1 to add /30 links as
both Layer 2 and layer 3 links.
3. Optional: To enable pseudowire connections between devices in different
domains to be created as links in the topology, locate the line that begins int
linkViaPseudoWires and set the value to 1.
a. Configure the following parameters:
resolvePWViaFarEndIP
Set to 0 to disable the creation of links using far-end Pseudowire IP
addresses. Set to 1 to create links using far-end Pseudowire IP
addresses.
Chapter 2. Configuring network discovery
211
resolvePWViaLabels
Set to 0 to disable the creation of links using Pseudowire inverse
label searching. Set to 1 to create links using Pseudowire inverse
label searching.
resolvePWViaVPLSInterface
Set to 0 to disable the creation of links using Virtual Private Label
Switching (VPLS) duplicates. Set to 1 to create links using Virtual
Private Label Switching (VPLS) duplicates.
4. Optional: To enable BGP session connections between devices in different
domains using the BGP session information downloaded by the bgp agents,
locate the line that begins int linkViaBGPSessions and set the value to 1.
a. Configure the following parameters:
linkBGPInLayer2
Set to 1 to place the link into the L2 topology if the BGP cross
domain processing finds a BGP link between domains.
Set to 0 to disable.
linkBGPInLayer3
Set to 1 to place the link into the L3 topology if the BGP cross
domain processing finds a BGP link between domains.
Set to 0 to disable.
linkEstalbishedSessionsOnly
Set to 1 to connect the two BGP interfaces if a cross domain BGP
session is found for which the status is not established.
Set to 0 to connect the two BGP interfaces if a cross domain BGP
session is found only if the status has been established.
linkBGPSessionsStrictly
Set to 1 to enable linking via general IP matches, should a strict
BGP session match fail.
Set to 0 to disable.
5. Optional: To enable CDP connections between devices in different domains to
be created using the CDP agent return data, locate the line that begins int
linkViaCDP and set the value to 1.
a. Configure the following parameters:
linkViaCDPAtLowestInterface
Set to 0 to connect together found interfaces.
Set to 1 to attempt to recurse in order to connect at the lowest level
port/interface.
linkViaCDPAtLayer2
Set to 1 to place the link into the L2 topology if a CDP link between
domains is found.
Set to 0 to disable.
linkViaCDPAtLayer3
Set to 1 to place the link into the L3 topology if a CDP link between
domains is found.
Set to 0 to disable.
212
IBM Tivoli Network Manager IP Edition: Discovery Guide
6. Optional: To use MPLS TE agents neighbor data to resolve connections between
devices in separate domains, locate the line that begins int linkViaMPLSTE and
set the value to 1.
a. Configure the following parameters:
linkViaMPLSTEAtLayer2
Set to 1 to place the link into the L2 topology if an MPLS TE link
between domains is found.
Set to 0 to disable.
linkViaMPLSTEAtLayer3
Set to 1 to place the link into the L3 topology if an MPLS TE link
between domains is found.
Set to 0 to disable.
linkViaMPLSTEAtMPLSTE
Set to 1 to enables the creation of an MPLS TE connection if an
MPLS TE link can be identified.
Set to 0 to disable.
7. Optional: To use OSPF agents neighbor data to resolve connections between
devices in separate domains, locate the line that begins int linkViaOSPF and
set the value to 1.
a. Configure the following parameters:
linkViaOSPFAtLayer2
Set to 1 to place the link into the L2 topology if an OSPF link
between domains is found.
Set to 0 to disable.
linkViaOSPFAtLayer3
Set to 1 to place the link into the L3 topology if an OSPF link
between domains is found.
Set to 0 to disable.
linkViaOSPFAtOSPF
Set to 1 to enables the creation of an OSPF connection if an OSPF
link can be identified.
Set to 0 to disable.
8. Optional: To use PIM agents neighbor data to resolve connections between
devices in separate domains, locate the line that begins int linkViaPIM and set
the value to 1.
a. Configure the following parameters:
linkViaPIMAtLayer2
Set to 1 to place the link into the L2 topology if a PIM link between
domains is found.
Set to 0 to disable.
linkViaPIMAtLayer3
Set to 1 to place the link into the L3 topology if a PIM link between
domains is found.
Set to 0 to disable.
Chapter 2. Configuring network discovery
213
linkViaPIMAtPIM
Set to 1 to enables the creation of a PIM connection if a PIM link
can be identified.
Set to 0 to disable.
9. Optional: Configure the following advanced parameters, which apply to links
created using all enabled technologies and methods:
previewChanges
Set to 1 if you want the links not to be created but only saved to a log
file. To view previewed links, set the ncp_disco process to
-messagelevel debug before starting the discovery. Messages about the
connections that would have been created are logged to the
NCHOME/log/precision/ncp_disco.DOMAIN.log file. Set to 0 if you want
the links to be created.
lowLayerResolutionMode
If more than one type of connection exists between two ports, you can
choose at what level that connection is created. It is often more useful
to use the more specific, lowest level connection.
v Set to 0 to create only the connection that was found by the
cross-domain stitchers.
v Set to 1 to create the connection only between the ports that are
stacked at the lowest level under an interface. For example, where a
POS interface is stacked over a SONET port, this option creates the
connection only between the SONET ports. If you enable this option,
the stitching takes longer.
v Set to 2 to create the connection between the interfaces and their
lowest stacked ports. For example, where a POS interface is stacked
over a SONET port, this option creates one connection between the
SONET ports and one connection between the POS interfaces. If you
enable this option, the stitching takes longer.
Related reference:
“Cross-domain stitchers” on page 514
Cross-domain stitchers look for links between devices in different domains and
create connections between them in the topology.
Adding and editing cross-domain links manually:
If you do not see links between devices in different domains, you can manually
create or configure them.
To add or edit cross-domain links, complete the following steps:
1. Back up and edit the stitcher file NCHOME/precision/disco/stitchers/
LinkDomainsLoadPresetConnections.stch.
2. Uncomment the OQL insert statement.
3. Copy one OQL insert statement for each connection that you want to make.
4. Edit the OQL insert statement and add the details of the connection that you
want to create, using the following parameters:
entryNo
A unique numeric ID for this row. Start at 1 and increase to n.
action Set to ADD to add a connection.
214
IBM Tivoli Network Manager IP Edition: Discovery Guide
aEndDiscoDomainName
The domain in which the device at the beginning of the connection was
discovered. This connection is created only after a discovery is run in
this domain.
aEndDiscoEntityName
The entityName of the device at the beginning of the connection.
zEndNCIMDomainName
The domain in which the device at the end of the connection is located.
If a discovery is run in only this domain, this connection is not created.
zEndNCIMEntityName
The entityName of the device at the end of the connection.
topologyEntityType
The NCIM topology entityType of the connection.
Related reference:
“Cross-domain stitchers” on page 514
Cross-domain stitchers look for links between devices in different domains and
create connections between them in the topology.
Configuring cross-domain links using interface descriptions:
You can create connections between all interfaces that match a search of the
interface descriptions.
To search for interfaces and create connections between them, complete the
following steps:
1. Back up and edit the stitcher file NCHOME/precision/disco/stitchers/
LinkDomainsLoadInterfaceDescriptionMatches.stch.
2. Copy one OQL insert statement for each connection that you want to make.
3. Edit the OQL insert statement and add the details of the connection that you
want to create, using the following parameters:
entryNo
A unique numeric ID for this row. Start at 1 and increase to n.
action Set to ADD to add a connection.
onlyAdminUp
Set to 1 to restrict the search to interfaces whose administrative status is
Up. Set to 0 to include all interfaces, whether their administrative status
is Up or Down.
Administrative status is the desired state of the interface. A network
administrator can set the administrative status of an interface to Up,
Down, or Testing.
aEndDiscoMatchType
Set to EXACT to perform an exact text search or REGEX to perform a
regular expression search for source interfaces in the databases of
ncp_disco.
aEndDiscoDomainName
The domain in which the device at the beginning of the connection was
discovered. This connection is created only after a discovery is run in
this domain.
Chapter 2. Configuring network discovery
215
aEndDiscoSearchTerm
The search term against which an interface in the
aEndDiscoDomainName domain must match in the databases of
ncp_disco.
zEndNCIMMatchType
Set to EXACT to perform an exact text search or REGEX to perform a
regular expression search for target interfaces in the NCIM database.
zEndNCIMDomainName
The NCIM domain in which to search for target interfaces in the NCIM
database.
topologyEntityType
The NCIM topology entityType of the connection in the NCIM
database.
All interfaces matching the search are connected together.
The following example shows an insert that connects all interfaces in the NCOMS
domain whose descriptions contain the string connection to vmhost_network to all
interfaces in the NCOMSADJ domain whose descriptions also contain the string
connection to vmhost_network:
INSERT INTO linkDomains.interfaceDescriptionMatch
(
entryNo,
action,
onlyAdminUp,
aEndDiscoMatchType,
aEndDiscoDomainName,
aEndDiscoSearchTerm,
zEndNCIMMatchType,
zEndNCIMDomainName,
zEndNCIMSearchTerm,
topologyEntityType
)
VALUES
(
1,
// entryNo
’ADD’,
// action
1,
// onlyAdminUp - must be up
’EXACT’,
// aEndDiscoMatchType
’NCOMS’,
// aEndDiscoDomainName
’connection to vmhost_network’, // aEndDiscoSearchTerm
’EXACT’,
// zEndNCIMMatchType
’NCOMSADJ’,
// zEndNCIMDomainName
’connection to vmhost_network’, // zEndNCIMSearchTerm
72
// topologyEntityType
);
The following example shows an insert that connects all interfaces in the NCOMS
domain whose descriptions match the regular expression ELON(GW|WR|AR) to all
interfaces in the NCOMSADJ domain whose descriptions contain the string
connection to PE2_ASBR_AS2:
INSERT INTO linkDomains.interfaceDescriptionMatch
(
entryNo,
action,
onlyAdminUp,
aEndDiscoMatchType,
aEndDiscoDomainName,
aEndDiscoSearchTerm,
zEndNCIMMatchType,
216
IBM Tivoli Network Manager IP Edition: Discovery Guide
zEndNCIMDomainName,
zEndNCIMSearchTerm,
topologyEntityType
)
VALUES
(
2,
’ADD’,
1,
’REGEX’,
’NCOMS’,
’ELON(GW|WR|AR)’,
’EXACT’,
’NCOMSADJ’,
’connection to PE2_ASBR_AS2’,
72
);
//
//
//
//
//
//
//
//
//
//
entryNo
action
onlyAdminUp - must be up
aEndDiscoMatchType
aEndDiscoDomainName
aEndDiscoSearchTerm
zEndNCIMMatchType
zEndNCIMDomainName
zEndNCIMSearchTerm
topologyEntityType
Related reference:
“Cross-domain stitchers” on page 514
Cross-domain stitchers look for links between devices in different domains and
create connections between them in the topology.
Running cross-domain discoveries
Before creating your cross-domain network views, run cross-domain discoveries.
Before running cross-domain discoveries, configure how the cross-domain links are
built.
To run your cross-domain discoveries, complete the following steps:
1. Run a full discovery in your first domain.
2. Run a full discovery in your second domain.
3. Run a full discovery in any other domains. After discovering all domains once,
some connections might be duplicated, and your links between domains might
not be as expected.
4. Run a second full discovery in every domain. Any inferred connections are
replaced by discovered connections.
The links between each domain are added by the cross-domain stitchers. The
AGGREGATION domain is created by the aggregation stitching, which runs at the
end of discovery (and whenever the topology is updated).
Create any network views you want, using the AGGREGATION domain.
Creating cross-domain network views
After running your cross-domain discoveries, create cross-domain network views
to visualize your network. You can create standard or dynamic network views.
Before creating a cross-domain network view, you must configure and run
cross-domain discoveries for each domain that you want to aggregate.
To create network views across domains, complete the following steps:
1. Click the Incident icon and select Network Availability > Network Views.
2. Within Network Views, in the Libraries tab, click New View
.
3. Complete the General tab as follows:
Chapter 2. Configuring network discovery
217
Name Type a name for the network view, dynamic view, or network view
container.
Important: It is best practice to use network view names containing
Latin characters only. Network views names containing non-Latin
characters (for example Cyrillic characters) are not supported as they
cannot be imported and exported when migrating to a new version of
Network Manager.
Parent Select the node under which the view appears in the hierarchy in the
Navigation Tree. To display the view on the top level, select NONE.
Type
Select a type of network view. Because the resulting network view will
contain all devices from all discovered networks, consider the size of
the network views so as not to create unnecessary load on the server.
Fill in the other fields as appropriate for that type of network view.
4. Click the Filter tab. Complete the tab as follows:
Domain
Select the AGGREGATION domain.
Fill in the other fields as appropriate for that type of network view.
5. Click OK. The new view is added to the navigation tree in the Navigation
Panel. If you added the view to a container, expand the container node to see
the new view in the tree.
Your network view shows devices from all discovered domains.
Example: Small network or Proof of Concept (POC)
If you want to check whether two or more domains have been discovered and
joined together as you expect, you could recreate all the network views that are
usually created automatically after a discovery finishes. Do this only if you are
sure that the total of the resulting network views will not have an adverse
performance impact. For example, you might want to do this while testing
cross-domain discovery, on a non-production system. To create all the usual
network views, complete the following steps:
1. Create a new network view of type Dynamic Views - Template.
2. Select the domain AGGREGATION.
3. Select the template IP Default.
Checking cross-domain links
After creating your cross-domain network views, check that you see the links
between domains that you expect.
Before checking the links between domains, ensure that you have run a full
cross-domain-enabled discovery twice in each domain.
If you do not see the links between the domains that you expect, complete the
following steps:
1. Ensure that the appropriate agents are enabled for the technologies and devices
that are on the edges of your domains.
2. Ensure that all the appropriate technologies are enabled for the cross-domain
stitching.
3. Check that the boundary between domains is appropriate.
218
IBM Tivoli Network Manager IP Edition: Discovery Guide
It is important to scope your discovery domains to ensure the minimum of
links between domains. For example, you would not normally split the
network such that highly connected switches were in different domains.
Natural splits for domains are often along geographical lines.
Restriction:
However you split your network, you must ensure that any given device
appears in only one domain. That is, the discovery domains must not overlap if
you want to join them together using cross-domain discovery.
4. If you know that links between devices in different domains are present, but
they are not shown in the Network Views, you can add or edit the links
manually.
Related tasks:
“Adding and editing cross-domain links manually” on page 214
If you do not see links between devices in different domains, you can manually
create or configure them.
Configuring geographical discoveries
Fix Pack 2
Before you can view devices in their geographical context, you must configure a
geographical discovery. Choose a method of enriching devices with geographical
information.
Configuring a mapping provider
Fix Pack 3
Before you run the first geographical discovery, configure the mapping provider
that you want to use.
1. Ensure that you have the correct licenses for any mapping provider that you
intend to use. No licenses for any mapping providers are included with
Network Manager.
2. Back up and edit the following file: $JazzSM_HOME/profile/installedApps/
JazzSMNode01Cell/isc.ear/ncp_gis.war/resources/config.json
3. Edit the mapProvider section.
The following code extracts show an example section from the config.json file.
Chapter 2. Configuring network discovery
219
1]
2]
3]
4]
5]
6]
7]
8]
9]
10]
11]
12]
13]
14]
15]
16]
17]
18]
19]
20]
21]
22]
23]
24]
25]
26]
"mapProvider": {
"baseMapLayerName": "IBM Network Management",
"baseLayer": "osm",
"baseLayersDefn": {
"osm": {
"baseLayerName": "OpenStreetMap"
},
"bing": {
"baseLayerName": "Microsoft Bing",
"imagerySet": "Road",
"key": "${myBingKey}"
},
"xyz": {
"baseLayerName": "OpenLayer XYZ Format",
"urls": ["https://api.mapbox.com/styles/v1/mapbox/streets-v9
/tiles/256/{z}/{x}/{y}?access_token="]
},
"google": {
"baseLayerName": "Google",
"url": "https://maps.google.com/maps/api/js?libraries=
visualization,drawing,geometry&v=3.exp"
}
"wms": {
"baseLayerName": "My Custom GeoServer WMS Layer",
"url": "https://offline:443/geoserver/wms",
"params": {}
}
}
4. Set the provider that you want to use by editing the baseLayer value.
In the preceding example, the baseLayer value is set to osm on line 3.
You can specify only one of the following defined keywords for the baseLayer
value:
v bing for Bing Maps
v osm for Open Streetmap
v wms for Web Map Service
v xyz for OpenLayer XYZ format
v google (deprecated as of V4.2 Fixpack 3)
o
You can customize the baseLayerName and baseMapLayerName values.
Important: Do not delete any empty sections from the config.json file.
Missing sections can cause errors.
Enriching discovery with geographical data
Fix Pack 3
To display geographical maps, you must enrich the network topology with
geographical data.
Enriching the network topology with geographical data requires several steps:
v Retrieve the geographical data from an external database or system.
v Add the geographic data to the topology.
v Create a collection in Network Manager that collects devices to a geographic
location.
v Optionally, create collections to represent hierarchies of geographical regions.
220
IBM Tivoli Network Manager IP Edition: Discovery Guide
Note: Customizing discovery is an advanced procedure. You must be familiar with
the discovery data flow, general database administration, and the stitcher language.
To retrieve the geographical data, two options are to add it to the SysLocation field
in the device record by using a script, or to export it from a database to a .csv file.
Other options are possible depending on how your data is stored.
To create collections and add geographical data to the topology, you must use the
stitcher language. Two example methods are supplied with the product: the
GeoBySysLocation and GeoByLookup stitchers.
v The GeoBySysLocation stitcher calls a PostLayerProcessing stitcher
AddGeoLocationData. The AddGeoLocationData stitcher extracts the location
description, longitude, and latitude from the SysLocation field during a network
discovery. The location data populates the m_ExtraInfo->geographicLocation
field in the workingEntities.finalEntity database table to build the geographic
location collection.
v The GeoByLookup stitcher calls a DNCIM InferDNCIMObjects stitcher
PopulateDNCIM_CustomGeography. The GeoByLookup stitcher builds a hierarchy of
geographic regions-> geographic locations-> devices, by resolving the
geographical data from an external database. The GeoByLookup stitcher can be
called by a customer stitcher such as the example ACMEDeviceLocationEnrich
stitcher. The example ACMEDeviceLocationEnrich stitcher resolves IP addresses to
geographical locations to create a hierarchy of Address -> City -> State ->
Country.
Example: Configuring geographical discovery by using location data from device
records:
Fix Pack 3
One way to enrich devices with geographical data is by using location data from
the device records.
The AddGeoLocationData stitcher is provided as a demonstration of one method of
adding geographic information from device records. This stitcher assumes that
valid geographical data was added to the device record in the SysLocation field in
the following format: location address;longitude;latitude. Your network
administrator can set the SysLocation field on devices manually or by using a
script. To use a different field, modify the stitcher.
To configure discovery to use geographical data from the SysLocation, complete
the following steps.
1. Back up and edit the following stitcher: $NCHOME/precision/disco/stitchers/
PostLayerProcessing.stch.
2. Add the following line at the appropriate place in the file for your discovery
data flow, for example, at the end:
ExecuteStitcher(’AddGeoLocationData’);
3. Run a discovery. The AddGeoLocationData stitcher adds geographic data to the
appropriate fields within the m_ExtraInfo field.
Chapter 2. Configuring network discovery
221
Example: configuring geographical discovery by using location data from a file:
Fix Pack 2
One way to enrich devices with geographical data is by importing location data
from a comma-separated values (.csv) file into the NCIM topology database.
To enrich devices with geographic data by using a .csv file, adapt the following
example steps to your needs.
1. Create a .csv file that contains location information for the devices you want to
view in geographical views. For example, you can export the data from a
database to file.
The location information must be in the following format:
ip,address,city,state,country,latitude,longitude
The following example shows the top two lines of a .csv file.
IP, ADDRESS, CITY, STATE, COUNTRY, LATITUDE, LONGITUDE
192.168.0.1,"113620 Redwood Gulch Rd, Cupertino, CA 95014, USA",
PLAL,CA,US,37.15458,-122.05561
The sample ACMEDeviceLocationEnrich.stch stitcher expects the .csv file to be
in this format. If you want to use a different format, you must modify the
stitcher.
2. Create a database table in the NCIM topology database to store geographical
data.
The sample ACMEDeviceLocationEnrich.stch stitcher expects this table to be
called ACMEGeoLocation. If you want to use a different table name, you must
modify the stitcher.
For DB2, the database table must contain fields of the following types and
specifications:
IP VARCHAR(255) NOT NULL,
ADDRESS VARCHAR(255),
CITY VARCHAR(255),
STATE VARCHAR(255),
COUNTRY VARCHAR(255),
LATITUDE DECIMAL(10 , 8) NOT NULL DEFAULT 0,
LONGITUDE DECIMAL(11 , 8) NOT NULL DEFAULT 0
For Oracle, the database table must contain fields of the following types and
specifications:
IP VARCHAR(255) NOT NULL,
ADDRESS VARCHAR(255),
CITY VARCHAR(255),
STATE VARCHAR(255),
COUNTRY VARCHAR(255),
LATITUDE NUMBER(15,8) DEFAULT 0 NOT NULL,
LONGITUDE NUMBER(15,8) DEFAULT 0 NOT NULL
3. Import the geographical data from the .csv file into the database table you
created using your choice of database tool.
For example, to load a file core_lat_long_all.csv into a table
ACMELOOKUPGEOLOCATION in an NCIM database on Oracle by using Oracle loader
V12.1, run the following command from the Oracle directory.
sqlldr SYSTEM/PASSWORD@mySchema control=/opt/oracle/load.ctl
Where the load.ctl file contains the following code.
LOAD DATA
infile ’LOAD DATA
infile ’core_lat_long_all.csv’
REPLACE
INTO TABLE NCIM.ACMELOOKUPGEOLOCATION
222
IBM Tivoli Network Manager IP Edition: Discovery Guide
fields terminated by ’,’ optionally enclosed by ’"’
(
IP,
ADDRESS,
CITY,
STATE,
COUNTRY,
LATITUDE,
LONGITUDE
)
The commands for other versions or other tools are different.
4. Back up and edit the following stitcher: $NCHOME/precision/disco/stitchers/
DNCIM/InferDNCIMObjects.stch.
5. Uncomment this line:
ExecuteStitcher(’ACMEDeviceLocationEnrich’, domainId,
isRediscovery, dynamicDiscoNode );
6. Run a discovery.
The PopulateDNCIM_CustomGeography.stch stitcher adds devices to the correct
geographical collections based on their location data.
The ACMEDeviceLocationEnrich.stch stitcher populates the geographic tables in the
DNCIM discovery database with data from the NCIM database table that you
created.
Integrating an online or offline Web Map Service
Fix Pack 3
You can set up a WMS (Web Map Service) integration to display geographical
maps. Some WMS integrations can display maps without internet access.
To integrate a WMS, complete the following steps:
1. Install a mapping provider that implements the WMS standard. Refer to the
documentation for the version of the provider that you are installing.
2. Configure the mapping provider to use SSL.
3. Run the mapping provider and verify that it is working correctly. You might
want to cache a public WMS as a test.
4. Configure the geographical maps to use a WMS mapping provider.
a. Back up and edit the following file: $JazzSM_HOME/profile/installedApps/
JazzSMNode01Cell/isc.ear/ncp_gis.war/resources/config.json
b.
Set the baseLayer value to wms.
c. Configure a new baseLayersDefn section and specify the correct parameters.
The WMS parameters that are accepted by OpenLayers are listed at
http://openlayers.org/en/latest/apidoc/ol.source.TileWMS.html. The
parameters that you must use are defined in the WMS request specification
of your WMS server.
Use the following syntax for parameters: "PARAM_NAME":"PARAM_VALUE". To
avoid errors, use a validation tool to validate the JSON.
The following example configures parameters for a GeoServer integration.
"baseLayer": "wms",
"baseLayersDefn": {
.....
},
"wms": {
"baseLayerName": "My Custom GeoServer WMS Layer",
Chapter 2. Configuring network discovery
223
"url": "https://offline:443/geoserver/wms",
"params": {
"REQUEST": "GetMap",
"FORMAT": "image/png",
"SRS": "EPSG:4326",
"BBOX": "-104.2822265625,33.5302734375,-87.4072265625,40.78125",
"VERSION": "1.1.1",
"STYLES": "",
"SERVICE": "WMS",
"WIDTH": "768 ",
"HEIGHT": "330",
"TRANSPARENT": "true",
"LAYERS": "topp:states"
}
}
If you do not specify any parameters in the "params": {} section, leave the
section empty.
Important: Do not delete any empty sections from the config.json file.
Missing sections can cause errors.
You can customize the baseLayerName and baseMapLayerName values.
For offline map integration, the baseLayer value must be wms.
Adding custom map layers
You can add custom layers to geographical maps. For example, you can add
geographical information that is made available by a public server.
Configure an offline mapping provider, if you want the custom layer to be
available offline.
The following mapping provider types are supported:
v ArcGISRest
v Web Map Service (WMS)
To add a custom map layer, complete the following steps:
1. Back up and edit the following file: $JazzSM_HOME/profile/installedApps/
JazzSMNode01Cell/isc.ear/ncp_gis.war/resources/config.json
2. Create a new customLayers section and specify the correct parameters.
The WMS parameters that are accepted by OpenLayers are listed at
http://openlayers.org/en/latest/apidoc/ol.source.TileWMS.html. The
parameters that you must use are defined in the WMS request specification of
your WMS server. Use the following syntax for parameters:
"PARAM_NAME":"PARAM_VALUE". To avoid errors, use a validation tool to validate
the JSON.
The ArcGISRest parameters that are accepted by OpenLayers are listed at
http://openlayers.org/en/latest/apidoc/ol.source.TileArcGISRest.html.
The following example configures parameters for one WMS custom layer and
one ArcGISRest custom layer.
"customLayers": [
{
"layerName": "Drainage Divisions",
"layerType": "wms",
"url": "http://geoserver.nationalmap.nicta.com.au/
admin_bnds_abs/ows",
"params": {
"LAYERS": "admin_bnds:ADD_2011_AUST"
}
224
IBM Tivoli Network Manager IP Edition: Discovery Guide
}, {
"layerName": "Prohibited Areas",
"layerType": "arcGISRest",
"url": "http://services.ga.gov.au/gis/rest/services/
NM_Reserves/MapServer",
"params": {}
}
]
If you do not supply any arcGISRest parameters, include the line but leave it
empty: "params": {}. Removing or omitting sections from the file causes errors.
You can customize the baseLayerName and baseMapLayerName values.
For custom map layers, the layerType value must be one of the following
supported values:
v wms
v arcGISRest
3. Define multiple layers if you want. The z-index of the layers is defined by their
position in the file. To display one layer above another layer, define it higher in
the file.
Verifying geographical discoveries
Fix Pack 2
After you run a geographical discovery, verify that it ran successfully.
To check that the geographical discovery ran successfully, complete the following
steps:
1. Check the logs for the ncp_disco process in the $NCHOME/log/precision
directory to find out if the geographical stitchers that you configured are
working.
2. Query the location tables in the NCIM topology database to find out if they are
populated with geographic data.
For example, use the following command:
select * from NCIM.geographicLocation
3. Log into Dashboard Application Services Hub. Open the following URL:
https://server:port/ibm/console/nm_rest/topology/devices/geo/all
If geographical discovery completed successfully, JSON results for the
geographically enriched devices are displayed.
4. Open a geographic view and check that the expected devices appear.
Chapter 2. Configuring network discovery
225
226
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 3. Monitoring network discoveries
You can monitor the state and progress of your network discoveries. In addition
you can monitor full discovery and partial discovery by running OQL queries from
the command line.
Monitoring network discovery from the GUI
From the Active Discovery Status page, you can monitor the status and progress of
the current full or partial discovery, investigate the work of the discovery agents,
and view details of the last full discovery.
From the Active Discovery Status page, you can also start and stop full and partial
discoveries.
Related tasks:
“Starting a discovery” on page 52
After you configure a discovery, you can start and, if necessary, stop the discovery.
“Reviewing the configuration” on page 26
On the Configuration Summary window, review your settings. You can also save
the settings here, and, optionally, start the discovery with the settings that you
configured.
“Manually discovering a device or subnet” on page 255
You can manually discover devices so that the network topology in Network
Manager matches the network.
“Starting partial discovery from the GUI” on page 257
Starting a partial discovery involves defining a seed and scopes.
Monitoring full and partial discoveries
You can monitor the state and progress of your full or partial discovery using the
GUI.
Monitoring full and partial discovery progress
You can use the Monitoring tab to monitor the progress of the current full or
partial discovery through each of the discovery phases.
Complete the following steps to monitor the progress of the current full or partial
discovery.
1. Click the Discovery icon and select Network Discovery Status.
2. Select a domain.
3. Click the Monitoring tab.
4. Start either a full or partial discovery by selecting the option from the Start
Discovery button
.
The following phases are shown in the table.
© Copyright IBM Corp. 2006, 2017
227
Interrogating Devices
During this phase, devices are first discovered by the finders, and then
information is retrieved from the devices by the agents. This phase is also
known as phase 1.
Resolving Addresses
During this phase, the agents resolve IP to MAC address translations. This
phase is also known as phase 2.
Downloading Connections
During this phase, the switch agents download the forwarding tables from
the switches in the network. This phase is also known as phase 3.
Correlating Connections
During this phase, the connectivity between the devices is calculated, the
containment model is created, and the network topology is built. This
phase is also known as phase -1.
You can see which phase the current discovery is in by looking at the Status
column of the table. If a phase has not started, this column is empty. If a phase is
in progress, this column shows a spinning wheel icon. If a phase has completed
successfully, this column shows a green tick icon.
Status Shows the status of a particular phase. The column shows the following
kinds of status.
Table 27. Discovery phase status
State
Icon
Description
Completed
If a phase has completed successfully, this column shows a green
tick icon.
In
progress
If a phase is in progress, this column shows a spinning wheel
icon.
Not
started
If a phase has not started, this column is empty.
You can see how long each phase is taking in the Elapsed Time column in the
table. Each phase takes a different amount of time depending on the scope of the
discovery, the complexity of the network, and the amount of detail being retrieved
from the devices. If the elapsed time continues to increase, and the work
completed does not increase, the discovery might be encountering problems.
Remember: In the first phase, the count of IP addresses discovered stops
increasing part way through the phase. This is part of the normal operation of the
discovery. The count of IP addresses discovered only increases during the first part
of the phase, while the finders discover new devices. In the latter part of the
phase, the discovery agents retrieve information from these devices, and new IP
addresses are not discovered.
The Discovery Agents section shows the progress of the discovery agents. If you
think that a phase is taking too long to complete, click the Discovery Agents tab to
see what the discovery agents are doing.
You can see the progress within a phase in the Work Completed column in the
table. For the first phase, this column shows the number of IP addresses found so
far. For the other phases, this column shows the percentage of work completed in
the phase.
228
IBM Tivoli Network Manager IP Edition: Discovery Guide
Related concepts:
“Discovery stages and phases” on page 425
The discovery process can be divided into two stages: data collection and data
processing. The stages are subdivided into phases.
Comparing full discoveries
You can use the Monitoring tab to compare the current discovery to the previous
full discovery.
You cannot compare partial discoveries. Within the table, the data in the Previous
columns is for the last full discovery. Complete the following steps to compare
fully discoveries.
1. Click the Discovery icon and select Network Discovery Status.
2. Within Network Discovery Status, click the Monitoring bar.
You can see the time that is taken to complete each phase of the previous
discovery in the Previous subcolumn of the Elapsed Time column.
Note: To display discovery times from all previous discoveries, run the
disco_profiling_data.pl script from the command line. For more information
about the disco_profiling_data.pl script, see the IBM Tivoli Network Manager IP
Edition Administration Guide.
The time that is taken for each phase depends on the scope of the discovery, the
complexity of the network, and the amount of detail that is retrieved from the
devices. If the network is not changed significantly, and the discovery scope and
settings are not changed significantly, but the elapsed time for a phase in the
current discovery is more than the time taken for the same phase in the previous
discovery, the discovery might be encountering problems.
You can see how many IP addresses are being found in the current discovery and
how many were found in the previous discovery in the Work Completed column
in the table. If fewer IP addresses are found in the current discovery, there might
be a problem with the scope of the discovery, or with SNMP access to devices.
Monitoring ping finder progress
You can use the Ping Finder Status table to monitor the progress of the ping
finder during a full discovery.
To open Ping Finder Status, complete the following steps.
1. Click the Discovery icon and select Network Discovery Status.
2. Within Network Discovery Status, click the Ping Finder Status tab.
You can use the Ping Finder Status table to see which IP addresses and subnets
are discovered up to this point. If the ping finder is processing a subnet, you can
also see which IP address was last pinged.
The Ping Finder Status table contains the following information:
Address
A list of IPs and subnets discovered to this point.
Netmask
For each subnet, this column indicates the netmask value.
Chapter 3. Monitoring network discoveries
229
Last Pinged
The last IP address pinged.
Status Indicates whether the Ping finder is still pinging this device or subnet or
whether it has completed pinging.
Table 28. Ping finder status
State
Icon
Description
Completed
Ping finder has completed the pinging of this subnet or IP
address.
Started
Ping finder is currently pinging this subnet or IP address.
Stopped
Ping finder has not started pinging this subnet or IP address.
Awaiting
status
System is awaiting Ping finder status for this subnet or IP
address.
Monitoring discovery agent progress
You can use the Agents Status section to monitor the progress of the discovery
agents during a full or partial discovery.
Discovery agents gather data from discovered devices. This data is used during the
Correlating connectivity phase of the discovery (phase -1) to build the network
connectivity and containment.
You can use the Agents Status to answer these and other questions as the
discovery is running:
v Are all agents running okay?
v Have any agents failed?
v Are any agents failing to complete?
v Which device is a particular agent currently working on?
Complete the following steps to open Agents Status and to monitor the progress
of the discovery agents.
1. Click the Discovery icon and select Network Discovery Status.
2. Click the Agents Status tab. The Agents Status section contains two tables, the
Agents Status table at the top and the Entity Status table below. The Agents
Status table toolbar contains the following controls.
Filter Agents by Phase
Use the phase drop-down list to select a discovery phase. The agents
table then displays the following agents:
v Full or partial discovery: all discovery agents that have started during
the current discovery and that are scheduled to finish in the
discovery phase that you selected.
Refresh
Refreshes the data in both the Agents Status and Entity Status table.
The icon changes to the Refreshing icon
while the table data is
being refreshed. You cannot refresh the tables again until the refresh
has completed.
230
IBM Tivoli Network Manager IP Edition: Discovery Guide
The Agents Status table lists all the agents that have started so far during this
discovery and contains the following information. This information is updated
every 20 seconds. When you first open this table, it is sorted by descending
order of State.
Agent Discovery agents that have started during the current discovery and
that are scheduled to finish in the discovery phase that you selected.
Completes in Phase
The phase in which the discovery agent completes.
State
Current state of the discovery agent. Possible states, in the default
descending order, are listed in the following table.
Table 29. Agent states
State
Value
Icon
Description
Died
5
The agent has terminated unexpectedly. This is a
potential discovery problem.
Finished
4
The agent is still running but has finished processing of
all the entities in its queue. The agent is still available to
process any further agents placed in the queue.
Running
3
The agent is currently processing entities.
Starting
2
The agent is starting up.
Not
running
1
The Agent is not running.
Total Entities
The total number of entities that this agent is required to process. This
number varies as follows:
v Full or partial discovery: the total number of entities that this agent is
required to process increases as the discovery progresses and the
finders discover more devices that need to be processed by the agent.
Outstanding Entities
The number of entities that are waiting to be processed by this agent.
This number can go up and down during the discovery. The number
increases initially as the discovery progresses and the finders discover
more devices that need to be processed by the agent. As the agent
completes processing entities, this number decreases until it reaches
zero.
Note: If this value does not go down to zero during the discovery, this
means that the agent was unable to complete processing on one or
more entities and there is a potential discovery problem.
3. Click an agent in the Agents Status table. The Entity Status table lists the
entities that have been processed or are currently being processed by this agent.
The Entity Status table responds to changes in the Agents Status table. The
table updates in the following situations: when a new agent is selected in the
Agents Status table; when changing the filtering of the Entity Status table by
All or Queue; and when the Agents Status table Refresh
button is pressed.
When you first open this table, it is sorted by descending order of State.
Chapter 3. Monitoring network discoveries
231
Agent_name
Use this radio button to specify whether to display all entities (All) or
only entities queued for processing (Queue). The default setting is
Queue.
All
Set the Details table to display all entities for this agent. This
includes entities that have been queued for processing by the
agent, entities currently being processed by the agent, and
entities that have already been processed by the agent.
Queue
Set the Details table to display only entities that have been
queued for processing by this agent.
Identifier
Identifier for entities processed by this agent. If All is selected, then this
column displays entities processed, in processing, or queued for
processing by this agent. If Queued is selected, then this column
displays entities queued for processing by this agent.
State
Current state of the entity. Possible states, in the default descending
order, are listed in the following table:
Table 30. Entity states
State
Value
Icon
Description
Died
5
Processing of the entity terminated unexpectedly. Either
the agent was stopped manually, or there is a discovery
problem.
Finished
4
An agent has completed processing this entity.
Running
3
An agent is currently processing this entity.
Starting
2
An agent is beginning to process this entity.
Not
running
1
This entity is not currently being processed.
Elapsed Time
The time taken for the agent to process this entity, expressed in the
format HH:MM:SS. This value is only displayed for those entities that
have completed processing.
Despatch Time
The date and time at which the agent began processing this entity. This
value is only displayed for those entities for which processing has
begun or completed.
Return Time
The date and time at which the agent retrieved data for this entity. This
value is only displayed for those entities that have completed
processing.
SNMP Access
Indicates whether the agent was able to access this entity using SNMP.
Related tasks:
“Troubleshooting an unusually long discovery” on page 265
A discovery might be taking a long time to complete because an agent is unable to
complete processing on a specific device. Use the Agents Status section to
determine which agent is taking a long time to complete and which device it is
232
IBM Tivoli Network Manager IP Edition: Discovery Guide
working on.
“Identifying failed agents” on page 266
A source of discovery failure can be agents that terminate unexpectedly during
discovery. Use the Agents Status section to determine whether any agents
terminated unexpectedly.
Monitoring discovery from the command line.
When the ncp_disco process is running, you can monitor the progress of the
discovery by using the OQL Service Provider, the ncp_oql process, to query the
discovery databases to determine what is happening at any time.
Related tasks:
“Discovering the network using the command-line interface” on page 56
As an experienced user, you can configure and track a network discovery using
configuration files and database queries.
Monitoring full and partial discoveries
You can monitor the state and progress of your full or partial discovery using the
command line.
The queries presented in the subsequent topics have been generalized for all
discovery scenarios and are not limited to the layer 3 discovery.
The examples are given only to demonstrate the amount of flexibility you have
when retrieving information from databases using OQL. Using the schematic
definitions of all the databases and knowledge of OQL syntax, you can construct
queries that answer any questions you have regarding the current status of the
discovery process.
You can issue simple queries to find out, for example, what the ncp_disco process
is currently doing, which discovery agents have discovered devices, or how many
devices have been discovered so far. You can also issue complex queries to find
out, for example, which devices have been discovered by a specific discovery
agent, or which discovery agents have interrogated a specific device.
For information on starting the OQL Service Provider, including prerequisites, see
the IBM Tivoli Network Manager IP Edition Language Reference.
Sample discovery status queries
You can use queries similar to these examples to find out the status of different
parts of the discovery.
Sample: Determining which address the Ping finder is pinging
The following query returns the current address being pinged by the Ping finder:
select m_CurrentAddress from pingFinder.status;
go
.
{
m_CurrentAddress=192.168.0.1;
}
Chapter 3. Monitoring network discoveries
233
Sample: Identifying the current phase of the discovery
The following example shows how to identify the current phase of the discovery.
The results of the above query show that the discovery process is still in data
collection phase 1.
select * from disco.status;
go
.
{
m_DiscoveryMode=0;
m_Phase=1;
m_BlackoutState=0;
m_CycleCount=0;
m_ProcessingNeeded=0;
m_FullDiscovery=0;
}
Sample: Identifying the status of a NAT discovery
This example shows how to identify the status of the NAT discovery.
select m_NATStatus from disco.NATStatus;
go
.
{
m_NATStatus=3;
}
Sample: Identifying which agents are enabled
This example shows how to identify whether you have enabled the appropriate
discovery agents.
select m_AgentName, m_Valid from disco.agents
where m_Valid = 1;
go
...
{
m_AgentName=’Details’;
m_Valid=1;
}
{
m_AgentName=’AssocAddress’;
m_Valid=1;
}
{
m_AgentName=’IpRoutingTable’;
m_Valid=1;
}
{
m_AgentName=’IpForwardingTable’;
m_Valid=1;
}
Sample: identifying the status of the discovery stitchers
The following example shows how to identify the status of the stitchers by
querying the stitchers.status table.
select * from stitchers.status
where m_State > 0 ;
go
.........
{
m_Name=’AgentRetToInstrumentationSubnet’;
234
IBM Tivoli Network Manager IP Edition: Discovery Guide
m_State=3;
}
{
m_Name=’DetailsRetProcessing’;
m_State=3;
}
.....
.....
{
m_Name=’DetectionFilter’;
m_State=3;
}
{
m_Name=’FnderProcToDetailsDesp’;
m_State=3;
}
{
m_Name=’FnderRetProcessing’;
m_State=3;
}
The results from the query show the current status of all stitchers that have been
called by the discovery process so far. Note that the results shown above have
been abbreviated.
Sample: identifying which agents are active
The following example shows how to query the status of the agents in the agents
database.
select * from agents.status
where m_State > 0 ;
go
..
{
m_Name=’Details’;
m_State=3;
m_NumConnects=1;
}
{
m_Name=’IpRoutingTable’;
m_State=3;
m_NumConnects=1;
}
The results of the above query show that only the Details agent and the
IpRoutingTable agent are active (that is, they have a state greater than zero).
Related reference:
Appendix A, “Discovery databases,” on page 293
There are various specialized databases that are used by ncp_disco, the component
that discovers network device existence and connectivity, and by ncp_model, the
component that manages, stores, and distributes the discovered network topology.
Chapter 3. Monitoring network discoveries
235
Sample device queries
You can use queries similar to these examples to identify devices that meet certain
criteria, for example, devices that have been found by the finders.
Sample: Identifying which devices have been found by the finders
The following example shows how to identify devices that have been found by the
finders.
select * from finders.processing;
go
....
{
m_UniqueAddress=’172.20.12.253’;
m_Protocol=1;
m_Creator=’IpRoutingTable’;
}
{
m_UniqueAddress=’172.20.22.61’;
m_Protocol=1;
m_Creator=’IpRoutingTable’;
}
{
m_UniqueAddress=’172.20.0.221’;
m_Protocol=1;
m_Creator=’IpRoutingTable’;
}
{
m_UniqueAddress=’10.10.35.17’;
m_Creator=’PingFinder’;
}
The above query shows the devices discovered by the Ping finder as well as
devices reported as a result of connections discovered by the IpRoutingTable
Discovery agent.
Sample: Identifying devices that have been sent to the Details agent
The following example shows how to identify devices that have been sent to the
Details agent.
select * from Details.despatch;
go
.................................................................
................................
{
m_UniqueAddress=’10.10.38.82’;
}
{
m_UniqueAddress=’10.10.38.83’;
}
.....
.....
{
m_UniqueAddress=’10.10.38.84’;
}
{
m_UniqueAddress=’10.10.38.87’;
}
{
m_UniqueAddress=’10.10.38.88’;
}
{
m_UniqueAddress=’10.10.38.89’;
236
IBM Tivoli Network Manager IP Edition: Discovery Guide
}
{
m_UniqueAddress=’10.10.38.90’;
}
Sample: Identifying devices that have been returned from the Details
agent
To identify which devices have returned from the Details agent, query the returns
table of the Details agent, as shown below.
select * from Details.returns;
go
.................................................................
................................
{
m_UniqueAddress=’10.10.8.255’;
m_UpdAgent=’Details’;
m_HaveAccess=1;
m_Description=’Ascend Max-HP T1/PRI S/N;
m_ObjectId=’1.3.6.1.4.1.529.1.2.6’;
m_LastRecord=1;
}
{
m_UniqueAddress=’10.10.9.1’;
m_UpdAgent=’Details’;
m_Name=’minotaur.Kazeem.San.COM’;
m_HaveAccess=0;
m_LastRecord=1;
}
.....
.....
{
m_UniqueAddress=’10.10.9.2’;
m_UpdAgent=’Details’;
m_Name=’cyclops.Kazeem.San.COM’;
m_HaveAccess=0;
m_LastRecord=1;
}
{
m_UniqueAddress=’10.10.9.3’;
m_UpdAgent=’Details’;
m_Name=’centaur.Kazeem.San.COM’;
m_HaveAccess=0;
m_LastRecord=1;
}
Sample: Identifying all devices discovered until now
The following example shows how to identify all known network entities.
select m_Name, m_ObjectId, m_UniqueAddress
from workingEntities.finalEntity;
go
..................................
{
m_Name=’10.10.8.255’;
m_ObjectId=’1.3.6.1.4.1.529.1.2.6’;
m_UniqueAddress=’10.10.8.255’;
}
{
m_Name=’minotaur.Kazeem.San.COM’;
m_UniqueAddress=’10.10.9.1’;
}
.....
.....
Chapter 3. Monitoring network discoveries
237
{
m_Name=’cyclops.Kazeem.San.COM’;
m_UniqueAddress=’10.10.9.2’;
}
Sample: Identifying which agents have discovered devices
The following example shows how to identify the agents that have discovered
devices.
select m_Name, m_Creator
from workingEntities.finalEntity;
go
..................................
{
m_Name=’b11-m1-2611.Kazeem.San.COM[ 0 [ 2 ] ]’;
m_Creator=’IpRoutingTable’;
}
{
m_Name=’b-ayo.Kazeem.San.COM’;
m_Creator=’Details’;
}
{
m_Name=’b11-m1-2611.Kazeem.San.COM[ 0 [ 1 ] ]’;
m_Creator=’IpRoutingTable’;
}
.....
.....
{
m_Name=’b11-m1-2611.Kazeem.San.COM’;
Sample: Determining the different types of interfaces discovered
The following example shows how to identify the interface types on each
discovered device. Use the select DISTINCT keyword to deduplicate the multiple
interface type entries that are stored for each device in the
workingEntities.finalEntity table.
select DISTINCT m_LocalNbr->m_IfType, m_ObjectId
from workingEntities.finalEntity
where m_EntityType = 2;
go
..................................
{
m_IfType=166;
m_ObjectId=’1.3.6.1.4.1.9.1.222’;
}
{
m_IfType=6;
m_ObjectId=’1.3.6.1.4.1.9.1.222’;
}
{
m_IfType=1;
m_ObjectId=’1.3.6.1.4.1.9.1.222’;
}
{
m_IfType=6;
m_ObjectId=’1.3.6.1.4.1.9.1.310’;
}
{
m_IfType=22;
m_ObjectId=’1.3.6.1.4.1.9.1.310’;
}
..................................
238
IBM Tivoli Network Manager IP Edition: Discovery Guide
Sample: Monitoring agents in the current phase
Use the following example query to identify which agents the current phase is
waiting on before it can complete. The following example query does this by
listing the names of all the agents that finish in the current phase and that meet
the following criteria:
v The agent is valid. (m_State <> 0)
v The agent is currently in use. (m_State <> 1)
v The agent status is not yet complete. (m_State <> 4)
select m_Name from agents.status
where
m_State <> 0 AND
m_State <> 1 AND
m_State <> 4 AND
m_CompletionPhase IN (( select m_Phase from disco.status )) ;
Once you have identified which agents still need to complete in the current phase,
use the following query to determine which devices those agents are working on.
select
m_Name,
m_UniqueAddress,
m_ObjectId,
m_Description
from
<agentName>.despatch
where
m_UniqueAddress NOT IN
(( select m_UniqueAddress from <agentName>.returns where m_LastRecord = 1 )) ;
Sample network entity queries
You can use queries on the instrumentation database to identify whether network
entities such as subnets and VLANs have been discovered. The instrumentation
database tables store a record of every discovered device.
Sample: Identifying the number of discovered subnets
The following example query returns details of the discovered subnets.
select * from instrumentation.subNet;
go
.......................................
{
m_SubNet=’172.20.67.0’;
m_NetMask=’255.255.255.0’;
}
.....
.....
{
m_SubNet=’172.20.70.0’;
m_NetMask=’255.255.254.0’;
}
{
m_SubNet=’172.20.95.0’;
m_NetMask=’255.255.255.0’;
}
( 81 record(s) : Transaction complete )
Sample: Identifying discovered VLANs
The following example query returns details of the discovered VLAN IDs.
Chapter 3. Monitoring network discoveries
239
select * from instrumentation.vlan;
go
.......................................
{
m_Vlan=23;
}
{
m_Vlan=65;
}
.....
.....
{
m_Vlan=677;
}
( 4826 record(s) : Transaction complete )
Sample complex discovery queries
You can use queries similar to these examples to identify devices that meet certain
criteria, for example, devices that have been found by particular discovery agents.
Identifying devices that have been sent to a specific agent
The following example query identifies devices that have been sent to the
IpRoutingTable agent.
select m_Name, m_ObjectId, m_Description
from IpRoutingTable.despatch;
go
.................................
{
m_Name=’10.10.63.193’;
m_ObjectId=’1.3.6.1.4.1.9.1.108’;
m_Description=’Cisco Internetwork Operating System Software
IOS (tm) 7200 Software (C7200-JS-M), Version 12.0(4)T, RELEASE SOFTWARE (fc1)
Copyright (c) 1986-1999 by Cisco Systems, Inc.
Compiled Thu 29-Apr-99 06:27 by kpma’;
}
.....
.....
{
m_Name=’10.10.71.248’;
m_ObjectId=’1.3.6.1.4.1.9.1.258’;
m_Description=’Cisco Internetwork Operating System Software
IOS (tm) MSFC Software (C6MSFC-IS-M), Version 12.0(7)XE1, EARLY DEPLOYMENT
RELEASE SOFTWARE (fc1)
TAC:Home:SW:IOS:Specials b-ayo k-az-eem for info
Copyright (c) 1986-2000 by Cisco Systems, Inc.
Compiled Fri 04-Feb-00 00:’;
}
Identifying devices that have been returned by a specific agent
The following example query identifies devices returned by the IpRoutingTable
discovery agent.
select m_Name from IpRoutingTable.returns;
go
.................................
{
m_Name=’10.10.71.248’;
}
.....
.....
{
m_Name=’10.10.71.248’;
240
IBM Tivoli Network Manager IP Edition: Discovery Guide
}
{
m_Name=’10.10.71.248’;
}
Identifying additional devices that have been discovered by a specific
agent
An agent can discover additional devices by interrogating a device. In this
situation, the additional device would be in the returns table of that agent, but not
the despatch table. You can identify which devices are present in the
IpRoutingTable.returns table, but not in the IpRoutingTable.despatch table, by
performing a join between the IpRoutingTable.despatch and
IpRoutingTable.returns tables, as in the following example.
select IpRoutingTable.returns.m_Name from
IpRoutingTable.returns, IpRoutingTable.despatch
where
IpRoutingTable.returns.m_Name <>
IpRoutingTable.despatch.m_Name;
go
..........................................
{
m_Name=’10.10.71.237’;
}
.....
.....
{
m_Name=’10.10.71.55’;
}
{
m_Name=’10.10.71.51’;
}
Identifying the devices that an agent has enqueued
The following example returns those devices in the despatch table that have not
yet been returned.
select * from <agent>.despatch
where
(
m_UniqueAddress NOT IN
(( select m_UniqueAddress from <agent>.returns where m_LastRecord = 1 ))
);
Sample queries for locating a specific device
To see whether a specific device has been discovered, you can use queries similar
to these examples to search through the discovery data flow.
Sample: Identifying whether a device is present in the workingEntities
database
The following example query determines if the device is present in the
workingEntities database.
select * from workingEntities.finalEntity
where m_UniqueAddress =’10.10.63.239’;
go
.
( 0 record(s) : Transaction complete )
Chapter 3. Monitoring network discoveries
241
Sample: Identifying whether a device has been returned from the
AssocAddress agent
If the device is not present in the workingEntities database, you can use the
following example query to determine if the device has been returned from the
AssocAddress agent.
select * from AssocAddress.returns
where m_UniqueAddress = ’10.10.63.239’;
go
.
( 0 record(s) : Transaction complete )
Sample: Identifying whether a device has been returned from the
Details agent
If the device has not been returned from the AssocAddress agent, you can use the
following example query to determine if the device has been returned from the
Details agent.
select * from Details.returns
where m_UniqueAddress = ’10.10.63.239’;
go
.
( 0 record(s) : Transaction complete )
Sample: Identify whether a device has been sent to the Details agent
If the device has not been returned from the Details agent, you can check if the
device has been sent to the Details agent by querying the Details.despatch table,
as shown below. This result indicates that the device has been sent to the Details
agent, but has not yet been processed.
select * from Details.despatch
where m_UniqueAddress=’10.10.63.239’;
go
.
{
m_UniqueAddress=’10.10.63.239’;
}
( 1 record(s) : Transaction complete )
Sample: Identifying whether a device has been discovered by the
finders
If the device is not in the Details.despatch table, you can query the finders
database, as shown below. This result shows that the device has been discovered
by the finders.
select * from finders.processing
where m_UniqueAddress=’10.10.63.239’;
go
.
{
m_UniqueAddress=’10.10.63.239’;
}
( 1 record(s) : Transaction complete )
select * from finders.returns
where m_UniqueAddress=’10.10.63.239’;
go
.
( 0 record(s) : Transaction complete )
242
IBM Tivoli Network Manager IP Edition: Discovery Guide
Sample collector discovery queries
You can use queries similar to these examples to monitor devices discovered using
the collectors.
Sample: Determining the directionality of connections between layer 1
devices discovered by collectors
The following example shows how to check that the collector has retrieved
directionality of connections between devices. Allowed values for connection
directionality are as follows:
v 0 for bidirectional (two-way link)
v 1 for unidirectional (one-way link)
select * from CollectorLayer1.returns;
go
....
{
m_UniqueAddress=’10.1.1.18’;
m_Name=’OpticalNE1’;
m_ManagerId=’localhost:8081_1’;
m_HaveAccess=1;
m_Protocol=1;
m_UpdAgent=’CollectorLayer1’;
m_LocalNbr={
m_InterfaceId=’STS 1’;
m_LocalNbrName=’OpticalNE1’;
};
m_RemoteNbr={
m_RemoteNbrName=’OpticalNE2’;
m_InterfaceId=’PTP 1’;
m_Unidirectional=1;
};
}
{
m_UniqueAddress=’10.1.1.20’;
m_Name=’OpticalNE3’;
m_ManagerId=’localhost:8081_1’;
m_HaveAccess=1;
m_Protocol=1;
m_UpdAgent=’CollectorLayer1’;
m_LocalNbr={
m_InterfaceId=’STS 2’;
m_LocalNbrName=’OpticalNE3’;
};
m_RemoteNbr={
m_RemoteNbrName=’OpticalNE1’;
m_Unidirectional=1;
};
}
This result fragment shows two devices.
Device 10.1.1.18
This device has a local neighbour named OpticalNE1 and a remote
neighbour named OpticalNE2.
Device 10.1.1.18 has a unidirectional link to its remote neighbour
OpticalNE2; that is, a one-way link in the direction 10.1.1.18 –>
OpticalNE2.
Device 10.1.1.20
This device has a local neighbour named OpticalNE3 and a remote
neighbour named OpticalNE1.
Chapter 3. Monitoring network discoveries
243
Device 10.1.1.20 has a unidirectional link to its remote neighbour
OpticalNE1; that is, a one-way link in the direction 10.1.1.20 –>
OpticalNE1.
244
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 4. Classifying network devices
On completion of discovery, Network Manager automatically classifies all
discovered network devices based on a predefined device class hierarchy. You can
change the way network devices are classified.
Changing the device class hierarchy
Change the device class hierarchy to change the way network devices are
classified. A common situation that requires a change to the class hierarchy is
when the discovery process identifies an unclassified device, that is, a device that
is not defined in the class hierarchy.
Following a discovery, you can check whether any devices are unclassified by
running the following reports:
v Devices with Unclassified SNMP Object IDs report
v Devices with Unknown SNMP Object IDs report
Listing the existing device classes
Before you edit AOC definitions and reinstantiate the topology, list the device
classes that are currently in use.
You list existing device classes by querying the ncp_model databases. The query
returns the names of the classes to which devices in the current topology have
been instantiated. Substitute your domain name and username where NCOMS and
admin are specified.
1. Log into the OQL Service Provider using the following command:
ncp_oql -domain NCOMS -username admin -service ncim You can also issue this
query using the Management Database Access page.
2. Specify the relevant password when prompted.
3. Type the following query:
select * from entityClass;
go
The following table shows an example of the output of this query:
Table 31. Query results
Class identifier
Class name
1
Core
2
EndNode
1815493792
Super class identifier Class type
Manager name
Core
PrecisionIP
1
EndNode
PrecisionIP
Brother
2
PhysicalHost
PrecisionIP
1899974822
BrotherPrinter
1815493792
Printer
PrecisionIP
1367768986
HPOfficePro85xx
2
Printer
PrecisionIP
200
PhysicalHost
2
EndNode
PrecisionIP
200
Router
PrecisionIP
®
163
AIX
3
HPPrinter
200
EndNode
PrecisionIP
202
HypervisorHost
200
HypervisorHost
PrecisionIP
© Copyright IBM Corp. 2006, 2017
245
Table 31. Query results (continued)
Class identifier
Class name
Super class identifier Class type
Manager name
209
PowerHyperHost
202
HypervisorHost
PrecisionIP
210
VMWareHyperHost
202
HypervisorHost
PrecisionIP
4
Linux
200
EndNode
PrecisionIP
117
NoSNMPAccess
200
EndNode
PrecisionIP
211
PowerVMControl
200
EndNode
PrecisionIP
129
Sun
200
EndNode
PrecisionIP
134
Windows
200
EndNode
PrecisionIP
161
zOS
200
EndNode
PrecisionIP
201
VirtualHost
2
VirtualMachine
PrecisionIP
207
VirtualAIXHost
201
VirtualMachine
PrecisionIP
206
VirtualLinuxHost
201
VirtualMachine
PrecisionIP
205
VirtualSolarisHost
201
VirtualMachine
PrecisionIP
204
VirtualWindowsHost
201
VirtualMachine
PrecisionIP
138
InferredDevice
1
NetworkDevice
PrecisionIP
85
InferredCE
138
Router
PrecisionIP
86
InferredHub
138
Switch
PrecisionIP
Creating and editing AOC files
Create and edit AOC files to classify unclassified devices or to change the class
hierarchy of your topology.
If the discovery process identified an unclassified device, you can classify the
device by creating a new AOC file that is specific to the device class to which this
device belongs.
You can edit AOCs in either of two ways: update the ncp_class databases, or
modify the AOC file definitions:
v If you want to edit the current AOC definitions by updating the ncp_class
database directly, then use the Management Database Access or the OQL Service
Provider.
v If you want to modify the AOC file definitions, then complete the following
steps.
1. Go to the NCHOME/precision/aoc directory.
2. Back up any files that you want to edit.
3. Create a text file or edit an existing AOC file by using a text editor.
Restriction: Only alphanumeric characters and the underscore (_) character
may be used for AOC filenames. Any other characters, for example the hyphen
(-) are forbidden.
4. If you created a new AOC file, add an insert to the class.classIds database
table in the ClassSchema.cfg configuration file.
5. Edit the startup options for the ncp_class process and set the -read_aocs_from
option to ensure that the new or changed AOC files are read.
6. Restart the ncp_class process after you change the AOC files. After ncp_class
is restarted and running, restart the ncp_model process.
246
IBM Tivoli Network Manager IP Edition: Discovery Guide
7. Ensure that a domain-specific version of any new AOC files is present in the
NCHOME/precision/aoc directory.
8. Back up and remove the class cache files in the NCHOME/var/precision directory.
For example, remove the following cache files:
Class.Cache.class.activeClasses.NCOMS
Class.Cache.class.staticClasses.NCOMS
9. Run a full discovery and check that the results match the changes you made.
Related reference:
“AOC specific to device class” on page 251
Use this sample AOC file to understand how Network Manager assigns discovered
devices to the device class at a lower level in the class hierarchy.
Applying AOC changes to the topology and to the reports
After you have updated the AOC definitions and passed the changes to ncp_class,
you can apply the changes to the topology by waiting for the next discovery to
complete or by restarting the discovery at the point when the topology is passed
from ncp_disco to ncp_model.
When the next full discovery completes, the AOC changes that you made are
automatically applied to the network topology.
If you do not want to wait for the next full discovery, use the appropriate stitcher
to restart the discovery at the required point. To re-instantiate the containment
model, you must start the stitcher that sends the topology from ncp_disco to
ncp_model.
1. Log into the OQL Service Provider or access the Management Database Access.
2. Issue the following query to the disco.status table to confirm that the ncp_disco
process is in rediscovery mode: select * from disco.status;
Here is a sample response.
m_DiscoveryMode=1;
m_Phase=1;
m_BlackoutState=0;
m_CycleCount=0;
m_ProcessingNeeded=0;
m_FullDiscovery=0;
From the results returned by the query, you can see that ncp_disco is currently
in the rediscovery mode, that is, m_DiscoveryMode=1.
3. Start the SendTopologyToModel stitcher. The SendTopologyToModel sends the
topology from ncp_disco to ncp_model.
a. Ensure that you are in the OQL Service Provider or the Management
Database Access.
b. To insert the stitcher into the stitchers.actions table, issue the following
command:
insert into stitchers.actions
( m_Name )
values
( ’SendTopologyToModel’ );
After your OQL insert is accepted, the stitcher is invoked and the network
topology is sent to ncp_model. When the topology is sent, it is instantiated in
accordance with the modified AOC hierarchy.
Chapter 4. Classifying network devices
247
4. In order to ensure that the newly classified devices are removed from the
Devices with Unclassified SNMP Object IDs report and the Devices with
Unknown SNMP Object IDs report, perform the following steps:
a. Clarify exactly which new sysObjectId values are being mapped by the new
or edited AOC files. For example, the original AOC files mapped the
following sysObjectId values:
v 1.2.3.4
v 1.5.6.*
Then two new sysObjectId values are added to the system: 1.9.8 and 1.5.6.7.
In the AOC file, the sysObjectId value 1.5.6.7 is covered by the mapping
1.5.6.*. However, the AOC file must be updated to add the sysObjectId
value 1.9.8.
b. Clarify which AOC files are mapped by the NCIM topology database
mappings table. The mappings table is used by the Devices with
Unclassified SNMP Object IDs report and the Devices with Unknown
SNMP Object IDs report to determine which data to show in the reports.
This table is not automatically updated when you edit AOC files and restart
the Topology manager, ncp_class, and consequently these reports continue
to show the new sysObjectId values as unclassified and unknown. The
mappings in the mappings table are also more specific than the mappings
in the AOC files. For example, the NCIM topology database mappings table
might contain the following data:
Table 32.
mappingGroup
mappingKey
mappingValue
Description
sysObjectId
1.2.3.4
Device Type A
Description of Device
Type A
sysObjectId
1.5.6.1
Device Type B
Description of Device
Type B
sysObjectId
1.5.6.2
Device Type C
Description of Device
Type C
In the AOC file, only the sysObjectId value 1.9.8 needed to be added
because the generic mapping 1.5.6.* covered the new sysObjectId value
1.5.6.7. However, in the NCIM topology database mappings table both
sysObjectId values 1.9.8 and 1.5.6.7 must be added.
c. From the command line, update the NCIM topology database mappings
table with relevant records for the new sysObjectId values. For example, to
add records for the two new sysObjectId values 1.9.8 and 1.5.6.7, issue the
following SQL insert statements:
insert into mappings (mappingGroup, mappingKey, mappingValue) values
(’sysObjectId’, ’1.9.8’, ’device_type’);
insert into mappings (mappingGroup, mappingKey, mappingValue) values
(’sysObjectId’, ’1.5.6.7’, ’device_type’);
Where device_type is the device type to which the sysObjectId value must be
mapped. For information on the NCIM topology database mappings table,
see the IBM Tivoli Network Manager IP Edition Topology Database Reference.
After the AOC changes have been applied to the topology, either automatically by
waiting for the next discovery, or manually by performing the steps in this topic,
you will notice the following changes are applied to network polling and
visualization.
v When you define a new polling policy, the new classes you defined are
displayed in the Classes tab in the Poll Policy Editor.
248
IBM Tivoli Network Manager IP Edition: Discovery Guide
v When you visualize the network using network views, the network view tree
now displays the classes defined in the modified class hierarchy.
v If you updated the NCIM topology database mappings table as described then
the Devices with Unclassified SNMP Object IDs report and the Devices with
Unknown SNMP Object IDs report no longer return any devices.
AOC file samples
Use the AOC file samples to understand how Network Manager assigns
discovered devices to the device classes in the class hierarchy.
EndNode class
Use this sample EndNode class AOC file to understand how Network Manager
assigns discovered devices to the EndNode class.
Sample
The following sample AOC file fragment assigns devices to the EndNode class
using the filter defined in the instantiate_rule clause.
//*************************************************************
//
// File : EndNode.aoc
//
//*************************************************************
active object ’EndNode’
{
super_class = ’Core’;
instantiate_rule = "EntityOID like ’1 \.3\.6\.1\.4\.1\.2021\.’ OR
EntityOID = ’1.3.6.1.4.1.2021’ OR
EntityOID = ’1.3.6.1.4.1.1575’ OR
EntityOID like ’1 \.3\.6\.1\.4\.1\.11\.2\.3\.9\.’ OR
EntityOID = ’1.3.6.1.4.1.11.2.3.9’ OR
(EntityType = 1 AND EntityOID IS NULL)
OR
...
OR
(
EntityOID = ’1.3.6.1.4.1.1977’
)
OR
(
EntityOID like ’1\.3\.6\.1\.4\.1\.2136\.’
)
OR
...
For the EndNode class the instantiate_rule is very long. It consists of multiple lines
comparing the EntityOID, (this is the sysObjectID of the device), to various values,
joined together by an OR operator. There are different versions of the OR
comparison:
EntityOID = '1.3.6.1.4.1.2021'
This filter is looking for an exact match of the EntityOID to the value
1.3.6.1.4.1.2021. If the match is not exact, then the comparison fails and the
device is not assigned to the EndNode class.
EntityOID like '1\.3\.6\.1\.4\.1\.11\.2\.3\.9\.'
This filter is looking for a match like the value 1\.3\.6\.1\.4\.1\.11\.2\.3\
.9\. The \. is required to make sure that the . (period) is matched. Also,
Chapter 4. Classifying network devices
249
notice that the value ends in \. This allows matching OIDs that start with
the specified value but have additional values following the last . (period)
specified.
NetworkDevice class
Use this sample NetworkDevice class AOC file to understand how Network
Manager assigns discovered devices to the NetworkDevice class.
Sample
The following sample AOC file fragment assigns devices to the NetworkDevice
class using the filter defined in the instantiate_rule clause.
//*************************************************************
//
// File : NetworkDevice.aoc
//
//*************************************************************
active object ’NetworkDevice’
{
super_class = ’Core’;
instantiate_rule = ’EntityType = 1 OR // Chassis
EntityType = 2 OR // Interface
EntityType = 3 OR // LogicalInterface
EntityType = 5 OR // Card
EntityType = 6 OR // PSU
EntityType = 8 OR // Module
EntityType = 0’;
...
For the NetworkDevice class, the instantiate_rule tries to match device types. The
following examples are filters that are used in the instantiate_rule.
EntityType = 1
Matches all entities discovered that are chassis devices. Chassis devices
have the field entityType set to a value of 1 in the NCIM topology
database entityData table.
EntityType = 2
Matches all entities discovered that are ports or interfaces. Ports and
interfaces have the field entityType set to a value of 2 in the NCIM
topology database entityData table.
EntityType = 3
Matches all entities discovered that are logical interfaces. Logical interfaces
have the field entityType set to a value of 3 in the NCIM topology
database entityData table.
EntityType = 5
Matches all entities discovered that are cards. Cards have the field
entityType set to a value of 5 in the NCIM topology database entityData
table.
EntityType = 6
Matches all entities discovered that are power supply units (PSUs). PSUs
have the field entityType set to a value of 6 in the NCIM topology
database entityData table.
EntityType = 8
Matches all entities discovered that are modules. Modules have the field
entityType set to a value of 8 in the NCIM topology database entityData
table.
250
IBM Tivoli Network Manager IP Edition: Discovery Guide
AOC specific to device class
Use this sample AOC file to understand how Network Manager assigns discovered
devices to the device class at a lower level in the class hierarchy.
Sample
The following sample AOC file fragment assigns devices to the
EWindowsNetHarmoni class using the filter defined in the instantiate_rule clause.
This is an EndNode device.
//*************************************************************
//
// File : EWindowsNetHarmoni.aoc
//
//*************************************************************
active object ’EWindowsNetHarmoni’
{
super_class =’EndNode’;
instantiate_rule = "EntityOID like ’1 \.3\.6\.1\.4\.1\.1977\.1\.6\.1279\.’";
...
For the EWindowsNetHarmoni class, the following parameters are defined in the
AOC file. The instantiate_rule parameter is long. It consists of multiple lines
comparing the EntityOID, (this is the sysObjectID of the device), to various values,
joined together by an OR operator. There are different versions of the OR
comparison:
super_class ='EndNode'
This parameter establishes the device as belonging to the EndNode class.
The EWindowsNetHarmoni class inherits all the attributes of the EndNode
class.
instantiate_rule = "EntityOID like '1 \.3\.6\.1\.4\.1\.1977\.1\.6\.1279\.'"
This filter is looking for a match to the value 1\.3\.6\.1\.4\.1\.11\.2\.3\
.9\. The \. is required to make sure that the . (period) is matched. Also,
notice that the value ends in \. This allows matching OIDs that start with
the specified value but have additional values following the last . (period)
specified.
Chapter 4. Classifying network devices
251
252
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 5. Keeping discovered topology up-to-date
After a discovery has completed, you can keep the discovered topology updated
by scheduling a discovery, manually discovering devices, and removing devices.
Scheduling discoveries
After a full discovery completes, you can schedule further discoveries by inserting
the time, date, and day for discoveries to run in the FullDiscovery.stch stitcher
file.
1. Back up the NCHOME/precision/disco/stitchers/FullDiscovery.stch file.
2. Create separate instances of the FullDiscovery.stch file for each domain in the
network. To create a domain-specific instance, insert .domain into the file name.
For example, FullDiscovery.NCOMS.stch. If you do not have separate
FullDiscovery.stch files for each domain, all the domains on the network are
discovered.
3. Schedule the discovery of the first domain. In a FullDiscovery.domain.stch
file, uncomment one of the ActOnTimedTrigger lines. Then, change it to run the
discovery at a certain time. For example, to schedule the discovery for 11:00 PM
every day, change the line as follows:
ActOnTimedTrigger(( m_TimeOfDay ) values ( 2300 ) ; );
4. Repeat the steps in the FullDiscovery.stch file for each domain on the
network.
Examples
v To schedule a discovery on the sixth day of the week since Sunday (that is, on
Saturdays) at 11 PM:
ActOnTimedTrigger(( m_DayOfWeek , m_TimeOfDay )
values ( 6 , 2300 ) ; ) ;
Sunday = 0, Monday = 1, Tuesday = 2, Wednesday = 3, Thursday = 4, Friday =
5, Saturday = 6.
v To schedule a discovery on the 13th day of each month at 2 PM:
ActOnTimedTrigger(( m_DayOfMonth , m_TimeOfDay )
values ( 13 , 1400 ) ; );
v To schedule a discovery at intervals of 13 hours:
ActOnTimedTrigger(( m_Interval ) values ( 13 ) ; );
Related concepts:
“About types of discovery” on page 1
Different terms are used to describe network discovery, depending on what is
being discovered and how the discovery has been configured. You can run
discoveries, rediscoveries, and full and partial discoveries.
© Copyright IBM Corp. 2006, 2017
253
Viewing discovery status for a device
From the topology GUIs you can view information about a device, including when
it was first discovered, last discovered, and last rebooted.
To perform this procedure, you must be in the Network Views or in the Network
Hop View, and the topology map must be displaying the device of interest.
1. In the topology map, right select one or more devices.
2. Select Discovery... > Show Discovery Overview.
3. The Discovery Overview window displays the following information:
Access IP
IP address through which this entity was discovered and through
which it is monitored.
Class Name
Class of devices to which this device belongs.
Current
Current date and time.
Entity Name
IP address, DNS name, or sysName for this device. For example, an IP
address such as 172.20.1.7, or a DNS name, such as company-abc.net.
Entity Created
Date and time when the entity was first uploaded to the NCIM
topology database.
Interface Filtered
A flag to show whether the device has had interface filtering applied to
it or not. If you do not see all the information for the device that you
expect, the information might have been filtered out. You can do an
SNMP walk of the device using the MIB Browser with the option to
ignore filtering.
Last Discovered
Date and time when the Details agent last accessed the device.
Last Modified
Date and time when the last detected change on the device was
reflected in the NCIM topology database. For example, if an interface
name on the device changes, this is the time at which that change was
uploaded to NCIM.
Last Reboot
Date and time when the device was last rebooted. This is calculated
based on the sysUpTime MIB value retrieved from the device, so Last
Reboot is only available if the sysUpTime was retrieved. For example,
for devices with no SNMP access, the value of Last Reboot is NULL.
254
IBM Tivoli Network Manager IP Edition: Discovery Guide
Manually discovering a device or subnet
You can manually discover devices so that the network topology in Network
Manager matches the network.
Sometimes you might know that one or more devices have had their configuration
changed, and want to discover them again regardless of whether the system has
detected the change from traps sent by the devices.
You can manually discover a device or subnet in the following ways:
v You can use the Discovery Configuration GUI to specify individual devices or
complete subnets to be discovered.
v You can discover specific devices or sets of devices from the Hop View or
Network Views.
v You can make inserts to the finders.rediscovery table using ncp_oql, specifying
the IP address or subnet to be discovered.
Note: Do not use manual discoveries to remove devices from the topology. Devices
that are no longer accessible remain in the topology until their LingerTime reaches
zero and another discovery is run, or until you remove them using the
RemoveNode.pl script. Do manual discoveries only against devices that are
operational but whose configuration has been changed.
Related tasks:
“Removing a device from the network” on page 260
You can manually remove a device that is known to be scheduled for permanent
removal from the network.
“Monitoring network discovery from the GUI” on page 227
From the Active Discovery Status page, you can monitor the status and progress of
the current full or partial discovery, investigate the work of the discovery agents,
and view details of the last full discovery.
Manually discovering a device or subnet using the GUI
You can configure and launch discovery of a device or subnet from the Discovery
Configuration GUI. You can customize the discovery configuration to make partial
discovery run as quickly as possible.
Enabling partial discovery agents
You can configure partial discovery by enabling the appropriate agents from the
Partial Discovery Agents tab in the Discovery Configuration GUI.
You can speed up the time taken for a partial discovery by selecting only those
agents essential to discover new or modified devices.
Related reference:
“Guidance for selecting agents” on page 481
To discover device technologies (that is, those that use protocols other than IP) on
your network, you must ensure that the appropriate agents are active.
Chapter 5. Keeping discovered topology up-to-date
255
Configuring advanced partial discovery settings
Among the advanced partial discovery settings that you can configure are
feedback, rebuilding of layer, and remote neighbor parameters.
Configuring feedback settings:
You can specify feedback settings when configuring a partial discovery with the
GUI.
Feedback is the mechanism by which data returned by agents is used to find other
devices. Examples of feedback data include the IP address of remote neighbors, or
the subnet within which a local neighbor exists.
The feedback mechanism allows any new IP addresses to be fed back into the
discovery and thus increases the size of the discovered network. You need to
balance completeness of the discovered topology (feedback on) with greater speed
of discovery (feedback off).
You can choose from the following options after selecting the Advanced tab within
the Configuration option in the Discovery Configuration GUI:
v No Feedback: Feedback is off for all discoveries. This option provides speed but
discovers only those devices specified to the finders, and hence provides an
incomplete topology. However, this setting ensures that discoveries complete in
the quickest possible time.
v Feedback: Feedback is on for full discoveries and partial discoveries. This option
provides a complete topology in all situations but takes the longest time.
v Feedback Only on Full: Feedback is on for full discoveries, ensuring a complete
topology. For partial discoveries there is no feedback. This ensures that the
partial discovery runs in the quickest time possible. This is the default setting.
Configuring rebuilding of layer settings:
You can allow the rebuilding of the topology layers to display an accurate
topology when you configure a partial discovery.
To rebuild the topology layers following a partial discovery, select the Enable
Rediscovery Rebuild Layers setting on the Advanced tab within the Configuration
option in the Discovery Configuration GUI. If you specify that topology layers
should be rebuilt following partial discovery, the result is an accurate topology
showing all connectivity. However, the process of adding new devices takes longer.
Related concepts:
“Option to rebuild topology layers” on page 445
You can specify whether to rebuild the topology layers following a partial
rediscovery. Using this option, you can increase the speed of partial rediscovery.
256
IBM Tivoli Network Manager IP Edition: Discovery Guide
Enabling discovery of remote neighbors for partial discovery:
You can improve the accuracy of connections found during a partial discovery by
enabling the discovery of remote neighbors.
By default, remote neighbor discovery is off. Enabling remote neighbor discovery
makes the discovery take longer.
With remote neighbour discovery on, Network Manager checks, during a partial
discovery, whether any connections to remote neighbors have changed. (Remote
neighbors in this context are connected devices that were in scope of the last full
discovery but are out of scope of the current partial discovery.)
If the connections have changed, the connected devices are included in the partial
discovery, resulting in a more accurate topology.
Restriction: If a connection between devices has changed, but the information
about the connection is stored only on the device that is out of scope, then the
change is not registered and the connected devices are not included in the partial
discovery. Enabling remote neighbor discovery increases the accuracy of the
topology, if it has changed, but does not ensure that all changes are discovered. For
the most accurate topology, run a full discovery.
To enable remote neighbor discovery, select Enable Rediscovery of Related
Devices on the Advanced tab within the Configuration option in the Discovery
Configuration GUI.
Starting partial discovery from the GUI
Starting a partial discovery involves defining a seed and scopes.
If a full discovery has not been run since the last time that the discovery engine,
ncp_disco, was started, you cannot start a partial discovery.
You can start a partial discovery of a device or subnet from the Active Discovery
Status window. You can also discover specific devices by right-clicking them from
within the Hop View and Network Views.
To start a partial discovery from the Active Discovery Status window, complete the
following tasks.
1. Select the domain in which you want to run a discovery from the Domain
menu. You can start to type the name of the domain, and matching domains
are listed below the Domain field.
2. Click the downward-facing arrow next to the Start Discovery button
and select Start Partial Discovery from the menu. The Partial Discovery
window is displayed. Specify the IP addresses and subnets that contain the
devices to be discovered
3. Under Partial Discovery, select the required nodes and subnets.
4. To add a new subnet or node, click New.
5. Complete the fields as follows and click OK:
Discover
Select one of the following options:
Identifier
Type the required IP address.
Chapter 5. Keeping discovered topology up-to-date
257
Subnet
Type the required subnet and specify the number of netmask
bits. The Netmask field is automatically updated.
EMS Device Name
Type the name of a device that was discovered through an
Element Management System (EMS). You can type the
nativeID, entity name, sysName, or display name.
Note: When running a partial discovery of an EMS collector
from the Discovery Status GUI, within the New Partial
Discovery Node/Subnet window you must specify the EMS
identifier value in the EMS Device Name field and not in the
Identifier field. The Identifier field only accepts IP addresses.
6. To add new scope zones, click Scope.
Note: If you add a scope zone that is not included within the scope of the last
full discovery, connections between devices in the new scope and the old scope
might not be accurate until the next full discovery. Enabling remote neighbor
discovery can help improve the accuracy of these connections.
7. To add a new discovery scope zone click New
zone, click the required entry in the list.
. To edit an existing scope
8. Complete the fields as follows and click OK:
Scope By:
Select one of the following options:
Subnet
Type the required subnet and specify the number of netmask
bits. The Netmask field is automatically updated.
You can specify a subnet or an individual IP address using
these fields.
v For example, to specify an IPv4 Class C subnet 10.30.2.0, type
10.30.2.0/24, where 10.30.2.0 is the subnet prefix, and 24 is
the subnet mask.
v To specify an individual device, type an IPv4 IP address and
a subnet mask of 32. For example, type 10.30.1.20/32.
v If you are using IPv6, use a subnet mask of 112 or higher, in
order to avoid excessive discovery times.
Wildcard
Use an asterisk (*) as a wildcard.
For example, to specify a scope of all IP addresses that begin
with the 10.30.200. subnet prefix, type 10.30.200.*.
Restriction: Network Manager does not support the IPv4–mapped IPv6
format and expects all IPv6 addresses to be in standard colon-separated
IPv6 format. For example, Network Manager does not support an
IPv4–mapped IPv6 address such as ::ffff:192.0.2.128. Instead enter
this address as ::ffff:c000:280 (standard colon-separated IPv6
format).
Protocol
Select the required Internet protocol: IPv4 or IPv6.
258
IBM Tivoli Network Manager IP Edition: Discovery Guide
Action
Define the subnet range as an inclusion zone or exclusion zone. If the
subnet range is an inclusion zone that you intend to ping during the
discovery, click Add to Ping Seed List. Clicking this option
automatically adds the devices in the scope zone as a discovery seed
devices.
Restriction: The Add to Ping Seed List option is not available for IPv6
scope zones. This prevents ping sweeping of IPv6 subnets, which can
potentially contain billions of devices to be pinged. Ping sweeping of
IPv6 subnets can therefore result in a non-terminating discovery.
9. Click OK then click Go. When a partial discovery is running, the Start
Discovery button is toggled off
Related concepts:
.
“About types of discovery” on page 1
Different terms are used to describe network discovery, depending on what is
being discovered and how the discovery has been configured. You can run
discoveries, rediscoveries, and full and partial discoveries.
Related tasks:
“Starting a discovery” on page 52
After you configure a discovery, you can start and, if necessary, stop the discovery.
“Monitoring network discovery from the GUI” on page 227
From the Active Discovery Status page, you can monitor the status and progress of
the current full or partial discovery, investigate the work of the discovery agents,
and view details of the last full discovery.
Manually discovering a device or subnet from the command
line
You can manually discover a device or subnet from the command line.
To manually discover a device or subnet from the command line, make inserts to
the finders.rediscovery table using ncp_oql, specifying the IP address or subnet
to be discovered, as described in the following example.
Manual discovery
To manually discover the device with IP address 192.168.1.2, first start the OQL
Service Provider using the following command:
ncp_oql -domain NCOMS -service Disco
Having logged into the OQL provider, run the following query (note that the
command is entered on one line):
insert into finders.rediscovery (m_Address, m_RequestType) values
("192.168.1.2", 1);
When discovery of a device is forced like this, ncp_disco immediately passes it to
the Ping finder to confirm it exists, and, if it does, triggers the appropriate agents
to reanalyze it. If the connections from the device have changed, neighboring
devices might also be discovered.
Chapter 5. Keeping discovered topology up-to-date
259
Removing a device from the network
You can manually remove a device that is known to be scheduled for permanent
removal from the network.
1. Remove the device from the topology database using the RemoveNode.pl script.
2. Physically remove the device from the network.
Related tasks:
“Manually discovering a device or subnet” on page 255
You can manually discover devices so that the network topology in Network
Manager matches the network.
Setting the linger time for a device
The value of the LingerTime field indicates how many discoveries a device can fail
to be found in before it is assumed to have been removed from the network and
its record is removed from the topology. Setting the LingerTime field to zero
ensures that when the device is not found in the next discovery, its record is
immediately removed from the topology.
Setting the LingerTime in the ncimCache.lingerTime table sets the LingerTime for
only the chassis. Contained entities such as interfaces and cards are removed from
the topology when a discovered device has different containment data showing
that the contained entity is no longer present. LingerTime can be overridden for
specific devices or contained entities by editing the discovery stitchers.
To set the LingerTime field for a device to zero, complete the following steps:
1. Enter a command similar to the following to start the OQL Service Provider:
ncp_oql -domain NCOMS -service Model
2. Update the LingerTime field in the ncimCache.lingerTime table for all entities
that represent the device. For example, if the device is called
core-router.abcd.com, enter the following command, on one line:
update ncimCache.lingerTime set lingerTime->LINGERTIME = 0
where ENTITYNAME = ’core-router.abcd.com’;
260
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 6. Troubleshooting discovery
You can troubleshoot discovery by monitoring discovery events and by running
discovery reports. You can also configure your own discovery events.
Troubleshooting discovery with reports
The troubleshooting reports provide easy visibility into the discovery results to
help with verification and troubleshooting of both the discovery results and the
network itself.
Network Manager uses the Tivoli® Common Reporting component to generate
reports. More information on Tivoli Common Reporting is located at
v Tivoli Common Reporting Information Center
v developerWorks® Tivoli Common Reporting
To access the reports in the Network Manager GUI, complete the following steps.
Click the Reporting icon and select Common Reporting. Within the widget, select
Network Manager. A list of folders display. These folders contain all Cognos
reports for your access.
You can use reports for verifying and troubleshooting discovery results such as the
examples in Table 33.
For more information on the Network Manager reports, refer to the IBM Tivoli
Network Manager IP Edition Administration Guide.
Table 33. Report categories to use for discovery troubleshooting
Troubleshooting
task
Consult this report
category and report
Identifying all
discovered nodes
and interfaces
Utility reports: Discovered
nodes and interfaces flat
file list
Resolving
mismatches
Troubleshooting reports:
This report provides a list of
Connected Interface Duplex connections that have mismatches
Mismatch
between half- and full-duplex devices,
where one end of the connection is
half-duplex and the other end is
full-duplex. This mismatch is one of the
key configuration problems that
network managers have to find to
resolve performance or availability
issues.
Resolving
Troubleshooting reports:
inaccessible devices Devices with no SNMP
Access
© Copyright IBM Corp. 2006, 2017
Benefit of the report
This report lists all nodes and interfaces
that were discovered. It also marks
interfaces or ports connected to network
devices. It allows you to check that
specific devices and interfaces were
actually discovered.
This report identifies the devices that do
not have SNMP access. You can then
identify the reason for the SNMP access
failure.
261
Table 33. Report categories to use for discovery troubleshooting (continued)
Troubleshooting
task
Consult this report
category and report
Resolving
unconnected
devices
Troubleshooting reports:
Devices With No
Connections
Benefit of the report
This report lists unconnected devices as
a first step in determining why the
discovery found no network
connections for a device.
Troubleshooting reports:
Devices with Unclassified
SNMP Object IDs
Asset reports:
Resolving
v Interface Availability
unclassified devices
v Summary By Device
Class
Using these reports, you can create
leaf-node AOC files for the new device
class.
v Vendor and Device
Availability
Resolving devices
with unregistered
SNMP object IDs
Troubleshooting reports:
Devices with Unknown
SNMP Object IDs
Using the information in this report,
you can modify the AOC files
associated with the unregistered
devices.
Identifying devices
pending deletion
Troubleshooting reports:
Devices Pending Delete on
Next Discovery
This report displays information on
devices to be deleted from the topology
if they are not found during the next
discovery cycle. The report allows you
to check that removal of devices from
the topology is progressing, and to
identify devices erroneously scheduled
for removal.
Monitoring discovery status
You can view discovery status messages to understand the status and progress of
the discovery. You can also configure your own discovery events.
Process flow for creating discovery events
Discovery events are created during the discovery process showing the progress of
agents, stitchers, and finders. These events are sent to and stored in Tivoli
Netcool/OMNIbus and can be viewed using the Web GUI.
Discovery events are created in the following stages:
v During the data collection phase of discovery, dedicated stitchers (AgentStatus
and FinderStatus) detect whether finders and agents have started or stopped.
v During the data processing phase, a dedicated stitcher (CreateStchTimeEvent)
detects key events; for example, discovery has started building the working
entities table, or the containment table.
v Whenever one of the above stitchers detects an event, it writes that event to the
disco.events table.
v The DiscoEventProcessing stitcher responds to an insert into the disco.events
table and creates and sends the appropriate event to the probe for Tivoli
Netcool/OMNIbus, nco_p_ncpmonitor, which then forwards the event to the
ObjectServer.
262
IBM Tivoli Network Manager IP Edition: Discovery Guide
v You can switch the generation of discovery events on or off by setting the value
of the m_CreateStchrEvents field in the disco.config table.
You can configure your own discovery events by writing a stitcher to detect the
desired event and write that event data to the disco.events table.
Related reference:
“disco.events table” on page 305
The events table constrains discovery events generated to a standard format. An
event is generated by inserting a record into this table.
“Main discovery stitchers” on page 487
This topic lists the main discovery stitchers.
Monitoring discovery status messages
You can view discovery status messages to understand the status and progress of
the discovery.
The discovery processes, including agents, stitchers, and finders, send messages to
IBM Tivoli Netcool/OMNIbus when they start and stop. You can view these
messages to see if the discovery processes are running as expected, and to gauge
the overall progress of discovery.
To view discovery process status messages, complete the following tasks.
1. Click the Incident icon and select Events > Event Viewer.
2. Apply a filter to the Event Viewer so that only events with an Agent of
ncp_disco are displayed.
3. Optional: Refine the filter or sort on EventId to view only specific kinds of
discovery events.
4. Ensure that the LocalPriObj and LocalSecObj columns are displayed in the
Event Viewer. These columns contain information for discovery events. (Not all
columns are used by all events.)
Related tasks:
IBM Tivoli Netcool/OMNIbus Welcome page
Create or edit filters using the Filter Builder to customize the events displayed in
the Event Viewer. For more information on filters, search the Tivoli
Netcool/OMNIbus documentation.
NCIM entity ID retrieval failure
If a discovery event appears in the Event Viewer with the description "The
retrieval of an entity ID from NCIM for a certain entity failed", then the NCIM
database might be down. This will cause a mismatch between the entity IDs in
NCIM and in the embedded discovery database DNCIM; that is, NCIM and
DNCIM will have a different set of entity IDs for the same network entities.
If the NCIM database is down for any reason while the RetrieveNCIMEntityId
stitcher is running, then there will be a mismatch between the entity IDs in NCIM
and DNCIM. It is not essential for the entity IDs in DNCIM and NCIM to match;
however, in the event of discovery fault resolution, it is helpful if the entity IDs are
consistent across the databases.
If there is a mismatch between the entity IDs inNCIM and DNCIM then you can
make sure that the databases are aligned for the next discovery by doing one of
the following:
Chapter 6. Troubleshooting discovery
263
v Refresh the DNCIM database prior to the next discovery
v Log into your running discovery DNCIM database and delete all the records in
entityNameCache for your domain
Note: If your NCIM topology database is shared between multiple domains then
the chance of the DNCIM and NCIM entity IDs becoming mismatched is much
higher.
Refresh the DNCIM database prior to the next discovery
Refresh the DNCIM database only if the Discovery engine, ncp_disco, is not
running.
Refresh the DNCIM database by deleting the following directory and everything in
it. The DNCIM database stores all the database files in this directory:
$NCHOME/precision/embeddedDb/sqlite/processName.domain
Where:
v processName is the name of the Network Manager process that is using DNCIM.
In this case, this is the name of the Discovery engine, ncp_disco.
v domain is the name of the current domain.
For example, if the name of the current domain is NCOMS, then the database files
are located here:
$NCHOME/precision/embeddedDb/sqlite/ncp_disco.NCOMS
Note: This will result in a small delay to the next discovery because the DNCIM
database must be rebuilt.
Log into the DNCIM database and delete all records in
entityNameCache for your domain
Provided that the discovery is in the static state (phase 0) it is safe to alter the
discovery DNCIM database. Proceed as follows:
1. Check that the Discovery engine, ncp_disco, is running and that discovery is in
phase 0 by running the following query. If this query returns the value 0, then
the discovery is in phase 0.
select m_Phase from disco.status
2. Issue the following OQL command to access the DNCIM database:
ncp_oql -domain domain_name -service DNCIM
Where domain_name is the name of the current network domain.
3. Issue the following command to delete all the records in entityNameCache:
DELETE FROM entityNameCache
Note: For a large database, the delete operation can take a long time.
264
IBM Tivoli Network Manager IP Edition: Discovery Guide
Troubleshooting discovery agents
You can use the Discovery Status GUI to troubleshoot discovery problems
associated with discovery agents.
Troubleshooting an unusually long discovery
A discovery might be taking a long time to complete because an agent is unable to
complete processing on a specific device. Use the Agents Status section to
determine which agent is taking a long time to complete and which device it is
working on.
To use the Agents Status section to determine if the cause of the problem is an
agent that is blocked on a device, complete the following steps:
1. Click the Discovery icon and select Network Discovery Status.
2. Within Network Discovery Status, click the Agents Status tab.
3. Set the Phases drop-down list above the upper Agents table to Interrogating
Devices. The upper Agents table now displays only agents that are scheduled
to complete in the first discovery phase, Interrogating Devices.
Note: This problem usually occurs during the first discovery phase,
Interrogating Devices.
4. Ensure that the State column is sorted in descending order. The agents appear
by default in descending order of agent state, as listed in the following table.
Table 34. Agent states
State
Value
Icon
Description
Died
5
The agent has terminated unexpectedly. This is a
potential discovery problem.
Finished
4
The agent is still running but has finished processing of
all the entities in its queue. The agent is still available to
process any further agents placed in the queue.
Running
3
The agent is currently processing entities.
Starting
2
The agent is starting up.
Not
running
1
The Agent is not running.
5. Scroll down the table to find the agents that have the status Running
.
These are the agents that are still processing devices. If the discovery has been
running for an unusually long time, then there might be just one agent that
still has Running status
. This is the blocked agent.
6. Select one of the agents with Running status
. By default, the lower table
now displays all the entities that are still queued for this agent.
7. Click the All radio button above the lower table. The lower table now shows
all entities that have been processed by this agent, that are still being
processed by this agents, or that are in the agent queue.
8. Ensure that the State column is sorted in descending order. The entities
appear by default in descending order of agent state, as listed in the following
table.
Chapter 6. Troubleshooting discovery
265
Table 35. Entity states
State
Value
Icon
Description
Died
5
Processing of the entity terminated unexpectedly. Either
the agent was stopped manually, or there is a discovery
problem.
Finished
4
An agent has completed processing this entity.
Running
3
An agent is currently processing this entity.
Starting
2
An agent is beginning to process this entity.
Not
running
1
This entity is not currently being processed.
9. Scroll down the table to find the entities that have the status Running
.
These entities are still being processed by this agent. If the agent is stuck on a
single device, then there will only be one entity with Running status
.
10. Look at the other information in the table to find out more about this entity.
The Elapsed Time column indicates how long the agent has been processing
this device. The SNMP Access column indicates whether the agent was able to
gain SNMP access to this device. If the agent was unable to gain SNMP access
to the device, there might be a problem with SNMP community string
settings. Further investigation of this device is required.
11. If the device has a large number of interfaces, the discovery might appear to
be stuck on this device because it takes a long time to download all the
information. Configure an interface filter for this device to filter out
information that you are not interested in. When you run discovery again, the
SNMP helper retrieves less information from the device, and this might solve
the problem.
Related tasks:
“Filtering SNMP information from devices” on page 99
You can filter out SNMP information when devices are queried by the SNMP
helper by configuring inserts into the SNMP helper database.
“Configuring SNMP interface filters” on page 101
You can configure one or more interface filters per device type.
“Monitoring discovery agent progress” on page 230
You can use the Agents Status section to monitor the progress of the discovery
agents during a full or partial discovery.
Identifying failed agents
A source of discovery failure can be agents that terminate unexpectedly during
discovery. Use the Agents Status section to determine whether any agents
terminated unexpectedly.
To use the Agents Status section to determine whether any discovery agents are
not running correctly, complete the following steps:
1. Click the Discovery icon and select Network Discovery Status.
2. Within Network Discovery Status, click the Agents Status tab.
3. Ensure that the Phases drop-down list above the upper Agents table is set to
All Phases. The upper Agents table now displays all agents that started so far
in this discovery.
266
IBM Tivoli Network Manager IP Edition: Discovery Guide
4. Click the State column in the upper Agents table so that the agents are ordered
in descending order of State. The agents now appear in the table in
alphabetical order of status.
5. Any agents that terminated unexpectedly are at the top of the table and have
the status Died.
Further investigation is required to determine why this agent terminated
unexpectedly.
Related tasks:
“Monitoring discovery agent progress” on page 230
You can use the Agents Status section to monitor the progress of the discovery
agents during a full or partial discovery.
Troubleshooting missing devices
If a device that you expect to find in your network topology is not present, follow
these steps to troubleshoot the problem.
Before following these steps, run a full discovery with feedback enabled.
To check some common causes for a device not being found in the network maps,
complete the following steps.
1. Verify that the device you are looking for is running and connected to the
network.
2. Search for the device.
a. Search for the device in the network maps by hostname and then by IP
address.
b. If you know which devices it is connected to, try finding one of the
connected devices in the Network Hop View. Then set the number of hops
to 1 and see if the device is shown as connected.
3. Check whether the device is in scope. Review the discovery scope, including
exclusion zones, in the Scope tab of the Network Discovery Configuration GUI.
4. Check if the device is being filtered out of the discovery.
a. Click Filters.
b. Review the prediscovery and postdiscovery filters to ensure that the device
is not being prevented from being discovered or instantiated.
c. Search the ncp_disco.domain.log file for the device name.
If the device has been filtered out by a postdiscovery filter, messages are
present such as:
Filtering entity name and not sending to model
name matches the instantiateFilter
If a device relationship has been filtered out by a postdiscovery filter,
messages are present such as:
Filter relationship involving name
Related tasks:
“Setting discovery filters” on page 37
Use filters to filter out devices either before discovery or after discovery. You can
filter out devices based on a variety of criteria, including location, technology, and
manufacturer. Filters provide additional restrictions to those defined in the scope
zones.
Chapter 6. Troubleshooting discovery
267
“Scoping discovery” on page 27
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
Troubleshooting an idle discovery
If you start the discovery, and after some minutes no devices have been
discovered, follow these troubleshooting steps.
If the discovery status stays in phase zero (idle) after you start it, and no devices
have been discovered, try the following troubleshooting steps.
1. If you are using the file finder, check that you have correctly specified which
field in the seed file contains the IP address and which contains the host name.
You can verify these settings in the Discovery Configuration GUI.
2. If you are using the ping finder and pinging individual IP addresses, check that
these IP addresses are reachable. If not, you might have a network outage or a
firewall issue.
3. Verify that the seed IP addresses are in scope. Even if you add an address to
the ping finder or file finder, the device is not pinged or instantiated if it is not
included in the scope. For example, if your discovery scope is 172.16.1.0 /24
and your seeds are in the 192.168.1.0 /24 network, then the finders cannot find
them.
4. If you are pinging a large, sparsely populated subnet, for example, a class B
subnet containing only 10 devices, the ping finder might take a long time to
find the first device.
If you need to review the discovery logs, refer to the information about locating
log files and changing logging levels in the IBM Tivoli Network Manager IP Edition
Administration Guide.
Related tasks:
“Starting a discovery” on page 52
After you configure a discovery, you can start and, if necessary, stop the discovery.
Repairing a corrupted discovery
If the discovery stops in an unusual way, for example, if the ncp_disco process is
stopped forcibly from the command line, or exits unexpectedly, you might need to
repair the discovery before running another discovery.
If the discovery is shut down normally, all the dependent processes such as
discovery agents are also shut down, and the discovery database is ready for
another discovery. However, if the ncp_disco process is stopped forcibly or
unexpectedly, then dependent processes can be left running, and the discovery
cache files are left in a state such that they can interfere with the next discovery. In
this case the discovery can be said to be corrupted.
To repair a corrupted discovery, complete the following steps:
1. Remove the entry for the ncp_disco process from the services.inTray database
in ncp_ctrl, if it is present. Removing the entry prevents the ncp_ctrl process
from restarting ncp_disco.
268
IBM Tivoli Network Manager IP Edition: Discovery Guide
2. Stop the ncp_disco process, if it is still running, using an appropriate command
for your operating system. For example, on Unix, run the kill -9 command on
the process ID for ncp_disco.
3. Remove the cache files for the dNCIM database. Navigate to the
$PRECISION_HOME/embeddedDb/sqlite directory and delete the ncp_disco.domain
directory.
4. Optional: Archive or remove existing log files to start the next discovery with
fresh log files. The log files for the following processes are relevant:
v ncp_disco
v ncp_df_*
v ncp_agent*
v ncp_disco_perl_agent*
5. Search for any discovery finders or agents that are still running in the
corrupted domain. The discover finders have process names that start with
ncp_df. The discovery agents start with ncp_agent, and any Perl discovery
agents start with ncp_disco_perl_agent. Stop any agents or finders that are still
running in the corrupted domain.
6. If you want to run the ncp_disco process as a process managed by the ncp_ctrl
process, which is the default, then start ncp_disco as a managed process. See
the topic on starting managed processes for more information. Starting
ncp_disco as a managed process starts a new discovery.
7. Start or monitor your discovery using the Discovery Configuration GUI.
Related tasks:
“Removing discovery cache files”
Remove discovery cache files to perform a new, clean discovery.
Removing discovery cache files
Remove discovery cache files to perform a new, clean discovery.
To remove the current network discovery for a domain, you must remove all
discovery cache files. You might want to do this when you need to remove all data
from a previous discovery, or when directed to do so by IBM Support.
This procedure deletes all current discovery cache files and clears the discovery
database, effectively resetting discovery. After performing this procedure, you must
run a new full discovery of your network.
Note: Because the network topology is stored separately in the NCIM database,
this procedure does not remove your network maps. However, any changes made
to your network since the last discovery are reflected in the next discovery.
Perform the following procedure to remove all discovery cache files:
1. Stop all Network Manager processes using the itnm_stop script.
2. Navigate to the $NCHOME/var/precision directory and remove all files that
belong to the domain you wish to remove. Files that belong to a particular
domain have the domain in the file name. For example, a configuration file
belonging to the domain NCOMS would be called file_name.NCOMS.cfg.
3. Navigate to the $PRECISION_HOME/embeddedDb/sqlite directory and delete the
ncp_disco.domain directory.
4. Optional: Archive or remove existing log files to start the next discovery with
fresh log files. The log files for the following processes are relevant:
Chapter 6. Troubleshooting discovery
269
v ncp_disco
v ncp_df_*
v ncp_agent*
v ncp_disco_perl_agent*
5. Restart the Network Manager processes using the itnm_start script.
New, empty log files are automatically created when the Network Manager
processes are restarted using the itnm_start scripts.
6. Perform a new network discovery.
Troubleshooting illegal characters
If you see an error message about illegal characters in insert statements into the
topology database, follow these steps to troubleshoot the problem.
If you have network devices with characters in their descriptions that are not
allowed in the locale set in the database, you might see an error message similar to
the following:
Warning: W-RIV-002-206: [4115626896t] CMdlDbEntityMgr.cc(647) A database ’execute’
operation has failed : SQLRETURN = 1 CNcpODBCSth.cc line 233 : [<database>][<database> ODBC Driver]
[<database>]An illegal character has been found in the statement.
1. Back up and edit the SnmpStackSchema.cfg file.
2. Locate the line that configures an insert into the snmpStack.conversionCfg table
and edit it to the following:
insert into snmpStack.conversionCfg values (1);
3. Save and close the file.
The SNMP Helper substitutes characters returned from devices that are not
allowed in the database locale with the question mark character: '?'.
The SNMP Helper substitutes characters on only those objects that are configured
in the snmpStack.multibyteObjects table.
270
IBM Tivoli Network Manager IP Edition: Discovery Guide
Chapter 7. Discovering and using custom data
You can enrich the topology by adding custom data to the information discovered
by the discovery process. For example, you can add custom data about discovered
entities from third-party sources using agents or collectors. This custom data can
subsequently be used for event enrichment, network visualization, polling and
reporting.
Adding custom data to the network topology involves discovering the data and
then storing it in the topology database. There are several methods for discovering
data. Choose the appropriate method based on the source and complexity of the
data.
There are two methods you can use to store custom data. Choose the appropriate
method based on what you want to do with the custom data:
Storing custom data using name-value pairs
If you want to use the extra data only for use in event enrichment or
viewing in the Structure Browser, then you can add custom data using
name-value pairs. You do not need to create custom database tables.
This method can be easier to implement and upgrade because you do not
need to change the default database schemas.
Storing custom data in new database tables
If you want to use the data not only for event enrichment or viewing in
the Structure Browser, but also for custom polling, finding devices in the
Hop View, or to use in defining Network Views, you must create new
database tables.
Reasons for adding custom data
The reasons for adding custom data determine the appropriate method of storing
the data. Common reasons for adding custom data to your topology include
enriching the data that is associated with a device or interface, and modeling
custom connectivity between devices.
Storing custom data in new database tables
If you want to filter or search on the data, store the data in custom tables. This
method of storing custom data is suitable for the following example uses.
v Creating different reports for different customers
v Implementing different poll policies for different providers based on Service
Level Agreements
v Creating a network view based on location
All the previous uses involve identifying the relevant entities based on the custom
data fields. Storing the data in new database tables is more performant for these
uses than storing the data as name-value pairs.
© Copyright IBM Corp. 2006, 2017
271
Storing custom data as name-value pairs in the entityDetails
database table
If you want to include the custom data as part of another operation, store the data
as name-value pairs in the entityDetails database table. This method of storing
custom data is suitable for the following example uses.
v Adding customer names to reports that filter on other data
v Tagging network events with location or customer name
In these cases, the relevant entities are selected based on other database fields.
Entities are selected by SQL queries or Event Gateway lookups. The custom data is
extracted from the selected entities if it is present. For these uses, you can
alternatively store the data in new database tables, but it is quicker to store data as
name-value pairs in the entityDetails database table.
Modeling custom connectivity between entities
Custom connectivity is modeled in Network Manager by using layers. Examples of
connectivity modeled by default by using layers include the following types:
v Cisco Discovery Protocol, the protocol that is used between Cisco
communications devices.
v SynOptics Network Management Protocol, the protocol that is used between
Nortel communications devices.
If you want to model custom connectivity between entities, then you must store
the data in new database tables. You must write a custom agent to retrieve the
relevant custom data from your network entities. You must also write a custom
layer stitcher to build the custom connectivity from the agent data. Examples of
default layer stitchers that are provided with Network Manager are CDPLayer.stch,
OSPFLayer.stch, SONMPLayer.stch, and SRPLayer.stch. You can inspect these
stitchers to help you write your custom layer stitcher.
Discovering custom data
To use custom data in the product, you must first add the information to the
discovery.
You can use different methods to discover custom data.
Adding name-value pairs to entities using the File finder
If you enable the File finder to seed your discovery, then you can add name-value
pairs to entities by adding extra columns to the seed file read by the File finder.
The example procedure below assumes that you are adding the following extra
columns to your File finder seed file:
v customer
v location
The following example text file fragment shows what the seed file might look like:
vi /var/tmp/logged_hosts
172.16.1.21
172.16.1.201
172.16.1.25
172.16.2.33
272
lnd-dharma-acme
lnd-phoenix-acme
prs-sun-acme
ranger1
IBM Tivoli Network Manager IP Edition: Discovery Guide
acme
acme
acme
telecorp
london
london
paris
newyork
172.16.2.34
ranger2
telecorp
newyork
~
"/var/tmp/logged_hosts" [Read only] 4 lines, 190 characters
In this example text file fragment, the third column holds customer information,
and the fourth column holds location information.
1. Edit the DiscoFileFinderParseRules.cfg configuration file.
2. In this configuration file, configure the File finder to parse the seed file using
an insert similar to the example. Ensure that you configure the m_ColDefs field
to match the new custom tag columns.
insert into fileFinder.parseRules
(
m_FileName,
m_Delimiter,
m_ColDefs
)
values
(
"/var/tmp/logged_hosts",
"[
]",
[
{
m_VarName="m_UniqueAddress",
m_ColNum=1
},
{
m_VarName="m_Name",
m_ColNum=2
},
{
m_VarName="m_CustomTags->customer",
m_ColNum=3
},
{
m_VarName="m_CustomTags->location",
m_ColNum=4
}
]
);
This insert instructs the File finder to do the following:
v Parse /var/tmp/logged_hosts.
v Treat white space as the data separator.
v Use the following column definitions:
– m_UniqueAddress for the first column
– m_Name for the second column
– m_CustomTags->customer for the third column
– m_CustomTags->location for the fourth column
3. Edit the DbEntityDetails.cfg file and configure an insert similar to the
following:
insert into dbModel.entityDetails
(
EntityType,
EntityDetails
)
values
(
1, -- chassis
{
Customer = "eval(text, ’&m_ExtraInfo->m_CustomTags->customer’)",
Chapter 7. Discovering and using custom data
273
Location = "eval(text, ’&m_ExtraInfo->m_CustomTags->location’)"
}
);
insert into dbModel.entityDetails
(
EntityType,
EntityDetails
)
values
(
2, -- port/interface
{
Customer = "eval(text, ’&m_ExtraInfo->m_CustomTags->customer’)",
Location = "eval(text, ’&m_ExtraInfo->m_CustomTags->location’)"
}
);
4. Restart Network Manager to propagate the configuration file changes:
itnm_start ncp -domain domain
5. Run a full discovery using the File finder to discover your network with the
name-value pairs added.
Ensure that the new data is propagated between discoveries.
Related reference:
“model.config table” on page 411
The model.config table stores the configuration information that is used by
MODEL during rediscovery.
Developing agents or collectors to retrieve custom data
You can develop custom discovery agents or collectors to retrieve custom data and
add it to the discovery.
You can retrieve custom data from a third-party source, such as a flat file,
database, or third-party system. Do this by developing a Perl agent or an EMS
collector.
Important:
Writing custom discovery agents or collectors is an advanced procedure. Incorrect
inserts into discovery databases can corrupt discovery and cause unpredictable
results. Consider engaging IBM Services or an IBM Business Partner.
Use the following information to determine the best method to retrieve data:
Table 36. Methods for retrieving data
274
Source system
Method
Link
EMS
EMS collector
“Configuring EMS
discoveries” on page 105
Flat file or database
Custom agent
For information about
writing discovery agents, see
the IBM Tivoli Network
Manager IP Edition Perl API
Guide.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Adding data manually using custom tag tables
You can add name-value pairs to entities by creating inserts containing the
name-value pair data into the disco.ipCustomTags table or into the
disco.filterCustomTags table.
Related reference:
“ncimCache.entityData table” on page 402
The ncimCache.entityData table holds different kinds of data about entities.
Adding name-value pairs to entities using the
disco.ipCustomTags table
You can associate name-value pair tags to unique IP addresses using the
disco.ipCustomTags table. Use this method if you know the individual IP
addresses that you want to tag.
The example procedure below assumes that you are adding the following two
custom name-value pair tags to entities in your discovery:
v customer
v location
This example uses the disco.ipCustomTags table to configure the following
name-value pair tags:
Table 37.
IP Address
Name
Value
172.16.1.21
customer
acme
172.16.1.21
location
london
172.16.1.201
customer
acme
172.16.1.201
location
london
172.16.1.25
customer
acme
172.16.1.25
location
paris
172.16.2.33
customer
telecorp
172.16.2.33
location
newyork
172.16.2.34
customer
telecorp
172.16.2.34
location
newyork
1. Edit the DiscoConfig.cfg configuration file.
2. In this configuration file, add an insert similar to the following.
insert into disco.ipCustomTags
(
m_UniqueAddress,
m_CustomTags
)
values
(
’172.16.1.21’,
{
customer="acme",
location="london"
}
);
insert into disco.ipCustomTags
(
Chapter 7. Discovering and using custom data
275
m_UniqueAddress,
m_CustomTags
)
values
(
’172.16.1.201’,
{
customer="acme",
location="london"
}
);
insert into disco.ipCustomTags
(
m_UniqueAddress,
m_CustomTags
)
values
(
’172.16.1.25’,
{
customer="acme",
location="paris"
}
);
insert into disco.ipCustomTags
(
m_UniqueAddress,
m_CustomTags
)
values
(
’172.16.2.33’,
{
customer="telecorp",
location="newyork"
}
);
insert into disco.ipCustomTags
(
m_UniqueAddress,
m_CustomTags
)
values
(
’172.16.2.34’,
{
customer="telecorp",
location="newyork"
}
);
3. Save the DiscoConfig.cfg configuration file.
You can now run a full discovery to discover your network with the custom tags.
276
IBM Tivoli Network Manager IP Edition: Discovery Guide
Adding name-value pairs to entities using the
disco.filterCustomTags table
You can associate name-value pair tags to a filtered set of IP addresses using the
disco.filterCustomTags table. Use this method if you want to tag multiple
addresses using a shared attribute of those devices.
You can filter IP addresses based on a wide variety of criteria. For example, you
can filter based on device name, based on IP address, or based on VLAN identifier.
The example procedure below applies a filter based on IP address, and uses the
disco.filterCustomTags table to configure the following name-value pair tags to all
IP addresses in the subnet 172.20.3.0/24:
Table 38.
IP Address
Name
Value
172.20.3.0/24
customer
acme
172.20.3.0/24
location
london
1. Edit the DiscoConfig.cfg configuration file.
2. In this configuration file, add the following insert:
insert into disco.filterCustomTags
(
m_Filter,
m_CustomTags
)
values
(
"m_UniqueAddress LIKE ’172.20.3’",
{
customer="acme",
location="london"
}
);
3. Save the DiscoConfig.cfg configuration file.
Other examples of filters
The procedure above applies a filter based on IP address: "m_UniqueAddress LIKE
’172.20.3’".
You can create a filter based on any attributes associated with discovered entities.
For example, you could apply the following filters:
v Filter based on entity name: "m_Name LIKE ’lon’"
v Filter based on VLAN identifier of a VLAN entity: "m_LocalNbr->m_VlanID =
102"
You can now run a full discovery to discover your network with the custom tags.
Chapter 7. Discovering and using custom data
277
Enriching the topology using the GetCustomTag stitcher
You can use the GetCustomTag stitcher to add data to topology entities. You might
choose to use this method if you have complex customization needs.
If you want to apply a fixed tag to matched entities, you can use the
m_CustomTags field, and you do not need to use the GetCustomTag stitcher.
If you want to add more complex data, then customize the GetCustomTag.stch
stitcher. The tag configured in the m_StitcherTagName field is used as the field
name, and the value returned by the GetCustomTag stitcher is used as the field
value.
Note: Editing stitchers is an advanced task, which requires knowledge of the
Stitcher Language and the discovery data flow.
To customize the GetCustomTag.stch stitcher, complete the following steps:
1. Add data to the disco.filterCustomTags or disco.ipCustomTags table to specify
which entities to apply custom tags to.
2. Edit the DiscoConfig.cfg configuration file to configure the GetCustomTag
stitcher.
3. In this configuration file, add the following insert:
insert into disco.filterCustomTags
(
m_Filter,
m_StitcherTagName,
)
values
(
"m_UniqueAddress LIKE ’172.20.3.’",
’customer’
);
This insert configures the system to use the GetCustomTag.stch stitcher to look
up the value of the customer field for each entity in the subnet 172.20.3.0/24.
The GetCustomTag.stch stitcher must be modified to provide this information,
otherwise the name/value pair is not added to the entity.
4. Save the DiscoConfig.cfg configuration file.
5. Modify the GetCustomTag.stch stitcher to support the custom tag. The
GetCustomTag.stch stitcher receives the tag and entity name as stitcher
arguments 1 and 2 respectively and returns a text value. Customize the
GetCustomTag.stch stitcher to determine the appropriate return values,
depending on what you want to use the data for. In the following example, the
stitcher is customized to check for the string lon in the supplied entity name. If
the entity name contains the string, the value A-Z Inc., London is returned as
the value for customer. If the entity name does not contain the string, none is
returned.
UserDefinedStitcher
{
StitcherTrigger
{
// Called from another stitcher when tag criteria is met
}
StitcherRules
{
text tagName = eval(text,’$ARG_1’);
text entityName = eval(text,’$ARG_2’);
278
IBM Tivoli Network Manager IP Edition: Discovery Guide
text value = NULL;
if(tagName == "customer")
{
// insert logic to retrieve custom tag
//
// As an example, here we use pattern matching to
// assign all entities with ’lon’ in their name
// to the A-Z Inc. customer.
//
int count = MatchPattern(entityName, ’(lon)’);
if (count == 1)
{
value = "A-Z Inc., London";
}
else
{
// Not an A-Z Inc. device.
// If we leave value as NULL then no
// ’customer’ custom tag will be
// created, however in this example we
// want such entities tagged with
// ’none’..
value = "none";
}
}
SetReturnValue(value);
}
}
Note: Only entities that pass the criteria configured in the
disco.filterCustomTags or disco.ipCustomTags table are passed to the
GetCustomTag.stch stitcher.
The following custom name-value pair tag is added to all IP addresses in the
subnet 172.20.3.0/24:
Table 39. Data added to entities
IP Address
Name
Value
172.20.3.0/24
Customer
A-Z Inc., London
You must now configure the DbEntityDetails.cfg configuration file to ensure that,
following discovery, the NCIM topology database entityDetails table is updated
with the custom tags.
The example GetCustomTag stitcher:
This example explains how an example GetCustomTag stitcher retrieves the
customer name associated with a device.
How the GetCustomTag stitcher is called
The GetCustomTag.stch stitcher is called by the AddCustomTags.stch stitcher. You
do not need to modify the AddCustomTags stitcher. You do need to modify the
GetCustomTag stitcher.
The AddCustomTags stitcher loops through the tags and the entities in the
disco.ipCustomTags and disco.filterCustomTags tables. If, in either of these tables,
the m_StitcherTagName field is set, then the AddCustomTags stitcher calls the
Chapter 7. Discovering and using custom data
279
GetCustomTag stitcher and passes it the relevant entity name and the
m_StitcherTagName field as parameters. The m_StitcherTagName field holds the
name part of a name-value pair tag, for example, Customer.
If the GetCustomTags stitcher returns a non-NULL value for a tag or entity then
the AddCustomTags stitcher updates the m_ExtraInfo->m_CustomTags object in the
workingEntities.finalEntity table record for the entity. The tag is used as the field
name and the return value is used as the field value. From the
workingEntities.finalEntity database table, the data passes to the DNCIM database,
the ncimCache database, and the NCIM database.
Note: The AddCustomTags stitcher retrieves the entity name by performing a
lookup in the workingEntities.finalEntity table. The stitcher uses the IP address in
the disco.ipCustomTags table or the m_Filter as the WHERE clause provided in the
disco.filterCustomTags table.
Description of an example GetCustomTag stitcher
The GetCustomTag stitcher takes as input a single entity name and a tag (the
m_StitcherTagName field). You write custom logic in the stitcher to evaluate the
value part of the name-value pair. By default the stitcher contains example code
similar to that described here. You can customize this stitcher to work with
different name-value pairs and you can change the logic defining how the value is
calculated.
Table 40. Line-by-line description of an example GetCustomTag stitcher
Line numbers Description
280
10
Set the value of the tagName variable from the first argument received
from the AddCustomTags stitcher. This value is the name of the tag for
which the value is to be evaluated.
11
Set the value of the entityName variable from the first argument received
from the AddCustomTags stitcher. The entityName variable holds the
entity name associated with the IP address for which the stitcher is
evaluating the value of a name-value pair tag.
13
Set the value variable to NULL. The value variable is returned by the
stitcher and holds the evaluated value of the name-value pair tag.
15
Test for a supported tag. In this case the tag is customer. You can add
support for further custom tags by adding more else if blocks.
16-35
The customer tag lookup code. If the entity name contains the text pattern
lon then set the value variable to the customer name A-Z Inc. London,
otherwise set it to none.
37
Return the value of the tag.
IBM Tivoli Network Manager IP Edition: Discovery Guide
1]
2]
3]
4]
5]
6]
7]
8]
9]
10]
11]
12]
13]
14]
15]
16]
17]
18]
19]
20]
21]
22]
23]
24]
25]
26]
27]
28]
29]
30]
31]
32]
33]
34]
35]
36]
37]
38]
39]
40]
41]
42]
UserDefinedStitcher
{
StitcherTrigger
{
// Called from another stitcher when tag criteria
// is met
}
StitcherRules
{
text tagName = eval(text,’$ARG_1’);
text entityName = eval(text,’$ARG_2’);
text value = NULL;
if(tagName == "customer")
{
// insert logic to retrieve custom tag
//
// As an example, here we use pattern matching
// to assign all entities with ’lon’
// in their name to the A-Z Inc. customer.
//
int count = MatchPattern(entityName, ’(lon)’);
if (count == 1)
{
value = "A-Z Inc., London";
}
else
{
// Not an A-Z Inc. device.
// If we leave value as NULL then no ’customer’
// custom tag will be created,
// however in this example we want
// such entities tagged with ’none’..
value = "none";
}
}
SetReturnValue(value);
}
}
Storing custom data as name-value pairs in the entityDetails table
If you want to use the extra data for uses such as adding to reports, enriching
network events, or viewing in the Structure Browser, then you can store custom
data as name-value pairs in the existing entityDetails database table. You do not
need to create new database tables.
The entityDetails database table is a default topology database table. You can add
custom data to this table by inserting it as name-value pairs. This method is easier
than creating new database tables, but less performant if you need to select entities
based on the data.
Tip: If you want to use the data for custom polling, finding devices in the Hop
View, or to use in defining Network Views, create new database tables instead. Use
the procedure at: “Storing custom data in new database tables” on page 284.
Chapter 7. Discovering and using custom data
281
To discover custom data and store it as name-value pairs, you need to discover the
data, ensure that the data persists over multiple discoveries, and configure how the
data is added to the DNCIM discovery database.
The data flow for discovering custom data and storing it as name-value pairs is as
follows:
1. The data is retrieved from the source (flat file, EMS, or other source) by a
discovery agent, collector, or Finder.
2. The name-value pairs are inserted into the workingEntities.finalEntity database
table.
3. The ncp_disco process uses the dbModel.entityDetails discovery database table
to populate the entityDetails table in the DNCIM discovery database with the
information from the workingEntities.finalEntity table.
4. The data in the entityDetails table in DNCIM is automatically copied to the
entityDetails table in NCIM and the ncimCache.entityData table.
5. From the ncimCache.entityData table, the data is available to the Event
Gateway for event enrichment. If events are enriched with the data, the
information is available in the Event Viewer.
6. From the NCIM topology database, the data is available to the Structure
Browser.
The following table shows an example of the kind of data you might add to a
device as name-value pairs.
Table 41. Example of name-value pair tags
IP address
Name
Value
172.20.3.20
customer
acme
172.20.3.20
location
london
Importing name-value pairs into the DNCIM discovery
database
After the name-value pairs have been discovered, they must be inserted into the
DNCIM discovery database. Configure the DbEntityDetails.cfg configuration file
so that the name-value pairs are inserted into the DNCIM discovery database.
The ncp_disco process uses the dbModel.entityDetails discovery database table to
populate the entityDetails table in the DNCIM discovery database with the
information from the workingEntities.finalEntity table. To configure an insert into
the dbModel.entityDetails table, complete the following steps:
1. Edit the DbEntityDetails.cfg configuration file.
Note: Editing the ModelNcimDb.cfg configuration file makes it more difficult to
migrate your customizations. Edit the DbEntityDetails.cfg configuration file
instead.
2. Add an insert into the dbModel.entityDetails database table to extend the
default EntityType filter.
You can have only one entityDetails mapping per EntityType filter. For
example, append a mapping similar to the following code:
insert into dbModel.entityDetails
(
EntityType,
EntityDetails
282
IBM Tivoli Network Manager IP Edition: Discovery Guide
)
values
(
1, -- chassis
{
NetworkEdge = "eval(text, ’&m_ExtraInfo->m_NetworkEdge’)",
CustomerName = "eval(text, ’&m_ExtraInfo->m_CustomerName’)",
CustomerType = "eval(text, ’&m_ExtraInfo->m_CustomerType’)"
}
);
3. Save and close the DbEntityDetails.cfg configuration file.
The next time that a full discovery is run, the name-value pairs are inserted into
the entityDetails table in the DNCIM discovery database. The data in the
entityDetails table in DNCIM is automatically copied to the entityDetails table in
NCIM and the ncimCache.entityData table.
Ensure that custom name-value pairs are preserved between discoveries.
Preserving custom name-value pairs between discoveries
By default, custom data added to the dbModel.entityDetails table using inserts into
the DbEntityDetails.cfg file is deleted if it is not present in the next discovery. You
can configure discovery to preserve this custom data.
To configure the discovery to keep custom name-value pairs that were added to
the dbModel.entityDetails table, enable the KeepOldEntityDetails setting.
If the KeepOldEntityDetails setting is enabled, the data is preserved in future
discoveries. The values are updated if new information is discovered.
To enable the KeepOldEntityDetails setting, complete the following steps:
1. Back up and edit the NCHOME/etc/precision/ModelSchema.cfg file.
2. Locate the insert into the model.config table and set the KeepOldEntityDetails
field to 1 (enabled).
For example, the insert might look like this:
insert into model.config
(
LingerTime,
ChassisCreationEvents,
IpInterfaceCreationEvents,
MaintenanceStateEvents,
ManagedStatusUpdateInterval,
DeleteRenamedDevices,
KeepOldEntityDetails
)
values
(
3,
0,
0,
0,
30,
1,
1,
);
Chapter 7. Discovering and using custom data
283
Storing custom data in new database tables
If you want to use the data for custom polling, finding devices in the Hop View, or
to use in defining Network Views, you must create new database tables.
If you want to use custom data for applications that involve selecting entities
based on the custom data, it is more performant to use custom database tables.
Tip: If you want to use the extra data only for applications where entities are
selected based on other database fields, for example in event enrichment or
viewing in the Structure Browser, you do not need to create custom database
tables. You can store custom data more easily as name-value pairs in the
entityDetails database table, following the procedure at: “Storing custom data as
name-value pairs in the entityDetails table” on page 281.
To store custom data in new database tables, you need to do the following tasks:
v Create new tables in the NCIM topology database.
v Create the same tables in the DNCIM discovery database.
v Discover the data.
v Configure how the data is added to the DNCIM discovery database.
The data flow for discovering custom data by creating custom database tables is as
follows:
1. The data is retrieved from the source (flat file, EMS, or other source) by a
discovery agent or collector.
2. The data is inserted into the workingEntities.finalEntity database table.
3. The ncp_disco process uses the dbModel.entityMap discovery database table to
populate the new custom table in the DNCIM discovery database with the
information from the workingEntities.finalEntity table.
4. The data in the new custom table in DNCIM is automatically copied to the
equivalent table in NCIM and the ncimCache.entityData table.
5. From the ncimCache.entityData table, the data is available to the Event
Gateway for event enrichment. If events were enriched with the data, the
information is available in the Event Viewer.
6. From the NCIM topology database, the data is available to the Network Hop
View, Network Views, and Structure Browser.
Creating new tables in the NCIM topology database
Create new tables in the NCIM database to hold the custom data that you want to
discover.
If you create the NCIM database tables first, you can plan what you want to use
the data for, before you configure how it is discovered.
1. Define the new table in NCIM by using the command line tool for your
database, or ncp_oql.
2. Call the first field of the new table entityID and define the field as a foreign
key to the entityData table. Defining the entityID field in this way links the
extra information about the entity to the main NCIM entity register. If the
entity is removed from the entityData table, the data is also deleted from the
custom table.
3. Restart Network Manager.
284
IBM Tivoli Network Manager IP Edition: Discovery Guide
4. Optional: Insert some example data into the new table and test if it is suitable
for your purpose.
Creating new tables in different databases
The following example SQL statement shows how to create a custom table
exampleCustomData in NCIM for DB2. The table used in the example is based on
the example dNCIM customisation defined in the createCustomization.sql file
supplied with Network Manager.
CREATE TABLE exampleCustomData
(
entityIdINTEGER NOT NULL,
slaId
VARCHAR(255),
customerId
VARCHAR(255),
customerContact
VARCHAR(255),
CONSTRAINT example_cd_pk PRIMARY KEY (entityId),
CONSTRAINT excd_entData_fk FOREIGN KEY (entityId)
REFERENCES entityData(entityId) ON DELETE CASCADE
);
The following example SQL statement shows how to create a custom table
exampleCustomData in NCIM for Oracle. The table used in the example is based on
the example dNCIM customisation defined in the createCustomization.sql file
supplied with Network Manager.
CREATE TABLE exampleCustomData
(
entityIdNUMBER(10) NOT NULL,
slaId
VARCHAR2(255),
customerId
VARCHAR2(255),
customerContact
VARCHAR2(255),
-CONSTRAINT
example_cd_pk PRIMARY KEY (entityId),
-CONSTRAINT excd_entData_fk FOREIGN KEY (entityId)
REFERENCES entityData(entityId) ON DELETE CASCADE
);
Now create the same table in the DNCIM discovery database.
Updating dNCIM to store custom data
Update dNCIM to store custom data by first writing an SQL script to define the
tables to store the custom data.
To support the creation of the new SQL script and to ensure that the custom tables
defined in the script are automatically recreated if the dNCIM database is dropped,
the following pieces of sample code are provided. You can use these pieces of code
as a starting point
Code to define the custom dNCIM tables
A sample SQL script is provided called createCustomization.sql, located
at $NCHOME/precision/scripts/sql/sqlite/createCustomization.sql. This
script contains an example of the SQL needed to create a custom table to
store custom data:
CREATE TABLE dncim.exampleCustomData
(
entityId
INTEGER NOT NULL,
slaId
VARCHAR(255),
customerId
VARCHAR(255),
Chapter 7. Discovering and using custom data
285
customerContact
VARCHAR(255),
CONSTRAINT example_cd_pk PRIMARY KEY (entityId),
CONSTRAINT exCd_entData_fk FOREIGN KEY (entityId)
REFERENCES entityData(entityId) ON DELETE CASCADE
);
To update dNCIM to store custom data, perform the following steps:
1. Modify the sample SQL script createCustomization.sql script to define the
tables to store your custom data.
2. Save the file $NCHOME/precision/scripts/sql/sqlite/createCustomization.sql.
3. Delete the old dNCIM database directory $NCHOME/precision/embeddedDb/
sqlite/ncp_disco.domain_name/.
Where domain_name is the name of the relevant domain.
The dNCIM database directory $NCHOME/precision/embeddedDb/sqlite/
ncp_disco.domain_name/ will be recreated when you next restart the Discovery
engine, ncp_disco. The new dNCIM database directory will pick up the
changes that you specified in the createCustomization.sql SQL script.
You must also configure NCIM to store the custom data.
Mapping retrieved data to DNCIM custom data tables
Specify how custom data from the discovery should be stored in the topology
database by mapping the custom data to the custom tables added to dNCIM and
NCIM.
Define inserts within the $NCHOME/etc/precision/DbEntityDetails.cfg
configuration file to specify how to map the custom data to the dNCIM custom
tables.
Related reference:
“dbModel database” on page 388
The dbModel database maps custom discovery data from discovery agents to
NCIM tables.
Example: add single row of custom data about existing entity
To add a single row of custom data, add the appropriate insert to the
$NCHOME/etc/precision/DbEntityDetails.cfg configuration file.
Inserting data discovered using the File finder, a discovery agent, or
collector
The following insert adds a single row of custom data about an existing entity. In
the mapping, the values on the left are the field names of a new table called
exampleCustomData. The exampleCustomData table must be created in dNCIM and
NCIM. The eval statements on the right take the values from the
workingEntities.finalEntity database table. This data must already be discovered
by using one of the methods for discovering custom data and added to the
workingEntities.finalEntity database table.
In this example, service-level agreement data for a an existing entity is mapped to
the custom dNCIM table exampleCustomData.
286
IBM Tivoli Network Manager IP Edition: Discovery Guide
In this example, the data was discovered using the File finder, a discovery agent,
or collector. The data was added to custom fields within the m_ExtraInfo field in
the workingEntities.finalEntity database table.
1]
2]
3]
4]
5]
6]
7]
8]
9]
10]
11]
12]
13]
14]
15]
16]
17]
insert into dbModel.entityMap
(
EntityFilter,
TableName,
FieldMap
)
values
(
"m_ExtraInfo->m_CustomerSLA IS NOT NULL",
"exampleCustomData",
{
entityId
= "eval(int, ’&m_EntityId’)",
slaId = "eval(text, ’&m_ExtraInfo->m_CustomerSLA’)",
customerId
= "eval(text, ’&m_ExtraInfo->m_CustomerId’)",
customerContact
= "eval(text, ’&m_ExtraInfo->m_CustomerContact’)"
}
);
The table below describes the insert.
Table 42. Description of the insert
Line
Description
9
Only add rows to the custom table where the m_ExtraInfo->m_CustomerSLA custom
field for the entity has a value. This filters out entities that are not associated with
a service-level agreement.
10
Add the rows to the custom dNCIM table exampleCustomData.
11-16
Add the following data to each row:
v Entity identifier.
v Service level agreement identifier.
v Customer identifier.
v Customer contact.
Inserting data discovered using custom tag tables
The following insert adds a single row of custom data about an existing entity. In
the mapping, the values on the left are the field names of a new table called
exampleCustomData. The exampleCustomData table must be created in dNCIM and
NCIM. The eval statements on the right take the values from the
workingEntities.finalEntity database table. This data must already be discovered
by using one of the methods for discovering custom data and added to the
workingEntities.finalEntity database table.
In this example, service-level agreement data for a an existing entity is mapped to
the custom dNCIM table exampleCustomData.
In this example, the data was discovered using custom tag tables. Data discovered
using custom tag tables is added to custom fields within the m_ExtraInfo>m_CustomTags field in the workingEntities.finalEntity database table.
Chapter 7. Discovering and using custom data
287
1]
2]
3]
4]
5]
6]
7]
8]
9]
10]
11]
12]
13]
14]
15]
16]
17]
18]
19]
20]
insert into dbModel.entityMap
(
EntityFilter,
TableName,
FieldMap
)
values
(
"m_ExtraInfo->m_CustomTags->m_CustomerSLA IS NOT NULL",
"exampleCustomData",
{
entityId
= "eval(int, ’&m_EntityId’)",
slaId
= "eval(text, ’&m_ExtraInfo
->m_CustomTags->m_CustomerSLA’)",
customerId
= "eval(text, ’&m_ExtraInfo
->m_CustomTags->m_CustomerId’)",
customerContact
= "eval(text, ’&m_ExtraInfo
->m_CustomTags->m_CustomerContact’)"
}
);
The table below describes the insert.
Table 43. Description of the insert
Line
Description
9
Only add rows to the custom table where the m_ExtraInfo->m_CustomTags>m_CustomerSLA custom field for the entity has a value. This filters out entities that
are not associated with a service-level agreement.
10
Add the rows to the custom dNCIM table exampleCustomData.
11-16
Add the following data to each row:
v Entity identifier.
v Service level agreement identifier.
v Customer identifier.
v Customer contact.
Related reference:
“dbModel.entityMap table” on page 391
The dbModel.entityMap table defines how values are mapped from the discovery
workingEntities.finalEntity table to dNCIM and NCIM.
Using custom data to enrich events
You can use custom data in event enrichment in a similar way to normal data.
Ensure that you are familiar with how to do event enrichment with normal data. If
you want to use a new field in the ObjectServer alerts.status table to store the
enriched data, you must create the field in the ObjectServer first before following
the steps below.
For information on how to add a custom field to an ObjectServer table, see the
IBM Tivoli Netcool/OMNIbus Administration Guide.
The name of an interface is available in the NCIM topology database interface
table. This field can be accessed using NCIM cache, and is held in the
ncimCache.entityData table.
288
IBM Tivoli Network Manager IP Edition: Discovery Guide
For more information on the structure of NCIM cache tables and fields, see the
IBM Tivoli Network Manager IP Edition Topology Database Reference.
The following steps explain how to configure this extra event enrichment.
1. Edit the Event Gateway schema file, $NCHOME/etc/precision/
EventGatewaySchema.cfg, to allow the Event Gateway to update the new field.
Remember to add a comma at the end of the line containing the NmosSerial
field, before the line containing the new InterfaceName field. For example, to
configure the Event Gateway to update a new field customer, add the text in
bold to the outgoing event filter.
insert into config.ncp2nco
(
FieldFilter
)
values
(
[
"NmosCauseType",
"NmosDomainName",
"NmosEntityId",
"NmosManagedStatus",
"NmosObjInst",
"NmosSerial",
"Customer"
]
);
Note: Fields that are added to the outgoing event filter are automatically
added to the incoming field filter, config.nco2ncp, thus ensuring that the
current value of the field is retrieved. This allows the StandardEventEnrichment
stitcher to check the value of the InterfaceName field before updating it. This
technique ensures that the Event Gateway does not keep updating the same
value.
2. Edit the Event Gateway stitchers to retrieve the customer information from the
topology database and to populate the Customer field. One way to do this is
by adding code to the StandardEventEnrichment stitcher. The code is different
depending whether you added custom data as name-value pairs to the
entityDetails table or created a custom database table. Adding this code to the
stitcher ensures that this procedure is performed for all topology events that are
matched to an entity. Add this code to the stitcher immediately before the final
line, the call to GwEnrichEvent( enrichedFields ) and after determining the
entityType value. For more information on the GwEnrichEvent() stitcher rule,
see the IBM Tivoli Network Manager IP Edition Language Reference.
The following example code takes the value of customerId from the
entityDetails table in the ncimCache files. Use this method if you added custom
data without creating new NCIM database tables.
1]
2]
3]
4]
5]
6]
7]
8]
9]
if ( entityType == 1 )
{
text customerName = @entity.entityDetails.customerId;
if ( customerName <> eval(text, ’&Customer’) )
{
@enrichedFields.Customer = customerName;
}
}
Chapter 7. Discovering and using custom data
289
Table 44. Lines of code relevant to the interface name example
Line numbers Description
1
This event enrichment is only relevant for chassis events. Check that this
event relates to a chassis by ensuring that the entityType value is 1, and if
so, continue processing.
3
Retrieve the customer data from the entityDetails table.
Note: Fields within the NCIM cache are usually in all uppercase, for
example, @mainNode.chassis.SYSLOCATION. In this example, customerName is
in mixed case because it is in the entityDetails table.
5-8
Only populate the Customer field if the value is not already present in the
in-scope event.
The following example code takes the value of customerName from the customer
table in the ncimCache files. Use this method if you added custom data to a
new NCIM database table.
1]
2]
3]
4]
5]
6]
7]
8]
9]
if ( entityType == 1 )
{
text customerName = @entity.customer.CUSTOMERNAME;
if ( customerName <> eval(text, ’&CustomerName) )
{
@enrichedFields.CustomerName = customerName;
}
}
Visualizing custom data in the Structure Browser
If you add custom data using name-value pairs in the entityDetails table or by
creating new database tables, you can see the data in the Structure Browser.
You do not need to perform any extra configuration steps to see custom data in the
entityDetails table in the Structure Browser.
To see new database tables in the Structure Browser, complete the following steps.
1. Go to the $NMGUI_HOME/profile/etc/tnm/ directory.
2. Edit the ncimMetaData.xml file and locate the section that defines the
entityType with which you want to associate the custom data. This entityType
is most commonly 1, that is, a chassis.
3. Add the custom data by adding lines similar to the following lines in bold:
<entityMetaData entityType="1" table="physicalChassis" manager="PrecisionIP"
entitySearch="true">
<dataField tableAlias="e"
entitySearch="false"/>
<dataField tableAlias="e"
entitySearch="false"/>
<dataField tableAlias="e"
entitySearch="false"/>
<dataField tableAlias="e"
entitySearch="true"/>
dataType="int" column="entityId"
dataType="str" column="entityName"
dataType="str" column="displayLabel"
dataType="bool" column="manual"
...
<dataField tableAlias="x" dataType="str" column="customerId"/>
<dataField tableAlias="x" dataType="str" column="slaId"/>
<dataField tableAlias="x" dataType="str" column="customerContact"/>
290
IBM Tivoli Network Manager IP Edition: Discovery Guide
<fromTables>
FROM _ncim_.entityData e
...
LEFT OUTER JOIN _ncim_.exampleCustomData x ON x.entityId =
e.entityId
In the preceding example, a left join against the custom table is used. This join
ensures that data is displayed for devices that do not have an entry in the
custom database table. The fields to be displayed are listed, and the tableAlias
matches the alias given in the left join statement.
Using custom data in polling
You can poll a set of network devices based on custom data.
To define a polling scope based on custom data, complete the following steps.
1. Create a network view based on the custom data that you want to use. Refer to
the task “Visualizing custom data in the topology views” for more information.
2. Create or edit a poll policy. Specify the new network view as the scope for the
poll policy.
Visualizing custom data in the topology views
If you added custom data to a new NCIM database table, you can search on the
custom data, and you can create network views with the custom data.
It is possible to create network views based on custom data that was added as
name-value pairs, but these network views are not efficient. For better
performance, create network views based on only custom data that was added in
new database tables.
To enable visualization of custom attributes in the topology views, complete the
following tasks:
1. Go to the $NMGUI_HOME/profile/etc/tnm/ directory.
2. Edit the ncimMetaData.xml file by appending lines similar to the following
example:
<entityMetaData table="customer" manager="AllManagers" entitySearch="true">
<dataField dataType="str" column="customerName"/>
<dataField dataType="str" column="customerType"/>
</entityMetaData>
In the preceding example, the custom table customer is added. The manager
attribute must always be set to AllManagers. Set the attribute entitySearch to
true to use the data in searches. Each dataField is a single column of the table
to be displayed and must have the correct dataType.
Operators can now select the table when they search in the Hop View or when
they create a new dynamic network view.
Chapter 7. Discovering and using custom data
291
292
IBM Tivoli Network Manager IP Edition: Discovery Guide
Appendix A. Discovery databases
There are various specialized databases that are used by ncp_disco, the component
that discovers network device existence and connectivity, and by ncp_model, the
component that manages, stores, and distributes the discovered network topology.
The ncp_disco component and ncp_model component store configuration,
management, and operational information in databases. You can interrogate these
databases by logging into the DISCO or MODEL service using the OQL Service
Provider.
The ncp_disco databases can either be active or passive. When data is inserted into
an active database, an action is automatically triggered; for example, another table
is populated with data, or a script or stitcher is launched.
Related concepts:
“Device filters” on page 14
Use prediscovery filters to increase the efficiency of discovery.
Related tasks:
“Setting discovery filters” on page 37
Use filters to filter out devices either before discovery or after discovery. You can
filter out devices based on a variety of criteria, including location, technology, and
manufacturer. Filters provide additional restrictions to those defined in the scope
zones.
“Scoping discovery” on page 27
To scope the discovery for IP-based devices and subnets, define the zones of the
network (that is, subnet ranges) that you want to include in the discovery, and the
zones that you want to exclude.
Discovery engine database
Use the Discovery engine (ncp_disco) database to configure the general options for
the discovery process, and to track the discovery process.
The Discovery engine database, disco, is defined in $NCHOME/etc/precision/
DiscoSchema.cfg.
disco.agents table
The agents table specifies the discovery agents that ncp_disco uses for the
discovery. Every agent that you want to run must have an insertion into the
disco.agents table within the DiscoAgents.cfg configuration file that enables that
agent (set m_Valid=1). If m_Valid=0, the agent is not run.
© Copyright IBM Corp. 2006, 2017
293
Table 45. disco.agents database table schema
Column name
Constraints
m_AgentClass
Data type
Description
Integer
The category to which the current
discovery agent belongs:
v (0) Routing agent
v (1) Switch agent
v (2) Hub agent
v (3) ILMI agent
v (4) FDDI agent
v (5) PNNI agent
v (6) Frame Relay agent
v (7) CDP agent
v (8) NAT agent
m_AgentName
v PRIMARY
KEY
Text
The unique name of the discovery agent.
Integer
The level of debugging for the agent.
v NOT NULL
m_DebugLevel
Defines what signal to use to stop the
agent. This property can be used if
directed by IBM Support, but is not
defined in the DiscoSchema.cfg table.
m_EndSignal
m_HostName
Text
The name of the host machine on which
to run the agent.
m_IsIndirect
Integer
A flag indicating the type of connectivity
information returned by the discovery
agent:
v (0) Direct connectivity; for example,
Routing agents
v (1) Indirect connectivity information;
for example, Switch agents
m_LogFile
Text
The text file to which debugging output
is written.
m_Precedence
Integer
An integer representation of the
precedence level of the information
returned by the discovery agent; the
higher the integer, the higher the
weighting given to the information
returned.
The precedence is only used when there
is a conflict when merging device
information to produce the
workingEntities.finalEntity database
table.
m_MessageLevel
Text
Specifies the message level (the default is
warn). Options include:
v debug
v info
v warn
v error
v fatal
294
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 45. disco.agents database table schema (continued)
Column name
Constraints
Data type
Description
m_NumThreads
Integer
The number of threads this agent runs. If
not specified, the default number is 10;
the maximum allowed is 900.
m_Valid
Integer
A flag determining whether or not the
discovery agent is to be used:
v (1) Run the discovery agent
v (0) Do not run the discovery agent
Integer
m_ValidOnPartial
Specifies whether the agent is to be used
on a partial discovery:
v 0: Agent is not to be used in a partial
discovery.
v 1: Agent is to be used in a partial
discovery.
The disco.agents table also indicates agent precedence, which can be used when
merging device information to produce the workingEntities.finalEntity table.
Precedence determines which records are used when duplicate or conflicting
records are reported by different discovery agents.
The following precedence applies:
v The Details agent has the lowest precedence because it is designed to retrieve
only basic device information.
v Routing agents have the next highest precedence. Their connectivity information
is at the IP layer only, however, so it is not as accurate as that returned by the
switching agents.
v Switching agents have next-highest precedence because they can return
information on the media layer (layer 2), which is more accurate than layer 3
information.
Related reference:
“Discovery agent definition files” on page 59
The discovery agent definition files define the operation of the discovery agents.
“DiscoAgents.cfg configuration file” on page 62
The DiscoAgents.cfg configuration file defines which agents run during a
discovery.
disco.config table
The config table configures the general operation of the discovery process.
Table 46. disco.config database table schema
Column name
m_AddIntDisplayLabel
Constraints
Data type
Description
Boolean
Integer
Specifies whether to add an interface display
label:
v 0: Do not add an interface display label.
v 1: Add an interface display label.
Appendix A. Discovery databases
295
Table 46. disco.config database table schema (continued)
Column name
Constraints
Data type
Description
m_AllowVirtual
Default = 1
Integer
Flag indicating whether to allow virtual IP
addresses as part of the discovery.
v 0: Do not perform any discovery for virtual
IP addresses.
v 1: Perform discovery for virtual IP
addresses. This is the default setting.
v 2: Perform discovery for virtual IP
addresses only if the address is defined in
the scope.special table. This table defines
management IP addresses.
m_BuildLogicalCollections
Boolean
Integer
Specifies whether to build logical collection
entities to group together items such as VTP
domains, OSPF areas, and MPLS VPNs:
v 0: Do not build logical collection entities.
v 1: Build logical collection entities.
m_CheckFileFinderReturns
Externally
defined
Boolean data
type
Boolean
Integer
Flag indicating whether to use the Ping finder
to check the devices specified in the flat file
supplied to the File finder.
v 1: This setting tells the Ping finder to check
the devices specified in the flat file supplied
to the File finder. This setting is
recommended if you have reason to doubt
that some of the devices specified in the flat
file are still connected to the network.
default = 0
v 0: This setting indicates that you do not
want to perform any checking of the
devices specified in the flat file supplied to
the File finder.
m_CycleLimit
m_CreateStchrEvents
Integer
Externally
defined
Boolean data
type
Boolean
Integer
296
Specifies whether to create discovery events to
be sent to the ObjectServer. This field takes the
following values:
v 0: Do not generate discovery events.
v 1: Generate discovery events.
default = 1
m_CustomIntNaming
The number of discovery cycles to complete
before instigating a full rediscovery (used by
the FinalPhase stitcher).
Boolean
Integer
IBM Tivoli Network Manager IP Edition: Discovery Guide
Changes the default naming convention for
discovered interfaces. If you change the
default naming convention for discovered
interfaces, you must change the
BuildInterfaceName stitcher to specify your
naming convention.
Table 46. disco.config database table schema (continued)
Column name
m_DirScanIntvl
Constraints
Data type
Description
Integer
The time period between scans for
modifications to the stitcher and agent files.
If changes are found, the stitcher and agent
definitions are loaded and the appropriate
changes are made to the stitchers and agents.
m_DiscoProfiling
Boolean
Integer
Flag indicating whether to profile the
discovery.
v 1: Profile the discovery.
v 0: Do not profile the discovery.
m_DiscoOnStartup
Boolean
Integer
Specifies whether a discovery should
automatically start when the Discovery engine,
ncp_disco, is started:
v 0: Do not automatically start a discovery.
v 1: Automatically start a discovery.
m_DisplayMode
Integer
Specifies how the display label used for GUI
network and network hop views should be
populated for main nodes.
v 0 - Use Entity Name (default)
v 1 - Use SysName. This option is useful
when it is not desirable to name entities by
sysName in the database (see
m_UseSysName) but it is desirable to have
the entities displayed in the GUI views with
a sysName.
Appendix A. Discovery databases
297
Table 46. disco.config database table schema (continued)
Column name
Constraints
Data type
Description
m_FeedbackCtrl
Default = 0
Integer
Flag indicating whether to use the feedback
mechanism during the discovery. The feedback
mechanism allows any new IP addresses to be
fed back into the discovery and thus increases
the size of the discovered network. Devices
that are fed back are pinged by the Ping
finder.
Note: For feedback to work the ping finder
must be activated.
v 0: Feedback is off for all discoveries and
rediscoveries. This option provides speed
but discovers only those devices specified to
the finders, and hence provides an
incomplete topology. However, this setting
ensures that discoveries and rediscoveries
complete in the quickest possible time.
v 1: Feedback is on for full discoveries, full
rediscoveries, and partial rediscoveries. All
IP addresses are pinged. This option
provides a complete topology in all
situations but takes the longest.
v 2: Feedback is on for full discoveries and
full rediscoveries, this ensuring a complete
topology in these cases. In the case of
partial rediscoveries there is no feedback.
This ensures that the partial rediscovery
runs in the quickest time possible. This is
the default setting.
m_FindersOnStartup
Boolean
Integer
Specifies whether the finders should
automatically start when the Discovery engine,
ncp_disco, is started :
v 0: Do not automatically start finders.
v 1: Automatically start finders.
m_EnableCrossDomainProcessing
m_InferCEs
Externally
defined
Boolean data
type
Boolean
Integer
Set to 1 to enable cross-domain processing. If
you are performing a cross-domain discovery,
you must perform other configuration steps in
addition.
Boolean
Integer
Flag indicating whether to infer the existence
of customer-edge (CE) routers. When enabled,
DISCO creates a CE router entity for each
provider-edge (PE) router interface that is on a
/30 subnet and does not have CE information
from another source.
default = 0
v 1: This setting tells DISCO to infer the
existence of CE routers.
v 0: This setting tells DISCO not to infer the
existence of CE routers.
298
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 46. disco.config database table schema (continued)
Column name
Constraints
m_InferPEsUsingBGP
Data type
Description
Boolean
Integer
Specifies whether to infer the existence of
provider-edge (PE) routers using BGP
information on customer-edge (CE) routers:
v 0: Do not infer PEs.
v 1: Infer PEs.
m_ManagedWaitTimeOut
Integer
Applicable when the value of the field
m_WaitForManagedProcs is set to 1. Maximum
time to wait for all collectors to complete
retrieving data from their EMSs. Effectively a
fail-safe mechanism to cover the siutation
where one of the collectors never completes
processing.
By default, this value is set to 0, which means
wait indefinitely.
m_MinResidentSize
Integer
The minimum initial size of DISCO in
kilobytes (KB). The maximum value that you
can specify is 500 MB (512 000 KB).
Specifying an initial value speeds up the
discovery by allocating the memory of DISCO
in one block.
m_ModelVlans
Externally
defined
Boolean data
type
Boolean
Integer
Flag indicating whether to switch off VLAN
modelling.
1: This setting switches on VLAN modelling.
When you make this setting, the
AddGlobalVlans, CreateTrunkConnections and
AddVlanContainers stitchers are called.
0: This setting switches off VLAN modelling.
When you make this setting, the
AddGlobalVlans, CreateTrunkConnections and
AddVlanContainers stitchers are not called.
m_NothngFndPeriod
Float
The maximum time lapse, in seconds, between
the discovery of one device and the discovery
of the next device in the device discovery
phase.
Appendix A. Discovery databases
299
Table 46. disco.config database table schema (continued)
Column name
Constraints
Data type
m_OspfPidNaming
Default=0
Integer
Description
Fix Pack 2
Defines whether OSPF process IDs
(PIDs) are used when naming and creating
OSPF-related entities. Leave this setting at the
default (off) unless your network has a
meaningful OSFP process ID allocation policy
and you are running discovery agents capable
of discovering process IDs from the target
devices.
The possible options are the following:
0 - (default)
Do not use PIDs when naming OSPF
entities.
1 - Name OSPF Areas by PID
Use PID and area ID when creating
and naming area entities. Areas
collect interfaces with the same
domain, area and PID.
2 - Name OSPF domains and Areas by PID
Use PID and area ID when creating
and naming area entities. Areas
collect interfaces with the same
domain, area and PID. Create
per-process ID OSPF routing domains
in addition to the standard
PID-agnostic domains. Per-PID
domains collect only areas with the
required PID.
m_PendingPerCent
m_PingVerification
Integer
Default = 2
Integer
The maximum allowed ratio of pending
devices to processing devices. A breach of this
threshold condition instigates a full discovery
(rather than a partial rediscovery).
Option to check whether an interface is able to
be pinged. If the device is not pingable, then
Network Manager does not poll the device for
alerts
v 0: Do not check pingability: Network
Manager performs no pingability check on
any of the interfaces discovered. Interfaces
will be polled regardless of whether they
are pingable at discovery time.
v 1: Check pingability: perform a pingability
check, following discovery, for every
interface discovered.
v 2: Determine best method: sets the
pollability flag for an interface based on
whether feedback was active during the
discovery..
300
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 46. disco.config database table schema (continued)
Column name
m_RebuildLayers
Constraints
Data type
Description
Externally
defined
Boolean data
type
Boolean
Integer
Flag indicating whether to rebuild topology
layers after partial rediscovery.
v 1: Rebuild the layers. After partial
rediscovery, topology layers stitchers are
run. Partial rediscovery takes longer but
results in a complete topology.
v 0: Do not rebuild the layers. After partial
rediscovery, topology layers stitchers are not
run. The result is a much quicker partial
discovery; however, connectivity associated
with the newly discovered device is not
fully seen in the topology.
m_RediscoverRelatedDevices
Boolean
Integer
In a partial rediscovery when a device has
changed, specifies whether to rediscover the
related devices if the connection appears to
have changed:
v 0: Do not rediscover the related devices if
the connection appears to have changed.
v 1: Rediscover the related devices if the
connection appears to have changed.
m_RefreshDiscovery
Default = 1
Boolean
Integer
Specifies whether the FullDiscovery stitcher
restarts the discovery when called after an
initial full discovery has completed. The
default value is 1: restart the discovery
process. Set the value to 0 to not restart the
discovery process using the
RestartDiscoProcess.stch stitcher.
Haying this option enabled by default is is
useful for the following reasons:
v If the discovery is loading custom data into
the DiscoContrib.cfg file then this option
facilitates the process by having the new
discovery process read the file again.
v The option also helps if the discovery
process is accumulating memory because
the newly started process resets the process
to the initial state
Note: The FullDiscovery stitcher only stops
and starts the discovery process if there is no
discovery in progress at the time it is called.
m_RestartAgents
m_RestartFinders
Integer
Integer
A flag that determines whether DISCO
attempts to restart discovery agents that fail
during their operation.
Flag to determine whether to restart a failed
finder.
Appendix A. Discovery databases
301
Table 46. disco.config database table schema (continued)
Column name
Constraints
m_RTVPNResolution
Data type
Description
Integer
Specifies whether to apply fine control over
Layer 3 VPN resolution and naming in a route
target-based discovery:
v 1: Use route target.
v 2: Use VRF (default).
m_SubnetFiltering
Integer
Alters which interfaces are included in
subnet-based connections:
v 0: No filtering
v 1: Filter out VRF interfaces (consider using
m_VpnASTagging instead of this mode as it
improves connectivity in all layers rather
than just layer 3).
v 2 - Filter out in-scope interfaces known to
hold inaccessible duplicate IPs.
v 3 - Automatic. Decides best approach based
on other configuration options.
m_UseIfIndex
Boolean
Integer
Specifies whether to name interfaces using the
ifIndex only. This setting overrides the
m_UseIfName setting.
v 0: Do not name interfaces using the ifIndex
only.
v 1: Name interfaces using the ifIndex only.
m_UseContext
Boolean
Integer
Flag indicating whether this is a
context-sensitive discovery.
v 1: Specifies a context-sensitive discovery.
v 0: Specifies that this is not a
context-sensitive discovery.
m_UseIPName
Externally
defined
Boolean data
type
Boolean
Integer
Externally
defined
Boolean data
type
v 1: Uses the IP address for device naming.
v 0 (default): Does not use IP address for
device naming. Instead, the DNS name is
used where available.
default = 0
m_UseIfName
Flag to indicate which naming strategy to use
for devices.
Boolean
Integer
default = 0
Flag indicating which naming strategy to use
when building interfaces.
v 1: This setting indicates that you want to
use ifName or ifDescr to name the
interfaces rather than their ifIndex, card or
port information.
v 0: This setting indicates that you want to
use the default naming convention for any
device interface:
baseName[<card>[<port>]
302
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 46. disco.config database table schema (continued)
Column name
Constraints
Data type
Description
m_UseSysName
Externally
defined
Boolean data
type
Boolean
Integer
Flag indicating which naming strategy to use
when naming devices.
v 1: This setting indicates that you want to
name devices using the value of the SNMP
sysName variable as the main source of
naming information. The sysName variable
must be set and must be unique within the
network.
default = 0
v 0: This setting indicates that you do not
want to name devices using the value of the
SNMP sysName variable as the main source
of naming information.
m_VerifyCDPUsingDeviceId
Boolean
Integer
Specifies whether to verify the CDP links
using the CDP device ID. Occasionally the
CDP device ID has been found to be
unreliable. Switching on
m_VerifyCDPUsingDeviceId will improve CDP
connectivity if the Device ID is accurate but
might degrade connectivity if the Device ID is
inaccurate.
v 0: Do not verify the CDP links using the
CDP device ID.
v 1: Verify the CDP links using the CDP
device ID.
m_VpnASTagging
Integer
Specifies whether CE facing PE interfaces
should be assigned to a private address space:
v 0: Do not assign.
v 1: Assign.
v 2: Automatic. Decides the best approach
based on other configuration options.
m_WaitForManagedProcs
Boolean
Integer
Flag indicating whether to tell the discovery
engine ncp_disco wait until the Collector
finder status is complete before moving to the
next phase of discovery.
v 1: Wait until the Collector finder status is
complete before moving to the next phase
of discovery. Setting
m_WaitForManagedProcs = 1 when running
a multiple collector discovery forces the
discovery process to remain in phase 1 until
all the collectors have completed data
processing on their respective EMSs.
v 0: Do not wait until the Collector finder
status is complete before moving to the next
phase of discovery.
When this field is set to 1, then the parameter
m_ManagedWaitTimeOut defines the maximum
time to wait for all collectors to complete
retrieving data from their EMSs.
Appendix A. Discovery databases
303
Table 46. disco.config database table schema (continued)
Column name
m_WriteTablesToCache
Constraints
Data type
Description
Externally
defined
Boolean data
type
Boolean
Integer
Flag indicating whether to write a cache of the
Discovery engine, ncp_disco, tables to disk.
Note: Setting this flag results in discoveries
that are slower than a standard discovery.
v 1: Write cache of ncp_disco tables to disk.
The tables that are defined in the failover
database are cached and ncp_disco can be
restarted at any point.
v 0: Do not write cache of ncp_disco tables to
disk. No tables are cached during the
discovery and ncp_disco ignores any
existing cache files if it is restarted.
m_UnmanagedSubInts
Boolean
Integer
Flag indicating whether to automatically set
sub-interfaces to unmanaged when the parent
interface is marked as unmanaged by the
PopulateDNCIM_ManagedStatus.stch stitcher.
v 1: Automatically set sub-interfaces to
unmanaged if the parent interface is set to
unmanaged by the stitcher.
v 0: Do not automatically set sub-interfaces to
unmanaged.
Related tasks:
“Defining the scope of an MPLS/VPN discovery” on page 192
When configuring the discovery of one or more Virtual Private Networks ( VPNs )
running across an MPLS core, you can restrict the scope of this discovery to a
particular VPN name or VPN Routing and Forwarding (VRF) table name.
Related reference:
“DiscoConfig.cfg configuration file” on page 73
The DiscoConfig.cfg configuration file is used to have the Ping finder automatically
check the devices discovered by the File finder, and to enable a context-sensitive
discovery.
disco.convergedTopologies table
The convergedTopologies table stores information on how layers must be merged
by the discovery process.
Table 47. disco.convergedTopologies database table schema
Column name
Constraints
Data type
Description
m_TopologyName
v PRIMARY
KEY
Text
Name of the topology to be created from the
source topologies.
m_Order
Integer
Order in which to process this entry.
m_SourceTopologies
List of text
Topologies to be used in the merge, by order
of most accurate topology first.
v NOT NULL
304
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 47. disco.convergedTopologies database table schema (continued)
Column name
Constraints
m_RetainOverride
Data type
Description
Boolean
Integer
Controls whether the override flags found in
the source topologies are to be put into the
merge topology. This value is only relevant
when the merged topology is going to be used
as a source topology in another merged
topology.
v 0: Do not copy override flags.
v 1: Copy override flags.
m_UseContainment
Boolean
Integer
Provides fine control over whether interface
containment information is taken into
consideration when merging this particular
topology.
v 0: Do not try to use containment to refine
links.
v 1: Allow links on interfaces higher in the
containment to be overridden by any links
on interfaces lower down; that is, more
physical interfaces.
disco.dynamicConfigFiles table
The dynamicConfigFiles table stores the names of configuration files that must be
reread each time a full discovery is launched.
Table 48. disco.dynamicConfigFiles database table schema
Column name
Constraints
Data type
Description
m_Name
Primary key
Text
Name of configuration file to be reread,
Timestamp
Last update time for this configuration file.
Not null
m_UpdTime
disco.events table
The events table constrains discovery events generated to a standard format. An
event is generated by inserting a record into this table.
Table 49. disco.events database table schema
Column name
Constraints
Data type
Description
m_EventName
Not null
Text
The name of the event.
m_EntityName
Not null
Text
The name of the entity on which the event
occurred.
m_EventType
Not null
Integer
This field can take one of the following values:
v 1: Problem
v 2: Resolution
v 13: Informational
Appendix A. Discovery databases
305
Table 49. disco.events database table schema (continued)
Column name
Constraints
Data type
Description
m_Severity
Not null
Integer
This field can take one of the following values:
v 0: CLEAR
v 1: INDETERMINATE
v 2: WARNING
v 3: MINOR
v 4: MAJOR
v 5: CRITICAL
It is possible to define more values.
m_Description
Not null
m_ExtraInfo
Externally
defined vblist
data type
Text
Description of the discovery event
Specifies a list of additional information.
Related concepts:
“Process flow for creating discovery events” on page 262
Discovery events are created during the discovery process showing the progress of
agents, stitchers, and finders. These events are sent to and stored in Tivoli
Netcool/OMNIbus and can be viewed using the Web GUI.
disco.filterCustomTags table
The filterCustomTags table stores custom tags, which can be associated with a
filtered set of discovered entities during the discovery and used to perform custom
visualization and polling tasks.
Table 50. disco.filterCustomTags database table schema
Column name
m_Filter
Constraints
Data type
Description
Text
Filter definition that extracts a set
of IP address to which the
name-value pair tags in the
m_CustomTags is to be associated to.
You can create a filter based on any
attributes associated with
discovered entities. For example,
you could apply the following
filters:
v Filter based on entity IP address:
"m_UniqueAddress LIKE
’172.20.3’"
v Filter based on entity name:
"m_Name LIKE ’lon’"
v Filter based on VLAN identifier
of a VLAN entity:
"m_LocalNbr->m_VlanID = 102"
m_StitcherTagName
Text
Name of a tag to be evaluated
using the GetTagStitcher.stch
stitcher.
m_CustomTags
Object type vblist
List of name-value pair tags.
306
IBM Tivoli Network Manager IP Edition: Discovery Guide
disco.ipCustomTags table
The ipCustomTags table stores custom tags, which can be associated with unique
discovered entities during the discovery and used to perform custom visualization
and polling tasks.
Table 51. disco.ipCustomTags database table schema
Column name
Constraints
Data type
Description
m_UniqueAddress
Text
IP address to which the name-value
pair tags in the m_CustomTags is to be
associated to.
m_StitcherTagName
Text
Name of a tag to be evaluated using
the GetTagStitcher.stch stitcher.
m_CustomTags
Object type vblist
List of name-value pair tags.
disco.managedProcesses table
The managedProcesses table is a repository for all the subprocesses managed by
DISCO, such as the finders. Provided that CTRL is running, processes that are
inserted into this table are started and managed by DISCO.
Table 52. disco.managedProcesses database table schema
Column name
Constraints
Data type
m_Name
v PRIMARY KEY Text
v UNIQUE
Description
The name of the process to be
managed.
v NOT NULL
m_Args
List of text
A list of command-line arguments sent
to the executable.
m_Host
Text
The name of the host on which to run
the executable.
m_LogFile
Text
The name of the log file to which
output is written.
disco.NATStatus table
The NATStatus table is used to configure the discovery system to use NAT.
Table 53. disco.NATStatus database table schema
Column name
m_NATChecks
Constraints
Data type
Description
Integer
A counter for unresponsive NAT
Gateways that were configured for
discovery.
Important: Do not change the value of
this field unless you are advised to do
so by IBM Software Support.
Appendix A. Discovery databases
307
Table 53. disco.NATStatus database table schema
(continued)
Column name
Constraints
Data type
Description
m_NATStatus
v UNIQUE
Integer
This column is populated automatically
by the discovery process, and can be
used to track the process of a NAT
discovery. To make inserts into this
table, set the value to 0. Possible values
are as follows:
v NOT
NULL
v 0: Uninitialized
v 1: Seeded discovery with gateways
v 2: Awaiting gateway returns
v 3: Processing NAT translations
v 4: NAT translations complete
m_UsingNAT
v UNIQUE
v NOT
NULL
Boolean integer Indicates whether the discovery uses
multiple address spaces. If the discovery
uses multiple address spaces, set the
value to 1. If not, set the value to 0.
disco.profilingData table
The profilingData table is used by the discovery profiling stitchers to record data
associated with time and memory expended during the discovery.
Table 54. disco.profilingData database table schema
Column name
Constraints
Data type
Description
m_AgentData
List
For each agent that ran during the
discovery, provides a brief summary of
the work performed by that agent
during the discovery.
m_CompletionMem
64-character string
Memory used when phase -1 of the
discovery completed.
m_CompletionTime
Integer
Time that phase -1 completed.
m_DiscoveryMode
Integer
Type of discovery:
v 0: Full discovery
v 1: Partial discovery
m_NumDetailsReturns
Integer
Total number of details table returns
during the discovery.
m_NumEntities
Integer
Total number of entities in the dNCIM
database based on the count of NCIM
topology database entityData table
records for the domain.
m_NumFinderInserts
Integer
Total number of finder inserts during
the discovery.
m_NumMainNodes
Integer
Total number of main nodes
discovered.
m_NumMainNodesWithAccess
Integer
Total number of main nodes with
SNMP access discovered.
m_NumIPs
Integer
Total number of IP addresses
discovered.
m_NumRouters
Integer
Total number of routing devices
discovered.
308
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 54. disco.profilingData database table schema (continued)
Column name
Constraints
Data type
Description
m_NumSwitches
Integer
Total number of switches discovered.
m_Phase1StartMem
64-character string
Memory used when phase 1 of the
discovery started.
m_Phase1StartTime
Integer
Time that phase 1 of the discovery
started. Phase 1 is also known as the
Interrogating Devices phase.
m_Phase2StartMem
64-character string
Memory used when phase 2 of the
discovery started.
m_Phase2StartTime
Integer
Time that phase 2 of the discovery
started. Phase 2 is also known as the
Resolving Addresses phase.
m_Phase3StartMem
64-character string
Memory used when phase 3 of the
discovery started.
m_Phase3StartTime
Integer
Time that phase 3 of the discovery
started. Phase 3 is also known as the
Downloading Connections phase.
m_ProcPhaseStartTime
Integer
Time that phase -1, the data processing
phase of the discovery started. Phase -1
is also known as the Correlating
Connections phase.
m_ProcPhaseStartMem
64-character string
Memory used when phase -1 of the
discovery started.
m_SoftwareVersion
Text
Software version used.
m_StitcherData
List
For each stitcher that ran during the
discovery, provides information on
how long the stitcher ran for, and how
many times it was executed during the
discovery. This enables the
identification of problem stitchers
during a discovery.
disco.status table
Use the disco.status table to monitor the progress of the ncp_disco process during
the discovery process.
Attention: The disco.status table is used and updated internally, and you must
not make inserts into this table.
Table 55. disco.status database table schema
Column name
Constraints
Data type
m_BlackoutState
Externally
Boolean
defined
Integer
Boolean data
type
Description
Flag to show if the discovery
process is in Blackout mode, that
is, whether or not DISCO is
accepting new devices from the
finders in the current discovery
cycle:
v 0: False (accepting new devices)
v 1: True (not accepting new
devices)
Appendix A. Discovery databases
309
Table 55. disco.status database table schema (continued)
Column name
Constraints
m_CycleCount
Data type
Description
Integer
Current® rediscovery cycle, that is,
the current number of cycles
DISCO has been through without
actually building a topology.
In rediscovery mode, DISCO only
builds a topology at the end of the
last cycle (the last cycle is
determined by the fact that there
is nothing left in finders.pending
awaiting processing).
m_DiscoveryCycle
Requested
Externally
Boolean
defined
Integer
Boolean data
type
Flag to indicate that a discovery
has been requested by the GUI.
m_DiscoveryCycle
RequestTime
Integer
The time that the discovery was
requested, in Unix time.
m_DiscoveryMode
Integer
The present discovery mode:
v 0: Full discovery
v 1: Partial discovery
m_ForcedLayerRebuild
m_FullDiscovery
Boolean
Integer
Externally
Boolean
defined
Integer
Boolean data
type
Flag that indicates whether a
'false' value of the
disco.config.m_RebuildLayers
column has been overridden for
the current discovery cycle. The
default value is 0.
Flag to indicate that the
FullDiscovery.stch stitcher has
been called during the discovery.
If the stitcher is called, the flag is
set to 1 to ensure that the
FullDiscovery.stch stitcher is
executed when the current
discovery finishes (thus starting
another full discovery).
If the flag is set to any other
value, no action is taken.
310
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 55. disco.status database table schema (continued)
Column name
m_Phase
Constraints
Data type
Description
Integer
The current phase within the
present discovery cycle. During
the data collection stage, the
phases are as follows:
v 0: The discovery has not yet
started.
v 1: The main discovery phase in
which device data is retrieved.
Most discovery agents complete
in this phase.
v 2 - n: The phases in which the
topology data is retrieved for
the currently discovered objects.
The number of phases required
depends on how your discovery
is configured. By default, in a
layer 2 discovery, phase 2
consists of the retrieval of IP to
MAC address translations and
phase 3 consists of the retrieval
of Ethernet switch topology
information.
During the data processing
stage, the following phase is
undertaken.
v 3: The phase in which the
collected data is processed; the
layers are built and the data is
sent to MODEL.
More detailed information about
the discovery phases can be found
in “Discovery stages and phases”
on page 425.
m_ProcessingNeeded
Externally
Boolean
defined
Integer
Boolean data
type
Flag to indicate whether the
current topology needs
reprocessing. This flag is checked
when DISCO is in rediscovery
mode in order to determine
whether any newly found devices
(that are now in the
finders.pending table) necessitate
the reprocessing of the entire
topology:
v 0: The topology does not need
reprocessing
v 1: The topology needs
reprocessing
Appendix A. Discovery databases
311
disco.tempData table
The tempData table is used by the discovery profiling stitchers to record the time
and memory expended to perform the discovery.
Table 56. disco.tempData database table schema
Column name
Constraints
Data type
Description
m_Phase1TmpTime
Integer
Time taken by phase 1 of the discovery,
also known as the Interrogating Devices
phase.
m_Phase2TmpTime
Integer
Time taken by phase 2 of the discovery,
also known as the Resolving Addresses
phase.
m_Phase3TmpTime
Integer
Time taken by phase 3 of the discovery,
also known as the Downloading
Connections phase.
m_ProcPhaseTmpTime
Integer
Time taken by phase -1, the data processing
phase of the discovery, also known as the
Correlating Connections phase.
m_Phase1TmpMem
64-character string
Memory used during phase 1 of the
discovery.
m_Phase2TmpMem
64-character string
Memory used during phase 2 of the
discovery.
m_Phase3TmpMem
64-character string
Memory used during phase 3 of the
discovery.
m_ProcPhaseTmpMem
64-character string
Memory used during phase -1 of the
discovery.
Example configuration of the disco.agents table
This example uses OQL commands to insert configuration values into the
disco.agents table.
v The ArpCache discovery agent is enabled to run during the discovery
(m_Valid=1), belongs to the routing class (m_AgentClass=0), returns direct
connectivity information (m_IsIndirect=0) and has a precedence level of 2.
v The AtmForumPnni discovery agent is disabled for this discovery (m_Valid=0),
belongs to the PNNI class (m_AgentClass=5), returns direct connectivity
information (m_IsIndirect=0) and has a precedence level of 5.
v The BayEthernetHub discovery agent is disabled for this discovery (m_Valid=0),
belongs to the hub class (m_AgentClass=2), returns indirect connectivity
information (m_IsIndirect=1) and has a precedence level of 3.
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’ArpCache’, 1, 0, 0, 2
);
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
312
IBM Tivoli Network Manager IP Edition: Discovery Guide
’AtmForumPnni’, 0, 5, 0, 5
);
insert into disco.agents
(
m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence
)
values
(
’BayEthernetHub’, 0, 2, 1, 3
);
Example configuration of the disco.config table
This example uses OQL commands to insert configuration values into the
disco.config table.
v The maximum period between device discovery is 300 seconds. This condition
and the next condition must be satisfied in order to proceed to the next phase of
the discovery cycle.
v The maximum allowable ratio of pending to processing devices is 20 percent. If
this threshold is breached, a full discovery is instigated.
v The cycle limit is 5, which means that a maximum of five discovery cycles are
necessary to complete the discovery process. If there are more than 5 discovery
cycles, a full rediscovery is initiated.
v The agent restart flag is 1, which means that DISCO is mandated to restart any
discovery agent that fails in its operation.
v The finder restart flag is 1, which means that DISCO is mandated to restart any
finder that fails in its operation.
v Scans for updates to the agents and stitchers have been disabled. This is usually
the case when you do not wish to alter the discovery data flow.
v Do not write a cache of the Discovery engine, ncp_disco, tables to disk.
insert into disco.config
(
m_NothngFindPeriod,
m_PendingPerCent,
m_CycleLimit,
m_RestartAgents,
m_RestartFinders,
m_DirScanIntvl,
m_WriteTablesToCache
)
values
(
300,
20,
5,
1,
1,
0,
0
);
Appendix A. Discovery databases
313
Example configuration of the disco.managedProcesses table
This example uses OQL commands to insert configuration values into the
disco.managedProcesses table. If the CTRL program is running, you can configure,
launch, and manage the File finder and Ping finder subprocesses.
insert into disco.managedProcesses
(
m_Name, m_Args, m_Host
)
values
(
"ncp_df_file", [ ], "othello"
);
insert into disco.managedProcesses
(
m_Name, m_Args, m_Host
)
values
(
"ncp_df_ping", [ ], "othello"
);
Discovery scope database
The scope database limits the extent or reach of a discovery. Using the scope
database, you can configure a range of protocols and attributes that define zones
that are to be included or excluded from the discovery process.
The range of IP addresses and devices that can potentially be considered by the
discovery process is unlimited, so unless you restrict the scope of the discovery,
ncp_disco would eventually attempt to discover the entire Internet.
For example, you can specify that sensitive devices not be discovered and
consequently not be instantiated. A sensitive device is one that you do not want to
poll. This might be because there is a security risk involved in polling the device,
or that polling might overload device.
Related reference:
“DiscoScope.cfg configuration file” on page 75
The DiscoScope.cfg configuration file can be used to configure the scope of a
discovery.
disco.scope database schema
The scope database is defined in $NCHOME/etc/precision/DiscoSchema.cfg and
$NCHOME/etc/precision/DiscoScope.cfg. Its fully qualified database table names
are: scope.zones; scope.detectionFilter; scope.instantiateFilter; scope.special.
314
IBM Tivoli Network Manager IP Edition: Discovery Guide
scope.detectionFilter table
If you specify a filter in the detectionFilter table, only devices matching it are
discovered.
Table 57. scope.detectionFilter database table schema
Column
name
Constraints
m_Filter
Data type
Description
Text
A textual representation of an attribute
filter against the columns of the
Details.returns table; for example,
m_UniqueAddress or m_ObjectId.
Although you can configure the filter condition to test any of the columns in the
Details.returns table, when filtering IP devices you might need to use the IP
address as the basis for the filter if you need to restrict the detection of a particular
device. If the device does not grant SNMP access to the Details agent, the Details
agent might not be able to retrieve MIB variables such as the Object ID. However,
you are guaranteed the return of at least the IP address when the device is
detected.
scope.inferMPLSPEs table
Use the scope.inferMPLSPEs table when enabling inference of inaccessible
provider-edge (PE) devices by using the BGP data on the customer-edge (CE)
devices. This table enables you to optionally specify which zones to process to
determine which of the inferred PE devices are valid devices.
To specify which zones to process to determine which of the inferred PE devices
are valid devices populate the scope.inferMPLSPEs table, using standard format
scope entries, as in the scope.zones table. Use this option when you have
inaccessible devices that are connected by means of BGP but which are not actually
PE devices.
If the following conditions are true, then the system creates a “third-party”
network object to model this inaccessible provider network.
v A router is within this scope
v The router has BGP peers outside the discovered network
v m_InferMPLSPEsUsingBGP is on. This can also be defined using the Advanced
tab on the Discovery Configuration GUI.
Table 58. scope.inferMPLSPEs database table schema
Column name
Constraints
m_Protocol
v PRIMARY KEY Integer
v NOT NULL
v Externally
defined
netProtocol
data type
Data type
Description
An integer representation of the IP
protocol used by the
presently-defined zone:
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
Appendix A. Discovery databases
315
Table 58. scope.inferMPLSPEs database table schema (continued)
Column name
Constraints
Data type
Description
m_Action
v NOT NULL
Integer
Action to perform for current zone:
v 0: Undefined
v Externally
defined
filtAction data
type
m_Zones
NOT NULL
v 1: Include
v 2: Exclude
List of type
zone
A list of varbinds (name=value)
that define the present discovery
zone.
Only process interfaces in the 199.220.* network
The following example shows how to instruct the system to only process interfaces
in the 199.220.* network.
insert into scope.inferMPLSPEs
(
Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[ { m_Subnet = "199.220.*" } ]
);
scope.instantiateFilter table
When you specify a filter in the instantiateFilter table, only devices that pass the
criteria are instantiated, that is, sent to the DNCIM database. If no filter is
specified, all discovered devices are instantiated.
Note that because the m_Protocol column must be unique, there must be only one
insert into this table for any given protocol. Multiple filters must be defined within
a single insert.
316
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 59. scope.instantiateFilter database table schema
Column name
Constraints
m_Filter
Data type
Description
Text
A textual representation of an attribute filter against
the columns of the ncimCache database.
The following example insert prevents instantiation
of an interface:
insert into scope.instantiateFilter
(
m_Filter
)
values
(
"
(
BASENAME != ’jane’
OR
(
BASENAME = ’jane’
AND
networkInterface->IFINDEX != 1
)
)
"
);
Related reference:
“workingEntities.finalEntity table” on page 385
The finalEntity table is a central repository for information about discovered
entities.
scope.mplsTe table
The scope.mplsTe table defines the scope of MPLS Traffic Engineered (TE) tunnel
discovery, and defines what information is retrieved.
The following table shows the schema of the scope.mplsTe table.
Table 60. scope.zones database table schema
Column name
Constraints
Data type
Description
m_Protocol
v NOT NULL
Integer
An integer representation of the IP
protocol used by the
presently-defined zone:
v Externally
defined
netProtocol
data type
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
m_Zones
m_AddressSpace
NOT NULL
List of type
zone
Defines the scope in which the
tunnel heads will be discovered
Text
Optional address space
Appendix A. Discovery databases
317
Table 60. scope.zones database table schema (continued)
Column name
Constraints
m_Mode
Data type
Description
Integer
The TE tunnel discovery mode
defines what information is
retrieved. Possible values are:
v 0: Unknown (not set)
v 1: Tunnel Head/Tail with Transit
Hop List
v 2: Tunnel Head/Tail (No Hop
List)
v 3: Tunnel Head, Tails, and Transit
devices
m_TunnelFilter
Integer
The TE tunnel filter. Possible values
are:
v 0: Unknown (not set)
v 1: Include tunnels with this head
v 2: Exclude tunnels with this head
Related tasks:
“Configuring the StandardMPLSTE agent” on page 191
Configure which tunnels to discover, and what details to retrieve.
scope.multicastGroup table
The scope.multicastGroup table defines which multicast groups to discover and
which details to retrieve from these groups.
The following table shows the schema of the scope.multicastGroup table.
Table 61. scope.multicastGroup database table schema
Column name
Data type
Description
m_AddressSpace
Text
Optional address space
m_GroupName
Text
Descriptive name for a group
list type zone
Zones defines the multicast
subnets to which the scope
options apply
Integer
IGMP Group discovery mode
m_Groups
Constraints
Not null
m_IGMPMode
v 0 - unknown (use default)
v 1 - Include group
v 2 - Exclude group
m_IPMRouteMode
Integer
IP Multicast Route Group
discovery mode:
v 0 - unknown (use default)
v 1 - Include group
v 2 - Exclude group
318
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 61. scope.multicastGroup database table schema (continued)
Column name
Constraints
m_PimMode
Data type
Description
Integer
The PIM multicast discovery
mode defines what information is
retrieved. Possible values are:
v 0: Unknown (use default)
v 1: Retrieve PIM group data
v 2: Do not retrieve PIM group
data. Groups with this option
applied will not be represented
in the PIM Service/End Point
data.
m_Protocol
v NOT NULL
Integer
An integer representation of the
IP protocol used by the
presently-defined zone:
v Externally
defined
netProtocol
data type
(Currently
IPv4 [1] only)
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
Related tasks:
“Configuring a multicast discovery” on page 43
Configure a multicast discovery by enabling the required agents and scoping the
discovery.
scope.multicastSource table
The scope.multicastSource table defines which IPM routes to discover. This is
particularly useful if you have multiple IPM route sources, since you can scope
multicast discovery by IPM route source to focus on the sources of interest.
The following table shows the schema of the scope.multicastSource table.
Table 62. scope.multicastSource database table schema
Column name
Constraints
Data type
Description
m_Protocol
v NOT NULL
Integer
An integer representation of the
IP protocol used by the
presently-defined zone:
v Externally
defined
netProtocol
data type
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
m_Source
NOT NULL
list type zone
The multicast source to be
included or excluded
Appendix A. Discovery databases
319
Table 62. scope.multicastSource database table schema (continued)
Column name
Constraints
m_IPMRouteMode
Data type
Description
Integer
An integer representation of the
network protocol used by the
presently defined group. The
following values are possible:
v IP Multicast Route Source
discovery mode
v 0 - unknown (use default)
v 1 - Include Source
v 2 - Exclude Source
m_Groups
list type zone
The multicast group subnets to
which the source scope option
applies
Related tasks:
“Configuring a multicast discovery” on page 43
Configure a multicast discovery by enabling the required agents and scoping the
discovery.
scope.special table
The special table defines management IP addresses. A management address is an
IP address on a device whose only role is to manage the device. Management
addresses do not handle network traffic.
Table 63. scope.special database table schema
Column name
Constraints
Data type
Description
m_Zones
NOT NULL
List of type
zone
A list of varbinds
(name=value) that define
the present discovery
zone. This takes the form
of a list of subnet IP
addresses and subnet.
m_AddressSpace
Text
Optional address space
identifier for a particular
scope entry.
m_Protocol
Integer
An integer representation
of the IP protocol used by
the presently-defined
zone:
v 1: IPv4
v 2: IPv4 that has been
through network
address translation
(NAT)
v 3: IPv6
m_OutOfBand
Int Type
Boolean
Indicates whether the
management area is out
of band. Takes one of the
following values:
v 0: in band
v 1: out of band
320
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 63. scope.special database table schema (continued)
Column name
Constraints
Data type
Description
m_IsManagement
Int Type
Boolean
Indicates whether the
address is a management
address.
m_IsValidVirtual
Int Type
Boolean
Indicates whether the
address is a valid virtual
IP.
m_Identifier
Text
Optional identifier for
tracking.
m_Priority
Int
Priority that is used if
there are multiple
matches. The
scope.special entry that
has the highest priority is
selected. This priority
must be set to at least 1.
m_NonPingable
Int
If set to 1, the address is
selected even if it cannot
be pinged.
m_AdminInterface
Int Type
Boolean
Indicates whether the
address is an interface.
m_ExtraInfo
Object type
vblist
Optional fields with
which the target entity
can be enriched.
scope.zones table
Use the zones table to define areas of the network to be either included or
excluded from the discovery process. A zone is typically defined as a list of
varbinds. Varbinds are name = value pairs.
You can define multiple zones, and you can combine inclusion and exclusion
zones. However, if you define a combination of inclusion and exclusion zones, the
exclusion zones must be within the scope of the inclusion zones.
Table 64. scope.zones database table schema
Column name
Constraints
Data type
m_Protocol
v PRIMARY KEY Integer
v NOT NULL
v Externally
defined
netProtocol
data type
Description
An integer representation of the IP
protocol used by the
presently-defined zone:
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
m_Action
v NOT NULL
v Externally
defined
filtAction data
type
Integer
Action to perform for current zone:
v 0: Undefined
v 1: Include
v 2: Exclude
Appendix A. Discovery databases
321
Table 64. scope.zones database table schema (continued)
Column name
Constraints
Data type
Description
m_Zones
List of type
zone
A list of varbinds (name=value)
that define the present discovery
zone.
m_AddressSpace
Text
The name of the NAT address
space to which the device belongs.
This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is NULL.
Example scope database configuration
The example OQL inserts into the scope database tables in this topic would be
appended to the DiscoScope.cfg configuration file to configure the ncp_disco
process when it starts.
Configuration of the scope.zones table
Use this information to understand how to configure the scope.zones table.
Creating two inclusion zones
This example configuration of the scope.zones table creates two inclusion zones for
the current discovery. Both zones are defined using a single insert.
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[
{
m_Subnet="172.16.1.0",
m_NetMask=24
},
{
m_Subnet="172.16.2.*"
}
]
);
The previous OQL insert specifies the following conditions:
v The network uses the Internet Protocol (m_Protocol=1).
v Any devices that fall into the present zone are to be included in the discovery
(m_Action=1).
v The discovery includes:
– Any device that falls within the 172.16.1.0 subnet (with a subnet mask of 24,
that is, 24 bits turned on and 8 bits turned off, which implies a netmask of
255.255.255.0).
– Any device with an IP address starting with 172.16.2, that is, in the 172.16.2.0
subnet with a mask of 255.255.255.0.
322
IBM Tivoli Network Manager IP Edition: Discovery Guide
Creating a zone within a zone
Zones can be specified within zones: within a given inclusion zone, you can
specify devices or subnets that are not to be detected. These devices are not pinged
by the Ping finder or interrogated by the discovery agents. For example, you can
define an include scope zone consisting of the Class B subnet 172.20.0.0/16, and
completely contained within that zone you can specify an exclude scope zone
consisting of the subnet 172.20.32.0/19. Finally, completely contained within the
exclude scope zone you could specify an include scope zone 172.20.33.0/24.
// Include all IP addresses in this range
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[{m_Subnet = ’172.20.0.0’, m_NetMask = 16 }]
);
// Apart from the IP addresses in this range
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
2,
[{m_Subnet = ’172.20.32.0’ , m_NetMask = 19 }]
);
// Except for these IP addresses which we do want to include
insert into scope.zones
(
m_Protocol,
m_Action,
m_Zones
)
values
(
1,
1,
[{m_Subnet = ’172.20.33.0’ , m_NetMask = 24 }]
);
The previous OQL insert specifies three scope zones:
v All zones specify that the network uses the Internet Protocol (m_Protocol=1).
v Include and exclude zones are defined as follows:
– Any devices that fall into the first zone, 172.20.0.0/16, are to be included in
the discovery (m_Action=1).
– Any devices that fall into the second zone, 172.20.32.0/19, which is
completely contained within the first zone, are to be excluded from the
discovery (m_Action=2).
– Any devices that fall into the third zone, 172.20.33.0/24, which is completely
contained within the second zone, are to be included in the discovery
(m_Action=1).
Appendix A. Discovery databases
323
Preventing the detection of devices with a filter
This example insert defines a detection filter. Since there must only be one insert
into the scope.detectionFilter table, multiple conditions for IP must be defined
using a single insert. The conditions of the filter can be combined using the
Boolean OQL keywords AND and OR.
insert into scope.detectionFilter
(
m_Protocol, m_Filter
)
values
(
1,
"(
( m_UniqueAddress <> ’10.10.63.234’ )
AND
( m_ObjectId not like ’1\.3\.6\.1\.4\.1\..*’ )
)"
);
The above example filter ensures that only the following are further interrogated
by the discovery:
v Devices that do not have the IP address 10.10.63.234.
v Devices that do not have the Object ID 1.3.6.1.4.1.*.
In the above example, the backslash (\) is used in conjunction with the not like
comparison to escape the . character, which would otherwise be treated as a
wildcard.
Restricting instantiation based on entity name
This example insert defines an instantiation filter, also known as a postdiscovery
filter. This example prevents the instantiation of devices that match a given entity
name.
The filter (m_Filter) uses topology data in the ncimCache format.
Note: To ensure that alerts are not raised for interfaces that are excluded by the
instantiation filter, you must set the RaiseAlertsForUnknownInterfaces variable. To
this, perform the following steps:
1. Edit the $NCHOME/etc/precision/NcPollerSchema.cfg configuration file.
2. Add the following line to the file:
update config.properties set RaiseAlertsForUnknownInterfaces = 0;
Restricting instantiation of a chassis based on entity name
The following example postdiscovery filter restricts instantiation of a chassis and
its contents.
insert into scope.instantiateFilter
(
m_Filter
)
values
(
"
(
BASENAME != ’jane’
)
"
);
324
IBM Tivoli Network Manager IP Edition: Discovery Guide
Restricting instantiation of mutiple chassis
The following example postdiscovery filter restricts instantiation of a chassis and
its contents.
insert into scope.instantiateFilter
(
m_Filter
)
values
(
"
(
snmpSystem->SYSDESCR NOT LIKE ’ device’
)
"
);
Access databases
There are several databases that control access to network devices: snmpStack
database and telnetStack database.
snmpStack database
The snmpStack database defines the operation of the SNMP helper.
Description
The snmpStack database in defined in the SnmpStackSchema.cfg file.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
snmpStack.accessParameters database table
The snmpStack.accessParameters database table configures the way that the SNMP
helper handles the retrieval of large non-scalar variables for particular devices or
subnets.
Description
Any values inserted into this table override the values for m_GetNextBoundary and
m_GetNextSlowDown that have been specified in the snmpHelper.configuration table.
Schema
The snmpStack.accessParameters database table schema is described in the
following table:
Appendix A. Discovery databases
325
Table 65. snmpStack.accessParameters database table schema
Column name
Constraints
Data type
Description
m_GeneralSlowDown
NOT NULL
Integer
The general amount by which to
delay a request (in milliseconds). A
general slow down must only be
used where absolutely necessary
as it can significantly increase the
overall discovery time.
m_GetNextBoundary
NOT NULL
Integer
When retrieving a particular
non-scalar SNMP variable from a
device, this is the minimum
number of GetNext requests to be
issued before the delay specified
by m_GetNextSlowDown is
introduced.
m_GetNextSlowDown
NOT NULL
Integer
The delay (in milliseconds) to
introduce between each SNMP
GetNext request when the number
of separate GetNext requests
issued while retrieving a particular
non-scalar SNMP variable exceeds
m_GetNextBoundary.
m_NetAddress
NOT NULL
Text
The IP address on which to
override the boundary and
slowdown values.
m_NetMask
Text
The netmask. If no netmask is
specified, m_NetAddress is taken to
be a single IP address. If a
netmask is specified, m_NetAddress
is taken to be a subnet address.
m_SnmpPort
Integer
The SNMP port on the target
device, or target devices if the
device access configuration
specified by this record is
applicable to a subnet. If no value
is specified for m_SnmpPort, then
the value defaults to the standard
SNMP 161 port.
snmpStack.multibyteObjects table
The snmpStack.multibyteObjects table defines MIB objects that are checked to see if
they are multibyte strings.
Description
Sending a raw ASCII string back to the helper server can cause problems if the
string contains characters with special meaning in ASCII. If the MIB objects contain
multibyte strings, the SNMP helper encodes them.
Schema
The snmpStack.multibyteObjects database table schema is described in the
following table:
326
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 66. snmpStack.multibyteObjects database table schema
Column name
Constraints
Data type
Description
m_ObjectName
NOT NULL
Text
The MIB object name to be
checked.
snmpStack.conversionCfg database table
The snmpStack.conversionCfg database table configures the SNMP Helper to
replace characters that are not allowed in the locale of the NCIM database with the
question mark character: '?'.
Description
The SNMP Helper substitutes characters on only those objects that are configured
in the snmpStack.multibyteObjects table.
Inserts into this database table are configured in the SnmpStackSchema.cfg file.
Schema
The snmpStack.conversionCfg database table schema is described in the following
table:
Table 67. snmpStack.conversionCfg database table schema
Column name
Constraints
m_SubstituteInvalidUTF8 NOT NULL
Data type
Description
Integer
If set to 1, the SNMP Helper
replaces characters that are not
allowed in the locale of the NCIM
database with the question mark
character: '?'.
If set to 0, no action is taken on
invalid characters.
snmpStack.verSecurityTable database table
The snmpStack.verSecurityTable maps an IP or subnet address with an SNMP
version (1, 2, or 3).
Description
The security parameters must be configured, as specified by the SNMP version, in
order to gain SNMP access to network devices. An example of this is the use of
community strings for SNMP versions 1 and 2, as well as the specification of the
different security levels offered by SNMP V3.
Schema
The snmpStack.verSecurityTable database table schema is described in the
following table:
Appendix A. Discovery databases
327
Table 68. snmpStack.verSecurityTable database table schema
Column name
Constraints
m_AccessLevel
Data type
Description
Integer
The SNMP access level. Possible
values are:
v 1 - Read
v 2 - Read/write
The default value is 1.
m_EncryptedPwd
Integer
Whether the password stored in
the configuration file is
encrypted:
v 1 - Encrypted
v 2 - Unencrypted
m_IpOrSubNetVer
Text
The IP or subnet address to
which the device access
configuration specified by this
record is applicable. The
interpretation of this field as an
IP or a subnet address is
dependent on the value
specified in the
m_NetMaskBitsVer field.
m_NetMaskBitsVer
Integer
The subnet mask for the
address specified by the
m_IpOrSubNetVer field. If this
field is set to 32 then
m_IpOrSubNetVer is taken as a
single IP address.
m_NumRetries
Integer
The number of times to retry
the request.
m_Password
Text
The password to try for this IP
or subnet address; for example,
community string.
m_Protocol
Integer
An integer representation of the
network protocol used by the
presently-defined zone:
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
v 4: Element Management
System (EMS) key for a
non-IP device
m_SecurityName
328
IBM Tivoli Network Manager IP Edition: Discovery Guide
Text
The SNMP V3 security
password.
Table 68. snmpStack.verSecurityTable database table schema (continued)
Column name
m_SnmpPort
Constraints
Data type
Description
Integer
The SNMP port on the target
device, or target devices if the
device access configuration
specified by this record is
applicable to a subnet.
If no value is specified for
m_SnmpPort, then the value
defaults to the standard SNMP
161 port.
m_SNMPVer3Details
Object of type An object representation of the
V3SecInfo
authpassword and/or
privpassword details for SNMP
V3.
m_SNMPVer3Level
Integer
Integer representation of the
SNMP V3 security level.
m_SNMPVersion
Integer
The SNMP version that this
configuration applies to.
v 0: SNMP V1
v 1: SNMP V2
v 2: SNMP V3
m_TimeOut
Integer
The maximum time to wait for
a reply from a device, in
milliseconds.
m_Type
Integer
An integer classification of the
password type; for example:
(2) SNMP Get password.
telnetStack database
The telnetStack database defines the Telnet access parameters for devices.
Description
The telnetStack database is defined in the TelnetStackSchema.cfg file.
Related reference:
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
telnetStack.passwords database table
The telnetStack.passwords database table defines the Telnet access parameters for
devices.
Schema
The telnetStack.passwords database table schema is described in the following
table:
Appendix A. Discovery databases
329
Table 69. telnetStack.passwords database table schema
Column name
Constraints
Data type
Description
m_AccessPort
Integer
The port on which to access the device.
m_ConPrompt
Text
Console prompt to expect from remote device.
Default = "^.*[a-zA-Z0-9].*[$%>#]$".
m_EncryptedPwd
Integer
Whether the password stored in the configuration
file is encrypted:
v 1 - Encrypted
v 2 - Unencrypted
m_IpOrSubNet
Text
IP or subnet address depending on value of
m_NetMaskBits.
m_LogPrompt
Text
Login prompt to expect from remote device.
Default = ".*ogin:.*".
m_NetMaskBits
m_Password
m_PreferSSHv1
NOT NULL
Integer
The subnet mask. If set to 32, m_IpOrSubNet is
taken to be a single IP address.
Text
The password to try for this subnet or IP address.
Default = "\n" (carriage return).
Integer
Fix Pack 2
A boolean flag that indicates whether
SSHv1 is used if a device supports SSH v1 and v2.
Possible values are:
v 0: Use SSHv2 support.
v 1: Prefer SSHv1 support.
If no value is specified for m_PreferSSHv1, then the
value defaults to 0.
The m_PreferSSHv1 setting functions only when
m_SSHSupport is enabled and the target device
supports both SSH v1 and v2.
m_PrivAccessCmd
Text
The command for this device to enter into privileged
mode.
m_PrivCommands
List type text
Which commands require privileged access.
m_PrivConPrompt
Text
The regular expression for the console prompt in
privileged mode.
m_PrivPassword
Text
The password to enter privileged mode.
m_PrivPwdPrompt
Text
The regular expression for the password prompt in
privileged mode.
m_Protocol
Integer
An integer representation of the network protocol
used by the presently-defined zone:
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through network address
translation (NAT)
v 3: IPv6
v 4: Element Management System (EMS) key for a
non-IP device
m_PwdPrompt
330
Text
IBM Tivoli Network Manager IP Edition: Discovery Guide
Password prompt to expect from remote device.
Default = ".*assword:.*".
Table 69. telnetStack.passwords database table schema (continued)
Column name
m_SSHSupport
Constraints
Data type
Description
Boolean Integer
Flag to indicate whether or not to use SSH support
for this device:
v 1: Use SSH support for this device.
v 0: Do not use SSH support for this device.
If no value is specified for m_SSHSupport, then the
value defaults to 0, that is, no SSH support.
m_TimeOut
Integer
The time to wait for a response from the device, in
milliseconds.
m_Username
Text
The username to try for this subnet or IP address.
Default = "".
Process management databases
On startup, the discovery engine, ncp_disco, populates the agent and stitcher
databases with information extracted from the discovery agent and discovery
stitcher files. While operating, ncp_disco scans for alterations to the agent and
stitcher files and updates the agent and stitcher databases if necessary. The
frequency of scans is set in the disco database.
The agents and stitchers databases contain definition and configuration information
for the agents and stitchers, such as a list of the types of devices that are sent to
any given agent. The information in these databases is extracted by the discovery
engine from the following directories:
v /precision/disco/agents
v /precision/disco/stitchers
The stitchers databases also contain information about when any given stitcher is
triggered; for example, "start stitcher X upon completion of agent Y," or "start
stitcher X upon the insertion of an entry into database table Z." It is therefore
possible to start stitchers on demand by inserting their name into the appropriate
actions table using OQL. The necessary agents are started automatically when a
device is inserted into the despatch table of the agent.
Configuring the data flow: starting stitchers on-demand
The information extracted by DISCO contains the full definitions of the agents and
stitchers, which includes the trigger conditions. By modifying the trigger
conditions, you can modify the data flow of the discovery process.
You can start the discovery cycle from any point within the configured data flow
by placing a stitcher into the actions table of the stitchers database.
Appendix A. Discovery databases
331
agents database schema
The agents database is defined in $NCHOME/etc/precision/DiscoSchema.cfg. Its
fully qualified database table names are: agents.definitions; agents.victims;
agents.status
agents.definitions table
The agents.definitions table contains scheduling information for every discovery
agent, extracted from the information in the discovery agent file.
Table 70. agents.definitions database table schema
Column name Constraints
m_Name
Data type
v PRIMARY KEY Text
Description
Name of the agent.
v NOT NULL
m_Type
Externally
defined
agentType data
type
Integer
Agent Type:
v 0: Undefined
v 1: Precompiled
v 2: Text defined
v 3: Combination
m_Text
NOT NULL
m_ExecuteOn
m_Phase
Default = 1
m_UpdTime
Text
Textual description of agent rules.
Text
The host on which to execute the agent.
Integer
The discovery phase by the end of
which the agent is expected to
complete.
Long integer
The time of the last modification, which
determines whether the agent has
changed since its definition was stored.
agents.sourceInfo table
The agents.sourceInfo table holds information on the types of data source used by
an agent.
Table 71. agents.sourceInfo database table schema
Column name
Constraints
Data type
Description
m_DiscoveryProtocol
NOT NULL
Text
The protocol used by the agent to get data from
this source. Possible values are:
v Unknown
v Other
v Manual
v FlatFile
v SNMP
v Telnet
v XML-RPC
v VSphere
v OtherJavaAPI
v TL1
v CORBA
m_Name
v PRIMARY KEY
Text
v NOT NULL
332
IBM Tivoli Network Manager IP Edition: Discovery Guide
Name of the agent.
Table 71. agents.sourceInfo database table schema
Column name
Constraints
m_RequiredField
(continued)
Data type
Description
List type text
Lists a field that must exist in the main node
record in order for the entity to be considered of
this source.
m_RequiredValue
m_Source
Lists a value for the field specified in
m_RequiredField that must exist in the main
node record in order for the entity to be
considered of this source.
NOT NULL
Text
The source of the data. Possible values are:
v Unknown: source of the chassis is unknown.
v Other: other source.
v TopologyEditor: chassis was manually added
using the Topology Editor.
v PresetLayer: chassis was manually set using
the PresetLayer stitcher.
v Agent: chassis was discovered as part of the
standard discovery process.
v Collector: chassis was discovered as part of
the EMS discovery process.
agents.status table
The agents.status table contains information about the present status of the agent.
Table 72. agents.status database table schema
Column name
Constraints
m_CompletionPhase
m_Name
v PRIMARY KEY
Data type
Description
Integer
The discovery phase in which the agent
completes.
Text
Name of the agent.
v NOT NULL
v UNIQUE
m_NumConnects
Default = 0
Integer
The number of times that DISCO has connected
to the agent.
m_State
Externally defined
agentState data type.
Integer
The current state of the agent:
Default = 0
v 0: Undefined
v 1: Not running
v 2: Start up
v 3: Running
v 4: Finished
v 5: Died
Appendix A. Discovery databases
333
agents.victims table
The agents.victims table contains an extraction of the criteria that determine which
devices get sent to the agent.
Table 73. agents.victims database table schema
Column
name
Constraints
m_Name
v PRIMARY KEY Text
Data type
Description
Name of the agent.
v NOT NULL
v UNIQUE
Text
m_Filter
The filter condition that determines
which devices are sent to the agent.
Stitchers database schema
The stitchers database is defined in $NCHOME/etc/precision/DiscoSchema.cfg. Its
fully qualified database table names are: stitchers.triggers; stitchers.status;
stitchers.actions.
stitchers.triggers table
The stitchers.triggers table contains an extraction of the criteria that determine the
trigger for the stitcher.
Table 74. stitchers.triggers database table schema
Column name
Constraints
Data type
m_Name
v PRIMARY KEY Text
Description
Name of the stitcher.
v NOT NULL
v UNIQUE
Integer
m_Type
The type of stitcher trigger:
v 0: Undefined
v 1: On the completion of some other
activity; for example, another stitcher
or a discovery phase
v 2: On a table insert
v 3: On demand
v 4: On a timer
m_Trigger
334
Externally
defined
ruleTrigger data
type
IBM Tivoli Network Manager IP Edition: Discovery Guide
Object
Description of the stitcher trigger.
stitchers.status table
The stitchers.status table contains the information about the present status of the
stitcher.
Table 75. stitchers.status database table schema
Column
name
Constraints
m_Name
v PRIMARY KEY Text
Data type
Description
Name of the stitcher.
v NOT NULL
v UNIQUE
m_State
Externally
Integer
defined stchrState
data type
The current state of the stitcher:
Default = 0
v 2: Running
v 0: Undefined
v 1: Start up
v 3: Finished
v 4: Not maintained (the stitcher is not
having its state maintained)
stitchers.actions table
If a stitcher is inserted into the stitchers.actions table, DISCO runs the stitcher.
Once the stitcher has completed, its entry is deleted from the stitchers.actions table.
Any stitchers triggered to execute from the stitcher that has been inserted, or upon
completion of the stitcher, are also executed.
You can also configure other actions to take place on completion of the stitcher, so
that the discovery cycle completes from that point onwards.
Table 76. stitchers.actions database table schema
Column name
Constraints
Data type
Description
m_Name
v PRIMARY
KEY
Text
Name of the stitcher.
v NOT NULL
Related concepts:
“Configurable discovery data flow” on page 438
The discovery process data flow is user-configurable. Stitchers control the
movement of data between databases, and you can customize the discovery
process by changing the way in which the stitchers are triggered and operate.
Subprocess databases
The finders, Details, and agent databases are used during the discovery by the
discovery engine subprocesses to store information retrieved from the network.
The databases are defined within the configuration file, DiscoSchema.cfg.
The subprocess databases include:
v The finders database, which is used by the finders to store information about
device existence.
v The Details database, which is used by the Details agent to store basic device
information.
v The discovery agent databases, which are created using a template.
Appendix A. Discovery databases
335
The finders, Details and AssocAddress agents must always be run, so their
databases are defined in the DiscoSchema.cfg configuration file. The databases for
the rest of the discovery agents are created based on a template that is defined in
the DiscoSchema.cfg configuration file.
finders database schema
The finders database is defined in $NCHOME/etc/precision/DiscoSchema.cfg.
The fully qualified database table names of the finders database are:
v finders.despatch
v finders.returns
v finders.pending
v finders.processing
v finders.rediscovery
The finders database is the central monitoring and management point for finders
operating during discovery. The finders discover the existence of devices and
report these devices back to the finders database, but do not discover connections.
Network entities reported by the finders are usually sent to the Details agent for
retrieval of basic device information, although the discovery data flow is fully
configurable.
Related concepts:
“Discovery cycles” on page 430
A discovery cycle has occurred when the discovery data flow for a particular cycle
has gone from start to finish. A full discovery might require more than one cycle.
finders.despatch table
The finders.despatch table contains a record of all the requests sent to the finders
and the current status of the requests.
Table 77. finders.despatch database table schema
Column name
Constraints
Data type
Description
m_Finder
v PRIMARY KEY
Text
The name of the finder
responsible for the
request.
Text
The OQL request sent to
the finder named above.
Integer
The current status of the
request sent to the finder.
v NOT NULL
m_FindRequest
v PRIMARY KEY
v UNIQUE
v NOT NULL
m_Request Status
336
IBM Tivoli Network Manager IP Edition: Discovery Guide
finders.returns table
When a finder finds a device, it returns the information to the finders.returns table,
provided that the discovery is still in the device discovery phase, that is, data
collection phase one. If the discovery is in the blackout state, the finders return the
information to the pending table.
The returns table serves as a transfer point, notifying the system that a device
exists. By default, a stitcher sends the device information to the Details agent to
discover basic device information.
Table 78. finders.returns database table schema
Column name
Constraints
Data type
Description
m_UniqueAddress
v PRIMARY KEY
Text
A string that uniquely
identifies this entity. The
content of this field is
unconstrained, and might be
an IP address or an element
management system (EMS)
key.
m_Name
Text
The unique name of the
network entity.
m_Creator
Text
The finder that created this
record.
m_Protocol
Integer
An integer representation of
the network protocol used by
the presently-defined zone:
v UNIQUE
v NOT NULL
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been
through network address
translation (NAT)
v 3: IPv6
v 4: Element Management
System (EMS) key for a
non-IP device
finders.pending table
The pending table accepts device information when the returns table has been
locked out by DISCO. The returns table has to be locked during data processing
because even though the data collection stage has completed, it does not
necessarily mean that all the devices on the network have been discovered.
Network entities that have been sent to the pending table are processed after the
current discovery cycle has been completed.
Table 79. finders.pending database table schema
Column name
Constraints
m_UniqueAddress
v PRIMARY
KEY
Data
type
Text
A string that uniquely identifies this
entity. The content of this field is
unconstrained, and might be an IP
address or an element management
system (EMS) key.
Text
The unique name of the network entity.
v UNIQUE
v NOT NULL
m_Name
Description
Appendix A. Discovery databases
337
Table 79. finders.pending database table schema
Column name
Constraints
Data
type
(continued)
Description
m_Creator
Text
The finder that created this record in the
table.
m_Protocol
Integer
An integer representation of the network
protocol used by the presently-defined
zone:
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through network
address translation (NAT)
v 3: IPv6
v 4: Element Management System (EMS)
key for a non-IP device
Text
m_AddressSpace
The name of the NAT address space to
which the device belongs.
This value is set in the
translations.NATAddressSpaceIds table. If
the discovery is not using NAT, or if the
device is in the public domain, this value
is NULL.
finders.processing table
The processing table contains a record of all the discovered entities that are
currently being processed by DISCO. Any device that has been reported to the
returns table and is awaiting the next action to take place has an entry in the
processing table.
Table 80. finders.processing database table schema
Column name
Constraints
Data type
Description
m_UniqueAddress
v PRIMARY
KEY
Text
A string that uniquely identifies
this entity. The content of this field
is unconstrained, and might be an
IP address or an element
management system (EMS) key.
m_Name
Text
The unique name of the network
entity.
m_Creator
Text
The finder that created this record
in the table.
m_Protocol
Integer
An integer representation of the
network protocol used by the
presently-defined zone:
v UNIQUE
v NOT NULL
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
v 4: Element Management System
(EMS) key for a non-IP device
338
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 80. finders.processing database table schema
Column name
Constraints
m_AddressSpace
(continued)
Data type
Description
Text
The name of the NAT address
space to which the device belongs.
This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is NULL.
finders.rediscovery table
The rediscovery table can hold nodes and subnets that you want to rediscover.
Any device inserted into this table is sent to the Ping finder for processing.
Table 81. finders.rediscovery database table schema
Column name
Constraints
Data type
m_Address
v PRIMARY KEY Text
v NOT NULL
Int
m_RequestType
Description
The IP address of the discovered
network entity.
The type of IP address:
v 1: Individual
v 2: Subnet
m_NetMask
m_Protocol
NOT NULL
Text
The net mask if the address refers to a
subnet.
Integer
An integer representation of the IP
protocol used by the presently-defined
zone:
v 1: IPv4
v 2: IPv4 that has been through
network address translation (NAT)
v 3: IPv6
CollectorDetails database schema
The CollectorDetails database is defined in $NCHOME/etc/precision/
DiscoSchema.cfg. Its fully qualified database table names are:
CollectorDetails.despatch; CollectorDetails.returns.
The CollectorDetails agent retrieves basic information about devices discovered by
the collector finders when information from the collector finders is placed in the
despatch table. The CollectorDetails agent retrieves the appropriate device
information and places the results in the returns table.
CollectorDetails.despatch table
The despatch table contains basic information about devices that have been
detected by the collector finders. When data is placed in this table, the
CollectorDetails agent automatically interrogates the network for more detailed
device information.
Appendix A. Discovery databases
339
Table 82. CollectorDetails.despatch database table schema
Column name
Constraints
Data type
Description
m_UniqueAddress
v PRIMARY KEY
Text
A string that uniquely identifies this entity. The
content of this field is unconstrained, and
might be an IP address or an element
management system (EMS) key.
Text
Identifies the manager of the device. Takes the
value "" if device is accessed directly.
m_Name
Text
Unique name of an entity on the network.
m_Protocol
Integer
An integer representation of the network
protocol used by the presently-defined zone:
v NOT NULL
m_ManagerId
NOT NULL
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through network
address translation (NAT)
v 3: IPv6
v 4: Element Management System (EMS) key
for a non-IP device
Text
m_AddressSpace
The name of the NAT address space to which
the device belongs.
This value is set in the
translations.NATAddressSpaceIds table. If the
discovery is not using NAT, or if the device is
in the public domain, this value is NULL.
m_DespatchTime
m_ExtraInfo
Externally defined vblist
data type
Timestamp
Date and time the network was interrogated
by the CollectorDetails agent.
Object
Any extra information.
CollectorDetails.returns table
The returns table holds detailed device information retrieved by the
CollectorDetails agent. Information inserted into this table is automatically
processed by the stitchers so that the device connectivity can be discovered by the
appropriate discovery agent.
Table 83. CollectorDetails.returns database table schema
Column name
Constraints
m_Name
340
Data type
Description
Text
Unique name of an entity on the
network.
m_UniqueAddress
NOT NULL
Text
A string that uniquely identifies
this entity. The content of this
field is unconstrained, and might
be an IP address or an element
management system (EMS) key.
m_ManagerId
NOT NULL
Text
Identifies the manager of the
device. Takes the value "" if device
is accessed directly.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 83. CollectorDetails.returns database table schema
Column name
Constraints
m_Protocol
(continued)
Data type
Description
Integer
An integer representation of the
network protocol used by the
presently-defined zone:
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
v 4: Element Management System
(EMS) key for a non-IP device
m_ObjectId
Text
Textual representation of the
device class (an ASN.1 address).
m_Description
Text
Value of sysDescr MIB variable of
the entity.
Integer
Flag indicating whether there is
SNMP access to the device:
m_HaveAccess
Externally
defined Boolean
data type
v 1: Have access
v 0: No access
m_UpdAgent
m_LastRecord
Externally
defined Boolean
data type
Text
The agent that updated this
device.
Boolean
integer
A flag indicating whether this is
the last record for this entity (that
is, whether the entity has been
completely processed):
v 1: True
v 0: False
m_AddressSpace
Text
The name of the NAT address
space to which the device belongs.
This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is
NULL.
m_ReturnTime
Timestamp
Date and time this value was
returned.
Object
Any extra information.
m_ExtraInfo
Externally
defined vblist
data type
Appendix A. Discovery databases
341
Details database schema
The Details database is defined in $NCHOME/etc/precision/DiscoSchema.cfg. Its
fully qualified database table names are: Details.despatch; Details.returns.
The Details agent retrieves basic information about devices discovered by the
finders when information from the finders is placed in the despatch table. The
Details agent retrieves the appropriate device information and places the results in
the returns table.
A stitcher takes the information from the Details.returns table and sends it to the
Associated Address agent and ultimately the appropriate discovery agent.
details.despatch table
The despatch table contains basic information about devices that have been
detected by the finders. When data is placed in this table, the Details agent
automatically interrogates the network for more detailed device information.
Table 84. Details.despatch database table schema
Column name
Constraints
Data
type
m_UniqueAddress
v PRIMARY KEY
Text
The IP address of the discovered
network entity.
Text
Unique name of an entity on the
network.
Text
Identifies the manager of the device.
Takes the value "" if device is
accessed directly.
Integer
An integer representation of the IP
protocol used by the
presently-defined zone:
v NOT NULL
m_Name
m_ManagerId
NOT NULL
m_Protocol
Description
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
m_AddressSpace
Text
The name of the NAT address space
to which the device belongs.
This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the public
domain, this value is NULL.
342
IBM Tivoli Network Manager IP Edition: Discovery Guide
details.returns table
The returns table holds detailed device information retrieved by the Details agent.
Information inserted into this table is automatically processed by the stitchers so
that the device connectivity can be discovered by the appropriate discovery agent.
Table 85. Details.returns database table schema
Column name
Constraints
Data type
Description
m_AddressSpace
Text
The name of the NAT address
space to which the device belongs.
This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is
NULL.
m_Description
Text
Value of sysDescr MIB variable of
the entity.
m_ExtraInfo
Externally
defined vblist
data type
Object
Any extra information.
m_HaveAccess
Externally
defined Boolean
data type
Integer
Flag indicating whether there is
SNMP access to the device:
v 1: Have access
v 0: No access
m_LastRecord
Externally
defined Boolean
data type
Boolean
integer
A flag indicating whether this is
the last record for this entity (that
is, whether the entity has been
completely processed):
v 1: True
v 0: False
Text
Identifies the manager of the
device. Takes the value "" if device
is accessed directly.
m_Name
Text
Unique name of an entity on the
network.
m_ObjectId
Text
Textual representation of the
device class (an ASN.1 address).
m_Protocol
Integer
An integer representation of the
IP protocol used by the
presently-defined zone:
m_ManagerId
NOT NULL
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
m_UniqueAddress
m_UpdAgent
NOT NULL
Text
The IP address of the discovered
network entity.
Text
The agent that updated this
device.
Appendix A. Discovery databases
343
Finders databases
Finders determine device existence. Each of the finders uses a different method to
discover network devices. You can enable finders for your discovery by
configuring them as managed processes of DISCO in their respective configuration
files. Finders are automatically launched at the appropriate time, provided that
CTRL is running.
Each finder must be configured by editing its configuration file. The finders
discover the existence of devices and report these devices back to the finders
database, but do not discover connections.
Note that the finders database is distinct from the databases that are associated
with the individual finders.
The finders are described in the table below, with their executable name and the
location of their configuration file. $NCHOME is the environment variable that
contains the path to the netcool directory.
Table 86. Description of the finders
344
Finder
Executable
Configuration file
Description
Ping
ncp_df_ping
$NCHOME/etc/precision/
DiscoPingFinderSchema.cfg
$NCHOME/etc/precision/
DiscoPingFinderSeeds.cfg
Makes a simple ICMP
echo request for broadcast
or multicast addresses,
individual IP addresses,
or all devices on a subnet.
File
ncp_df_file
$NCHOME/etc/precision/
DiscoFileFinderSchema.cfg
$NCHOME/etc/precision/
DiscoFileFinderParseRules.cfg
Parses a file, such as
/etc/hosts, to retrieve a
list of devices to find
devices on the network.
Database ncp_df_dbentry
$NCHOME/etc/precision/
DiscoDBEntryFinderSchema.cfg
Reads a database in order
to retrieve a list of
devices to find on the
network.
Collector ncp_df_collector
$NCHOME/etc/precision/
DiscoCollectorFinderSchema.cfg
$NCHOME/etc/precision/
DiscoCollectorFinderSeeds.cfg
An EMS collector is a
software module that
retrieves and stores
topology data from an
Element Management
System (EMS). The
Collector finder queries a
collector and gets a list of
IP addresses managed by
the EMS associated with
that collector.
IBM Tivoli Network Manager IP Edition: Discovery Guide
collectorFinder database
The collectorFinder database defines the operation of the Collector finders.
Description
The collectorFinder database is defined in the DiscoCollectorFinderSchema.cfg
configuration file. It has the following tables:
v collectorFinder.collectorRules
v collectorFinder.configuration
Related reference:
“DiscoCollectorFinderSeeds.cfg configuration file” on page 65
The DiscoCollectorFinderSeeds.cfg configuration file defines how topology data
is acquired from Element Management System (EMS) collectors during discovery.
collectorFinder.collectorRules database table
The collectorFinder.collectorRules database table configures the operation of the
Collector finder.
Description
You can override some of the settings for particular collectors in the
collectorFinder.configuration table. The collectorRules table can contain multiple
records.
Schema
The collectorFinder.collectorRules database table schema is described in the
following table:
Table 87. collectorFinder.collectorRules database table schema
Column name
Constraints
Data type Description
Text
m_Host
The host address on which the
collector is running. This field is NOT
NULL only if the collector is running
on a different host to Network
Manager.
This field may be configured for both
a discovery and a rediscovery.
m_Port
v PRIMARY KEY
v NOT NULL
Text
The port on which the collector is
listening. If the collector is running on
the same host as Network Manager,
then this is a Network Manager port.
This field may be configured for both
a discovery and a rediscovery.
Appendix A. Discovery databases
345
Table 87. collectorFinder.collectorRules database table schema (continued)
Column name
Constraints
m_RequestType
Data type Description
Integer
Flag denoting which topology data to
download from the data source. This
flag works together with the
m_Address and m_NetMask fields.
The flag takes the following values:
v 0: Rediscover all devices. All devices
retrieved by the collector are
discovered. The m_Address and
m_NetMask fields are ignored.
v 1: Rediscover single device. Only
one of the devices retrieved by the
collector is discovered. The
m_Address field specifies the device
and the m_NetMask fields is
ignored.
v 2: Rediscover subnet. One of the
subnets retrieved by the collector is
discovered. The m_Address field
specifies the subnet and the
m_NetMask field specifies the
subnet mask.
This field is configured for a
rediscovery only.
m_DataSourceId
Integer
Limits rediscovery to a single data
source supported by the collector. This
field is rarely used as a collector
usually only supports a single data
source.
This field is configured for a
rediscovery only.
m_Address
Text
Used in conjunction with the
m_RequestType and m_NetMask fields
when specifying a device or subnet to
rediscover. See the entry for
m_RequestType for more information.
This field is configured for a
rediscovery only.
m_NetMask
Text
Used in conjunction with the
m_RequestType and m_Address fields
when specifying a device or subnet to
rediscover. See the entry for
m_RequestType for more information.
This field is configured for a
rediscovery only.
m_NumRetries
Integer
Number of retries to issue an RPC
XML request to the collector. Setting
this field is optional. If set, this field
overrides the default specified in the
collectorFinder.configuration table.
This field may be configured for both
a discovery and a rediscovery.
346
IBM Tivoli Network Manager IP Edition: Discovery Guide
collectorFinder.configuration database table
The collectorFinder.configuration table specifies the general rules of the Element
Management System (EMS) collector methodology and must only contain one
record.
Schema
The collectorFinder.configuration database table schema is described in the
following table:
Table 88. collectorFinder.configuration database table schema
Column name
Constraints
Data type
Description
m_NumThreads
Integer
The number of threads to be used by the
Collector finder.
m_TimeOut
Integer
The maximum time to wait for a reply
from a collector (the timeout).
m_NumRetries
Integer
The number of times to issue an RPC
XML request to a collector.
m_MaxResponseSize
Integer
The maximum size for an XML-RPC
response in bytes.
Note: The default maximum response
size might be too small when running a
Collector-based discovery against
Collectors that result in very large
responses. In such cases, increase the
maximum response size. To increase the
maximum response size, set the
m_MaxResponseSize parameter to a higher
value. Make sure you set the same value
for m_MaxResponseSize in both of the
following files:
v NCHOME/etc/precision/
DiscoCollectorFinderSchema.cfg
v NCHOME/etc/precision/
DiscoXmlRpcHelperSchema.cfg
dbEntryFinder database
The dbEntryFinder database defines the operation of the Database finder.
Description
The dbEntryFinder database is defined in the DiscoDBEntryFinderSchema.cfg file.
It has the following tables:
v dbEntryFinder.configuration
v dbEntryFinder.dbQueries
Related reference:
“DiscoDBEntryFinderQueries.cfg configuration file” on page 66
The DiscoDBEntryFinderQueries.cfg file is used to specify the a database query to
be run against a specified database in order to retrieve a list of IP addresses of
devices to discover on the network.
Appendix A. Discovery databases
347
dbEntryFinder.configuration database table
You can configure the Database finder with the dbEntryFinder.configuration table,
which specifies the number of threads to be used by the finder.
Schema
The dbEntryFinder.configuration database table is described in the following table.
Table 89. dbEntryFinder.configuration database table schema
Column name
Constraints
Data type
Description
m_NumThreads
NOT NULL
Integer
The number of threads to be used by
the Database finder.
dbEntryFinder.dbQueries database table
By configuring inserts into the dbEntryFinder.dbQueries table, you can specify the
SQL queries to run to retrieve device details from the database that stores
discovery seed details. You can also specify optional mapping parameters that
define how to map the device details retrieved from the database to the
finders.returns or finders.discovery tables.
Schema
The dbEntryFinder.dbQueries database table schema is described in the following
table:
Table 90. dbEntryFinder.dbQueries database table schema
Column name
Constraints
Data type
Description
m_DBEntryName
v NOT NULL
Text
The unique name of this database
entry.
Text
Identifier of the database that
contains the device details, as defined
in the DbLogins.DOMAIN.cfg
configuration file.
Integer
Indicates which trigger type invokes
this query:
v UNIQUE
m_DbId
m_TriggerType
NOT NULL
v 1 Full discovery
v 2 Partial rediscovery
v 3 Forced rediscovery
348
m_Query
Text
m_Parameters
List of atoms Optional parameters to pass to the
query.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Code of the query.
Table 90. dbEntryFinder.dbQueries database table schema
Column name
Constraints
Data type
(continued)
Description
List of atoms Optional mapping parameters that
define how to map the fields returned
from the query into fields expected
by the Discovery engine, ncp_disco.
These parameters map data into
target database tables as follows:
m_Mapping
v If m_TriggerType is 1 or 2, then
map the data to the
finders.returns table.
v If m_TriggerType is 3, then map the
data to the finders.rediscovery
table.
fileFinder database
The fileFinder database defines the operation of the File finder.
Description
The fileFinder database is defined in the DiscoFileFinderParseRules.cfg file. It has
the following tables:
v fileFinder.configuration
v fileFinder.parseRules
Related reference:
“DiscoFileFinderParseRules.cfg configuration file” on page 68
The DiscoFileFinderParseRules.cfg file can be used to specify the files to be parsed
for a list of IP addresses of devices that exist on the network.
fileFinder.configuration database table
You can configure the File finder with the fileFinder.configuration table, which
specifies the number of threads to be used by the finder.
Schema
The fileFinder.configuration database table is described in the following table.
Table 91. fileFinder.configuration database table schema
Column name
Constraints
Data type
Description
m_NumThreads
NOT NULL
Integer
The number of threads to be used by
the File finder.
Appendix A. Discovery databases
349
fileFinder.parseRules database table
By configuring inserts into the fileFinder.parseRules table, you can specify the files
to be parsed for a list of IP addresses of devices on the network.
Description
The fileFinder.parseRules table specifies the rules for file parsing.
A typical file that you would parse, for example, is the /etc/hosts file on the
machine running DISCO. You can also seed the discovery by parsing the
/etc/defaultrouter file.
Schema
The fileFinder.parseRules database table schema is described in the following table:
Table 92. fileFinder.parseRules database table schema
Column name
Constraints
Data type
Description
m_FileName
v NOT NULL
Text
The unique full path and filename of
the file to be parsed, for example,
/etc/hosts.
m_Delimiter
Text
The delimiter that separates the data
fields in the file. Regular pattern
matching expressions are also
accepted as valid delimiters.
Note: \t is not supported as a valid
value for the <tab> character.
m_ColDefs
List of atoms A list of rules that specify which
variables to extract and the columns
from which to get them.
v UNIQUE
pingFinder database
The pingFinder database defines the operation of the Ping finder.
Description
The pingFinder database is defined in the DiscoPingFinderSeeds.cfg file. It has the
following tables:
v pingFinder.configuration
v pingFinder.pingFilter
v pingFinder.pingRules
v pingFinder.scope
Related reference:
“DiscoPingFinderSeeds.cfg configuration file” on page 71
The DiscoPingFinderSeeds.cfg configuration file is used for seeding the Ping finder
and restricting device detection.
350
IBM Tivoli Network Manager IP Edition: Discovery Guide
pingFinder.configuration database table
The pingFinder.configuration table specifies the general rules of the ping
methodology. The table must contain only one record.
Description
The pingFinder.configuration table allows you to configure the way devices are
pinged, including enabling broadcast or multicast pinging. Although pinging of
broadcast/multicast addresses allows devices to be discovered more quickly than
other detection methods, it is sometimes less desirable to do so under certain
network conditions, such as when the network is heavily congested. In general,
you would ping broadcast addresses on an unknown sparsely populated network.
You must only ping multicast addresses where they have been set up on the
network.
Schema
The pingFinder.configuration database table schema is described in the following
table:
Table 93. pingFinder.configuration database table schema
Column name
Data type
Description
m_NumThreads
Integer
The number of threads to be used by the Ping
finder.
m_TimeOut
Integer
The maximum time to wait for a reply from a
pinged address (the timeout).
m_InterPingTime
Integer
The interval between pinging the addresses in a
subnet.
m_NumRetries
Integer
The number of times a device is to be
re-pinged.
m_Broadcast
Integer
Flag used to enable or disable broadcast
address pinging:
v 1: Enable
v 0: Disable
m_Multicast
Integer
Flag used to enable or disable multicast address
pinging:
v 1: Enable
v 0: Disable
pingFinder.pingFilter database table
The pingFinder.pingFilter table can be used to exclude particular devices or
subnets from being pinged by the Ping finder.
Description
You may wish to exclude certain interfaces, such as ISDN and modem interfaces,
because pinging these interfaces generates phone calls, which costs money. If you
configure the Ping finder to use both the scope.zones table and the
pingFinder.pingFilter table, the Ping finder pings those devices or subnets it has
been seeded with if they are within either the discovery scope or the Ping finder
scope.
Appendix A. Discovery databases
351
Schema
The pingFinder.pingFilter database table schema is described in the following table:
Table 94. pingFinder.pingFilter database table schema
Column name
Constraints
Data type
m_Protocol
v PRIMARY KEY Integer
Description
An integer representation of the IP
protocol used by the
presently-defined zone:
v NOT NULL
v Externally
defined
netProtocol
data type
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
m_Action
v NOT NULL
Integer
Action to perform for current zone:
v 0: Undefined
v Externally
defined
netProtocol
data type
v 1: Include
v 2: Exclude
m_Zones
List of type
zone
A list of varbinds (name=value)
that define the present zone.
m_AddressSpace
Text
The name of the NAT address
space to which the device belongs.
This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is NULL.
pingFinder.pingRules database table
The pingFinder.pingRules table specifies the different addresses and subnets to be
pinged by the Ping finder.
Description
The pingRules table can contain multiple records.
Schema
The pingFinder.pingRules table is described in the following table.
Table 95. pingFinder.pingRules database table schema
Column name
Constraints
Data type
m_Address
v PRIMARY KEY Text
Description
The address to ping.
v NOT NULL
m_RequestType
Integer
Flag denoting address type:
v 1: Individual
v 2: Subnet
m_NetMask
352
IBM Tivoli Network Manager IP Edition: Discovery Guide
Text
The subnet mask. If a value is
specified for this field, it automatically
implies that the address is a subnet
address.
Table 95. pingFinder.pingRules database table schema (continued)
Column name
Constraints
Data type
Description
m_TimeOut
Integer
Maximum time to wait for response.
This value overrides the default
timeout specified in the configuration
table.
m_NumRetries
Integer
Maximum number of times to
reattempt the ping. This value
overrides the default value.
pingFinder.scope database table
The pingFinder.scope table defines the scope of the Ping finder.
Description
You can use the pingFinder.scope table to configure the way the Ping finder checks
whether it is allowed to ping a particular device. You can exclude particular
devices or subnets from being pinged by the Ping finder.
Schema
The pingFinder.scope database table schema is described in the following table:
Table 96. pingFinder.scope database table schema
Column name
m_UseScope
Constraints
Data type
Description
Integer
Flag denoting whether or not to use the
entries in the scope.zones table when
deciding which devices to ping:
v 0: The Ping finder ignores the
scope.zones table when deciding
which devices to ping.
v 1: This is the default value. The Ping
finder uses the scope.zones table to
check which devices can be pinged.
If you are performing an unscoped
discovery, that is, a discovery without
any entries in the scope.zones table,
then it is preferable to set m_UseScope
to zero to reduce processing load.
m_UsePingEntries
Integer
Flag denoting whether or not to use the
entries in the pingFinder.pingFilter table
when deciding which devices to ping:
v 0: This is the default value. The Ping
finder ignores any entries in the
pingFinder.pingFilter table when
deciding which devices can be
pinged.
v 1: The Ping finder checks the
pingFinder.pingFilter table before it
pings a particular device to see if the
device can be pinged.
Appendix A. Discovery databases
353
The Helper Server databases
When the Helper Server starts, it creates a database for each helper that is to be
run.
Tip: It is good practice to configure the Helper Server to start automatically by
making the appropriate OQL insertion into the services.inTray table of CTRL.
Alternatively, you can start the Helper Server manually with the ncp_d_helpserv
command on the command line.
Related reference:
“DiscoHelperServerSchema.cfg configuration file” on page 71
The DiscoHelperServerSchema.cfg configuration file defines the contents of the
several helper databases.
ARPhelper database
The ARPHelper database configures the operation of the ARP helper, stores
information about the requests the ARP helper makes from the network.
The ARPHelper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
Related reference:
“DiscoARPHelperSchema.cfg configuration file” on page 65
The DiscoARPHelperSchema.cfg configuration file performs IP address to MAC
address resolution.
ARPhelper.ARPHelperConfig table
The ARPhelper.ARPHelperConfig database table configures the general operation
of the ARP helper.
The ARPhelper.ARPHelperConfig database table is described in the following table.
Table 97. ARPhelper.ARPHelperConfig database table schema
Column name
Constraints
Data type
Description
m_HelperDbTimeout
UNIQUE
Long64
The helper database timeout,
that is, how long before the
database expires in the absence
of any activity.
m_HelperReqTimeout
Long64
The helper request timeout, that
is, how long before each request
expires.
m_HelperStartupTimeout
Long64
The default helper startup
timeout, that is, the maximum
time to wait for a helper to start
up when requested.
m_HelperDoWeQuery
Integer
Indicates whether the Helper
Server queries its database or
whether it queries the network
using a helper:
(0) Do not use cache
(1) Use cache
354
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 97. ARPhelper.ARPHelperConfig database table schema
Column name
Constraints
m_HelperDoQueryVBs
Optional
Data type
(continued)
Description
Object type List of helper inputs that
varbinds
always query the database
before querying the network. If
the item is found in the
database then the network is
not queried.
Optional
Object type List of helper inputs that do not
varbinds
query the database. This field
overrides the value specified in
m_HelperDoWeQuery.
m_HelperDoWeStore
Integer
m_HelperDoNotQueryVBs
Indicates whether the Helper
Server stores any replies from
the helpers in its database:
(0) Do not store replies in
database
(1) Store replies in database
m_HelperDoStoreVBs
Optional
Object type List of helper inputs that
varbinds
always store data in the Helper
Server database. This field
overrides the value of
m_HelperDoWeStore.
Optional
Object type List of helper inputs that never
varbinds
store data in the Helper Server
databases. This field overrides
the value of m_HelperDoWeStore.
m_HelperDebugLevel
Integer
Sets the debug level of the
helper, printing to
m_HelperLogfile.
Text
The full path and file for the
logfile of the current helper.
m_HelperDoNotStoreVBs
Optional
m_HelperLogfile
Optional
The m_HelperDoWeQuery and m_HelperDoWeStore fields each have two related
optional fields. A record entered into either m_HelperDoWeQuery or
m_HelperDoWeStore is the default setting to which the helper responds if no
records are entered into the optional fields. However, a record entered into either
of the related optional fields overrides the default setting.
For example, if m_HelperDoWeQuery is set to query the network rather than the
cache (that is, m_HelperDoWeQuery=0) and if an IP address of 192.168.0.1 is
specified in m_HelperDoQueryVBs, then a request record where m_IpAddress =
192.168.0.1 results in the cache being queried rather than the network. The
network is only queried if the information is not currently held in the cache.
ARPhelper database configuration
The following example insert gives a typical ARP helper configuration.
insert into ARPHelper.ARPHelperConfig
(
m_HelperDbTimeout,
m_HelperReqTimeout,
Appendix A. Discovery databases
355
m_HelperStartupTimeout,
m_HelperDoWeQuery,
m_HelperDoWeStore
)
values
(
259200, 1200, 90, 0, 0
);
ARPhelper.ARPHelperTable table
The ARPHelper.ARPHelperTable database table stores information about the
requests the ARP helper makes from the network.
The ARPHelper.ARPHelperTable database table is described in the following table.
Table 98. ARPHelper.ARPHelperTable database table schema
Column name
Constraints
Data type
Description
Text
The address space of the
device.
Text
IP address of the device
to interrogate.
m_HostMac
Text
The physical address of
the device (MAC
address).
m_HostMask
Text
The subnet mask of the
host device to be
interrogated.
m_HostSubnet
Text
Subnet of the host device
to be interrogated.
m_Protocol
Integer
An integer representation
of the IP protocol used by
the presently-defined
zone:
m_AddressSpace
m_HostIp
NOT NULL
v 1: IPv4
v 2: IPv4 that has been
through network
address translation
(NAT)
v 3: IPv6
RivHelperDbTimeToDie
Indicates how long the
requested information is
to live within the Helper
Server.
RivHelperRequestGetKey
NOT NULL
Text
A key interface to the
databases of the Helper
Server for Get requests.
RivHelperRequestReplyKey
v PRIMARY
KEY
Text
A unique key interface to
the databases of the
Helper Server for Reply
requests.
v NOT NULL
v UNIQUE
356
Long64
IBM Tivoli Network Manager IP Edition: Discovery Guide
ARPHelper.configuration table
The ARPHelper.configuration database table defines the number of threads the
helper uses.
The ARPHelper.configuration database is described in the following table.
Table 99. ARPHelper.configuration database table schema
Column Name
Constraints
Data type
Description
m_NumThreads
None
Integer
The number of threads to be used by
the helper.
DNSHelper database
The DNSHelper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
The DNSHelper database table stores information about the requests that the DNS
helper makes from the network, and configuration information for the DNS helper.
Related reference:
“DiscoDNSHelperSchema.cfg configuration file” on page 67
The DiscoDNSHelperSchema.cfg configuration file defines access to DNS, which
enables the discovery to do domain name lookups, by configuring the DNS helper.
DNSHelper.DNSHelperTable table
The DNSHelper.DNSHelperTable database table stores information about the
requests that the ARP helper makes from the network.
The DNSHelper.DNSHelperTable database table is described in the following table.
Table 100. DNSHelper.DNSHelperTable database table schema
Column name
Data type
Description
m_HostName
Text
The host name for
this IP address.
m_HostIp
Text
The IP addresses for
this host.
RivHelperDbTimeToDie
Long64
How long the
requested information
is to live within the
Helper Server.
Text
A key for Get
requests.
Atom
The response data.
Text
A unique key for
Reply requests.
RivHelperRequestGetKey
Constraints
NOT NULL
RivHelperRequestOutput
RivHelperRequestReplyKey
v PRIMARY
KEY
v NOT NULL
v UNIQUE
Appendix A. Discovery databases
357
DNSHelper.DNSHelperConfig table
The DNSHelper.DNSHelperConfig table holds configuration information for the
DNS helper.
The DNSHelper.DNSHelperConfig table is described in the following table.
Table 101. DNSHelper.DNSHelperConfig database table schema
Column name
Constraints
Data type
Description
m_HelperDbTimeout
UNIQUE
Long64
The helper database
timeout, that is, how long
before the database
expires.
Integer
Sets the debug level of
the helper, printing to
m_Logfile.
Object type
varbinds
List of helper inputs that
always query the
database before querying
the network. If the item
is found in the database
then the network is not
queried.
Object type
varbinds
List of helper inputs that
do not query the
database. This field
overrides the value of
m_HelperDoWeQuery.
Object type
varbinds
List of helper inputs that
never store data in the
Helper Server databases.
This field overrides
m_HelperDoWeStore.
Object type
varbinds
List of helper inputs that
always store data in the
Helper Server database.
This field overrides
m_HelperDoWeStore.
Integer
Indicates whether the
Helper Server queries its
database or whether it
queries the network
using a helper:
m_HelperDebugLevel
optional
m_HelperDoQueryVBs
optional
m_HelperDoNotQueryVBs
optional
m_HelperDoNotStoreVBs
optional
m_HelperDoStoreVBs
optional
m_HelperDoWeQuery
v 0: Do not use cache
v 1: Use cache
m_HelperDoWeStore
Integer
Indicates whether the
Helper Server stores any
replies from the helpers
in its database:
v 0: Do not store replies
in database
v 1: Store replies in
database
m_HelperLogfile
optional
358
IBM Tivoli Network Manager IP Edition: Discovery Guide
Text
The full path and file for
the logfile of the current
helper.
Table 101. DNSHelper.DNSHelperConfig database table schema (continued)
Column name
Constraints
Data type
Description
m_HelperReqTimeout
Long64
The helper request
timeout, that is, how long
before each request
expires.
m_HelperStartupTimeout
Long64
The default helper
start-up timeout, that is,
the maximum time to
wait for a helper to start
up when requested.
DNS helper database configuration
The following example insert shows a typical DNS helper configuration.
insert into DNSHelper.DNSHelperConfig
(
m_HelperDbTimeout,
m_HelperReqTimeout,
m_HelperStartupTimeout,
m_HelperDoWeQuery,
m_HelperDoWeStore
)
values
(
259200, 1200, 90, 0, 0
);
DNSHelper.configuration table
The DNSHelper.configuration database table configures the operation of the DNS
Helper. This table must contain only one record
The DNSHelper.configuration table is described in the following table.
Table 102. DNSHelper.configuration database table schema
Column name
Constraints
Data type
Description
m_NumThreads
Integer
The number of threads to be used by the
helper.
m_MethodList
List of text
An ordered list of the methods for name
retrieval.
DNShelper.methods table
The DNShelper.methods database table holds information used by the DNS Helper
to access devices.
The DNShelper.methods database table is described in the following table.
Table 103. DNShelper.methods database table schema
Column name
Constraints
Data type Description
m_FileName
Text
The filename, if appropriate.
m_FileOrder
Integer
The order of the files:
v 0: Name first, then IP address
v 1: IP address, then name
Appendix A. Discovery databases
359
Table 103. DNShelper.methods database table schema (continued)
Column name
Constraints
Data type Description
m_MethodName
v PRIMARY Text
KEY
The name of the method.
v NOT
NULL
v UNIQUE
m_MethodType
Integer
The type of the method:
v 0: System
v 1: DNS
v 2: File
m_NameDomain
Text
Domain name; for example, abcd.com.
m_NameDomainList
Text
Contains a list of expected domain
suffixes. If you expect the discovery
to return some or all devices names
with domain suffixes already
appended, then you can specify a list
of expected domain suffixes in this
column.
Note: The domain suffix value
specified in m_NameDomain is not
appended to any device names
returned by the discovery that have
any of the suffixes listed in
m_NameDomainList.
m_NameServerAddr
Text
The IP address of the DNS server
(specified as a text string). If no value
is specified, /etc/resolv.conf is read.
m_TimeOut
Integer
Time out for the request in seconds.
PingHelper database
The PingHelper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
Related reference:
“DiscoPingHelperSchema.cfg configuration file” on page 73
The DiscoPingHelperSchema.cfg configuration file defines how devices are to be
pinged.
PingHelper.configuration table
The PingHelper.configuration database table configures broadcast and multicast
pinging.
Although pinging broadcast and multicast addresses allows devices to be
discovered quicker than other detection methods, it is not advisable to do so under
certain network conditions; for instance, when the network is heavily congested.
The PingHelper.configuration database table must contain only one record.
The schema of the PingHelper.configuration database table is described in the
following table.
360
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 104. PingHelper.configuration database table schema
Column name
m_Broadcast
Constraints
Data type
Description
Integer
Flag used to enable or
disable broadcast address
pinging:
v (1) Enable
v (0) Disable
m_ICMPSrcPort
The ICMP source port.
m_InterPingTime
Integer
The time interval in
milliseconds between
successive ping attempts of
subnet addresses.
m_NumRetries
Integer
The number of times a
device is to be re-pinged.
m_NumThreads
Integer
The number of threads to be
used by the helper.
m_Multicast
Integer
Flag used to enable or
disable multicast address
pinging:
v (1) Enable
v (0) Disable
m_TimeOut
Integer
The maximum time to wait
for a reply from a pinged
address, in milliseconds. If
you are running the
TraceRoute agent you may
need to increase this value,
depending on network
conditions.
m_UdpSrcPort
Integer
The UDP port to be used.
PingHelper.PingHelperConfig table
The PingHelper.PingHelperConfig database table configures the operation of the
Ping helper.
The schema of the PingHelper.PingHelperConfig database table is described in the
following table.
Table 105. PingHelper.PingHelperConfig database table schema
Column name
Constraints
Data type
Description
m_HelperDbTimeout
UNIQUE
Long64
The helper database
timeout, that is, how
long before the database
expires.
Integer
Sets the debug level of
the helper, printing to
the file specified in
m_HelperLogfile.
m_HelperDebugLevel
optional
Appendix A. Discovery databases
361
Table 105. PingHelper.PingHelperConfig database table schema (continued)
Column name
m_HelperDoNotQueryVBs
optional
m_HelperDoNotStoreVBs
optional
m_HelperDoQueryVBs
optional
m_HelperDoStoreVBs
optional
m_HelperDoWeQuery
Constraints
Data type
Description
Object type
varbinds
List of helper inputs
that do not query the
database. This field
overrides
m_HelperDoWeQuery.
Object type
varbinds
List of helper inputs
that never store data in
the Helper Server
databases. This field
overrides
m_HelperDoWeStore.
Object type
varbinds
List of helper inputs
that always query the
database before
querying the network. If
the item is found in the
database then the
network is not queried.
Object type
varbinds
List of helper inputs
that always store data in
the Helper Server
database. This field
overrides
m_HelperDoWeStore.
Integer
Indicates whether the
Helper Server queries
its database or whether
it queries the network
using a helper:
v 0: Do not use cache
v 1: Use cache
m_HelperDoWeStore
Integer
Indicates whether the
Helper Server stores any
replies from the helpers
in its database:
v 0: Do not store replies
in database
v 1: Store replies in
database
Text
The full path and file
for the logfile of the
current helper.
m_HelperReqTimeout
Long64
The helper request
timeout that is, how
long before each request
expires.
m_HelperStartupTimeout
Long64
The default helper
startup timeout, that is,
the maximum time to
wait for a helper to start
up when requested to.
m_HelperLogFile
optional
362
IBM Tivoli Network Manager IP Edition: Discovery Guide
PingHelper.PingHelperConfig database table configuration
The following insert provides a typical example configuration of the
PingHelper.PingHelperConfig database table.
insert into PingHelper.PingHelperConfig
(
m_HelperDbTimeout,
m_HelperReqTimeout,
m_HelperStartupTimeout,
m_HelperDoWeQuery,
m_HelperDoWeStore
)
values
(
259200, 1200, 90, 0, 0
);
PingHelper.PingHelperTable table
PingHelper.PingHelperTable database table configures the operation of the Ping
helper.
The schema of the PingHelper.PingHelperTable database table is described in the
following table.
Table 106. PingHelper.PingHelperTable database table schema
Column name
Constraints
Data type
Description
m_HostIp
Atom
IP address to ping.
m_HostMask
Text
The subnet mask of
the address to ping.
m_HostSubnet
Text
Subnet of the IP
address to ping.
m_PingRequestType
Integer
The type of ping
request:
v 1: Individual
address
v 2: Subnet
m_PingResponseType
Integer
Type of reply to the
ping.
m_PingRetries
Integer
Number of retries
for the ping.
m_PingTimeout
Integer
Maximum time to
wait for reply.
m_Protocol
Integer
An integer
representation of the
IP protocol used by
the presently-defined
zone:
v 1: IPv4
v 2: IPv4 that has
been through
network address
translation (NAT)
v 3: IPv6
Appendix A. Discovery databases
363
Table 106. PingHelper.PingHelperTable database table schema (continued)
Column name
Constraints
RivHelperDbTimeToDie
Data type
Description
Long64
How long the
requested
information is to live
within the Helper
Server.
RivHelperRequestGetKey
NOT NULL
Text
A key interface to
the databases of the
Helper Server for
Get requests.
RivHelperRequestReplyKey
v PRIMARY
KEY
Text
A key interface to
the databases of the
Helper Server for
Reply requests.
Atom
The response data.
v NOT NULL
v UNIQUE
RivHelperRequestOutput
snmpHelper database
The snmpHelper database configures the operation of the SNMP Helper. This
database is defined in NCHOME/etc/precision/DiscoSnmpHelperSchema.cfg.
Related reference:
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
snmpHelper.configuration table
The snmpHelper.configuration database table configures the operation of the
SNMP Helper.
The snmpHelper.configuration database table is described in the following table.
Table 107. snmpHelper.configuration database table schema
364
Column name
Constraints
Data
type
m_ExponentialRetries
None
Integer
m_LogRequests
None
Boolean Specifies whether the system should
log details about each request
serviced by the SNMP helper. If set
to positive, this causes the
SnmpHelperDebug.DOMAIN.Trace file
to be created in the log directory.
m_NumIOThreads
None
Integer
The number of input/output
threads that the engine should use.
The default value is 10, and the
maximum allowed value is 1000 but
it is best practice to set this value
no higher than 100.
m_NumRetries
None
Integer
The number of attempts to retrieve
SNMP variable(s) from a device.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Description
Number of times to try to
reestablish SNMP communication
with a device that has temporarily
stopped responding
Table 107. snmpHelper.configuration database table schema (continued)
Column name
Constraints
Data
type
m_NumThreads
None
Integer
m_ReadStackConfigOnConnect
None
Boolean Indicates whether to read (or
reread) the contents of the
SnmpStackSecurityInfo.cfg file
when connecting to the Helper
server, ncp_d_helpserv.
m_ResolveHostNames
None
Boolean Specifies whether the SNMP helper
ncp_dh_snmp should attempt to
resolve a hostname.
m_TimeOut
None
Integer
Description
The number of threads to be used
by the helper.
The maximum time to wait for a
reply from a device, in milliseconds.
snmpHelper.dependentInstanceFilter database table
The snmpHelper.dependentInstanceFilter database table is used to define interface
filters that depend on other filters.
Schema
The snmpHelper.dependentInstanceFilter database table schema is described in the
following table:
Table 108. snmpHelper.dependentInstanceFilter database table schema
Column name
Constraints
Data type
m_InstanceFilter
not null
primary key
text
Description
The dependent filter.
The syntax of the filter is
MIB_variable_name in
(eval(list_type,’&MIB_table.MIB_entry’))
where MIB_variable_name must exist in
MIB_table, and a filter on MIB_table has been
defined in the snmpHelper.instanceFilter table.
m_ApplyToFilteredTable
text
This value is automatically derived from
m_InstanceFilter. You must not configure inserts
into this field.
Related reference:
“Example dependent SNMP interface filter” on page 103
You can create dependent filters that use the results of previous filters to filter
additional tables.
Appendix A. Discovery databases
365
snmpHelper.instanceFilter database table
The snmpHelper.instanceFilter database table configures SNMP interface filters for
the SNMP helper.
Schema
The snmpHelper.instanceFilter database table schema is described in the following
table:
Table 109. snmpHelper.instanceFilter database table schema
Column
name
Data
Constraints type
m_Filter
Name
not null,
text
primary key
m_Device
Filter
not null
text
Description
The name of the interface filter. The name must be unique.
The device filter is applied to each discovered device to determine whether or
not to apply the interface filter.
The filter must be in the following form:
mibVariableName expression values
[ optional_Boolean_operator expression optional_Boolean_operator .. ]
For example, the following are all valid filters:
// Apply the interface filter to only a specific type of device
sysObjectID = ’1.3.6.1.4.1.4874.1.1.1.1.3’
// More complex example of the above
sysObjectID = ’1.3.6.1.4.1.4874.1.1.1.1.3’ OR sysDescr LIKE ’ERX-1440’
// Apply the interface filter only to devices in certain locations
sysLocation in ( ’location1’, ’location2’ )
//Apply the interface filter to all types of device.
sysObjectID != ’’
m_Device
FilterOids
366
list
type
text
Specifies any OIDs that need to be retrieved in order to allow the evaluation of
the device filter defined in the m_DeviceFilter field. The OIDs are usually
determined programatically from the value of m_DeviceFilter. You do not
normally need to define the OIDs manually.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 109. snmpHelper.instanceFilter database table schema (continued)
Column
name
m_Instance
Filter
Data
Constraints type
text
Description
The interface filter to be applied to the filtered tables. The interface filter is only
applied to devices that match the device filter. Only rows from those tables with
interfaces that match this filter are returned.
The filter must be in the following form:
mibVariableName expression values
[ optional_Boolean_operator expression optional_Boolean_operator .. ]
For example, the following are all valid filters:
// Only interfaces with names like this are returned
ifName like ’Gi0’
// This filter is against 2 distinct tables (ifTable and ifXTable)
with the requirement that these share a common index (ifIndex)
ifName like ’Gi0’ or ifDescr like ’FastEthernet’
// Filter out interfaces of these types
ifType not in ( 1, 53, 166 )
Restriction: You can configure inserts into only one of the m_InstanceFilter or
m_InstanceFilterTable fields.
Restriction:
The MIB variable used in the interface filter must be from a table that is keyed
on ifIndex, for example, from ifTable or ifXTable.
m_Instance
FilterTable
text
m_Instance
Filters
list
type
object
type
vblist
Defines a table that is not to be queried.
Restriction: You can configure inserts into only one of the m_InstanceFilter or
m_InstanceFilterTable fields.
Restriction: If you define a table that is not to be queried using the
m_InstanceFilterTable field, you must not apply other filters to the same MIB
table for the same device.
The m_InstanceFilters field contains the full collection of interface filters. The
full interface filters are automatically generated from the contents of the
m_InstanceFilter or m_InstanceFilterTable fields.
Restriction: User-configured inserts into this field are not supported.
Related tasks:
“Configuring SNMP interface filters” on page 101
You can configure one or more interface filters per device type.
snmpHelper.SnmpHelperConfig table
The snmpHelper.SnmpHelperConfig database table configures the operation of the
SNMP Helper.
The schema of the snmpHelper.SnmpHelperConfig database table is described in
the following table.
Appendix A. Discovery databases
367
Table 110. snmpHelper.SnmpHelperConfig database table schema
Column name
Constraints
Data type
Description
m_HelperDbTimeout
UNIQUE
Long64
The helper database
timeout, that is, how
long before the
database expires.
Integer
Sets the debug level of
the helper, printing to
m_HelperLogfile.
Object type
varbinds
List of helper inputs
that do not query the
database. This field
overrides
m_HelperDoWeQuery.
Object type
varbinds
List of helper inputs
that never store data in
the Helper Server
databases. This field
overrides
m_HelperDoWeStore.
Object type
varbinds
List of helper inputs
that always query the
database before
querying the network.
If the item is found in
the database then the
network is not queried.
Object type
varbinds
List of helper inputs
that always store data
in the Helper Server
database. This field
overrides
m_HelperDoWeStore.
Integer
Indicates whether the
Helper Server queries
its database or whether
it queries the network
using a helper:
m_HelperDebugLevel
optional
m_HelperDoNotQueryVBs
optional
m_HelperDoNotStoreVBs
optional
m_HelperDoQueryVBs
optional
m_HelperDoStoreVBs
optional
m_HelperDoWeQuery
v 0: Do not use cache
v 1: Use cache
m_HelperDoWeStore
Integer
Indicates whether the
Helper Server stores
any replies from the
helpers in its database:
v 0: Do not store
replies in database
v 1: Store replies in
database
m_HelperLogfile
optional
368
IBM Tivoli Network Manager IP Edition: Discovery Guide
Text
The full path and file
for the logfile of the
current helper.
Table 110. snmpHelper.SnmpHelperConfig database table schema (continued)
Column name
Constraints
Data type
Description
m_HelperStartupTimeout
Long64
The default helper
startup timeout, that is,
the maximum time to
wait for a helper to
start up when
requested to.
m_HelperReqTimeout
Long64
The helper request
timeout, that is, how
long before each
request expires.
SNMP helper database configuration
The following insert provides an example configuration of the SNMP helper
database.
insert into SnmpHelper.SnmpHelperConfig
(
m_HelperDbTimeout,
m_HelperReqTimeout,
m_HelperStartupTimeout,
m_HelperDoWeQuery,
m_HelperDoWeStore
)
values
(
259200, 1200, 90, 0, 0
);
snmpHelper.SnmpHelperTable table
The snmpHelper.SnmpHelperTable database table configures the operation of the
SNMP helper.
The schema of the snmpHelper.SnmpHelperTable database table is described in the
following table.
Table 111. snmpHelper.SnmpHelperTable database table schema
Column name
Constraints
m_CommunitySuffix
Data type
Description
Text
The suffix to the
community string.
m_HostIp
NOT NULL
Text
IP address of the
device to
interrogate.
m_OID
NOT NULL
Atom
Object ID for the
Get request.
Appendix A. Discovery databases
369
Table 111. snmpHelper.SnmpHelperTable database table schema (continued)
Column name
Constraints
m_Protocol
Data type
Description
Integer
An integer
representation of
the IP protocol used
by the
presently-defined
zone:
v 1: IPv4
v 2: IPv4 that has
been through
network address
translation (NAT)
v 3: IPv6
Integer
m_RequestType
Type of request:
v 0: Get
v 1: GetNext
v 2: GetBulk
m_SnmpIndex
Atom
The index of the
Get request (if it is
a Get request).
RivHelperDbTimeToDie
Long64
How long the
requested
information is to
live within the
Helper Server.
Text
A key interface to
the databases of the
Helper Server for
Get requests.
Atom
The response data.
Text
A key interface to
the databases of the
Helper Server for
Reply requests.
RivHelperRequestGetKey
NOT NULL
RivHelperRequestOutput
RivHelperRequestReplyKey
v PRIMARY
KEY
v NOT
NULL
v UNIQUE
snmpFilter database
The snmpFilter database is automatically populated with information about
devices that have SNMP interface filters applied to them. You can also define
dependent SNMP interface filters in this database table.
Description
The snmpFilter database is defined in the NCHOME/etc/precision/
DiscoSnmpHelperSchema.cfg file.
370
IBM Tivoli Network Manager IP Edition: Discovery Guide
snmpFilter.instances database table
The snmpFilter.instances database table is used by the SNMP Helper to hold
cached data for devices for which filtered SNMP requests were made. This table is
automatically populated. You must not configure inserts into this table.
Schema
The snmpFilter.instances database table schema is described in the following table:
Table 112. snmpFilter.instances database table schema
Column name
Constraints
Data type
Description
m_HostIP
not null
text
The IP address of the device to which this
filter is applied.
m_FilterName
not null
text
The name of the filter from which the
instance list was generated.
m_InstanceFilterTables
not null
list type text
The list of the tables to which this interface
filter applies.
list type text
The list of instances for this device that
match the filter.
m_InstanceList
TelnetHelper database
The TelnetHelper database defines the operation of the Telnet helper.
Related reference:
“DiscoTelnetHelperSchema.cfg configuration file” on page 83
The DiscoTelnetHelperSchema.cfg configuration file defines the operation of the
Telnet helper, which returns the results of a Telnet operation into a specified
device.
TelnetHelper.configuration database table
The TelnetHelper.configuration table specifies the general rules for receiving
information from remote devices.
The TelnetHelper.configuration table is described in the following table.
Table 113. TelnetHelper.configuration database table schema
Column name
Constraints
Data type
Description
m_NumThreads
Integer
The number of threads to be used by the
helper. If you change this value, be sure
that your system is configured to allow
at least this number of concurrent Telnet
sessions.
m_TimeOut
Integer
The maximum time to wait for access to
a device (milliseconds).
m_Retries
Integer
The number of times to retry the device.
Appendix A. Discovery databases
371
TelnetHelper.deviceConfig database table
The TelnetHelper.deviceConfig table sets device-specific configuration options.
The TelnetHelper.deviceConfig table is described in the following table.
Table 114. TelnetHelper.deviceConfig database table schema
Column name
Constraints
m_ContinueCmd
Data
type
Text
Description
The response to send to the remote
device in order for it to continue the
paged output. This is usually set to
"y".
You must take care setting this value,
as some devices require a carriage
return after the command and some
do not. For maximum flexibility, a
return is not added by default. It must
be specified explicitly using a trailing
Ctrl-M in the string.
m_ContinueMsg
Text
The expected prompt from the remote
device between paged output; for
example, "Do you want to continue".
Regular expressions are valid entries.
m_IpOrSubNet
Text
The IP or fully qualified subnet
address of the device corresponding to
a particular configuration. If this is not
specified, the configuration is used as
the default subnet address.
m_NetMaskBits
Integer
The number of most significant bits in
the netmask. This number must be
specified if m_IpOrSubNet is specified.
m_PageLength
Integer
The output page length size. This is
set to 0 by default; that is, no paging.
If you set a page length size, you must
also insert a value into the
m_PageLengthCmd column in order to
set a page length command.
m_PageLengthCmd
Text
The command to issue in order to set
the output page length.
m_Protocol
Integer
An integer representation of the IP
protocol used by the presently-defined
zone:
v 1: IPv4
v 2: IPv4 that has been through
network address translation (NAT)
v 3: IPv6
372
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 114. TelnetHelper.deviceConfig database table schema (continued)
Column name
m_SysObjectId
Constraints
Data
type
Text
optional
Description
The sysObjectID MIB variable to
match for this configuration entry. The
entry with the longest OID match will
be the entry used. For example, if you
specify a value of 1.3.6.1.4.1.9.1 then
all devices with OIDs of the form
1.3.6.1.4.1.9.1.* will be matched. Cisco
IOS devices have OIDs of the form
1.3.6.1.4.1.9.1.*.
This field is ignored if m_IpOrSubNet
is specified.
m_TransmissionDelay
Integer
This option allows you to customize
the delay used by ncp_dh_telnet when
transmitting data to a device. This
may be useful if data loss or device
issues occur when using the default
transmission delay setting.
TelnetHelper.telnetHelperconfig database table
The TelnetHelper.telnetHelperconfig database table configures the operation of the
Telnet Helper.
The TelnetHelper.telnetHelperconfig database table is described in the following
table.
Table 115. TelnetHelper.telnetHelperconfig database table schema
Column name
Constraints
Data type
Description
m_HelperDbTimeout
UNIQUE
Long64
The helper database
timeout, that is, how long
before the database
expires.
Integer
Sets the debug level of the
helper, printing to
m_HelperLogfile.
Object type
varbinds
List of helper inputs that
do not query the database.
This field overrides
m_HelperDoWeQuery.
Object type
varbinds
List of helper inputs that
never store data in the
Helper Server databases.
This field overrides
m_HelperDoWeStore.
Object type
varbinds
List of helper inputs that
always query the database
before querying the
network. If the item is
found in the database
then the network is not
queried.
m_HelperDebugLevel
optional
m_HelperDoNotQueryVBs
optional
m_HelperDoNotStoreVBs
optional
m_HelperDoQueryVBs
optional
Appendix A. Discovery databases
373
Table 115. TelnetHelper.telnetHelperconfig database table schema (continued)
Column name
Constraints
m_HelperDoStoreVBs
optional
m_HelperDoWeQuery
Data type
Description
Object type
varbinds
List of helper inputs that
always store data in the
Helper Server database.
This field overrides
m_HelperDoWeStore.
Integer
Indicates whether the
Helper Server queries its
database or whether it
queries the network using
a helper:
v 0: Do not use cache
v 1: Use cache
m_HelperDoWeStore
Integer
Indicates whether the
Helper Server stores any
replies from the helpers in
its database:
v 0: Do not store replies
in database
v 1: Store replies in
database
Text
The full path and file for
the logfile of the current
helper.
m_HelperReqTimeout
Long64
The helper request
timeout, that is, how long
before each request
expires.
m_HelperStartupTimeout
Long64
The default helper
start-up timeout, that is,
the maximum time to
wait for a helper to start
up when requested.
m_HelperLogfile
optional
Telnet helper database configuration
The following example insert gives a typical configuration of the Telnet helper
database.
insert into TelnetHelper.TelnetHelperConfig
(
m_HelperDbTimeout,
m_HelperReqTimeout,
m_HelperStartupTimeout,
m_HelperDoWeQuery,
m_HelperDoWeStore
)
values
(
259200, 1200, 90, 0, 0
);
374
IBM Tivoli Network Manager IP Edition: Discovery Guide
TelnetHelper.telnetHelperTable database table
The TelnetHelper.telnetHelperTable database table configures the operation of the
Telnet helper.
The TelnetHelper.telnetHelperTable table is described in the following table.
Table 116. TelnetHelper.telnetHelperTable database table schema
Column name
Constraints
m_Protocol
Data type
Description
Integer
An integer
representation of the IP
protocol used by the
presently-defined zone:
v 1: IPv4
v 2: IPv4 that has been
through network
address translation
(NAT)
v 3: IPv6
Text
A unique request reply
key interface to the
databases of the Helper
Server.
Text
A request get key
interface to the
databases of the Helper
Server.
Long64
How long the requested
information is to live
within the Helper
Server.
Text
IP address of the device
to interrogate.
m_TelnetCommand
Text
The Telnet command.
RivHelperRequestOutput
Atom
The response data.
RivHelperRequestReplyKey
v PRIMARY
KEY
v NOT
NULL
v UNIQUE
RivHelperRequestGetKey
NOT NULL
RivHelperDbTimeToDie
m_HostIp
NOT NULL
XmlRpcHelper database
The XmlRpcHelper helper database is defined in NCHOME/etc/precision/
DiscoHelperServerSchema.cfg.
Related reference:
“DiscoXmlRpcHelperSchema.cfg configuration file” on page 86
The DiscoXmlRpcHelperSchema.cfg configuration file can be used to configure the
XML-RPC helper, which enables Network Manager to communicate with EMS
collectors using the XML-RPC interface.
Appendix A. Discovery databases
375
XmlRpcHelper.configuration table
The XmlRpcHelper.configuration database table configures the threads and timeout
for the XMLRPC helper.
The XmlRpcHelper.configuration database table must contain only one record. The
XmlRpcHelper.configuration database table is described in the following table.
Table 117. XmlRpcHelper.configuration database table schema
Column name
Constraints
Data type
Description
m_NumThreads
None
Integer
The number of threads to be used
by the helper.
m_TimeOut
None
Integer
The maximum time to wait for a
reply from an EMS collector, in
milliseconds. If you are running the
TraceRoute agent you may need to
increase this value, depending on
network conditions.
XmlRpcHelper.XmlRpcHelperConfig table
The XmlRpcHelper.XmlRpcHelperConfig helper database table configures the
operation of the XMLRPC Helper.
The schema of the XmlRpcHelper.XmlRpcHelperConfig database table is described
in the following table.
Table 118. XmlRpcHelper.XmlRpcHelperConfig database table schema
Column name
Constraints
Data type
Description
m_HelperDbTimeout
UNIQUE
Long64
The helper database timeout, that
is, how long before the database
expires.
Integer
Sets the debug level of the helper,
printing to the file specified in
m_HelperLogfile.
m_HelperDebugLevel
optional
m_HelperDoNotQueryVBs
optional
m_HelperDoNotStoreVBs
optional
m_HelperDoQueryVBs
optional
m_HelperDoStoreVBs
optional
376
IBM Tivoli Network Manager IP Edition: Discovery Guide
Object type List of helper inputs that do not
varbinds
query the database. This field
overrides m_HelperDoWeQuery.
Object type List of helper inputs that never
varbinds
store data in the Helper Server
databases. This field overrides
m_HelperDoWeStore.
Object type List of helper inputs that always
varbinds
query the database before querying
the network. If the item is found in
the database then the network is
not queried.
Object type List of helper inputs that always
varbinds
store data in the Helper Server
database. This field overrides
m_HelperDoWeStore.
Table 118. XmlRpcHelper.XmlRpcHelperConfig database table schema (continued)
Column name
m_HelperDoWeQuery
Constraints
Data type
Description
Integer
Indicates whether the Helper
Server queries its database or
whether it queries the network
using a helper:
v 0: Do not use cache
v 1: Use cache
Because each data item is requested
from the Collector only once,
caching is not usually enabled.
m_HelperDoWeStore
Integer
Indicates whether the Helper
Server stores any replies from the
helpers in its database:
v 0: Do not store replies in
database
v 1: Store replies in database
Because each data item is requested
from the Collector only once,
caching is not usually enabled.
Text
The full path and file for the logfile
of the current helper.
m_HelperReqTimeout
Long64
The helper request timeout that is,
how long before each request
expires.
m_HelperStartupTimeout
Long64
The default helper startup timeout,
that is, the maximum time to wait
for a helper to start up when
requested to.
m_HelperLogFile
optional
XmlRpcHelper.config database configuration
The following insert provides a typical example configuration of the
XmlRpcHelper database. This insert specifies the following settings:
v Helper database expires after 3 days.
v Each helper database request timeout expires after 20 minutes.
v Maximum time to wait for a helper to start up when requested is 90 seconds.
v Helper Server does not query its database.
v Helper Server does not store any replies from the helpers in its database.
insert into XmlRpcHelper.XmlRpcHelperConfig
(
m_HelperDbTimeout,
m_HelperReqTimeout,
m_HelperStartupTimeout,
m_HelperDoWeQuery,
m_HelperDoWeStore
)
values
(
259200,
1200,
Appendix A. Discovery databases
377
90,
0,
0
);
XmlRpcHelper.XmlRpcHelperTable table
The XmlRpcHelper.XmlRpcHelperTable configures the operation of the XMLRPC
helper.
The schema of the XmlRpcHelper.XmlRpcHelperTable database table is described
in the following table.
Table 119. XmlRpcHelper.XmlRpcHelperTable database table schema
Column name
Constraints
Data type
Description
Integer
Data source of interest.
Text
The IP address of the physical
device.
m_MethodCalled
Text
Method called.
m_MethodSignature
Integer
Method signature.
m_Port
Atom
Port of physical device.
RivHelperDbTimeToDie
Text
How long the requested
information is to live within the
Helper Server.
Text
A key interface to the databases
of the Helper Server for Get
requests.
Atom
Response data.
Text
A key interface to the databases
of the Helper Server for Reply
requests.
m_DataSourceId
m_Host
RivHelperRequestGetKey
NOT NULL
NOT NULL
RivHelperRequestOutput
RivHelperRequestReplyKey
v PRIMARY
KEY
v NOT
NULL
v UNIQUE
Tracking discovery databases
During the discovery process, the discovery engine, ncp_disco, records every
element discovered in the network, whether it has been processed or not. The
instrumentation and translations databases are used for this purpose. These
databases can be interrogated at any time to view the number of device types and
categories that have been discovered.
The translations, instrumentation, and workingEntities databases record the known
network entities and technologies, and can be used to track the progress of the
discovery.
378
IBM Tivoli Network Manager IP Edition: Discovery Guide
translations database
The translations database is defined in the $NCHOME/etc/precision/
DiscoSchema.cfg file. It has several fully qualified database table names.
The fully qualified database table names for the translations database are as
follows:
v translations.ipToBaseName
v translations.vlans
v translations.NAT
v translations.NATtemp
v translations.NATAddressSpaceIds
v specialManagementIPs
translations.ipToBaseName table
The ipToBaseName table is a registry of discovered devices and the IP addresses
associated with those devices.
When a device has multiple interfaces, and therefore multiple IP addresses, the
Associated Address agent downloads all the associated addresses, stores them in
the ipToBaseName table and allows the appropriate discovery agents to discover
the device. Any subsequent attempt to discover the device by means of another of
its IP addresses is halted when the Associated Address agent checks the
ipToBaseName table, that is, before the device details are passed to the appropriate
discovery agent.
Table 120. translations.ipToBaseName database table schema
Column name
Constraints
Data type
Description
m_BaseName
NOT NULL
Text
Base name of the discovered entity.
m_BaseAddress
NOT NULL
Text
Base address of the discovered entity.
m_WorkAddress
NOT NULL
Text
The address that was used for data
retrieval.
m_IpAddress
NOT NULL
Text
IP address of the entity.
m_AddressSpace
Text
The name of the NAT address space to
which the device belongs. This value is
set in the
translations.NATAddressSpaceIds table.
If the discovery is not using NAT, or if
the device is in the public domain, this
value is NULL.
m_InScope
Boolean
integer
Indicates whether the value of the field
m_IpAddress is in scope.
Integer
Protocol for this address. This field can
take the following values:
m_Protocol
NOT NULL
v 1: IPv4
v 3: IPv6
m_IsManagementIP
Boolean
integer
Indicates whether this is a management
IP address.
m_IsOutOfBand
Boolean
integer
Indicates whether this is an out of band
address.
m_Name
Text
Name of interface with IP if known.
Appendix A. Discovery databases
379
translations.vlans table
The vlans table holds a list of devices that are part of Virtual Local Area Networks
(VLANs). Each record in the vlans table maps the device to the VLAN to which it
belongs.
Table 121. translations.vlans database table schema
Column name
Constraints
Data type
m_Name
v PRIMARY KEY Text
v NOT NULL
m_VlanID
v PRIMARY KEY Text
v NOT NULL
Description
The name of the device
associated with this entry.
The VLAN identifier on the
device.
m_Subnet
Text
The subnet with which the VLAN
appears to be associated.
m_NetMask
Text
The subnet mask.
m_AddressSpace
Text
The name of the NAT address
space to which the device
belongs. This value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is
NULL.
translations.NAT table
The NAT table is used to hold static NAT mappings. The mapped devices are
discovered even if they are outside the scope of the discovery.
Table 122. translations.NAT database table schema
Column name
Constraints
Data
type
Description
m_OutsideGlobalAddr
v PRIMARY KEY
Text
The public address.
Text
The private address.
m_InsideGlobalAddr
Text
This column is currently not used.
m_OutsideLocalAddr
Text
This column is currently not used.
m_AddressSpace
Text
The name of the NAT address space
to which the device belongs. This
value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the public
domain, this value is NULL.
v NOT NULL
m_InsideLocalAddr
380
NOT NULL
IBM Tivoli Network Manager IP Edition: Discovery Guide
translations.NATtemp
The NATtemp table is used to hold NAT mappings from a particular NAT
gateway. This enables the discovery process to compare the old and new NAT
mappings and initiate a partial or full rediscovery if necessary.
Table 123. translations.NATtemp database table schema
Column name
Constraints
Data type Description
m_OutsideAddr
v PRIMARY
KEY
Text
The public address of the device.
Text
The private address of the device.
Text
The name of the NAT address space
to which the device belongs. This
value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the public
domain, this value is NULL.
v NOT NULL
m_InsideAddr
NOT NULL
m_AddressSpace
translations.NATAddressSpaceIds table
The NATAddressSpaceIds table is used to identify the IP addresses of NAT
gateways and specify an address-space identifier for each one.
Table 124. translations.NATAddressSpaceIds database table schema
Column name
Constraints
Data type Description
m_NATGatewayIP
v PRIMARY
KEY
Text
The IP address of the gateway.
Text
The address space identifier to be
used for all devices in the NAT
domain belonging to the gateway
whose IP address is specified in
m_NATGatewayIP.
v NOT NULL
m_AddressSpaceId
Related tasks:
“Defining address spaces for NAT gateways” on page 199
To specify the IP address of your NAT gateways and the address space identifier
you want to use for each associated NAT domain, edit DiscoConfig.cfg to create
or amend an insert into translations.NATAddressSpaceIds.
specialManagementIPs table
After the discovery processing phase, this table contains an entry for each IP
address that was in scope, based on the entries in the scope.special table.
Table 125. specialManagementIPs table
Column
Constraints
Data type
Description
m_IpAddress
Not null
Text
The IP address of the
entity.
m_WorkAddress
Not null
Text
The address that was
used for data
retrieval
Appendix A. Discovery databases
381
Table 125. specialManagementIPs table (continued)
Column
Constraints
Data type
Description
m_AdminInterfaceIP
Int type Boolean
Indicates whether the
address is an
interface, as defined
in the scope.special
table
m_IsManagementIP
Int type Boolean
Indicates whether the
address is a
management address,
as defined in the
scope.special table
m_ExtraInfo
Object type VB list
The extra information
that enriches the
target entity, as
defined in the
scope.special table.
m_AddressSpace
Text
The address space for
this IP as defined in
the ipToBaseName
table.
m_Identifier
Text
The identifier, as
defined in the
scope.special table.
m_Priority
Int
The priority, as
defined in the
scope.special table.
m_NonPingable
Int
Indicates whether the
address is selected
even if it cannot be
pinged, as defined in
the scope.special
table
m_UsedForChassis
Int
If 1then this IP
address was assigned
to be used as the
access address for a
chassis entity.
instrumentation database schema
The instrumentation database is defined in $NCHOME/etc/precision/
DiscoSchema.cfg. It lists discovered devices grouped by technology. You can do
OQL queries to retrieve the names of all discovered subnets, VLANs, Frame Relay
devices, and so on.
The fully qualified database table names for the instrumentation database are:
v instrumentation.ipAddresses
v instrumentation.name
v instrumentation.subNet
v instrumentation.vlan
v instrumentation.frameRelay
v instrumentation.ciscoFrameRelay
382
IBM Tivoli Network Manager IP Edition: Discovery Guide
v instrumentation.hsrp
v instrumentation.pnniPeerGroup
v instrumentation.fddi
instrumentation.ipAddresses table
The ipAddresses table contains a record of the unique IP addresses discovered in
the network.
Table 126. instrumentation.ipAddresses database table schema
Column name
Constraints
Data type
Description
m_UniqueAddress
v PRIMARY KEY
Text
The IP address of a discovered
network entity.
v NOT NULL
v UNIQUE
instrumentation.name table
The name table contains a record of the unique name of every discovered device.
Table 127. instrumentation.name database table schema
Column name
Constraints
Data type
Description
m_Name
v PRIMARY
KEY
Text
The name of a discovered network
entity.
v NOT NULL
v UNIQUE
instrumentation.subNet table
The subNet table contains a record of every discovered subnet address and mask.
Table 128. instrumentation.subNet database table schema
Column name
Constraints
Data type
Description
m_SubNet
v PRIMARY
KEY
Text
The subnet address of a discovered
subnet.
Text
The subnet mask of a discovered
subnet.
v NOT NULL
v UNIQUE
m_NetMask
v NOT NULL
v UNIQUE
instrumentation.vlan table
The vlan table contains a record of every discovered VLAN.
Table 129. instrumentation.vlan database table schema
Column name
Constraints
Data type
Description
m_Vlan
UNIQUE
Integer
The ID of the discovered VLAN.
Appendix A. Discovery databases
383
instrumentation.frameRelay table
The frameRelay table contains a record of every discovered Frame Relay device.
Table 130. instrumentation.frameRelay database table schema
Column name
Constraints
Data type
Description
m_IfDlci
v PRIMARY
KEY
Integer
The Frame Relay device Data Link
Connection Identifier.
Integer
The unique value for each device
interface.
v NOT NULL
v UNIQUE
m_IfIndex
v PRIMARY
KEY
v NOT NULL
instrumentation.ciscoFrameRelay table
The ciscoFrameRelay table contains a record of every discovered Cisco Frame
Relay device.
Table 131. instrumentation.ciscoFrameRelay database table schema
Column name
Constraints
Data type
Description
m_UniqueKey
v NOT NULL
Text
A combination of the IP Address, the
FRIfIndex, and the FRDlci.
Integer
The unique value for each device
interface.
Integer
The Frame Relay device Data Link
Connection Identifier.
v UNIQUE
m_FRIfIndex
v PRIMARY
KEY
v NOT NULL
m_FRDlci
v PRIMARY
KEY
v NOT NULL
v UNIQUE
instrumentation.hsrp table
The hsrp table contains a record of every discovered Hot Standby Router Protocol
(HSRP) device.
Table 132. instrumentation.hsrp database table schema
Column name
Constraints
Data type
Description
m_GroupAddress
v PRIMARY
KEY
Text
The group address of the
device.
m_PrimaryAddress
Text
The primary address of
the device.
m_StandbyAddress
Text
The standby address of
the device.
v NOT NULL
v UNIQUE
384
IBM Tivoli Network Manager IP Edition: Discovery Guide
instrumentation.pnniPeerGroup table
The pnniPeerGroup table contains the lowest level Peer Group Identifiers of PNNI
devices that have been discovered. Logical PNNI Peer Groups IDs are not stored.
Table 133. instrumentation.pnniPeerGroup database table schema
Column name
Constraints
Data type
Description
m_PeerGroupId
v PRIMARY
KEY
Text
The lowest level PNNI peer
group identifier.
v NOT NULL
v UNIQUE
instrumentation.fddi table
The fddi table contains the Fibre Distributed Data Interface (FDDI) nodes that have
been discovered.
Table 134. instrumentation.fddi database table schema
Column name
Constraints
Data type
Description
m_UniqueAddress
v PRIMARY
KEY
Text
The unique address of the
node.
Integer
The station management task
for that node.
v NOT NULL
m_StationManagmentTask
v PRIMARY
KEY
v NOT NULL
workingEntities database
The workingEntities database is defined in $NCHOME/etc/precision/
DiscoSchema.cfg. Its fully qualified database table names are:
workingEntities.finalEntity; workingEntities.containment.
The workingEntities database provides a central repository for information about
discovered entities and the containment details associated with each of these
entities. However, this database is populated only at the end of the discovery
process.
workingEntities.finalEntity table
The finalEntity table is a central repository for information about discovered
entities.
Table 135. workingEntities.finalEntity database table schema
Column name
Constraints
Data
type
Description
m_AddressSpace
Text
The name of the NAT address space
to which the device belongs. This
value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the public
domain, this value is NULL.
m_BaseName
Text
The name of the Base Entity for this
device.
Appendix A. Discovery databases
385
Table 135. workingEntities.finalEntity database table schema (continued)
Column name
Constraints
Data
type
m_Creator
NOT NULL
Text
Name of agent (or finder) that
discovered the entity.
Text
Description of the device, taken from
the sysDescr MIB variable for the
entity.
Integer
Element type description of the
discovered entity:
m_Description
m_EntityType
Externally
defined
entityType data
type
Description
v 0: Unknown type
v 1: Base entity
v 2: Local neighbor
v 3: Remote neighbor
m_ExtraInfo
Externally
defined vblist
data type
Object
Extra information requested by the
agent.
m_HaveAccess
Externally
defined Boolean
data type
Boolean Flag indicating whether SNMP access
integer to the device is available:
v 1: SNMP access is available
v 0: No SNMP Access
m_IsActive
Externally
defined Boolean
data type
Boolean Indicates whether the entity is active:
Integer v (2) Indicates that the entity is
discovered but is not in scope.
Entities that are not in scope are
not monitored by Network
Manager.
v (1) Entity is active.
v (0) Entity is inactive.
m_LocalNbr
Externally
defined vblist
data type
Object
Information about the local neighbor.
m_Name
v PRIMARY
KEY
Text
Unique name of the discovered
entity.
m_ObjectId
Text
Device class (a textual representation
of the ASN.1 address).
m_UniqueAddress
Text
IP address of the network entity.
v NOT NULL
v UNIQUE
386
IBM Tivoli Network Manager IP Edition: Discovery Guide
workingEntities.containment table
The containment table is a central repository for information about containment
information for discovered entities. It shows the containment relationships between
all entities in the finalEntity table.
As an example of how the containment table works, assume the finalEntity table
includes the following distinct entities:
v A device with IP address 1.2.3.4
v An interface on this device, 1.2.3.4[0[1]]
The finalEntity table provides no containment information for these two entities. In
other words, it does not indicate that the interface 1.2.3.4[0[1]] is physically
contained within the device 1.2.3.4. This containment information is held within
the containment table, as follows:
m_Container=’1.2.3.4’
m_Part=’1.2.3.4[0[1]]’
m_IsPhysical=1
m_LinkType=1
Note that m_Container and m_Part are each unique names of entities on the
network, each with a unique m_Name in the finalEntity table.
Table 136. workingEntities.containment database table schema
Column name
Constraints
Data type
m_Container
v PRIMARY KEY Text
v NOT NULL
m_Part
v PRIMARY KEY Text
v NOT NULL
m_IsPhysical
Boolean
integer
Description
The name of an object which contains
something. This object refers to an
entity on the network and
corresponds to an entity with its own
entry and unique m_Name in the
workingEntities.finalEntity table.
The name of the object which is
contained. This object refers to an
entity on the network and
corresponds to an entity with its own
entry and unique m_Name in the
workingEntities.finalEntity table.
Flag indicating whether the
containment is physical or logical:
v 1: Physical Containment
v 0: Logical Containment
m_LinkType
Integer
Value indicating mode of data
transfer between m_Container and
m_Part. The following values are
possible:
v 0: No data is transmitted.
v 1: Data is transmitted both ways.
v 2: Data travels from m_Container
to m_Part.
v 3: Data travels from m_Part to
m_Container
Appendix A. Discovery databases
387
workingEntities.interfaceMapping
The interfaceMapping table enables the stitching to quickly identify interfaces.
The following table lists the columns in the interfaceMapping table.
Note: Not all the fields in this table are populated; however, the use of this table
provides a fast way of looking up data.
Table 137. workingEntities.interfaceMapping database table schema
Column name
Constraints
Data type
Description
m_Name
not null
Text
Unique name of an interface on the
network.
m_IfIndex
Integer
SNMP ifIndex.
m_InterfaceId
Text
Interface identifier.
m_EntPhysIndex
Integer
Entity MIB physical Index if present.
Text
Interface RFC.ifDescr.
m_IfName
Text
Interface RFC ifName.
m_IfAlias
Text
Interface RFC ifAlias field.
m_IfType
Integer
Interface RFC ifType.
m_PhysAddress
Text
MAC address for this entity if
present.
Text
Name of the "Base Entity" for this
device.
Text
Name of the address space this
device is on. For public devices the
field is null.
m_IfDescr
m_BaseName
Not null
m_AddressSpace
dbModel database
The dbModel database maps custom discovery data from discovery agents to
NCIM tables.
The dbModel database is used for mapping data that hs been retrieved by
discovery agents to the appropriate tables in the NCIM topology database. It is
defined in the NCHOME/etc/precision/ModelNcimDB.cfg configuration file.
dbModel.access table
The dbModel.access table configures database access.
The following table shows the schema for the dbModel.access database table.
Table 138. dbModel.access database table schema
Column name
Constraints
Data type
Description
EnumGroupFilter
NOT NULL
Text
Lists the enumerations groups that contain
enumerations that can be used in the entity maps
defined in the dbModel.entityMap table. The
enumerations are defined in the enumerations
table in the NCIM topology database.
TransactionLength
NOT NULL
Integer
The number of SQL statements to execute within
a single transaction during topology upload
before committing.
388
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 138. dbModel.access database table schema
(continued)
Column name
Constraints
Data type
Description
WebTopDataSource
NOT NULL
Text
The name of the Webtop Datasource to use. This
value can be different from the ObjectServer
name.
DomainHost
Text
The hostname that Topoviz connects to. This is set
in the entry for ncp_config in the
ServiceData.cfg configuration file. This field
should be left blank unless you need to overwrite
this value.
DomainPort
Integer
The port that Topoviz connects to. This is set in
the entry for ncp_config in the ServiceData.cfg
configuration file. This field should be left blank
unless you need to overwrite this value.
Example: Using an enumeration group filter and entity map
In the workingEntities.finalEntity table, the OSPF interface type is stored in the
m_OspfIfState enumerated list, which is contained in the m_ExtraInfo field. The
value of the m_OspfIfState field is a single integer, for example, 3. m_OspfIfState
corresponds to ospfIfState in the NCIM topology database. The enumerations for
ospfIfState are defined for the enumGroup ospfIfType in the enumerations table in
the NCIM database, as shown in the following example output:
> select * from enumerations where enumGroup = ’ospfIfType’;
> go
+------------+---------+-------------------+-----------------+
| ENUMGROUP | ENUMKEY | ENUMVALUE
| ENUMDESCRIPTION |
+------------+---------+-------------------+-----------------+
| ospfIfType | 1
| broadcast
|
|
| ospfIfType | 2
| nbma
|
|
| ospfIfType | 3
| pointToPoint
|
|
| ospfIfType | 5
| pointToMultipoint |
|
+------------+---------+-------------------+-----------------+
The following example insert includes ospfIfType (shown here in bold type) in the
enumerations to be downloaded:
insert into dbModel.access
(
EnumGroupFilter,
TransactionLength,
WebTopDataSource
)
values
(
"enumGroup in (’ASN’ , ’sysServices’, ’ifAdminStatus’, ’ifOperStatus’,
’sysServices’, ’ifType’, ’ifOperStatusToOperationalStatus’,
’entPhysicalClass’, ’cefcFRUPowerAdminStatus’, ’cefcFRUPowerOperStatus’,
’TruthValue’,’TruthValueString’, ’entSensorType’, ’entSensorScale’,
’entSensorStatus’, ’cefcModuleAdminStatus’, ’cefcModuleOperStatus’,
’ipForwarding’, ’cefcPowerRedundancyMode’, ’EntityType’, ’ospfIfState’,
’ospfIfType’, ’dot3StatsDuplexStatus’, ’accessProtocol’, ’cdmDuplex’,
’OperationalStatusEnum’)",
500,
"NCOMS"
);
Appendix A. Discovery databases
389
The following example insert into the dbModel.entityMap database shows
m_ospfIfType (displayed in bold type) from the workingEntities.finalEntity table
being mapped to the ospfIfType column in the ospfEndPoint table in the NCIM
topology database.
insert into dbModel.entityMap
(
EntityFilter,
TableName,
FieldMap,
StitcherDefined
)
values
(
"m_ObjectId = ’OSPF_PROTOCOL_ENDPOINT’",
’ospfEndPoint’,
{
entityId
= "eval(int, ’&m_EntityId’)",
areaId
= "eval(text, ’&m_ExtraInfo->m_AreaId’)",
ospfIfAdminStat = "eval(int, ’&m_ExtraInfo->m_OspfIfAdminStat’)",
ospfIfState
= "eval(text, ’LOOKUP(&m_ExtraInfo->m_OspfIfState,
&&ospfIfState)’)",
ospfIfType = "eval(text, ’LOOKUP(&m_ExtraInfo->m_OspfIfType,
&&ospfIfType)’)",
defaultCost
= "eval(int, ’&m_ExtraInfo->m_Cost’)"
},
1
);
Because the enumeration for ospfIfType was downloaded, the integer value of
ospfIfType from the workingEntities.finalEntity table is mapped to a meaningful
string in the record in the NCIM topology database. For example, instead of 3, the
value for the interface type is stored as pointToPoint.
dbModel.entityDetails table
The dbModel.entityDetails table defines extra information to be added to the
EntityDetails table in the NCIM topology database.
The following table shows the schema for the dbModel.entityDetails database
table.
Table 139. dbModel.entityDetails database table schema
Column name
Constraints
Data type
Description
EntityType
Primary Key
Integer
Any entities of this type will have the
entityDetails field in NCIM enriched with the
fields from EntityDetails. A single insert is
allowed per entity type.
EntityDetails
NOT NULL
Object type
vblist
A list of key-value pairs that, if they are present,
are inserted into the EntityDetails table in the
NCIM topology database. Use this field to set
multiple values for the same entity type.
390
IBM Tivoli Network Manager IP Edition: Discovery Guide
dbModel.entityMap table
The dbModel.entityMap table defines how values are mapped from the discovery
workingEntities.finalEntity table to dNCIM and NCIM.
The NCHOME/etc/precision/ModelNcimDB.cfg configuration file contains example
inserts showing how to add data for new and existing entities.
The following table shows the schema for the dbModel.entityMap database table.
Table 140. dbModel.entityMap database table schema
Column name
Constraints
Data type
Description
EntityFilter
NOT NULL
Text
The filter to apply to the contents of the
workingEntities.finalEntity database table. Any
entity matching the filter has the entityMap
applied to it.
TableName
NOT NULL
Text
The name of table to be populated in dNCIM or
NCIM.
Text
Evaluated in the same way as FieldMap.
Populates the entityData.displayLabel field for
different types of entity.
Object of type
vblist
Maps the fields of the table defined by the
TableName value to the evaluation against the data
from the workingEntities.finalEntity database
table.
Connection
Object of type
vblist
This field is not used.
Relationships
Object of type
vblist
List of relationships that this entity has with other
entities. For example, if it connects or contains
other entities.
Iterators
Object of type
vblist
Used to iterate over lists in the OQL record.
ImplicitEntities
Object of type
vblist
Defines any new entities to be created in NCIM
that are not explicitly represented in ncp_model.
StitcherDefined
Boolean integer If this is 1, then the mapping is done by the
stitchers and not by this table. By default, this
value is 0.
DisplayLabel
FieldMap
NOT NULL
Related tasks:
“Mapping retrieved data to DNCIM custom data tables” on page 286
Specify how custom data from the discovery should be stored in the topology
database by mapping the custom data to the custom tables added to dNCIM and
NCIM.
Appendix A. Discovery databases
391
Working topology databases
The discovery engine, ncp_disco, uses a series of databases to perform the data
processing stages of the discovery cycle. Stitchers operate on these databases to
knit together a network topology and create the containment model.
The stitchers produce the various network topologies, such as layer 2 and layer 3
topologies, by amalgamating the information in the discovery agents returns tables
into a single cumulative topology within the fullTopology database.
fullTopology database schema
The fullTopology database is defined in $NCHOME/etc/precision/
DiscoSchema.cfg. Its fully qualified database table name is
fullTopology.entityByNeighbor.
The fullTopology database holds the generated topology. On completion of the
data collection phase of the discovery, the stitchers merge the information that has
been retrieved by the discovery agents to form a single topology, which at this
stage is in a name-to-name format.
fullTopology.entityByNeighbor table
The entityByNeighbor table contains information about connectivity between
discovered devices.
Table 141. fullTopology.entityByNeighbor database table schema
Column name
Constraints
Data type
Description
m_Name
v PRIMARY
KEY
Text
Unique name of an entity on the
network.
Text
The name of the device that is
connected to the unique network
entity.
Integer
Integer representation of the type of
connection between the network
entity and its neighbor:
v NOT NULL
m_NbrName
v PRIMARY
KEY
v NOT NULL
m_NbrType
Externally
defined
connectionType
data type
v 2: Main-to-Local
v 3: Local-to-Remote
dNCIM schema
The dNCIM database holds the containment model that is derived from the
workingEntities.finalEntity, workingEntities.containment and layer tables, mainly
fullTopology.entityByNeighbor. The model is built by the stitchers located in the
dNCIM subdirectory, $NCHOME/precision/disco/stitchers/DNCIM. This is the
version of the topology that is sent to the ncp_model component
The dNCIM database contains the same tables as the NCIM topology database.
These NCIM tables hold topology information about the network In addition,
dNCIM contains extra tables that store processing data as the topology is being
built.
392
IBM Tivoli Network Manager IP Edition: Discovery Guide
rediscoveryStore database
The rediscoveryStore database is used for comparison purposes in rediscovery
mode. It is defined in $NCHOME/etc/precision/ DiscoSchema.cfg. Its fully
qualified database table names are: rediscoveryStore.dataLibrary;
rediscoveryStore.rediscoveredEntities
The rediscoveryStore database holds information from previous discovery cycles
that can be used for comparison purposes during a full or partial rediscovery.
rediscoveryStore.dataLibrary table
The dataLibrary table is used as a reference point during rediscovery mode to
compare the previous and present states.
Table 142. rediscoveryStore.dataLibrary database table schema
Column name
Constraints
Data type
Description
m_Name
Text
Unique name of an entity on the
network.
m_UniqueAddress
Text
The IP address of a discovered
network entity.
Text
The entity that is used to compare
this network entity.
NOT NULL
m_CompareDb
rediscoveryStore.rediscoveredEntities table
The rediscoveredEntites table stores entities found during a rediscovery.
Table 143. rediscoveryStore.rediscoveredEntities database table schema
Column name
Constraints
Datatype
Description
m_Name
Text
Unique name of an entity on the
network.
m_UniqueAddress
Text
The IP address of a discovered
network entity.
m_PhysAddr
Text
The physical address of the entity.
m_OldBaseName
The base name of the entity prior
to rediscovery
m_NewBaseName
The base name of the entity after
rediscovery.
Topology manager databases
On completion of a discovery, ncp_model receives topology updates from dNCIM,
and based on these updates, generates the necessary inserts to update the NCIM
database. The Topology Manager also broadcasts these changes to other processes
in Network Manager.
Appendix A. Discovery databases
393
ncimCache database
This database stores topology updates from DNCIM.
The ncimCache database is created by ncp_model. The ncp_model process sends
topology updates on the message bus to all subscribers in the format of this
database. The ncp_g_event and ncp_store processes subscribe to topology updates
and keep a copy of the ncimCache database.
The Event Gateway stitchers use data from the ncimCache database.
You can query the ncimCache database tables on the service model.
ncimCache.collects table
The ncimCache.collects table lists all the entities participating in a given collection.
The following table shows the schema for the ncimCache.collects database table.
Table 144. ncimCache.collects database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
collectingEntityID in the collects table in the
NCIM database.
ENTITYNAME
NOT NULL
String
The name of the collecting entity.
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
MSGTYPE
collects
NOT NULL
v ENTITYNAME corresponds to
collectedEntityID in the collects table in the
NCIM database.
v SEQUENCE corresponds to sequence in the
collects table in the NCIM database.
Format of the data in the ncimCache.collects database table
The following example shows the format of the data in the ncimCache.collects
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.collects.DOMAIN file.
{
ENTITYID=31051;
ENTITYNAME=’SUBNET_OBJECT / 192.168.232.24 / 30 /’;
MSGTYPE=’collects’;
collects=[
{
ENTITYNAME=’some-device.1[ 0 [ 33 ] ]’;
SEQUENCE=0;
},
{
ENTITYNAME=’some-device.2[ 0 [ 25 ] ]’;
SEQUENCE=0;
}
];
}
394
IBM Tivoli Network Manager IP Edition: Discovery Guide
ncimCache.connectActions table
The ncimCache.connectActions table lists all changes made manually to
connections in the topology.
The following table shows the schema for the ncimCache.connectActions database
table.
Table 145. ncimCache.connectActions database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to the
aEndEntityId in the connectActions table in the
NCIM database.
ENTITYNAME
NOT NULL
String
The name of the entity.
MANUAL
Boolean
If the connection was added manually to the
topology, this value is present and set to 1.
MSGTYPE
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity. All
names correspond to the column names in the
connectActions table in the NCIM database.
connectActions
NOT NULL
Format of the data in the ncimCache.connectActions database table
The following example shows the format of the data in the
ncimCache.connectActions database table, as shown either using an OQL query, or
as seen in the NCHOME/var/precision/
Store.Cache.ncimCache.connectActions.DOMAIN file.
{
ENTITYID=60857;
ENTITYNAME=’MyManualDevice’;
MANUAL=1;
MSGTYPE=’connectActions’;
connectActions=[
{
ACTION=’add’;
AENDENTITYNAME=’MyManualDevice’;
CHANGETIME=’2013-07-08 11:50:58’;
CONNECTACTIONSID=61;
DESCRIPTION=’’;
LOCATION=’192.168.78.108’;
MANUAL=1;
TOPOENTITYNAME=’Layer1Topology’;
UNIDIRECTIONAL=0;
USERNAME=’defaultWIMFileBasedRealm/itnmadmin’;
ZENDENTITYNAME=’bungle’;
}
];
}
Appendix A. Discovery databases
395
ncimCache. connectstable
The ncimCache.connects table describes the type and speed of connections between
devices.
The following table shows the schema for the ncimCache.connects database table.
Table 146. ncimCache.connects database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to the
aEndEntityId in the connects table in the NCIM
database.
ENTITYNAME
NOT NULL
String
The name of the aEndEntityId device.
MANUAL
Boolean
If the connection was added manually to the
topology, this value is present and set to 1.
MSGTYPE
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the connection.
connectSpeeds
NOT NULL
ENTITYNAME
The name of the zEndEntityId device in
the connects table in the NCIM database.
SPEEDTYPE
Corresponds to speedType in the
connectSpeeds table in the NCIM
database.
SPEEDVALUE
Corresponds to speedValue in the
connectSpeeds table in the NCIM
database.
UNIDIRECTIONAL
Corresponds to unidirectional in the
connects table in the NCIM database.
connects
NOT NULL
List of
name/value
pairs
A list of name/value pairs for the connection.
ENTITYNAME
Corresponds to zEndEntityID in the
connects table in the NCIM database.
MANUAL
This value is 1 if the connection was
manually added. The connection can be
between discovered devices, manually
added devices, or both. If the connection
was not manually added, this
name/value pair is not present.
TOPOENTITYNAME
Corresponds to entityId in the
topologyLinks table in the NCIM
database.
UNIDIRECTIONAL
Corresponds to unidirectional in the
connects table in the NCIM database.
396
IBM Tivoli Network Manager IP Edition: Discovery Guide
Format of the data in the ncimCache.connects database table
The following example shows the format of the data in the ncimCache.connects
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.connects.DOMAIN file.
{
ENTITYID=42795;
ENTITYNAME=’mydevice[ 0 [ 25 ] ]’;
MSGTYPE=’connects’;
connectSpeeds=[
{
ENTITYNAME=’’mydevice[ 0 [ 33 ] ]’;
SPEEDTYPE=’DEFAULT’;
SPEEDVALUE=100000000;
UNIDIRECTIONAL=0;
}
];
connects=[
{
ENTITYNAME=’’mydevice[ 0 [ 33 ] ]’;
TOPOENTITYNAME=’IpPathTopology’;
UNIDIRECTIONAL=0;
},
{
ENTITYNAME=’’mydevice[ 0 [ 33 ] ]’;
TOPOENTITYNAME=’RouterLinksTopology’;
UNIDIRECTIONAL=0;
},
{
ENTITYNAME=’’mydevice[ 0 [ 33 ] ]’;
TOPOENTITYNAME=’RelatedToTopology’;
UNIDIRECTIONAL=0;
},
{
ENTITYNAME=’’mydevice[ 0 [ 33 ] ]’;
TOPOENTITYNAME=’ConvergedTopology’;
UNIDIRECTIONAL=0;
}
];
}
ncimCache. containstable
The ncimCache.contains table lists containment information for a device.
The following table shows the schema for the ncimCache.contains database table.
Table 147. ncimCache.contains database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
containingEntityID in the contains table in the
NCIM database.
ENTITYNAME
NOT NULL
String
The name of the collecting entity.
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
MSGTYPE
contains
NOT NULL
v ENTITYNAME is the collectedEntityID in the
contains table in the NCIM database.
v UPWARDCONNECTION corresponds to
upwardConnection in the contains table in the
NCIM database.
Appendix A. Discovery databases
397
Format of the data in the ncimCache.contains database table
The following example shows the format of the data in the ncimCache.contains
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.contains.DOMAIN file.
{
ENTITYID=40892;
ENTITYNAME=’my-device.mylab’;
MSGTYPE=’contains’;
contains=[
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[
UPWARDCONNECTION=1;
},
398
IBM Tivoli Network Manager IP Edition: Discovery Guide
0 [ 31 ] ]’;
0 [ 19 ] ]’;
0 [ 20 ] ]’;
0 [ 22 ] ]’;
0 [ 23 ] ]’;
0 [ 24 ] ]’;
0 [ 25 ] ]’;
0 [ 26 ] ]’;
0 [ 27 ] ]’;
0 [ 28 ] ]’;
0 [ 30 ] ]’;
0 [ 33 ] ]’;
0 [ 35 ] ]’;
0 [ 37 ] ]’;
{
ENTITYNAME=’my-device.mylab[ 0 [ 39 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 41 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 43 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 45 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 46 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 47 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 21 ] ]’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab_SLOT_I2_R0’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab_SLOT_I12_R1’;
UPWARDCONNECTION=1;
},
{
ENTITYNAME=’my-device.mylab_SLOT_I32_R2’;
UPWARDCONNECTION=1;
}
];
}
ncimCache.dependency table
The ncimCache.dependency table lists entities that are dependent on other devices.
The following table shows the schema for the ncimCache.dependency database
table.
Table 148. ncimCache.dependency database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to the
independentEntityID in the dependency table in
the NCIM database.
ENTITYNAME
NOT NULL
String
The name of the independent entity.
String
The name of the table within the ncimCache
database.
MSGTYPE
Appendix A. Discovery databases
399
Table 148. ncimCache.dependency database table schema
(continued)
Column name
Constraints
Data type
Description
dependency
NOT NULL
List of
name/value
pairs
A list of name/value pairs for dependent entities.
v DEPENDENCYTYPE corresponds to
dependencyType in the dependency table in the
NCIM database.
v ENTITYNAME corresponds to
dependentEntityID in the dependency table in
the NCIM database.
Format of the data in the ncimCache.dependency database table
The following example shows the format of the data in the ncimCache.dependency
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.dependency.DOMAIN file.
In this example, the cell depends on the base station.
{
ENTITYID=60844;
ENTITYNAME=’baseStation12’;
MSGTYPE=’dependency’;
dependency=[
{
DEPENDENCYTYPE=0;
ENTITYNAME=’Cell-01’;
}
];
}
ncimCache.domainMembers table
The ncimCache.domainMembers table shows the domain to which an entity
belongs.
The following table shows the schema for the ncimCache.domainMembers
database table.
Table 149. ncimCache.domainMembers database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
entityId in the domainMembers table in the NCIM
database.
ENTITYNAME
NOT NULL
String
The name of the entity.
MANUAL
Boolean
If the entity was added manually to the topology,
this value is present and set to 1.
MSGTYPE
String
The name of the table within the domainMembers
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
domainMembers
400
NOT NULL
IBM Tivoli Network Manager IP Edition: Discovery Guide
v DOMAINNAME corresponds to domainMgrId
in the domainMembers table in the NCIM
database.
Format of the data in the ncimCache.domainMembers database table
The following example shows the format of the data in the
ncimCache.domainMembers database table, as shown either using an OQL query,
or as seen in the NCHOME/var/precision/
Store.Cache.ncimCache.domainMembers.DOMAIN file.
{
ENTITYID=42739;
ENTITYNAME=’my-device.mylab[ 0 [ 33 ] ]’;
MSGTYPE=’domainMembers’;
domainMembers=[
{
DOMAINNAME=’DOMAIN1’;
}
];
}
ncimCache.entityActions table
The ncimCache.entityActions table lists all devices added using the manual
topology API.
The following table shows the schema for the ncimCache.entityActions database
table.
Table 150. ncimCache.entityActions database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
entityID in the entityActions table in the NCIM
database.
ENTITYNAME
NOT NULL
String
The name of the entity.
MSGTYPE
String
The name of the table within the ncimCache
database.
MANUAL
Boolean
This value is always 1, showing that the device
was added manually to the topology.
List of
name/value
pairs
A list of name/value pairs for the entity. All
names correspond to the column names in the
entityActions table in the NCIM database.
entityActions
NOT NULL
Format of the data in the ncimCache.entityActions database table
The following example shows the format of the data in the
ncimCache.entityActions database table, as shown either using an OQL query, or as
seen in the NCHOME/var/precision/Store.Cache.ncimCache.entityActions.DOMAIN
file.
{
ENTITYID=60857;
ENTITYNAME=’MyManualDevice’;
MANUAL=1;
MSGTYPE=’entityActions’;
entityActions={
ACTION=’add’;
CHANGETIME=’2013-07-08 11:50:31’;
DESCRIPTION=’’;
DOMAINNAME=’STEPH’;
ENTITYACTIONSID=106;
ENTITYID=60857;
ENTITYNAME=’MyManualDevice’;
Appendix A. Discovery databases
401
LOCATION=’192.168.78.108’;
MANUAL=1;
USERNAME=’defaultWIMFileBasedRealm/itnmadmin’;
};
}
ncimCache.entityData table
The ncimCache.entityData table holds different kinds of data about entities.
The following table shows the schema for the ncimCache.entityData database table.
Table 151. ncimCache.entityData database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to the
entityId in the entityData table in the NCIM
database.
ENTITYNAME
NOT NULL
String
The name of the entity.
MANUAL
Boolean
If the entity was added manually to the topology,
this value is present and set to 1.
MSGTYPE
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity,
corresponding to the entityData table in NCIM.
This section contains a separate row per entity in
the entityData table. The information that is
included here depends on the type of the entity.
For example, a chassis has different information
available than an interface.
List of
name/value
pairs
The lists of name/value pairs depend on the
information that is available for the entity. The
name of the list corresponds to the equivalent
database table in NCIM.
entityData
Other table names
NOT NULL
Format of the data in the ncimCache.entityData database table for a
chassis
The following example shows the format of the data in the ncimCache.entityData
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.entityData.DOMAIN file.
This example shows data for a chassis, corresponding to the classMembers,
computerSystem, discoverySource, entityData, operatingSystem, physicalChassis,
and snmpSystem tables in NCIM.
{
BASENAME=’xx-xx-xxnn.xx.test.lab’;
ENTITYID=40892;
ENTITYNAME=’xx-xx-xxnn.xx.test.lab’;
ENTITYTYPE=1;
METACLASS=’Element’;
MSGTYPE=’entityData’;
classMembers={
CLASSID=33;
ENTITYID=99999;
};
computerSystem={
ENTITYID=99999;
};
402
IBM Tivoli Network Manager IP Edition: Discovery Guide
discoverySource=[
{
DISCOVERYPROTOCOL=’SNMP’;
ENTITYID=40892;
MANAGEDBY=’DirectAccess’;
SOURCE=’Agent’;
}
];
entityData={
CDMADMINSTATE=0;
CHANGETIME=’2013-06-26 14:21:10’;
CREATETIME=’2013-06-26 14:21:10’;
DESCRIPTION=’Cisco IOS Software, 2800 Software (C2800NM-ADVIPSERVICESK9-M),
Version 12.4(24)T7, RELEASE SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2012 by Cisco Systems, Inc.
Compiled Tue 28-Feb-12 10:43 by prod_rel_team’;
DISPLAYLABEL=’xx-xx-xxnn.xx.test.lab’;
ENTITYID=40892;
ENTITYNAME=’xx-xx-xxnn.xx.test.lab’;
ENTITYTYPE=1;
MAINNODEENTITYID=40892;
MANUAL=0;
};
operatingSystem={
ENTITYID=40892;
};
physicalChassis={
ACCESSIPADDRESS=’192.168.233.103’;
ACCESSPROTOCOL=’IPv6’;
CDMTYPE=2;
CLASSNAME=’Cisco28xx’;
ENTITYID=40892;
FWREVISION=’System Bootstrap, Version 12.4(1r) [hqluong 1r],
RELEASE SOFTWARE (fc1)’;
HWREVISION=’V02 ’;
INTERFACECOUNT=47;
ISIPFORWARDING=’forwarding’;
MANUFACTURER=’Cisco’;
MODEL=’CISCO2811
’;
NAME=’2811 chassis’;
PARTNUMBER=’CISCO2811
’;
PHYSICALINDEX=1;
RELATIVEPOSITION=-1;
SERIALNUMBER=’XXXXXXXXXXXX’;
SERVICES=’datalink(2) network(3) transport(4) application(7)’;
SWREVISION=’12.4(24)T7, RELEASE SOFTWARE (fc2)’;
VENDORTYPE=’1.3.6.1.4.1.9.12.3.1.3.436’;
};
snmpSystem={
ENTITYID=40892;
SYSCONTACT=’example@example.com’;
SYSDESCR=’Cisco IOS Software, 2800 Software (C2800NM-ADVIPSERVICESK9-M),
Version 12.4(24)T7, RELEASE SOFTWARE (fc2)
Technical Support: http://www.cisco.com/techsupport
Copyright (c) 1986-2012 by Cisco Systems, Inc.
Compiled Tue 28-Feb-12 10:43 by prod_rel_team’;
SYSLOCATION=’B510/3D32 3rd Floor Lab’;
SYSNAME=’xx-xx-xxnn.xx.test.lab’;
SYSOBJECTID=’1.3.6.1.4.1.9.1.576’;
};
}
Appendix A. Discovery databases
403
Format of the data in the ncimCache.entityData database table for an
interface
The following example shows the format of the data in the ncimCache.entityData
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.entityData.DOMAIN file.
This example shows data for a network interface, corresponding to the entityData,
networkInterface, and physicalConnector tables in NCIM.
{
BASENAME=’my-device1.mylab’;
CONNECTIONS=[’my-device2.mylabb[ 0 [ 25 ] ]’];
ENTITYID=42739;
ENTITYNAME=’my-device1.mylab[ 0 [ 33 ] ]’;
ENTITYTYPE=2;
METACLASS=’Element’;
MSGTYPE=’entityData’;
entityData={
CDMADMINSTATE=2;
CHANGETIME=’2013-06-26 14:21:24’;
CREATETIME=’2013-06-26 14:21:24’;
DISPLAYLABEL=’[ IfIndex:33 ]’;
ENTITYID=42739;
ENTITYNAME=’my-device1.mylab[ 0 [ 33 ] ]’;
ENTITYTYPE=2;
MAINNODEENTITYID=40892;
MANUAL=0;
};
networkInterface={
ACCESSIPADDRESS=’2222:22a:2a2e:222::22’;
ACCESSPROTOCOL=’IPv6’;
CONNECTORPRESENT=’false’;
ENTITYID=42739;
IFADMINSTATUS=’up’;
IFALIAS=’to my-device’;
IFDESCR=’Vlan25’;
IFHIGHSPEED=100;
IFINDEX=33;
IFNAME=’Vl25’;
IFOPERSTATUS=’up’;
IFSPEED=100000000;
IFTYPE=53;
IFTYPESTRING=’propVirtual’;
MTU=1500;
OPERATIONALDUPLEX=’Unknown’;
OPERATIONALSTATUS=’started’;
PHYSICALADDRESS=’00:22:22:22:22:22’;
PROMISCUOUS=’false’;
};
physicalConnector={
CDMTYPE=9;
ENTITYID=42739;
};
}
Format of the data in the ncimCache.entityData database table for a
connection
The following example shows the format of the data in the ncimCache.entityData
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.entityData.DOMAIN file.
404
IBM Tivoli Network Manager IP Edition: Discovery Guide
This example shows data for an IP connection, corresponding to the entityData and
ipConnection tables in NCIM.
{
BASENAME=’my-device1.mylab[ 0 [ 33 ] ]->my-device2.mylab[ 0 [ 25 ] ]’;
ENTITYID=50401;
ENTITYNAME=’my-device1.mylab[ 0 [ 33 ] ]->my-device2.mylab[ 0 [ 25 ] ]’;
ENTITYTYPE=40;
METACLASS=’Element’;
MSGTYPE=’entityData’;
entityData={
CDMADMINSTATE=0;
CHANGETIME=’2013-07-03 10:46:35’;
CREATETIME=’2013-07-03 10:46:35’;
DESCRIPTION=’Sequential Hop between my-device1.mylab[ 0 [ 33 ] ] and
my-device2.mylab[ 0 [ 25 ] ]’;
DISPLAYLABEL=’my-device.mylab[ 0 [ 33 ] ]->my-device2.mylab[ 0 [ 25 ] ]’;
ENTITYID=50401;
ENTITYNAME=’my-device1.mylab[ 0 [ 33 ] ]->my-device2.mylab[ 0 [ 25 ] ]’;
ENTITYTYPE=40;
MANUAL=0;
};
ipConnection={
ENTITYID=50401;
};
}
ncimCache.hostedService table
The ncimCache.hostedService table maps a main node device, the hosting entity, to
the service or applications that are running on that device, the hosted entities. The
hostedService table belongs to the category entities.
The following table shows the schema for the ncimCache.hostedService database
table.
Table 152. ncimCache.hostedService database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
hostingEntityId in the hostedService table in the
NCIM database.
ENTITYNAME
NOT NULL
String
The name of the hosting entity.
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the hosted entity.
MSGTYPE
hostedService
NOT NULL
v ENTITYNAME corresponds to hostedEntityID
in the hostedService table in the NCIM
database.
Format of the data in the ncimCache.hostedService database table
The following example shows the format of the data in the
ncimCache.hostedService database table, as shown either using an OQL query, or
as seen in the NCHOME/var/precision/
Store.Cache.ncimCache.hostedService.DOMAIN file.
{
ENTITYID=8734;
ENTITYNAME=’router3.ibm.com’;
MSGTYPE=’hostedService’;
hostedService=[
Appendix A. Discovery databases
405
{
ENTITYNAME=’OSPF_RoutingService_ID_192.168.34.21_RD_[0]’;
}
];
}
ncimCache.lingerTime table
The ncimCache.lingerTime table stores the linger time for a device.
The following table shows the schema for the ncimCache.lingerTime database
table.
Table 153. ncimCache.lingerTime database table schema
Column name
Constraints
Data type
BASENAME
Description
The base name of this entity.
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
entityId in the lingerTime table in the NCIM
database.
ENTITYNAME
NOT NULL
String
The name of the entity.
ENTITYTYPE
The type of the entity, as enumerated in the
entityType NCIM table.
MSGTYPE
lingerTime
NOT NULL
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
LINGERTIME
The linger time is the number of
discoveries that a device can fail to be
found in before it is removed from the
topology.
The linger time is set for a device when
it is instantiated, from the default value
in the model.config table. Each time that
a device in the topology is not
discovered, the linger time is decreased
by 1. When the linger time is zero, if the
device is not discovered, it is removed
from the topology.
Format of the data in the ncimCache.lingerTime database table
The following example shows the format of the data in the ncimCache.lingerTime
database table, as shown either using an OQL query, or as seen in the
NCHOME/var/precision/Store.Cache.ncimCache.lingerTime.DOMAIN file.
{
BASENAME=’somedevice.mylab’;
ENTITYID=40892;
ENTITYNAME=’somedevice.mylab’;
ENTITYTYPE=1;
MSGTYPE=’lingerTime’;
lingerTime={
LINGERTIME=2;
};
}
406
IBM Tivoli Network Manager IP Edition: Discovery Guide
ncimCache.managedStatus table
The ncimCache.managedStatus table stores the managed status information for
network entities.
The following table shows the schema for the ncimCache.managedStatus database
table.
Table 154. ncimCache.managedStatus database table schema
Column name
Constraints
Data type
BASENAME
Description
The name of the base entity for this device.
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to entityID in the
managedStatus table in the NCIM database.
ENTITYNAME
NOT NULL
String
The name of the entity.
ENTITYTYPE
The type of the entity.
MANUAL
Boolean
If the entity was added manually to the topology, this value
is present and set to 1.
MSGTYPE
String
The name of the table within the ncimCache database.
List of
name/value
pairs
A list of name/value pairs for the entity.
managedStatus
NOT NULL
STATUS
The managed status of an entity can be one of the
following values:
0
Managed state. The entity is managed. A
device can be set to managed by using the
Topoviz or the Structure Browser GUIs, or
by using the ManagedNode.pl or
RemoveNode.pl scripts.
1
Unmanaged state. The entity is
unmanaged. A device can be set to
unmanaged by using the Topoviz or the
Structure Browser GUIs, or by using the
UnManagedNode.pl or RemoveNode.pl
scripts.
2
Unmanaged by ncp_disco. This setting
cannot be modified from the GUI. This
value is set by the
PopulateDNCIM_ManagedStatus.stch
stitcher.
Unmanaged because the IP address is out
of the discovery scope. The device has
been discovered through another IP
address that is within the discovery scope.
A managed status of 3 is usually given to
interfaces, rather than chassis. This value
is set by the
PopulateDNCIM_ManagedStatus.stch
stitcher.
Note: Unmanaged entities do not suppress other
events in RCA. The ncp_poller process does not
poll unmanaged entities. Events on unmanaged
entities have the field NmosManagedStatus set in
the alerts.status field in the ObjectServer.
3
Appendix A. Discovery databases
407
Format of the data in the ncimCache.managedStatus database table
The following example shows the format of the data in the
ncimCache.managedStatus database table, as shown either using an OQL query, or
as seen in the NCHOME/var/precision/
Store.Cache.ncimCache.managedStatus.DOMAIN file.
{
BASENAME=’somedevice’;
ENTITYID=42766;
ENTITYNAME=’somedevice[ 0 [ 47 ] ]’;
ENTITYTYPE=2;
MSGTYPE=’managedStatus’;
managedStatus={
STATUS=1;
};
}
ncimCache.networkPipe table
The ncimCache.networkPipe table represents managed connections.
The following table shows the schema for the ncimCache.networkPipe database
table.
Table 155. ncimCache.networkPipe database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
collectingEntityID in the networkPipe table in the
NCIM database.
ENTITYNAME
NOT NULL
String
The name of the collecting network pipe.
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
MSGTYPE
networkPipe
NOT NULL
v AENDENTITYNAME corresponds to entityId
in the networkPipe table in the NCIM database.
v AGGREGATIONTYPE corresponds to
aggregationType in the networkPipe table in
the NCIM database.
v UNIDIRECTIONAL corresponds to
unidirectional in the connects table in the
NCIM database.
v ZENDENTITYNAME corresponds to
zEndEntityId in the connects table in the
NCIM database.
Format of the data in the ncimCache.networkPipe database table
The following example shows the format of the data in the
ncimCache.networkPipe database table, as shown either using an OQL query, or as
seen in the NCHOME/var/precision/Store.Cache.ncimCache.networkPipe.DOMAIN file.
{
ENTITYID=50401;
ENTITYNAME=’my-device.mylab[ 0 [ 33 ] ]->my-device2.lab[ 0 [ 25 ] ]’;
MSGTYPE=’networkPipe’;
networkPipe=[
{
AENDENTITYNAME=’my-device2.lab[ 0 [ 25 ] ]’;
408
IBM Tivoli Network Manager IP Edition: Discovery Guide
AGGREGATIONTYPE=4;
UNIDIRECTIONAL=0;
ZENDENTITYNAME=’my-device.mylab[ 0 [ 33 ] ]’;
}
];
}
ncimCache.pipeComposition table
The ncimCache.pipeComposition table can be used with the networkPipe table to
represent a hierarchy of connections.
The following table shows the schema for the ncimCache.pipeComposition
database table.
Table 156. ncimCache.pipeComposition database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of the containing network pipe.
Corresponds to groupComponent in the
pipeComposition table in the NCIM database.
ENTITYNAME
NOT NULL
String
The name of the network pipe.
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
MSGTYPE
pipeComposition
NOT NULL
v AGGREGATIONSEQUENCE corresponds to
aggregationSequence in the collects table in
the NCIM database.
v ENTITYNAME is the component network pipe,
and corresponds to partComponent in the
pipeComposition table in the NCIM database.
Format of the data in the ncimCache.pipeComposition database table
The following example shows the format of the data in the
ncimCache.pipeComposition database table, as shown either using an OQL query,
or as seen in the NCHOME/var/precision/
Store.Cache.ncimCache.pipeComposition.DOMAIN file.
{
ENTITYID=50402;
ENTITYNAME=’IP_Path_[172.30.233.103]->[172.30.233.101]’;
MSGTYPE=’pipeComposition’;
pipeComposition=[
{
AGGREGATIONSEQUENCE=1;
ENTITYNAME=’my-device.mylab[ 0 [ 33 ] ]->ny-p1-cr28.na.test.lab[ 0 [ 25 ] ]’;
}
];
}
Appendix A. Discovery databases
409
ncimCache.protocolEndpoint table
The ncimCache.protocolEndpoint table allows a higher-level connection to be
defined in terms of lower-level connections. It associates a device entity, usually an
interface, with protocol-specific information associated with that device entity. The
protocolEndPoint table belongs to the category connectivity.
The following table shows the schema for the ncimCache.protocolEndpoint
database table.
Table 157. ncimCache.protocolEndpoint database table schema
Column name
Constraints
Data type
Description
ENTITYID
NOT NULL
Integer
The identifier of an entity. Corresponds to
endPointEntityID in the protocolEndpoint table in
the NCIM database. This entity specifies
protocol-specific addressing information for this
endpoint.
ENTITYNAME
NOT NULL
String
The name of the end point entity.
MANUAL
Boolean
If the entity was added manually to the topology,
this value is present and set to 1.
MSGTYPE
String
The name of the table within the ncimCache
database.
List of
name/value
pairs
A list of name/value pairs for the entity.
protocolEndpoint
NOT NULL
v ENTITYNAME corresponds to the name of the
implementingEntityID entity in the
protocolEndpoint table in the NCIM database.
This entity implements this protocol end point.
This is usually a device interface.
Format of the data in the ncimCache.protocolEndpoint database table
The following example shows the format of the data in the
ncimCache.protocolEndpoint database table, as shown either using an OQL query,
or as seen in the NCHOME/var/precision/
Store.Cache.ncimCache.protocolEndpoint.DOMAIN file.
{
ENTITYID=42739;
ENTITYNAME=’my-device.mylab[ 0 [ 33 ] ]’;
MSGTYPE=’protocolEndPoint’;
protocolEndPoint=[
{
ENTITYNAME=’my-device.mylab[ 0 [ 33 ] ] IP: 2222:22a:2a2e:222::22’;
},
{
ENTITYNAME=’my-device.mylab[ 0 [ 33 ] ] IP: 192.168.222.22’;
}
];
}
410
IBM Tivoli Network Manager IP Edition: Discovery Guide
model database schema
This database stores information about the topology so that during rediscovery,
topologies can be merged efficiently.
The model database is defined in NCHOME/etc/precision/ ModelSchema.cfg. Its
fully qualified database table names are: model.config; model.profilingData, and
model.statistics.
model.config table
The model.config table stores the configuration information that is used by
MODEL during rediscovery.
Table 158. model.config database table schema
Column name
Constraints
Data type
Description
ChassisCreation
Events
NOT NULL
Boolean Integer
If set to 1, generates ItnmEntityCreation and
ItnmEntityDeletion events when a chassis entity
is created.
DiscoveryUpdateMode
NOT NULL
Integer
For internal system use only; do not modify.
Prior to a batch update, ncp_disco sets this
value to 1 for a partial discovery, or to 0 for a
full discovery.
DeleteRenamedDevices
NOT NULL
Boolean Integer
Controls whether duplicate nodes are created in
the topology if a device name, that is, the
EntityName, is changed between discovery
cycles but the IP address of the device remains
the same. Possible values are as follows. An
example describes the behavior depending on
the value. In this example, the topology
contains a node that is called
deviceA.home.com, which has a LingerTime
value of 3. Before the next discovery cycle, the
deviceA.home.com device is renamed to
deviceB.home.com. If you change this setting,
restart the product for the change to take effect.
v 0 (default): A duplicate node is created. The
LingerTime of the existing node is
decremented. In the example, the nodes
deviceA.home.com and deviceB.home.com
are duplicates. The LingerTime of
deviceA.home.com is decremented to 2. The
LingerTime of deviceB.home.com is set to 3.
v 1: The existing node is overwritten by a node
that has the new name of the device. In the
example, the deviceA.home.com node is
overwritten. A node is created for
deviceB.home.com.
Important: If you set this field to 1, you must
disable sysName naming in the advanced
discovery parameters.
IpInterfaceCreation
Events
NOT NULL
Boolean Integer
If set to 1, generates ItnmEntityCreation and
ItnmEntityDeletion events when an interface
with its own IP address is created.
Appendix A. Discovery databases
411
Table 158. model.config database table schema
(continued)
Column name
Constraints
Data type
Description
KeepOldEntityDetails
NOT NULL
Integer
If this value is set to 0 (the default), any custom
data that was added to the
dbModel.entityDetails table is kept up-to-date
by future discoveries. Custom data that was
added but is no longer present in a discovery is
removed from the NCIM topology database. If
this value is set to 1, then custom data is always
kept in future discoveries, unless it is manually
deleted.
LingerTime
v PRIMARY KEY
Integer
The LingerTime value is how many discovery
cycles a device can fail to be found in before it
is considered as no longer present in the
topology and removed.
v NOT NULL
v UNIQUE
MaintenanceState
Events
NOT NULL
Boolean Integer
If set to 1, generates ItnmMaintenanceState
events when the status of an entity changes in
the managedStatus table.
ManagedStatusUpdate
Interval
NOT NULL
Integer
Interval in seconds at which ncp_model scans
the NCIM managedStatus table for changes.
This is the maximum time the poller should
take to react to changes in managed status
made in any of the following GUIs: Network
Views, Network Hop View, Structure Browser.
Default value 30 seconds.
Any combination of the flags ChassisCreationEvents, IpInterfaceCreationEvents,
and MaintenanceStateEvents can be turned on and off. The default is for all three
to be disabled.
Note: If you have a network that contains routers with a large number of IP
addresses, then enabling the IpInterfaceCreationEvents flag can might generate a
large number of events in the Object Server.
Related tasks:
“Adding name-value pairs to entities using the File finder” on page 272
If you enable the File finder to seed your discovery, then you can add name-value
pairs to entities by adding extra columns to the seed file read by the File finder.
model.profilingData
The model.profilingData table stores data associated with time and memory
expended during the discovery. This table includes information on how long it
took to transfer the discovery profiling data to the NCIM topology database.
Table 159. model.profilingData database table schema
Column name
Constraints
Data type
Description
BatchStartTime
v PRIMARY KEY
Integer
The time that a batch update from the Discovery
engine, ncp_disco, started.
v NOT NULL
v UNIQUE
BatchStartSize
NOT NULL
Integer
Number of records in the batch received.
BatchStartMem
NOT NULL
64-bit integer
Memory usage when batch started.
Integer
The time a batch update from the Discovery
engine, ncp_disco, ended.
BatchEndTime
412
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 159. model.profilingData database table schema (continued)
Column name
Constraints
Data type
Description
BatchEndSize
Integer
Number of records at the end.
Note: This value could be larger than at the start
if subsequent batches got merged in.
BatchEndMem
64-bit integer
Memory usage when batch ended.
EntityCount
Integer
Number of entities after the batch update.
ChassisCount
Integer
Number of chassis devices after the batch update.
InterfaceCount
Integer
Number of interfaces after the batch update.
model.statistics table
The model.statistics table stores information about previous discoveries.
Table 160. model.statistics database table schema
Column name
Constraints
Data type
Description
TopologyCount
v PRIMARY
KEY
Long
A count of the number of times
the topology has been sent
from DISCO to MODEL.
Integer
Indicates whether DISCO has
finished transferring the
topology to MODEL.
v NOT NULL
v UNIQUE
TopologySendFinished
This column is set to 0 when
the SendTopologyToModel.stch
stitcher begins sending the
topology, and set to 1 when it
has completed sending the
topology.
InsertCount
Long
The number of entities inserted
into the topology.
UpdateCount
Long
The number of entities updated
in the topology.
DeleteCount
Long
The number of entities deleted
from the topology.
Failover database
Failover recovery with the failover database is not to be confused with agent and
finder failover recovery, which are configured directly from the disco.config table.
When selected, agent and finder failover recovery operate regardless of whether
recovery with the failover database is implemented.
If the m_WriteTablesToCache column of the disco.config table is set to 1 (true), data
is cached during the discovery process to enable data recovery in the event that
the Discovery engine, ncp_disco, fails. A discovery running in this mode is slower
than a standard discovery, because of the extra time required to store data on the
disk throughout the discovery process.
Appendix A. Discovery databases
413
Ignored cached data
If DISCO is restarted in failover recovery mode, any cached data for a group of
tables are ignored.
The cached data for the following tables are ignored when DISCO is restarted in
failover recovery mode:
v disco.config
v disco.managedProcesses
v disco.agents
v The entire scope database
v failover.config
v failover.doNotCache
v failover.restartPhaseAction
For the above tables, only the insertions specified in the schema file at the time of
the restart are registered.
The failover database schema
The failover database is defined in $NCHOME/etc/precision/DiscoSchema.cfg. Its
fully qualified database table names are: failover.config; failover.status;
failover.findRateDetails; failover.doNotCache; failover.restartPhaseAction.
failover.config table
There must never be more than one insert into the failover.config table.
Table 161. failover.config database table schema
Column name
Constraints
Data type
Description
m_InitialiseFromCache
Externally
defined
Boolean data
type
Boolean
integer
Flag indicating whether to use
the data that already exists in
the cache:
v 0: Do not use cached data
v 1: Use cached data if any
exists
Integer
m_NumberOfRetries
The number of times to try
using the cached data before
giving up (that is, the number
of subsequent times that DISCO
can be restarted before starting
with a clean slate).
If no value is specified, DISCO
always starts with clear
databases.
m_StoreEveryNthDevice
414
Default = 10
IBM Tivoli Network Manager IP Edition: Discovery Guide
Integer
How often the findRateDetails
table is to be updated. After the
specified number of devices
have been found the table is
updated.
failover.status table
The failover.status table displays the number of times that the DISCO process has
attempted to restart with cached data. This table is active, so you must not
configure inserts into it.
Table 162. failover.status database table schema
Column name
Constraints
Data type
Description
m_NumberOfAttempts
v NOT NULL
Integer
The number of times that the
DISCO process has attempted
to restart with cached data.
v PRIMARY KEY
This column is set to 1 when
DISCO is first run in failover
recovery mode and
incremented each time DISCO
is subsequently run in
failover mode.
failover.findRateDetails table
The findRateDetails table gives details of devices that have been found at a certain
point in the discovery. This table is active and inserts must not be made in the
schema file; the table is populated automatically.
Table 163. failover.findRateDetails database table schema
Column name
Constraints
Data type
Description
m_StartTime
v NOT NULL
Text
The time at which the first
device was found.
m_LastFindTime
Text
The time at which the last
device was found.
m_DevicesFound
Integer
The number of devices found
so far.
v PRIMARY KEY
failover.doNotCache table
To prevent caching a given table, you can specify its name in the doNotCache
table. This ensures that unnecessary cache files are not created, such as those for
temporary tables defined within stitchers.
Appendix A. Discovery databases
415
Table 164. failover.doNotCache database table schema
Column name
Constraints
Data type
Description
m_DatabaseName
NOT NULL
Text
The name of any database that is
not to be cached during failover
recovery.
The following tables must be
cached in order to use the failover
recovery mode, and therefore must
not be listed in this table:
v disco.status
v failover.status
The following tables must be
cached, and therefore must not be
listed in this table:
v The agent despatch and returns
tables.
v finders.processing
v translations.ipToBaseName
m_TableName
NOT NULL
Text
The name of the table within the
database specified in
m_DatabaseName that is not to be
cached.
Use * to indicate all the tables of
the database.
failover.restartPhaseAction table
The restartPhaseAction table contains the set of stitchers that are executed when
restarting in a given discovery phase. Multiple stitchers can be specified, but they
are executed in an arbitrary order. It is recommended that at least the FinalPhase
stitcher is executed when restarting in the topology creation phase.
Table 165. failover.restartPhaseAction database table schema
Column name
Constraints
Data type
Description
m_RestartPhase
NOT NULL
Integer
The phase in which DISCO is
restarted.
m_ExecuteStitcher
NOT NULL
Text
The stitcher that is to be
executed in this phase.
Example failover database configuration
This example uses OQL commands to insert configuration values into the failover
database tables that are appended to the DiscoConfig.cfg file to configure DISCO
when it is launched.
416
IBM Tivoli Network Manager IP Edition: Discovery Guide
Example configuration of the failover.config table
This example uses OQL commands to insert configuration values into the
failover.config table.
For this configuration of the failover.config table, data already in the cache is used.
The Discovery engine, ncp_disco, can be restarted up to three times before cached
data is ignored. These values are used only when
disco.config.m_WriteTablesToCache=1.
insert into failover.config
(
m_InitialiseFromCache,
m_NumberOfRetries
)
values
( 1, 3 );
Example configuration of the failover.doNotCache table
This example uses OQL commands to insert configuration values into the
failover.doNotCache table. The disco.config table and all tables of the
instrumentation database are not cached.
insert into failover.doNotCache
(
m_DatabaseName,
m_TableName
)
values
(
’disco’, ’config’
);
insert into failover.doNotCache
(
m_DatabaseName, m_TableName
)
values
(
’instrumentation’, ’*’
);
Agent Template database
The databases of each discovery agent are based on a template called the
agentTemplate database.
The agentTemplate database is defined in $NCHOME/etc/precision/
DiscoSchema.cfg, and its fully qualified database table names are:
agentTemplate.despatch and agentTemplate.returns.
Related reference:
“Discovery agent definition files” on page 59
The discovery agent definition files define the operation of the discovery agents.
Appendix A. Discovery databases
417
Discovery agent despatch table
When a device has been interrogated by the Details agent, it is passed to the
Associated Address agent to check whether it has already been discovered. If the
device has not been discovered, the device details are processed and sent by a
stitcher to the despatch table of the appropriate agent.
The despatch table is described in Table 166.
When the device details are placed in the despatch table, the agent attempts to
retrieve connectivity information pertaining to the device.
Table 166. agentTemplate.despatch database table schema
Column name
Constraints
Data type
m_Name
PRIMARY KEY Text
NOT NULL
Description
Unique name of an entity on the
network.
m_UniqueAddress
NOT NULL
Text
A string that uniquely identifies this
entity. The content of this field is
unconstrained, and might be an IP
address or an element management
system (EMS) key.
m_ManagerId
PRIMARY KEY Text
Manager of the device. If the device
is accessed directly, this is set to " ".
By default, this is set to " ".
NOT NULL
m_Protocol
Integer
An integer representation of the
network protocol used by the
presently-defined zone:
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through
network address translation (NAT)
v 3: IPv6
v 4: Element Management System
(EMS) key for a non-IP device
m_ObjectId
Text
Textual representation of the device
class (an ASN.1 address).
m_SnmpAccessIP
Text
If present, overrides the IP address
used for SNMP access to devices
using the Helper Server.
m_AddressSpace
Text
The name of the NAT address space
to which the device belongs. This
value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the public
domain, this value is NULL.
Boolean
Integer
Flag indicating whether there is
SNMP access to the device:
m_HaveAccess
418
Externally
defined
Boolean data
type
IBM Tivoli Network Manager IP Edition: Discovery Guide
v (1) Have Access
v (0) No Access
Discovery agent returns table
Returned device connectivity details are placed in the returns table of the agent.
These details are used to populate the topology databases.
The returns table is described in Table 167.
Table 167. agentTemplate.returns database table schema
Column name
Constraints
Data type
Description
m_Name
NOT NULL
Text
Unique name of an entity on the
network.
m_ManagerId
PRIMARY KEY Text
NOT NULL
Manager of the device. If the device
is accessed directly, this is set to " ".
By default, this is set to " ".
m_UniqueAddress NOT NULL
Text
A string that uniquely identifies this
entity. The content of this field is
unconstrained, and might be an IP
address or an element management
system (EMS) key.
m_Protocol
Integer
An integer representation of the
network protocol used by the
presently-defined zone:
v 0: Unknown
v 1: IPv4
v 2: IPv4 that has been through
network address translation
(NAT)
v 3: IPv6
v 4: Element Management System
(EMS) key for a non-IP device
m_ObjectId
m_HaveAccess
Text
Textual representation of the device
class (an ASN.1 address).
Externally
defined
Boolean data
type
Boolean Integer Flag indicating whether there is
SNMP access to the device:
m_ExtraInfo
Externally
defined vblist
data type
Object
Any extra information specified by
the user in the agent definition file.
m_LocalNbr
Externally
defined
neighbor data
type
Object
Direct neighbors (interfaces).
m_RemoteNbr
Externally
defined
nbrsNeighbor
data type
Object
Remote neighbors connected to
interfaces.
m_UpdAgent
Text
The agent that updated this device.
m_SnmpAccessIP
Text
If present, overrides the IP address
used for SNMP access to devices
using the Helper Server.
v (1) Have Access
v (0) No Access
Appendix A. Discovery databases
419
Table 167. agentTemplate.returns database table schema (continued)
Column name
Constraints
m_AddressSpace
m_LastRecord
420
Externally
defined
Boolean data
type
IBM Tivoli Network Manager IP Edition: Discovery Guide
Data type
Description
Text
The name of the NAT address space
to which the device belongs. This
value is set in the
translations.NATAddressSpaceIds
table. If the discovery is not using
NAT, or if the device is in the
public domain, this value is NULL.
Boolean integer Is this the last record for this entity:
v (1) True
v (0) False
Appendix B. Discovery process
The Network Manager discovery process produces a network topology that
includes connectivity and containment data.
Discovery subprocesses
The discovery process consists of several subprocesses that work together to
discover devices and device interconnectivity.
When you launch a discovery, the internal Network Manager discovery engine
(ncp_disco) is run. The ncp_disco engine manages the process of discovering
device existence and interconnectivity.
Whenever you launch a full discovery the Discovery Engine, ncp_disco, rereads its
configuration files. The Discovery Engine also instructs the Helper Server and the
individual helpers to reread their configuration files. This is controlled by the
DiscoReadConfig() rule within the FullDiscovery stitcher file.
Note: When you launch a partial discovery, ncp_disco does not read its
configuration files.
The Discovery engine operates by detecting the existence of a device on the
network and querying the device for inventory and connectivity information,
which is subsequently processed or 'stitched' together to generate a connectivity or
topology model. The discovery engine components are described in Table 168.
Table 168. Discovery components
Name
Description
Finders
Finders discover the existence of devices but do not retrieve connectivity
information.
© Copyright IBM Corp. 2006, 2017
421
Table 168. Discovery components (continued)
422
Name
Description
Agents(The
Discovery
engine starts
each agent as a
dependent
unmanaged
process. In the
event of a
failure of the
Discovery
engine, the
Process
controller,
ncp_ctrl, shuts
down each of
the agents
started by the
discovery. For
more
information on
process control,
see the IBM
Tivoli Network
Manager IP
Edition
Administration
Guide.)
ncp_disco uses discovery agents to request connectivity information from
devices that the finders have discovered. There are a variety of agents,
each specialized to retrieve information from different devices, and, in
certain cases, to use different protocols. Agents do not have any direct
interaction with the network, but instead retrieve information through
the Helper Server. Agents can be libraries or text files, and are specialized
for particular protocols, devices or classes.
Helper Server
The Helper Server manages the helpers and stores the information that is
retrieved from the network. Discovery agents retrieve their information
through the Helper Server to reduce the load on the network. The Helper
Server can service the requests directly with cached data or pass on the
request to the appropriate helper.
Helpers(The
Helper Server
starts each
helper as a
dependent
unmanaged
process. In the
event of a
failure of the
Discovery
engine, the
Process
controller,
ncp_ctrl, shuts
down each of
the helpers
started during
the discovery.)
The helpers retrieve information from the network on behalf of the
discovery agents. Helpers also translate agent queries into the
appropriate network protocol and make requests to the devices.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 168. Discovery components (continued)
Name
Description
Stitchers
Stitchers are processes that transfer, manipulate and distribute data
between databases. The discovery stitchers are also responsible for
processing the information collected by the agents and using this
information to create the network topology. A predefined set of stitchers
is included with Network Manager. You can modify existing stitchers or
write new stitchers to perform custom manipulation of your network
topology. For example, you can write a stitcher to make your device
interfaces appear with a custom naming convention. Stitchers are coded
using the stitcher language.
Discovery timing
Each full discovery consists of one or more discovery cycles. The division of a full
discovery into multiple discovery cycles enables the discovery to complete in a
timely way.
In the first discovery cycle, Network Manager discovers the existence of a
predetermined majority of devices on the network, and proceeds to complete all
data collection and processing operations associated with these devices. When
Network Manager has discovered the existence of a predetermined majority of
devices on the network, Network Manager enters the blackout state.
Any devices that Network Manager discovers during the blackout state are placed
into a database table named finders.pending. These devices are only processed in
the following discovery cycle. This means that the discovery process does not have
to wait for all devices to be discovered before proceeding to the more detailed data
collection and data processing operations.
Note: Ideally a discovery should complete in a single discovery cycle; however,
sometimes it is not possible to discover the existence of entities sufficiently quickly
as a result more discovery cycles are needed. Reasons why the system does not
discover the existence of entities sufficiently quickly include: ping sweeping of
sparsely populated subnets, and lack of access to devices. First-time discoveries
often have multiple cycles. This can be mitigated by using the BuildSeedList.pl
script to build a seed list after the initial discoveries. This seed list will then be
used in subsequent discoveries to find devices in a more timely manner.
By default, each discovery cycle is made up of a data collection stage and a data
processing stage. The data collection stage is in turn broken up into three phases.
Figure 7 on page 424 shows a timing diagram for a discovery that requires two
discovery cycles to complete.
The data collection and data processing stages are briefly described in Table 169 on
page 424.
Appendix B. Discovery process
423
1
Database
tables
Finders
database
pending
Blackout state
Discovery cycle 1
Data collection
Phase
Phase
Phase
Data processing
Discovery cycle 2
Data collection
Phase
Phase
Data processing
Figure 7. Discovery timing for a full discovery with two discovery cycles
In Figure 7, the blackout state for the first discovery cycle begins and ends at the
instants indicated by the numbers 1 and 2 respectively:
▌1▐: Blackout state begins. A predetermined majority of devices on the network
have now been discovered. Any devices discovered after this point are placed
into the finders.pending table for processing in the subsequent discovery cycle.
▌2▐: Blackout state ends. Devices stored in the finders.pending table are now
processed in the subsequent discovery cycle.
Note: If the network being discovered is particularly large or complex, more than
two discovery cycles may be required to complete a full discovery. In this case,
each discovery cycle, except for the last cycle, has its own blackout state.
Table 169. Data collection and data processing stages
Stage or Phase
Description
Data collection stage
During this stage, Network Manager interrogates the
network for device information, using the finder, agent and
helper components of DISCO. The data collection stage is
divided into three phases, which are described in this table.
Data collection: first phase
During this phase, finders identify devices on the network.
Phase one completes when the device find rate drops below
a certain level. For each device discovered, agents retrieve
device details, IP addresses associated with the device, and
device connectivity information.
Data collection: second phase During this phase, an agent retrieves IP address to MAC
address mapping data.
Data collection: third phase
424
During this phase agents download all forward database
table information for the network switches and ping all
devices to confirm the accuracy of the contents of the
forward database tables.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 169. Data collection and data processing stages (continued)
Stage or Phase
Description
Data processing stage
During this stage, Network Manager deduces the network
topology based on data collected during the data collection
stage. Stitchers analyze the data collected and build a
network topology that includes connectivity and
containment data.
Related concepts:
“Discovery stages and phases”
The discovery process can be divided into two stages: data collection and data
processing. The stages are subdivided into phases.
“Discovery cycles” on page 430
A discovery cycle has occurred when the discovery data flow for a particular cycle
has gone from start to finish. A full discovery might require more than one cycle.
“Data collection stage” on page 426
The data collection stage involves interrogating the network for device information
to produce a network topology. DISCO uses the finders, agents and helpers during
the data collection stage. The data collection stage can be further subdivided into a
number of phases.
“Data processing stage” on page 426
Topology deduction takes place during the data processing stage, as the
information from the data collection stage is analyzed, interpreted and processed
by the stitchers. The culmination of the data processing stage is the production of
the containment model.
Discovery stages and phases
The discovery process can be divided into two stages: data collection and data
processing. The stages are subdivided into phases.
Related concepts:
“Discovery timing” on page 423
Each full discovery consists of one or more discovery cycles. The division of a full
discovery into multiple discovery cycles enables the discovery to complete in a
timely way.
“Discovery cycles” on page 430
A discovery cycle has occurred when the discovery data flow for a particular cycle
has gone from start to finish. A full discovery might require more than one cycle.
Related tasks:
“Monitoring full and partial discovery progress” on page 227
You can use the Monitoring tab to monitor the progress of the current full or
partial discovery through each of the discovery phases.
Appendix B. Discovery process
425
Data processing stage
Topology deduction takes place during the data processing stage, as the
information from the data collection stage is analyzed, interpreted and processed
by the stitchers. The culmination of the data processing stage is the production of
the containment model.
The data processing stage corresponds to creating the topology. This is the final
conceptual step in the discovery cycle.
The data processing and data collection stages usually overlap, because you can
configure the stitchers to begin processing connectivity information from different
discovery agents before the main stitching operation begins.
Related concepts:
“Discovery timing” on page 423
Each full discovery consists of one or more discovery cycles. The division of a full
discovery into multiple discovery cycles enables the discovery to complete in a
timely way.
“Creating the topology” on page 437
The creation of the topology is carried out in several steps.
Data collection stage
The data collection stage involves interrogating the network for device information
to produce a network topology. DISCO uses the finders, agents and helpers during
the data collection stage. The data collection stage can be further subdivided into a
number of phases.
First phase
In the first phase of data collection, the finders identify all the devices that exist on
the network. Generally, a phase can be completed when all the launched processes
have completed their operation. However, although you might want to wait until
all devices have been discovered by the finders before proceeding to phase two, it
is inefficient to hold back the discovery process by waiting indefinitely. The first
phase therefore completes when the find rate drops below a certain level,
determined by no devices being discovered for the amount of time specified in
disco.config.m_NothingFndPeriod.
The following conceptual steps in the discovery cycle take place during data
collection phase one:
v
Discovering device existence
v
Discovering device details (standard)
v Discovering associated device addresses
v Discovering device connectivity
Agents in the first phase
Some agents return data that can be used to find other devices, for example, the IP
address of remote neighbors, or the subnet within which a local neighbor exists.
This mechanism is known as feedback.
The Feedback stitcher manages feedback by sending the information returned by
the agents to the Ping finder for inclusion in the discovery. However, the blackout
426
IBM Tivoli Network Manager IP Edition: Discovery Guide
state ensures that any agent involved in the feedback process must be run in phase
one for devices to be discovered in the current discovery cycle.
Phase one also usually involves the Switch discovery agents downloading all
VLAN and interface information.
Blackout state
After phase one, the discovery enters the blackout state. The finders have discovered
the existence of a pre-determined majority of devices on the network. Any new
device addresses discovered in the blackout state, either by the finders or
recursively by a discovery agent, are put into the finders.pending database table.
Devices in the finders.pending database table are processed in the next discovery.
If there are devices in the finders.pending database table, the next discovery starts
as soon as the current discovery finishes.
Second phase
After the criteria for the completion of phase one have been fulfilled, phase two
begins. To map layers two and three of the OSI model, the ARP Cache discovery
agent populates the Helper Server with ARP data, which is a list of device IP
address-to-MAC address resolution.
Before the discovery can transfer from phase two to phase three, the processes
from phase two must have completed their operation. An agent is considered to
have finished after all entities in its despatch table are also in its returns table.
The agents are multithread, and records of discovered devices passed to the agents
are tagged with a certain phase. Consequently, at any time an agent can be
processing devices in two separate phases. If any action that should have occurred
in phase two is detected after phase three has begun, phase three continues while
the agent runs through phase two processing.
Third phase
By phase three, the discovery process has full knowledge of the devices that exist
within the network (acquired from phase one) and access to full IP
address-to-MAC address mappings for all devices in the Helper Server (acquired
from phase two). The Switch agents can now proceed to download all the forward
database table information of the network switches whilst pinging all devices to
confirm the accuracy of the contents of the forward database tables.
When phase three has finished, which is signified by the completion of all
processes scheduled to run in the phase, the discovery is ready to proceed from the
data collection stage to the data processing stage, where all the connectivity
information is knitted together to form a network topology.
Impact of the stages and phases approach on DISCO processes
The division of the data collection stage into phases affects all the processes
involved in the discovery and network topology deduction, because the phases are
processed in order. Any given phase cannot begin until the criteria for completion
of the previous phase have been met.
Appendix B. Discovery process
427
All the processes of DISCO must therefore have an associated phase (or phases) in
which they are allowed to operate. Thus, whilst the finders are typically configured
to run through all phases, you might want to configure certain discovery agents to
operate only within a specific phase(s). The flexibility of DISCO allows you to have
processes that are intelligent enough to behave differently when they operate
within different phases, and can pass control to other processes or stop operation
until the start of their next operational phase.
Related concepts:
“Discovery timing” on page 423
Each full discovery consists of one or more discovery cycles. The division of a full
discovery into multiple discovery cycles enables the discovery to complete in a
timely way.
“Discovering device existence” on page 431
The discovery of device existence is carried out in several steps.
“Discovering device details (standard)” on page 432
The standard discovery of device details is carried out in several steps.
“Discovering associated device addresses” on page 434
There are several steps in the process flow during the discovery of associated
device addresses.
“Discovering device connectivity” on page 436
The discovery of device connectivity is carried out in several steps.
Advantages of staged discovery
There are several reasons why it is advantageous to apply a staged and phased
approach to discovery.
Switch connectivity
In determining the connectivity of some devices, it is sometimes necessary for the
discovery agent to know all the devices that exist before requesting particular
Management Information Base (MIB) variable(s), especially if the requested
information is transient.
An example is when the layer 2 agents discover connectivity between Ethernet
switches. Ethernet switches have forward database tables that expire over time. So,
to ensure that a switch has a fully populated forward database table at the time of
interrogation, you could ping all devices associated with the switch.
You would therefore configure the switch discovery agents to perform some other
processing in data collection phase one. After the agents receive the signal that
phase one has been completed (that is, all devices have been found) they can start
phase two operations. For example, they could ping all devices within the
discovery domain while downloading the forward database tables for all switches.
Mapping subnet boundaries
One limitation of configuring individual discovery agents to make individual ARP
requests directly from the Helper Server is that the ARP helper cannot run
simultaneously on multiple subnets unless it is specifically configured to do so. To
resolve this problem, use a special ARP Cache discovery agent that imitates a
generic discovery agent (in the sense that entities can be sent to it) but that also
can map boundaries or different layers of the OSI model.
428
IBM Tivoli Network Manager IP Edition: Discovery Guide
The ARP Cache discovery agent can inquire about ARP caches that exist on
routers. It uses this information to populate the ARP helper database within the
Helper Server and build up full device IP address to MAC address mapping
without having to rely on the ARP helper.
This approach can be applied when using switch discovery agents that need to
perform IP address-to-MAC address resolution before they can start operation.
Following the example above, you could configure your discovery data collection
stage to have three phases:
v Phase one: Find all devices that exist on the network.
v Phase two: Use the ARP Cache discovery agent to populate the Helper Server
with full IP address to MAC address mappings.
v Phase three: Ping all devices and invoke the switch discovery agents by
downloading the forward database tables for all switches in the network, using
the IP address to MAC address mappings determined in phase two.
Multiphase discovery agents
Another possible consequence of dividing the data collection stage into phases is
that you can configure the discovery agents to perform different operations within
different phases.
Although a discovery agent is programmed to start operating in phase two, it
could also conduct some other operation in phase one. This is because the end of
phase one signifies only that all devices have been discovered. The agent could be
configured to perform other actions such as downloading interfaces, issuing Telnet
requests, or downloading other MIB variables during phase one. Only after phase
two has started does the agent begin to process instructions specific to phase two.
Tip: It is good practice to configure the discovery to occur over multiple phases, to
ensure maximum accuracy of the deduced topology.
Effect of discovery multiphasing on network traffic
One of the main benefits of multiphasing is reduced network traffic.
Because similar types of network requests are grouped in phases, data can be
cached in the Helper Server to reduce the network load. The Helper Server is the
intermediary between the discovery agents and the network, and can amalgamate
multiple pings of the same device into one block so that they are resolved into a
single ping.
The Helper Server also has a request pool that ensures that the Helper Server does
not overload the network. The request pool does this by restricting the number of
simultaneously-handled requests.
Criteria for multiphasing
The main criterion for configuring a discovery that has multiple phases is to assess
the requirements of the different operations that need to be performed during the
discovery process. For example, Ethernet-based discovery agents require at least
two phases. It is possible to have discovery agents that can operate in any phase.
Appendix B. Discovery process
429
Managing the phases
The different phases of the discovery data collection stage are managed by an
internal phase manager.
The phase manager:
v Reads the maximum overall phase number and calculates the total number of
phases when all the discovery agent and stitcher definition files are loaded.
v Calculates the phase and process dependencies, that is, which discovery agents
are scheduled to run in which phases.
v Monitors the processes running during the phases.
When the phase manager detects that all the processes for the current phase have
completed, it sends a signal indicating phase completion for all the processes that
are waiting to be launched in the next phase.
Discovery cycles
A discovery cycle has occurred when the discovery data flow for a particular cycle
has gone from start to finish. A full discovery might require more than one cycle.
The discovery data flow can be categorized into the following conceptual steps:
v Discovering device existence
v Discovering device details (standard)
v Discovering device details (context-sensitive)
v Discovering associated device addresses
v Discovering device connectivity
v Creating the topology
These steps follow the discovery data flow in order from start to finish, with the
exception of discovering device details (context-sensitive), which replaces
discovering device details (standard) if the discovery is context-sensitive.
Related concepts:
“Discovery timing” on page 423
Each full discovery consists of one or more discovery cycles. The division of a full
discovery into multiple discovery cycles enables the discovery to complete in a
timely way.
“Discovery stages and phases” on page 425
The discovery process can be divided into two stages: data collection and data
processing. The stages are subdivided into phases.
“Discovery process with EMS integration” on page 439
Network Manager collects topology data from an EMS using collectors.
430
IBM Tivoli Network Manager IP Edition: Discovery Guide
Discovering device existence
The discovery of device existence is carried out in several steps.
Figure 8 shows how the initial existence of devices on the network is discovered.
Network
F
F
F
F: finders
1
2
Database tables
Finders database
3
despatch
returns
pending
processing
Details agent
4
despatch
returns
Figure 8. Discovery process flow: device existence
The process flow shown in Figure 8 is described below.
▌1▐: The finders receive their instructions from their configuration files and the
inserts made into the finders.despatch table, then proceed to the network to
look for devices.
▌2▐: The finders return the device existence information to the finders.returns
table.
▌3▐: After the device existence information is placed into the finders.returns
table, a stitcher moves the information to the finders.processing table. This
signifies that the network entity is being processed by DISCO. If the discovery
is in the blackout state, the information is placed into the finders.pending table
instead.
▌4▐: A stitcher moves the information about device existence from the
finders.processing table to the Details.despatch table, ready for processing by
the Details agent.
Related concepts:
Appendix B. Discovery process
431
“Data collection stage” on page 426
The data collection stage involves interrogating the network for device information
to produce a network topology. DISCO uses the finders, agents and helpers during
the data collection stage. The data collection stage can be further subdivided into a
number of phases.
Discovering device details (standard)
The standard discovery of device details is carried out in several steps.
Figure 9 shows how device details are discovered in a standard discovery.
Network
H
H
2
Helper server
1
3
H: helper
Details agent
4
AssocAddress agent
Figure 9. Discovery Process Flow: Device Details (Standard)
The process flow shown in Figure 9 is described below.
▌1▐: All the agent despatch tables are active, so an insertion into the
Details.despatch table automatically triggers the Details agent to discover basic
device information and determine whether SNMP access to the device is
available.
▌2▐: The Details agent interrogates the network through the Helper Server.
Requests are cached to reduce the number of times that the helpers
(represented by the letter H in Figure 9) must interrogate the network directly.
▌3▐: The information retrieved from the network is returned to the
Details.returns table.
432
IBM Tivoli Network Manager IP Edition: Discovery Guide
▌4▐: The information in the Details.returns table is passed to the despatch table
of the Associated Address (AssocAddress) agent for processing.
Related concepts:
“Data collection stage” on page 426
The data collection stage involves interrogating the network for device information
to produce a network topology. DISCO uses the finders, agents and helpers during
the data collection stage. The data collection stage can be further subdivided into a
number of phases.
Discovering device details (context-sensitive)
The discovery of context-sensitive device details is carried out in several steps.
Figure 10 shows how device details are discovered in a context-sensitive discovery.
Network
H
H
2
Helper server
H: helper
1
3
Details agent
4
5
Context agent
AssocAddress agent
Figure 10. Discovery process flow: device details (context-sensitive)
The process flow shown in Figure 10 is described below.
▌1▐: All the agent despatch tables are active, so an insertion into the
Details.despatch table automatically triggers the Details agent to discover basic
device information and determine whether or not SNMP access to the device is
available.
Appendix B. Discovery process
433
▌2▐: The Details agent interrogates the network through the Helper Server.
Requests are cached to reduce the number of times that the helpers must
interrogate the network directly.
▌3▐: The information retrieved from the network is returned to the
Details.returns table.
▌4▐: The information in the Details.returns table is passed to the despatch table
of the appropriate Context agent, which adds context tags.
▌5▐: After the Context agent has finished its processing, the information is
passed to the despatch table of the Associated Address (AssocAddress) agent
for processing.
Related concepts:
“Context-sensitive discovery” on page 18
If you need to discover devices that support multiple contexts, you must run a
context-sensitive discovery. For example, a device that uses separate SNMP
contexts to provide access to its virtual routers. Context-sensitive discovery ensures
correct representation of context-accessible virtual devices. Always check that your
particular device type is supported for discovery.
Related tasks:
“Configuring a context-sensitive discovery” on page 104
If you need to discover devices that support multiple contexts, you must run a
context-sensitive discovery. For example, a device that uses separate SNMP
contexts to provide access to its virtual routers. Context-sensitive discovery ensures
correct representation of context-accessible virtual devicess. Always check that your
particular device type is supported for discovery.
Related reference:
“DiscoConfig.cfg configuration file” on page 73
The DiscoConfig.cfg configuration file is used to have the Ping finder automatically
check the devices discovered by the File finder, and to enable a context-sensitive
discovery.
Discovering associated device addresses
There are several steps in the process flow during the discovery of associated
device addresses.
The following figure shows how associated device addresses are discovered.
434
IBM Tivoli Network Manager IP Edition: Discovery Guide
Network
Helper
Helper
Helper server
Agent
3
1
Agent
ipToBaseName
2
Translations
database
AssocA
Figure 11. Discovery process flow: associated device addresses
The following process flow describes Figure 11:
▌1▐: The Associated Address agent uses the Helper Server to download all the
IP addresses associated with the interfaces of the device that is under
investigation.
▌2▐: The Associated Address agent checks the IP addresses against the registry
of addresses, the translations.ipToBaseName table. The details are also added to
this registry. If the device has already been discovered by another of its
addresses (that is, if the translations.ipToBaseName table already contains a
record for this device), the details of the device are not sent to the discovery
agents.
▌3▐: Provided the device has not already been discovered, the stitchers pass the
details to the appropriate discovery agents, as specified in the DiscoAgents.cfg
configuration file.
Related concepts:
“Data collection stage” on page 426
The data collection stage involves interrogating the network for device information
to produce a network topology. DISCO uses the finders, agents and helpers during
the data collection stage. The data collection stage can be further subdivided into a
number of phases.
Appendix B. Discovery process
435
Discovering device connectivity
The discovery of device connectivity is carried out in several steps.
The following figure shows how device connectivity is discovered, as well as how
devices are discovered recursively.
Network
Helper
Helper
1
1
Helper server
Agent
2
Finders
database
Agent
2
Figure 12. Discovery process flow: device connectivity
The following process flow describes Figure 12:
▌1▐: When information is inserted into the despatch table of a discovery agent,
the agent attempts to discover the connectivity information for that device. The
agent sets up a TCP socket-based communication link with the Helper Server
and requests the appropriate connectivity information.
▌2▐: A stitcher passes the addresses of the remote neighbors of the device, and
the subnet address or addresses of the device, to a finder for discovery. Because
these addresses might not exist, and also might not be in the specified
discovery scope, the addresses must run through the discovery process from
the beginning.
Related concepts:
“Data collection stage” on page 426
The data collection stage involves interrogating the network for device information
to produce a network topology. DISCO uses the finders, agents and helpers during
the data collection stage. The data collection stage can be further subdivided into a
number of phases.
436
IBM Tivoli Network Manager IP Edition: Discovery Guide
Creating the topology
The creation of the topology is carried out in several steps.
The following figure shows a simplified data flow for the creation of the topology
from the raw data returned by the discovery agents
returns table for agents
1
2
3
workingEntities,
finalEntity
2
workingEntities,
containment
3
Layer databases
fullTopology,
entityByNeighbor
4
5
4
dNCIM
ncp_model
Figure 13. Discovery process flow: creating the topology
The following process flow describes the data flow.
▌1▐: After all the discovery agents have finished, and the discovery enters the
data processing stage, special data processing stitchers interact with the
discovery agent databases to produce the workingEntities.finalEntity table.
Network entities that did not pass the instantiation filter are not included in the
workingEntities.finalEntity table.
▌2▐: The stitchers use a subset of the agents-returns tables, together with the
workingEntities.finalEntity table, to deduce and create the containment model.
This model is stored in the workingEntities.containment table.
▌3▐: The stitchers use a further subset of the agents-returns tables, together with
the workingEntities.finalEntity table and the workingEntities.containment table,
to build the various topology layers, which are stored in the layer database
tables. The full set of layers is merged in the fullTopology.entityByNeighbor
table.
Appendix B. Discovery process
437
▌4▐: The stitchers merge the three tables produced (workingEntities.finalEntity;
workingEntities.containment; fullTopology.entityByNeighbor) to build the
network model. The network model is stored in the dNCIM database. The
dNCIM data processing stitchers are used to populate the dNCIM database.
The database topology is then sent in ncimCache format to ncp_model.
▌5▐: The Topology manager, ncp_model, receives the topology from the dNCIM
database and merges it into the existing NCIM database topology model. The
ncp_model process instantiates each network element and sends the topology to
other components as required.
Related concepts:
“Data processing stage” on page 426
Topology deduction takes place during the data processing stage, as the
information from the data collection stage is analyzed, interpreted and processed
by the stitchers. The culmination of the data processing stage is the production of
the containment model.
Advanced discovery configuration options
Use this information to understand how to configure the discovery process data
flow and to configure download of full routing tables.
Configurable discovery data flow
The discovery process data flow is user-configurable. Stitchers control the
movement of data between databases, and you can customize the discovery
process by changing the way in which the stitchers are triggered and operate.
Stitcher and agent triggers
You can modify the data flow by changing the criteria that trigger the deployment
of the stitchers and discovery agents, by modifying the stitchers, and, if necessary,
by modifying the agent definitions. Some typical triggers are:
v Data being inserted into a specific database table
v A stitcher or discovery agent completing its operation
v The end of a discovery phase
Any changes you make are automatically detected by DISCO during its periodic
scan of the agent and stitcher files (the scan frequency is determined by the entry
in the disco.config database). On detecting changes, DISCO modifies its agent and
stitcher definitions databases accordingly, and applies the changes to the next
discovery cycle.
For more details about the stitchers and the stitcher language, see the IBM Tivoli
Network Manager IP Edition Language Reference.
On-demand stitchers
Stitchers can be started on demand. If you insert a stitcher into the stitchers.actions
database, DISCO automatically runs the stitcher. This means that the discovery
cycle can be started at any point, and further actions can be configured to start
when the stitcher completes.
Related reference:
438
IBM Tivoli Network Manager IP Edition: Discovery Guide
“stitchers.actions table” on page 335
If a stitcher is inserted into the stitchers.actions table, DISCO runs the stitcher.
Once the stitcher has completed, its entry is deleted from the stitchers.actions table.
Any stitchers triggered to execute from the stitcher that has been inserted, or upon
completion of the stitcher, are also executed.
Partial matching
By default, the discovery process uses partial matching, which means that the
discovery agents do not need to download the full routing tables during discovery.
You do not need to modify the discovery agent definition files to use partial
matching. However, it is possible to prevent the IpForwardingTable and
IpRoutingTable discovery agents from using partial matching in certain cases if
you have devices on your network that do not support partial matching.
To prevent partial matching on certain devices, you must specify the devices that
do not support partial matching in the DiscoRouterPartialMatchRestrictions();
section of the IpForwardingTable.agnt definition file (for modern devices that use
RFC2096) or the IpRoutingTable.agnt definition file (for older devices that use
RFC1213). If a discovered device matches the filter specified in the
DiscoRouterPartialMatchRestrictions(); section, partial matching is not
attempted on that device.
Discovery process with EMS integration
Network Manager collects topology data from an EMS using collectors.
The following steps show how Network Manager collects topology data from an
EMS using collectors.
Collector-based discovery can be divided into the following conceptual steps:
v Discovering device existence
v Discovering basic device information
v Discovering detailed device information
For an overview of how Network Manager collects topology data from Element
Management Systems (EMSs) and integrates this data into the discovered topology,
see the IBM Tivoli Network Manager IP Edition Product Overview.
Related concepts:
“Discovery cycles” on page 430
A discovery cycle has occurred when the discovery data flow for a particular cycle
has gone from start to finish. A full discovery might require more than one cycle.
Related tasks:
“Configuring EMS discoveries” on page 105
You can configure Network Manager to collect topology data from Element
Management Systems (EMS) and integrate this data into the discovered topology.
Appendix B. Discovery process
439
Discovering device existence with collectors
During a collector discovery, the discovery of device existence takes place in
several steps.
Figure 14 shows how the initial existence of devices held on the collectors is
discovered.
Network
F
F
F
1
F: Collector finders
2
Database tables
Finders database
despatch
3
returns
pending
processing
CollectorDetails agent
4
despatch
returns
Figure 14. Collector discovery process flow: discovery of device existence
The following process flow describes Figure 14:
▌1▐: The collector finders receive instructions from its configuration files and
then proceeds to the network to look for collectors.
▌2▐: The collector finders return the list of devices to the finders.returns table.
▌3▐: Immediately after the device existence information is placed into the
finders.returns table, the FnderRetProcessing stitcher moves the information to
the finders.processing table, to denote that the network entity is being
processed. If the discovery is in the blackout state, the information is placed
into the finders.pending table.
▌4▐: The FnderProcToDetailsDesp stitcher moves the information about device
existence from the finders.processing table to the CollectorDetails.despatch table
so that the CollectorDetails agent can process the information.
440
IBM Tivoli Network Manager IP Edition: Discovery Guide
Discovering basic device information
During a collector discovery, the discovery of basic device information takes place
in several steps.
The following figure shows how basic device details are discovered in a collector
discovery.
Network
H
H
2
Helper server
1
3
CollectorDetails agent
H: Collector
Figure 15. Collector discovery process flow: Discovery of basic device information
The following process flow describes Figure 15:
▌1▐: All the agent despatch tables are active, so an insertion into the
CollectorDetails.despatch table automatically triggers the CollectorDetails agent
to discover basic device information from the collector.
▌2▐: The CollectorDetails agent uses the Helper Server to interrogate the helper
collector .
▌3▐: The information retrieved from the network is returned to the
CollectorDetails.returns table.
Appendix B. Discovery process
441
Discovering detailed device information
During a collector discovery, the discovery of detailed device information takes
place in several steps.
The following figure shows how detailed device information is discovered in a
collector discovery.
Network
CollectorLTE agent
CollectorRan agent
Helper
Helper
2
Helper server
CollectorInventory agent
CollectorVpn agent
CollectorLayer1 agent
1
CollectorLayer2 agent
1
CollectorLayer3 agent
1
CollectorDetails agent
Figure 16. Collector discovery process flow: detailed device information
The following process flow describes Figure 16:
▌1▐: The CollectorDetailsRetProcessing stitcher passes the information in the
CollectorDetails.returns table to the despatch table of the various collector agents
for processing.
▌2▐: Inserting information into the despatch table of an agent triggers an attempt
by that agent to discover information about that device. The collector agents
interrogate the collectors to discover the following information about each device.
CollectorInventory agent
Retrieves local neighbor, entity and associated address data for each of the
devices on the collector.
CollectorLayer1
442
IBM Tivoli Network Manager IP Edition: Discovery Guide
Retrieves layer 1 and microwave connectivity information for the devices
on the collector.
CollectorLayer2
Retrieves layer 2 connectivity information for the devices on the collector.
CollectorLayer3
Retrieves layer 3 connectivity information for the devices on the collector.
CollectorLTE
Retrieves LTE-specific entity information for the devices on the collector.
CollectorRan
Retrieves radio access network (RAN) information for the devices on the
collector.
CollectorVpn
Retrieves layer 2 and layer 3 VPN data for the devices on the collector.
Rediscovery
When a discovery has completed, ncp_disco enters rediscovery mode, in which the
discovery of new devices results in updates to the topology model.
Full and partial rediscovery
By modifying the stitchers, you can configure the way DISCO treats devices that
are found in the rediscovery mode.
By default, when the system is in rediscovery mode and either a new device is
found or an existing device changes, the device is rediscovered. The stitchers
ensure that the device is rediscovered only once. The stitchers also check that the
change has not caused the relationship of the device with its neighbors to change.
If necessary, the neighbors of the device are rediscovered. If the number of devices
that need to be rediscovered as a result of relationship changes exceeds a certain
limit, the rediscovery process initiates a full rediscovery.
Related concepts:
“About types of discovery” on page 1
Different terms are used to describe network discovery, depending on what is
being discovered and how the discovery has been configured. You can run
discoveries, rediscoveries, and full and partial discoveries.
Process flow of the FnderRetProcessing stitcher
To configure the way in which DISCO handles newly discovered devices, edit the
FnderRetProcessing.stch stitcher. This stitcher processes the entries that are placed
into the finders.returns table.
The default process flow of the FnderRetProcessing.stch stitcher is:
1. When an entry is placed in the finders.returns table, the stitcher checks whether
the device is in the scope of the discovery. If the device is not in scope, it is
ignored.
2. If the device is in scope and disco.status.m_DiscoveryMode=0, that is, DISCO is
in discovery mode, the stitcher moves the device details to either the
finders.pending table to be processed later (if the discovery is in the blackout
state) or the finders.processing table to be processed now.
Appendix B. Discovery process
443
3. If the device is in scope and disco.status.m_DiscoveryMode=1, that is, DISCO is
in rediscovery mode, the stitcher determines whether the device needs to be
rediscovered. By default, the stitcher rediscovers:
v Devices for which finders.returns.m_Creator='Rediscovery'. There is no
Rediscovery finder, but this column is set to 'Rediscovery' by other stitchers,
such as ProcRemoteConns.stch, to indicate that as a result of rediscovering
other devices this device needs to be rediscovered.
v Any newly found device that is in scope and has not already been
discovered.
4. If necessary, you can alter the section of the FnderRetProcessing.stch stitcher
that performs the above checks in order to configure when rediscovery of a
device takes place, although this configuration adjustment must be undertaken
by advanced users only.
5. If a device that has already been discovered is to be rediscovered, the stitcher
refreshes the information held in the Helper Server that relates to that device.
6. For all devices to be rediscovered, the stitcher removes the old entries for that
device from the finders.processing, Details.returns and Details.despatch tables,
copying the old information to the rediscoveryStore.dataLibrary table for
comparison purposes.
7. The stitcher then places the details of the device to be rediscovered into the
finders.processing table and the FnderProcToDetailsDesp.stch stitcher moves
the device details to the Details agent.
Processing information from discovery agents during
rediscovery
After the entity that is being rediscovered has been processed by the Details agent,
and the details are placed in the Details.returns table, the DetailsRetProcessing.stch
stitcher compares the old data in the rediscoveryStore.dataLibrary table with the
new data. By default, the rediscovery continues from this point.
If necessary, you can edit the DetailsRetProcessing.stch stitcher so that rediscovery
continues only when certain conditions are in place. For example, rediscovery
continues only when SNMP access is available.
The rediscovery data is processed by the AssocAddress agent and then by the
appropriate agents (according to the configured discovery process flow) and sent
to their returns tables.
A full discovery combines the information from the discovery agent returns tables
to produce the topology. However, in a rediscovery, the information must be
checked to determine whether the relationships between devices have changed as a
result of the new information.
For example, if the device being rediscovered, device A, was connected to device B
before the rediscovery, but is now connected to a third device, device C, then both
B and C must also be rediscovered because their relationship has changed. The
AgentRetProcessing.stch stitcher determines the relationships between devices and
the comparison is done by ProcRemoteConns.stch. Switches and hubs need to be
rediscovered differently to routers because the connectivity information they
provide is indirect instead of direct. Any entity that also needs to be rediscovered
as a consequence of rediscovery is inserted back into the finders.returns table with
the parameter m_Creator='Rediscovery'.
444
IBM Tivoli Network Manager IP Edition: Discovery Guide
Full rediscoveries
Comparing the current relationship between devices to their previous relationship,
and rediscovering all the devices whose relationships have changed, can sometimes
become circular. However, the discovery process includes a check to prevent this
repetition.
If the ratio of entities that have been compared to the entities that need to be
rediscovered exceeds the percentage specified in the
disco.config.m_PendingPerCent column, then DISCO stops rediscovering
individual devices and initiates a full network discovery.
Additionally, the fact that all rediscovered entities are recorded in the
rediscoveryStore.rediscoveredEntities table means that a given entity can be
rediscovered only once.
Rediscovery completion
When all the entities that need to be rediscovered have been processed, the
topology layers are rebuilt by the FinalPhase.stch stitcher. This stitcher also clears
the rediscoveryStore database so that it is ready for the next rediscovery.
It is important to note that DISCO might go through many discovery cycles during
rediscovery before the topology is rebuilt. DISCO rebuilds the topology only when
there are no entities needing to be rediscovered.
Option to rebuild topology layers
You can specify whether to rebuild the topology layers following a partial
rediscovery. Using this option, you can increase the speed of partial rediscovery.
Suggested reasons to rebuild or not to rebuild the topology layers are:
v If you specify that the topology layers should not be rebuilt following partial
rediscovery, the result is that new devices are added to the topology much faster
than they would be if the topology layers are rebuilt; however, the resulting
topology may not be complete. Connectivity associated with the newly
discovered device is not fully reflected in the topology. Topology layers are fully
rebuilt when a full rediscovery is run.
v If you specify that topology layers should be rebuilt following partial rediscovery,
the result is an accurate topology showing all connectivity. However the process
of adding new devices takes longer.
Use the m_RebuildLayers field in the disco.config table to specify whether or not
to rebuild topology layers following partial rediscovery. You set this value as
follows:
v If disco.config.m_RebuildLayers=0, then following partial rediscovery, topology
layers stitchers are not run. The result is a much quicker partial discovery:
however, connectivity associated with the newly discovered device is not fully
reflected in the topology.
v If disco.config.m_RebuildLayers=1, then following partial rediscovery, topology
layers stitchers are run. Partial rediscovery takes longer but results in a complete
topology.
Appendix B. Discovery process
445
446
IBM Tivoli Network Manager IP Edition: Discovery Guide
Appendix C. Discovery agents
Use this information to support the selection of discovery agents to run as part of
your discovery.
The following topics provide information on the discovery agents available. There
is also guidance on the agents to select, based on the characteristics of your
network.
Agents
Discovery agents retrieve information about devices in the network. They also
report on new devices by finding new connections when investigating device
connectivity. Discovery agents are used for specialized tasks. For example, the ARP
Cache discovery agent populates the Helper Server database with IP
address-to-MAC address mappings.
In addition to the main discovery agents, which can be enabled or disabled
according to your discovery requirements, there are two agents that must always
be run: the Details agent and the Associated Address agent.
Each discovery agent has its own database resident within DISCO. These databases
are generically structured and based on a template called the agentTemplate
database.
Each discovery agent database contains the following tables:
v agentName.despatch
v agentName.returns
Note: The default configuration sets the majority of agents to run. This is because
the more agents that are run, the wider the range of networks that can be
discovered. Furthermore, agents are designed to quickly stop analyzing devices
that do not provide the data they require. This means that running a large number
of agents increases network traffic by a very small amount only.
Note: Network Manager kills all discovery agents at the end of data collection
stage 3. This ensures that the next discovery restarts the agents and forces the
agents to reread their configuration files at the beginning of a discovery, thereby
detecting any changes to the configuration files.
Related reference:
“Subprocess databases” on page 335
The finders, Details, and agent databases are used during the discovery by the
discovery engine subprocesses to store information retrieved from the network.
The databases are defined within the configuration file, DiscoSchema.cfg.
“DiscoAgentReturns.filter configuration file” on page 64
The DiscoAgentReturns.filter configuration file allows you to apply a topology
data filter to data returned by all discovery agents.
© Copyright IBM Corp. 2006, 2017
447
Details agent
This agent is triggered by the entries in the finders.processing table. At least one
finder is needed to activate this agent. The SNMP helper configuration for
associated devices is also a prerequisite for running this agent.
The Details agent retrieves basic information about devices discovered by the
finders, and determines whether SNMP access to the device is available. This
mandatory agent is triggered by the entries in the finders.processing table, so at
least one finder is needed to activate this agent.
The Details agent is triggered when device information (usually transferred from
the finders by a stitcher) is placed in the Details.despatch database table.
The Details agent retrieves basic information from the network and deposits this
information in the Details.returns table. The basic information retrieved
comprises the DNS name of the device obtained by the configured DNS helper,
and the system object ID obtained by the SNMP helper. IpForwarding data is
downloaded and inserted into the ExtraInfo field which is used to identify routing
devices. SysName information is also downloaded for use if this optional naming
scheme is required. The insertion of data into the returns table triggers a stitcher
that sends this information to the Associated Address agent.
Related concepts:
“Discovering device details (standard)” on page 432
The standard discovery of device details is carried out in several steps.
Associated Address (AssocAddress) agent
This mandatory agent is triggered by the output of the Details agent. The SNMP
helper configuration for associated devices is a prerequisite for running this agent.
When an interface on a device has been discovered, and basic device information
has been retrieved by the Details agent, a stitcher passes the discovered device
information to the Associated Address agent. This agent downloads all the other IP
addresses associated with the device and adds them to a central registry, held in
the translations.ipToBaseName table, provided the device details are not already
in the registry. Downloading all the associated IP addresses ensures that any given
device is only interrogated once by the main discovery agents, thus reducing the
load on the agents. Any attempt to discover a device more than once (using
multiple interfaces) is blocked by the Associated Address agent as the device
details are already in the translations database.
Provided the device being checked has not already been discovered, a stitcher
sends the device details to the appropriate discovery agent for the retrieval of
device connectivity and protocol-specific information.
Related concepts:
“Discovering associated device addresses” on page 434
There are several steps in the process flow during the discovery of associated
device addresses.
448
IBM Tivoli Network Manager IP Edition: Discovery Guide
Interface data retrieved by agents
The Interfaces agent downloads interface information primarily from the interfaces
table of RFC1213.mib. For each device discovered, the interface information is
written to the m_LocalNbr field within each record in the relevant agent.returns
table.
The interface information can hold a number of subfields, including an index
number that identifies the interface together with the properties of that interface
and values for each property. For example, the m_LocalNbr field may include the
following subfields:
v m_LocalNbr->m_IfIndex: the index associated with this interface
v m_LocalNbr->m_IfType: the type of interface
v m_LocalNbr->m_SubnetMask: the subnet mask of the interface
Related reference:
“Connectivity at the layer 3 network layer” on page 460
There are a number of discovery agents that retrieve connectivity information from
OSI model layer 3 (the Network Layer). Layer 3 is responsible for routing,
congestion control, and sending messages between networks.
Discovery agent definition file keywords
Discovery agent definition file keywords are used to define the operation of
discovery agents.
DiscoAgentClass
The DiscoAgentClass keyword specifies the basic type of agent. The following table
identifies the most commonly used values:
Value
Description
0
Specifies an IP type agent.
1
Specifies a switch type agent.
2
Specifies a hub type agent.
3
Specifies an ATM device type agent.
4
Specifies an FDDI type agent.
5
Specifies a PVC type agent.
6
Specifies a frame relay type agent.
8
Specifies a NAT gateway agent.
The following example shows a DiscoAgentClass keyword set to a frame relay
type agent. Frame relay type agents typically discover Frame Relay interfaces and
connections between two points on Frame Relay networks that incorporate specific
network devices, for example, CISCO devices.
DiscoCompiledAgent
{
.
.
.
DiscoAgentClass( 6 );
.
.
.
}
Appendix C. Discovery agents
449
DiscoAgentClassEnabledByDefault
The DiscoAgentClassEnabledByDefault keyword specifies whether the agent is
enabled by default for full discoveries. Specify one of the following values:
Value
Description
0
Specifies that the agent is not enabled by
default for full discoveries.
1
Specifies that the agent is enabled by default
for full discoveries.
The following example shows a DiscoAgentClassEnabledByDefault keyword set to
enable a frame relay type agent by default for full discoveries.
DiscoCompiledAgent
{
.
.
.
DiscoAgentClass( 6 );
.
.
.
DiscoAgentEnabledByDefault( 1 );
}
DiscoAgentClassEnabledByDefaultOnPartial
The DiscoAgentClassEnabledByDefaultOnPartial keyword specifies whether the
agent is enabled by default for partial discoveries. Specify one of the following
values:
Value
Description
0
Specifies that the agent is not enabled by
default for partial discoveries.
1
Specifies that the agent is enabled by default
for partial discoveries.
The following example shows a DiscoAgentClassEnabledByDefaultOnPartial
keyword set to enable a frame relay type agent by default for partial discoveries.
DiscoCompiledAgent
{
.
.
.
DiscoAgentClass( 6 );
.
.
.
DiscoAgentEnabledByDefaultOnPartial( 1 );
DiscoAgentEnabledByDefault( 1 );
}
DiscoAgentIsIndirect
A direct agent returns relationship data about objects that it is directly connected to
at the layer it deals with. An indirect agent returns relationship data about objects
it is indirectly connected to. The most common indirect agents are switch agents.
450
IBM Tivoli Network Manager IP Edition: Discovery Guide
The remote neighbor records for indirect agents relate to devices that can be
reached from a specific port, not from devices to which they are directly connected.
The relationship data from indirect agents is required to determine which remote
neighbor records of a device need to be rediscovered when the device changes.
The DiscoAgentIsIndirect keyword specifies whether the agent is an indirect
agent that returns relationship data about objects it is indirectly connected to.
Specify one of the following values:
Value
Description
0
Specifies that the agent is a direct agent.
1
Specifies that the agent is an indirect agent.
The following example shows a DiscoAgentIsIndirect keyword set to specify that
a frame relay type agent is a direct agent.
DiscoCompiledAgent
{
.
.
.
DiscoAgentGUILocked( 0 );
DiscoAgentClass( 6 );
DiscoAgentIsIndirect( 0 );
.
.
.
DiscoAgentEnabledByDefaultOnPartial( 1 );
DiscoAgentEnabledByDefault( 1 );
}
DiscoAgentCompanionAgents
The DiscoAgentCompanionAgents keyword is used to display in the GUI the agent
or agents that this agent should execute with.
The following example shows a DiscoAgentCompanionAgents keyword that displays
in the GUI the agent (ArpCache.agnt) that should execute with the Centillion
Networks agent.
DiscoCompiledAgent
{
.
.
.
-- This agent examines all devices originally made by Centillion
-- Networks (enterprise OID 1.3.6.1.4.1.930), to see if it can
-- discover them.
.
.
.
DiscoAgentCompanionAgents( "ArpCache" );
.
.
.
}
Appendix C. Discovery agents
451
DiscoAgentCompletionPhase
The DiscoAgentCompletionPhase keyword specifies during which of the discovery
phases the specified agent should complete executing. Specify one of the following
values:
Value
Description
1
Specifies that the agent should complete
execution during discovery phase 1.
2
Specifies that the agent should complete
execution during discovery phase 2.
3
Specifies that the agent should complete
execution during discovery phase 3.
The following example shows a DiscoAgentCompletionPhase keyword set to enable
a frame relay type agent to complete execution during discovery phase 1.
DiscoCompiledAgent
{
.
.
.
DiscoAgentCompletionPhase( 1 );
.
.
.
DiscoAgentEnabledByDefaultOnPartial( 1 );
DiscoAgentEnabledByDefault( 1 );
}
DiscoAgentConflictingAgents
The DiscoAgentConflictingAgents keyword is used to display in the GUI the agent
or agents that this agent should not execute with.
The following example shows a DiscoAgentConflictingAgents keyword that
displays in the GUI the agents (IpRoutingTable.agnt and IpForwardingTable.agnt)
that should not execute with the IP backup routes agent.
DiscoCompiledAgent
{
.
.
.
-- This agent examines every device with SNMP access to see if it
-- can discover it.
.
.
DiscoAgentConflictingAgents( "IpRoutingTable","IpForwardingTable" );
.
.
.
}
DiscoAgentDescription
The DiscoAgentDescription keyword specifies a description of the agent that is
displayed in the GUI.
452
IBM Tivoli Network Manager IP Edition: Discovery Guide
The following example shows a DiscoAgentDescription keyword that specifies a
description to display in the GUI for a frame relay type agent. The description
makes use of HTML coding.
DiscoCompiledAgent
{
.
.
.
DiscoAgentDescription("
<b>Agent Name :</b> CiscoFrameRelay<br>
<br>
<b>Agent Type :</b> Layer 3<br>
<br>
<b>Agent Prerequisites :</b> SNMP helper configuration for associated devices.<br>
<br>
<b>Operation :</b><br>
Discovers Frame Relay interfaces and connections between two points on Frame Relay
networks that incorporate Cisco devices. If you need to add DLCI information to the
interfaces of Frame Relay devices, then run Frame Relay agents in conjunction with
the IP layer agents.<br>
<br>
");
.
.
.
}
DiscoAgentMinCertifiedDeviceOS
The DiscoAgentMinCertifiedDeviceOS keyword specifies a device operating system
specific filter. This filter can be configured to run the specified agent against
specific releases of a device operating system.
The following example shows a DiscoAgentMinCertifiedDeviceOS keyword that
specifies a device operating system specific filter for an agent that discovers MPLS
VRFs, VPNs, and label switching information from CISCO routers. This device
operating specific filter configures the agent to run against the following CISCO
devices and associated operating system releases:
v m_ObjectId — Specifies the CISCO devices (OID 1.3.6.1.4.1.9) that the agent
attempts to discover.
v m_OSVersion — Specifies the CISCO device operating system filter that
configures the agent to run against the following device operating system
versions:
– 12.0 releases of 12.0(27) or later which are not experimental
– 12.2 releases of 12.2(19) or later which are not experimental
– 12.3 releases of 12.3(18) or later which are not experimental
– 12.4 releases
DiscoCompiledAgent
{
.
.
.
DiscoAgentMinCertifiedDeviceOS
(
"(
m_ObjectId LIKE ’1\.3\.6\.1\.4\.1\.9\.’,
m_OSVersion >= ’12.0(27)’ AND m_OSVersion < ’12.1’ AND m_OSVersion
NOT LIKE ’.*Experimental.*’,
m_MibVar = ’sysDescr.0’
),
Appendix C. Discovery agents
453
(
m_ObjectId LIKE ’1\.3\.6\.1\.4\.1\.9\.’,
m_OSVersion >= ’12.2(19)’ AND m_OSVersion < ’12.3’ AND m_OSVersion
NOT LIKE ’.*Experimental.*’,
m_MibVar = ’sysDescr.0’
),
(
m_ObjectId LIKE ’1\.3\.6\.1\.4\.1\.9\.’,
m_OSVersion >= ’12.3(18)’ AND m_OSVersion < ’12.4’ AND m_OSVersion
NOT LIKE ’.*Experimental.*’,
m_MibVar = ’sysDescr.0’
),
(
m_ObjectId LIKE ’1\.3\.6\.1\.4\.1\.9\.’,
m_OSVersion >= ’12.4’,
m_MibVar = ’sysDescr.0’
)"
);
.
.
.
}
DiscoAgentPrecedence
The DiscoAgentPrecedence keyword specifies which agent gets precedence when
there is conflicting data from two agents. Specify a value that is greater than or
equal to 0 (zero). The recommended range of values is from 1 to 100, where the
higher the number the higher the precedence. The higher the precedence the more
that agent data is correct. For example, if given conflicting data from a precedence
2 agent and a precedence 3 agent then the precedence 3 agent data is used.
The following example shows a DiscoAgentPrecedence keyword for a frame relay
type agent set to a precedence of 2.
DiscoCompiledAgent
{
.
.
.
DiscoAgentGUILocked( 0 );
DiscoAgentClass( 6 );
DiscoAgentIsIndirect( 0 );
DiscoAgentPrecedence( 2 );
.
.
.
DiscoAgentEnabledByDefaultOnPartial( 1 );
DiscoAgentEnabledByDefault( 1 );
}
DiscoPerlAgent
The DiscoPerlAgent keyword specifies whether this .agnt file refers to a Perl
agent.
The following example shows a DiscoPerlAgent keyword specified for a Perl based
agent that extracts information about the operating system running on the device.
DiscoPerlAgent
{
.
.
.
454
IBM Tivoli Network Manager IP Edition: Discovery Guide
DiscoAgentGUILocked( 0 );
DiscoAgentClass( 0 );
DiscoAgentIsIndirect( 0 );
DiscoAgentPrecedence( 2 );
DiscoAgentEnabledByDefaultOnPartial( 0 );
DiscoAgentEnabledByDefault( 0 );
}
Types of agents
The agents supplied with Network Manager can be divided into categories
according to the type of data they retrieve or the technology they discover.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
Discovery agents that discover connectivity among Ethernet
switches
Discovery agents that discover connectivity information between Ethernet switches
have three main operational stages: gain access to the switch and download all the
switch interfaces; discover VLAN information for the switch; download the
forward database table for the switch.
A list of the discovery agents that handle Ethernet switches is shown in Table 170.
Note: Before you enable these layer 2 agents, it is necessary to configure SNMP
access. Some agents also require Telnet access and Telnet Helper configuration.
Table 170. Ethernet switch discovery agents
Agent name
Function
AccelarSwitch
The AccelarSwitch agent contains the specialized methods
for retrieving connectivity information from Accelar
routing switches. These devices are now branded as the
Nortel Passport 86xx series. This agent also discovers
BayStack 450 and BayStack 470 devices.
This agent downloads the switch forwarding database
(FDB) table and the VLAN information for the device. The
switch stitcher uses this information to resolve layer 2
Ethernet connectivity.
BayEthernetHub
The BayEthernetHub agent discovers hub cards that are
manufactured by Bay. Connectivity information is
downloaded from the hub and the connectivity is resolved
by the HubFdbToConnections stitcher.
Before you enable this agent, it is also necessary to
configure the SNMP Helper.
Appendix C. Discovery agents
455
Table 170. Ethernet switch discovery agents (continued)
Agent name
Function
CentillionSwitch
The CentillionSwitch agent contains the methods that are
needed to retrieve and resolve information from the
Centillion switching devices, in particular the
enterprise-specific VLAN information.
ChipcomDistributedMM
The ChipcomDistributedMM agent discovers the Ethernet
switch connectivity for 3Com CoreBuilder 5000 devices
that contain distributed management modules.
ChipcomEthernetMM
The ChipcomEthernetMM agent is appropriate for
Chipcom online concentrators that contain Ethernet
Management Modules (EMMs), and discovers the Ethernet
connectivity of Chipcom EMMs.
CiscoSRP
The CiscoSRP agent discovers the connectivity of networks
by using the Spatial Reuse Protocol (SRP), that is, DPT
Ring topologies. SRP is a layer 2 protocol that was
developed by Cisco. It uses ‘side' information to identify
adjacent neighbors in its ring topology. The CiscoSRP
agent discovers connectivity of any device that supports
the CISCO-SRP-MIB. The agent definition file is configured
by default to accept only Cisco devices with any IOS
version, except devices that are supported by the
CiscoSRPTelnet agent. The agent accepts only devices that
support the srpMacAddress MIB variable.
IOS version 12.2(14)S7 and 12.2(18)S, used with NPE-G1
cards, are known to corrupt SNMP data. IOS version
12.2(15)BC1 is known to lack CISCO-SRP_MIB support.
CiscoSRPTelnet
The CiscoSRPTelnet agent discovers the connectivity of
networks by using the Spatial Reuse Protocol (SRP), that
is, DPT Ring topologies. SRP is a layer 2 protocol that was
developed by Cisco that uses ‘side' information to identify
adjacent neighbors in its ring topology. The
CiscoSRPTelnet agent discovers the connectivity of any
device that supports the show controllers srp command.
The agent definition file is configured to accept only Cisco
devices that have an IOS that is known not to support the
CISCO-SRP-MIB. Those IOS versions that have issues with
SNMP discovery. IOS version 12.2(14)S7 and 12.2(18)S,
used with NPE-G1 cards, are known to corrupt SNMP
data. IOS version 12.2(15)BC1 is known to lack
CISCO-SRP_MIB support.
Note: Before you enable this agent, configure Telnet access
and the Telnet Helper.
CiscoSwitchSnmp
The CiscoSwitchSnmp agent contains the specialized
methods for retrieving information from Cisco switches by
using SNMP. This agent uses different methods for finding
VLANs and card or port to ifIndex mappings because
different Cisco switches store this information in different
MIB variables.
The CiscoSwitchSnmp agent also discovers Virtual Port
Channel (vPC) links from Forwarding Database (FDB)
data.
456
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 170. Ethernet switch discovery agents (continued)
Agent name
Function
CiscoSwitchTelnet
The CiscoSwitchTelnet agent contains specialized methods
for retrieving connectivity information from Cisco switches
by using Telnet. This agent uses different methods to find
VLANs and card/port to ifIndex mappings because
different Cisco switches store this information in different
MIB variables. Only FDB tables are downloaded by using
Telnet. All other information is downloaded by using
SNMP.
The Telnet commands that are used to obtain the FDB
table are show cam dynamic and show mac-address table.
Some devices might require enable mode to run the show
mac-address table command.
Note: Before you enable this agent, configure SNMP and
Telnet access and the SNMP and Telnet Helpers.
CiscoVSS
The Cisco VSS agent discovers Virtual Switching System
information from Cisco switches.
Corebuilder3ComSwitch
The Corebuilder3ComSwitch agent discovers links for the
CoreBuilder 9000 layer 3 switches that are manufactured
by 3Com.
DasanSwitchTelnet
The DasanSwitchTelnet agent is responsible for the
discovery of the layer 2 connectivity in the FDB/MAC
table of Dasan switches. The agent was developed against
the following devices: V5208 (OS 9.07)V5224 (OS 9.10). The
agent is able to discover layer 2 connectivity, VLANs, and
trunk ports. It is configured to run only against devices
with a sysObjectID of 1.3.6.1.4.1.6296.* and that support
the command show vlan.
Note: Before you enable this agent, configure Telnet access
and the Telnet Helper.
DefaultEthernetHub
This agent has a specialized class for dealing with
semi-intelligent hubs.
EnterasysSwitch
The EnterasysSwitch agent provides layer 2 connectivity
discovery by retrieving the FDB table and VLAN
information from the device. The agent discovers layer 2
connectivity for devices that support the IEEE 802.1q or
IEEE 802.1d standards, as modeled in the Q-BRIDGE-MIB
and BRIDGE-MIB SNMP MIBs.
Note: This agent is used for Enterasys devices that do not
have SecureFast turned on.
ExtremeSwitch
The ExtremeSwitch agent obtains layer 2 connectivity
information, EDP neighbors, and VLAN details from
Extreme switches.
The Extreme devices must be configured to enable SNMP
access and dot1dFdbTable population to achieve a detailed
layer 2 discovery. Send the following commands to each
Extreme device:
v enable snmp access
v enable dot1dFdbTable
This configuration change is only required on switches
that are running a version of ExtremeWare® before 6.1.8.
Appendix C. Discovery agents
457
Table 170. Ethernet switch discovery agents (continued)
Agent name
Fix Pack 2
F5Switch
FoundrySwitch
Function
This agent discovers configuration for F5 switches. The
agent retrieves information from the sysChassisSlotSlotId
variable in the F5-BIGIP-COMMON-MIB and
F5-BIGIP-SYSTEM-MIB MIBs.
Note: Before you enable this agent, configure SNMP and
Telnet access and the SNMP and Telnet Helpers.
The FoundrySwitch agent discovers switch connectivity of
any Foundry device that supports the IEEE 802.1q or IEEE
802.1d standards, as modeled in the Q-BRIDGE-MIB and
BRIDGE-MIB SNMP MIBs.
The agent definition file is configured to accept all
SNMP-enabled Foundry devices by default. The agent
discovers only devices that support the Q-BRIDGE-MIB
dot1qVlanVersionNumber MIB variable or the
BRIDGE-MIB. The FoundrySwitch agent also obtains
multislot port trunking information, but does not discover
single-slot port trunking. Some Foundry devices support
only IEEE 802.1d and as a consequence no VLAN
information is discovered for these devices.
HuaweiSwitchTelnet
The HuaweiSwitchTelnet agent discovers the Ethernet
switch connectivity for Huawei Quidway switches.
This agent is Telnet-based, but also requires SNMP access
to discover certain information. It requires completion of
the Privileged mode (Super 3 mode) sections of the
TelnetStackPasswords.cfg configuration file. If you do not
complete these parts of the file, the agent fails.
Certain Telnet commands have the side-effect of changing
the command prompt of a Huawei device. For example,
the command prompt:
<device_name> becomes
[device_name] or
[device_name-diag] when certain commands are entered.
The parameters m_ConPrompt and m_PrivConPrompt in
the TelnetStackPasswords.cfg file must be configured to
cope with these variations.
Note: Before you enable this agent, configure Telnet access
and the Telnet Helper.
458
HPSwitch
The HPSwitch agent contains the specialized methods for
retrieving connectivity information from HP ProCurve
switches, including the download of enterprise-specific
VLAN information.
Marconi3810
The Marconi3810 specialized agent discovers the Ethernet
connectivity of Marconi ES-3810 switches that run
operating system version 4.x.x and 5.x.x. This agent also
removes connectivity from LANE interfaces by default,
which can be configured by using the GetElanData flag in
the .agnt file.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 170. Ethernet switch discovery agents (continued)
Agent name
Function
SecureFast
The SecureFast agent contains the specialized methods for
retrieving connectivity information from
Enterasys/Cabletron SecureFast VLAN switches. These
devices use the Cabletron Discovery Protocol to discover
their neighbors. The SecureFast operating mode is turned
on. This agent is sent to all Cabletron and Enterasys
devices that are specified by 1.3.6.1.4.1.52.* and
1.3.6.1.4.1.5624.* in the .agnt file, and determines whether
a device is SecureFast enabled by downloading the
sfpsCommonNeighborSwitchMAC MIB variable.
Devices in SecureFast mode do not support the
dot1dBridge MIBs.
StandardSwitch
The StandardSwitch generic agent provides layer 2
connectivity discovery of all switches for which a
specialized agent does not exist. The agent discovers layer
2 connectivity for devices that support the IEEE 802.1q or
IEEE 802.1d standards, as modeled in the Q-BRIDGE-MIB
and BRIDGE-MIB SNMP MIBs.
Devices in SecureFast mode do not support the
dot1dBridge MIBs.
SuperStack3ComSwitch
The SuperStack3ComSwitch agent finds the connections in
stacked switches that are manufactured by 3Com.
XyplexEthernetHub
The XyplexEthernetHub agent discovers the layer 2
connectivity of intelligent hubs that are manufactured by
Xyplex.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
“DiscoTelnetHelperSchema.cfg configuration file” on page 83
The DiscoTelnetHelperSchema.cfg configuration file defines the operation of the
Telnet helper, which returns the results of a Telnet operation into a specified
device.
Appendix C. Discovery agents
459
Connectivity at the layer 3 network layer
There are a number of discovery agents that retrieve connectivity information from
OSI model layer 3 (the Network Layer). Layer 3 is responsible for routing,
congestion control, and sending messages between networks.
Table 171. Layer 3 network layer agents
Agent name
Function
AlteonVRRP
VRRP is not modelled for RCA. The AlteonVRRP agent only sets tags on VRRP
interfaces that show the state of Alteon routers at the time of the discovery.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
CiscoBGPTelnet
The CiscoBGPTelnet agent downloads the following BGP data from Cisco routers:
v Peer data: the agent retrieves iBGP and eBGP data from peer routers.
v Route data: the agent retrieves routing information from BGP routing tables of
peer routers. This option is off by default as it will retrieve huge amounts of
data from a typical service provider network. This agent also provides the option
to configure a filter to specify the route data that you would like to retrieve.
Note: Before enabling this agent, configure Telnet access and the Telnet helper.
CiscoFrameRelay
The CiscoFrameRelay agent discovers Frame Relay interfaces and connections
between two points on Frame Relay networks that incorporate Cisco devices.
Frame Relay agents should be run in conjunction with the IP layer agents if you
want to add DLCI information to the interfaces of Frame Relay devices.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
CiscoOSPFTelnet
The CiscoOSPFTelnet agent is responsible for discovery of Cisco devices running
the Open Shortest Path First (OSPF) protocol. This agent provides complementary
information to that of the StandardOSPF agent, such as what OSFP processes are
running and virtual-link information.
Note: Before enabling this agent, configure Telnet access and the Telnet helper.
ExtremeESRP
The ExtremeESRP agent discovers Extreme Standby Routing Protocol (ESRP)
information from Extreme routing switches. ESRP is a feature of ExtremeWare that
allows multiple switches to provide redundant routing services to users. The agent
relies on the extremeEsrpTable and extremeEsrpNeighborTable of the
EXTREME-ESRP-MIB being correctly populated.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
FoundryVRRP
VRRP is not modelled for RCA. The FoundryVRRP agent only sets tags on VRRP
interfaces that show the state of Foundry routers at the time of the discovery.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
HSRPSnmp
The HSRPSnmp agent retrieves connectivity information using SNMP by means of
the MIB from routing devices that use the HSRP (Hot Stand-by Routing Protocol)
Virtual IP protocol.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
InetRouting
The InetRouting agent discovers connectivity.
Interfaces
This agent is triggered by the AssocAddress agent returns.
The Interfaces agent downloads interface information primarily from the interfaces
table of RFC1213.mib. The information will then be written to the m_LocalNbr field
of the returned entities. You can increase or decrease the number of returned
variables by modifying the Interfaces.agnt. Any basic MIB variable (sysDescr,
sysName, and so on) or MIB variable that is indexed by the ifIndex can be added
to the OIDs to download in the .agnt file.
The Interfaces agent also retrieves IPv6 interface information.
You must enable the Interfaces agent if you want to use interface filtering.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
460
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 171. Layer 3 network layer agents (continued)
Agent name
Function
IpBackupRoutes
The IpBackupRoutes agent finds links by looking through the IpNetToMedia MIB
table, which gives the physical and IP address of devices connected to the router.
This agent is not enabled by default because it retrieves a large amount of
information that is not essential in order to determine layer 3 connections.
Furthermore, this information may be obsolete because it is downloaded from a
table that is not dynamic and requires manual refresh. If you are performing a
layer 2 discovery, then the server connectivity that this agent discovers is often
obsolete, as it may have been superseded by switch connectivity information.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
IpForwardingTable
The IpForwardingTable agent finds links in the more recent version of the routing
tables, that is, the IP Forwarding table as specified in RFC 2096. It also exploits
Open Shortest Path First (OSPF) information to enhance the discovery of Juniper
devices. This agent downloads elements from the routing table based on discovery
scoping. The default setting assumes that the SNMP agent for a particular device
supports partial matching. If the device cannot partial match, this should be
specified in the DiscoRouterPartialMatchRestrictions section of the .agnt file.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
IpRoutingTable
Retrieves generic connectivity information by looking through the router routing
table, as specified in RFC1213. The agent downloads elements from the routing
table based on discovery scoping. The default agent setting assumes that the SNMP
agents for particular devices support partial matching. If a device cannot partial
match, this should be specified in the DiscoRouterPartialMatchRestrictions section
of the .agnt file.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
ISISExperimental
Discovers connectivity between routers that support the experimental ISIS MIBs.
This agent should be used when some of your routers are configured with
netmasks of 255.255.255.255, making them unsuitable for standard discovery.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
LinkStateAdvOSPF
Retrieves link state advertisements (LSAs) from OSPF routers. These LSAs are used
by the CreateOSPFNetworkLSAPseudoNodes stitcher to create OSPF pseudonodes.
Pseudonodes overcome the problem of full meshing when representing OSPF area
in Topoviz Network Views and enables connections within OSPF areas to be
visualized in a clear, uncluttered manner.
JuniperBGPTelnet
Downloads BGP information from Juniper routers. It is not enabled by default
because it gathers a very specific piece of information only, that is, whether devices
are route reflectors.
Note: Before enabling this agent, configure Telnet access and the Telnet helper.
NetScreenInterface
The NetScreenInterface agent retrieves information about all configured interfaces
in Juniper Netscreen devices. The agent retrieves information about logical
interfaces and other interfaces, which is not available from the standard IF-MIB,
and requires both the NETSCREEN-INTERFACE-MIB.mib and NS-VPN-MON.mib
files. The agent also retrieves VPN tunnel and tunnel connectivity information that
is configured in Juniper NetScreen devices.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
Appendix C. Discovery agents
461
Table 171. Layer 3 network layer agents (continued)
Agent name
Function
NetScreenIpRoutingTable
The NetScreenIpRoutingTable agent retrieves information on IP routing tables
configured on Netscreen devices. The agent determines the interfaces and
sub-interfaces from the interface index of the Netscreen device.
This agent performs the same function as the IpRoutingTable agent, but for
Netscreen devices only, in order to take account of sub-interfaces which would not
be discovered correctly by the IpRoutingTable agent.
The NetScreenIpRoutingTable agent uses the IP-FORWARD-MIB Standard MIB and
the NETSCREEN-INTERFACE-MIB.
Note: The IpRoutingTable agent does not process the Netscreen devices processed
by the NetScreenIpRoutingTable agent.
NokiaVRRP
Downloads VRRP information from routers that support the Nokia interpretation
of the VRRP MIB. The information retrieved includes the VRRP state, ID, primary
IP and associated addresses. This information is retrieved from the following MIB
variables:
v vrrpOperState
v vrrpOperMasterIpAddr
v vrrpAssoIpAddrRowStatus
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
NortelPassport
RFC2787VRRP
The NortelPassport agent retrieves Layer 3 connectivity and containment
information from Nortel Passport switches.
The RFC2787VRRP agent downloads Virtual Router Redundancy Protocol (VRRP)
information from routers that run RFC2787-compliant VRRP and support the
RFC2787 VRRP MIB. Some Nokia firewalls support this MIB.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
VRRP is not modelled for RCA. This agent sets tags on VRRP interfaces that show
the state of the interfaces at the time of the discovery. The agent also downloads
associated IP addresses, which are used to build VRRP collections.
Tip: There are two subtly different versions of the VRRP MIB. They contain the
same names but with different OIDs. If this agent does not work, use the other
version of the VRRP MIB.
462
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 171. Layer 3 network layer agents (continued)
Agent name
Function
StandardBgp
The StandardBgp agent is responsible for discovery of networks running the
Border Gateway Protocol. It supports any device that complies with the standard
RFC1657 (BGP4-MIB) MIB and discovers the following information:
v Autonomous System IDs
v BGP Peer connections to external peers (EBGP)
v BGP Peer connections to internal peers (IBGP)
v BGP acquired route data (not recommended)
The agent definition file is configured to accept all SNMP enabled devices by
default, but the agent will only accept devices that support the BGP44-MIB,
bgpIdentifier MIB variable.
The agent has the following additional configuration parameters in the
DiscoAgentDiscoveryScoping section of its .agnt file:
v GetPeerData – determines whether the agent should acquire BGP Peer data
(activated by default).
v GetRouteData – determines whether the agent should acquire BGP routes
(deactivated by default). This may result in a large amount of data being
discovered.
The StandardBgp agent does not currently support peer groups, confederations, per
VRF BGP processes, or route reflection.
Note: Before enabling this agent, configure SNMP access and the SNMP helper. It
is also necessary to configure the Ping helper.
StandardOSPF
The StandardOSPF agent is responsible for the discovery of networks running the
Open Shortest Path First (OSPF) protocol. It will support any device that complies
with the standard RFC1850.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
TraceRoute
The TraceRoute agent finds links by tracing the route taken by an ICMP ping
packet with a predetermined life span. If you are using this agent, you should
increase the value of m_Timeout in the DiscoPingHelperSchema.cfg configuration
file, as traceroute functionality takes longer than standard ICMP. This agent is not
enabled by default as it does not only operate on SNMP-enabled devices.
Therefore, if this agent were switched on by default, it would trace the route to
every device on the network. The result could be incomplete connectivity in a
meshed environment or inaccurate connectivity in a load-balanced environment.
Note: Before enabling this agent, configure SNMP access and the SNMP helper.
Related tasks:
“Configuring device access” on page 32
Specify SNMP community strings and Telnet access information to enable helpers
and Network Manager polling to access devices on your network.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
Appendix C. Discovery agents
463
“DiscoPingHelperSchema.cfg configuration file” on page 73
The DiscoPingHelperSchema.cfg configuration file defines how devices are to be
pinged.
Topology data stored in an EMS
There are several discovery agents that retrieve information about devices
managed by an EMS.
The routing protocol discovery agents query an EMS collector for basic and
detailed information about devices managed by EMS. These agents are shown in
Table 172.
Table 172. Routing protocol discovery agents
Agent name
Function
CollectorDetails
Retrieves basic information about the devices on the collector,
including sysObjectId, sysDescr, and naming data.
CollectorInventory
Retrieves local neighbor, entity and associated address data for
each of the devices on the collector.
CollectorLayer1
Retrieves layer 1 and microwave connectivity information for the
devices on the collector.
CollectorLayer2
Retrieves layer 2 connectivity information for the devices on the
collector.
CollectorLayer3
Retrieves layer 3 connectivity information for the devices on the
collector.
CollectorLTE
Retrieves LTE-specific entity information for the devices on the
collector.
CollectorRan
Retrieves radio access network (RAN) information for the
devices on the collector.
CollectorVpn
Retrieves layer 2 and layer 3 VPN data for the devices on the
collector.
Related concepts:
“Other components of the EMS integration” on page 110
In addition to collectors, EMS integration is composed of several components that
assist in the collection of topology data.
Discovering connectivity among ATM devices
Asynchronous Transfer Mode (ATM) is an alternative switching protocol for mixed
format data (such as pure data, voice, and video). Several types of discovery
agents can be used to discover ATM devices on a network.
Note: Before enabling these agents, it is necessary to configure SNMP access and
the SNMP Helper.
Table 173. ATM discovery agents
464
Agent name
Function
AtmForumPnni
The AtmForumPnni agent retrieves connectivity information from ATM
devices that use the Private Network-to-Network Interface (PNNI)
dynamic routing protocol and the ATM Forum's PNNI MIB. The PNNI
protocol is commonly used on large networks, as it provides ATM
switches with a detailed map of the network topology so that the ATM
devices can make optimal routing decisions.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 173. ATM discovery agents (continued)
Agent name
Function
CellPath90
The CellPath90 agent enables discovery of the ATM connection of
Marconi CellPath 90 WAN (Wide Area Network) multiplexers. The
CellPath 90 WAN multiplexer does not know the ATM addresses of its
neighbours, so it can only be discovered when it is connected to
another, more intelligent, certified ATM device.
The CellPath90 discovery agent is used in the calculation of network
topology. It places information about the CellPath 90 into the correct
layers within the discovery database.
CiscoPVC
The CiscoPVC agent retrieves PVC data from Cisco devices.
ILMI
The ILMI agent retrieves connectivity information from devices using
the Interim Local Management Interface (ILMI), an RFC standard for
managing ATM and IP networks. It investigates how ATM networks
are connected down to the layer 2 virtual circuit and port level. This
agent also removes logical connectivity from LANE interfaces.
ILMIForeSys
The ILMIForeSys agent discovers physical ATM connections between
devices by using the ILMI (Interim Local Management Interface)
connectivity information provided by the Marconi ASX series of
switches.
When connectivity is deduced using ILMI information, it is usually the
same as the connectivity that could have been calculated using PNNI
information, as is the case with the standard AtmForumPnni and ILMI
agents. However, there are some situations where the ILMI information
contains details of a connection that is not in the PNNI information,
and some situations where the PNNI information details a connection
not in the ILMI information. The following examples detail situations
where this may be the case:
v Connections between ASX series switches and SE420/SE440 IADs are
only discovered using ILMI.
v Connections between Cisco routers or switches containing ATM
cards and an ATM core are only discovered using ILMI.
v As with the PnniForeSys agent, the ILMIForeSys agent is designed to
operate seamlessly in conjunction with the ILMI agent. A network
containing a mixture of ASX devices and another vendor's devices
(for example, Cisco 5509 switches with ATM cards) can, therefore, be
accurately discovered.
MariposaAtm
The MariposaAtm agent discovers the ATM connectivity of the SE420
and SE440 Integrated Access Devices (IADs).
Note: The Ethernet switching and Frame Relay capabilities of these
devices are not currently certified.
PnniForeSys
The PnniForeSys agent discovers physical ATM connections between
devices by using the Private Network-to-Network Interface (PNNI)
connectivity information provided by the Marconi ASX series switches.
The PnniForeSys agent is designed to operate in conjunction with the
AtmForumPnni agent.
The PnniForeSys agent performs extra processing on Fore devices that
do not store a logical ifIndex in their pnniLinkIfIndex variable. The
information retrieved from these devices requires further processing to
retrieve the actual ifIndex, which is held within the ifTable .
Note: SNMP helper configuration for associated devices is a
prerequisite for this agent. The AtmForumPnni agent must also be
active.
Appendix C. Discovery agents
465
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
Agents for discovering MPLS devices
To discover Multiprotocol Label Switching (MPLS) data, including Virtual Private
LAN Service (VPLS) information, enable the appropriate agents.
The agents that retrieve MPLS data use either Telnet or SNMP to retrieve the data.
Before you enable the MPLS agents, configure Telnet and SNMP access.
v Before you enable the MPLS agents that use Telnet, configure Telnet to enable
the agents to access devices and to understand device output.
v Before you enable the MPLS agents that use SNMP, configure SNMP to enable
access to devices and to specify threads, timeouts, and number of retries.
Tip: Agents that retrieve VPLS information can retrieve large amounts of data.
Enabling these agents can add significant processing time to the discovery process.
If you do not need to rediscover VPLS information, disable these agents for a faster
discovery.
Table 174. MPLS discovery agents
466
Agent name
Function
CiscoMPLSSnmp
The CiscoMPLSSnmp agent discovers MPLS paths on Cisco
devices by using standard MIBs, and on Cisco devices that
support the Cisco Experimental MPLS MIBs.
CiscoMPLSTelnet
The CiscoMPLSTelnet agent discovers MPLS paths and LDP
VPLS on Cisco devices.
CiscoQinQTelnet
The CiscoQinQTelnet agent discovers QinQ (IEEE 802.1QinQ)
configuration on Cisco devices.
HuaweiMPLSTelnet
The HuaweiMPLSTelnet agent discovers Layer 2 and Layer 3
MPLS/VPN related data on Huawei devices, including
User-facing Provider Edge (UPE) and Network Provider Edge
(NPE) information. You must configure the discovery to
discover and visualize VPLS information from Huawei VPNs.
JuniperMPLSTelnet
The JuniperMPLSTelnet agent discovers MPLS paths on
Juniper devices. This agent also discovers Juniper MultiHome
VPLS configurations and tags the Virtual Switch Instance (VSI)
with the relevant information.
JuniperMPLSSNMP
The JuniperMPLSSNMP agent discovers MPLS/VPN (RT-based
VPN discovery) and VPLS (LDP and BGP) related data on
Juniper devices.
JuniperQinQTelnet
The JuniperQinQTelnet agent discovers QinQ (IEEE 802.1QinQ)
configuration on Juniper devices.
LaurelMPLSTelnet
The LaurelMPLSTelnet agent discovers MPLS paths on Laurel
devices. This agent is intended for route target-based
discoveries only.
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 174. MPLS discovery agents (continued)
Agent name
Function
StandardMPLSTE
The StandardMPLSTE discovers MPLS Traffic Engineered (TE)
tunnels by using SNMP.
UnisphereMPLSTelnet
The UnisphereMPLSTelnet agent discovers MPLS paths on
Juniper ERX routers (formerly Unisphere).
Related tasks:
“Configuring discovery of Huawei VPNs” on page 194
To visualize VPN information from Huawei devices, you must configure the
discovery.
Multicast agents
Multicast agents retrieve data from devices participating in multicast groups and
routes.
The agents that retrieve multicast data need SNMP and Ping access to retrieve the
data. Before enabling the multicast agents, ensure that you first configured SNMP
to enable the agents to access devices and to specify threads, timeouts, and number
of retries.
The following table describes the multicast agents.
Table 175. Multicast discovery agents
Agent name
Function
StandardIGMP
Discovers networks running the Internet Group Management
Protocol (IGMP). Supports any device that complies with the
RFC2933 IGMP MIB. Depending on the level of MIB support,
the following information may be discovered: IGMP Interfaces;
Per-Interface Group Memberships; Group Members Visible on
IGMP Interfaces.
StandardIPMRoute
Discovers IP multicasting networks. Supports any device that
complies with the RFC2932 IPMRoute MIB. Depending on the
level of MIB support, the following information may be
discovered: Multicast Routing data (upstream/downstream);
Interfaces involved in Multicast Routing; Multicast Sources and
Groups.
StandardPIM
Discovers networks running the Multicast protocol PIM.
Supports any device that complies with the RFC2934 PIM MIB.
Depending on the level of MIB support, the following
information may be discovered: PIM Interfaces; PIM
Adjacencies; Candidate RPs/BSR.
Related tasks:
“Enabling the multicast agents” on page 44
To discover multicast groups, you must enable the appropriate agents and add the
relevant SNMP community strings.
Appendix C. Discovery agents
467
Discovering NAT gateways
There are several agents that download Network Address Translation (NAT)
information from known NAT gateways.
None of the agents listed in the table below is enabled in the default configuration.
These agents require advanced configuration, and it is preferable not to enable
them by default.
Table 176. NAT gateway agents
Agent name
Function
CiscoNATTelnet
The CiscoNATTelnet agent interrogates Cisco routers acting as NAT
gateways. This agent downloads the static NAT translations by means
of TELNET from the device. The translations are then used to identify
within which part of the network a particular device exists.
Note: Before enabling this agent, it is necessary to configure Telnet
access and the Telnet Helper.
NATNetScreen
The NATNetScreen agent interrogates NetScreen® Firewalls acting as
NAT gateways. This agent downloads the static NAT translations by
means of TELNET from the device. The translations are then used to
identify within which part of the network a particular device exists.
Note: Before enabling this agent, it is necessary to configure Telnet
access and the Telnet Helper.
NATTextFileAgent The NATTextFileAgent mimics the function of the other NAT gateway
agents by reading NAT mapping information from a flat file. The
translations are then used to identify within which part of the network
a particular device exists.
Note: Before enabling this agent, it is necessary to configure SNMP
access and the SNMP Helper.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetStackPasswords.cfg configuration file defines access credentials for Telnet
access to devices.
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
“DiscoTelnetHelperSchema.cfg configuration file” on page 83
The DiscoTelnetHelperSchema.cfg configuration file defines the operation of the
Telnet helper, which returns the results of a Telnet operation into a specified
device.
468
IBM Tivoli Network Manager IP Edition: Discovery Guide
Discovering containment information
An important principle used by the network model is containment. A container
holds other objects. You can put any object within a container and even mix
different objects within the same container.
Containment information includes a physical breakdown of all parts held within
the container, as well as detailed information on each of these parts. The parts that
can be held within a container are:
v Chassis
v Interface
v Logical interface
v Vlan object
v Card
v PSU
v Logical collection, such as a VPN
v Module
There is also an Unknown category, which covers entities for which no part type
has been defined.
The following table describes the discovery agents that discover containment
information.
Table 177. Discovery agents that discover containment information
Agent name
Function
AvayaPhysicalInventory
The AvayaPhysicalInventory agent queries RAPID-CITY MIB for each physical
entity and retrieves containment information for that physical entity. Run the
AvayaPhysicalInventory agent if you want to model physical containment and
perform asset management. Enable this agent if you have Avaya (formerly Nortel)
devices in your network.
Note: Configure SNMP access and the SNMP Helper before enabling this agent.
BrocadeEntity
The BrocadeEntity agent queries FOUNDRY-SN-ROOT-MIB, IF-MIB and ENTITY-MIB
MIBs for Brocade ICX and VDX devices for each physical entity. The agent
retrieves containment information for that physical entity.
Run the BrocadeEntity agent if you want to model physical containment and
perform asset management for ICX6430, ICX7430, VDX8770 and VDX6470 devices.
Enable this agent if you have Brocade devices in your network.
Note: Configure SNMP access and the SNMP Helper before enabling this agent.
IBMSystemNetworkingSwitch
The IBMSystemNetworkingSwitch agent retrieves Layer 2 connectivity and VLAN
containment information (including VLAN tags, VLAN Trunk, and Trunk Group
information) using SNMP.
Appendix C. Discovery agents
469
Table 177. Discovery agents that discover containment information (continued)
Agent name
Function
Entity
The Entity agent queries the MIB for each entity and retrieves containment
information for that entity. Before enabling this agent, you must configure SNMP
access and the SNMP Helper.
Running the Entity agent during a discovery is optional. Some containment
information is gathered during a discovery even if the Entity agent is not run. Run
the Entity agent to model physical containment and perform asset management.
Note: During a discovery, the Entity agent retrieves a large amount of data. This
slows down the discovery. You should therefore only use this agent if you need to
perform asset management on the retrieved data.
For information on Entity agent configuration, see “Entity agent configuration” on
page 471.
IfStackTable
The IfStackTable determines the interface stacking hierarchy on devices that
support the RFC 2863 MIB.
Note: Configure SNMP access and the SNMP Helper before enabling this agent.
JuniperBoxAnatomy
The JuniperBoxAnatomy agent retrieves information about which modules and
components are installed in a Juniper device and their containment. The agent uses
vendor-specific MIBs such as the Juniper Box Anatomy MIB.
JuniperERXIfStackTable
The JuniperERXIfStackTable determines the interface stacking hierarchy on Juniper
ERX devices.
This agent determines virtual-router and VRF context-sensitive stacking
information for Juniper ERX devices. When a context-sensitive discovery is enabled
this agent can be disabled, as the IfStackTable agent also determines this
information. This will improve the performance of discovery.
Note: Configure SNMP access and the SNMP Helper before enabling this agent.
JuniperLAGStack
The JuniperLAGStack agent retrieves Link Aggregation Group (LAG) information
from Juniper devices. LAG information is needed to accurately represent the
interface stacking hierarchy.
JuniperVlanTagTelnet
Discovers VLAN tagging configuration for Juniper E, ERX, M and MX Series
routers. For Juniper model MX, M and T series, the agent issues the telnet
command show configuration interfaces and captures the vlan-id from the
output. For Juniper model E and ERX series, the agent retrieves
juniVlanSubIfVlanId and juniVlanSubIfVlanStackId from the Juniper-ETHERNETMIB.
Note: Configure the SNMP Helper and the Telnet Helper before enabling this
agent.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
470
IBM Tivoli Network Manager IP Edition: Discovery Guide
Entity agent configuration
You can configure the Entity agent to specify how much data the agent should
retrieve. You can optionally choose to download this extra information from the
entity MIBs of the Asset, ExtraPhysData, Module, Power®, and Sensor entities.
Configure the Entity agent by setting the following variables in the Entity.agnt
file:
v GetAssetData
v GetExtraPhysData
v GetModuleData
v GetPowerData
v GetSensorData
In each case, set a value of 1 to retrieve the data, and set a value of 0 if you do not
want to retrieve the data. The default value is 1.
In addition, you can specify how the Entity agent retrieves data from devices. The
options are as follows:
0 GetNext
This is the default value.
Using this data retrieval option, the system requests one SNMP variable at
a time from the device in series, that is, retrieval of one column in a table,
one value at a time for a given device. This approach is slower but puts
least pressure on the device. In a discovery with multiple entities the
expectation is that overall this approach will not slow down the discovery
as the SNMP helper is still busy with other activities. This approach might
take a long time for individual large devices. This method works with
SNMP version 1.
1 Asynchronous GetNext
Similar to the GetNext method in that one index is retrieved at a time with
the difference that all the columns are retrieved in parallel. This is also
supported by SNMP version 1 and is faster but it also puts slightly more
load on the device.
2 GetBulk
Requests the entire column or multiple columns and individual Get
commands in one go. This method requires SNMP version 2 support. If the
device only supports version 1 then the retrieval method is broken down
into multiple SNMP Get Next and Get commands. This is the fastest
retrieval and it does not put much more load on the device than the
Asynchronous GetNext method. This method also involves larger packets
on the network.
Note: The Entity.agnt file, together with all other agent configuration files, can be
found in the $NCHOME/precision/disco/agents directory.
Appendix C. Discovery agents
471
Discovery agents for wireless networks
Network Manager provides agents that discover devices on wireless networks.
Table 178. Discovery agents on wireless networks
Agent name
Function
Airspace
The Airspace Perl discovery agent retrieves WLAN information from
devices using the Airspace MIBs.
Discovery agents on other protocols
Network Manager provides agents that discover devices that use other protocols
than ones previously described.
Note: Before enabling these agents, it is necessary to configure SNMP access and
the SNMP Helper.
Table 179. Discovery agents on other protocols
Agent name
Function
AlteonStp
This is a Spanning Tree Protocol discovery agent for Alteon switches that support the
dot1dStp section of the BRIDGE-MIB.
BrocadeFDPSnmp
The BrocadeFDPSnmp agent provides Layer 2 links using the Foundry Discovery Protocol
(FDP). The agent establishes links between Brocade devices. By using the
FOUNDRY-SN-ROOT-MIB and IF-MIB MIB files, the agent can discover the neighboring devices
and store minimal information about the local device and its corresponding neighbor. This
agent uses the index from the FDP network layer address of the device to find complete
information that links to the neighboring devices.
CDP
The CDP agent understands the protocol used among Cisco communication devices. Using
CDP, Cisco devices can discover their nearest neighbors and store minimal information about
them.
This agent begins with the address of a known Cisco device and uses CDP to find more
complete information about the locations of other connected or neighboring Cisco devices.
DefaultLLDP
The DefaultLLDP agent discovers layer 2 connectivity between devices that support the LLDP
MIB and have Link Layer Discovery Protocol (LLDP) enabled.
Both the LLDP and DefaultLLDP agents use data from the LLDP MIB that is indexed by
lldpRemLocalPortNum. This variable indicates which ifIndex or port a particular LLDP
connection exists on. The LLDP agent supports devices where lldpRemLocalPortNum refers
to the ifIndex on the device: typically, Cisco devices. The DefaultLLDP agent supports devices
where lldpRemLocalPortNum refers to the port or other arbitrarily assigned index: typically,
non-Cisco devices such as Juniper or BNT devices.
The DefaultLLDP agent checks if the device supports the Extended-LLDP-MIB. If the device
does not support the Extended-LLDP-MIB, lldpRemLocalPortNum is assumed to be a switch
port. The agent then uses the dot1dBasePortIfIndex variable from the BRIDGE-MIB to
determine the ifIndex of this record. Enable both the LLDP and DefaultLLDP agents so that
Network Manager is able to find LLDP connectivity on devices that have different
implementations of lldpRemLocalPortNum.
FddiDefault
The FddiDefault agent discovers any device that supports the standard FDDI MIB. When an
FDDI device is interrogated, information relating to the interfaces of that device and its
upstream and downstream neighbours is returned. The FddiLayer stitcher uses this and all
other FDDI agents to determine the FDDI ring topology.
FddiCiscoConc
The FddiCiscoConc agent discovers Cisco Concentrator FDDI devices. Cisco concentrators
know the full connectivity of every FDDI ring that passes though them, as opposed to just
their upstream and downstream neighbours. Hence the FddiLayer stitcher gives the topology
information returned by this agent precedence over that found by FddiDefault.
472
IBM Tivoli Network Manager IP Edition: Discovery Guide
Table 179. Discovery agents on other protocols (continued)
Agent name
Function
LLDP
The LLDP agent discovers layer 2 connectivity between devices that support the LLDP MIB
and have Link Layer Discovery Protocol (LLDP) enabled.
Both the LLDP and DefaultLLDP agents use data from the LLDP MIB that is indexed by
lldpRemLocalPortNum. This variable indicates which ifIndex or port a particular LLDP
connection exists on. The LLDP agent supports devices where lldpRemLocalPortNum refers
to the ifIndex on the device: typically, Cisco devices. The DefaultLLDP agent supports devices
where lldpRemLocalPortNum refers to the port or other arbitrarily assigned index: typically,
non-Cisco devices such as Juniper or BNT devices.
The LLDP agent checks if the device supports the Extended-LLDP-MIB. If it does, the agent
retrieves the mapping between lldpRemLocalPortNum and ifIndex. If the device does not
support the Extended-LLDP-MIB, lldpRemLocalPortNum is assumed to be the ifIndex. Enable
both the LLDP and DefaultLLDP agents so that Network Manager is able to find LLDP
connectivity on devices that have different implementations of lldpRemLocalPortNum.
SONMP
The SONMP agent uses the SynOptics Network Management Protocol, the protocol used
between Nortel communications devices. The SONMP agent begins with the address of a
known Nortel device and uses SONMP to discover location, containment, address, and
connection information from connected, or neighbouring, Nortel devices.
StandardSTP
The StandardSTP agent discovers STP connectivity data on any STP-enabled switch that
supports the dot1dSTP section of the BRIDGE-MIB. You should run this agent in addition to
any other necessary switch agents in order to discover STP backup (blocking) connections.
The STP switch discovery method has the following advantages over other switch-based
discovery methods:
v Hidden links: STP backup (blocking) connections are discovered.
v Speed: the agent completes in Phase 1; no pinging is required.
Note : The STP agent only shows connections between STP enabled switches, that is, it
ignores connections to nodes, non-switch devices, and non-STP enabled switches.
This agent will not discover multiple STP instances, VLANs, or Virtual Routers.
Related reference:
“SnmpStackSecurityInfo.cfg configuration file” on page 87
The SnmpStackSecurityInfo.cfg configuration file defines the community strings,
versioning, and other properties used by any process that needs to interrogate
devices using SNMP, for example, the SNMP helper. Community strings can be
configured on a per-device or per-subnet basis, to allow the SNMP Helper to
retrieve MIB variables from devices.
“DiscoSnmpHelperSchema.cfg configuration file” on page 82
The DiscoSnmpHelperSchema.cfg configuration file defines the operation of the
SNMP Helper, which specifies the general rules of SNMP information retrieval.
Appendix C. Discovery agents
473
Context-sensitive discovery agents
There are several agents that take part in a context-sensitive discovery.
Attention: Enabling a context-sensitive discovery enables all the Context agents.
The discovery process runs the appropriate agents for the devices to be discovered,
based on the OID defined in the agent definition files. Disabling a context-sensitive
discovery disables all the Context agents and no Context agents will run. You do
not need to enable or disable individual Context agents.
Note: These agents require Telnet access and the Telnet Helper.
Table 180. Context-sensitive discovery agents
Agent Name
Function
CheckpointContext
This Perl agent queries CheckPoint VSX firewalls to retrieve
context data. Retrieving context data allows other
context-sensitive discovery agents to retrieve interface and
connectivity data from the appropriate contexts.
CheckpointVSX
The CheckpointVSX agent retrieves details of the virtual firewalls
running on a VSX device. For those virtual firewalls it retrieves
further information to resolve the dependencies between the
physical hardware and the logical interfaces running on top of the
hardware. This information is then used to inform the root cause
analysis and better model the VSX devices.
CiscoNexusContext
Discovers VRF context-sensitive information from Cisco Nexus
family devices.
Prerequisite: You must configure an SNMP context for each VRF
so that the VRFs can be discovered.
The SNMP context is used to discover the IP address and IP
routing data from non-default VRFs.
RedbackContext
The RedbackContext agent discovers virtual router
context-sensitive information for Redback devices.
UnisphereERXContext
The UnisphereERXContext agent discovers virtual router and VRF
context-sensitive information for Juniper ERX devices.
You can restrict the scope of the VRF contexts discovered by
configuring the optional DiscoAgentDiscoveryScoping section in
the .agnt file. The configurable options are:
v IncludeVRF – allows the discovery of the named VRF.
v ExcludeVRF – does not discover the specified VRF.
VRF names are case-sensitive. The wildcard " * " can be used in
place of a VRF name to apply the filter to all VRFs. If no filters
are specified, all VRFs will be discovered by default.
Related concepts:
“Context-sensitive discovery” on page 18
If you need to discover devices that support multiple contexts, you must run a
context-sensitive discovery. For example, a device that uses separate SNMP
contexts to provide access to its virtual routers. Context-sensitive discovery ensures
correct representation of context-accessible virtual devices. Always check that your
particular device type is supported for discovery.
Related tasks:
474
IBM Tivoli Network Manager IP Edition: Discovery Guide
“Configuring a context-sensitive discovery” on page 104
If you need to discover devices that support multiple contexts, you must run a
context-sensitive discovery. For example, a device that uses separate SNMP
contexts to provide access to its virtual routers. Context-sensitive discovery ensures
correct representation of context-accessible virtual devicess. Always check that your
particular device type is supported for discovery.
Related reference:
“DiscoConfig.cfg configuration file” on page 73
The DiscoConfig.cfg configuration file is used to have the Ping finder automatically
check the devices discovered by the File finder, and to enable a context-sensitive
discovery.
“TelnetStackPasswords.cfg configuration file” on page 90
The TelnetSt