Netcool/Precision IP Discovery Configuration Guide 3.6

frontmatter.fm August 16, 2006 

Netcool/Precision for IP 

NetworksTM 3.6 

Discovery Configuration Guide

© 2006 Micromuse Inc., Micromuse Ltd. 

All rights reserved. No part of this work may be reproduced in any form or by any 

person without prior written permission of the copyright owner. This document is 

proprietary and confidential to Micromuse, and is subject to a confidentiality 

agreement, as well as applicable common and statutory law. 

Micromuse Disclaimer of Warranty and Statement of Limited Liability 

Micromuse provides this document “as is”, without warranty of any kind, either 

express or implied, including, but not limited to, the implied warranties of 

merchantability, fitness for a particular purpose or non-infringement. This 

document may contain technical inaccuracies or typographical errors. Micromuse 

may make improvements and changes to the programs described in this document 

or this document at any time without notice. Micromuse assumes no responsibility 

for the use of the programs or this document except as expressly set forth in the 

applicable Micromuse agreement(s) and subject to terms and conditions set forth 

therein. Micromuse does not warrant that the functions contained in the programs 

will meet your requirements, or that the operation of the programs will be 

uninterrupted or error-free. Micromuse shall not be liable for any indirect, 

consequential or incidental damages arising out of the use or the ability to use the 

programs or this document. 

Micromuse specifically disclaims any express or implied warranty of fitness for high 

risk activities. 

Micromuse programs and this document are not certified for fault tolerance, and 

are not designed, manufactured or intended for use or resale as on-line control 

equipment in hazardous environments requiring fail-safe performance, such as in 

the operation of nuclear facilities, aircraft navigation or communication systems, 

air traffic control, direct life support machines, or weapons systems (“High Risk 

Activities”) in which the failure of programs could lead directly to death, personal 

injury, or severe physical or environmental damage. 

Compliance with Applicable Laws; Export Control Laws 

Use of Micromuse programs and documents is governed by all applicable federal, 

state and local laws. All information therein is subject to U.S. export control laws 

and may also be subject to the laws of the country where you reside. 

All Micromuse programs and documents are commercial in nature. Use, 

duplication or disclosure by the United States Government is subject to the 

restrictions set forth in DFARS 252.227-7015 and FAR 52.227-19. 

Trademarks and Acknowledgements 

Micromuse and Netcool are registered trademarks of Micromuse. 

Other Micromuse trademarks include but are not limited to: Netcool/OMNIbus, 

Netcool/OMNIbus for Voice Networks, Netcool/Reporter, Netcool/Internet 

Service Monitors, Netcool/ISM, Netcool/ISM Global Perspective, Netcool/NT 

Service Monitors, Netcool/Wireless Service Monitors, Netcool/WSM, 

Netcool/Usage Service Monitors, Netcool/USM, Netcool/Telco Service 

Monitors, Netcool/TSM, Netcool/Fusion, Netcool/Data Center Monitors, 

Netcool DCM, Netcool/Impact, Netcool/Visionary, Netcool/Precision, Netcool 

Probes & Monitors, Netcool Desktops, Netcool Gateways, Netcool Impact/Data 

Source Adaptors, Netcool EventList, Netcool Map, Netcool Virtual Operator, 

Netcool/Precision for IP Networks, Netcool/Precision for Transmission 

Networks, Netcool/Firewall, Netcool/Wave, Netcool/Webtop, Netcool TopoViz, 

Netcool/SM Operations, Netcool/SM Configuration, Netcool/OpCenter, 

Netcool/System Service Monitors, Netcool/SSM, Netcool/Application Service 

Monitors, Netcool/ASM, Netcool/ISM WAM, Netcool/SM Reporter, Netcool 

for Asset Management, Netcool/Realtime Active Dashboards, 

Netcool/Dashboards, Netcool/RAD, Netcool for Voice over IP, Netcool for 

Security Management, Netcool Security Manager, Netcool/Portal 2.0 Premium 

Edition, Netcool ObjectServer, Netcool/RAD, Netcool GUI Foundation, 

Netcool Installer, Netcool Licensing, Netcool/Software Developers Kit, NGF, 

Micromuse Alliance Program, Micromuse Channel Partner, Authorized Netcool 

Reseller, Netcool Ready, Netcool Solutions, Netcool Certified, Netcool Certified 

Consultant, Netcool Certified Trainer, Netcool CCAI Methodology, Micromuse 

University, Microcorrelation, Acronym, Micromuse Design, Integration Module 

for Netcool, The Netcool Company, VISIONETCOOL, Network Slice. 

Micromuse acknowledges the use of I/O Concepts Inc. X-Direct 3270 terminal 

emulators and hardware components and documentation in Netcool/Fusion. 

X-Direct ©1989-1999 I/O Concepts Inc. X-Direct and Win-Direct are 

trademarks of I/O Concepts Inc. 

Netcool/Fusion contains IBM Runtime Environment for AIX®, Java 

Technology Edition Runtime Modules © Copyright IBM Corporation 1999. All 

rights reserved. 

Netcool/Precision IP includes software developed by the University of California, 

Berkeley and its contributors. 

Micromuse acknowledges the use of MySQL in Netcool/Precision for IP 

Networks. Copyright © 1995, 1996 TcX AB & Monty Program KB & Detron 

HB Stockholm SWEDEN, Helsingfors FINLAND and Uppsala SWEDEN. All 

rights reserved. 

Micromuse acknowledges the use of the UCD SNMP Library in Netcool/ISM and 

the Netcool/OMNIbus SNMP Writer Gateway. Copyright © 1989, 1991, 1992 

by Carnegie Mellon University. Derivative Work - Copyright © 1996, 1998, 

1999, 2000 The Regents of the University of California. All rights reserved. 

Permission to use, copy, modify and distribute this software and its documentation 

for any purpose and without fee is hereby granted, provided that the above 

copyright notice appears in all copies and that both that copyright notice and this 

permission notice appear in supporting documentation, and that the name of 

CMU and The Regents of the University of California not be used in advertising 

or publicity pertaining to distribution of the software without specific written 

permission. 

CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 

INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 

AND FITNESS. IN NO EVENT SHALL CMU OR THE REGENTS OF THE 

UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL, 

INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 

WHATSOEVER RESULTING FROM THE LOSS OF USE, DATA OR 

PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 

OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 

CONNECTION WITH THE USE OR PERFORMANCE OF THIS 

SOFTWARE. 

Portions of the Netcool/OMNIbus code are copyright (C) 1989-95 GROUPE 

BULL. 

Permission is hereby granted, free of charge, to any person obtaining a copy of this 

software and associated documentation files (the “Software”), to deal in the 

Software without restriction, including without limitation the rights to use, copy, 

modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, 

and to permit persons to whom the Software is furnished to do so, subject to the 

following conditions: 

The above copyright notice and this permission notice shall be included in all 

copies or substantial portions of the Software. 

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF 

ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 

TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 

PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT 

SHALL GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR 

OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT 

OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION 

WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 

SOFTWARE. 

Portions of the Netcool/ISM code are copyright ©2001, Cambridge Broadband 

Ltd. All rights reserved. 

Portions of the Netcool/ISM code are copyright © 2001, Networks Associates 

Technology, Inc. All rights reserved. 

Micromuse acknowledges the use of Viador Inc. software and documentation for 

Netcool/Reporter. Viador © 1997-1999 is a trademark of Viador Inc.

Micromuse acknowledges the use of software developed by the Apache Group for 

use in the Apache HTTP server project. Copyright © 1995-1999 The Apache 

Group. Apache Server is a trademark of the Apache Software Foundation 

(http://www.apache.org/). All rights reserved. 

Micromuse acknowledges the use of software developed by Edge Technologies, 

Inc. 2003 Edge Technologies, Inc. and Edge enPortal are trademarks or registered 

trademarks of Edge Technologies Inc. All rights reserved. 

Micromuse acknowledges the use of Merant drivers. Copyright © MERANT 

Solutions Inc., 1991-1998. 

The following product names are trademarks of Tivoli Systems or IBM 

Corporation: AIX, IBM, OS/2, RISC System/6000, Tivoli Management 

Environment, and TME10. 

IBM, NetView/6000, Domino, Lotus, Lotus Notes, and WebSphere are either 

trademarks or registered trademarks of IBM Corporation. VTAM is a trademark 

of IBM Corporation. 

Omegamon is a trademark of Candle Corporation. 

Netspy is a trademark of Computer Associates International Inc. 

The Sun logo, Sun Microsystems, SunOS, Solaris, SunNet Manager, Java are 

trademarks of Sun Microsystems Inc. 

SPARC is a registered trademark of SPARC International Inc. Programs bearing 

the SPARC trademark are based on an architecture developed by Sun 

Microsystems Inc. SPARCstation is a trademark of SPARC International Inc., 

licensed exclusively to Sun Microsystems Inc. 

UNIX is a registered trademark of the X/Open Company Ltd. 

Sybase is a registered trademark of Sybase Inc. Adaptive Server is a trademark of 

Sybase Inc. 

Action Request System and Remedy are registered trademarks of Remedy 

Corporation. 

Peregrine System and ServiceCenter are registered trademarks of Peregrine Systems 

Inc. 

HP, HP-UX and OpenView are trademarks of Hewlett-Packard Company. 

InstallShield is a registered trademark of InstallShield Software Corporation. 

Microsoft, Windows 95/98/Me/NT/2000/XP are either registered trademarks or 

trademarks of Microsoft Corporation. 

Microsoft Internet Information Server/Services (IIS), Microsoft Exchange Server, 

Microsoft SQL Server, Microsoft perfmon, Windows Media, and Microsoft 

Cluster Service are either registered trademarks or trademarks of Microsoft 

Corporation in the United States and/or other countries. 

BEA and WebLogic are registered trademarks of BEA Systems Inc. 

FireWall-1 is a registered trademark of Check Point Software Technologies Ltd. 

Netscape and Netscape Navigator are registered trademarks of Netscape 

Communications Corporation in the United States and other countries. 

Netscape's logos and Netscape product and service names are also trademarks of 

Netscape Communications Corporation, which may be registered in other 

countries. 

Micromuse acknowledges the use of Xpm tool kit components. 

SentinelLM is a trademark of Rainbow Technologies Inc. 

GLOBEtrotter and FLEXlm are registered trademarks of Globetrotter Software 

Inc. 

Red Hat, the Red Hat “Shadow Man” logo, RPM, Maximum RPM, the RPM 

logo, Linux Library, PowerTools, Linux Undercover, RHmember, RHmember 

More, Rough Cuts, Rawhide and all Red Hat-based trademarks and logos are 

trademarks or registered trademarks of Red Hat Inc. in the United States and other 

countries. 

Linux is a registered trademark of Linus Torvalds. 

SUSE is a trademark of SUSE LINUX Products GmbH, a Novell business. 

Macromedia and Flash are trademarks or registered trademarks of Macromedia, 

Inc. in the United States and/or other countries. 

Nokia is a registered trademark of Nokia Corporation. 

WAP Forum and all trademarks, service marks and logos based on these 

designations (Trademarks) are marks of Wireless Application Protocol Forum Ltd. 

Micromuse acknowledges the use of InstallAnywhere software in Netcool/WAP 

Service Monitors. Copyright © Zero G Software Inc. 

Orbix is a registered trademark of IONA Technologies PLC. Orbix 2000 is a 

trademark of IONA Technologies PLC. 

NetCharts is a registered trademark of Visual Mining, Inc. and/or its affiliates. 

Micromuse acknowledges the use of Graph Layout Toolkit in Netcool/ Precision 

for IP Networks. Copyright © 1992 - 2001, Tom Sawyer Software, Berkeley, 

California. All rights reserved. 

Portions of Netcool/Precision for IP Networks and Netcool/SM Reporter are © 

TIBCO Software, Inc. 1994-2006. All rights reserved. TIB and TIB/Rendezvous 

are trademarks of TIBCO Software, Inc. 

Portions of Netcool/Precision for IP Networks & Netcool/OMNIbus probes and 

monitors are copyright © 1996-2005, Daniel Stenberg, . All 

rights reserved. Permission to use, copy, modify, and distribute this software for 

any purpose with or without fee is hereby granted, provided that the above 

copyright notice and this permission notice appear in all copies. 

THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF 

ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED 

TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A 

PARTICULAR PURPOSE AND NONINFRINGEMENT OF THIRD PARTY 

RIGHTS. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 

HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 

LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR 

OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH 

THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 

SOFTWARE. 

Except as contained in this notice, the name of a copyright holder shall not be used 

in advertising or otherwise to promote the sale, use or other dealings in this 

Software without prior written authorization of the copyright holder. 

Portions of Netcool/SM Reporter are copyrighted by DataDirect Technologies 

Corp., 1991-2005. 

Portions of Netcool/SM Reporter are copyright (c) 1990-1999 Sleepycat Software. 

All rights reserved. 

Redistribution and use in source and binary forms, with or without modification, 

are permitted provided that the following conditions are met: 

1. Redistributions of source code must retain the above copyright notice, this list 

of conditions and the following disclaimer. 

2. Redistributions in binary form must reproduce the above copyright notice, this 

list of conditions and the following disclaimer in the documentation and/or other 

materials provided with the distribution. 

3. Redistributions in any form must be accompanied by information on how to 

obtain complete source code for the DB software and any accompanying software 

that uses the DB software. The source code must either be included in the 

distribution or be available for no more than the cost of distribution plus a nominal 

fee, and must be freely redistributable under reasonable conditions. For an 

executable file, complete source code means the source code for all modules it 

contains. It does not include source code for modules or files that typically 

accompany the major components of the operating system on which the executable 

file runs. 

THIS SOFTWARE IS PROVIDED BY SLEEPYCAT SOFTWARE `ÀS IS'' 

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 

NOT LIMITED TO, THE IMPLIED WARRANTIES OF 

MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR 

NON-INFRINGEMENT, ARE DISCLAIMED. IN NO EVENT SHALL 

SLEEPYCAT SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT, 

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 

OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 

ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 

LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 

ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 

IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

Sleepycat software is available from 

http://downloads.sleepycat.com/db-3.0.55.zip. 

Portions of Netcool/SM Reporter are copyright (c) 1990, 1993, 1994, 1995. The 

Regents of the University of California. All rights reserved. 








3. Neither the name of the University nor the names of its contributors may be 

used to endorse or promote products derived from this software without specific 

prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE REGENTS AND 

CONTRIBUTORS `ÀS IS'' AND* ANY EXPRESS OR IMPLIED 

WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 

WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 

PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 

REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 

CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 

PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 

USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 

CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 

CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 

NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 

USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 

SUCH DAMAGE. 

Portions of Netcool/SM Reporter are copyright (c) 1995, 1996. The President and 

Fellows of Harvard University. All rights reserved. 








3. Neither the name of the University nor the names of its contributors may be 

used to endorse or promote products derived from this software without specific 

prior written permission. 

THIS SOFTWARE IS PROVIDED BY HARVARD AND ITS 

CONTRIBUTORS `ÀS IS'' AND ANY EXPRESS OR IMPLIED 



PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 

HARVARD OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, 

INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 








SUCH DAMAGE. 

Netcool/SM Reporter includes the Jetty Package which is copyright (c) 1998 Mort 

Bay Consulting Pty. Ltd. (Australia) and others. Individual files in this package 

may contain additional copyright notices. The javax.servlet packages are copyright 

Sun Microsystems Inc. 

1. The Standard Version of the Jetty package is available from 

http://www.mortbay.com. 

2. You may make and distribute verbatim copies of the source form of the Standard 

Version of this Package without restriction, provided that you include this license 

and all of the original copyright notices and associated disclaimers. 

3. You may make and distribute verbatim copies of the compiled form of the 

Standard Version of this Package without restriction, provided that you include 

this license. 

4. You may apply bug fixes, portability fixes and other modifications derived from 

the Public Domain or from the Copyright Holder. A Package modified in such a 

way shall still be considered the Standard Version. 

5. You may otherwise modify your copy of this Package in any way, provided that 

you insert a prominent notice in each changed file stating how and when you 

changed that file, and provided that you do at least ONE of the following: 

a) Place your modifications in the Public Domain or otherwise make them Freely 

Available, such as by posting said modifications to Usenet or an equivalent 

medium, or placing the modifications on a major archive site such as ftp.uu.net, or 

by allowing the Copyright Holder to include your modifications in the Standard 

Version of the Package. 

b) Use the modified Package only within your corporation or organization. 

c) Rename any non-standard classes so the names do not conflict with standard 

classes, which must also be provided, and provide a separate manual page for each 

non-standard class that clearly documents how it differs from the Standard 

Version. 

d) Make other arrangements with the Copyright Holder. 

6. You may distribute modifications or subsets of this Package in source code or 

compiled form, provided that you do at least ONE of the following: 

a) Distribute this license and all original copyright messages, together with 

instructions (in the manual page or equivalent) on where to get the complete 

Standard Version. 

b) Accompany the distribution with the machine-readable source of the Package 

with your modifications. The modified package must include this license and all 

of the original copyright notices and associated disclaimers, together with 

instructions on where to get the complete Standard Version. 

c) Make other arrangements with the Copyright Holder. 

7. You may charge a reasonable copying fee for any distribution of this Package. 

You may charge any fee you choose for support of this Package. You may not 

charge a fee for this Package itself. However, you may distribute this Package in 

aggregate with other (possibly commercial) programs as part of a larger (possibly 

commercial) software distribution provided that you meet the other distribution 

requirements of this license. 

8. Input to or the output produced from the programs of this Package do not 

automatically fall under the copyright of this Package, but belong to whomever 

generated them, and may be sold commercially, and may be aggregated with this 

Package. 

9. Any program subroutines supplied by you and linked into this Package shall not 

be considered part of this Package. 

10. The name of the Copyright Holder may not be used to endorse or promote 

products derived from this software without specific prior written permission. 

11. This license may change with each release of a Standard Version of the Package. 

You may choose to use the license associated with version you are using or the 

license of the latest Standard Version. 

12. THIS PACKAGE IS PROVIDED “AS IS” AND WITHOUT ANY 

EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT 

LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY 

AND FITNESS FOR A PARTICULAR PURPOSE. 

Netcool/SM Reporter includes FreeMarker, a tool that allows Java programs to use

templates to generate HTML or other text output that contains dynamic content. 

Copyright (C) 1998, 2002 Benjamin Geer. E-mail: beroul@users.sourceforge.net 



Redistributions of source code must retain the above copyright notice, this list of 

conditions and the following disclaimer. 

Redistributions in binary form must reproduce the above copyright notice, this list 

of conditions and the following disclaimer in the documentation and/or other 


Neither the name “Freemarker” nor any of the names of the project contributors 

may be used to endorse or promote products derived from this software without 

specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND 

CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED 




COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY 

DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 








SUCH DAMAGE. 

Copyright 2006 Micromuse. Portions of Netcool/WSM are licensed under the 

Apache License, Version 2.0 (the “License”); you may not use this file except in 

compliance with the License. You may obtain a copy of the License at 

http://www.apache.org/licenses/LICENSE-2.0. Unless required by applicable law 

or agreed to in writing, software distributed under the License is distributed on an 

“AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 

KIND, either express or implied. See the License for the specific language 

governing permissions and limitations under the License. 

Micromuse acknowledges the use of Digital X11 in Netcool/Precision for IP 

Networks. Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, 

Massachusetts, All Rights Reserved. DIGITAL DISCLAIMS ALL 

WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL 

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN 

NO EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT 

OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER 

RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN 

AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS 

ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR 

PERFORMANCE OF THIS SOFTWARE. 

Micromuse acknowledges the use of functionality within the Netcool/OMNIbus 

Probe for Ping that was developed by Stanford University. 

Netcool/SM Operations, Netcool/SM Configuration, and Netcool/OMNIbus 

probes and monitors include software developed by the OpenSSL Project for use 

in the OpenSSL Toolkit (http://www.openssl.org/. Copyright (c) 1998-2005 The 

OpenSSL Project. All rights reserved. Redistribution and use in source and binary 

forms, with or without modification, are permitted provided that the following 

conditions are met: 






3. All advertising materials mentioning features or use of this software must display 

the following acknowledgment: “This product includes software developed by the 

OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)” 

4. The names “OpenSSL Toolkit” and “OpenSSL Project” must not be used to 

endorse or promote products derived from this software without prior written 

permission. For written permission, please contact openssl-core@openssl.org. 

5. Products derived from this software may not be called “OpenSSL” nor may 

“OpenSSL” appear in their names without prior written permission of the 

OpenSSL Project. 

6. Redistributions of any form whatsoever must retain the following 

acknowledgment: “This product includes software developed by the OpenSSL 

Project for use in the OpenSSL Toolkit (http://www.openssl.org/)” 

THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT “AS IS” 

AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 

ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 

ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 

INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 

DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT 

OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 

PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 

ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 

LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 

ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN 

IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 

This product includes cryptographic software written by Eric Young 

(eay@cryptsoft.com). This product includes software written by Tim Hudson 

(tjh@cryptsoft.com). 

Original SSLeay License Copyright (C) 1995-1998 Eric Young 

(eay@cryptsoft.com). All rights reserved. 

This package is an SSL implementation written by Eric Young 

(eay@cryptsoft.com). The implementation was written so as to conform with 

Netscapes SSL. This library is free for commercial and non-commercial use as long 

as the following conditions are adhered to. The following conditions apply to all 

code found in this distribution, be it the RC4, RSA, lhash, DES, etc., code; not 

just the SSL code. The SSL documentation included with this distribution is 

covered by the same copyright terms except that the holder is Tim Hudson 

(tjh@cryptsoft.com). Copyright remains Eric Young's, and as such any Copyright 

notices in the code are not to be removed. If this package is used in a product, Eric 

Young should be given attribution as the author of the parts of the library used. 

This can be in the form of a textual message at program startup or in 

documentation (online or textual) provided with the package. Redistribution and 

use in source and binary forms, with or without modification, are permitted 

provided that the following conditions are met: 

1. Redistributions of source code must retain the copyright notice, this list of 





3. All advertising materials mentioning features or use of this software must display 

the following acknowledgement: “This product includes cryptographic software 

written by Eric Young (eay@cryptsoft.com)”. 

4. If you include any Windows specific code (or a derivative thereof) from the apps 

directory (application code) you must include an acknowledgement: “This 

product includes software written by Tim Hudson (tjh@cryptsoft.com)” 

THIS SOFTWARE IS PROVIDED BY ERIC YOUNG `ÀS IS'' AND ANY 

EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 

LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 

AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN 

NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 

FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 

OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 

TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 

OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 

WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 

(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 

OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 

POSSIBILITY OF SUCH DAMAGE. 

The licence and distribution terms for any publicly available version or derivative 

of this code cannot be changed, i.e. this code cannot simply be copied and put 

under another distribution licence [including the GNU Public Licence.] 

Micromuse acknowledges the use of software developed by ObjectPlanet. ©2003 

ObjectPlanet, Inc., Ovre Slottsgate, 0157 Oslo, Norway. 

Micromuse acknowledges the use of Expat in Netcool/ASM. Copyright 1998, 

1999, 2000 Thai Open Source Software Center Ltd. and Clark Cooper. Copyright 

2001, 2002 Expat maintainers. THE EXPAT SOFTWARE IS PROVIDED 

HEREUNDER “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS 

OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 

OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 

NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR 

COPYRIGHT HOLDERS OF THE EXPAT SOFTWARE BE LIABLE FOR 

ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN 

ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 

OUT OF OR IN CONNECTION WITH THE EXPAT SOFTWARE OR 

THE USE OR OTHER DEALINGS IN THE SOFTWARE. Expat explicitly 

grants its permission to any person obtaining a copy of any Expat software and 

associated documentation files (the “Expat Software”) to deal in the Expat 

Software without restriction, including without limitation the rights to use, copy, 

modify, merge, publish, distribute, sublicense, and/or sell copies of the Expat 

Software. Expat's permission is subject to the following conditions: The above 

copyright notice and this permission notice shall be included in all copies or 

substantial portions of the Expat Software. Except as set forth hereunder, all 

software provided by Micromuse hereunder is subject to the applicable license 

agreement. 

Micromuse acknowledges that Netcool Security Manager includes Hypersonic 

SQL. Copyright (c) 2001-2002, The HSQL Development Group. All rights 

reserved. 

JABBER® is a registered trademark and its use is granted under a sublicense from 

the Jabber Software Foundation. 

Micromuse acknowledges the use of MySQL in Netcool/Precision for IP 

Networks and in Netcool/Precision for Transmission Networks. Copyright © 

1995, 1996 TcX AB & Monty Program KB & Detron. 

Micromuse acknowledges the use of Cryptix in Netcool/Precision IP. Copyright 

(c) 1995-2004 The Cryptix Foundation Limited. All rights reserved. 



1. Redistributions of source code must retain the copyright notice, this list of 





THIS SOFTWARE IS PROVIDED BY THE CRYPTIX FOUNDATION 

LIMITED AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR 

IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 

IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A 


CRYPTIX FOUNDATION LIMITED OR CONTRIBUTORS BE LIABLE 

FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 

OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 

TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 

OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 

HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 

WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 




Micromuse acknowledges the use of PCRE in Netcool/Precision. Copyright 

©1997-2005 University of Cambridge. All rights reserved. Redistribution and use 

in source and binary forms, with or without modification, are permitted provided 

that the following conditions are met: 






3. Neither the name of the University of Cambridge nor the name of Google Inc. 

nor the names of their contributors may be used to endorse or promote products 

derived from this software without specific prior written permission. 






COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY 








USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 


Micromuse acknowledges the use of Net-SNMP in Netcool/ISM and 

Netcool/OMNIbus probes & monitors. 

Part 1: CMU/UCD copyright notice: (BSD like) Copyright 1989, 1991, 1992 by 

Carnegie Mellon University Derivative Work - 1996, 1998-2000. Copyright 

1996, 1998-2000 The Regents of the University of California. All Rights 

Reserved. Permission to use, copy, modify and distribute this software and its 

documentation for any purpose and without fee is hereby granted, provided that 

the above copyright notice appears in all copies and that both that copyright notice 

and this permission notice appear in supporting documentation, and that the 

name of CMU and The Regents of the University of California not be used in 

advertising or publicity pertaining to distribution of the software without specific 

written permission. 

CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA 

DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, 

INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY 

AND FITNESS. IN NO EVENT SHALL CMU OR THE REGENTS OF THE 

UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL, 

INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 

WHATSOEVER RESULTING FROM THE LOSS OF USE, DATA OR 

PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE 

OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN 

CONNECTION WITH THE USE OR PERFORMANCE OF THIS 

SOFTWARE. 

Part 2: Networks Associates Technology, Inc. copyright notice (BSD) Copyright 

(c) 2001-2003, Networks Associates Technology, Inc. All rights reserved. 



- Redistributions of source code must retain the above copyright notice, this list of 


- Redistributions in binary form must reproduce the above copyright notice, this 



- Neither the name of the Networks Associates Technology, Inc. nor the names of 

its contributors may be used to endorse or promote products derived from this 

software without specific prior written permission.















SUCH DAMAGE. 

Part 3: Cambridge Broadband Ltd. copyright notice (BSD) Portions of this code 

are copyright (c) 2001-2003, Cambridge Broadband Ltd. All rights reserved. 








- The name of Cambridge Broadband Ltd. may not be used to endorse or promote 

products derived from this software without specific prior written permission. 

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER “AS IS” 

AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT 


MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 

ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER 

BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 

EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 

NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 

SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 

INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 

LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 




Part 4: Sun Microsystems, Inc. copyright notice (BSD) Copyright © 2003 Sun 

Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, USA. 

All rights reserved. Use is subject to license terms below. This distribution may 

include materials developed by third parties. Sun, Sun Microsystems, the Sun logo 

and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in 

the U.S. and other countries. Redistribution and use in source and binary forms, 

with or without modification, are permitted provided that the following 

conditions are met: 






- Neither the name of the Sun Microsystems, Inc. nor the names of its contributors 

may be used to endorse or promote products derived from this software without 

specific prior written permission. 














USE OF THIS SOFTWARE, EVEN IF DVISED OF THE POSSIBILITY OF 

SUCH DAMAGE. 

Part 5: Sparta, Inc. copyright notice (BSD) Copyright (c) 2003-2004, Sparta, Inc. 

All rights reserved. Redistribution and use in source and binary forms, with or 

without modification, are permitted provided that the following conditions are 

met: 






- Neither the name of Sparta, Inc. nor the names of its contributors may be used 

to endorse or promote products derived from this software without specific prior 

written permission. 















SUCH DAMAGE. 

Part 6: Cisco/BUPTNIC copyright notice (BSD) Copyright (c) 2004, Cisco, Inc. 

and Information Network, Center of Beijing University of Posts and 

Telecommunications. All rights reserved. Redistribution and use in source and 

binary forms, with or without modification, are permitted provided that the 

following conditions are met: 






- Neither the name of Cisco, Inc., Beijing University of Posts and 

Telecommunications, nor the names of their contributors may be used to endorse 

or promote products derived from this software without specific prior written 

permission. 














USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

SUCH DAMAGE. 

Micromuse acknowledges the use of STLport in Netcool Probes & Monitors. 

Copyright 1999, 2000 Boris Fomitchev This material is provided “as is”, with 

absolutely no warranty expressed or implied. Any use is at your own risk. 

Permission to use or copy this software for any purpose is hereby granted without 

fee, provided the above notices are retained on all copies. Permission to modify the 

code and to distribute modified code is granted, provided the above notices are 

retained, and a notice that the code was modified is included with the above 

copyright notice. 

The Licensee may distribute binaries compiled with STLport (whether original or 

modified) without any royalties or restrictions. 

The Licensee may distribute original or modified STLport sources, provided that: 

The conditions indicated in the above permission notice are met; 

The following copyright notices are retained when present, and conditions 

provided in accompanying permission notices are met: 

Copyright 1994 Hewlett-Packard Company, 

Copyright 1996, 97 Silicon Graphics Computer Systems, Inc. 

Copyright 1997 Moscow Center for SPARC Technology. 

Permission to use, copy, modify, distribute and sell this software and its 

documentation for any purpose is hereby granted without fee, provided that the 

above copyright notice appear in all copies and that both that copyright notice and 

this permission notice appear in supporting documentation. Hewlett-Packard 

Company makes no representations about the suitability of this software for any 

purpose. It is provided “as is” without express or implied warranty. 




this permission notice appear in supporting documentation. Silicon Graphics 

makes no representations about the suitability of this software for any purpose. It 

is provided “as is” without express or implied warranty. 




this permission notice appear in supporting documentation. Moscow Center for 

SPARC Technology makes no representations about the suitability of this software 

for any purpose. It is provided “as is” without express or implied warranty. 

All other trademarks, registered trademarks and logos are the property of their 

respective owners. 

Micromuse Inc., 650 Townsend Street, San Francisco, USA CA 94103 

www.micromuse.com 

Document Version Number: 1.0

Contents 

Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 

Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 

About this Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 

Associated Publications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Netcool®/OMNIbus Installation and Deployment Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Netcool®/OMNIbus User Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Netcool®/OMNIbus Administration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Netcool®/OMNIbus Probe and Gateway Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Netcool®/Precision IP Installation and Deployment Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 

Netcool®/Precision IP Discovery Configuration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Netcool®/Precision IP Monitoring and RCA Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Netcool®/Precision IP Desktop Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Netcool®/Precision IP Topology Visualization Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Netcool GUI Foundation Administration Guide. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Netcool Licensing Administration Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 

Typographical Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 

Note, Tip, and Warning Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 

Syntax and Example Subheadings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 

Contents 

Operating System Considerations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 

Chapter 1: Introduction to Discovery with Netcool/Precision IP . . . . . . . . . . 11 

The Precision Server Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 

Communication Between Processes on Different Hosts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Communication Between DISCO and the Helper Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

The ServiceData Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 

Changing the Multicast Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 

Netcool/Precision IP 3.6 Discovery Configuration Guide i

Contents 

ii 

Configuring Netcool/Precision IP Server Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

Domain-Specific Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 

An Overview of Using Netcool/Precision IP on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Controlling Netcool/Precision IP on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 

Additional Functionality for Windows. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 

Functionality Not Available for Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 

Introduction to DISCO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 

An Overview of the Discovery Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 

Discovering Device Existence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 

Discovering Device Details (Standard). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 

Discovering Device Details (Context-Sensitive) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 

Discovering Associated Device Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 

Discovering Device Connectivity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 

Creating the Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 

Configurable Discovery Data Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 

Context-Sensitive Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 

Restricting the Discovery and Defining Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 

Discovery Stages and Phases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Data Collection Stage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 

Data Processing Stage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

Advantages of Staged Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 

Criteria for Multiphasing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 

Managing the Phases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

The Effect of Discovery Multiphasing on Network Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 

After the First Discovery: Rediscovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 

Conducting a Full or Partial Rediscovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 

Rediscovery Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 

Forcing Rediscoveries of Particular Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 

Netcool/Precision IP 3.6 Discovery Configuration Guide

Contents 

Chapter 2: Process Control with CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 

Introducing CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 

The CTRL Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 

Configuring CTRL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

Setting up a Single Netcool/Precision IP Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 

Setting up Multiple Netcool/Precision IP Domains . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 

Configuring Netcool/Precision IP Domains on Windows . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 

Component Dependencies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

Configuring Managed Processes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 

Configuring Unmanaged Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 

Starting CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

Prerequisites for Running CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 

Querying the Databases of CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 

Logging onto the Databases of CTRL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60 

The services Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64 

Chapter 3: Creating and Managing Users. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 

Introduction to User Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

The User Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

User Authentication with AUTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 

Profile Creation and Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 

User Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 

Configuring User Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 

The Default Profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 

The Default User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 

Starting AUTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 

Prerequisites for Running AUTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 

Starting the User Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 

Using the User Configuration Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 

Creating and Editing Users . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 

Creating and Editing Profiles. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 

Netcool/Precision IP 3.6 Discovery Configuration Guide iii

Contents 

iv 

The AUTH Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

The auth Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 

Chapter 4: Network Discovery Using the Network Discovery GUI. . . . . . . . . 85 

Introducing Methods for Configuring Network Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 

The Network Discovery GUI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 

Configuring a Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96 

Scoping the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 

Seeding the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 

Configuring the Dynamic Finders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 

Setting SNMP and Telnet Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 

Enabling and Disabling Discovery Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118 

Setting Discovery Filters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120 

Configuring DNS Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127 

Configuring NAT Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130 

Setting Advanced Discovery Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133 

Starting and Monitoring a Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138 

Running Discoveries and Rediscoveries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139 

Using the Discovery Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143 

Launching the Discovery Wizard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144 

Scoping and Seeding the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145 

Setting SNMP Passwords. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150 

Setting Telnet Access Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151 

Specifying the Type of Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152 

Optimizing the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155 

Completing the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160 

Reading and Writing Configuration Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162 

Chapter 5: Querying Netcool/Precision IP Databases . . . . . . . . . . . . . . . . . . . . . . . . . 165 

Accessing the Precision Server Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166 


Contents 

The OQL Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 

Accessing the OQL Workbench. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 

Using the OQL Workbench . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 

The OQL Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 

Starting the OQL Service Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169 

Using the OQL Service Provider . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170 

Chapter 6: Network Discovery from the Command Line . . . . . . . . . . . . . . . . . . . . . 175 

Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176 

Preparing for Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177 

Starting DISCO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 178 

Prerequisites for Running DISCO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179 

Configuring the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 

Configuration Task List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 

Scoping the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 

Configuring DISCO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 

Configuring the Ping Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 

Activating the Discovery Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184 

Deactivating the Discovery Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 

The Helper Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 

Managing the Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 

Configuring the Device SNMP Access Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187 

Editing Stitcher and Agent Definition Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189 

Running the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190 

Netcool/Precision IP 3.6 Discovery Configuration Guide v

Contents 

vi 

Tracking the Progress of the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 

Simple Queries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 

Complex Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191 

Other Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 

Identifying the Status of the Ping Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 

Interrogating the Databases of DISCO: Simple Database Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192 

Complex Database Queries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199 

Identifying the Number of Discovered Devices of a Given Device Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 

Determining Whether the Discovery Has Completed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205 

Chapter 7: Scoping a Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 

Introduction to Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 

Reasons for Scoping the Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 

Types of Scoping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208 

Defining Discovery Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 

Defining a Single Inclusion Zone. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 

Defining Multiple Inclusion Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210 

Defining Exclusion Zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 211 

Restricting Detection of Specific Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 

Restricting Interrogation of Specific Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 

Restricting Instantiation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 

Devices with Out Of Scope Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218 

Chapter 8: Using Finders to Seed a Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 

Introduction to the Finders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 

Multiple Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 

Configuring the Ping Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 

General Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 221 

Seeding the Ping Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 

Scoping the Ping Finder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 

The Status Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227 


Contents 

Configuring the File Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 

The configuration Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 

The parseRules Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228 

Example Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

Files to Parse and Rules for Parsing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229 

General Operation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231 

Verifying the Existence of a Device Reported by the File Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232 

Configuring the Sniffer Finder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 

The Configuration Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 


Configuring the Trap Finder. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 

The configuration Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 236 


Chapter 9: Discovery Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239 

Introducing the Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 

The Details Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 

The Associated Address (AssocAddress) Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 240 

Discovery Agent Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241 

Types of Agent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242 

Discovering Connectivity between Ethernet Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 

Connectivity at the Layer 3 Network Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 

Discovering Connectivity between ATM Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 

Discovering MPLS Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 

Discovering NAT Gateways. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 

Discovering Containment Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 

Discovery Agents on Other Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 

Context Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Task-specific Discovery Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261 

Enabling and Disabling the Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 

Enabling and Disabling the Discovery Agents Prior to a Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265 

Netcool/Precision IP 3.6 Discovery Configuration Guide vii

Contents 

viii 

Selecting Agents To Run. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 

Which IP layer Agents to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 

Which Standard Agents To Use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 

Which Specialized Agents To Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 

Suggested List of Agents for a Layer 3 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 

Suggested List of Agents for a Layer 2 Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269 

Discovering Device Protocols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Configuring Extreme Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 271 

Filtering Devices Sent to the Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 

Introduction to the Discovery Agent Filter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272 

Internal Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274 

Partial Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 276 

Retrieving Extra Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 

Changing the Agent Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 

The Mediation and Processing Layers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 

The Mediation Layer Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 

The Mediation Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 

The Processing Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 

Special Case: Adding Information to the master.entityByNeighbor Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 283 

Discovering SPVCs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 

SPVC Script Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 

Chapter 10: The Discovery Helper System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 

Introduction to the Helper System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 

The Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 286 

Helper System Operation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 

Dynamic Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287 

Starting the Helper Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 

Starting the Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 


Contents 

Configuring the Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 

Configuring the ARP Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 289 

Configuring the DNS Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290 

Configuring the PING Helper. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291 

Configuring the SNMP Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 

Configuring the Telnet Helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293 

SNMP and Telnet Device Access Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

Configuring SNMP Device Access. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298 

Configuring Telnet Device Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 

The Helper Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 

The ARP Helper database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307 

The DNS Helper Database Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309 

The Ping Helper Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 

The SNMP Helper Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314 

The Telnet Helper Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316 

Connecting to Helpers on Different Subnets. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319 

Communication Between DISCO and the Helper Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 

The ServiceData Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321 

Changing the Multicast Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323 

Chapter 11: Configuring an MPLS Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 325 

About MPLS Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 

Layer 3 MPLS VPNs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 

Enhanced Layer 2 MPLS VPNs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 

Configuring MPLS Agents and SNMP and Telnet Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 

Enabling MPLS Agents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329 

Configuring MPLS Discovery Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 

Configuring Telnet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331 

Configuring SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332 

Netcool/Precision IP 3.6 Discovery Configuration Guide ix

Contents 

x 

Advanced MPLS Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 

Defining the Scope of an MPLS/VPN Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333 

Specifying a VPN Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 

Fine Tuning Label Data Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336 

Visualizing MPLS Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337 

Chapter 12: Managing NAT Environments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 

Network Address Translation (NAT) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 

Overview of NAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342 

The Precision Server and NAT Environments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 

Differences in a NAT Discovery Process Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 

Configuring a NAT Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Enabling NAT Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Defining Address Spaces for Each Domain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346 

Configuring Trap Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347 

Running the Appropriate Agent. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 

Adapting the Containment Model for Use with NAT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 352 

Viewing NAT Environments Using Topoviz Network Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 353 

Chapter 13: Accessing Topology Data in MODEL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 

About MODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356 

Starting MODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 

Prerequisites for Running MODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358 

About the Containment Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 

Applying the Containment Principle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359 

Generating the Containment Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 

Altering the Containment Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362 


Contents 

Accessing the Discovered Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

Prerequisites for Accessing the Network Topology Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

Querying the MODEL Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

The Master Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363 

The Containment Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365 

Reinstantiating the Containment Model. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 

Identifying the Current Classes Used in MODEL (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368 

Editing the AOC Definitions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 

Restarting the Discovery Data Flow at the Appropriate Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 

Confirming the Instantiation (Optional) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371 

Databases of MODEL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 

The master Database Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 372 

The model Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375 

Chapter 14: The Persistent Topology Store . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377 

STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378 

Starting STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379 

Prerequisites for Running STORE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 

Restoring Databases Using STORE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380 

STORE Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 

The system Database Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381 

The kernel Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384 

The fault Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388 

Example Configurations: Configuring STORE to Listen for Topology Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 

Example Configurations: Configuring STORE to Listen for Event Traffic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 

Netcool/Precision IP 3.6 Discovery Configuration Guide xi

Contents 

xii 

Chapter 15: The Active Object Class Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 

Introduction to the AOC Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 

The Precision Server Aproach to Network Modelling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400 

Active Object Classes and the Precision Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 

Multiple Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

Active Classes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 402 

Starting CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 

Prerequisites for Running CLASS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404 

The CLASS Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 

The class Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405 

Manually Editing AOCs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 

The Architecture of an AOC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 

AOC Components - An Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 

A Complete AOC File Explained. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 

Chapter 16: The SNMP Trap Multiplexer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415 

SNMP Trap Multiplexing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416 

Starting TrapMux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 

Configuring TrapMux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 

Example TrapMux Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 

Controlling TrapMux Using the OQL Service Provider. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 418 

The trapMux Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 

Replaying Traps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 

Replay the File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422 


Contents 

Appendix A: The Discovery Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 

Types of Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 

DISCO Configuration Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 

Discovery Scope Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 

Process Management Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424 

DISCO Subprocess Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 

Databases for Tracking the Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 

Topology Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 

Rediscovery Database. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 

Additional Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425 

Failover Recovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 

Ignored Cached Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 

The failover Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426 

Example failover Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430 

Configuration Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 

The config Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431 

The managedProcesses Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 434 

The status Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435 

The agents Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 

The NATStatus Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 

Example Configuration of the disco.config Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 439 

Example Configuration of the disco.managedProcesses Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 

Example Configuration of the disco.agents Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 

Discovery Scope Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 

The scope Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 

Example scope Database Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445 

More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447 

Process Management Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 

Configuring the Data Flow: Starting Stitchers On-Demand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 

The agents Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 448 

The stitchers Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450 

Netcool/Precision IP 3.6 Discovery Configuration Guide xiii

Contents 

xiv 

Subprocess Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 

The finders Database Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 454 

The Details Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457 

Tracking Discovery Databases. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 

The translations Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 460 

The instrumentation Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463 

The workingEntities database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467 

Topology Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 

The fullTopology Database Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470 

The scratchTopology Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471 

The impactTopology Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 472 

Rediscovery Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 

The dataLibrary Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 

The rediscoveredEntities Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 475 

Additional Databases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 

The agentTemplate Database Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 476 

Appendix B: The Object Query Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 479 

Introduction to OQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 

Key Differences Between OQL and SQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 

General Rules of OQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 

Quotes in OQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480 

Punctuation Used in OQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 

Comments in OQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 481 

Logical operators of OQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 

Precedence and Association of Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 482 

Conventions Used in This Chapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 

Sample Databases Used in This Appendix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483 


Contents 

Creating a Database or Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485 

Datatypes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 485 

Column Constraints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 

Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 

Unique . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 

Counter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 487 

Timestamp. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 

Example of Database and Table Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488 

Inserting Data into a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 

Example of Inserting Data into a Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 490 

Selecting Data from a Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 

Conditional Tests in OQL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 

Example Uses of the like Operator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 495 

Example Use of the and Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 496 

Example Use of the or Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 

Selecting Based on Part of an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 497 

Using Select to Perform Subqueries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498 

Using Subqueries to Search a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 

Selecting Based on Part of a List. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 499 

Selecting Data into Another Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 

Using any, *, and all to Perform Table Joins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 

Updating a Record in a Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 

Updating a List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 

Updating an Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503 

Listing the Databases or Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 

Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 505 

Deleting a Record from a Database Table. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 

Basic Example of Deletion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 

Deleting on Part of Object or List . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507 

Deleting a Database or Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 

Example of Deleting a Database and Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508 

Netcool/Precision IP 3.6 Discovery Configuration Guide xv

Contents 

xvi 

The Eval Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509 

The eval Statement Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510 

Extraction of Record Values and Fields in OQL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512 

Advanced Use of the eval Statement. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513 

Appendix C: Stitchers and Stitcher Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 517 

Introduction to Discovery Stitchers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 

Discovery Stitchers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 

Monitoring Stitchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 

Stitcher Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518 

Structure of the Stitchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519 

List of Default Discovery Stitchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 521 

Stitcher Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 

Stitcher Language Structural Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 

Stitcher Trigger Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535 

Stitcher Rules. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536 

Stitcher Language Programming Constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 

Stitcher Language Datatypes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 

Stitcher Language Relational Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 

Comments in Stitchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 

Precedence and Association of Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 

Quotes in the Stitcher Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 

Stitcher Text File Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 

Compiled Stitchers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 

Text-Based Discovery Stitchers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 

Stitcher Trigger Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 


Contents 

Stitcher Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 

Variables Within the Stitcher Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 

Programming Constructs: Looping within the Stitcher Rules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545 

Stitcher Rules: Delete() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 

Stitcher Rules: ExecuteOQL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 

Stitcher Rules: RetrieveOQL(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 

Stitcher Rules: RetrieveSingleOQL() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 

Stitcher Rules: RetrieveOQLFromService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 549 

Stitcher Rules: GetInScopeRecord(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 

Stitcher Rules: GetRecordFromScope() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 

Stitcher Rules: SendOQLtoService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 550 

Stitcher Rules: SendAllOQLToService() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 

Stitcher Rules: ExecuteStitcher() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 

Stitcher Rules: ExecEvalOnRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 

Stitcher Rules: IsInSubnet() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 

Stitcher Rules: MergeEntities() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 

Stitcher Rules: PrintRecord() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 553 

Stitcher Rules: Print() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 

Stitcher Rules: MatchPattern(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 554 

Discovery-specific Stitcher Rules: DiscoSendOQLToFinder() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 

Discovery-specific Stitcher Rules: DiscoRefresh(). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557 

Discovery-specific Stitcher Rules: IsRecordInFilter() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 

Discovery-specific Stitcher Rules: DiscoDiscoveryCycleComplete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558 

Contact Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 569 

Netcool/Precision IP 3.6 Discovery Configuration Guide xvii

Contents 

xviii 


preface.fm July 5, 2005 

Preface 

This guide describes how to administer and use the Precision Server. The following chapters and appendices 

describe each functional area, and task-oriented examples are provided to assist users and administrators in 

configuring and using the application. 

This preface contains the following sections: 

• Audience on page 2 

About this Guide on page 3 

Associated Publications on page 5 

Typographical Notation on page 7 

Operating System Considerations on page 10 

Netcool/Precision IP 3.6 Discovery Configuration Guide 1

Preface 

Audience 

2 

This guide is intended for both users and administrators, and provides detailed cross-platform information 

about tools, functions, and capabilities. In addition, it is designed to be used as a reference guide to assist 

you in designing and configuring your environment. 

Netcool/Precision IP works in conjunction with Netcool ® /OMNIbus and it is assumed that you 

understand how Netcool/OMNIbus works. For more information on Netcool/OMNIbus, refer to the 

publications described in Associated Publications on page 5. 


About this Guide 

This book is organized as follows: 

Netcool/Precision IP 3.6 Discovery Configuration Guide 

About this Guide 

Chapter 1: Introduction to Discovery with Netcool/Precision IP on page 11 introduces the Precision 

Server architecture and the concept of domains. This chapter also describes DISCO, the 

auto-discovery engine, and the discovery process, including restricting discovery and rediscovery. 

Chapter 2: Process Control with CTRL on page 47 describes how to start the Precision Server Domain 

Process Controller, ncp_ctrl, and configure it to start and manage your Precision Server 

processes. 

Chapter 3: Creating and Managing Users on page 69 describes the default users and profiles included 

with the Precision Server. This chapter also describes how to use the User Configuration Tool to 

create and edit users and user profiles. in addition, this chapter describes the Precision Server 

authentication engine, ncp_auth, along with its databases. 

Chapter 4: Network Discovery Using the Network Discovery GUI on page 85 describes the Discovery 

Configuration GUI, which is the recommended way to configure your discovery. This chapter 

describes how to start the GUI, and how to use it to configure all aspects of your network discovery. 

Chapter 5: Querying Netcool/Precision IP Databases on page 165 describes ncp_oql, the Object 

Query Language (OQL) Service Provider. This chapter describes how to use the OQL Service 

Provider to query the databases of Netcool/Precision IP. 

Chapter 6: Network Discovery from the Command Line on page 175 describes how to start, run, and 

track a discovery from the command line. 

Chapter 7: Scoping a Discovery on page 207 describes how to limit the scope of a discovery using 

OQL. 

Chapter 8: Using Finders to Seed a Discovery on page 219 describes the finders, processes that discover 

device existence. This chapter describes how to configure the behavior of the finders using OQL 

inserts. 

Chapter 9: Discovery Agents on page 239 describes the Discovery Agents supplied with the Precision 

Server. This chapter describes the different types of Agent, how to enable and disable the Agents, and 

how to configure the Discovery Agents. 

Chapter 10: The Discovery Helper System on page 285 describes the Helper Server, a subsystem of 

DISCO, and its helpers. This chapter describes how to start the Helper Server and how to configure 

the helpers. 

Chapter 11: Configuring an MPLS Discovery on page 325 describes how to discover MPLS networks. 

It explains which types of MPLS discovery you can perform using Netcool/Precision IP and leads you 

through the steps required to perform an MPLS discovery. 

3

Preface 

4 

Chapter 12: Managing NAT Environments on page 341 describes NAT (Network Address 

Translation) and how Netcool/Precision IP manages NAT environments. This chapter also describes 

how to configure a NAT discovery. 

Chapter 13: Accessing Topology Data in MODEL on page 355 describes the function of the MODEL 

component, including how to access the discovered network topology. This chapter also describes the 

containment model used by Netcool/Precision IP to model physical and logical containment of 

network devices. 

Chapter 14: The Persistent Topology Store on page 377 describes the persistent topology store, 

STORE, and its databases. 

Chapter 15: The Active Object Class Server on page 399 describes CLASS, the AOC Server. This 

chapter describes how to start CLASS, and how to manually edit the AOCs. 

Chapter 16: The SNMP Trap Multiplexer on page 415 describes how to forward traps to multiple 

destinations using trapMux, the SNMP trap multiplexer. 

Appendix A: The Discovery Databases on page 423 gives the schemas of all the databases used by 

DISCO. 

Appendix B: The Object Query Language on page 479 describes OQL, the Object Query Language 

used by the databases of Netcool/Precision IP. This chapter describes how to perform various types of 

queries and operations on component databases. 

Appendix C: Stitchers and Stitcher Language on page 517 gives a list of stitchers used in the discovery 

process. Stitchers are software processes used throughout Netcool/Precision IP to transfer and 

manipulate data. This chapter also describes the syntax and rules of the stitcher language. 


Associated Publications 


Associated Publications 

Netcool/Precision IP integrates with the Netcool/OMNIbus event management product. Netcool/Precision 

IP is also deployed within the Netcool GUI Foundation server application, which runs Netcool/Precision 

IP and other Netcool suite GUIs. 

To efficiently administer Netcool/Precision IP, you must possess an understanding of the 

Netcool/OMNIbus technology. This section provides a description of the documentation that accompanies 

Netcool/OMNIbus, Netcool/Precision IP and the Netcool GUI Foundation. 

Netcool®/OMNIbus Installation and Deployment Guide 

This book is intended for Netcool administrators who need to install and deploy Netcool/OMNIbus. It 

includes installation, upgrade, and licensing procedures. In addition, it contains information about 

configuring security and component communications. It also includes examples of Netcool/OMNIbus 

architectures and how to implement them. 

Netcool®/OMNIbus User Guide 

This book is intended for anyone who needs to use Netcool/OMNIbus desktop tools on UNIX or Windows 

platforms. It provides an overview of Netcool/OMNIbus components, as well as a description of the 

operator tasks related to event management using the desktop tools. 

Netcool®/OMNIbus Administration Guide 

This book is intended for system administrators who need to manage Netcool/OMNIbus. It describes how 

to perform administrative tasks using the Netcool/OMNIbus Administrator GUI, command line tools, and 

process control. It also contains descriptions and examples of ObjectServer SQL syntax and automations. 

Netcool®/OMNIbus Probe and Gateway Guide 

This book contains introductory and reference information about probes and gateways, including probe 

rules file syntax and gateway commands. For more information about specific probes and gateways, refer to 

the documentation available for each probe and gateway on the Micromuse Support Site. 

Netcool®/Precision IP Installation and Deployment Guide 

This book describes the automated installation process and minimum system requirements for 

Netcool/Precision IP. This book also describes post-installation configuration and troubleshooting. 

5

Preface 

Netcool®/Precision IP Discovery Configuration Guide 

6 

This book describes how to configure and run discoveries. It contains reference information about the 

Precision Server, which performs network discovery. The book describes the components that make up the 

Precision Server, including helpers, agents, stitchers, and databases, and includes a detailed command line 

option reference. In addition, this book provides comprehensive information about the stitcher and OQL 

languages used within Netcool/Precision IP. 

Netcool®/Precision IP Monitoring and RCA Guide 

This book describes how to customize monitoring and event correlation, and how to write and adapt 

monitoring stitchers. The book also describes the RCA Engine databases, and the additional components 

installed as part of the integration with Netcool/OMNIbus. 

Netcool®/Precision IP Desktop Guide 

This book describes the operation of the Precision Desktop. The Precision Desktop is not available on 

Windows. 

Netcool®/Precision IP Topology Visualization Guide 

This book describes how to visualize your topology using the Topoviz Hop View. The book also describes 

how to partition your view of the network using the Network Views, and how to view device information 

using the MIB Browser. 

Netcool GUI Foundation Administration Guide 

This book describes how to administer the Netcool GUI Foundation, the central server application that runs 

web-based GUIs from different Netcool products. This guide describes how to configure the Netcool GUI 

Foundation server, manage users, create and provision pages, and administer security permissions. 

Netcool Licensing Administration Guide 

Online Help 

This book is intended for Netcool administrators who need to install and administer Netcool Licensing. It 

provides an overview of the generic Netcool Licensing component, as well as instructions for installing, 

upgrading, and configuring one or more license servers to dispense licenses to Netcool Licensing clients. 

Netcool/Precision IP web-based GUIs contain context-sensitive online help with index and search 

capabilities. Online documentation, HTML versions of the associated guides, are also available. 


Typographical Notation 



Table 1 shows the typographical notation and conventions used to describe commands, SQL syntax, and 

graphical user interface (GUI) features. This notation is used throughout this book and other Netcool ® 

publications. 

Table 1: Typographical Notation and Conventions (1 of 2) 

Example Description 

Monospace The following are described in a monospace font: 

Commands and command line options 

Screen representations 

Source code 

Object names 

Program names 

SQL syntax elements 

Filenames, paths, and directory names 

Italicized monospace text indicates a variable that the user must populate. For example, -password 

password. 

Bold The following application characteristics are described in a bold font style: 

Buttons 

Note: Text in the pop-up tooltips is used to name buttons with icons. These button names are 

described in plain text. 

Frames 

Text fields 

Menu entries 

A bold arrow symbol indicates a menu entry selection. For example, File→Save. 

Italic The following are described in an italic font style: 

An application window name; for example, the Login window 

Information that the user must enter 

The introduction of a new term or definition 

Emphasized text 

References to external documents 

[1] Code or command examples are occasionally prefixed with a line number in square brackets. For 

example: 

[1] First command... 

[2] Second command... 

[3] Third command... 

7

Preface 

8 

Table 1: Typographical Notation and Conventions (2 of 2) 

Example Description 

{ a | b } In SQL syntax notation, curly brackets enclose two or more required alternative choices, separated by 

vertical bars. 

[ ] In SQL syntax notation, square brackets indicate an optional element or clause. Multiple elements or 

clauses are separated by vertical bars. 

| In SQL syntax notation, vertical bars separate two or more alternative syntax elements. 

... In SQL syntax notation, ellipses indicate that the preceding element can be repeated. The repetition is 

unlimited unless otherwise indicated. 

,... In SQL syntax notation, ellipses preceded by a comma indicate that the preceding element can be 

repeated, with each repeated element separated from the last by a comma. The repetition is unlimited 

unless otherwise indicated. 

a In SQL syntax notation, an underlined element indicates a default option. 

( ) In SQL syntax notation, parentheses appearing within the statement syntax are part of the syntax and 

should be typed as shown unless otherwise indicated. 

Many Netcool commands have one or more command line options that can be specified following a hyphen 

(-). 

Command line options can be string, integer, or BOOLEAN types: 

A string can contain alphanumeric characters. If the string has spaces in it, enclose it in quotation 

(") marks. 

An integer must contain a positive whole number or zero (0). 

A BOOLEAN must be set to TRUE or FALSE. 

SQL keywords are not case-sensitive, and may appear in uppercase, lowercase, or mixed case. Names of 

ObjectServer objects and identifiers are case-sensitive. 

Note, Tip, and Warning Information 

The following types of information boxes are used in the documentation: 

Note: Note is used for extra information about the feature or operation that is being described. Essentially, 

this is for extra data that is important but not vital to the user. 


! 



Tip: Tip is used for additional information that might be useful for the user. For example, when describing 

an installation process, there might be a shortcut that could be used instead of following the standard 

installation instructions. 

Warning: Warning is used for highlighting vital instructions, cautions, or critical information. Pay close 

attention to warnings, as they contain information that is vital to the successful use of our products. 

Syntax and Example Subheadings 

The following types of constrained subheading are used in the documentation: 

Syntax 

Syntax subheadings contain examples of ObjectServer SQL syntax commands and their usage. For example: 

CREATE DATABASE database_name; 

Example 

Example subheadings describe typical or generic scenarios, or samples of code. For example: 

[1] 

[2] 

[6] 

9

Preface 

Operating System Considerations 

10 

Unless otherwise specified, command files are located in the NCHOME/precision/bin directory, 

where NCHOME is the environment variable that contains the path to the Netcool Suite home directory. 

The precise formulation of this path depends on your platform: 

On UNIX platforms, replace NCHOME with $NCHOME. All command line formats and examples are 

for the standard UNIX shell. UNIX is case-sensitive. You must type commands in the case shown in 

the book. 

On Microsoft Windows platforms, replace NCHOME with %NCHOME% and the forward slash (/) with 

a backward slash (\). 


1. Server_Overview.fm July 11, 2005 

Chapter 1: Introduction to Discovery with 

Netcool/Precision IP 

This chapter introduces the components and processes of the Precision Server and also provides a detailed 

overview of the discovery process. 

This chapter contains the following sections: 

The Precision Server Architecture on page 12 

Communication Between Processes on Different Hosts on page 15 

Configuring Netcool/Precision IP Server Domains on page 18 

An Overview of Using Netcool/Precision IP on Windows on page 20 

Introduction to DISCO on page 23 

An Overview of the Discovery Process on page 25 

Restricting the Discovery and Defining Exceptions on page 34 

Discovery Stages and Phases on page 35 

After the First Discovery: Rediscovery on page 40 


Chapter 1: Introduction to Discovery with Netcool/Precision IP 

1.1 The Precision Server Architecture 

12 

The Precision Server maps and distributes the network topology, interprets and distributes class-based 

management policy issues, and provides the basis for retrieval of device-specific data from the network 

devices through an extensible polling mechanism. 

The Precision Server is extensible and scalable. It is possible to plug in one or more network management 

applications that can make use of the processes available in the Precision Server to gather application-specific 

data and perform application-specific tasks. An example of such an application is the Netcool/Precision IP 

RCA and monitoring system, which is described in the Netcool/Precision IP Monitoring and RCA Guide. 

Figure 1 shows the core components of the Precision Server. The components are described in detail in 

individual chapters of this guide. 

AUTH 

Helper Server 

H 

H 

Network 

Figure 1: Precision Server Overview 

F 

CTRL 

DISCO 

F 

CLASS 

MODEL 

STORE 

Netcool/Precision IP provides the user with the capability to automatically discover network devices and 

their connectivity. This auto-discovery capability generates a topology model that can be: 

Displayed using the Topoviz topology visualization tool. 

H = helper 

F = finder 

Used to automatically configure the Netcool/Precision IP network monitoring system to identify 

network events. 



The Precision Server Architecture 

Used to correlate disparate network events using the Netcool/Precision IP Root Cause Analysis 

(RCA) Engine. 

Provide a list of network assets to network-inventory systems. 

The automated network discovery process (DISCO) is highly configurable and extensible. It 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 DISCO system components are described in Table 1. 

Table 1: Components of the Discovery System 

Component Description 

Discovery finders Finders can use a number of different protocols to 

determine the existence of devices on the network. 

Discovery agents Agents are used to request information from devices that 

the finders have discovered. There are a variety of agents, 

each specialized to retrieve information from different 

devices, and/or use different protocols. 

Discovery Helper Server Requests for information made by agents go through the 

Helper Server. The Helper Server can service the requests 

directly with cached data or pass on the request to the 

appropriate helper. 

Discovery helpers Helpers translate queries into the appropriate network 

protocol and make requests to the devices. 

Discovery stitchers Stitchers process the information collected by the agents 

into a topology/connectivity model. 

Once generated, the topology model is held in the topology repository (MODEL). MODEL is queried by 

other subsystems using Netcool/Precision IP's Object Query Language (OQL). The persistent storage 

system (STORE) is used to store the network model on disk. Further details of MODEL and STORE can 

be found in Chapter 13: Accessing Topology Data in MODEL on page 355 and Chapter 14: The Persistent 

Topology Store on page 377. If necessary, you can also use OQL to query the component databases through 

an OQL command line interface, details of which can be found in Appendix B: The Object Query Language 

on page 479. 

When a device has been discovered and recognized by Netcool/Precision IP, it is assigned (instantiated) a 

management class. A device's class defines the network management policies that are applied to the device. 

The management class is defined by the Netcool/Precision IP Active Object Class (AOC) system – a 

hierarchically defined set of management policies that are controlled and distributed by the AOC server 

engine (CLASS). The AOC system is briefly described in Manually Editing AOCs on page 409 and covered 

in greater detail in the Netcool/Precision IP Monitoring and RCA Guide. For details of CLASS, see 

Chapter 15: The Active Object Class Server on page 399 of this guide. 

13


14 

The Precision Server provides a process management system (CTRL) that is responsible for starting and 

stopping individual components within Netcool/Precision IP. For details of configuring CTRL, see 

Chapter 2: Process Control with CTRL on page 47. 

The Precision Server stores information (including the topology model) in a database system, access to which 

is controlled using the Netcool/Precision IP authentication system (AUTH). Using the User Management 

interface, as an administrative user, you can define different levels of access within different profiles and 

assign appropriate profiles to individual users. For details of adding users to the system, see 

Chapter 3: Creating and Managing Users on page 69. 

Inter-process communication is achieved using the Netcool/Precision IP message bus (based upon 

TIB/Rendezvous). The publish-subscribe mechanism, based upon multicast technology, provides 

communication between the individual components and also allows them to be distributed onto multiple 

machines. For details on configuring TIB/Rendezvous, see the Netcool/Precision IP Installation and 

Deployment Guide. 

Note: When inter-process communication needs to take place with processes running on different hosts that 

are behind a firewall, you need to dedicate a port for each process running on a separate host. For 

information on how to do this for discovery helpers and agents running on separate hosts, see 

Communication Between Processes on Different Hosts on page 15. 



Communication Between Processes on Different Hosts 

1.2 Communication Between Processes on Different Hosts 

When inter-process communication needs to take place with processes running on different hosts that are 

behind a firewall, then you need to use a TCP socket-based connection to dedicate a port for each process 

running on a separate host. Examples of this kind of inter-process communication may occur in the 

following scenarios: 

Helpers and the Helper Server are running on a different host to DISCO 

Agents and the Helper Server are running on a different host to DISCO 

Interaction between primary and backup servers in a failover architecture 

This section considers the scenario in which the helpers and the Helper Server are running on a different 

host to DISCO and describes how to facilitate inter-process communication in this case. The same 

principles described in this example apply to all the scenarios. 

Communication Between DISCO and the Helper Server 

If the helpers and the Helper Server are running on a different host to DISCO, then DISCO and the Helper 

System communicate using a TCP socket-based connection. However, the initial communication of the 

server address is accomplished by a multicast process. A client (discovery agents and helpers are clients to the 

Helper Server) sends a multicast request for the address of the server to participating Precision Server 

processes. The server responds with its connection details, and a TCP connection is established. This 

connection then becomes the private link between the server and the client process. You can specify the exact 

multicast address and port number for communication between processes through the Service Data 

configuration file, ServiceData.cfg. 

The ServiceData Configuration File 

The ServiceData configuration file is a dynamic file that is constantly updated by Precision Server 

processes. Every Precision Server service (that is, component or process) using a TCP socket adds a line to 

the file on start up containing information about the service. The service removes the line from the 

configuration file when it terminates. The information appended to the configuration file is listed below: 

The service name 

The service domain 

The service IP address 

The service port number 

The server on which the process is being run 

15


16 

In the example configuration file shown below, the first service called MulticastService shows the 

multicast address and port number. The second service shows that the Helper service is running on the 

DEMO domain, and includes information about the IP address, port number and the name of the server 

where the Helper service is running. 

-- 

-- Server data file - contains info on servers and the general multicast 

-- address to use. 

-- 

SERVICE: MulticastService DOMAIN: ANY_PRECISION_DOMAIN ADDRESS: 225.13.13.13 PORT: 

33000 

SERVICE: Helper DOMAIN: DEMO ADDRESS: 192.168.31.8 PORT: 51153 SERVERNAME: britanicus 

DYNAMIC: YES 

Defining Fixed Helper Ports 

When helpers are located on different hosts that are behind a firewall, you need to dedicate a port on the 

server machine for communication with the helpers. You also need to dedicate a port on each of the 

machines where one or more helpers are running for communication with the server. You do this by 

modifying the ServiceData.cfg file on the Netcool/Precision IP installation on the server machine 

and on each of the Netcool/Precision IP installations on each of the remote hosts where helpers are running. 

Note: Netcool/Precision IP needs to be installed on each of the remote hosts where helpers are running. 

To set fixed port settings for helpers on the server machine: 

1. On the server machine, start the Helper server. For information on how to do this, see Starting the 

Helper Server on page 288. 

2. Copy the ServiceData.cfg file so that you have a backup copy. 

3. Edit the ServiceData.cfg file and copy the line relevant to the helper (or helpers) for which 

you want to fix a static port. 

The line may look something like this: 

SERVICE: Helper DOMAIN: DEMO ADDRESS: 192.168.31.8 PORT: 51153 SERVERNAME: 

britanicus DYNAMIC: YES 

The port for the helper in this example has been assigned on a dynamic basis by Rendezvous. 

4. Change the PORT setting to the desired value. 

5. Change the string DYNAMIC:YES to DYNAMIC:NO. 

6. Save the ServiceData.cfg file. 


To set fixed port settings for the server on the helper host: 



Communication Between Processes on Different Hosts 

2. On the server, edit the ServiceData.cfg file and copy the line that you edited to set fixed port 

settings for helpers on the server machine. 

3. Edit the ServiceData.cfg file on the helper host and paste the line that you copied in Step 2. 

Using the example above, this line looks like this: 


britanicus DYNAMIC: NO 


5. Repeat steps 1 to 4 for each of the helpers that requires a fixed port setting. 

Changing the Multicast Address 

In order to modify the multicast address used by the Precision Server processes, you have to edit the address 

and the port of the first line of the ServiceData.cfg configuration file, as shown below. 

-- 

-- Server data file - contains info on servers and the general 

-- multicast address to use. 

-- 

SERVICE: MulticastService DOMAIN: DOMAIN_NAME ADDRESS: MULTICAST_ADDRESS PORT: 

PORT_NUMBER 

In the above statement: 

MulticastService refers to the Precision Server service that is being configured to use a 

particular multicast address. Valid entries include Model, Events, Class, Auth, Exec, Ctrl. 

DOMAIN_NAME indicates the domain name of the service that is to use the specified multicast 

address. It is possible to set the same service to use different multicast addresses for each domain that 

it is run in. Alternatively, you may replace the DOMAIN_NAME with ANY_PRECISION_DOMAIN, 

which means that the service is to use the same multicast address for all domains it is executed in. 

MULTICAST_ADDRESS indicates the multicast address to be used by the multicast service 

provider. 

PORT_NUMBER indicates the port number to be used by the multicast service provider. 

The multicast address in the configuration files must be the same for all devices that have clients that talk to 

each other. If this is not the case, processes on one device can talk but others are not able to listen because 

they are not tuned in to the right frequency. 

17


1.3 Configuring Netcool/Precision IP Server Domains 

18 

A Netcool/Precision IP domain is an arbitrary set of Precision Server executables that work together in a 

single group identified by a name that is referred to as the domain name. You can run multiple domains in 

order to perform multiple network discoveries, and multiple Precision Server processes can run 

independently of each other on the same device if they belong to different domains. 

The domain in which a component runs is determined by the command line argument -domain, which 

is compulsory for all components. 

Note: In order for RCA and topology visualization to function properly, each ObjectServer (or 

ObjectServer failover pair) must be associated with only one Netcool/Precision IP domain. 

Domain-Specific Configuration Files 

Netcool/Precision IP components are controlled by configuration files. For example, the component 

ncp_ctrl reads the CtrlServices.cfg file on startup and starts those components that have entries 

in the file. 

You can run components in multiple domains with different configurations by creating different 

configuration files for each domain. When started, components look for a domain-specific version of their 

configuration file(s), and use this in preference to the default version. 

Some components, such as the configuration GUIs, save your configuration changes by writing to 

component configuration files. Any configuration files changed during a session with a configuration GUI 

are specific to the domain in which the GUI was started. 

Note: You only need to create domain-specific versions of those files that are different for a given domain. 

Files without changes can be ’shared' by components running in different domains. 

To create a domain-specific version of a file: 

1. Back up the original version of the file. 

2. Save a copy of the file with the domain name appended to the filename. 

For example, to save the file CtrlServices.cfg for the domain MASTER, it must be named 

CtrlServices.MASTER.cfg. 

In the above example, the next time that ncp_ctrl is run in the domain MASTER, it starts those processes 

listed in the CtrlServices.MASTER.cfg file. The next time that ncp_ctrl is run in a different 

domain, NCOMS, for example, it starts those processes listed in the CtrlServices.cfg file. 



Configuring Netcool/Precision IP Server Domains 

Note: Many instructions to Netcool/Precision IP components are specified by inserting data into database 

tables. These insert commands are coded in configuration files. When specifying inserts for a given 

Netcool/Precision IP component, ensure that all inserts to the same database are coded in the same 

configuration file. If different configuration files try to execute inserts on the same database, unexpected 

results may occur. 

Note: You should also ensure that the configuration file in which you specify inserts is different to the 

configuration file that you use to create databases for a given Netcool/Precision IP component. This ensures 

that the process of upgrading to a new version of Netcool/Precision IP runs smoothly. 

Domain-Specific File Names 

Although in practice there are some files that you are unlikely to need to alter, in principle all of the following 

types of files can be made domain-specific: 

Configuration files, that is, all files ending in .cfg 

Discovery agent files, that is, all files ending in .agnt 

Active Object Class files, that is, all files ending in .aoc 

Stitcher files, that is, all files in a stitchers directory ending in .stch or .so 

In the Netcool/Precision IP documentation, these files are referred to using their default names unless noted 

otherwise. 

Note: In order to ensure that users are valid across all domains, ncp_auth does not use domain-specific 

versions of its configuration file even if they exist. 

19


1.4 An Overview of Using Netcool/Precision IP on Windows 

20 

This section provides a concise overview of using Netcool/Precision IP on a Windows platform and provides 

details of the additional functionality for Windows, as well as functionality not currently provided for 

Windows. 

This section is structured as follows: 

Controlling Netcool/Precision IP on Windows on page 20 

Additional Functionality for Windows on page 21 

Functionality Not Available for Windows on page 22 

Controlling Netcool/Precision IP on Windows 

Micromuse recommends that Netcool/Precision IP domain processes are run as Windows services. The 

main benefit of running Netcool/Precision IP processes as services is that an administrator can create 

domains and services that a standard user can control. 



An Overview of Using Netcool/Precision IP on Windows 

Additional items will appear on the Windows Start Menu upon successful installation of Netcool/Precision 

IP. Figure 2 shows the new Netcool/Precision IP items added to the Start Menu. The menu items enable 

you to open a ncp_ctrl console, or start or stop ncp_ctrl. These menu items only apply to the 

domain that was set up during installation. 

Figure 2: Netcool/Precision IP on the Windows Start Menu 

Additional Functionality for Windows 

This section provides details of the additional functionality available to Windows in this release of 

Netcool/Precision IP. 

Netcool/Precision IP enables you to set up and control Netcool/Precision IP processes as Windows services. 

See Configuring Netcool/Precision IP Server Domains on page 18 for further details. 

A new -errorlevel command line parameter has been added to all Netcool/Precision IP processes. The 

number following this parameter will indicate the types of errors to be printed. Permitted values are: 

1 - Print only fatal errors 

21


22 

2 - Print fatal errors and warnings 

3 - Print fatal errors, warnings and informational messages 

The default -errorlevel is 3, which is equivalent to previous functionality. You can set the value to 1 

for all processes. Please note that this will make fixing subtle problems more difficult. Debug is controlled 

independently using the -debug parameter. However, for coherence, if -errorlevel is set to a lower 

value than -debug, the error level will be increased to either 3 or the debug level, whichever is lower. 

You can copy Netcool/Precision IP configuration files between Windows and UNIX. The files might lose 

some formatting when viewed in a text editor due to the different formats for line breaks in text files on 

Windows and UNIX systems. However, Netcool/Precision IP is able to read them. When UNIX 

configuration files are used on Windows, Notepad will not show any line breaks. Wordpad will display 

UNIX text files correctly, so it is the best application to view configuration files copied from UNIX 

platforms. When a Windows configuration file is used on UNIX, vi will show ^M at the end of each line. 

This is a cosmetic issue and does not affect usability of the file by Netcool/Precision IP. 

Functionality Not Available for Windows 

This section provides details of the Netcool/Precision IP functionality that is not available on Windows 

installations. 

The User Configuration Tool is not available for Windows deployments; you can modify AUTH 

using OQL if you need to change or add user settings for a Windows deployment. 

The MONITOR Configuration Tool is not available for Windows deployments; you can edit AOCs 

using Notepad or another text editor of your choice, but the changes will not take effect until the 

Precision Server components are restarted. 

The Perl API is not included in this version of Netcool/Precision IP, therefore the 

NATTextFileAgent agent cannot be used. 


1.5 Introduction to DISCO 


Introduction to DISCO 

DISCO manages the process of discovering device existence and interconnectivity. DISCO resolves 

retrieved connectivity information to create the containment model and produce a network topology that is 

passed to the MODEL component. 

On startup, DISCO reads the following configuration files in order: 

NCHOME/etc/precision/DiscoSchema.cfg, which contains definitions of the databases 

used during the discovery process. 

NCHOME/etc/precision/DiscoAgents.cfg, which contains a list of the discovery agents 

and other subprocesses that DISCO is to run and manage. 

NCHOME/etc/precision/DiscoScope.cfg, which contains scoping information for the 

discovery. 

Note: NCHOME is the environment variable that contains the path to the Netcool Suite home directory. For 

information on how this environment variable varies with platform, see Operating System Considerations on 

page 10. 

The DISCO subprocesses involved in the discovery are shown in Table 2. The description includes 

cross-references to detailed explanations in this guide. 

Table 2: Processes and Applications That Interact with DISCO (1 of 2) 

Name Description 

Finders Finders discover the existence of devices but do not retrieve connectivity information (see 

Chapter 8: Using Finders to Seed a Discovery on page 219). 

Details agent The Details agent interrogates the network through the Helper Server for basic device information 

and determines whether SNMP access is available (see Chapter 9: Discovery Agents on page 239). 

Associated Address 

agent 

The Associated Address agent downloads all IP addresses associated with a device to verify that 

the device has not already been discovered through another interface. Devices that have already 

been discovered are not passed to the discovery agents (see The Associated Address (AssocAddress) 

Agent on page 240). 

Discovery agents The discovery agents retrieve connectivity information. They do not have any direct interaction 

with the network, but instead retrieve information through the Helper Server. Discovery agents 

can be libraries or text files, and are specialized for particular protocols, devices or classes (see 

Discovery Agents on page 239). 

Helper Server The Helper Server manages the helpers and stores information retrieved from the network. 

Discovery agents retrieve their information through the Helper Server to reduce the load on the 

network (see Introduction to the Helper System on page 286). 

23


24 

Table 2: Processes and Applications That Interact with DISCO (2 of 2) 

Name Description 

Helpers The helpers retrieve information from the network on behalf of the discovery agents (see The 

Discovery Helper System on page 285). 

Stitchers Stitchers are processes that are responsible for the transfer, manipulation and distribution of data 

between databases. The discovery stitchers are responsible for creating the network topology (see 

Introduction to Discovery Stitchers on page 518). 

In order for DISCO to launch and manage its subprocesses, CTRL must be running. DISCO instructs 

CTRL to launch the finders and discovery agents as necessary, although these subprocesses can also be 

started manually at the command line. 

When DISCO is operational, it periodically scans the agents and stitchers directories and loads any new or 

modified stitcher and discovery agent definitions. 


1.6 An Overview of the Discovery Process 


An Overview of the Discovery Process 

This section gives a step-by-step walkthrough of the discovery process, demonstrating how DISCO discovers 

devices on the network to produce a network topology containment model. 

The default data flow is shown in a series of diagrams that depict a single discovery cycle. A discovery cycle is 

said to have occurred when the data flow described in this section has completed from start to finish. A full 

discovery may require more than one cycle. 

Internally, the discovery is split into various stages and phases. These are explained in Discovery Stages and 

Phases on page 35. 

This section splits the discovery data flow into the following conceptual steps: 

Discovering Device Existence on page 26 

Discovering Device Details (Standard) on page 27 

Discovering Device Details (Context-Sensitive) on page 28 

Discovering Associated Device Addresses on page 29 

Discovering Device Connectivity on page 30 

Creating the Topology on page 31 

These steps follow the discovery data flow in order from start to finish, with the exception of Discovering 

Device Details (Context-Sensitive) on page 28, which replaces Discovering Device Details (Standard) on 

page 27 if the discovery is context-sensitive. 

25


Discovering Device Existence 

26 

Figure 3 shows how the initial existence of devices on the network is discovered. 

1 

3 

F 

Network 

despatch 

returns 

pending 

Database 

processing 

F F 

Finders database 

Figure 3: Discovery Process Flow: Device Existence 

The process flow shown in Figure 3 is described below. 

2 

4 

despatch 

returns F = finder 

Details Agent 

1. 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. Finders return device existence information to the finders.returns table. 

3. As soon as 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. See The Blackout State on page 35 for information on the 

blackout state and how data in the finders.pending table is managed. 

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. 


Discovering Device Details (Standard) 



Figure 4 shows how device details are discovered in a standard (not context-sensitive) discovery. 

1 

H 

despatch 

returns 

Network 

2 

Details Agent 

Figure 4: Discovery Process Flow: Device Details (Standard) 


H 

Helper Server 

3 

4 

despatch 

returns 

AssocAddress Agent 

H = helper 

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. 

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 4) 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 

Associated Address (AssocAddress) agent for processing. 

27


Discovering Device Details (Context-Sensitive) 

28 

Figure 5 shows how device details are discovered in a context-sensitive discovery. See Context-Sensitive 

Discovery on page 33 for more information on context sensitivity in discovery. 

1 

H 

despatch 

returns 

Details Agent 

Network 

2 

Figure 5: Discovery Process Flow: Device Details (Context-Sensitive) 


H 

Helper Server 

3 

4 

despatch 

returns 

Context Agents 

H = helper 

despatch 

returns 


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. 

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. When the Context agent has finished its processing, the information is passed to the despatch 

table of the Associated Address (AssocAddress) agent for processing. 

5 


Discovering Associated Device Addresses 

Figure 6 shows how associated device addresses are discovered. 

ipToBaseName 

translations 

database 



H 

Network 

Figure 6: Discovery Process Flow: Associated Device Addresses 

H 

Helper Server 

2 

1 

despatch 

returns 

3 


despatch 

returns 

Agent X 

despatch 

returns H = helper 

Agent Y 


1. The Associated Address agent downloads all the IP addresses associated with the interfaces of the 

device under investigation using the Helper Server. 

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, there is already a record for this device 

in the translations.ipToBaseName table), its details are not sent to the discovery agents. 

3. Provided the device has not already been discovered, stitchers pass the details to the appropriate 

discovery agents, as specified in the DiscoAgents.cfg configuration file. 

29


Discovering Device Connectivity 

30 

Figure 7 shows how device connectivity is discovered, as well as how devices are discovered recursively. 

despatch 

returns 

Agent X 

2 

1 

Figure 7: Discovery Process Flow: Device Connectivity 

H 

Network 


H 

Helper Server 

despatch 

returns 

pending 

processing 

Finders database 

1 

2 

despatch 

returns 

Agent Y 

H = helper 

1. Inserting information into the despatch table of an agent triggers an attempt by that agent to 

discover connectivity information about that device. The discovery agents set up a Transmission 

Control Protocol (TCP) socket-based communication link with the Helper Server and request the 

appropriate connectivity information. 

2. The addresses of the remote neighbors of the device, as well as the subnet address(es) of the device, are 

passed by a stitcher to the finders to be discovered. These addresses may or may not exist, and they 

may or may not be in the discovery scope, so they must go through the discovery process from the 

beginning. 


Creating the Topology 



Figure 8 shows a simplified data flow for the creation of the topology from the raw data returned by the 

discovery agents. 

despatch 

returns 

Agent V 

1 

FE 

EBNR 

Layer2 

database 

despatch 

returns 

Agent W 

Figure 8: Discovery Process Flow: Creating the Topology 

2 

FE 

EBNR 

fullTopology 

database 

despatch 

returns 

Agent X 

3 4 

EBN 

scratchTopology 

database 

Layer3 

database 

despatch 

returns 

Agent Y 

1. After all the discovery agents have finished, and the discovery enters the processing phase, special data 

processing stitchers interact with the discovery agent databases to produce temporary network 

topologies, for example, a layer 2 topology or a layer 3 topology. These topologies have separate tables 

for device information (EntityByName) and connectivity information (EntityByNeighbor). 

2. When all the discovery agents have finished their tasks (and all the appropriate temporary topologies 

have been created), another set of stitchers begin combining the temporary network topologies. A 

single topology is now generated. The workingEntities.FinalEntity table holds device 

information for the topology while the fullTopology.EntityByNeighbor table holds 

connectivity information. 

2 

FE 

EBNR 

MODEL 

1 

31


32 

3. When the fullTopology database is complete, a set of specialized topology stitchers work on the 

topology to deduce and create the containment model. The default containment model is based on 

physical containment and VLAN membership, and is stored in the 

workingEntities.FinalEntity table. Connectivity, containment and device information 

are now merged in the scratchTopology database. By default, this topology is sent straight to 

MODEL. 

4. MODEL instantiates each network element (subject to the instantiation filter) and sends the 

topology to other components as required. For more information on MODEL and the instantiation 

filter, see Chapter 13: Accessing Topology Data in MODEL on page 355. 

Configurable Discovery Data Flow 

The discovery process data flow is user-configurable. Stitchers control the movement of data between 

databases. You can therefore customize the discovery process to suit your own needs 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: 

Data being inserted into a specific database table 

A stitcher or discovery agent completing its operation 

The end of a discovery phase 

Any changes you make are automatically picked up 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 Appendix C: Stitchers and Stitcher 

Language on page 517. 

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. For details of the 

stitchers.actions database, see Table A25 stitchers.actions Database Table Schema on page 453. 


Context-Sensitive Discovery 

! 



If you have devices that you need to discover such as SMS devices, MPLS Edge devices, or other devices with 

virtual routers, you must run a context-sensitive discovery. Context-sensitive discovery ensures correct 

representation of virtual routers. 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 is true for all discovery agents. If the device is not of a type which supports virtual routers, that is, does 

not need context-sensitive processing, it is passed directly to the Associated Address agent. 

Warning: 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 Network Discovery GUI. 

To enable a context-sensitive discovery, appended the following insert to the DiscoSchema.cfg file: 

insert into disco.config 

( 

m_UseContext 

) 

values 

( 

1 

) 

Inserting the value 0 disables the context-sensitive discovery. 

33


1.7 Restricting the Discovery and Defining Exceptions 

34 

You can specify discovery exceptions. Discovered devices can be filtered by making entries to the tables of 

the scope database. The scope database is created in the DiscoSchema.cfg configuration file. 

Inserts into this database should be defined in the DiscoScope.cfg configuration file. 

The tables of the scope database are: 

scope.zones 

scope.detectionFilter 

scope.instantiateFilter 

The scope.zones table defines the scope of the discovery, either including or excluding areas of the 

network. Devices outside the scope are not passed to the Details agent, that is, these devices are not 

discovered and SNMP access is not attempted. 

The scope.detectionFilter table restricts the devices that are sent to the discovery agents. Only 

devices that match the filter are passed to the discovery agents for interface discovery. Devices that do not 

match the filter are passed to the Details agent, but no interfaces are discovered and the device is not passed 

to the discovery agents. This filter could be used to restrict SNMP access to a device. 

The scope.instantiateFilter table restricts the display of discovered devices. Only devices that 

match any filter that is specified are instantiated, although devices that do not match the filter are still 

discovered. 

For information on setting the scope of discovery, see Scoping a Discovery on page 207. 


1.8 Discovery Stages and Phases 


Discovery Stages and Phases 

This section describes how the discovery is divided into stages. The stages are subdivided into phases. 

The discovery process can be divided into two stages—data collection and data processing. 

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, as explained below. 

Data Collection Phase One 

In the first phase of the discovery, finders identify all the devices that exist on the network. Generally, a phase 

can only be completed when all the launched processes have completed their operation. However, although 

it may be desirable 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. Phase one therefore completes 

when the find rate drops below a certain level, determined by either: 

The rate at which devices are being discovered dropping below the threshold specified by 

disco.config.m_AvgeFindPeriod. 

No devices being discovered for the amount of time specified in 

disco.config.m_NothingFndPeriod. 

Agents in Data Collection Phase One 

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. The Feedback stitcher can send this 

information to the Ping finder for inclusion in the discovery, but because of the blackout state any agent 

involved in this process would have to be run in phase one in order for devices to be discovered in the current 

discovery cycle. 

Phase one therefore usually involves the Switch discovery agents downloading all VLAN and interface 

information. 

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

35


36 

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. 

Data Collection Phase Two 

When the criteria for the completion of phase one have been fulfilled, phase two begins. In order to map 

layers two and three of the OSI model, the ARP Cache discovery agent populates the Helper Server with 

ARP data, specifically, a complete list of device IP address to MAC address resolution. 

Completion Criteria 

For a transition to occur from phase two to phase three, the processes from phase two must have completed 

their operation. An agent is deemed to have finished once all entities in its despatch table are also in its 

returns table. 

The agents are multithread, however, and records of discovered devices passed to the agents are tagged with 

a certain phase. Consequently, at any given 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. 

Data Collection Phase Three 

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. 

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




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. 

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 two stages usually overlap, because the stitchers can be configured to begin processing connectivity 

information from different discovery agents before the main stitching operation begins. 

Advantages of Staged Discovery 

The following examples illustrate why it is advantageous to apply a staged and phased approach to discovery. 

Example 1: Switch Connectivity 

In determining the true 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 of a transient nature. 

A good example is when the layer 2 agents discover connectivity between Ethernet switches. Ethernet 

switches have forward database tables that expire over time. One technique that ensures that a switch has a 

fully populated forward database table at the time of interrogation, is to 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. Once they receive the signal that phase one has been completed (that is, all devices have 

been found) they can commence phase two operations. For example, they could ping all devices within the 

discovery domain whilst downloading the forward database tables for all switches. 

37


38 

Example 2: Mapping Subnet Boundaries 

One apparent 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. One way of resolving this problem is by using a special ARP Cache discovery 

agent that imitates a generic discovery agent (in the sense that entities can be sent to it) but that is also able 

to map boundaries or different layers of the OSI model. 

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 could be applied when using Switch discovery agents that need to perform IP address to MAC 

address resolution before they can commence operation. Following the example above, you could configure 

your discovery data collection stage to have three phases: 

Phase one: Find all devices that exist on the network. 

Phase two: Use the ARP Cache discovery agent to populate the Helper Server with full IP address to 

MAC address mappings. 

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. 

Example 3: 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 commence operation in phase two, it could also conduct some 

other operation in phase one. This is because the end of phase one only signifies that all devices have been 

nominally 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 when phase 

two has commenced does the agent begin to perform processing instructions specific to phase two. 

It is good practice to configure the discovery to occur over multiple phases, to ensure maximum accuracy of 

the deduced topology. 

Criteria for Multiphasing 

The main criterion for configuring a discovery that has multiple phases is an assessment of the requirements 

of the different operations that need to be performed during the discovery process. 




Example three above suggests that Ethernet-based discovery agents require at least two phases. It is possible 

to have discovery agents that can operate in any phase. 

Managing the Phases 

The different phases of the discovery data collection stage are managed by an internal phase manager that is 

responsible for reading the maximum overall phase number and calculating the total number of phases as 

soon as all the discovery agent and stitcher definition files are loaded. The phase manager is also responsible 

for calculating the phase and process dependencies, that is, which discovery agents are scheduled to run in 

which phases. 

The phase manager also 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. 

The Effect of Discovery Multiphasing on Network Traffic 

One of the main benefits of multiphasing is a reduction in network traffic. Since certain similar types of 

network request are grouped together in phases, data can be cached in the Helper Server to provide an 

efficient means of reducing 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 one actual ping. 

The Helper Server also has a request pool, which ensures that only a certain number of requests are handled 

simultaneously. The request pool ensures the Helper Server does not overload the network. The Helper 

Server is introduced and explained in detail in The Discovery Helper System on page 285. 

39


1.9 After the First Discovery: Rediscovery 

40 

When the data collection and processing stages of the first discovery have completed, and the network 

topology has been sent to MODEL, DISCO adopts a reactive state, ready to conduct a rediscovery if 

necessary. DISCO can be configured to perform either a full rediscovery of the network or a partial 

rediscovery limited to a particular subnet. 

During rediscovery the overall operational stages of DISCO (as described in the previous sections of this 

chapter) remain the same, and DISCO adheres to the configured operational data flow. However, while in 

this stage DISCO is reactive, listening for events that prompt it to initiate a rediscovery of a particular subnet 

or device. 

The receipt of a trap from a device within the network is one example of an event that can trigger a 

rediscovery. In this instance you would configure the data flow so that the receipt of a trap by the Trap finder 

prompts DISCO to assess whether a full or partial rediscovery should be conducted. 

Conducting a Full or Partial Rediscovery 

Once a discovery has been completed, DISCO enters rediscovery mode, in which the discovery of the 

existence of new devices results in updates to the network topology model. One advantage of the fact that 

the discovery data flow is fully configurable is that by modifying the stitchers you can configure the way in 

which DISCO treats devices that are found when 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 only rediscovered once and 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 also rediscovered (although, as explained on page 43, the rediscovery process 

initiates a full rediscovery if the number of devices needing to be rediscovered as a result of relationship 

changes exceeds a certain limit). 

The following sections describe this process in more detail. 

Determining the Current Discovery Mode 

You can determine the current mode of DISCO by querying the disco.status table. If 

disco.status.m_DiscoveryMode=1, DISCO is in rediscovery mode. 

An example query of the disco.status table is given in Using the OQL Service Provider on page 170. 



After the First Discovery: Rediscovery 

By default, DISCO adopts a reactive mode when m_DiscoveryMode=1. If the finders find a new 

device, DISCO determines whether the device is in scope and whether it warrants a full or partial network 

rediscovery. You can configure the way DISCO determines whether to conduct a full or partial rediscovery 

by modifying the FnderRetProcessing.stch stitcher, which handles the processing of devices 

placed in the finders.returns table. The process flow of the FnderRetProcessing.stch 

stitcher is described in Process Flow of the FnderRetProcessing Stitcher on page 41. 

Finding New Devices 

In order to find new devices at any point in the discovery, the finders must be active. Since the network has 

already been discovered, the most practical finder to deploy during rediscovery is the Trap finder, which 

listens for traps (messages that indicate a change in the state of the device). 

In order to run the Trap finder you must either configure DISCO (prior to the discovery) so that it starts 

the Trap finder as a managed process, or alternatively you can start the Trap finder at any time within the 

same domain as DISCO using the ncp_df_trap command as shown below, entering your domain name 

where NCOMS is specified. 

ncp_df_trap -domain NCOMS 

Once the Trap finder has started, it begins to listen for traps. If any traps are received from a network device, 

the Trap finder makes an insert into the finders.returns database table of DISCO. 

Process Flow of the FnderRetProcessing Stitcher 

In order to configure the way in which DISCO handles newly discovered devices, you can edit the 

FnderRetProcessing.stch stitcher, which is the stitcher responsible for processing entries placed 

into the finders.returns table. The default process flow of the FnderRetProcessing.stch 

stitcher is: 

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. 

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. 

41


42 

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: 

– Devices found by the Trap finder where the trap type is either a cold start, warm start or link up. 

– 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. 

– Any newly found device that is in scope and has not already been discovered. 

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. 

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. 

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. 

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 the Discovery Agents 

When 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 is run. This stitcher 

compares the old data in the rediscoveryStore.dataLibrary table with the new data. By 

default, the rediscovery continues from this point, although if necessary, you can edit this stitcher so that, 

for example, rediscovery only continues when SNMP access is available. 

The data is processed by the AssocAddress agent and then by the appropriate agents (according to the 

configured discovery process flow) and returned to their returns tables. 

A full discovery would combine 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 is responsible for determining 

the relationships between devices and the comparison is performed by ProcRemoteConns.stch. 

Switches and hubs need to be rediscovered differently to routers as 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 m_Creator='Rediscovery'. 

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, so the discovery process includes 

a check to prevent this happening. 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 only be 

rediscovered 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, making it 

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 only rebuilds the topology when there are no entities needing to be rediscovered. 

Option to Rebuild Topology Layers 

You can specify whether or not to rebuild the topology layers following a partial rediscovery. Using this 

option, you can greatly increase the speed of partial rediscovery. 

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. 

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. 

43


44 

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: 

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. 

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. 

For more information on the disco.config table, see The config Table on page 427. 

Forcing Rediscoveries of Particular Devices 

Sometimes you may know that one or more devices have had their configuration changed, and may want to 

rediscover them regardless of whether the system has detected the change from traps sent by the devices. 

Forcing a rediscovery can be achieved in two ways: 

You can use the Network Discovery GUI to specify individual devices or complete subnets to be 

rediscovered, as described in Chapter 4: Network Discovery Using the Network Discovery GUI on 

page 85. 

You can make inserts to the finders.rediscovery table using ncp_oql, specifying the IP 

address or subnet to be rediscovered. 

Example Forced Rediscovery 

To force a rediscovery of 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, execute the following query: 

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 re-analyze it. If the connections from the 

device have changed, neighboring devices may also be rediscovered. 

Note: Forced rediscoveries are not intended as a means of removing devices from the discovery if they have 

been removed from the network. A network management application cannot assume that a device that is no 

longer accessible has been deliberately removed from the network. Forced rediscoveries should only be used 

against devices that are operational but whose configuration has been changed. 


Removing a Device from Your Network 



The best way to deal with a device that is known to be scheduled for permanent removal from the network 

is as follows: 

1. Suspend polling against the device, as described in the Netcool/Precision IP RCA and Monitoring 

Guide. This prevents any spurious alerts being raised against the device by the monitoring system as 

the device is powered off. 

2. Physically remove the device from the network. 

3. Immediately before the next full network discovery, set the linger time for the record of the device in 

ncp_model to 0. 

Setting the Linger Time for a Device 

The value of the LingerTime field indicates how many discoveries a particular 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. To set the LingerTime field to zero: 

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 master.entityByName table for all entities that 

represent the device. For example, if the device is called core-router.micromuse.com, enter 

the following command: 

update master.entityByName set LingerTime = 0 where EntityName like 

'core-router.micromuse.com'; 

45


46 


2. CTRL.fm July 6, 2005 

Chapter 2: Process Control with CTRL 

This chapter explains how to configure the domain process controller to manage a single domain or multiple 

domains. 


Introducing CTRL on page 48 

Configuring CTRL on page 49 

Starting CTRL on page 59 

Querying the Databases of CTRL on page 60 



2.1 Introducing CTRL 

48 

CTRL (ncp_ctrl) is the master process controller that launches and manages Precision Server 

components. It also launches the Precision Server components in the appropriate order, in line with the 

configured process dependencies. 

CTRL is the only Precision Server component that can start another process. It is also used by other 

Precision Server processes that need to launch and manage their subprocesses. For example, MONITOR 

launches the Polling agents by sending an Object Query Language (OQL) insert to the tables of the CTRL 

database. 

The CTRL Database 

CTRL uses the services database to manage processes, as follows: 

Inserting a process into the appropriate table of this database causes that process to be executed. 

Deleting a process from the appropriate table of this database causes the process to be terminated. 

You can use CTRL to specify which Netcool/Precision IP processes to start event if CTRL is not yet 

running. This works as follows: 

If CTRL is not yet running, you can specify the Netcool/Precision IP components to be run by 

appending OQL inserts to the CtrlServices.cfg configuration file. 

If CTRL is running, specify the Netcool/Precision IP components to be run by logging into the 

CTRL database using the OQL Service Provider and issuing an insert into the appropriate table of 

the services database. 

You can also configure CTRL by choosing the automatic configuration option during the installation 

process. For more information on the installation process, see the Netcool/Precision IP Installation and 


The schema of the services database is given in The services Database Schema on page 64. 


2.2 Configuring CTRL 

This section describes how to set up CTRL to start and manage Netcool/Precision IP components. 


Configuring CTRL 

Although it is possible to manually launch the individual Precision Server components from the command 

line, it is more convenient to run a Precision Server domain using a single domain controller, which starts 

the individual processes as and when they are needed. 

CTRL has two configuration files: 

CtrlSchema.cfg contains the definitions for the CTRL databases. You should not need to edit 

this file. 

CtrlServices.cfg contains any necessary inserts into the CTRL databases to tell CTRL which 

components to start and in what order. 

In order to configure CTRL to launch and manage the appropriate processes, you must append OQL inserts 

to the CTRL configuration file, CtrlServices.cfg. CTRL starts two types of process: 

Managed processes for which CTRL is fully responsible. CTRL not only starts and stops these 

processes, but also keeps track of their activities and restarts them if they die. 

Unmanaged processes that CTRL is only responsible for starting or stopping. CTRL is not responsible 

for tracking unmanaged processes and makes no attempt to restart these processes if they die. 

Although it is entirely up to you to determine which processes are managed and which are unmanaged, it is 

recommended that the core Precision Server components are handled as managed processes. Only processes 

such as scripts should be launched as unmanaged processes. 

Note: CTRL must be used when running Netcool/Precision IP in failover configuration, as described in the 

Netcool/Precision IP Monitoring and RCA Guide. 

Setting up a Single Netcool/Precision IP Domain 

Micromuse recommends using one instance of CTRL to run and manage each domain. To set up a single 

Netcool/Precision IP domain: 

1. Back up your CtrlServices.cfg file. 

2. Save a copy of the CtrlServices.cfg file with your domain name appended to the filename, 

for example, CtrlServices.MASTER.cfg. 

3. Edit the CtrlServices.MASTER.cfg file following the instructions in this chapter. 

49


50 

4. Make any other configuration adjustments that you require. For example, you can configure your 

discovery (see Chapter 6: Network Discovery from the Command Line on page 175) and save your 

discovery configuration files with MASTER appended to the filename as above. If you configure your 

discovery using the Discovery Configuration GUI, your configuration files are automatically saved 

with the domain name in which the GUI was started appended to the filenames. 

5. Start CTRL using the following command: 

ncp_ctrl -domain MASTER & 

6. CTRL now starts the required components in the domain MASTER in the order you specified. 

Setting up Multiple Netcool/Precision IP Domains 

Micromuse recommends using one instance of CTRL to run and manage each domain. You can run several 

instances of CTRL simultaneously if required, each one managing a different domain. To set up two 

domains: 


2. Save a copy of the CtrlServices.cfg file with your first domain name appended to the 

filename, for example, CtrlServices.DOMAIN1.cfg. 

3. Edit the CtrlServices.DOMAIN1.cfg file following the instructions in this chapter. 



discovery configuration files with DOMAIN1 appended to the filename as above. If you configure 

your discovery using the Discovery Configuration GUI, your configuration files are automatically 

saved with the domain name in which the GUI was started appended to the filenames. 


ncp_ctrl -DOMAIN1 & 

6. CTRL now starts the required components in the domain DOMAIN1 in the order you specified. 

7. Save another copy of the CtrlServices.cfg file with your second domain name appended to 

the filename, for example, CtrlServices.DOMAIN2.cfg. 


9. Make any other configuration adjustments that you require, as in step 4. 


ncp_ctrl -domain DOMAIN2 & 





You now have two domains running separately. You can start, stop, or configure one domain without 

affecting the other. 

Note: When creating a new domain you must configure ncp_model_to_mysql to migrate the 

topology into the MySQL database used by Topoviz. During this configuration you are asked to provide the 

names of the ObjectServers that should be associated with the domain. It is not possible to associate a single 

ObjectServer with multiple domains. See the Netcool/Precision IP Installation and Deployment Guide for 

more details. 

Configuring Netcool/Precision IP Domains on Windows 

The following sections describe how to handle Netcool/Precision IP processes as Windows services and how 

to set up or remove domains as Windows services. 

If you want to configure and control domains from a console window, follow the steps in Setting up a Single 

Netcool/Precision IP Domain on page 49. 

Handling Netcool/Precision IP Processes as Windows Services 

There are two different ways of running Netcool/Precision IP processes on Windows: 

From a console; when a process is run from the console, it is run by the current user. If the user has 

restricted permissions, Netcool/Precision IP might not function correctly. Use Windows Control 

Panel to check user permissions. 

As a service; a service is the Windows equivalent of a background process on UNIX. When 

Netcool/Precision IP is installed, the installer creates services for the domain set up as part of the 

installation process. It is possible to install, or remove, services for additional domains by use of the 

ncp_install_services program. You can also start or stop services manually. 

The main benefit of running Netcool/Precision IP processes as services is that an administrator can create 

domains and services that a standard user can start even if that user does not have adequate permissions to 

run the service. Another benefit is that no visible windows clutter your desktop. 

The main advantage of running processes from the console is that troubleshooting is easier if any problems 

occur. 

Windows services have no STDOUT or STDERR. Therefore they must always log to a file, even if a specific 

file has not been configured for them in CtrlServices.cfg. By default, Netcool/Precision IP 

processes running as services will create log files in %NCHOME%\log\Precision, so you must not 

delete this directory. If you specify a different log file in CtrlServices.cfg then that specified file will 

be used instead. 

51


52 



page 10. 

Running Windows Services as a Specific User 

When a process is run as a service, it is run by the user configured to run that service, regardless of which 

user starts it. The default user for services is "LocalSystem", which Task Manager displays as "SYSTEM". 

To change the default Service user, select the service from the Windows Services window 

(Start Menu→Control Panel→Administrative Tools→Services) and modify its properties to include the 

revised user and password. You can also install all services for a domain to run as a specific user, using the 

following command: 

ncp_install_services -domain MASTER -username "MICROMUSE\admin" 

All domain services for MASTER will run under user "admin", as opposed to the default "LocalSystem". 

You must type in the password for the "admin" user before Netcool/Precision IP creates the services. You 

can specify the password on the command line using the -password option, but this is not recommended for 

security reasons. 

Setting Up an Additional Netcool/Precision IP Domain on Windows 

Micromuse recommends using one instance of CTRL to run and manage each domain. To set up an 

additional Netcool/Precision IP domain using Windows services: 


2. Save a copy of the CtrlServices.cfg file with your domain name appended to the filename, 

for example, CtrlServices.MASTER.cfg. 

3. Edit the CtrlServices.cfg file following the instructions in this chapter. 



discovery configuration files with MASTER appended to the filename as above. If you configure your 

discovery using the Discovery Configuration GUI, your configuration files are automatically saved 

with the domain name in which the GUI was started appended to the filenames. 

5. Edit the InstallServices.cfg file to include the services you want to install and any default 

parameters; this file uses the same format as the CtrlServices.cfg file. 

Note: The most frequently changed parameter is the name of the ObjectServer, but please note that 

when ncp_ctrl starts a service, any parameters in CtrlServices.cfg will take precedence 

over default service parameters. 


6. Create the domain using the command below: 

ncp_install_services -domain MASTER 



7. CTRL now starts the required components for the domain MASTER in the order you specified in the 

CtrlServices.MASTER.cfg file. 

8. View the Services window (Start Menu→Control Panel→Administrative Tools→Services) to check 

that all the required services are installed. See Figure 9. 

Figure 9: Services Window Showing Netcool/Precision IP Services 

9. If you want Netcool/Precision IP to start automatically each time you reboot your machine, then 

select "ncp_ctrl for domain MASTER" from the Services list and edit its properties so that 

it starts automatically. Leave all other Netcool/Precision IP services as manual startups, as 

ncp_ctrl will start them when they are required. 

10. Start the ncp_ctrl service; ncp_ctrl will will start the other services defined in the 

CtrlServices.MASTER.cfg file. 

53


54 

Setting Up Multiple Netcool/Precision IP Domains on Windows 

Micromuse recommends using one instance of CTRL to run and manage each domain. You can run several 

instances of CTRL simultaneously if required, each one managing a different domain. You must set up a 

separate ObjectServer for each domain. 

To set up two domains to run as services: 

1. Back up your CtrlServices.cfg file for the domain you set up during installation. 

2. Save a copy of the CtrlServices.cfg file with your first domain name appended to the 

filename, for example, CtrlServices.DOMAIN1.cfg. 




discovery configuration files with DOMAIN1 appended to the filename as above. If you configure 

your discovery using the Discovery Configuration GUI, your configuration files are automatically 

saved with the domain name in which the GUI was started appended to the filenames. 


parameters; this file uses the same format as the CtrlServices.cfg file. 

Note: The most frequently changed parameter is the name of the ObjectServer, but please note that 

when ncp_ctrl starts a service, any parameters in CtrlServices.cfg will take precedence 

over default service parameters. 


ncp_install_services -domain DOMAIN1 

7. Use the following command to start CTRL as a console process: 

ncp_ctrl -DOMAIN1 

If you want to run ncp_ctrl as a service, start it by opening the Windows Services window (Start 

Menu, Control Panel, Administrative Tools, Services) and then find the service named "ncp_ctrl 

in domain DOMAIN1". Select the service and click on the Service Start button. 


9. Save another copy of the CtrlServices.cfg file with your second domain name appended to 

the filename, for example, CtrlServices.DOMAIN2.cfg. 






parameters, as in step 5. 


ncp_install_services -domain DOMAIN2 

13. Make any other configuration adjustments that you require, as in step 4. 

14. Use the following command to start CTRL as a console process: 

ncp_ctrl -domain DOMAIN2 

If you want to run ncp_ctrl as a service, start it by opening the Services window 

(Start Menu→Control Panel→Administrative Tools→Services) and then find the service named 

"ncp_ctrl in domain DOMAIN2". Select the service and click on the Service Start button. 


You now have two domains running separately. You can start, stop, or configure one domain from the 

Services window (Start Menu→Control Panel→Administrative Tools→Services) without affecting the 

other. 

Note: When creating a new domain you must configure ncp_model_to_mysql to migrate the 

topology into the MySQL database used by Topoviz. During this configuration you are asked to provide the 

names of the ObjectServers that should be associated with the domain. It is not possible to associate a single 

ObjectServer with multiple domains. See the Netcool/Precision IP Installation and Deployment Guide for 

more details. 

Removing Netcool/Precision IP Services on Windows 

To remove services for a domain (in this example, MASTER), check that the services have stopped and then 

use the following command: 

ncp_install_services -domain MASTER -remove 

If the individual services are subject to control by ncp_ctrl, you must stop ncp_ctrl in order to stop 

the services. Any attempt to stop the individual services while ncp_ctrl is still running will result in 

ncp_ctrl restarting them. 

If you uninstall Netcool/Precision IP, the installer will only uninstall the services it created during the 

installation; any services for domains created subsequent to the installation will be left on your system. Use 

ncp_install_services to remove all such services prior to uninstalling Netcool/Precision IP, 

otherwise you will be unable to remove the orphan services. 

55


Component Dependencies 

56 

The Precision Server components must be started in the correct order. The component dependencies are 

shown in Table 3. 

Table 3: Dependencies of the Precision Server Processes 

Component Binary Name Dependencies 

AMOS ncp_f_amos MODEL, CLASS, STORE 

AUTH ncp_auth No dependency 

CLASS ncp_class No dependency 

CONFIG ncp_config No dependency 

CTRL ncp_ctrl No dependency 

DISCO ncp_disco The Helper Server, CTRL 

Discovery Configuration Tool ncp_discoconfig AUTH, CONFIG 

Gateway ncp_ncogate AMOS, MODEL, Netcool/OMNIbus 

ObjectServer 

The Helper Server ncp_d_helpserv No dependency 

MODEL ncp_model CLASS, STORE 

MONITOR ncp_monitor MODEL, CLASS, PROBE, CTRL 

OQL Service Provider ncp_oql AUTH and the component you wish to 

interrogate 

MONITOR Configuration Tool ncp_monitorconfig AUTH, CLASS 

MONITOR Probe nco_p_ncpmonitor Netcool/OMNIbus ObjectServer 

STORE ncp_store No dependency 

TrapMux ncp_trapmux No dependency 

User Configuration Tool ncp_userconfig AUTH, CONFIG 

Configuring Managed Processes 

In order to configure a process as a managed process, you must append an Object Query Language (OQL) 

insert into the services.inTray table. For more information on OQL, see The Object Query Language 

on page 479. For the full schema of the services.inTray table, see The services Database Schema on 

page 64. 


Example Configuration of DISCO as a Managed Process 

The following example configures DISCO to be launched as a managed process. 

insert into services.inTray 

( 

serviceName, 

servicePath, 

domainName, 

hostName, 

argList, 

dependsOn, 

retryCount, 

logFile 

) 

values 

( 

"ncp_disco", 

"$NCHOME/precision/bin", 

"NCOMS", 

"Felix", 

[ "-domain", "NCOMS", "-debug", "4" ], 

[ "ncp_d_helpserv" ], 

3, 

"$NCHOME/log/precision/disco.log" 

); 

The above insert instructs CTRL to: 

Launch ncp_disco as a managed process. 

Locate the executable in $NCHOME/precision/bin. 

Launch DISCO in the NCOMS domain on the host Felix. 

Pass the arguments "-domain NCOMS" and "-debug 4" to DISCO. 

Wait for the Helper Server to be active before starting DISCO. 

Restart DISCO a maximum of 3 times. 

Configuring Unmanaged Processes 



In order to configure a process as an unmanaged process, you must append an insert into the 

services.unManaged table. For the full schema of the services.unManaged table, see The 

unManaged Table on page 66. 

The services.unManaged table is mainly used by other Precision Server processes to instruct 

CTRL to start their subprocesses. For example, DISCO instructs CTRL to start the finders, helpers and 

agents by sending inserts into the services.unManaged table of CTRL. 

57


58 

Example Configuration of an Unmanaged Process 

In order to configure a user_script located in the NCHOME/precision/scripts directory as an 

unmanaged process, you would append an insert similar to the following to the CtrlServices.cfg 

configuration file. 

insert into services.unmanaged 

( 

serviceName, servicePath, argList 

) 

values 

( 

"user_script", 

"/opt/netcool/precision/solaris2/scripts/", 

[ ] 

); 


2.3 Starting CTRL 


Starting CTRL 

CTRL is started by using the following command line; optional arguments are shown enclosed in square 

brackets. 

ncp_ctrl –domain DOMAIN_NAME [ -debug DEBUG ] [ -help ] [ -latency LATENCY ] 

[ -logdir DIRNAME ] [ -slave ] [ -version ] 

Table 4: Explanation of Command Line Options 

Option Explanation 

-domain DOMAIN_NAME The name of the domain under which to run CTRL. 

-debug DEBUG The level of debugging output (1-4, where 4 represents the most detailed 

output). 

-help Displays the command line options. Does not start the component even if 

used in conjunction with other arguments. 

-latency LATENCY The maximum time in milliseconds (ms) that CTRL waits to connect to 

another Precision Server process using the messaging bus. This option is 

useful for large and busy networks where the default settings can cause 

processes to assume that there is a problem when in fact the 

communication delay is a result of network traffic. 

-logdir DIRNAME Directs log messages for each process started by CTRL to a separate file in 

the specified directory. 

-slave Indicates that this instance of CTRL is to be run in slave mode. The slave 

CTRL process must have the same domain name as the master CTRL 

process. 

Prerequisites for Running CTRL 

When running in slave mode, CTRL accepts requests from the master 

process to launch services. The slave mode can be used to distribute 

processes. 

-version Displays the version number of the component. Does not start the 

component even if used in conjunction with other arguments. 

CTRL is the master process and must be run before all other processes. For example, CTRL must be running 

in order for DISCO and MONITOR to launch their subprocesses. Provided CTRL has been configured 

correctly, it launches and manages the appropriate processes when their dependencies have been satisfied. 

59


2.4 Querying the Databases of CTRL 

60 

You can interact with the databases of CTRL by using the OQL Service Provider (ncp_oql) to manipulate 

entries directly. Inserting a process into the services.inTray table using the OQL Service Provider 

causes that process to be launched. Deleting an entry in the services.inTray table using the OQL 

Service Provider causes the process to be terminated. 

See Chapter 5: Querying Netcool/Precision IP Databases on page 165 for information on starting ncp_oql, 

querying databases, and exiting ncp_oql. 

The schema of the service database of CTRL is given after the example queries, in The services Database 

Schema on page 64. 

Logging onto the Databases of CTRL 

Before you can log into the databases of CTRL you must ensure that AUTH and CTRL are running for the 

domain that you wish to interrogate. 

You can log into the databases of CTRL using a command similar to the following: 

ncp_oql -domain NCOMS -service Ctrl -username admin 

Replace NCOMS and admin with your domain name and username. 

The following sections contain examples showing some common OQL queries. 

Identifying the Services That Are Configured To Run 

The following query returns all the services that CTRL is configured to run. 

|phoenix:1.> select * from services.inTray; 

|phoenix:2.> go 

{ 

serviceId=3; 

serviceName='ncp_model'; 

domainName='NCOMS'; 

hostName='phoenix'; 

argList=['-domain', '$domainName']; 

processId=7222; 

dependsOn=['ncp_class', 'ncp_store']; 

serviceState=4; 

retryCount=3; 

interval=10; 

} 

..... 

..... 

{ 

serviceId=4; 


serviceName='ncp_disco'; 


hostName='phoenix'; 

argList=['-domain','$domainName']; 


dependsOn=['ncp_d_helpserv']; 


retryCount=3; 

interval=10; 

} 

( 4 record(s) : Transaction complete ) 

|phoenix:1.> 


Querying the Databases of CTRL 

In the above example, |phoenix:1.> represents the OQL Service Provider prompt. phoenix is 

replaced by the appropriate value for your system, such as the host name. Every time you press the Enter 

key, the line counter increases by 1. 

Which Services Are Currently Active? 

The following query returns the processes that CTRL has started that are currently running (that is, 

processes for which services.inTray.serviceState=4). 

|phoenix:1.> select serviceName, domainName, processId 

|phoenix:2.> from services.inTray 

|phoenix:3.> where serviceState = 4 ; 


........... 

{ 

serviceName='ncp_store'; 



} 

{ 




} 

{ 




} 


|phoenix:1.> 

A list of the possible values of the serviceState column (and their meanings) can be found on page 66. 

61


62 

Identifying Services Currently Unmanaged 

Insertions into the services.unManaged table are made by other Precision Server components in 

order to start and stop their subprocesses; for example, DISCO uses CTRL to start the finders. The OQL 

query returns a list of processes that have been started by CTRL but are not managed by CTRL. 

|phoenix:1.> 

|phoenix:1.> select * from services.unManaged; 


.. 

{ 

serviceId=6; 

serviceName='ncp_df_ping'; 

servicePath='/opt/netcool/precision/Release/Solaris2/disco/bin/'; 

argList=['-domain','NCOMS']; 

processId=0; 


} 

{ 

serviceId=7; 

serviceName='ncp_df_file'; 

servicePath='/opt/netcool/precision/Release/Solaris2/disco/bin/'; 

argList=['-domain','NCOMS']; 

processId=0; 


} 


|phoenix:1.> 

Terminating a Service with CTRL 

You can terminate a service that is running by deleting the record in the services.inTray table. The 

following example terminates ncp_model. 

|phoenix:1.> delete from services.inTray 

|phoenix:2.> where serviceName = 'ncp_model' ; 


. 


|phoenix:1.> 


Dynamic Configuration Changes 



Once CTRL has loaded its configuration from CtrlServices.cfg, you can amend the configuration 

by making insertions, deletions and updates to the records of the CTRL databases. In the following example, 

the record for STORE is inserted into the database, which results in the execution of the ncp_store 

process. 

|phoenix:1.> insert into services.inTray 

|phoenix:2.> ( serviceName, domainName, 

|phoenix:3.> argList, retryCount ) 

|phoenix:4.> values 

|phoenix:5.> ( 'ncp_store', 'NCOMS' , 

|phoenix:6.> [ '-domain', '$domainName' ], 

|phoenix:7.> 3 

|phoenix:8.> ); 


. 


|phoenix:1.> 

Identifying Configured Process Dependencies 

The following query returns the configured component process dependencies. 

|phoenix:1.> select serviceName, dependsOn 

|phoenix:2.> from services.inTray; 


..... 

{ 

serviceName='ncp_auth'; 

dependsOn=[]; 

} 

{ 

serviceName='ncp_store'; 

dependsOn=[]; 

} 

..... 

..... 

{ 


dependsOn=['ncp_class', 'ncp_store']; 

} 

{ 


dependsOn=['ncp_d_helpserv']; 

} 


|phoenix:1.> 

63


The services Database Schema 

64 

The services database enables CTRL to manage and monitor the status of the core 

Netcool/Precision IP processes. The services database is described in Table 5. 

Table 5: Synopsis of the services database 

Database Defined in Fully qualified database table names 

services NCHOME/etc/precision/CtrlSchema.cfg services.inTray 

The inTray Table 

The inTray table is an active table for managed processes. Inserts into this table cause processes to be 

launched and deletions from the table cause processes to be terminated. CTRL also monitors the status of 

processes named in the inTray table and restarts them if they die. 

Table 6: services.inTray Database Table Schema (1 of 2) 

Column name Constraints Data type Description 

serviceId PRIMARY KEY 

NOT NULL 

UNIQUE 

services.slaveCtrl 

services.unManaged 

services.unControlled 

Integer The unique ID of the service (assigned internally). 

serviceName NOT NULL Text The name of the service to be managed. 

servicePath Text The full path to the service executable, assumed to 

be NCHOME/precision/bin if NULL. 

domainName Text The domain under which the service is to run. 

hostName Text The name of the machine upon which the service is 

to run. 

argList List of type text List of arguments sent to the service executable. 

processId Long integer The process ID of the service. 

dependsOn List of type text A list of processes that the current service is 

dependent on, that is, prerequisites. 


Table 6: services.inTray Database Table Schema (2 of 2) 


serviceState Externally defined 

serviceState data type 

The slaveCtrl Table 



Integer Integer reflecting the current operational state of 

the service: 

(0) The service is alive but currently idle. 

(1) The service is waiting for its prerequisites, that is, 

waiting for its dependencies to be satisfied. 

(2) The service is currently waiting for a heartbeat 

from another service. 

(3) Fork service, that is, the application is currently 

starting. 

(4) The service is alive and running. 

(5) The service is sick. 

(6) The service is dead. 

(7) The service has failed. 

(8) Shutdown. 

retryCount Integer The number of attempts to restart a service before 

aborting. 

interval Integer The average interval between service heartbeats 

(that is, signals from the service). 

logFile Text Name of file where output is logged. 

The slaveCtrl table is populated automatically and serves as a reference for other instances of CTRL 

that are running in slave mode. You must not use the OQL Service Provider to insert records into this table 

manually. 

Table 7: services.slaveCtrl Database Table Schema (1 of 2) 


slaveId UNIQUE 

PRIMARY KEY 

NOT NULL 

Integer The unique identification number of the CTRL 

process running in slave mode. 

domainName Text The domain under which the slave CTRL process is 

operating. 

hostName Text The name of the machine on which the slave CTRL 

process is running. 

65


66 

Table 7: services.slaveCtrl Database Table Schema (2 of 2) 


processId Long integer The process ID of the slave CTRL process. 

slaveState Externally defined 


The unManaged Table 

Integer The current operational state of the slave process. 

The unManaged table is used by CTRL to launch and terminate ‘unmanaged’ processes. An unmanaged 

process is defined as any process that is to be started by CTRL but is not monitored or restarted if it dies. 

The unManaged table is active, so inserting or deleting records from the table causes the corresponding 

processes to be started or stopped. 

Table 8: services.unManaged Database Table Schema 


serviceId UNIQUE 

PRIMARY KEY 

NOT NULL 

Integer The unique ID of the service. 

serviceName NOT NULL Text The name of the service. 

servicePath Text The full path to the service executable. If NULL, 

NCHOME/precision/bin is assumed. 

hostName Text The machine the service is running on. 

argList List of type Text A list of arguments that is sent to the service 

executable. 

processId Long integer The service process ID. 



Integer Integer reflecting the current operational state of 

the service. 

logFile Text Name of file where output is logged. 


The unControlled Table 



The unControlled table is a read-only table that is used to monitor uncontrolled services. Uncontrolled 

services are services from which CTRL has received a heartbeat but did not start. The unControlled 

table is for information purposes only and you must not make inserts into this table as this may lead to 

undesired functionality. 

Table 9: services.unControlledDatabase Table Schema 


serviceId UNIQUE 

PRIMARY KEY 

NOT NULL 

Integer The unique ID of the service. 

serviceName NOT NULL Text The name of the service. 

domainName Text The domain under which the service is running. 

hostName Text The name of the machine on which the service is 

running. 

processId Long integer The process ID of the service. 



Integer Integer reflecting the current operational state of the 

service. 

interval Integer The average interval between heartbeat signals from 

the service. 

67


68 


3. User_Configuration_Tool.fm July 7, 2005 

Chapter 3: Creating and Managing Users 

This chapter describes the User Configuration Tool. You can use this tool to add users to Netcool/Precision 

IP and configure user profiles. This chapter also describes AUTH, the Netcool/Precision IP Server 

authentication engine. 

The User Configuration Tool is not available for Netcool/Precision IP deployments on Windows; you can 

modify AUTH using OQL if you need to change or add user settings for a Windows deployment. 


Introduction to User Management on page 70 

Starting AUTH on page 73 

Starting the User Configuration Tool on page 74 

Using the User Configuration Tool on page 75 

The AUTH Database on page 82 



3.1 Introduction to User Management 

70 

A valid Netcool/Precision IP username and password is required in order to log into the following services: 

The Desktop 

The User Configuration Tool 

The Discovery Configuration Tool 

The OQL Service Provider 

The MONITOR Configuration Tool 

Note: The User Configuration Tool described in this chapter enables you to manage user accounts for the 

systems listed above. There is a separate set of user management functionality within the Netcool GUI 

Foundation. That user management functionality manages user access to the Netcool/Precision IP web 

applications, which run under the Netcool GUI Foundation. For introductory information on the Netcool 

GUI Foundation, see the Netcool/Precision IP Visualization Guide. For detailed information on how to 

perform user management functions within the Netcool GUI Foundation, administrators should refer to 

the Netcool GUI Foundation Administration Guide. 

The User Configuration Tool 

The User Configuration Tool is a GUI for creating, editing and managing user accounts. Creating a new 

user involves: 

Creating a user account and defining its username and password. 

Associating a profile, (that is, a set of permissions) with the user account. You can either use the 

predefined profiles, which are suitable for most Netcool/Precision IP users, or you can create your 

own profiles. 

Each profile is ranked with an integer value from 0 to 50, where 0 is the highest available rank and 50 the 

lowest. The rank of a profile is used within the Precision Desktop. 

If a user is assigned a profile that does not allow access to the User Configuration Tool, the user can only use 

the Tool to change their own password. 

User Authentication with AUTH 

AUTH (ncp_auth) is responsible for authenticating users for components that require authentication. 

AUTH supervises all user transactions, ensuring that users have permission to manage the network or 

configure the Precision Server. 



Introduction to User Management 

For example, when a user attempts to log into the databases of a Netcool/Precision IP component using the 

OQL Service Provider, the service provider communicates with AUTH to check that the user has permission 

to access those databases. The OQL Service Provider is only launched if AUTH validates the user by sending 

an authentication approval; otherwise the process is terminated. 

Netcool/Precision IP users must be configured with the User Configuration Tool, a standalone GUI 

supplied with the Precision Server. There are two stages to managing users with AUTH: 

1. Creating one or more profiles. 

2. Creating users and assigning a defined profile to each individual user. 

Profile Creation and Management 

A profile is a set of specific privileges or permissions that defines the actions that a user assigned to that profile 

can perform when using the Precision Server. For example, you may want to restrict certain users from 

modifying the AOC definitions using the MONITOR Configuration tool, and would therefore allow those 

users to view, but not modify, the class hierarchy. You could also restrict some users from accessing or 

modifying the Precision Server databases using the OQL Service Provider. 

It is perfectly acceptable to assign the same profile to many users, provided you are aware that those users 

have common permissions. You cannot, however, edit the supplied super profile, which must be assigned 

to the system administrator and which allows full control over the Precision Server, or assign this profile to 

multiple users. 

The profile rank is used by the Precision Desktop to determine which users can assign alerts to other users. 

A user can only assign alerts to another user with a lower or equal rank. 

User Creation 

You can create users by defining a username and password in the User Configuration Tool. Once a user has 

been defined, a profile must be assigned to them. 

Configuring User Permissions 

The auth database stores information on each user, such as their name, password and access privileges. 

Although it is possible to configure AUTH by editing the configuration file, this is not recommended 

practice as you are unable to configure encrypted passwords. It is therefore highly recommended that you 

configure user privileges through the User Configuration Tool, as described in Using the User Configuration 

Tool on page 75. 

71


72 

Changes made using the User Configuration Tool are automatically saved in an updated 

AuthSchema.cfg configuration file in the directory specified using the ncp_config 

-write_schemas_to command line option. If no directory was specified when CONFIG was started, 

the updated AuthSchema is saved in NCHOME/etc/precision and the existing AuthSchema is 

moved to NCHOME/etc/precision/backup. 



page 10. 

The Default Profiles 

Table 10 provides details of the default profiles that are supplied with the Precision Server. With suitable 

permissions, you can edit these profiles or create new profiles if necessary. You cannot edit the super profile, 

create a new profile with rank 0 or create another user with the profile ID super. 

The Default User 

! 

Table 10: Default Profiles Supplied with the Precision Server 

Profile ID Description Rank Permissions 

super The super user 0 Full control. 

admin Systems Administrator 1 Read and write permissions on all component databases and 

the ability to assign alerts in the Precision Desktop. 

supervise Supervisor 50 Read-only permissions on all databases and the ability to 

assign alerts in the Precision Desktop. 

user A Precision Desktop user 50 Read-only access to the Precision Desktop and the ability to 

assign alerts in the Precision Desktop. 

guest A read-only Precision Desktop 

user 

50 Read-only access to the Precision Desktop. 

By default, the Precision Server is supplied with an admin user account associated with the super profile. 

The admin account must be the only account associated with the super profile. 

Warning: Micromuse recommends that the system administrator change the password for the default user 

account (by default there is no password) and use the account to create other user accounts and configure 

their permissions. 


3.2 Starting AUTH 


Starting AUTH 

It is good practice to configure CTRL to launch and manage AUTH. AUTH can also be started manually 

using the following command line; optional arguments are shown enclosed in square brackets. 

ncp_auth -domain DOMAIN_NAME [ -debug DEBUG ] [ -help ] [ -latency LATENCY ] [ -version ] 



-domain DOMAIN_NAME The name of the domain under which to run AUTH. 

-debug DEBUG The level of debugging output (1-4, where 4 represents the most detailed output). 

-help Displays the command line options. Does not start the component even if used in 

conjunction with other arguments. 

-latency LATENCY The maximum time in milliseconds (ms) that AUTH waits to connect to another 

Precision Server process using the messaging bus. This option is useful for large 

and busy networks where the default settings can cause processes to assume that 

there is a problem when in fact the communication delay is a result of network 

traffic. 

-version Displays the version number of the component. Does not start the component 

even if used in conjunction with other arguments. 

Prerequisites for Running AUTH 

AUTH has no prerequisites. 

73


3.3 Starting the User Configuration Tool 

74 

In order to start the User Configuration Tool, you must have AUTH and CONFIG running in your 

domain. If AUTH and CONFIG are not running, the User Configuration Tool launches them on startup 

(and kills them on shutdown). 

Note: Only users with permission to make changes to other users and profiles can log into the User 

Configuration Tool. If you do not have permission to edit other users and profiles, then the only 

functionality available to you in the User Configuration Tool is to change your password. 

Start the User Configuration Tool using the following command: 

ncp_userconfig -domain NCOMS 

Substitute your domain name where NCOMS is specified. If EXEC is running, you can also start the User 

Configuration Tool from the Precision Desktop, by selecting the Admin→Configuration→User 

Configuration menu option. A graphical login window is displayed, as shown in Figure 10. Enter your 

username and password and click the Login button to start the User Configuration Tool. 

Figure 10: Login Window 

Only users with permission to make changes to other users and profiles can log into the User Configuration 

Tool. If you do not have permission to edit other users and profiles, you are asked whether you want to 

change your password, as this is the only functionality available to you in the User Configuration Tool: 

If you select Yes, you can enter your new password in the User Information window, as described in 

The User Information Window on page 76. 

If you select No, the User Configuration Tool exits. 


3.4 Using the User Configuration Tool 


Using the User Configuration Tool 

The User Configuration Tool consists of two main windows, the User List window and the Profile List 

window. 

The User List window is used to view and edit user details. To switch to the User List window, click the Users 

tab. The User List window is displayed on start-up by default. 

The Profile List window is used to view and edit user profiles. To switch to the Profile List window, click the 

Profiles tab. 

Creating and Editing Users 

The User List window shows all currently configured users. The User List window displays the following 

attributes of each account: 

User ID that is used to log into to the Netcool/Precision IP GUIs and the OQL Service Provider. 

The Name associated with the user. 

The Profile associated with the user. 

Whether or not the account is locked. 

Figure 11 shows an example User List window, with the Gandalf account selected. 

Figure 11: User List Window 

To delete a user: 

1. Select the user. 

2. Click the Delete button. 

75


76 

There is no undo functionality. You can only delete a user if you have permission to do so. 

To create a new user: 

1. Change the value in the drop-down list box to indicate the type of user to create: 

– Empty creates a new blank user. 

– Selected creates a new user based on the currently selected user. Creating a new user based on 

the selected user copies all the fields from the existing user except the User ID, Name and 

password. 

2. Click the New button. The User Information window appears. 

3. Enter the appropriate information in the User Information window. The User Information window is 

described in the next section. 

To edit an existing user: 

1. Double-click the user in the list, or 

2. Select the user and then click the Edit button. 

3. The User Information window appears. Enter the appropriate information in the User Information 

window. The User Information window is described in the next section. 

The User Information Window 

Use the User Information window to edit the properties of an existing or a new user account. You can enter 

or modify the following information, although only the username and profile are required for a valid user. 

The User Information window has two tabs, the General tab and the Contact tab. 


General Tab 

The User Information window is shown in Figure 12, with the General tab selected. 

Figure 12: User Information Window: Entering General Information 

In the General tab, you can enter the following information: 



The User ID that is used to log into the Netcool/Precision IP GUIs and the OQL Service Provider. 

The full Name of the user. 

A Description for the user. 

Whether or not the account is to be locked (select the Account Locked check box to lock the 

account). 

The Profile associated with the account (select the appropriate profile from the drop-down list box). 

The Password for the user (the password must be entered twice). 

Contact Tab 

In the Contact tab, not shown, you can enter the following information: 

The Title of the user. 

The Organisation that the user belongs to. 

The Location of the user. 

77


78 

The telephone number of the user. You can enter as many numbers as necessary: 

– To add a number, enter the number in the text box and click the + button; the number is added 

to the drop-down list box. 

– You can remove a number from the drop-down list box by selecting it and clicking the X 

button. 

The e-mail address of the user. 

The pager number of the user. 

Any extra information for this user. To enter extra information, click the Extra Info button. The 

Extra Information window is displayed. 

– Enter any parameters and their corresponding values in the text boxes, and select the type of 

value (Integer, String or List) from the drop-down list box. 

– You can enter as many items of extra information as necessary. Click the Add button to add 

more space to enter information. 

– You can remove a line from the Extra Info window by clicking in the Parameter box for that 

line and clicking the Delete button. 

– When you have finished adding extra information, click OK to return to the Contact tab. 

Cancel returns to the Contact tab without making your changes. 

Returning to the User List 

When you have finished modifying the user details, click OK to save the changes and return to the User List 

window. Clicking Cancel returns you to the User List window with no changes saved. 

If you attempt to create a new user account without entering a password for the user—or remove the 

password for an existing user—you are warned of the security implications and prompted to return to the 

User Information window to enter a password. If you wish to create a user account with no password, click 

OK to create the user and return to the User List window. 

Creating and Editing Profiles 

The Profile List window, which is selected by clicking on the Profile tab from the User List window, shows 

the following attributes of each of the currently configured profiles: 

The Profile ID that is associated with user profiles. 

A Description for this profile. 

The Profile List window also indicates which users are associated with the currently selected profile. 




An example Profile List window is shown in Figure 13. The operator profile is currently selected. 

Figure 13: Profile List 

To delete a profile: 

1. Select the profile. 

2. Click the Delete button. 

There is no undo functionality, although you can only delete a profile if you have permission to do so. 

To create a new profile: 

1. Change the value in the drop-down list box to indicate the type of profile to create: 

– Empty creates a new blank profile. 

– Selected creates a new profile based on the currently selected profile. Creating a new profile 

based on the selected profile copies all the fields from the existing profile except the Profile ID. 

79


80 

2. Click the New button. The Profile Information window appears. 

3. Enter the appropriate information in the Profile Information window. The Profile Information 

window is described in the next section. 

To edit an existing profile: 

1. Double-click the profile in the list, or select the profile and then click the Edit button. 

2. The Profile Information window is displayed. Enter the appropriate information in the Profile 

Information window. The Profile Information window is described in the next section. 

The Profile Information Window 

The Profile Information window, displayed in Figure 14, shows the operator profile with a ranking of 45. 

Figure 14: Profile Information Window 


In the Profile Information window, you can enter the following details: 

Profile: the name of the profile. 

The Description of the profile. 



The Ranking of the profile. 0 is the highest profile rank and 50 is the lowest. The 0 ranking is 

reserved for the super profile, so the highest rank that you can select for another profile is 1. 

The permissions are assigned to this profile for various Netcool/Precision IP components. 

Profile Permissions 

Profile permissions are defined on a per-component basis in the Actions area of the Profile Information 

window. For each component you can specify whether a user with this profile has: 

Read-only database access to the component (OQLRead). 

Read and write database access to the component (OQLReadWrite). 

For certain components you can define actions. For example, for the Precision Desktop you can specify 

whether the user can assign alerts to other users (AssignAlert). 

Below the drop-down list box containing the component name are two boxes: the Actions Available list box, 

and the Actions Selected list box: 

If a particular permission appears in the Actions Available list box, that permission is available for the 

currently selected component, but a user with this profile cannot carry out the action. 

If a particular permission appears in the Actions Selected list box, a user with this profile can carry 

out the action. 

Click on a permission in either list box and use the arrow buttons to move that permission between the boxes 

if necessary. When you click on a permission, a textual description of the permission appears in the Action 

Description list box. 

When you have finished modifying the profiles, click OK to return to the Profile List window. Clicking 

Cancel returns to the Profile List window without saving any changes. 

Exiting the User Configuration Tool 

When you have finished modifying the users and profiles, you can exit the User Configuration Tool by 

selecting the menu option File→Exit. 

81


3.5 The AUTH Database 

82 

Table 12 describes the database of AUTH. 

Table 12: auth Database Schema 

Database Description 

The auth database Stores defined profile and user settings. 

The auth Database Schema 

Table 13 describes the auth database. 

Table 13: Synopsis of the auth Database 

Database name auth 

Defined in NCHOME/etc/precision/AuthSchema.cfg 

Fully qualified database table names auth.users 

The users Table 

The users table contains the username and password for each Netcool/Precision IP user. The users 

table also specifies the profile assigned to this user. 

Table 14: auth.users Database Table Schema (1 of 2) 

auth.profiles 

auth.applications 

auth.contactInfo 


m_Name NOT NULL 

Default = "" 

Text The full name of this user. 

m_Password NOT NULL Text The password for this user (automatically 

encrypted by the User Configuration Tool). 

m_Description NOT NULL 

Default = "" 

Text A description of this user. 


Table 14: auth.users Database Table Schema (2 of 2) 


m_Locked NOT NULL 

Default = 1 

m_UserID NOT NULL 

The profiles Table 

PRIMARY KEY 

UNIQUE 


The AUTH Database 

Integer Integer indicating whether this user account 

is locked. 

Text The unique ID that this user uses to log into 

the GUIs and the OQL Service Provider. 

Each Netcool/Precision IP user must be assigned one of the profiles that are stored in the 

auth.profiles table. The profiles table contains information about the rank of the user relative 

to other users and a list of permissions for the profile. 

Table 15: auth.profiles Database Table Schema 


m_ProfileID NOT NULL 

PRIMARY KEY 

UNIQUE 

m_Description NOT NULL 

Default = "" 

m_Ranking NOT NULL 

Default = 50 

m_Permissions Externally defined 

permission data type 

Text The unique ID for this profile. A user is assigned to a 

given profile by inserting the value of 

auth.profiles.m_ProfileID into 

auth.users.m_ProfileID for that user. 

Text A description of this profile that appears in the User 

Configuration Tool. 

Integer The rank of a user assigned to this profile. The super 

user profile has a rank of 0, and any user assigned to 

this profile can make changes to all other profiles. 

Object type 

permission 

The higher the number, the lower the rank. The 

lowest rank is 50. 

A list of permissions associated with this profile. For 

each service the permissions specify whether a user 

assigned to this profile can: 

Read the databases of the service. 

Write to the databases of the service. 

83


84 

The applications Table 

The applications table contains descriptive information that is displayed in the Profile Information 

window of the User Configuration Tool. The applications table is populated by default with 

information provided to assist users wishing to configure the permissions available to a given profile. 

Table 16: auth.applications Database Table Schema 


m_AppID NOT NULL 

PRIMARY KEY 

UNIQUE 

The contactInfo Table 

Text The service name to which this information relates. 

m_Name NOT NULL Text The name of the component and service to which this 

information relates. The contents of the m_Name 

column appear in a drop-down list box in the User 


m_Description NOT NULL Text A description of this service. 

m_Actions Externally defined 

action data type 

The contactInfo table contains contact information for each Netcool/Precision IP user. 

Table 17: auth.contactInfo Database Table Schema 

Object type 

action 


m_UserID NOT NULL 

PRIMARY KEY 

UNIQUE 

A description of each of the available options that 

appear in the User Configuration Tool. 

Text The unique ID that this user uses to log into the GUIs 

and the OQL Service Provider. 

m_Title Text The title of the user. 

m_Organisation Text The organisation of the user. 

m_Location Text The location of the user. 

m_Phone List type text The phone number of the user. 

m_Email_Address Text The e-mail address of the user. 

m_PagerNumber Text The pager number of the user. 

m_ExtraInfo Externally defined 

vblist data type 

Object type 

vblist 

Extra information about this user. 


4. Discovery_Configuration_Tool.fm July 7, 2005 

Chapter 4: Network Discovery Using the 

Network Discovery GUI 

This chapter describes the Network Discovery GUI, which you can use to configure the discovery process. 


Introducing Methods for Configuring Network Discovery on page 86 

Configuring a Discovery on page 96 

Starting and Monitoring a Discovery on page 138 

Using the Discovery Wizard on page 143 

Reading and Writing Configuration Files on page 162 


Chapter 4: Network Discovery Using the Network Discovery GUI 

4.1 Introducing Methods for Configuring Network Discovery 

86 

You must configure the discovery process before attempting to discover your network. Configuring a 

discovery involves specifying parameters that govern how the discovery is performed. These parameters are 

described in Configuring a Discovery on page 96. 

The Precision Server provides two methods for configuring discovery, both of which are described in full in 

this guide. You can: 

Configure the discovery using the Network Discovery GUI, an intuitive GUI that is described in this 

chapter. 

Configure the discovery by manually editing the component configuration files and inserting values 

into the various component databases. This option is described in Chapter 6: Network Discovery from 

the Command Line on page 175 of this guide, but must only be used by advanced Precision Server 

users. 

If necessary you can use both methods of configuration. 

Note: Before configuring and running a discovery, you need to perform certain preparatory checks on your 

Netcool/Precision IP Server and on the networks you wish to discover. For more information, see Preparing 

for Discovery on page 177. 

The Network Discovery GUI 

The Network Discovery GUI offers two ways to configure your discovery, either using a wizard that guides 

you step-by-step through the process, or by using the custom configuration option, which allows you to edit 

specific discovery fields. If you are configuring the discovery for the first time, you are advised to use the 

wizard to configure your discovery. 

Accessing the Network Discovery GUI 

To access the Network Discovery GUI, log into the Netcool GUI Foundation, as described in the 

Netcool/Precision IP Topology Visualization Guide. The Netcool GUI Foundation is installed as part of the 

Netcool/Precision IP installation, and is the framework within which all Netcool/Precision IP web interfaces 

appear. 



Introducing Methods for Configuring Network Discovery 

Once you have logged into the Netcool GUI Foundation, select the Precision Admin page. This page 

provides access to the Network Discovery GUI, OQL Workbench and MySQL database settings, as shown 

in Figure 15. This figure shows the Precision Admin page with the Discovery Configuration tab open. See 

Table 18 on page 88 for information on which tabs to click to access the different sections of the Precision 

Admin page. 

Figure 15: Precision Admin Page Showing Discovery Configuration Options 

87


88 

Table 18: Tabs Available on the Precision Admin Page 

Tab Section of Network Discovery GUI 

Discovery Configuration Click here to configure a discovery in one of the following ways: 

Discovery Configuration Tab 

Configure a custom discovery as described in Configuring a Discovery on 

page 96. 

Use the wizard to help you choose configuration settings based on typical 

discovery scenarios as described in Using the Discovery Wizard on page 143. 

This section of the Network Discovery GUI is described in Discovery Configuration 

Tab on page 88. 

Discovery Status Click here to start and monitor a discovery. This section of the Network 

Discovery GUI is described in Discovery Status Tab on page 91. 

OQL Workbench Click here to access the Netcool/Precision IP databases using OQL commands. 

For more information, see Accessing the Precision Server Databases on page 166. 

Database Configuration Click here to configure access settings for the MySQL database . These settings 

apply both to Topoviz and to the Network Discovery GUI. 

A toolbar appears at the top of the Discovery Configuration section of the Network Discovery GUI. The 

items on this toolbar enable you to call up the Discovery Wizard and control the saving of data. The buttons 

are shown in Figure 16 and described in Table 19. 

Figure 16: Network Discovery GUI Toolbar 

Table 19: Description of Toolbar 

Item Description 

Domain 

drop-down 

list box 

Enables you to select a domain in which to configure and run your discovery. 

Calls the Discovery Wizard, which guides you through the discovery configuration process using the 

discovery configuration windows in series. 

Saves all changes on screen. 

Resets any unsaved changes and displays original configuration. 

Calls online help on the Network Discovery GUI. 




The Network Discovery GUI uses a series of tabs to help you step through the configuration of a discovery. 

Figure 17 shows these tabs. Table 20 describes the features you can find under each tab. 

Figure 17: Tabs In The Configuration Section of the Network Discovery GUI 

Table 20: Description of Tabs 

Tab Description 

Scope Define zones in the network to be included in or excluded from discovery. For more information, see 

Scoping the Discovery on page 97. 

Seed Define the starting points from which to look for devices. For more information, see Seeding the Discovery 

on page 100. 

Sniffer and 

Trap 

Define dynamic finders that provide alternative starting points for the discovery by identifying IP 

addresses embedded within data traffic. For more information, see Configuring the Dynamic Finders on 

page 106 

Passwords SNMP and Telnet communication protocol parameters that enable Netcool/Precision IP to investigate 

devices that use these communication protocols. For more information, see Setting SNMP and Telnet 

Passwords on page 111. 

Device 

Support 

Define the discovery agents to be used to investigate device connectivity. For more information, see 

Enabling and Disabling Discovery Agents on page 118. 

Filters Define filters that enable you to filter out devices either prior to discovery or following discovery. For more 

information, see Setting Discovery Filters on page 120. 

DNS Specify access to DNS services that enable the discovery to perform domain name lookups. For more 

information, see Configuring DNS Helpers on page 127. 

NAT Specify Network Address Translation (NAT) data. NAT data provides discovery mappings between address 

space data and real device IP addresses and thereby facilitates further discovery. For more information, 

see Configuring NAT Support on page 130. 

Advanced Define advanced settings that govern features of the discovery such as concurrent processes and 

time-outs. For more information, see Setting Advanced Discovery Parameters on page 133. 

89


90 

Much of the configuration data in the Network Discovery GUI is presented in tables. An example, the 

Scoping Table, is shown in Figure 18. In these cases, a set of buttons appears above the table. These buttons 

enable you to enter data into the table, edit and delete data. These buttons are described in Table 21 Buttons 

For Manipulating Data in the Table on page 90. 

Figure 18: Table From the Network Discovery GUI 

Table 21: Buttons For Manipulating Data in the Table 

Button or 

Check Box 

Description 

Select All button. Selects all the rows in the table and displays a check in each of the Select check boxes. 

Deselect All button. Deselects any selected rows and removes the check from each of the Select check 

boxes. 

Delete button. Deletes the selected rows. 

New button. Calls up a window where you can specify values for the new row to add to the table. 

Select check box. Click this check box to select the corresponding row. Click a selected check box to 

deselect the corresponding row. 


Discovery Status Tab 

Figure 19 shows the Precision Admin page with the Discovery Status tab open. 

Figure 19: Precision Admin Page Showing Discovery Status Information 



A set of buttons appears at the top of the Status and Control section. These buttons enable you to start and 

stop a discovery or force a rediscovery, either full or partial. You can also refresh the data on discovered 

devices. The buttons are shown in Figure 20 and described in Table 22. 

Figure 20: Main Button Bar – Discovery Status 

91


92 

Table 22: Description of Main Button Bar – Discovery Status 

Button or Widget Description 

Domain drop-down 

list box 

Enables you to select a domain in which to run your discovery. 

Start Discovery button: starts the discovery (or rediscovery) of the type specified in the 

Discovery Type drop-down list box. Uses the values specified in the Configuration section of 

the Network Discovery GUI to perform this discovery. This button may be active (green) or 

inactive (gray). 

If the button is active, then no discovery is currently running. You can click the button to 

start a discovery. 

If the button is inactive (gray), then a discovery is currently running. 

If the CTRL process is not running in the domain you selected, then clicking on this button 

generates a warning that prompts you to check that CTRL is running in this domain. 

Stop Discovery button: stops a currently running discovery (or rediscovery). This button may be 

active (red) or inactive (gray). 

If the button is active, then a discovery is currently running. You can click the button to stop 

the discovery. 

If the button is inactive (gray), then no discovery is currently running. 

Discovery Type buttons: select the type of discovery to run using the following buttons: 

Full Rediscovery (left button) 

Partial Rediscovery (right button) 

For more information on these options, see Starting and Monitoring a Discovery on page 138. 

These buttons are inactive if no discovery is currently running. 

Discovery Settings button: click here to change the runtime settings for the DISCO and the 

Helper Server processes. Clicking this button calls up the Discovery Settings window, as shown in 

Discovery Settings Window on page 93. 

Note: These settings are of interest only if you are troubleshooting the DISCO or Helper Server 

processes. 

Refresh button: works in conjunction with the Discovered Devices tab. Refreshes the list of 

discovered devices so that the display area lists the latest devices discovered. Also refreshes the 

status data under the other tabs. 

This button is inactive if no discovery is currently running. 


Discovery Settings Window 



You access this window by clicking the Discovery Settings button in the Discovery Status button bar. Use 

this window to change the runtime settings for the DISCO and the Helper Server processes, as shown in 

Figure 21. Table 23 describes each of the fields in this window. These settings are saved to the 

ncp.ctrlServiceData table in the MySQL database. This table is created the first time that you press 

the Save button within this window. 

Note: These settings are of interest only if you are troubleshooting the DISCO or Helper Server processes. 

Figure 21: Discovery Settings Window 

Table 23: Discovery Settings 

Property Meaning 

Debug Level Specify a debugging level for troubleshooting this process (Helper Server or 

DISCO). 

Latency The maximum time in milliseconds (ms) that this process waits to connect to 

another Precision Server process using the messaging bus. This option is useful 

for large and busy networks where the default settings can cause processes to 

assume that there is a problem when in fact the communication delay is a result 

of network traffic. 

Retry Count The number of times that CTRL tries to restart this process before giving up. 

Log Filename Name of the log file to which to write messages from this process. 

93


94 

The Discovery Status pane contains a series of tabs to group the different types of information you can 

monitor. Figure 22 shows these tabs. Table 24 describes the features you can find under each tab. 

Figure 22: Tabs In The Status and Control Section of the Network Discovery GUI 

Table 24: Description of Status Tabs (1 of 2) 


Discovery 

Details 


Details: 

Overview 

section 


Details: Ping 

Finder 

Progress 

section 

Displays two sections that provide information on an overview of the progress of the discovery, 

containing the following information: 

The Overview section contains the following information: 

Discovery Phase: Indicates the phase of discovery currently in progress. For more information on the 

discovery phases, see Discovery Stages and Phases on page 35. 

Processed IP Addresses: Indicates how many IP addresses have been discovered to this point. 

Processed Names: Indicates how many domain names have been discovered to this point. 

Processed Sub-Nets: Indicates how many subnets have been discovered to this point. 

VLANs: Indicates how many VLANs have been discovered to this point. 

Cisco Frame Relay: Indicates how many Cisco Frame Relay devices have been discovered to this 

point. 

Frame Relay: Indicates how many Frame Relay devices have been discovered to this point. 

PNNI Peer Group: Indicates how many Private Network Node Interface (PNNI) devices have been 

discovered to this point. 

HSRP: Indicates how many Hot Standby Router Protocol (HSRP) devices have been discovered to this 

point. 

FDDI: Indicates how many Fibre Distributed Data Interface (FDDI) nodes have been discovered to this 

point. 

The Ping Finder Progress section contains the following information: 

IP/Subnet: A list of IPs and subnets discovered to this point. 

Netmask: For each subnet, this column indicates the netmask value. 

Current Address: The current address being processed. 

Status: Indicates whether the Ping finder is still pinging this device or subnet or whether it has 

completed pinging. 

These values are automatically refreshed every 10 seconds. 


Table 24: Description of Status Tabs (2 of 2) 



Tables 

Discovered 

Devices 


The following information is displayed for each discovery agent: 

Agent: The agents running in the current discovery. 

Queue: Indicates the current status of each discovery agent. 

These values are automatically refreshed every 10 seconds. 


This is a list of all devices discovered to this point. The following information is displayed for each device: 

Entity Name: The unique name of this entity on the network. 

IP Address: The unique IP address of this network entity. 

Once the discovery has reached an advanced stage, this window displays a large number of devices. You 

can filter these devices by creating and applying a filter, using the Filter option. 

This information is not automatically refreshed, as this would take up a lot of system memory resources. 

To refresh this information, click the Refresh button. 

The Refresh button appears in the main button bar at the top of the Discovery Status Details area. 

For more information on the Refresh button, see Table 22 Description of Main Button Bar – Discovery 

Status on page 92. 

95


4.2 Configuring a Discovery 

96 

Configuring a discovery using the Network Discovery GUI provides the ability to set a base set of parameters 

that govern how the discovery is performed. These parameters are the following: 

The areas of the network to be included in or excluded from the discovery process. This definition of 

network space is known as the scope of the discovery. For more information on how to scope the 

discovery using the Network Discovery GUI, see Scoping the Discovery on page 97. 

The location from which to begin discovering devices. This may be one or more IP or subnet 

addresses. This starting point is known as the seed of the discovery. For more information on how to 

seed the discovery using the Network Discovery GUI, see Seeding the Discovery on page 100. 

Dynamic finders, such as the Sniffer and Trap finders, which provide alternative starting points for 

the discovery by identifying IP addresses embedded within data traffic. For more information on 

configuring dynamic finders using the Network Discovery GUI, see Configuring the Dynamic Finders 

on page 106. 

SNMP and Telnet communication protocol parameters that enable Netcool/Precision IP to 

interrogate devices that use these communication protocols. For more information on setting SNMP 

and Telnet parameters using the Network Discovery GUI, see Setting SNMP and Telnet Passwords on 

page 111. 

The discovery agents to be used to investigate device connectivity. Depending on the type of 

discovery that you are performing (for example, Layer 2 or Layer 3), the Network Discovery GUI 

assists you in choosing the discovery agents you need. These agents vary because connectivity 

information varies with the technology of the hardware in the network. For more information on 

setting discovery agents using the Network Discovery GUI, see Enabling and Disabling Discovery 

Agents on page 118. 

Filters that enable you to filter out devices either prior to discovery or following discovery. 

Pre-discovery filters prevent discovered devices from being polled for connectivity information. Post 

discovery devices prevent discovered devices from being passed to MODEL. You may filter out 

devices based on a variety of criteria, including location, technology, and manufacturer. For more 

information on setting pre- and post-discovery filters using the Network Discovery GUI, see Setting 

Discovery Filters on page 120. 

Access to DNS services that enable the discovery to perform domain name lookups. For information 

on configuring DNS services for the discovery, see Configuring DNS Helpers on page 127. 



Configuring a Discovery 

Network Address Translation (NAT) data provides the discovery mappings between address space 

data and real device IP addresses and thereby facilitates further discovery. For information on 

configuring NAT support for the discovery, see Configuring NAT Support on page 130. 

Advanced settings that govern features of the discovery such as concurrent processes and time-outs. 

You can use these parameters to increase the speed of the discovery but you need to balance this with 

the load on the server. Generally a faster discovery involves a heavier load on the server in terms of 

memory usage. You should only modify the advanced settings if you are an advanced 

Netcool/Precision IP user. For information on configuring advanced settings for the discovery, see 

Setting Advanced Discovery Parameters on page 133. 

To configure a discovery, you complete a series of tabbed forms with values for some or all of these 

parameters. You may find data in some of these tabbed screens. This is data specified in earlier configurations 

and held in the relevant discovery configuration file. 

Note: When you configure a discovery using the Network Discovery GUI, the minimum amount of 

information that you must specify is one seed device and the correct SNMP community strings for the 

network to be discovered. 

Scoping the Discovery 

You can use the Scope tab within the Network Discovery GUI to to define zones of the network (that is, 

subnet ranges) that are to be included in or excluded from the discovery. You can define as many zones as 

necessary. 

97


98 

Adding a New Scope Zone 

To add a new zone: 

1. In the Network Discovery GUI, ensure that the Scope tab is selected within the Configuration 

option. 

Figure 23: Scope Tab 

The information that you specify in the form under the Scope tab is saved to the 

DiscoScope.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the name of the 

discovery domain, for example NCOMS. You can find more information on the purpose and function 

of the DiscoScope.cfg schema file in Introduction to Scope on page 208. 




2. Click the New button. 

The Scope window appears where you can enter the subnet and netmask bits (if applicable) for the 

zone in the relevant fields. You also have the option of entering a subnet using a wildcard. The Scope 

window is shown in Figure 24. 

Figure 24: Scope Window With Sample Zone Data 

3. Indicate whether the zone is to be included or excluded from the discovery by selecting the Include or 

the Exclude check box. If the zone is an inclusion zone, you can also indicate whether you wish to 

ping the zone during the discovery. By checking the box Add to ping seed list you add the entity or 

subnet to the ping seed list. For more information on seeding the Ping finder, see Seeding the Ping 

Finder on page 100. 

4. If you are performing NAT address mapping, then map this scope zone to a NAT address space. 

Specify the NAT address space in the Address Space field. Values for NAT addresses are set in the 

translations.NATAddressSpaceIds table. 

Note: The Address Space field appears if the NAT tab has the Enable Network Address Translation 

(NAT) Support tab selected, as described in Activating and Deactivating Network Address Translation 

on page 132. 

5. Click OK to confirm your settings. 

6. Click the Save button to save your settings. 

99


100 

Editing an Existing Scope Zone 

To edit an existing scope zone: 

1. Click on the hyperlink row in the Scope Zones table corresponding to the scope zone that you wish to 

modify. The Scope dialog appears containing the data for the scope zone that you selected. 

2. Modify the scope zone data as desired. 

3. Click OK to confirm your settings. 


Deleting Scope Zones 

To delete one or more scope zones: 

1. Select one or more rows from the Scope Zones table by clicking the Select check box or check boxes 

in the relevant rows. Click the Select All button to select all the rows in the Scope Zones table. 

2. Click the Delete button to delete the row or rows that you selected. 


Seeding the Discovery 

If you wish to run the Ping and File finders you must seed them with the starting points from which to look 

for devices. In the case of the Ping finder, you must specify one or more IP addresses and/or subnets to ping 

to determine if the devices exist. In the case of the File finder, you must specify a file that is likely to contain 

IP addresses for your network. You would usually parse a structured system file such as /etc/hosts. 

You can seed a discovery using both the Ping finder and the File finder simultaneously. In addition to these 

two finders that require you to provide the seed addresses, you can also seed the discovery using two dynamic 

finders, the Sniffer and Trap finders, which provide alternative starting points for the discovery by 

identifying IP addresses embedded within data traffic. For more information on the Sniffer and Trap 

finders, see Configuring the Dynamic Finders on page 106. 

Seeding the Ping Finder 

You 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 or not to activate 

the Ping finder for the discovery. 


To seed the Ping finder: 

1. In the Network Discovery GUI, select the Seed tab within the Configuration option. 

Figure 25: Seed Tab 



The information that you specify in the Ping finder form under the Seed tab is saved to the 

DiscoPingFinderSeeds.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the 

name of the discovery domain, for example NCOMS. You can find more information on the purpose 

and function of the DiscoPingFinderSeeds.cfg schema file in Configuring the Ping Finder 

on page 221. 

101


102 

2. Click the New button above the Ping finder table. 

The Ping Seed window appears where you can enter an IP address or a subnet and netmask bits (if 

applicable) for the ping seed in the relevant fields. The Ping Seed window is shown in Figure 26. 

Figure 26: Ping Seed Window With Sample Ping Seed Data 

3. In the Timeout field, specify the maximum time to wait for a reply from a pinged address. 

4. In the Retries field, specify the number of times a device is to be repinged. 

5. Click OK to confirm your settings. The new ping seed you defined appears as a hyperlink in the Ping 

finder table. 

6. Click the New button to define more seeds for the Ping finder. 


Activating and Deactivating the Ping Finder 

To activate the Ping finder: 

1. Select the Use Ping Finder in Discovery check box. 

Figure 27: Use Ping Finder in Discovery Check Box (Selected) 



To deactivate the Ping finder: 

1. Deselect the Use Ping Finder in Discovery check box. 

Figure 28: Use Ping Finder in Discovery Check Box (Deselected) 


Seeding the File Finder 



You seed the File finder with a text file on the Netcool/Precision IP host machine 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. For more information on the structure of this seed file, see Files to Parse and Rules for 

Parsing on page 229. 

Note: You usually use a file that already exists on the Netcool/Precision IP host machine. However, if you 

wish to create a new file to hold the seeds then you need to have write permissions for the directory where 

you wish to write the file. 

You can specify files containing seeds for the File finder and save these file settings. You can separately decide 

whether or not to activate the File finder for the discovery. 

103


104 

To seed the File finder: 

1. In the Network Discovery GUI, select the Seed tab within the Configuration option. 

Figure 29: Seed Tab 

The information that you specify in the File finder form under the Seed tab is saved to the 

DiscoFileFinderParseRules.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME 

is the name of the discovery domain, for example NCOMS. You can find more information on the 

purpose and function of the DiscoFileFinderParseRules.cfg schema file in Configuring 

the File Finder on page 228. 




2. Click the New button above the File finder table. 

The File Seed window appears where you can enter the path to a file containing seeds. The File Seed 

window is shown in Figure 30. 

Figure 30: File Seed Window With Sample File Seed Data 

3. In the Filename field, specify the path to the file on the Netcool/Precision IP host machine that 

contains seed data. This file must be a structured text file that contains the seeds in the form of IP 

addresses and device names in columns. 

4. Specify the column delimiter in this file by typing the the delimiter in the Delimiter field. You can 

use regular expressions to complete this field. 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 

Delimiter field. 

5. In the Name Column field, specify the column within this file that contains the device names of seed 

devices. Note that a default value of 0 appears in this field. You must change this to the non-zero 

value corresponding to the column number within this file that contains the device names. 

6. In the IP Column field, specify the column within this file that contains the IP addresses of seed 

devices. Note that a default value of 0 appears in this field. You must change this to the non-zero 

value corresponding to the column number within this file that contains the IP addresses. 

7. Click OK to confirm your settings. The new file seed you defined appears as a hyperlink in the File 

finder table. 

8. Click the New button to define more seeds for the File finder. 


105


106 

Activating and Deactivating the File Finder 

To activate the File finder: 

1. Select the Use File Finder in Discovery check box. 

Figure 31: Use File Finder in Discovery Check Box (Selected) 


To deactivate the File finder: 

1. Deselect the Use File Finder in Discovery check box. 

Figure 32: Use File Finder in Discovery Check Box (Deselected) 


Configuring the Dynamic Finders 

Sniffer and Trap finders are the dynamic finders, which you can configure. These finders provide alternative 

starting points for the discovery by identifying IP addresses embedded within data traffic. You can configure 

multiple Sniffer finders and multiple Trap finders. 

Configuring the Sniffer Finder 

The Sniffer finder listens to interfaces on the Netcool/Precision IP host machine. You can specify which 

interfaces the Sniffer finder should listen to. The Sniffer finder captures and analyses packets sent and 

received on these interfaces and extracts the IP addresses of the receiving devices (if the packet is being sent) 

or the IP addresses of the sending devices (if the packet is being received). The discovery process then uses 

these IP addresses as seed devices. 

The Sniffer finder captures a fixed number of packets before control is passed back to the discovery program. 

You can define the number of packets to be captured. 

Once you have saved your Sniffer finder settings, you can decide separately whether or not to activate the 

Sniffer finder for the discovery. 


To configure the Sniffer finder: 



1. In the Network Discovery GUI, select the Sniffer & Trap tab within the Configuration option. 

Figure 33: Sniffer and Trap Tab 

The information that you specify under the Sniffer & Trap tab is saved to the 

DiscoSnifferFinderSchema.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is 

the name of the discovery domain, for example NCOMS. You can find more information on the 

purpose and function of the DiscoSnifferFinderSchema.cfg schema file in Configuring 

the Sniffer Finder on page 234. 

107


108 

2. Click the New... button to the right of the Interfaces: list box. The New Interface window appears 

where you can enter the name of an interface on the Netcool/Precision IP host machine that the 

Sniffer finder should listen to for packets. The New Interface window is shown in Figure 34. 

Figure 34: New Interface Window 

3. In the Interface field, specify the path to the name of an interface on the Netcool/Precision IP host 

machine that the Sniffer finder should listen to for packets. 

4. Click OK to confirm your settings. The interface you defined appears in the Interfaces: field. 

5. Specify a value for Loop Times. This value specifies the number of packets to be captured per cycle 

before passing control back to the discovery program. 

Note: Although capturing more packets may be desirable, it impairs the system response time. This 

manifests itself as a small delay when the process is terminated. The larger the number of packets, the 

longer this delay. 


Activating and Deactivating the Sniffer Finder 

To activate the Sniffer finder: 

1. Select the Use Sniffer Finder in Discovery check box. 

Figure 35: Use Sniffer Finder in Discovery Check Box (Selected) 



To deactivate the Sniffer finder: 

1. Deselect the Use Sniffer Finder in Discovery check box. 

Figure 36: Use Sniffer Finder in Discovery Check Box (Deselected) 


Configuring the Trap Finder 



The Trap finder listens to SNMP traps received or sent through a specific port on the Netcool/Precision IP 

host machine. You can specify the port that the Trap finder should listen on. The Trap finder captures and 

analyses traps on this port and extracts IP addresses either from the IP header of the trap or from the payload. 

Once you have saved your Trap finder settings, you can decide separately whether or not to activate the Trap 

finder for the discovery. 

109


110 

To configure the Trap finder: 

1. In the Network Discovery GUI, select the Sniffer & Trap tab within the Configuration option. 

Figure 37: Sniffer and Trap Tab 

The information that you specify in the Trap finder form under the Sniffer & Trap tab is saved to 

the DiscoTrapFinderSchema.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is 

the name of the discovery domain, for example NCOMS. You can find more information on the 

purpose and function of the DiscoTrapFinderSchema.cfg schema file in Configuring the 

Trap Finder on page 236. 

2. Select whether to retrieve IP address from the payload or from the trap packet header. 

– Select Payload if the IP address in the trap packet header is not the actual IP address. 

– Select Trap Packet Header ifthe IP address is defined directly in the header. 

3. Specify the Trap Port. By default this is port 162. 



Activating and Deactivating the Trap Finder 

To activate the Trap finder: 

1. Select the Use Trap Finder in Discovery check box. 

Figure 38: Use Trap Finder in Discovery Check Box (Selected) 


To deactivate the Trap finder: 

1. Deselect the Use Trap Finder in Discovery check box. 

Figure 39: Use Trap Finder in Discovery Check Box (Deselected) 


Setting SNMP and Telnet Passwords 



You need to specify SNMP and Telnet access information in order to enable helpers and polling agents to 

access devices on your network. In order for the SNMP helper and Polling agents to be able to access devices 

on your network you must specify SNMP passwords as part of the discovery configuration. In order for the 

Telnet helper and the discovery agents that use Telnet to be able to access devices on your network and 

maintain a dialog with those devices, you must enter the relevant device prompts, login ID and password as 

part of the discovery configuration. 

Setting SNMP Passwords 

You use the Passwords tab within the Network Discovery GUI to define different SNMP communities and 

passwords for each of those communities. By storing the community strings and passwords for these 

communities, you allow discovery to proceed faster as the SNMP access parameters are already known. 

111


112 

To Set SNMP Passwords: 

1. In the Network Discovery GUI, ensure that the Passwords tab is selected within the Configuration 

option. 

Figure 40: Passwords Tab 

The SNMP information that you specify under the Passwords tab is saved to the 

SnmpStackSecurityInfo.cfg schema file. You can find more information on the purpose 

and function of the SnmpStackSecurityInfo.cfg schema file in Configuring the Device 

SNMP Access Parameters on page 187. 




2. Click the New button above the SNMP Passwords table. The SNMP Password window appears 

where you can specify address-specific, network-specific or global SNMP community strings, and 

supply passwords for these community strings. The SNMP Password window is shown in Figure 41. 

Figure 41: SNMP Password Window With Sample Community String Data 

3. Specify a name for the SNMP community string in the Community String field. 

4. Specify whether the community string is address specific, subnet specific or global. 

– If the string is global, then select the Globally (applies to all devices) check box. 

– If the string is subnet specific, then select the Subnet check box and specify a subnet in the 

appropriate fields. 

– If the string is address-specific, then select the IP Address check box and specify an IP address. 

113


114 

5. Specify the SNMP version for this SNMP community. Select V1, V2 or V3. If the SNMP 

community uses SNMP V3, then enter the Security Name and click in the drop-down list box to 

select one of the following options: 

– noAuthNoPriv–for SNMP communities that have no authentication or private key. In this case 

there is no need to specify any passwords. 

– AuthNoPriv–for SNMP communities that have an authentication key but no private key. Now 

specify a password in the Auth Password field. 

– AuthPriv–for SNMP communities that have both an authentication and a private key. Now 

specify passwords in the Auth Password and Private Password fields. 

6. Click OK to confirm your settings. The community string you defined appears as a hyperlink in the 

SNMP Passwords table. 


Setting Telnet Access Information 

Under the Passwords tab you can also define the relevant device prompts, login ID and password to enable 

the Telnet helper and the discovery agents that use Telnet to be able to access devices on your network and 

maintain a dialog with those devices. 


To Set Telnet Access Information: 



1. In the Network Discovery GUI, ensure that the Passwords tab is selected within the Configuration 

option. 

Figure 42: Passwords Tab 

The Telnet password information that you specify under the Passwords tab is saved to the 

TelnetStackPasswords.cfg schema file. You can find more information on the purpose 

and function of the TelnetStackPasswords.cfg schema file in Configuring Telnet Device 

Access on page 303. 

115


116 

2. Click the New button above the Telnet Passwords table. The Telnet Password window appears where 

you can specify prompts, login ID and password for a set of Telnet-accessible devices. You can specify 

these prompts, login ID and passwords for a single device, for all devices on a subnet or globally for all 

Telnet-accessible devices. The Telnet Password window, with default settings, is shown in Figure 43. 

Figure 43: Telnet Password Window With Sample Data 

3. Specify whether the prompt. login ID and password data is address specific, network specific or 

global. 

– If the data applies globally, then select the Globally (applies to all devices) check box. 

– If the string applies to a single device, then select the IP Address check box and specify an IP 

address. 

– If the string applies to all devices on a given subnet, then select the Subnet check box and 

specify a subnet in the appropriate fields. 

4. Type the prompt that the system presents at login in the Username Prompt field. You can use a 

regular expression here if you do not know the exact format of the prompt. A default value is 

provided. 

5. Type the login ID in the Username field. 




6. Type the prompt that the system presents when it requests the password at login in the Password 

Prompt field. You can use a regular expression here if you do not know the exact format of the 

prompt. A default value is provided. 

7. Type the password in the Password field. 

8. Type the prompt that the system presents once you have logged in in the Console Prompt field. You 

can use a regular expression here if you do not know the exact format of the prompt. A default value 

is provided. 

9. Specify a timeout in seconds in the Timeout field. This is the amount of time that the discovery waits 

for a response from the device before registering a timeout against this attempted Telnet access. If the 

Telnet access data is set against a subnet or globally, then this timeout applies to every attempt at 

access on the specified network. 

10. Set Use SSH to configure the Telnet Helper to use the Secure Shell (SSH) program. SSH enables 

authentication and provides more secure communications over the network. For more information, 

see Configuring Telnet Device Access on page 303. 

11. Click Advanced if you wish to set Telnet privileged access mode 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 only 

allows execution of basic commands, such as those that show the status of the system. This is a safety 

feature to prevent the discovery making any device configuration modifications without an explicit 

change to privileged mode. 

If you click Advanced, the Telnet Privileged Access Mode Properties window appears. 

Figure 44: Telnet Privileged Access Mode Properties Window 

117


118 

12. In the Command field, specify the command to enter privileged access mode. This is usually 

enable. 

13. Type the prompt that the system presents when it requests the password at login in the Password 

Prompt field. You can use a regular expression here if you do not know the exact format of the 

prompt. A default value is provided. 

14. Type the privileged mode password in the Password field. 

15. Type the prompt that the system presents once you have logged in in the Console Prompt field. You 

can use a regular expression here if you do not know the exact format of the prompt. A default value 

is provided. 

16. In the Commands requiring mode list, specify the commands that you wish to make accessible from 

privileged mode. Click the New… button to specify new commands. 

The commands that Netcool/Precision IP uses that require enable mode are: 

– show run 

– show mac-address-table 

– show ip nat translation 

None of these commands actually change the configuration of the device; however, these commands 

only work in enable mode. 

17. Click OK to confirm your settings. You return to the Telnet Password window. 

18. In the Telnet Password window, click OK to confirm your settings. The Telnet access data you 

defined appears as a hyperlink in the SNMP Passwords table. 


Enabling and Disabling Discovery Agents 

You must enable the appropriate agents for the discovery you wish to perform. You use the Device Support 

tab within the Network Discovery GUI to define the agents to run during the discovery. This section of the 

GUI shows all the agents that are available for a discovery and provides a succinct description of each agent. 

For more information about the agents that must be run for a specific type of discovery, see Selecting Agents 

To Run on page 267. 


Enabling Discovery Agents 

To enable discovery agents: 



1. In the Network Discovery GUI, select the Device Support tab within the Configuration option. 

Figure 45: Device Support Tab 

The Agents list shows all the discovery agents that are available for your discovery. If you highlight an 

agent by clicking on it, a description of the function of that agent appears in the box to the right. 

The information that you specify in the form under the Device Support tab is saved to the 

DiscoAgents.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the name of the 


of the DiscoAgents.cfg schema file in Activating the Discovery Agents on page 184. 

119


120 

2. Choose agents for your discovery by selecting the appropriate check boxes. 

– Select Full Layer 2 and Layer 3 Discovery to select all the agents necessary for a full layer 2 and 

layer 3 discovery. 

– Select an agent type check box to enable a group of agents for a specific type of discovery. 

Individual agents may be disabled individually. 

– Select a single agent to activate that agent for the discovery. 


If you choose a combination of agents that is not advised or that may result in an inefficient discovery, a 

warning box is displayed giving you the opportunity to alter your configuration before proceeding. The 

options provided in this window vary as follows: 

If you select an agent that should be run in conjunction with another agent(s), a warning box is 

displayed indicating that these other agent(s) will be selected as applicable. Click OK to select the 

recommended agent(s). Click Cancel to cancel the selection of these agents. 

Alternatively, if you select an agent that should not be run in conjunction with another agent(s), a 

warning box is displayed indicating that these other agent(s) will be automatically deselected. Click 

OK to deselect the recommended agent(s). Click Cancel to cancel the deselection of these agents. 

Figure 46 provides an example of a window with a warning about an inadvisable combination of agents. 

Figure 46: Warning About Poor Combination of Agents 

Setting Discovery Filters 

Once you have defined the scope of your discovery using the Scope tab, it is possible to restrict the scope 

using filters. For example, you may wish 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 define a pre-discovery or post-discovery filter. For more information on 

defining the scope of a discovery, see Scoping the Discovery on page 97. 




By default, the discovery filters do not filter out the Netcool/Precision IP host machine. This is because this 

machine usually also serves as the polling station for root cause analysis. In order for root cause analysis to 

work correctly, the polling station, and hence the Netcool/Precision IP host machine, must be part of the 

topology. For more information on root cause analysis, see the Netcool/Precision IP Monitoring and RCA 

Guide. 

If you do need to filter out the Netcool/Precision IP host machine, then you need to modify the following 

stitchers and remove the sections of code indicated by comments that prevent the Netcool/Precision IP host 

machine from being filtered. The stitchers are DetectionFilter.stch and 

InstantiationFilter.stch. For more information on these stitchers, see Appendix C: Stitchers 

and Stitcher Language on page 517. 

Pre-Discovery Filter 

A pre-discovery filter restricts device discovery. If this type of filter is defined as part of the discovery 

configuration, then only devices matching this filter are fully discovered. If no pre-discovery filter is defined 

then all devices within the scope are discovered. 

The test defined by the pre-discovery filter uses the columns of the Details.returns database table. 

For details of the discovery databases, see The Discovery Databases on page 423. 

Although you can configure the filter condition to test against any of the columns in the 

Details.returns table, you may need to use the IP address (m_UniqueAddress) 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. 

You can define multiple pre-discovery filters. Filters are combined automatically using a Boolean AND 

expression. All criteria defined in all filters must be matched. For more information on defining a filter, see 

Creating and Editing Filters on page 123. 

Post-Discovery Filter 

A post-discovery filter restricts device instantiation. If a post-discovery filter is defined for the discovery, only 

devices that pass the criteria are instantiated, that is, sent to MODEL. If no post-discovery filter is defined, 

then all discovered devices are sent to MODEL. For more information on the steps involved in the creation 

of the full topology and the transfer of this topology to MODEL, see Creating the Topology on page 31. 

You can define multiple post-discovery filters. Filters are combined automatically using a Boolean AND 

expression. All criteria defined in all filters must be matched. For more information on defining a filter, see 

Creating and Editing Filters on page 123. 

121


122 

The post-discovery filter operates on the scratchTopology.entityByName table. This means that 

the fields available in this filter are different from those available to the pre-discovery filter. The 

post-discovery filter operates on topology fields as opposed to basic device information. For more 

information on the the topology fields in the scratchTopology database, see The scratchTopology 

Database Schema on page 471. 

Selecting Pre-Discovery Filters 

To select a pre-discovery filter for use in your discovery: 

1. In the Network Discovery GUI, select the Filters tab within the Configuration option. 

Figure 47: Filters Tab 

2. In the Pre-Discovery Filter section of the window, select a filter from the Available Filters list box. 

3. Click the Add >> button. 



Selecting Post-Discovery Filters 

To select a post-discovery filter for use in your discovery: 



1. In the Post-Discovery Filter section of the window, select a filter from the Available Filters list box. 

2. Click the Add Filter button. 


Creating and Editing Filters 

The procedure for creating and editing filters is very similar. The fields available for pre-discovery and 

post-discovery filters vary. To create a new filter or edit an existing filter: 

1. Click the Filter Library button either within the Pre-Discovery Filter section or the Post-Discovery 

Filter section of the window. The Filter Library window appears. 

2. Click Add Filter to create a new filter. Alternatively, select a filter from the list on the left to edit it. A 

filter definition area appears where you can define a new filter or edit an existing filter, as shown in 

Figure 48. 

Figure 48: Editing a Filter 

3. Click the Add Filter... button to create a new filter or select an existing filter from the list to edit the 

filter. 

1 

2 

4. If you are creating a new filter then specify the name of the new filter in the Name field. 

123


124 

5. A filter is made up of one or more filter conditions. An example of a filter condition for a 

pre-discovery filter is: 

m_ObjectId not like 1\.3\.6\.1\.4\.1\.2\.3\.1\. 

Add or delete filter conditions as follows: 

– To add a new row for a filter condition, click the New button, labeled item 1 in Figure 48 on 

page 123. 

– To delete an existing filter condition row, click the Delete button, labeled item 2 in Figure 48 

on page 123. 

You can link these filter conditions to create a filter using an AND (All) or an OR (Any) Boolean 

operator. 

– Click the Basic tab to construct the filter using drop-down list boxes. Once you have saved the 

filter using the Save button under the Basic tab, you can see what the filter looks like in OQL 

by clicking on the Advanced tab. For more information on OQL syntax, see Appendix B: The 

Object Query Language on page 479. 

– Advanced users should click the Advanced tab and write the filter directly in the text box 

provided using OQL. Figure 49 shows an example of a filter defined using OQL under the 

Advanced tab. 

Figure 49: Filter Defined in OQL Under the Advanced Tab 


6. Specify whether to apply an All or Any relationship to the filter conditions: 



– Click All to specify that only devices that match all of the filter conditions should pass the filter. 

– Click Any to specify that devices that match any one of the filter conditions should pass the 

filter. 

7. Construct or modify a filter condition for your filter using the Field, Comparator and Value fields, as 

described in the following steps. 

8. Click on the Field drop-down list box and select a field to filter by. 

When constructing a pre-discovery filter, you can filter based on any of the fields in the 

Details.returns table. These fields are as follows: 

– m_Name 

– m_UniqueAddress 

– m_Protocol 

– m_ObjectId 

– m_Description 

– m_HaveAccess 

– m_UpdAgent 

– m_AddressSpace 

In addition, using the Advanced tab, you can construct filter rows using any of the fields from within 

the m_ExtraInfo field. 

For more information on the Details.returns table, see The returns Table on page 458. 

When constucting a post-discovery filter, you can filter based on any of the fields in the 

scratchTopology.entityByName table. These fields are as follows: 

– m_Name 

– m_Description 

– m_Type 

– m_ObjectId 

125


126 

– m_State 

– m_HaveAccess 

In addition, using the Advanced tab, you can construct filter rows using m_Addresses, 

m_Contains, m_UpwardConnections, m_RelatedTo, and any of the fields from within 

the m_ExtraInfo field. 

For more information on the scratchTopology.entityByName table, see The 

entityByName Table on page 471. 

9. Click on the Comparator drop-down list box and select an operator for your filter from the list box. 

For all fields, whether of type Text or Numerical, you can select any of the following operators: 

– = 

– 

– > 

– >= 

– < 

–



12. When you have defined all the lines of your filter, click Save. If a new filter has been created, the 

name of the filter you defined now appears in the list box on the left. 

13. Click Close to close the window. The filter you defined appears in the Available Filters list boxes for 

either the Pre-Discovery Filter or the Post-Discovery Filter sections of the window. 

Deleting a Filter 

To delete a filter: 

1. In the Filter Library window, select a filter from the list of filters on the left. 

2. Click the Delete button and confirm your choice. The filter you selected is removed from the list. 

Note: Some of the filters supplied with Netcool/Precision IP cannot be deleted. These include the end node 

and SNMP acccess pre-discovery filters. For these filters, the Delete button is disabled. 

Configuring DNS Helpers 

Helpers are specialized applications that retrieve information from and about network devices for the 

discovery agents. The DNS Helpers perform domain name resolution. You can specify one of the following 

three types of DNS Helper: 

DNS Server: a server on the network that is dedicated to performing domain name resolution. 

File: the name of a file held on the Netcool/Precision IP host machine that contains IP addresses and 

hostnames in lookup table format. 

System: the local DNS system on the Netcool/Precision IP host machine. 

You can find more information on DNS Helpers in Configuring the DNS Helper on page 290. 

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. This enables you to ensure that the most commonly accessed method is 

retrieved first. This enables a more effective use of resources during the discovery. 

Specifying DNS Helper Methods 

You can specify a number of methods to enable the DNS Helpers to perform domain name lookups. Each 

of these methods makes use of one of the three domain methods described above: DNS Server, File or 

System. 

127


128 

To specify DNS Helper methods: 

1. In the Network Discovery GUI, select the DNS tab within the Configuration option. 

Figure 50: DNS Tab 

2. Click the New button. The DNS Service Properties window appears where you can specify the details 


of the DNS Helper method. The DNS Service Properties window is shown in Figure 51. 

Figure 51: DNS Service Properties Window 

3. Specify a name for this method in the Service Name field. 



4. Indicate the type of method by selecting DNS Server, File, or System. Depending on the type of 

method you select, the parameters you need to specify vary. 

– If you selected DNS Server, then specify the IP address of this DNS server in the IP Address 

field. You also need to set a timeout for receving a response from the DNS server, using the 

Timeout field. 

– If you selected File, then type the name of the file that holds the domain lookup information in 

the Filename field. Specify the order in which this information appears in the lookup table, 

either Name then IP or IP then Name. 

– If you selected System, then in the Domain Suffix field, specify the suffix to append to each 

device name after the name is looked up. 

5. Click OK to confirm your settings. The method you specified appears as a hyperlink row within the 

DNS Helper Configuration table. 

6. Click the New button to define more methods for DNS Helpers. If you wish to change the order by 

which these methods are retrieved by the DNS Helper, then see Setting the Order of Methods for Name 

Retrieval in this section. 


129


130 

Setting the Order of Methods for Name Retrieval 

You can change the order in which the methods are retrieved by the DNS Helper. This enables you to ensure 

that the most commonly accessed method is retrieved first. This enables a more effective use of resources 

during the discovery. 

To set the order of DNS Helper methods, click on the Up or Down arrow button in the row corresponding 

to the method you wish to move up or down. 

Configuring NAT Support 

You can configure NAT translation for your discovery. You do this by mapping the address space identifier 

for a NAT domain to the IP address of the associated NAT gateway device. You can separately decide 

whether or not to activate NAT translation for the discovery. For more information on Network Address 

Translation, see Chapter 12: Managing NAT Environments on page 341. 


Configuring NAT Gateways 

To configure NAT gateways: 

1. In the Network Discovery GUI, select the NAT tab within the Configuration option. 

Figure 52: Network Address Translation Tab 



2. Click the New button. The NAT Gateway window appears where you can map the address space 

identifier for a NAT domain to the IP address of the associated NAT gateway device. The NAT 

131


132 

Gateway window is shown in Figure 53. 

Figure 53: NAT Gateway Window With Sample Data 

3. Specify the public IP address of the NAT gateway device in the IP Address field. 

4. Specify the address space identifier you wish to use for the associated NAT domain in the Address 

Space ID field. 

5. Click OK to confirm your settings. The gateway you specified appears as a hyperlink row within the 

NAT Support table. 

6. Click the New button to define more NAT gateway mappings. 


Activating and Deactivating Network Address Translation 

To activate Network Address Translation for your discovery: 

1. Select the Enable Network Address Translation (NAT) Support check box. 

Figure 54: Enable Network Address Translation (NAT) Support Check Box (Selected) 


After activating NAT, you must map the discovery scope zones to NAT address spaces, as described 

in Adding a New Scope Zone on page 98. Values for NAT addresses are set in the 



To deactivate Network Address Translation for your discovery: 

1. Deselect the Enable Network Address Translation (NAT) Support check box. 


Setting Advanced Discovery Parameters 

! 

Figure 55: Enable Network Address Translation (NAT) Support Check Box (Deselected) 



You can set advanced features for your discovery. The parameters you set here govern features such as 

concurrent processes and timeouts. You can use these parameters to increase the speed of your discovery but 

you need to balance speed considerations with the resultant load on the server. Generally, a faster discovery 

results in a heavier load on the server in terms of memory usage. 

Warning: You should only modify advanced settings for the discovery if you are an advanced user. If you 

find that your discovery does not work as expected after modifying these values then use the Reset button 

to put these settings back to their default values. 

Within the Advanced tab of the Network Discovery GUI, you configure the following advanced discovery 

options: 

Finders: you can configure advanced parameters for the File, Trap, and Sniffer Finders. 

Helpers: you can configure advanced parameters for the Ping, SNMP, Telnet, and DNS Helpers. 

Failover: you can configure failover for the discovery. 

133


! 

134 

Configuring Advanced Discovery Parameters 

To configure advanced discovery parameters: 

1. In the Network Discovery GUI, select the Advanced tab within the Configuration option. 

Figure 56: Advanced Tab 

Warning: Do not modify these values unless you understand the effect that they may have on your 

discovery. If you find that your discovery does not work as expected after modifying these values then 

use the Reset button to return these settings to their default values. 




2. To configure concurrent thread settings for the File, Trap, and Sniffer Finders, change the following 

settings: 

– Concurrent File Finders: This is the number of threads to be used by the File finder. You can 

find more information on this setting in 8.3 Configuring the File Finder on page 228. 

– Concurrent Trap Finders: This is the number of threads to be used by the Trap finder. You can 

find more information on this setting in 8.5 Configuring the Trap Finder on page 236 

– Concurrent Sniffer Finders: This is the number of threads to be used by the Sniffer finder. You 

can find more information on this setting in 8.4 Configuring the Sniffer Finder on page 234 

3. To configure advanced settings for the Ping finder, change the following settings: 

– Concurrent Ping Finders: This is the number of threads to be used by the Ping finder. 

– Default Timeout: This is the maximum time to wait for a reply from a pinged address. This 

value is expressed in milliseconds. 

– Default Number of Retries: This is the number of times a device is to be re-pinged. 

– Inter-Ping Time: This is the interval between pinging the addresses in a subnet or list. This 

value is expressed in milliseconds. 

– Allow Broadcast Pinging: This is a flag used to enable or disable broadcast address pinging. 

– Allow Multicast Pinging: This is a flag used to enable or disable multicast address pinging. 

You can find more information on these Ping finder settings in 8.2 Configuring the Ping Finder on 

page 221. 

4. To configure advanced settings for the Telnet Helper, change the following settings: 

– Concurrent Telnet Helpers: This is 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. 

– Default Timeout: This is the maximum time to wait for access to a device, expressed in 

milliseconds. 

– Number of Retries: This is the number of times to retry the device. 

You can find more information on these settings in Configuring the Telnet Helper on page 293. 

5. To configure advanced settings for the SNMP Helper, change the following settings: 

– Concurrent SNMP Helpers: This is the number of threads to be used by the helper. If you 


concurrent SNMP sessions. 

– Timeout: This is the maximum time to wait for access to a device, expressed in milliseconds. 

135


136 

– Number of Retries: This is the number of attempts to retrieve one or more SNMP variables 

from a device. 

– GetNext Slowdown: This is the delay 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. This value is expressed in milliseconds. 

– GetNext Boundary: 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. 

You can find more information on these settings in Configuring the SNMP Helper on page 292 and in 

Configuring SNMP Device Access on page 298. 

6. To configure advanced settings for the DNS Helper, change the following settings: 

– Concurrent DNS Helpers: This is the number of threads to be used by the helper. If you 


concurrent DNS sessions. 

– Default Timeout: This is the maximum time to wait for a response from a device. This value is 

expressed in milliseconds. 

You can find more information on these settings in Configuring the DNS Helper on page 290. 

7. To configure advanced generic discovery settings, change the following settings: 

– Enable VLAN Modelling: Indicate whether to model VLANs in this discovery. If you enable 

VLAN modelling, then you will be able to partition discovered topologies based on VLAN 

membership. 

– Enable SysName Naming: Set this option to instruct the system 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. You can find more 

information on this setting in The config Table on page 431. 

– Enable Discovery Failover: If you enable discovery failover, then data is cached during the 

discovery process to enable data recovery in the event that DISCO fails. A discovery running in 

failover mode is slower than a standard discovery, because failover recovery involves storing data 

on the disk throughout the discovery process. You can find more information on this setting in 

Failover Recovery on page 426. 


! 



Note: DISCO failover recovery is not to be confused with agent and finder failover recovery, 

which are configured directly from the disco.config database. If selected, agent and finder 

failover recovery operate regardless of whether DISCO failover recovery is implemented. DISCO 

failover is also entirely separate from Netcool/Precision IP failover. For more information on 

Netcool/Precision IP failover, see the Netcool/Precision IP Installation and Deployment Guide. 

– Enable File Finder Verification: Indicate whether you wish to use the Ping finder to verify the 

existence of devices specified in the file(s) used by the File finder. You may wish to do this if you 

have reason to doubt that the devices reported by the File finder are still connected to the 

network, possibly because of a rapidly changing network. For more information, see Verifying 

the Existence of a Device Reported by the File Finder on page 232. 

– Enable Rediscovery Rebuild Layers: Indicate whether you wish to rebuild the topology layers 

following a partial rediscovery. 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. For more information, see Option to Rebuild 

Topology Layers on page 43. 

– Enable RT Based MPLS VPLN Discovery: For MPLS discoveries, indicate whether you wish 

to display provider edge devices only (RT-based MPLS discovery) or edge devices and MPLS 

core devices (LSP-based MPLS discovery). For more information, see Configuring MPLS 

Discovery Method on page 330. 

– Enable ifName/ifDescr Interface Naming: Set this option if you wish to change the default 

naming convention for discovered interfaces. For more information, see BuildInterfaceName on 

page 525. 

Warning: If you choose to change the default naming convention for discovered interfaces, you 

will need to modify the BuildInterfaceName stitcher to specify your customized naming 

convention. 


137


4.3 Starting and Monitoring a Discovery 

138 

Once you have configured the discovery, and provided CTRL is running, you can start, and, if necessary, 

stop the discovery. 

Note: If CTRL is not running, you must ensure that it is correctly configured, either by using the automatic 

configuration option from the installation process or by following the instructions in Chapter 2: Process 

Control with CTRL on page 47. You can start CTRL using the command: 

ncp_ctrl -domain NCOMS. Replace NCOMS with your domain name. 

You can perform a full discovery, a full rediscovery and a partial rediscovery. 

Full Discovery: Run a full discovery if you wish to build a topology for a network that has not been 

discovered before. 

Rediscovery: Run a rediscovery if you have already built a topology for this network but you know 

that there have been a number of changes to the network. These changes include addition of new 

devices, change in configuration of existing devices and change in connectivity relationships between 

devices. 

– Run a Full Rediscovery if you wish to rediscover your entire network. 

– Run a Partial Rediscovery if you know that the changes to your network are limited to small 

number of devices. You first need to configure scoping and seeding for the rediscovery. If the 

relationship of these devices with neighboring devices has changed, then these neighboring 

devices may also be rediscovered. If the partial rediscovery needs to discover a large amount of 

devices based on connectivity information, then DISCO initiates a full rediscovery. The 

mechanism based on which DISCO makes this decision is described in 

You can use the Network Discovery GUI to force an immediate rediscovery. However, by default, following 

discovery DISCO adopts a reactive state, ready to conduct a rediscovery when either a new device is found 

or an existing device changes. In order to find new devices at any point in the discovery, the finders must be 

active. Since the network has already been discovered, the most practical finder to deploy during rediscovery 

is the Trap finder, which listens for traps (messages that indicate a change in the state of the device). 

For more information on how to configure DISCO to adopt a reactive state following a discovery, see 

Finding New Devices on page 41. 

Note: You can also force a rediscovery by making OQL inserts into the finders.rediscovery table, 

specifying the IP address or subnet to be rediscovered. For more information, see Forcing Rediscoveries of 

Particular Devices on page 44. 


Running Discoveries and Rediscoveries 


Starting and Monitoring a Discovery 

Use the Discovery Type option menu and the Start Discovery button to launch the desired discovery or 

rediscovery. You can run a full discovery, a full rediscovery or a partial rediscovery: 

Full Discovery: Run a full discovery if you wish to build a topology for a network that has not been 

discovered before. 

Rediscovery: Run a rediscovery if you have already built a topology for this network but you know 

that there have been a number of changes to the network. These changes include addition of new 

devices, change in configuration of existing devices and change in connectivity relationships between 

devices. 

– Run a Full Rediscovery if you wish to rediscover your entire network. 

– Run a Partial Rediscovery if you know that the changes to your network are limited to a small 

number of devices. 

Running a Full Discovery 

To run a full discovery: 

1. First configure your discovery as described in Configuring a Discovery on page 96. 

2. Within the Precision Admin page, click the Discovery Status tab. 

3. Click the Start Discovery button to launch the discovery. 

As the discovery runs, status information is displayed under the Discovery Details, Discovery 

Details, and Discovery Details tabs, as described in Table 24 Description of Status Tabs on page 94. 

Running a Full Rediscovery 

To run a full rediscovery: 

1. First make any necessary changes to your discovery configuration, as described in Configuring a 

Discovery on page 96. 


3. Click the Start Full Rediscovery button to launch the rediscovery. 

As the rediscovery runs, status information is displayed under the Discovery Details, Discovery 

Details, and Discovery Details tabs, as described in Table 24 Description of Status Tabs on page 94. 

139


140 

Running a Partial Rediscovery 

To run a partial rediscovery: 


2. Click the Start Partial Rediscovery button. 

The Partial Rediscovery window appears where you can specify IP addresses or subnets containing 

devices to be rediscovered. The Partial Rediscovery window is shown in Figure 57. 

Figure 57: Partial Rediscovery window 

3. To add an IP address or subnet to the list of devices to be rediscovered, click New… and type an IP 

address or a netmask in the Partial Redsicovery Node/Subnet window, as shown in Figure 58. 

Figure 58: New Partial Rediscovery Node/Subnet window 



Starting and Monitoring a Discovery 

4. Once you have specified all IP addresses and subnets to rediscover, you can modify the disovery scope 

to limit the scope of this rediscovery. To do this, click Scope…. The Edit Partial Rediscovery Scope 

window appears, showing the scope settings that you set for the discovery. 

Figure 59: Edit Partial Rediscovery Scope window 

5. To add a scope zone, click the New button and and type an IP address and a netmask in the Scope 

Properties window, as shown in Figure 60. 

Figure 60: Scope Properties window 

6. Once you have specified all scope zones, click OK in the Edit Partial Rediscovery Scope window. 

Note: If you wish to save the scope zones changes you made to the DiscoScope.cfg configuration 

file, then select Save changes to configuration file. 

141


142 

7. Click Go on the Partial Rediscovery window to launch the discovery. 

As the discovery runs, status information is displayed under the Discovery Details, Discovery Tables, 

and Discovery Devices tabs, as described in Table 24 Description of Status Tabs on page 94. 


4.4 Using the Discovery Wizard 

! 


Using the Discovery Wizard 

Note: The discovery configuration wizard does not enable you to perform complex discoveries involving 

NAT translations, MPLS configuration and other advanced features. To perform these complex discoveries, 

users should refer to information on using the Network Discovery GUI in Configuring a Discovery on 

page 96. Advanced users should refer to information on configuring the discovery using OQL inserts and 

configuration files in Configuring the Discovery on page 181. 

Scope: You can specify whether to run a scoped or unscoped discovery. A scoped discovery restricts 

the discovery to a certain part of your network and is recommended in most cases. An unscoped 

discovery attempts an unrestricted discovery in your entire network. 

Warning: If there are routes out of your network to the Internet, then an unscoped discovery is not 

recommended as it will find these routes and will proceed to discover parts of the Internet. 

SNMP and Telnet Passwords: You can specify the SNMP and Telnet passwords required by your 

network devices so that the discovery process can interrogate these devices to obtain data. You can 

specify a global password, or different passwords for each device or subnet. 

Type of Discovery: You can specify a Layer 3 or a Layer 2 discovery. A Layer 3 discovery is quicker 

and is recommended for your first discovery. However, 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. For more information on root cause analysis, see the Netcool/Precision IP Monitoring 

and RCA Guide. 

Modelling VLANs: You can 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. 

Filters: You can filter out devices with no SNMP access. You can also filter out end-nodes such as 

workstations and printers. 

It is recommended that you filter out end-nodes so that your discovery runs as quickly as possible. 

Filtering out all end nodes in networks that have large numbers of end nodes can lead to significant 

speed and performance improvements in your discovery 

143


144 

Optimizing Discovery: You can tune the discovery so that the results match your specific needs. For 

example, you can specify that the discovery should find the best possible connectivity and richness of 

information. Alternatively, you can opt to compromise on richness of information and specify the 

fastest possible discovery time. 

Based on what you specify, the wizard will determine which agents to switch on and off. If you select 

best possible connectivity, then the wizard simply switches on all agents. If you are not concerned 

with connectivity and your network is largely made up of Cisco devices, then the wizard can use 

Cisco-specific protocols to greatly speed up the discovery. However, if you are an advanced user and 

you wish to make a more precise selection of exactly which agents are run to discover connectivity, 

then you should use the tabbed Network Discovery GUI to configure your discovery, as described in 

Configuring a Discovery on page 96. 

Cisco Networks: If a large proportion of your network is made up of Cisco hardware and you prefer 

discovery speed to accurate connectivity, then the wizard will direct you to use the Cisco Discovery 

Protocol (CDP) and the Spanning Tree Protocol (STP) to perform the discovery. These two 

protocols provide fast discovery. In terms of connectivity, these protocols discover how switches are 

connected to each other. However, while the CDP protocol is able to discover connectivity between 

Cisco switches and CIsco routers, the STP protocol is not able to discover connectivity between 

switches and end nodes or connectivity between switches and routers. 

The CDP and STP protocols find Layer 2 connectivity only. For this reason they are only used, (and 

the wizard only asks you about them) if you select to run a Layer 2 and Layer 3 discovery. 

Launching the Discovery Wizard 

Launch the Configuration section of the Network Discovery GUI. This button is shown in Figure 61. 

Figure 61: Wizard button 

As you progress through the wizard, you step through a series of screens in which you specify values for 

discovery configuration parameters. You may find data in some of these tabbed screens. This is data specified 

in earlier configurations and held in the relevant discovery configuration file. 

After you launch the wizard, the Welcome window appears. Click Next to continue. 

Note: You can click Cancel at any point to exit the wizard, without saving any discovery settings. 


Scoping and Seeding the Discovery 

! 

The next window provides the option of a scoped or unscoped discovery. 

1. Select Scoped or Unscoped. 

Figure 62: Scoped or Unscoped Window 



– Scoped: Scoping restricts the discovery to a certain part of your network. In order to specify a 

scoped discovery, you must tell the wizard which area of the network to restrict the discovery to, 

and you must assign IP addresses or subnets as seeds to ping in order 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 in order to begin the discovery. 

Warning: If there are routes out of your network to the Internet, then an unscoped discovery is 

not recommended as it will find these routes and start to discover parts of the Internet. 

145


146 

2. When you have selected one of these options, click Next. 

– If you selected the Scoped option, then the Discovery Scope window appears, as shown in 

Figure 63. 

– If you selected the Unscoped option, then the Discovery Seed window appears, as shown in 

Figure 65 on page 148. 

3. Specify the scope of the discovery. 

Figure 63: Discovery Scope Window 

In this window, you specify the following: 

– Which area of the network to restrict the discovery to. You can specify one or more subnets 

within your network. 

– Which IP addresses or subnets as seeds to ping in order to begin the discovery 

The information that you specify in this window is saved to the 

DiscoScope.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the name of the 


of the DiscoScope.cfg schema file in Introduction to Scope on page 208. 




4. Specify the subnet or subnets to use for both scoping and seeding by clicking the New button and 

typing an IP address and a netmask in the New Discovery Scope window, as shown in Figure 64. 

Figure 64: New Discovery Scope Window 

The subnets that you specify are written to two discovery database tables: 

– The scope.zones table that stores the subnets that define the scope of the discovery. For 

more advanced information on scoping within a discovery, see Defining Discovery Zones on 

page 209. For more information on the scope.zones table, see The zones Table on 

page 442. 

– The pingFinder.pingRules table that stores the device or subnet addresses at which the 

finder begins looking for devices. The subnet or subnets that you specify are added to this table 

and each device within these subnets are pinged by the finder. For more advanced information 

on configuring the Ping finder, see Configuring the Ping Finder on page 183. For more 

information on the pingFinder.pingRules table, see Seeding the Ping Finder on 

page 222. 

Specify one or more subnets, and then click Next to proceed to the next window, shown in Figure 67 

SNMP Passwords Window on page 150. 

147


148 

5. If you selected the Unscoped option, then the Discovery Seed window appears. 

Figure 65: Discovery Seed Window 

In this window, you specify the seeds to use for your unscoped discovery. These are IP addresses to 

ping in order to begin the discovery. 


DiscoPingFinderSeeds.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the 


and function of the DiscoPingFinderSeeds.cfg schema file in Configuring the Ping Finder 

on page 221. 




6. Specify one or more IP addresses by clicking the New… button and typing an IP address in the New 

Discovery Seed window, as shown in Figure 66. 

Figure 66: New Discovery Seed Window 

The seed or seeds that you specify are written to the pingFinder.PingRules table. This table 

stores the device addresses at which the finder begins looking for devices. The IP addresses that you 

specify are added to this table and are pinged by the finder. For more advanced information on 

configuring the Ping finder, see Configuring the Ping Finder on page 183. For more information on 

the pingFinder.pingRules table, see Seeding the Ping Finder on page 222. Specify one or 

more IP addresses as seeds and then click Next to proceed. 

149


Setting SNMP Passwords 

150 

The next window provides the option of setting SNMP passwords. 

1. The SNMP Passwords window appears. 

Figure 67: SNMP Passwords Window 

In this window you specify address-specific, network-specific or global community strings, and, in the 

case of SNMP version 3, specify passwords for these community strings. 


SnmpStackSecurityInfo.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the 


and function of the SnmpStackSecurityInfo.cfg schema file in Configuring the Device 

SNMP Access Parameters on page 187. 




2. For each SNMP community string and associated passwords that you wish to define, click the New 

button, which appears above the SNMP Passwords table. The SNMP Password window appears. In 

this window you can specify address-specific, network-specific or global SNMP community strings, 

and supply passwords for these community strings. The SNMP Password window and associated 

instructions for completing the fields are shown in Figure 41 SNMP Password Window With Sample 

Community String Data on page 113. 

3. Once you have finished defining SNMP community strings, click Next. 

Setting Telnet Access Parameters 

The next window provides the option of setting Telnet access parameters. 

1. The Telnet Paswords window appears. 

Figure 68: Telnet Passwords Window 

In this window you specify prompts, login IDs and login passwords for Telnet accessible devices. 


TelnetStackPasswords.DOMAIN_NAME.cfg schema file, where DOMAIN_NAME is the 


and function of the TelnetStackPasswords.cfg schema file in Configuring Telnet Device 

Access on page 303. 

151


152 

2. For each set of Telnet accessible devices for which you wish to define prompts and passwords, click 

the New button, which appears above the Telnet Passwords table. The Telnet Password window 

appears. In this window you can 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. The Telnet Password window and associated instructions for completing the 

fields are shown in Figure 43 Telnet Password Window With Sample Data on page 116. 

3. Once you have finished defining Telnet passwords, click Next. 

Specifying the Type of Discovery 

The next window provides the option of specifying the type of discovery. You can specify either a Layer 3 

or a Layer 2 discovery. 

1. The Discovery Type window appears. 

Figure 69: Discovery Type Window 

In this window you specify whether to run a Layer 3 or a Layer 2 discovery. A Layer 3 discovery is 

quicker and is recommended for your first discovery. However, 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. For more information on root cause analysis, see the Netcool/Precision IP 

Monitoring and RCA Guide. 


2. When you have specified one of these options, click Next. 



– If you selected Layer 3 option, then the End Node Discovery window appears, as shown in 

Figure 71 End Node Discovery Window on page 154. 

– If you selected Layer 2 and Layer 3 option, then the VLAN Modelling window appears, as 

shown in Figure 70. 

Figure 70: VLAN Modelling Window 

In this 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. 

153


154 

3. Specify whether you wish to model VLANs. When you have specified an option, click Next. The End 

Node Discovery window appears. 

Figure 71: End Node Discovery Window 

This window provides the option to filter out end node devices such as workstations and printers. 

This ensures that your discovery runs as quickly as possible. You can also opt to filter out devices with 

no SNMP access. 

Tip: It is recommended that you filter out end-nodes so that your discovery runs as quickly as possible. 

Filtering out all end nodes in networks that have large numbers of end nodes can lead to significant 

speed and performance improvements in your discovery. 



Optimizing the Discovery 

The next window provides the opportunity to optimize the discovery. 

1. The Discovery Optimization window appears. 

Figure 72: Discovery Optimization Window 



In this window you can optimize the discovery for connectivity information, richness of information 

and speed. 

– 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 may 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. 

155


156 

– 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 in order to provide a faster discovery. For example, the discovery may 

provide information on how switches are connected to each other, but it may not provide 

information on connectivity between switches and end nodes or between switches and routers. 

Note: This option is more suitable if you are using Netcool/Precision IP to gather inventory data 

rather than for performing 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. 





– If you selected either of the first two options, this means that accurate connectivity is important. 

The Network Reliability window appears, as shown in Figure 75 Network Reliability Window on 

page 159. 

– If you selected either of the last two options, this means that you are willing to compromise on 

the accuracy of connectivity information in order 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 appears, as shown in Figure 73. 

Figure 73: Cisco Hardware Window 

Specify how much of your network is made up of Cisco hardware. 

– All of it: By selecting this option you direct the wizard to run the Cisco Discovery Protocol 

(CDP). 

– Most of it, Some of it, Don’t know: By selecting these options you direct the wizard to run the 

Cisco Discovery Protocol (CDP). If you chose a Layer 2 and Layer 3 discovery (Figure 69 

Discovery Type Window on page 152) or if you indicated that you wished to exclude end nodes 

from the discovery (Figure 71 End Node Discovery Window on page 154) then this option 

157


158 

invokes the Spanning Tree Protocol (STP) as well as CDP. 

– None of it: If you select this option then neither the CDP nor the STP protocol is used. 

3. When you have selected one of these options, click Next. 

– If your response to the Cisco hardware question was All of it or None of it, then the Network 

Reliability window appears, as shown in Figure 75 Network Reliability Window on page 159. 

– 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 appears, as shown in Figure 74. 

Figure 74: Spanning Tree Protocol Window 




4. When you have specified one of these options, click Next. The Network Reliability window appears, 

as shown in Figure 75. 

Figure 75: Network Reliability Window 

Choose an option corresponding to the reliability of your network when responding to ping and 

SNMP requests: 

– Very reliable: This option directs the wizard to apply very short timeouts, without any retries. 

This is appropriate for a very reliable network and results in fast discoveries. If, in the Discovery 

Optimization window (Figure 72 Discovery Optimization Window on page 155), you requested 

fastest possible discovery time at the expense of both connectivity information and richness of 

information, then the timeouts set by this option are even shorter. 

– Quite reliable: This option directs the wizard to apply slightly longer timeouts, with a single 

retry for both SNMP and ping requests. 

159


160 

– Not very reliable: This option directs the wizard to apply longer timeouts, two retries for 

SNMP requests and one retry for ping requests. These longer times are suitable for less reliable 

networks. 

– Don’t know: If you select this option then the wizard applies the same timeouts and retries as 

used for the Quite reliable option. 


Completing the Configuration 

The next window provides the option to review any of your settings. You can also save the settings here, and, 

optionally, start the discovery with the settings that you configured. 

1. The Configuration Summary window appears, as shown in Figure 76. 

Figure 76: Configuration Summary Window 

This window summarizes the discovery configuration settings that you specified using the wizard. 

– Click on any of the hyperlinks to go back to the relevant window. You can then modify the 

settings as appropriate. 

– Select Start Discovery to specify that you wish to run the discovery with these settings. 


2. When you are content with the discovery settings, click Finish: 



– If you selected Start Discovery then the discovery starts, using the discovery configuration 

settings that you specified using the wizard. 

– If you did not select Start Discovery then the discovery settings are saved. 

161


4.5 Reading and Writing Configuration Files 

162 

The binary named ncp_config acts as a configuration file server. It provides a means for the 

configuration GUIs to read from and write to schema files. It is started, and later stopped, automatically by 

the shell scripts that launch the GUIs and so in general need not be manually started. 

You can also start CONFIG manually with the following command line—optional arguments are shown 

enclosed in square brackets. 

ncp_config –domain DOMAIN_NAME [ -debug DEBUG ] [ -latency LATENCY ] 

[ -read_schemas_from DIRECTORY_NAME ] [ -write_schemas_to DIRECTORY_NAME ] [ -help ] 

[ -version ] 

The -read_schemas_from and -write_schemas_to command line options can only be used 

when starting ncp_config manually. 

Table 25: Explanation of Command Line Options (1 of 2) 


-domain DOMAIN_NAME The name of the domain under which to run CONFIG. Data saved in 

the Network Discovery GUI is saved to the domain name that you 

specify here. 

-debug DEBUG The level of debugging output (1-4, where 4 represents the most 

detailed output). 

-latency LATENCY The maximum time in milliseconds (ms) that CONFIG waits to connect 

to another Netcool/Precision IP process using the messaging bus. This 

option is useful for large and busy networks where the default settings 

can cause processes to assume that there is a problem when in fact 

the communication delay is a result of network traffic. 

-read_schemas_from DIRECTORY_NAME The full path of the directory from which CONFIG reads the schema 

files. 

If this option is not specified, NCHOME/etc/precision is used as a 

default. 

Note: NCHOME is the environment variable that contains the path to 

the Netcool Suite home directory. For information on how this 

environment variable varies with platform, see Operating System 

Considerations on page 10. 

-write_schemas_to DIRECTORY_NAME The full path to which CONFIG writes the schema files. 

If no path is specified, CONFIG updates the files in the source directory, 

saving a backup of the existing schema. 





Reading and Writing Configuration Files 

-help Displays the command line options. Does not start the component 




163


164 


5. Querying_Databases.fm July 5, 2005 

Chapter 5: Querying Netcool/Precision IP 

Databases 

This chapter describes the methods you can use to query the Netcool/Precision IP databases, the GUI-based 

OQL workbench and the OQL Service Provider, a command line interface. 


Accessing the Precision Server Databases on page 166 

The OQL Workbench on page 167 

The OQL Service Provider on page 169 


Chapter 5: Querying Netcool/Precision IP Databases 

5.1 Accessing the Precision Server Databases 

166 

The Object Query Language (OQL) is used by all the Netcool/Precision IP processes to interact with their 

databases. This chapter introduces the two methods available for issuing OQL commands to access the 

Netcool/Precision IP databases: 

The GUI-based OQL Workbench. This is described in The OQL Workbench on page 167. 

The OQL Service Provider, a command line interface. This is described in The OQL Service Provider 

on page 169. 

This chapter includes example OQL statements. Refer to Appendix B: The Object Query Language on 

page 479 for full details of the language syntax. 

Using either the GUI-based OQL workbench or the OQL Service Provider, you can access the databases of 

any process. Here are some of the activities that you can perform on the databases: 

Insert data into tables, for example, to cause CTRL to launch a managed process or to start or stop 


Create new databases or tables. 

Delete existing databases, tables, or records. 

Interrogate existing databases or tables, for example, to identify the current status of the discovery. 


5.2 The OQL Workbench 

The OQL Workbench provides GUI-driven access to the Netcool/Precision IP databases. 

Accessing the OQL Workbench 


The OQL Workbench 

To access the OQL Workbench, log into the Netcool GUI Foundation, as described in the Netcool/Precision 

IP Topology Visualization Guide. The Netcool GUI Foundation is installed as part of the Netcool/Precision 

IP installation, and is the framework within which all Netcool/Precision IP web interfaces appear. 

Once you have logged into the Netcool GUI Foundation, select the Precision Admin page. This page 

provides access to the OQL Workbench, as well as the Network Discovery GUI and MySQL database 

settings, as shown in Figure 77. This figure shows the Precision Admin page with the OQL Workbench tab 

open. 

Figure 77: OQL Workbench 

167


Using the OQL Workbench 

168 

You can use the OQL Workbench to perform queries on Netcool/Precision IP component databases. 

Using the OQL Workbench you can perform all of the operations that you perform with the OQL Service 

Provider. This section shows you the steps to perform database operations using the OQL Workbench. For 

examples of database operations, see Using the OQL Service Provider on page 170. 

To issue a database command using the OQL Workbench: 

1. Access the OQL workbench as described in Accessing the OQL Workbench on page 167. 

2. Click the Domain drop-down list box and select the domain in which to issue the OQL commands. 

3. Click the Service drop-down list box and select the service that you wish to interrogate. See Table 28 

on page 171 for a full list of OQL service names. 

4. Click in the Query field and type an OQL command. If your query requires multiple lines, then click 

the Advanced OQL Query button, shown in Table 26, and type the query in the Netcool/Precision IP 

OQL Workbench window. Click OK. 

5. Click the Go button, shown in Table 26, to issue the OQL command. The results appear in the main 

browser window. 

Table 26: Icons in the OQL Workbench 

Item Name Description 

Advanced 

OQL Query 

Enables you to specify a multiple line OQL command. 

Go Click here to issue your OQL command. 


5.3 The OQL Service Provider 



You can use the OQL Service Provider to perform queries on Netcool/Precision IP component databases. 

Starting the OQL Service Provider 

To launch the OQL Service Provider and log into the databases of a given Precision Server component, use 

the following command line; optional arguments are shown enclosed in square brackets. 

ncp_oql [ -agent AGENT_NAME.KEY ] [ -debug DEBUG ] –domain DOMAIN_NAME [ -help ] 

[ -history HISTORY_SIZE ] [ -latency LATENCY ] [ -oqldump ] [ -password PASSWORD ] 

[ -query QUERY ] -service SERVICE_NAME -username USERNAME 



-agent AGENT_NAME.KEY Used in conjunction with the MonitorAgent service to log into a 

Polling agent. 

AGENT_NAME is the name of the executable that is running the 

poll. 

KEY is the key under which the agent is running, as specified in 

the poll definition. 

The following example command could be used to log into the Ping 

Polling agent running in the NCOMS domain: 

ncp_oql -domain NCOMS -username admin -service 

MonitorAgent -agent ncp_m_timedstitcher.PING 



-domain DOMAIN_NAME The name of the relevant domain. Ensure that the process whose 

databases you wish to query is running. 

-help 

All Precision Server 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. 

-history HISTORY_SIZE The size of the command line history. 

-latency LATENCY The maximum time in milliseconds (ms) that the service provider waits 

to connect to another Precision Server process using the messaging 

bus. This option is useful for large and busy networks where the 

default settings can cause processes to assume that there is a problem 

when in fact the communication delay is a result of network traffic. 

-oqldump Using this argument results in the databases from the application 

being converted into OQL create and insert statements. This can be a 

useful means of recording the internal state of a component for 

debugging or analysis at a later date. 

169


170 



-password PASSWORD The password to access the OQL Service Provider. 

Note: In order to log into the OQL Service Provider, AUTH must be running in the same domain as the 

service that you are logging into. 

Using the OQL Service Provider 

This feature is provided for use in conjunction with the -query 

option, to enable OQL queries to be placed in scripts. 

For security reasons you must use this option carefully, as other users 

may be able to see your password. Micromuse recommend that you 

enter your password when prompted rather than at the command 

line. 

-query QUERY A query to pass to the OQL Service Provider, designed to allow OQL 

statements in scripts (used in conjunction with -password). 

-service SERVICE_NAME The service you wish to interrogate. See Table 28 on page 171 for a full 

list of OQL service names. 

-username USERNAME The username to use to log into the service provider. 

-version 

All Precision Server 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. 

Once you have logged into the service provider, you can issue OQL statements to act on the databases of 

the service that you are logged into. You must terminate statements with a semi-colon (;) and the go 

keyword. You can also use the send keyword instead of go. 

The following example shows a user logging into the DISCO databases and querying the disco.status 

table. In this example (and throughout this chapter) OQL keywords have been shown in bold for clarity. 

ncp_oql -domain NCOMS -service Disco -username admin 

ncp_oql ( Netcool/Precision IP OQL Interface ) 

Copyright (C) Micromuse Ltd., 1997-2003. All Rights Reserved. 

Password: 

|phoenix:1.> select * from disco.status; 


. 

{ 

m_DiscoveryMode=0; 

m_Phase=1; 

m_BlackoutState=0; 

m_CycleCount=0; 


m_ProcessingNeeded=0; 

m_FullDiscovery=0; 

} 


|phoenix:1.> 

Component Service Names 

The following table lists the OQL service name for each Netcool/Precision IP component. 

Table 28: Components and Their OQL Service Names 

Component OQL service name 

AMOS Amos 

AUTH Auth 

CLASS Class 

CONFIG Config 

CTRL Ctrl 

Desktop Desktop 

DISCO Disco 

DIST Dist 

EXEC Exec 

Helper Server Helper 

MODEL Model 

MONITOR Monitor 

Ping finder DiscoPingFinder 

Polling agent MonitorAgent 

Sequential ID Trap DIST Adaptor SidTrap 

SNMP Helper SnmpHelper 

STORE Store 

TrapMux TrapMux 



171


172 

The Command Line History 

There is a history function available at the OQL command prompt. The hist keyword displays a list of 

previously executed commands, which can be executed by typing ! followed by the number of the command 

you wish to repeat. An example of the hist function is shown below. 

|phoenix:1.> hist 

1: select * from disco.status 

2: select * from disco.managedProcesses 

3: select * from disco.config 

|phoenix:1.> !2 

select * from disco.managedProcesses 

.............................................. 

You can also type !! at any time to repeat the previous command. 

Specifying a Query Using the -query Option 

If necessary, you can launch the service provider in a special mode that executes a single specified query and 

disconnects from the service provider. This allows OQL queries to be put into scripts. 

The following example shows the -query option in use. 

ncp_oql -domain NCOMS -service Disco -username admin -password "password" -query "select 

* from disco.status;" 



Executing query: 

select * from disco.status; 

. 

{ 


m_Phase=1; 





} 


The above example performs a single query on the disco.status database table and disconnects from 

the OQL Service Provider. In order to perform this query, DISCO and AUTH would have to be running 

in the NCOMS domain, and the specified username and password combination would have to be valid. 

Any acceptable OQL query can be specified with the -query option. The query must be terminated with 

a semi-colon but not the go keyword. 


Listing the Databases and Tables of the Current Service 



The show databases command displays a list of the databases of the service you are logged into. The 

following example can be used by a user logged into the MODEL databases. 

|phoenix:1.> show databases; 


{ 

databases = [ 'master', 'translations' ] 

} 

( 1 Record(s) : Transaction complete ) 

|phoenix:1.> 

The show tables from command displays a list of the tables within a database, as shown below. 

|phoenix:1.> show tables from master; 


{ 

tables = [ 'entityByName', 'entityByNeighbor', 'containers' ] 

} 


|phoenix:1.> 

The show table command displays the columns within a table, as shown below. 

|phoenix:1.> show table 

master.entityByName; 


{ 

schema = { 

ObjectID = { 

DataType = 'long'; 

NotNull = 'Y'; 

PrimaryKey = 'Y'; 

Indexed = 'N'; 

Unique = 'Y'; 

} 

EntityName = { 

Datatype = 'text'; 




Unique = 'Y'; 

}; 

..... 

..... 

}; 

} 


|phoenix:1.> 

173


174 

Exiting the OQL Service Provider 

Type quit to exit the service provider, as shown in the following example. 

|phoenix:1.> quit; 


6. Running_tracking_discovery.fm July 5, 2005 

Chapter 6: Network Discovery from the 

Command Line 

This chapter explains how to configure, run, and track a network discovery from the command line. 


Introduction on page 176 

Preparing for Discovery on page 177 

Starting DISCO on page 178 

Configuring the Discovery on page 181 

Running the Discovery on page 190 

Tracking the Progress of the Discovery on page 191 


Chapter 6: Network Discovery from the Command Line 

6.1 Introduction 

176 

This chapter focuses on manual configuration of the discovery process. Altering configuration files is for 

advanced users only. You should be familiar with using OQL (see Chapter 5: Querying Netcool/Precision IP 

Databases on page 165) and with the discovery process (see An Overview of the Discovery Process on page 25). 

For reference, the databases of DISCO are described in Appendix A: The Discovery Databases on page 423. 

If this is the first time you have run a discovery, Micromuse recommends using the Discovery Configuration 

Tool, described in Chapter 4: Network Discovery Using the Network Discovery GUI on page 85. 


6.2 Preparing for Discovery 


Preparing for Discovery 

Operating System: if you are running under Solaris, then ensure that the host on which 

Netcool/Precision IP is running is fully patched with the latest Solaris patches. Linux does not require 

any Solaris patches. 

Scope of Discovery: you should consider the positioning of the Netcool/Precision IP host machine 

within the network. Is it positioned to be able to interrogate all devices that you wish to include in 

your discovery? Consider also all necessary networks, sub-networks and determine the associated 

netmasks. Are there any parts of the network that you wish to exclude? Gather also all relevant SNMP 

community strings for the devices within the scope. 

Routing: ensure that each of the networks and sub-networks to be discovered is reachable using the 

ICMP process. If necessary add routes to Netcool/Precision IP host machine using the route add 

command. 

Access Control Lists: Netcool/Precision IP uses five protocols that may need to pass through firewalls. 

These protocols are ICMP, SNMP, DNS, ARP and TELNET. In order to ensure that 

Netcool/Precision IP is able to access devices behind these firewalls you need to 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 wish to perform root cause analysis. In addition, the 

discovery must identify the relevant polling agent host. For more information on root cause analysis, 

see the Netcool/Precision IP Monitoring and RCA Guide. 

177


6.3 Starting DISCO 

178 

Micromuse recommends that CTRL, the domain process controller, is configured to start DISCO 

automatically at the appropriate time. 

DISCO can be started manually with the following command line, but CTRL must be running in order for 

DISCO to launch and manage its subprocesses. 

ncp_disco [ -cachesize SIZE_IN_MB ] [ -cachepercent PERCENTAGE_OF_CACHE_IN_MEMORY ] 

–domain DOMAIN_NAME [ -debug DEBUG ] [ -help ] [ -latency LATENCY ] [ -version ] 



-cachesize SIZE_IN_MB Specifies the size of the cache in megabytes (MB). 

-cachepercent 

PERCENTAGE_OF_CACHE_IN_MEMORY 

Enables you to specify the ratio of the cache that is resident in memory 

to the cache that is resident on the hard disk. 

The ratio that you specify depends on the amount of memory that 

exists on the host machine and the number of processes it is running. 

The default value is 100% cache. 

-domain DOMAIN_NAME The name of the domain under which to run DISCO. 



-help All Precision Server 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. 

-latency LATENCY The maximum time in milliseconds (ms) that DISCO waits to connect 

to another Precision Server process using the messaging bus. This 

option is useful for large and busy networks where the default settings 

can cause processes to assume that there is a problem when in fact 

the communication delay is a result of network traffic. 

-version 

All Precision Server 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. 

The -cachesize and -cachepercent options can be used to reduce the memory required when the 

process responds to OQL queries that result in large numbers of records being returned. 

When a value for -cachesize is specified, a fixed size of records is cached in core memory with the 

remaining records being flushed to disk. When a value for -cachepercent is specified, that percentage 

of the data is cached in core memory with the remainder being flushed to disk. These command line options 

are not intended to be used for permanent data storage as the cache is cleared when the process exits. 


Prerequisites for Running DISCO 


Starting DISCO 

CTRL must be running. Although it is possible to start DISCO manually from the command line, unless 

CTRL is running DISCO cannot launch and manage its subprocesses. 

The recommended additional components are: 

STORE, in order to store the discovered network topology 

CLASS, in order to provide the Active Object Class definitions 

MODEL, in order to receive the deduced network topology 

Although it is possible to run a full discovery without STORE, CLASS and MODEL, the topology is not 

passed to MODEL, the discovered devices are not instantiated to AOCs and the topology is not stored on 

disk. If necessary, STORE, CLASS and MODEL can be started after DISCO has completed the discovery 

and the topology can then be activated by manually invoking the SendTopologyToModel.stch 

Stitcher. You invoke this stitcher manually by inserting it into the stitchers.actions table. For 

more information on manually invoking a stitcher, see On-Demand Stitchers on page 32. 

DISCO Memory Requirements 

Netcool/Precision IP processes, including DISCO, are 32-bit processes and therefore have access to up to 4 

GB of memory. 

DISCO is the Netcool/Precision IP process that uses most memory. Occasionally you may encounter 

problems with DISCO (or other processes) running out of memory. 

This is unlikely to be a problem on Solaris or Linux, as these platforms to up to the maximum of 4 GB of 

memory. 

Problems with process memory may occur if you are running on AIX. On this platform, DISCO and other 

processes can automatically access up to 2 GB of memory only. This enables them to work out-of-the-box 

on both 32-bit and 64-bit kernels. 

179


180 

In order to enable a specific Netcool/Precision IP process to access up to 3.25 GB of memory on an AIX 

64-bit kernel, do the following: 

1. Ensure that you are running the 64-bit kernel. 

2. Go to the bin directory. 

cd NCHOME/precision/platform/aix5/bin 

Note: NCHOME is the environment variable that contains the path to the Netcool Suite home 

directory. For information on how this environment variable varies with platform, see Operating System 


3. Issue the command to alter the memory model used by a specific Netcool/Precision IP process. 

ldedit -bmaxdata:0xD0000000/dsa precision_process 

In this command, precision_process is the Netcool/Precision IP process whose memory 

access you wish to increase on AIX. For example, if you wish to increase the memory access for 

DISCO, then issue the following command: 

ldedit -bmaxdata:0xD0000000/dsa ncp_disco 


6.4 Configuring the Discovery 


Configuring the Discovery 

DISCO has three configuration files, which are stored in the NCHOME/etc/precision directory: 

The DiscoSchema.cfg file defines the databases used during the discovery process. 

The DiscoAgents.cfg file contains insert statements to the disco.agents table that tell 

DISCO which Discovery agents to start. 

The DiscoScope.cfg file contains inserts to the scope.zones table that define the scope of 


Some example OQL inserts that configure the behavior of DISCO are included in this chapter. For more 

information about the syntax of OQL, see Appendix B: The Object Query Language on page 479. 

A layer 3 (IP layer) discovery involves discovering the connectivity between routers and other devices, but 

does not discover the true connectivity between switches and other complex technologies such as ATM. 

There are extra prerequisites for running a discovery involving NAT domains. See Chapter 12: Managing 

NAT Environments on page 341 for more details. 

For more information on discovering non-IP technologies, see Discovering Device Protocols on page 271 and 

Chapter 11: Configuring an MPLS Discovery on page 325. 

The following section explains how to configure a basic IP layer (layer 3) discovery from the command line. 

Required and common configuration steps are described, and cross-references are given to more advanced 

configurations. 

Configuration Task List 

The following list details some of the configuration adjustments that must be made before DISCO is 

launched: 

Task one: Specify the scope of the discovery by appending the necessary OQL inserts to the 

scope.zones table within the DISCO configuration file, DiscoScope.cfg. The example 

discovery in this chapter discovers the 10.10.2.* subnet. 

Task two: Configure the general operation of DISCO (if necessary) by modifying the 

disco.config table. 

181


182 

Task three: Configure the finders, specifying how many are to be run and the location from which 

they are to begin discovering devices. The configuration of all the finders is not essential, as using the 

Ping finder on its own is enough to begin the discovery process. If necessary, you should: 

– Specify the file(s) to be parsed by the File finder by editing the 

DiscoFileFinderSchema.cfg file. 

– Specify the IP or Subnet address (or addresses) to be used as a seed (or seeds) for the Ping finder 

by editing the DiscoPingFinderSeeds.cfg file. 

– Configure the Trap finder to listen to specific traps by editing the 

DiscoTrapFinderSchema.cfg file. 

– Specify the interface and the number of network packets to be captured and analyzed by the 

Sniffer finder by editing the DiscoSnifferFinderSchema.cfg file. 

Task four: Configure the set of agents that are to be started by DISCO (provided that CTRL is 

running) by modifying the disco.agents table. This layer 3 discovery uses the following agents: 

– Details.agnt 

– AssocAddress.agnt 

– IpRoutingTable.agnt 

– IpForwardingTable.agnt 

Task five: Configure the helpers. Specify a host name and IP address range within the Helper Server 

configuration file, DiscoHelperServerSchema.cfg. This step is not essential. If a host name 

is not specified, CTRL starts the helpers on the same machine as the Helper Server. When the 

discovery process begins, the helpers respond automatically when instructed. 

Task six: Configure the device access variables and parameters for the Telnet helper, such as the 

username and password, as defined by the Telnet passwords file, 

TelnetStackPasswords.cfg. 

Task seven: Configure the SNMP access strings, for example, community strings, private and public 

passwords within the SNMP device access configuration file, SnmpStackSecurityInfo.cfg. 

The example discovery in this chapter uses the community strings "public" and "crims0n". 

Task eight: Configure the discovery process data flow by editing the definitions sections of each 

stitcher and Discovery agent. This step must only be undertaken by advanced users for whom the 

defaults are not suitable. 

If necessary, the OQL Service Provider can be launched in order to track the discovery by querying the 

DISCO databases as the discovery proceeds. 


Scoping the Discovery 



You must scope the discovery to restrict the area of the network that is to be discovered. You can configure 

the scope by configuring an insert into the DISCO scope.zones table. 

The following insert can be appended to the DiscoScope.cfg configuration file to restrict the discovery 

to the 10.10.2.* subnet. 

insert into scope.zones 

( 

m_Protocol, 

m_Action, 

m_Zones 

) 

values 

( 

1, 

1, 

[ 

{ 

m_Subnet="10.10.2.*" 

} 

] 

); 

Devices that are not within the specified subnet are not discovered, so any device found by the finders that 

is outside the 10.10.2.* subnet is not passed to the Details agent and therefore no further information 

about the device is discovered. 

Detailed information about scope can be found in Chapter 7: Scoping a Discovery on page 207. 

Configuring DISCO 

The general operation of DISCO can be configured, if necessary, through inserts into the disco.config 

database table. For more information, see Example Configuration of the disco.config Table on page 439. 

Configuring the Ping Finder 

You must seed the Ping finder with a device or subnet address at which the finder begins looking for devices. 

You seed the Ping finder by appending an insert into the pingFinder.pingRules table to the 

DiscoPingFinderSeeds.cfg configuration file. You can seed the Ping finder with as many IP 

addresses as necessary. 

For more information on configuring the finders, see Chapter 8: Using Finders to Seed a Discovery on 

page 219. 

183


184 

Example Subnet Seed 

The following insert seeds the Ping finder with a device with a subnet address of 172.16.25.0, and 

supplies the netmask of the device. 

insert into pingFinder.pingRules 

( 

m_Address, 

m_RequestType, 

m_NetMask 

) 

values 

( 

"172.16.25.0", 

2, 

"255.255.255.0" 

); 

Example IP Seed 

The following insert seeds the Ping finder with the 172.16.25.5 IP address. Note that there is no need 

to specify the netmask. 


( 

m_Address, 

m_RequestType 

) 

values 

( 

"172.16.25.5", 

1 

); 

Activating the Discovery Agents 

Provided CTRL is running, the Discovery agents that have been activated are started automatically at the 

appropriate time. 

There is an insert into the disco.agents table in the DiscoAgents.cfg configuration file for every 

installed Discovery agent. In order to activate an agent, you must alter the insert so that the m_Valid 

column for that agent is set to 1. In order to deactivate an agent, ensure that m_Valid=0. You can also 

activate and deactivate the agents using the Discovery Configuration Tool, as described in 

Chapter 4: Network Discovery Using the Network Discovery GUI on page 85. 




In order to activate or deactivate the agents you must alter the existing inserts within the schema file. Do not 

append new inserts into disco.agents as there is an insert for every supplied agent in the schema by 

default. 

For further details on configuring the Discovery agents, see Chapter 9: Discovery Agents on page 239. 

The following example inserts activate the appropriate agents. 

Example: Activating the Details Agent 

You can use the following insert to activate the Details agent. 

insert into disco.agents 

( 

m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence 

) 

values 

( 

'Details', 1, 0, 0, 1 

); 

Example: Activating the AssocAddress Agent 

You can use the following insert to activate the AssocAddress agent. 


( 


) 

values 

( 

'AssocAddress', 1, 2, 0, 2 

); 

Example: Activating the IpRoutingTable Agent 

You can use the following insert to activate the IpRoutingTable agent. 


( 


) 

values 

( 

'IpRoutingTable', 1, 0, 0, 2 

); 

185


186 

Example: Activating the IpForwardingTable Agent 

You can activate the IpForwardingTable agent using the following insert. 


( 


) 

values 

( 

'IpForwardingTable', 1, 0, 0, 2 

); 

Deactivating the Discovery Agents 

You can disable all unnecessary Discovery agents by locating the insertions for the agents that are not to be 

run and ensuring that the m_Valid column is set to 0. The following example deactivates the 

SuperStack3ComSwitch agent. 


( 


) 

values 

( 

'SuperStack3ComSwitch', 0, 1, 1, 3 

); 

The Helper Server 

You must configure the Helper Server as a managed process of CTRL by appending an insert into the CTRL 

services.inTray table within the CtrlSchema.cfg configuration file, as shown by the following 

example. 


( 

serviceName, 

servicePath, 

domainName, 

argList, 

retryCount 

) 

values 

( 

"ncp_d_helpserv", 

"$NCHOME/precision/bin", 

"NCOMS", 


); 

[ "-domain", "NCOMS" ], 

5 

This insert instructs CTRL to: 

Launch ncp_d_helpserv from $NCHOME/precision/bin. 

Launch the Helper Server in the domain NCOMS. 

Pass the argument -domain NCOMS to the Helper Server. 

Restart the Helper Server a maximum of 5 times. 

Managing the Helpers 



It is not necessary to configure the individual helpers as managed processes. Provided that the Helper Server 

is configured as a managed process of CTRL, the individual helpers are launched and managed 

automatically. 

The only situation in which you might need to configure an insert for an individual helper would be in order 

to start that helper on a remote machine (that is, a machine other than the one that is running the Helper 

Server). In this situation you would explicitly insert the required helper into the 

disco.managedProcesses table within the DiscoAgents.cfg configuration file, specifying the 

appropriate remote host in the m_Host column. 

Configuring the Device SNMP Access Parameters 

One of the prerequisites to discovering connectivity is that the discovery processes must have SNMP access 

to the routers and other devices that support SNMP on the network. You must therefore specify the 

community strings by altering the SNMP device access configuration file, 

SnmpStackSecurityInfo.cfg, which is used by the SNMP helper to enable device access. 

The following inserts configure the discovery subprocesses to use the community strings public and 

crims0n to access SNMP devices. 

insert into snmpStack.verSecurityTable 

( 

m_SNMPVersion, 

m_Password, 

m_SNMPVer3Level, 

m_SNMPVer3Details, 

m_SecurityName 

) 

values 

( 

0, 

'public', 

187


188 

); 

2, 

{ 

m_AuthPswd="authpassword", 

m_PrivPswd="privpassword" 

}, 

'authPriv' 


( 

) 

values 

( 

); 

m_IpOrSubNetVer, 

m_NetMaskBitsVer, 


m_Password, 



m_SecurityName 

"10.10.2.0", 

24, 

0, 

'crims0n', 

2, 

{ 



}, 

'authPriv' 

You can append as many inserts as there are passwords to the SnmpStackSecurityInfo.cfg 

configuration file. The SNMP helper cycles through all password and subnet configurations until a match 

is found. 

Note: Only one SNMP community string, the public community string, is set up in the out-of-the-box 

configuration. 

Configuring Telnet Device Access Parameters 

If there are devices on your network to which you do not have SNMP access, or if there is information you 

need to discover that is not available through SNMP, you can use the Telnet helper. For details on 

configuring the Telnet helper, see Configuring the Telnet Helper on page 293. 


Editing Stitcher and Agent Definition Files 

! 



You can change almost any aspect of the discovery process by editing the stitcher and agent definition files. 

It is possible to change such things as what data the Discovery agents retrieve from devices, and how data is 

transferred between database tables. For more information on the Discovery stitchers, see Introduction to 

Discovery Stitchers on page 518. For more information on the Discovery agents, see Chapter 9: Discovery 

Agents on page 239. 

Warning: Editing the stitcher and agent definition files should only be undertaken by advanced users who 

have a detailed knowledge of Netcool/Precision IP and the discovery process. 

Altering agent definition files can introduce parse errors. To check your agent for parse errors, you can run 

the agent in debug mode and examine the debug output. The following example shows one way to do this. 

Example: Running a Discovery Agent in Debug Mode 

If you have altered the MyAgent definition file, you can use the following command to run the agent in full 

debug mode and pipe the output to a file named mydebug.out: 

NCHOME/precision/bin/ncp_agent -agent MyAgent -domain TEST -debug 4 >&mydebug.out& 

Note that this command uses csh under UNIX. You should use the appropriate equivalent for your system. 

Altering stitcher files can also introduce parse errors. On startup ncp_disco parses all the discovery 

stitchers and checks that they have no errors. If there is a problem then the discovery will exit and an error 

message will be displayed. To check a stitcher for parse errors, you can run ncp_disco in debug mode 

and examine the debug output. The following example shows one way to do this. 

Example: Running ncp_disco in Debug Mode 

You can use the following command to run ncp_disco in full debug mode and pipe the output to a file 

named mydebug.out: 

NCHOME/precision/bin/ncp_disco -domain TEST -debug 4 >&mydebug.out & 

189


6.5 Running the Discovery 

190 

Once you have made the appropriate configuration adjustments to DISCO, you can run the discovery. It is 

good practice to ensure that CTRL is configured to launch and manage the Netcool/Precision IP processes 

at the appropriate time. The basic configuration of CTRL is described in Chapter 2: Process Control with 

CTRL on page 47. 

Provided CTRL has been configured correctly, you can start the discovery by running CTRL using the 

following command: 

ncp_ctrl -domain NCOMS 

[1] 25142 

ncp_ctrl ( Netcool/Precision IP Process Control Engine ) 


Consuming schemas.....done. 

Becoming Primary for tier 1 

This example assumes that CTRL has been configured to launch and manage the Netcool/Precision IP 

processes in the domain NCOMS. If you have configured CTRL to use another domain name, you must 

substitute the appropriate domain name in the command line. 

Once CTRL has started, it launches the other components one at a time according to their configured 

dependencies. You can check which processes have been launched using the ps command as shown below. 

ps -ef | grep NCOMS 

nmos_user 25831 1 0 12:56:41 ? 0:00 ncp_df_ping -domain NCOMS 

nmos_user 25736 25714 0 12:47:39 ? 0:00 ncp_dh_dns -domain NCOMS 

nmos_user 25905 25834 0 13:02:58 pts/7 0:00 ncp_agent -domain NCOMS -agent Details 

nmos_user 26153 26101 0 13:26:56 pts/9 0:00 grep NCOMS 

nmos_user 25716 25714 0 12:47:00 ? 0:00 ncp_auth -domain NCOMS 

nmos_user 25735 25714 0 12:47:39 ? 0:00 ncp_d_helpserv -domain NCOMS 

nmos_user 25714 1 0 12:46:50 ? 0:00 ncp_ctrl -domain NCOMS 

nmos_user 25729 25714 0 12:47:27 ? 0:18 ncp_disco -domain NCOMS 

nmos_user 25717 25714 0 12:47:00 ? 0:00 ncp_store -domain NCOMS 

If you have not configured CTRL, you can start DISCO manually by using the following command; 

however CTRL must also be running in order to launch the Helper Server and the DISCO managed 

processes. 

ncp_disco -domain NCOMS 


6.6 Tracking the Progress of the Discovery 


Tracking the Progress of the Discovery 

As soon as you have the discovery process running, you can monitor the progress of the discovery by using 

the OQL Service Provider, ncp_oql, to query the DISCO databases to determine what is being done at 

any point in time. 

The queries demonstrated in the subsequent sections of this chapter have been generalized for all discovery 

scenarios and are not limited to the layer 3 discovery shown earlier in this chapter. 

The examples in this chapter 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 should be able to construct queries that answer any questions you have 

regarding the current status of the discovery process. 

The OQL Service Provider is a command line interface and interpreter into the Object Query Language. 

For information on starting the OQL Service Provider, including prerequisites, see Chapter 5: Querying 

Netcool/Precision IP Databases on page 165. 

Simple Queries 

The following are some examples of simple queries you might wish to make on the progress of the discovery: 

Complex Queries 

What is DISCO doing at present? 

How many devices have been discovered in the network? 

How many devices have been found by the finders? 

Which devices are currently being processed by the finders? 

Which agents have discovered devices? 

What is the current phase of the discovery? 

What is the NAT status of the discovery? 

What is the current status of any of the Discovery agents? 

What is the current operational status of the stitchers? 

The following are examples of some more complex queries you might wish to make: 

Which devices have been discovered by a specific Discovery agent? 

Which Discovery agents have interrogated a specific device? 

191


Other Queries 

192 

Has the discovery reported any specific devices? 

What types of device have been discovered? 

The type of information you can retrieve about the discovery is almost unlimited. The more complex your 

queries, the more complex the information you can retrieve. For example: 

You can retrieve information from multiple tables by performing table joins. 

You can perform subqueries (a query within a query). 

Identifying the Status of the Ping Finder 

You can query the pingFinder.status database table of the Ping finder to identify which of the 

devices and subnets in scope have been pinged so far, and which address is currently being pinged. 

In order to start the OQL Service Provider to query the Ping finder databases, use a command similar to the 

following: 

ncp_oql -domain NCOMS -service DiscoPingFinder -username admin 

The pingFinder.status database table schema is given in The Status Database on page 227. The 

following example returns the current address being pinged by the Ping finder: 

|phoenix:1.> select m_CurrentAddress from pingFinder.status; 


. 

{ 

m_CurrentAddress=192.168.0.1; 

} 


|phoenix:1.> 

Interrogating the Databases of DISCO: Simple Database Queries 

This section contains example queries on the databases of DISCO. Definitions of all the databases in this 

section, unless specified otherwise, can be found in Appendix A: The Discovery Databases on page 423. 

Identifying the Current Status of DISCO 

To identify the current operational status of the discovery process, query the disco.status table as 

shown below. 




. 

{ 


m_Phase=1; 





} 


|phoenix:1.> 



The results of the above query show that the discovery process is still in data collection phase 1. The phases 

of the discovery process are described in detail in Discovery Stages and Phases on page 35. 

Identifying the Status of the NAT Discovery 

To identify the current NAT status of the discovery process, query the disco.NATStatus table as 

shown below. 

|phoenix:1.> select m_NATStatus from disco.NATStatus; 


. 

{ 

m_NATStatus=3; 

} 


|phoenix:1.> 

The results of the above query shows that the discovery process is still processing returned NAT translation 

data. For more information on the disco.NATStatus table and NAT discovery, see 

Chapter 12: Managing NAT Environments on page 341. 

Identifying Which Agents Are Enabled 

To identify whether you have correctly enabled the right Discovery agents to run during the discovery 

process, query the disco.agents table as shown below. 

|phoenix:1.> select m_AgentName, m_Valid from disco.agents 

|phoenix:2.> where m_Valid = 1; 


... 

{ 

m_AgentName='Details'; 

m_Valid=1; 

} 

{ 

m_AgentName='AssocAddress'; 

m_Valid=1; 

193


194 

} 

{ 

m_AgentName='IpRoutingTable'; 

m_Valid=1; 

} 

{ 

m_AgentName='IpForwardingTable'; 

m_Valid=1; 

} 


|phoenix:1.> 

The above query returns only the names of the Discovery agents that have been activated. 

Identifying the Status of the Stitchers 

To identify the operational status of the stitchers, query the stitchers.status table as shown below. 

|phoenix:1.> select * from stitchers.status 

|phoenix:2.> where m_State > 0 ; 


......... 

{ 

m_Name='AgentRetToInstrumentationSubnet'; 

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; 

} 


|phoenix:1.> 

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. 


Identifying the Status of the Agents 



To identify the operational status of the Discovery agents, query the agents database as shown below. 

|phoenix:1.> select * from agents.status 

|phoenix:2.> where m_State > 0 ; 


.. 

{ 

m_Name='Details'; 

m_State=3; 

m_NumConnects=1; 

} 

{ 

m_Name='IpRoutingTable'; 

m_State=3; 

m_NumConnects=1; 

} 


|phoenix: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). 

Identifying Which Devices Have Been Found by the Finders 

To learn what devices the finders have found on the network, query the tables of the finders database, for 

example, the finders.returns table, as shown below. 

|phoenix:1.> select * from finders.returns; 


.... 

{ 

m_UniqueAddress='172.20.12.253'; 

m_Protocol=1; 

m_Creator='IpRoutingTable'; 

} 

{ 


m_Protocol=1; 


} 

{ 


m_Protocol=1; 


} 

{ 


m_Creator='PingFinder'; 

195


196 

} 


|phoenix:1.> 

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. 

Identifying Which Devices Have Been Sent to and Returned by the Details 

Agent 

To identify which network entities have been sent to the Details agent for processing, query the 

Details.despatch table as shown below. 

|phoenix:1.> select * from Details.despatch; 


................................................................. 

................................ 

{ 


} 

{ 


} 

..... 

..... 

{ 


} 

{ 


} 

{ 


} 

{ 


} 

{ 


} 


To identify which devices have returned from the Details agent, query the returns table of the Details 

agent, as shown below. 

|phoenix:1.> select * from Details.returns; 


................................................................. 

................................ 

{ 



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_Name='minotaur.Kazeem.San.COM'; 



} 

..... 

..... 

{ 



m_Name='cyclops.Kazeem.San.COM'; 



} 

{ 



m_Name='centaur.Kazeem.San.COM'; 



} 


Identifying the Number of Discovered Devices 



To identify all network entities that are known on the system, query the workingEntities database, 

as shown below. 

|phoenix:1.> select m_Name, m_ObjectId, m_UniqueAddress 

|phoenix:2.> from workingEntities.finalEntity; 


.................................. 

{ 

m_Name='10.10.8.255'; 



} 

{ 



} 

197


198 

..... 

..... 

{ 



} 

|phoenix:1.> select m_Name, m_ObjectId, m_UniqueAddress 



.................................. 

{ 

m_Name='10.10.8.255'; 



} 

{ 



} 

..... 

..... 

{ 



} 

Identifying Which Agents Have Discovered Devices 

To identify which agents have discovered devices on the network, you can specifically query the 

m_Creator column of the workingEntities database, as shown below. 

|phoenix:1.> select m_Name, m_Creator 



.................................. 

{ 

m_Name='b11-m1-2611.Kazeem.San.COM[ 0 [ 2 ] ]'; 


} 

{ 

m_Name='b-ayo.Kazeem.San.COM'; 

m_Creator='Details'; 

} 

{ 



} 

..... 

..... 

{ 


m_Name='b11-m1-2611.Kazeem.San.COM'; 




.................................. 

{ 



} 

{ 

m_Name='b-ayo.Kazeem.San.COM'; 

m_Creator='Details'; 

} 

{ 



} 

..... 

..... 

{ 


Complex Database Queries 



The following more complex queries combine the use of various conditional OQL clauses to narrow down 

the search for more specific information in the DISCO databases. 

Identifying Which Devices Have Been Discovered by a Specific Agent 

You can identify the devices that have been discovered by a specific Discovery agent by focusing on the 

workingEntities database, and making a conditional selection that depends on the m_Creator 

column, as shown below. 


|phoenix:2.> from workingEntities.finalEntity 

|phoenix:3.> where 

|phoenix:4.> m_Creator = 'IpRoutingTable'; 


................................. 

{ 

m_Name='10.10.63.194'; 


} 

{ 



} 

..... 

..... 

199


200 

{ 



} 

{ 



} 


|phoenix:1.> 

The above query shows that the IpRoutingTable agent has discovered 178 devices. 

Identifying Which Devices Have Been Sent to and Returned by a Specific 

Agent 

You can identify the devices that have been discovered by a specific Discovery agent by focusing on the 

database of that particular Discovery agent, as shown below. 

|phoenix:1.> select m_Name, m_ObjectId, m_Description 

|phoenix:2.> from IpRoutingTable.despatch; 


................................. 

{ 

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:'; 

} 


|phoenix:1.> 




You can identify the devices returned by the IpRoutingTable Discovery agent, using the following 

command. 

|phoenix:1.> select m_Name from IpRoutingTable.returns; 


................................. 

{ 

m_Name='10.10.71.248'; 

} 

{ 

m_Name='10.10.71.248'; 

} 

..... 

..... 

{ 

m_Name='10.10.71.248'; 

} 

{ 

m_Name='10.10.71.248'; 

} 


|phoenix:1.> 

The above query shows that the IpRoutingTable agent has discovered 575 devices. 

Identifying Which Additional Devices Have Been Discovered by a Specific 

Agent 

An agent can discover additional devices as a result of 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 shown below. 

|phoenix:1.> select IpRoutingTable.returns.m_Name from 

|phoenix:2.> IpRoutingTable.returns, IpRoutingTable.despatch 

|phoenix:3.> where 

|phoenix:4.> IpRoutingTable.returns.m_Name 

|phoenix:5.> IpRoutingTable.despatch.m_Name; 


.......................................... 

{ 

m_Name='10.10.71.237'; 

} 

{ 

m_Name='10.10.71.247'; 

} 

{ 

m_Name='10.10.71.197'; 

201


202 

} 

..... 

..... 

{ 

m_Name='10.10.71.55'; 

} 

{ 

m_Name='10.10.71.51'; 

} 

{ 

m_Name='10.10.71.30'; 

} 

{ 

m_Name='10.10.71.236'; 

} 


|phoenix:1.> 

Identifying Whether the Discovery Has Located a Specific Device 

If you are interested in knowing whether the discovery process has discovered a specific device (for example, 

a device with the 10.10.63.239 IP address), you can perform the following queries, which are traces 

through the discovery dataflow: 

1. First, determine if the device is present in the workingEntities database, as shown below. 

|phoenix:1.> select * from workingEntities.finalEntity 

|phoenix:2.> where m_UniqueAddress ='10.10.63.239'; 


. 


|phoenix:1.> 

2. If the device is not present in this database, determine if it has been returned from the AssocAddress 

agent, as shown below. 

|phoenix:1.> select * from AssocAddress.returns 

|phoenix:2.> where m_UniqueAddress = '10.10.63.239'; 


. 


|phoenix:1.> 

3. If the device is not present in this database, determine if it has been returned from the Details agent, 

as shown below. 

|phoenix:1.> select * from Details.returns 

|phoenix:2.> where m_UniqueAddress = '10.10.63.239'; 


. 



|phoenix:1.> 



4. If the device has not been returned from the Details agent, then 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. 

|phoenix:1.> select * from Details.despatch 

|phoenix:2.> where m_UniqueAddress='10.10.63.239'; 


. 

{ 


} 


|phoenix:1.> 

5. 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. 

|phoenix:1.> select * from finders.processing 



. 

{ 


} 


|phoenix:1.> select * from finders.returns 



. 


|phoenix:1.> 

Failure to Locate a Specific Device 

If the device is not in any of the above databases, and falls within the scope of the discovery, you must wait 

until the discovery has located the device. If you are only interested in this device, you can set up a more 

restrictive scope for the discovery in order for the device to be discovered more quickly. 

203


Identifying the Number of Discovered Devices of a Given Device Type 

204 

You can determine how many of each type of any device have been discovered on your network by querying 

the tables of the DISCO instrumentation database. The instrumentation database tables store 

a record of every device that has been discovered on the network, including: 

Every unique IP address discovered in the network 

Every device discovered in the network 

Every subnet address and subnet mask discovered in the network 

The ID of every Virtual Local Area Network (VLAN) discovered in the network 

Every Frame Relay device discovered in the network 

Every Cisco Frame Relay device discovered in the network 

Every Hot Standby Router Protocol (HSRP) device discovered in the network 

Every Private Network Node Interface (PNNI) device discovered in the network 

All the Fibre Distributed Data Interface (FDDI) nodes discovered on the network 

Identifying the Number of Discovered Subnets 

The following example query returns details of the discovered subnets. 

|phoenix:1.>select * from instrumentation.subNet; 

|phoenix:2.>go 

....................................... 

{ 

m_SubNet='172.20.67.0'; 

m_NetMask='255.255.255.0'; 

} 

{ 

m_SubNet='172.20.68.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'; 

} 


|phoenix:1.> 


Identifying the Number of Discovered VLANs 

The following example query returns details of the discovered VLAN IDs. 

|phoenix:1.>select * from instrumentation.vlan; 

|phoenix:2.>go 

....................................... 

{ 

m_Vlan=23; 

} 

{ 

m_Vlan=24; 

} 

{ 

m_Vlan=61; 

} 

{ 

m_Vlan=65; 

} 

..... 

..... 

{ 

m_Vlan=677; 

} 


|phoenix:1.> 

Determining Whether the Discovery Has Completed 



In order to determine whether the discovery process has completed, you can query the disco.status 

table, as shown below. 



. 

{ 


m_Phase=1; 





} 


|phoenix:1.> 

205


206 

You can infer the eventual completion of the discovery process by querying the scratchTopology 

database, which serves as the exit point of the network topology to MODEL. For more information, see 

Querying the MODEL Databases on page 363. 


7. Scoping_a_discovery.fm July 5, 2005 

Chapter 7: Scoping a Discovery 

This chapter describes how to define the scope of your discovery using OQL. 


Introduction to Scope on page 208 

Defining Discovery Zones on page 209 

Devices with Out Of Scope Interfaces on page 218 



7.1 Introduction to Scope 

208 

This chapter explains how to restrict the scope of a discovery by appending OQL inserts to the 

DiscoScope.cfg file. 

For full details of the databases discussed in this chapter, see Appendix A: The Discovery Databases on 

page 423. You can also define the scope of the discovery using the Discovery Configuration Tool, as 

described in Chapter 4: Network Discovery Using the Network Discovery GUI on page 85. 

Reasons for Scoping the Discovery 

It is important to limit the scope of a discovery, as the range of IP addresses considered by the default 

discovery process is potentially unlimited. Without modification, the discovery process would attempt to 

discover every device connected to the network. By limiting the scope of the discovery you can concentrate 

on the important areas of your network. 

You might also want to restrict the scope of the discovery in order to control the discovery of sensitive devices 

that you do not want to poll. A given device might be considered sensitive because there is a security risk 

involved in polling the device, or because the act of polling itself might cause the device to overload. 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). 

Types of Scoping 

The Precision Server offers the following types of scoping: 

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. 

Within a given inclusion zone, you can specify devices or subnets that are not to be detected, that is, 

not to be pinged by the Ping finder. These devices are not interrogated by the discovery agents. 

You can configure a filter to determine whether a given device, having been discovered, is to be 

interrogated for connectivity information. 

You can configure a filter that determines whether a device within a defined zone is to be instantiated, 

that is, displayed on the network map. Devices that are not to be displayed on the network map are 

not sent to MODEL. 


7.2 Defining Discovery Zones 


Defining Discovery Zones 

In order to restrict the discovery, you must construct zones by appending an OQL insert into the 

scope.zones table to the DiscoScope.cfg configuration file. 

For each zone you must specify the following information: 

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

shown by the example in Defining Multiple Inclusion Zones on page 210. 

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, but the exclusion 

zones must be within the inclusion zones, otherwise they override the inclusion zones and nothing is 

discovered. 

A list of varbinds (name=value) that define the present discovery zone. 

The following examples demonstrate the creation of inclusion and exclusion zones. 

Defining a Single Inclusion Zone 

An inclusion zone is any zone that you want to be discovered by 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. 


( 

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. 

209


Defining Multiple Inclusion Zones 

210 

In the following example, three different IP inclusion zones are defined within a single insert. 


( 

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. The Precision Server discovers: 

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. 

Any device that falls within the 172.16.3.0 subnet with a mask of 255.255.255.0. 


Defining Exclusion Zones 



An exclusion zone is any zone that you do not want to be discovered by 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. 


( 

m_Protocol, 

m_Action, 

m_Zones 

) 

values 

( 

1, 

2, 

[ 

{ 

m_Subnet="172.16.1.0", 

m_NetMask=24 

] 

); 

Defining 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. 


( 

m_Protocol, m_Action, m_Zones, m_AddressSpace 

) 

values 

( 

1, 

1, 

[ 

{ 

m_Subnet="172.16.2.*", 

} 

], 

"NATDomain1" 

); 

The above example defines one inclusion zone. The Precision Server discovers 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, that 

also belongs to the NAT address space NATDomain1. The protocol is set to 1, that is, IP. 

211


212 

For more information on managing NAT environments, see Chapter 12: Managing NAT Environments on 

page 341. 

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. For more 

details, see Configuring the Ping Finder on page 221. 

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: 

The type of network protocol. Currently only IP is supported. 

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. 

Warning: 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. An example of combining 

multiple filters within a single insert is shown in Combining Multiple Filter Conditions on page 213. 

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. 


( 

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. A full explanation of the syntax of OQL can be found in Appendix B: The Object Query Language 

on page 479. 

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. 


( 

m_Protocol, 

m_Filter 

) 

values 

( 

1, 

"( 


AND 

( m_UniqueAddress '10.10.63.234' ) 

)" 

); 

213


214 

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. 

Restricting Instantiation 

! 

Instantiation refers to the process of associating a device with an Active Object Class. This takes place after 

the network topology is passed to MODEL. It is possible to configure the discovery so that certain devices 

(such as core sensitive devices that you do not wish to poll) are discovered but not passed across to MODEL. 

These devices are not instantiated or displayed in the network topology map. 

In order to restrict the devices that are instantiated you must edit the DiscoScope.cfg configuration 

file and append an OQL insert into the scope.instantiateFilter table. There must only be one 

insert into the scope.instantiateFilter per protocol. The instantiateFilter table 

requires the following information: 

The type of network protocol. Currently only IP is supported. 

The conditional test. Only devices that pass the filter are sent to MODEL. If no filter is defined, all 

discovered devices are passed to MODEL. 

The instantiateFilter works in the same way as the detectionFilter, since a stitcher is 

called to compare discovered devices using the test defined in the scope.instantiateFilter table. 

By default the test is performed after the Scratch Topology has been generated, but before the records are 

sent to MODEL. The conditional test must therefore be based on the columns of the 

scratchTopology.entityByName table. 

Warning: You must ensure that there is only one insert into the scope.instantiateFilter table 

per protocol. Multiple filters must be combined within a single insert in the same way as is done in the 

detectionFilter table. 

The following examples demonstrate the instantiation filter in use. 


Restricting Instantiation Based on Object ID 



The following example shows how you would prevent the instantiation 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 instantiated. 

insert into scope.instantiateFilter 

( 

m_Protocol, 

m_Filter 

) 

values 

( 

1, // The backslash is used here to escape the . 

"( // which would otherwise be treated 

// as a wildcard. 


)" 

); 

A full explanation of the syntax of OQL can be found in Appendix B: The Object Query Language on 

page 479. 

Restricting Instantiation Based on the IP Address 

The following example demonstrates how you might restrict the instantiation of devices based on the IP 

address, by filtering against the m_Addresses column of the scratchTopology.entityByName 

table. The m_Addresses column is a list of the OSI model layer 1-7 addresses for the device. The 

following example filter tests the value of m_Addresses(2), that is, the third entry in the list of addresses 

(list numbering starts at 0). The third entry in the list of addresses is the layer 3 address, that is, the IP address 

of the device. 

The following insert ensures that only devices that pass the filter are instantiated, that is, devices for which 

the IP address is not 172.16.1.231, and is not 172.16.5.47, and does not begin 192.168.123. 


( 

m_Protocol, 

m_Filter 

) 

values 

( 

1, 

"( 

( m_Addresses(2) "172.16.1.231" ) 

AND 

( m_Addresses(2) "172.16.5.47") 

AND 

215


216 

); 

)" 

( m_Addresses(2) not like "192\.168\.123\..*" ) 

You could also restrict instantiation based on other addresses for the device stored in the 

scratchTopology.entityByName.m_Addresses column. For example, 

m_Addresses(1) contains the layer 2 address of the device, that is, the MAC address. 

More Complex Example 

The following example shows a more complex insert, which combines a number of conditions relating to 

different columns of the scratchTopology.entityByName table. 


( 

m_Protocol, 

m_Filter 

) 

values 

( 

1, 

"( 

( m_Addresses(2) = '10.82.219.1' ) 

OR 

( m_Addresses(2) = '10.82.213.5' ) 

OR 

( m_Addresses(2) = '10.82.213.6' ) 

) 

OR 

( 

( m_Name LIKE '[Mm]icro[Mm]use' ) 

AND 

( m_Type < 3 ) 

) 

OR 

( 

( m_Type >= 3 ) 

AND 

( m_Type 7 ) 

)" 

); 




The above insert ensures that only the following devices would be sent to MODEL to be instantiated: 

Any device with the IP address 10.82.219.1, 10.82.213.5 or 10.82.213.6. 

Any device that is not a web server whose name contains the string micromuse (where either m may 

be capitalized) and for which m_Type < 3, that is, an interface or a chassis. 

Any device of m_Type equal to 3, 4, 5, 6 or 8, i.e, a logical interface, VLAN (Virtual Local Area 

Network) object, card, PSU (Power Supply Unit) or module. 

217


7.3 Devices with Out Of Scope Interfaces 

218 

Your network may contain devices that are within the discovery scope but that themselves contain interfaces 

that are out of scope. Since 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 wish 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. Possible configuration adjustments are: 

You can 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 AOC (Active Object Class); therefore the out 

of scope interfaces are not represented on the topology or monitored. 

You can create an AOC with an instantiation filter that matches the out of scope interfaces. The out 

of scope interfaces are therefore discovered and represented in the topology, but instantiated to this 

special AOC. If you configure the AOC to perform no monitoring, you can prevent all the out of 

scope interfaces from being monitored. 


8. Finder_configuration.fm August 16, 2006 

Chapter 8: Using Finders to Seed a Discovery 

This chapter explains how to configure the finders by appending OQL inserts into the appropriate 

configuration files. 


Introduction to the Finders on page 220 

Configuring the Ping Finder on page 221 

Configuring the File Finder on page 228 

Configuring the Sniffer Finder on page 234 

Configuring the Trap Finder on page 236 



8.1 Introduction to the Finders 

220 

Finders are the executables responsible for determining device existence. By default there are four finders, 

each using a different method to find network devices. You can enable the appropriate finders for your 

discovery by configuring them as managed processes of DISCO. Finders configured as managed processes 

are automatically launched at the appropriate time, provided that CTRL is running. 

Each finder to be run must also be configured by editing its configuration file. The finders are described in 

Table 30, with their executable name and the location of their configuration file. 

Table 30: Description of the Finders 

Finder Executable Configuration file Description 

Ping ncp_df_ping NCHOME/etc/precision/ 

DiscoPingFinderSchema.cfg 

File ncp_df_file 

NCHOME/etc/precision/ 

DiscoPingFinderSeeds.cfg 


DiscoFileFinderSchema.cfg 



page 10. 

Multiple Instances 


DiscoFileFinderParseRules.cfg 

Trap ncp_df_trap NCHOME/etc/precision/ 

DiscoTrapFinderSchema.cfg 

Sniffer ncp_df_sniffer NCHOME/etc/precision/ 

DiscoSnifferFinderSchema.cfg 

Makes a simple ICMP echo request for 

broadcast or multicast addresses, 

individual IP addresses, or all devices 

on a subnet. 

Parses a file, such as /etc/hosts, in 

order to find devices on the network. 

Listens for SNMP traps sent by devices. 

Extracts IP addresses and MAC 

addresses from network packets on 

the local subnet. The Sniffer finder can 

handle ARP packets and can be 

expanded to handle other packet 

types if the need arises. 

It is possible to run more than one copy of the same type of finder at the same time. However, you should 

only run multiple copies of the Sniffer finder to listen for packets on different subnets, and multiple copies 

of the File finder, to parse different file systems at the same time. 


8.2 Configuring the Ping Finder 

The Ping finder has two configuration files: 



The DiscoPingFinderSchema.cfg file defines the pingFinder database. You should not 

need to alter this file. 

The DiscoPingFinderSeeds.cfg file contains any configuration inserts into the Ping finder 

databases. 

By appending inserts into the pingFinder database to the DiscoPingFinderSeeds.cfg 

configuration file, you can specify the IP addresses and subnets to be pinged when the Ping finder checks 

for the existence of individual devices. 

General Configuration 

The pingFinder.configuration table specifies the general rules of the ping methodology and 

must only contain one record. 

Table 31: pingFinder.configuration Database Table Schema 


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: 

(1) Enable 

(0) Disable 

m_Multicast Integer Flag used to enable or disable multicast address 

pinging: 

(1) Enable 

(0) Disable 

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. 

221


222 

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. 

Disabling Broadcast and Multicast Address Pinging 

The following example disables broadcast and multicast pinging, specifies 20 threads, a timeout of 250 ms 

and 5 retries. 

insert into pingFinder.configuration 

( m_NumThreads, m_TimeOut, m_NumRetries, m_Broadcast, m_Multicast ) 

values 

( 20, 250, 5, 0, 0 ); 

Enabling Broadcast and Multicast Address Pinging 

The following example enables broadcast and multicast pinging, specifies 20 threads, a timeout of 250 ms 

and 5 retries. 

insert into pingFinder.configuration 

( m_NumThreads, m_TimeOut, m_NumRetries, m_Broadcast, m_Multicast ) 

values 

( 20, 250, 5, 1, 1 ); 

Seeding the Ping Finder 

You must seed the Ping finder by appending OQL inserts into the pingFinder.pingRules table to 

the DiscoPingFinderSeeds.cfg configuration file. An IP address or subnet that you insert into 

the pingRules table becomes the starting point for the Ping finder. 

The pingFinder.pingRules table specifies the different addresses and subnets to be pinged by the 

finder. You can also override some of the settings in the pingFinder.configuration table for 

particular addresses. The pingRules table may contain multiple records. The 

pingFinder.pingRules table is described in Table 32. 

Table 32: pingFinder.pingRules Database Table Schema (1 of 2) 


m_Address PRIMARY KEY 

NOT NULL 

Text The address to ping. 

m_RequestType Integer Flag denoting address type: 

(1) Individual 

(2) Subnet 


Table 32: pingFinder.pingRules Database Table Schema (2 of 2) 




m_NetMask Text The subnet mask. If a value is specified for this field, 

it automatically implies that the address is a subnet 

address. 

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. 

You can specify as many seeds for the Ping finder as necessary. The following are some common examples. 

Seeding Using a Single Device Address 

This example seeds the Ping finder with a single device address. The example does not specify values for 

m_NumRetries and m_TimeOut as they automatically take the default values from the 

configuration table. 


( m_Address, m_RequestType ) 

values 

( "10.10.2.224", 1 ); 

Investigation of Class C Subnet Addresses 

The following examples seed the Ping finder with class C subnet addresses. 


( m_Address, m_RequestType, m_NetMask ) 

values 

( "10.10.2.0", 2, "255.255.255.0" ); 



values 

( "10.10.47.0", 2, "255.255.255.0" ); 

Investigation of a Class B Subnet Address 

The following example seeds the Ping finder with a class B subnet address. 



values 

( "10.10.0.0", 2, "255.255.0.0" ); 

223


Scoping the Ping Finder 

224 

The pingFinder.scope table can be used to configure the way the Ping finder checks whether it is 

allowed to ping a particular device. 

Table 33: pingFinder.scope Database Table Schema 


m_UseScope Integer Flag denoting whether or not to use the entries in the 

scope.zones table when deciding which devices 

to ping: 

(0) The Ping finder ignores the scope.zones table 

when deciding which devices to ping. 

(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: 

If you want to exclude particular devices or subnets from being pinged by the Ping finder, configure an insert 

into the pingFinder.pingFilter table. 

Table 34: pingFinder.pingFilter Database Table Schema (1 of 2) 


m_Address NOT NULL 

PRIMARY KEY 

(0) This is the default value. The Ping finder ignores 

any entries in the pingFinder.pingFilter table 

when deciding which devices can be pinged. 

(1) The Ping finder checks the 

pingFinder.pingFilter table before it pings a 

particular device to see if the device can be pinged. 

Text The IP address of the device or subnet for which you 

want to allow or forbid pinging. 

m_RequestType Integer Possible values are: 

1 = IP 

2 = Subnet 


Table 34: pingFinder.pingFilter Database Table Schema (2 of 2) 


m_NetMask Text Netmask for the given subnet. 



m_ToPing Integer If this is set to 0, the Ping finder cannot ping this 

device/subnet. If this is set to 1, the Ping finder can 

ping this device/subnet. 

Note: When applying settings in the pingFinder.pingFilter table, the Ping finder gives 

precedence to individual IP addresses over subnets. For example, if you disable pinging of a subnet by setting 

m_ToPing to 0 for this subnet, but enable pinging of individual IP addressses within that subnet, then the 

individual IP addresses are pinged. In contrast, if you enable pinging of a subnet but disable pinging of 

individual IP addressses within that subnet, then all devices in that subnet are pinged except for the 

individual devices that you specified. 

No Scoping 

If you configure the Ping finder not to use the scope.zones table or the 

pingFinder.pingFilter table, the Ping finder pings all the devices it has been seeded with, 

regardless of whether they are in scope or not. DISCO still uses the scope.zones table to decide whether 

the discovery agents are allowed to interrogate each device or subnet. To configure the Ping finder not to 

use scoping, use the following insert. 

insert into pingFinder.scope 

( m_UseScope, m_UsePingEntries ) 

values 

( 0, 0 ); 

Using the Discovery Scope 

If you configure the Ping finder to use only the scope.zones table, the Ping finder does not ping devices 

that are out of the discovery scope. To configure the Ping finder to use the discovery scope, use the following 

insert. 



values 

( 1, 0 ); 

225


226 

Using a Custom Scope 

If you configure the Ping finder to use only the pingFinder.pingFilter table, you can specify 

exactly which devices and subnets the Ping finder is allowed to ping. You must ensure that the devices or 

subnets you allow the Ping finder to ping are within the discovery scope; otherwise the discovery agents do 

not discover them, and they are not instantiated to the topology. To configure the Ping finder to use only 

your custom scoping, use the following insert. 



values 

( 0, 1 ); 

Combining the Discovery and Custom Scope 

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 custom scope. To configure the Ping finder to use both 

the scope.zones table and the pingFinder.pingFilter table, use the following insert. 



values 

( 1, 1 ); 

Refreshing Ping Finder Scope 

If you configure the Ping finder to use the discovery scope defined in the scope.zones table, and you 

then run a discovery, the Ping finder uses the scope values that you defined. If you subsequently change the 

scope settings, you need to refresh the Ping finder before running any further discoveries, in order to make 

the Ping finder aware that the scope values have changed. There are two possible scenarios: 

You changed the scope settings using the Network Discovery GUI. In this case DISCO automatically 

refreshes the Ping finder to use the scope values that you defined. 

You changed the scope settings by configuring an OQL insert into the scope.zones table using 

the DiscoScope.cfg configuration file, as described in Scoping the Discovery on page 183. In this 

case, you need to manually refresh the Ping finder to use the scope values that you defined. You do 

this by manually invoking the PingFinderScopeRefresh.stch stitcher. This stitcher 

contains the single command: 

DiscoRefresh(’PingFinder’,’scope’); 

This command updates the Ping finder with the new scope, as defined in the scope.zones table. 




Note: To manually invoke the PingFinderScopeRefresh.stch stitcher, configure an insert 

into the table with the name of the PingFinderScopeRefresh.stch stitcher, as described in 

The actions Table on page 452. 

The Status Database 

The pingFinder.status database table is populated automatically by the Ping finder. You must not 

make inserts into this table. 

Table 35: pingFinder.status Database Table Schema 


m_Address NOT NULL Text The IP address of the device or subnet. 

m_RequestType Integer Possible values are: 

1 = IP 

2 = Subnet 

m_NetMask Text Subnet mask (if appropriate). 

m_Started Boolean Integer Boolean integer indicating whether pinging has 

started for the given device or subnet: 

(1) Pinging has started. 

(0) Pinging has not started. 

m_CurrentAddress Text The current address being pinged. 

m_Completed Boolean Integer Boolean integer indicating whether the Ping finder 

has finished pinging this device or subnet: 

(1) Ping finder has finished pinging this device or 

subnet. 

(0) Ping finder has not finished pinging this device or 

subnet 

227


8.3 Configuring the File Finder 

228 

The File finder has two configuration files: 

The DiscoFileFinderSchema.cfg file defines the fileFinder database. You should not 

need to alter this file. 

The DiscoFileFinderParseRules.cfg file contains any configuration inserts into the File 

finder databases. 

The configuration Table 

The fileFinder.configuration table, described in Table 36, specifies the number of threads to 

be used by the finder. 

Table 36: fileFinder.configuration Database Table Schema 


m_NumThreads NOT NULL Integer The number of threads to be used by the File 

finder. 

The parseRules Table 

The fileFinder.parseRules table, described in Table 37, specifies the rules for file parsing. 

By configuring inserts into the fileFinder.parseRules table, you can specify the files to be parsed 

for a list of IP addresses of devices that exist on the network. 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. 

Table 37: fileFinder.parseRules Database Table Schema 


m_FileName NOT NULL 

UNIQUE 

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 

character. 

m_ColDefs List of atoms A list of rules that specify which variables to extract 

and the columns from which to get them. 


Example Configurations 


Configuring the File Finder 

The following examples show OQL statements you could append to the File finder configuration file. 

Files to Parse and Rules for Parsing 

You can append inserts into the fileFinder.parseRules table in order to specify the files to be 

parsed and the rules for parsing. The usual files you would parse are /etc/defaultrouter and 

/etc/hosts, although the File finder can parse any text file. You can append multiple inserts to the 

DiscoFileFinderParseRules.cfg configuration file to define multiple files to be parsed. 

Example One 

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-micromuse 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 may be multiple tabs, spaces or a combination of both. 

You could configure the File finder to parse this example text file using an insertion similar to the following: 

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 

} 

229


230 

); 

] 

The above insert specifies that: 

The full path and name of the file is /var/tmp/logged_hosts. 

The source file delimiter is white space. The column delimiter is indicated in the insert using a simple 

regular expression, [ tab space ]+ . You must explicitly press the tab and space keys rather 

than entering \t to represent the tab character. 

The first column contains IP addresses and must be mapped to the m_UniqueAddress column of 

the DISCO finders.returns table. 

The second column contains host names and must be mapped to the m_Name column of the 

DISCO finders.returns table. 

Since 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. 

Example Two 

The following insert instructs the File finder to: 

Parse /etc/hosts. 

Treat white space as the data separator. 

Use the following column definitions: 

– m_UniqueAddress for the first column 

– m_Name for the second column 


( 

m_FileName, 

m_Delimiter, 

m_ColDefs 

) 

values 

( 

"/etc/hosts", 

"[ ]", 

[ 

{ 


m_ColNum=1 

}, 

{ 


); 


] 

Example Three 

} 

m_VarName="m_Name", 

m_ColNum=2 

The following insert instructs the File finder to: 

Parse /etc/defaultrouter. 

Treat one or more occurrences of white space as the data separator. 

Use m_UniqueAddress as the column definition. 


( 

m_FileName, 

m_Delimiter, 

m_ColDefs 

) 

values 

( 

"/etc/defaultrouter", 

"[ ]+", 

[ 

{ 


m_ColNum=1 

} 

] 

); 

General Operation 

The following example OQL insert configures the File finder to use 5 threads. 

insert into fileFinder.configuration 

( m_NumThreads ) 

values 

( 5 ); 


231


Verifying the Existence of a Device Reported by the File Finder 

232 

Since the function of the File finder is to parse a file for IP addresses and device names, you may wish to 

verify that a device reported by the File finder actually exists before sending the details to the Details agent. 

By default, Netcool/Precision IP does not verify the existence of the devices specified in the flat file that you 

supply to the File finder. This section explains how to do this. 

CASE 1: Well Maintained Seed File 

If you are sure of the integrity of the seed file, and can be sure that a device listed in the parsed file exists, 

you can adopt the default discovery configuration, in which any device discovered by the File finder is 

accepted without checking and sent to the Details agent. The default process flow is shown in Figure 78. 

Figure 78: The Well Maintained Seed File 

This default discovery configuration, by which any device discovered by the File finder is accepted without 

checking, is controlled by the default setting of m_CheckFileFinderReturns to 0 in the 

disco.config table, as described in Table A8 disco.config Database Table Schema on page 431. 

CASE 2: Badly Maintained Seed File 

If you have reason to doubt that the devices reported by the File finder are still connected to the network, 

possibly because of a rapidly changing network, you can configure the discovery so that any device 

discovered by the File finder is automatically checked by the Ping finder. If the Ping finder cannot contact 

the device, it is discarded, eliminating the unnecessary processing of a nonexistent device by the Details 

agent. 




Note: If you do not configure the Ping finder to check the existence of devices in your seed file, then when 

the discovery is complete, any non-existent devices listed in the seed file will appear in the topology. These 

non-existent devices will be monitored and will always fail attempts to ping them, because they do not exist. 

For this reason you should ensure that the seed file contains reliable information. 

Configure the discovery so that the File finder is automatically checked by the Ping finder, by setting 

m_CheckFileFinderReturns to 1 in the disco.config table. You can do this by appending 

the following insert to the DiscoSchema.cfg file: 


( 

m_CheckFileFinderReturns, 

) 

values 

( 

1, 

); 

For more information , see Table A8 disco.config Database Table Schema on page 431. 

233


8.4 Configuring the Sniffer Finder 

234 

The Sniffer finder configuration file DiscoSnifferFinderSchema.cfg defines the 

snifferFinder database. 

The Configuration Table 

The snifferFinder.configuration table specifies parameters for the Sniffer finder. 

Table 38: snifferFinder.configuration Database Table Schema 


m_NumThreads Integer The number of threads to be used by the Sniffer finder. 

m_Looptimes Integer The number of packets to be captured per cycle before 

passing control back to the main program. The default 

value is 200. 


The following example shows OQL insertion statements that you would append to the configuration file in 

order to configure the Sniffer finder. 

insert into snifferFinder.configuration 

( 

m_NumThreads, 

m_LoopTimes, 

m_Interfaces 

) 

values 

( 

1, 

200, 

["hme0"] 

); 

Although capturing more packets may be desirable, it 

impairs the system response time; a small delay occurs 

when the process is terminated—the larger the number of 

packets, the longer this delay. 

m_Interfaces List of text The interface to look for packets on. The default value is 

hme0. 


The above example configures the Sniffer finder to: 

Use one thread. 

Capture a maximum of 200 packets per cycle. 

Listen for packets on the interface hme0. 

Sniffing Multiple Interfaces 

The following example configures the Sniffer finder to listen to multiple interfaces. 

insert into snifferFinder.configuration 

( m_NumThreads, m_LoopTimes, 

m_Interfaces ) 

values 

( 1, 200, ["hme0", "hme1", 

"hme2"] ); 


Configuring the Sniffer Finder 

235


8.5 Configuring the Trap Finder 

236 

The Trap finder discovers devices by listening for SNMP traps and extracting IP addresses from those traps. 

The different types of traps are described in Table 39. 

Table 39: Table of Traps and Their Descriptions 

Number Name Description 

0 coldStart trap A coldStart trap signifies that the sending protocol entity is 

reinitialising itself such that the agent's configuration or the protocol 

entity implementation may be altered. 

1 warmStart trap A warmStart trap signifies that the sending protocol entity is 

reinitialising itself such that neither the agent configuration nor the 

protocol entity implementation is altered. 

2 linkDown trap A linkDown trap is generated by the failure of a recognized 

communication link. 

3 linkUp trap A linkUp trap is generated when a communication link that was 

formerly down comes alive. 

4 authenticationFailure trap An authenticationFailure trap is generated by a protocol message that 

has not been authenticated by the recipient, for example, an incorrect 

password. 

5 egpNeighborloss trap An egpNeighborLoss trap signifies that an Exterior Gateway Protocol 

(EGP) neighbor for whom the sending protocol entity was an EGP peer 

has been marked down and the peer relationship is no longer valid. 

6 enterprise-specific trap An enterprise-specific trap signifies that the sending protocol entity 

recognizes that an enterprise-specific event has occurred. 

The Trap finder configuration file DiscoTrapFinderSchema.cfg defines the trapFinder 

database. 

The configuration Table 

The trapFinder.configuration table specifies parameters for the Trap finder. 

Table 40: trapFinder.configuration Database Table Schema (1 of 2) 


m_NumThreads Integer The number of threads to be used by the Trap finder. 


Table 40: trapFinder.configuration Database Table Schema (2 of 2) 





m_TrapPort Integer The port to listen on for traps. The default value is set to 

port 162. 

m_SourceByPayload Default = 1 Integer Configures the way in which the trap source address is 

retrieved: 

The following example shows OQL statements to append to the configuration file in order to configure the 

Trap finder: 

insert into trapFinder.configuration 

( 

m_NumThreads, 

m_TrapPort, 

m_SourceByPayload 

) 

values 

( 

1, 

162, 

1 

); 

The above example configures the Trap finder to: 

Use 1 thread. 

Listen for traps on port 162. 

Attempt to retrieve the trap source address from the payload. 

(0) Retrieve the trap source address from the IP header. 

(1) Retrieve the trap source address from the payload, if 

possible, or the IP header if there is no address in the 

payload. 

237


238 


9. Discovery_Agents.fm July 6, 2005 

Chapter 9: Discovery Agents 

This chapter describes the discovery agents, the processes that discover device connectivity information. The 

information in this chapter helps you choose which discovery agents to run during a discovery. This chapter 

also describes advanced configuration such as retrieving extra information from devices, and discovering 

SPVCs. 


Introducing the Agents on page 240 

Types of Agent on page 242 

Enabling and Disabling the Agents on page 265 

Selecting Agents To Run on page 267 

Discovering Device Protocols on page 271 

Filtering Devices Sent to the Agents on page 272 

Partial Matching on page 276 

Retrieving Extra Information on page 278 

Discovering SPVCs on page 284 



9.1 Introducing the Agents 

240 

The discovery agents retrieve information about devices on the network. 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. 

In addition to the main discovery agents, which can be enabled or disabled according to your discovery 

requirements, there are two special agents that must always be run: the Details agent and the Associated 

Address agent. These special agents are described in this section. 

Note: The out-of-the-box 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 

stop analyzing devices that do not provide the data they require as soon as possible. This means that running 

a large number of agents increases network traffic by a very small amount only. 

The Details Agent 

This agent is triggered by the entries in finders.processing. Therefore, at least one finder will be 

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. 

See Figure 4 on page 27 for an illustration of the process flow of the Details agent. 

The Associated Address (AssocAddress) Agent 

This mandatory agent is triggered by, and is dependent upon, the output of the Details agent. The SNMP 

helper configuration for associated devices is a prerequisite for running this agent. 



Introducing the Agents 

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. See 

Figure 6 on page 29 for an illustration of the process flow of the Associated Address agent. 

Discovery Agent Databases 

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: 

agentName.despatch 

agentName.returns 

For full details about the database tables of each discovery agent, see Subprocess Databases on page 454. 

241


9.2 Types of Agent 

242 

The agents supplied with the Precision Server can be divided into the categories listed in Table 41. 

Table 41: Types of Agent 

Type of Agent Description of Agent Type More Details 

Agents that discover 

Ethernet switch 

connectivity 


layer 3 connectivity 


connectivity between 

Asynchronous Transfer 

Mode (ATM) devices 


MPLS devices 


NAT Gateways 


containment 

information 

Other protocol-specific 

agents 

Agents that discover connectivity information 

between Ethernet switches. 

Agents that retrieve connectivity information from 

OSI model layer 3 (the Network Layer), which is 

responsible for routing, congestion control, and 

sending messages between networks. 

Asynchronous Transfer Mode (ATM) is an alternative 

switching protocol designed 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. 

Agents specialized to retrieve MPLS (Multiprotocol 

Label Switching) data from different kinds of devices 

using a variety of protocols. 

Agents that download NAT (Network Address 

Translation) information from known NAT gateways. 

An important principle used by the network model 

is containment. A container holds other objects, 

such as chassis, interfaces and cards. You can put 

any object within a container and even mix different 

objects within the same container. This section 

describes the Entity agent, which queries the MIB for 

each entity and retrieves containment information 

for that entity. 

Agents that discover devices that use other 

protocols. 

Context agents Agents that take part in a context-sensitive 

discovery. For information on enabling a 

context-sensitive discovery, see Context-Sensitive 

Discovery on page 33. 

Task-specific agents Agents that perform a specific task within a 

discovery. 

Note: This section specifies which agents are not configured to ru n out-of the-box. 

Discovering Connectivity between 

Ethernet Switches on page 243 

Connectivity at the Layer 3 Network Layer 

on page 249 

Discovering Connectivity between ATM 

Devices on page 252 

Discovering MPLS Devices on page 254 

Discovering NAT Gateways on page 256 

Discovering Containment Information 

on page 258 

Discovery Agents on Other Protocols on 

page 259 

Context Agents on page 261 

Task-specific Discovery Agents on 

page 261 


Before enabling these agents, it may be necessary to configure SNMP or Telnet access. 

Configure SNMP as follows: 


Types of Agent 

– Configure SNMP access to devices, as described in Configuring SNMP Device Access on 

page 298. 

– Configure threads, timeout, and number of retries for the SNMP Helper, as described in 

Configuring the SNMP Helper on page 292. 

Configure Telnet as follows: 

– Configure Telnet access to devices, as described in Configuring Telnet Device Access on page 303. 

– Configure the Telnet Helper to understand device output, as described in Configuring the 

SNMP Helper on page 292. 

Discovering Connectivity between Ethernet Switches 

Discovery agents that discover connectivity information between Ethernet switches have three main 

operational stages: 

1. Gain access to the switch and download all the switch interfaces. 

2. Discover VLAN information for the switch. 

3. Download the forward database table for the switch. 

A list of the discovery agents designed to handle Ethernet switches is shown in Table 42. 

243


244 

Note: Before enabling these layer 2 agents, it is necessary to configure SNMP access, as described at the 

beginning of the section Types of Agent on page 242. Some agents also require Telnet access and Telnet 

Helper configuration. This is specified where required. 

Table 42: Ethernet Switch Discovery Agents (1 of 5) 

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. 

AlcatelSwitch The AlcatelSwitch agent contains the specialized methods for retrieving 

connectivity information from Alcatel routing switches that were formerly 

Xylan devices. 

BayEthernetHub Before enabling this agent, it is necessary to configure the SNMP Helper, as 

described at the beginning of the section Types of Agent on page 242. 

The BayEthernetHub agent discovers hub cards manufactured by Bay. 

Connectivity information is downloaded from the hub and the connectivity is 

resolved by the HubFdbToConnections stitcher. 

CentillionSwitch The CentillionSwitch agent contains the methods 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 containing distributed management 

modules. 

ChipcomEthernetMM The ChipcomEthernetMM agent is appropriate for Chipcom online 

concentrators containing Ethernet Management Modules (EMMs), and 

discovers the Ethernet connectivity of Chipcom EMMs. 






CiscoSRP The CiscoSRP agent discovers the connectivity of networks using the Spatial 

Reuse Protocol (SRP), that is, DPT Ring topologies. SRP is a layer 2 protocol 

developed by Cisco that uses ‘side’ information to identify adjacent 

neighbours 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 those supported by the 

CiscoSRPTelnet agent. The agent only accepts 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 Before enabling this agent, it is necessary to configure Telnet access and the 

Telnet Helper, as described at the beginning of the section Types of Agent on 

page 242. 

The CiscoSRPTelnet agent discovers the connectivity of networks using the 

Spatial Reuse Protocol (SRP), that is, DPT Ring topologies. SRP is a layer 2 

protocol developed by Cisco that uses ‘side’ information to identify adjacent 

neighbours 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 only accept Cisco devices that have an IOS known not to 

support the CISCO-SRP-MIB and those IOS versions that have known 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. 

CiscoSwitchSnmp The CiscoSwitchSnmp agent contains the specialized methods for retrieving 

information from Cisco switches using SNMP. This agent uses a variety of 

methods for finding VLANs and card or port to ifIndex mappings because 

different Cisco switches store this information in different MIB variables. 

245


246 



CiscoSwitchTelnet Before enabling this agent, it is necessary to configure SNMP and Telnet access 

and the respective Helpers, as described at the beginning of the section Types 

of Agent on page 242. 

The CiscoSwitchTelnet agent contains specialized methods for retrieving 

connectivity information from Cisco switches using Telnet. This agent uses a 

variety of 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 using telnet. All other information 

is downloaded using SNMP. 

The Telnet commands used to obtain the FDB table are show cam dynamic 

and show mac-address table. 

Some devices might require enable mode in order to run the show 

mac-address table command. 

Corebuilder3ComSwitch The Corebuilder3ComSwitch agent discovers links for the CoreBuilder 9000 

layer 3 switches manufactured by 3Com. 

DasanSwitchTelnet Before enabling this agent, it is necessary to configure Telnet access and the 


page 242. 

The DasanSwitchTelnet agent is responsible for the discovery of the layer 2 

connectivity held 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 only run against devices with a sysObjectID of 

1.3.6.1.4.1.6296.* and that support the command show vlan. 

DefaultEthernetHub This agent has a specialized class for dealing with semi-intelligent hubs. 

ExtremeSwitch The ExtremeSwitch agent obtains layer 2 connectivity information, EDP 

neighbours, 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: 

enable snmp access 

enable dot1dFdbTable 

This configuration change is only required on switches running a version of 

ExtremeWare® prior to 6.1.8. 






FoundrySwitch The FoundrySwitch agent discovers switch connectivity of any Foundry device 

that supports the IEEE 802.1q or IEEE 802.1d standards, as modelled in the 

Q-BRIDGE-MIB and BRIDGE-MIB SNMP MIBs respectively. 

The agent definition file is configured to accept all SNMP-enabled Foundry 

devices by default. The agent will only discover 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 only support IEEE 802.1d and, as a consequence, no 

VLAN information is discovered for these devices. 

HuaweiSwitchTelnet Before enabling this agent, it is necessary to configure Telnet access and the 


page 242. 

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. Failure to 

complete these sections will result in the agent failing. 

Certain telnet commands have the side-effect of changing the command 

prompt of a Huawei device. For example, the command prompt: 

becomes 

[device_name] or 

[device_name-diag] when certain commands are issued. 

It is essential that the parameters m_ConPrompt and m_PrivConPrompt in 

TelnetStackPasswords.cfg are configured to cope with these 

variations. 

HPSwitch The HPSwitch agent contains the specialized methods for retrieving 

connectivity information from HP ProCurve switches, including the download 

of enterprise-specific VLAN information. 

MACFromArpCache The ArpCache agent must be enabled for this agent to run. 

The MACFromArpCache agent is optionally activated in phase 3 of Discovery. It 

uses the ArpCache information retrieved by the ArpCache agent to retrieve the 

MAC address of the device. The agent is useful as it does not require SNMP 

access to the device to obtain the MAC address. 

247


248 



Marconi3810 The Marconi3810 specialised agent discovers the Ethernet connectivity of 

Marconi ES-3810 switches running operating system version 4.x.x and 5.x.x. 

This agent also removes connectivity from LANE interfaces by default - this can 

be configured using the GetElanData flag in the .agnt file. 

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 

neighbours and have SecureFast operating mode turned on. 

This agent is sent to all Cabletron and Enterasys devices, 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 modelled in the Q-BRIDGE-MIB and BRIDGE-MIB SNMP MIBs 

respectively. 

Devices in SecureFast mode do not support the dot1dBridge MIBs. 

SuperStack3ComSwitch The SuperStack3ComSwitch agent finds the connections in stacked switches 

manufactured by 3Com. 

XyplexEthernetHub The XyplexEthernetHub agent discovers the layer 2 connectivity of intelligent 

hubs manufactured by Xyplex. 


Connectivity at the Layer 3 Network Layer 



There are a number of discovery agents that are specifically designed to retrieve connectivity information 

from OSI model layer 3 (the Network Layer) that is responsible for routing, congestion control, and sending 

messages between networks. These agents are shown in Table 43. 

Table 43: Routing Protocol Discovery Agents (1 of 4) 


CiscoBGPTelnet Before enabling this agent, it is necessary to configure Telnet access and the Telnet 

Helper, as described at the beginning of the section Types of Agent on page 242. 

The CiscoBGPTelnet agent downloads BGP information from Cisco routers. It is not 

enabled in the out-of-the-box configuration because it gathers a very specific piece of 

information only, that is, whether devices are route reflectors. 

ExtremeESRP Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. 

Interfaces Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. The returned variables can be added to, or subtracted 

from, by altering 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. 

IpRoutingTable Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


The IpRoutingTable agent 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. 

249


250 



IpForwardingTable Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. 

IpBackupRoutes Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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 in the out-of-the-box configuration 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. 

ISISExperimental Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


The ISISExperimental agent 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. 

TraceRoute Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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 in 

the out-of-the-box configuration 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. 

CiscoFrameRelay Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. 






HSRPSnmp Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. 

AlteonVRRP Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. 

FoundryVRRP Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


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. 

RFC2787VRRP Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


The RFC2787VRRP agent downloads VRRP information from routers running 

RFC2787-compliant VRRP, and supporting the RFC2787 VRRP MIB. Some Nokia firewalls 

support this MIB. 

VRRP is not modelled for RCA. This agent only sets tags on VRRP interfaces that show 

the state at the time of the discovery. 

There are two subtlety different versions of the VRRP MIB. They contain the same 

names but with different OIDs. If this agent does not work, try switching the VRRP MIB 

over to the other version. Nokia firewalls can run both versions of the MIB. 

251


252 



StandardBgp Before enabling this agent, it is necessary to configure SNMP access and the SNMP 

Helper, as described at the beginning of the section Types of Agent on page 242. It is 

also necessary to configure the Ping Helper as described in Configuring the PING Helper 

on page 291. 

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: 

Autonomous System IDs 

BGP Peer connections to external peers (EBGP) 

BGP Peer connections to internal peers (IBGP) 

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: 

GetPeerData – determines whether the agent should acquire BGP Peer data 

(activated by default). 

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. 

NokiaVRRP Before enabling this agent, it is necessary to configure SNMP access and the SNMP 


This agent 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: 

vrrpOperState 

vrrpOperMasterIpAddr 

vrrpAssoIpAddrRowStatus 

Discovering Connectivity between ATM Devices 

Asynchronous Transfer Mode (ATM) is an alternative switching protocol designed 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, as 


Table 44: ATM Discovery Agents (1 of 2) 


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. 

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, ATM device that is certified by Micromuse. 

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: 

Connections between ASX series switches and SE420/SE440 IADs are only discovered using 

ILMI. 

Connections between Cisco routers or switches containing ATM cards and an ATM core are 

only discovered using ILMI. 

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 by the Precision Server. 

253


254 

Table 44: ATM Discovery Agents (2 of 2) 


MariposaAtm The MariposaAtm agent discovers the ATM connectivity of the SE420 and SE440 Integrated 

Access Devices (IADs). 

Discovering MPLS Devices 

Note: The Ethernet switching and Frame Relay capabilities of these devices are not currently 

certified by Micromuse. 

PnniForeSys SNMP helper configuration for associated devices is a prerequisite for this agent. The 

AtmForumPnni agent must also be active. 

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 in order to retrieve the actual ifIndex, which is held within the 

ifTable . 

The agents shown in Table 45 on page 255 are specialized to retrieve MPLS (Multiprotocol Label 

Switching) data from different kinds of devices using different protocols. For more details on these agents, 

see Chapter 11: Configuring an MPLS Discovery on page 325, which includes the following information 

necessary when configuring MPLS agents: 

Configuring SNMP and Telnet access to MPLS devices, as described in Configuring MPLS Agents and 

SNMP and Telnet Access on page 329 

Optionally specifying which VPNs and VRFs to discover, as described in Defining the Scope of an 

MPLS/VPN Discovery on page 333 

Specifying whether to perform route target-based (RT-based) or label switch path-based (LSP-based) 

MPLS discovery, as described in Configuring MPLS Discovery Method on page 330 




The agents that retrieve MPLS data use either TELNET or SNMP to retrieve the data. Before enabling the 

MPLS agents, ensure that you first configure Telnet and SNMP access as follows: 

Before enabling the MPLS agents that use TELNET, ensure that you have configured TELNET to 

enable the agents to access devices and to understand device output, as described in Configuring 

Telnet on page 331. 

Before enabling the MPLS agents that use SNMP, ensure that you have configured SNMP to enable 

the agents to access devices and to specify threads, timeouts, and number of retries, as described in 

Configuring SNMP on page 332. 

Table 45: MPLS Discovery Agents 


CiscoMPLSSnmp The CiscoMPLSSnmp agent discovers MPLS paths on Cisco devices that have the Cisco 

Experimental MPLS MIBs enabled. 

CiscoMPLSTelnet The CiscoMPLSTelnet agent discovers MPLS paths on Cisco devices. 

JuniperMPLSTelnet The JuniperMPLSTelnet agent discovers MPLS paths on Juniper devices. 

LaurelMPLSTelnet The LaurelMPLSTelnet agent discovers MPLS paths on Laurel devices. This agent is intended for 

route target-based discoveries only. 

UnisphereMPLSTelnet The UnisphereMPLSTelnet agent discovers MPLS paths on Juniper ERX routers (formerly 

Unisphere). 

Deduplicating Identical IP Addresses in Different VPNs 

During an MPLS discovery, Netcool/Precision IP may discover devices in different VPNs with identical IP 

addresses. In this case Netcool/Precision IP is unable to differentiate between these devices and may resolve 

device connectivity incorrectly. The devices in question may be the CE routers at the edge of the VPNs or 

may be devices within the VPNs. 

To overcome this problem, activate the AsAgent agent and provide Netcool/Precision IP with a mapping 

file, ASMap.txt. In this file provide a complete list of devices in each VPN, together with an 

AddressSpace tag, which defines which VPN the device belongs to. Table 46 provides a description of 

the AsAgent agent. 

Table 46: AsAgent Agent 


AsAgent Enables Netcool/Precision IP 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. 

255


256 

Table 47 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 47: 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 

Discovering NAT Gateways 

Table 48 lists the agents that download NAT (Network Address Translation) information from known 

NAT gateways. For more details, see Chapter 12: Managing NAT Environments on page 341. 

Note: None of the agents listed in Table 48 is enabled in the out-of-the-box configuration. This is because 

these agents require advanced configuration and thus it is preferable not to enable it by default. 

Table 48: NAT Gateway Agents (1 of 2) 


CiscoNATTelnet Before enabling this agent, it is necessary to configure Telnet access and the Telnet Helper, as 


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. 


Table 48: NAT Gateway Agents (2 of 2) 


Configuring NAT Gateway Management Interfaces 



NATNetScreen Before enabling this agent, it is necessary to configure Telnet access and the Telnet Helper, as 


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. 

NATTextFileAgent Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


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. 

DISCO assumes that the management interface of the NAT gateway is in public address space. If this is not 

the case then Netcool/Precision IP is not able to identify the address space of interfaces on the NAT gateway 

device. This may result in incorrect connectivity. An example of a situation where the NAT gateway 

management interface is not in public address space is when a VPN is used to access the management 

interface. 

To overcome this problem, activate the NATGateway agent and provide Netcool/Precision IP 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. Table 49 provides a description of the NATGateway agent. 

Table 49: NATGateway Agent 


NATGateway Enables Netcool/Precision IP 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. This agent works in conjunction with the 

NATGatewayRetProcessing.stch stitcher and with the NATGateways.txt file in 

NCHOME/precision/etc. 

257


258 

Table 50 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 50: 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 

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. 

The Entity agent queries the MIB for each entity and retrieves containment information for that entity. 

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 as follows: 

Chassis 

Interface 

Logical interface 

Vlan object 

Card 

PSU 

Logical collection, such as a VPN 

Module 

There is also an Unknown category, which covers entities for which no part type has been defined. 

Note: Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


Running the Entity agent during a discovery is entirely optional. Some containment information will be 

gathered during a discovery even if the Entity agent is not run. You should run the Entity agent if you wish 

to model physical containment and perform asset management. You can find more information on 

containment in About the Containment Model on page 359. 




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. 

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 Sensor, Power, Asset, and Module 

entities. Do this by setting the following variables in the Entity.agnt file: 

GetSensorData 

GetPowerData 

GetModuleData 

GetAssetData 

In each case, specify that you wish to get the data by setting a value of 1. Specify that you do not wish to get 

the data by setting a value of 0. 

Note: The Entity.agnt file, together with all other agent configuration files, can be found in the 

NCHOME/precision/disco/agents directory. Note that NCHOME is the environment variable 

that contains the path to the Netcool Suite home directory. For information on how this environment 

variable varies with platform, see Operating System Considerations on page 10 

Discovery Agents on Other Protocols 

Table 51 lists the agents that discover devices that use other protocols to the ones described so far in this 

section. 

Table 51: Discovery Agents on Other Protocols (1 of 2) 


AlteonStp Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


This is a Spanning Tree Protocol discovery agent for Alteon switches that support the dot1dStp 

section of the BRIDGE-MIB. 

CDP Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


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. 

259


260 

Table 51: Discovery Agents on Other Protocols (2 of 2) 


CiscoOSPFTelnet Before enabling this agent, it is necessary to configure Telnet access and the Telnet Helper, as 


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. 

FddiDefault Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


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 Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


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. 

StandardOSPF Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


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. 

StandardSTP Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


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: 

Hidden Links – STP backup (blocking) connections are discovered. 

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. 


Context Agents 

! 



Table 52 lists the agents that take part in a context-sensitive discovery. For information on enabling a 

context-sensitive discovery, see Context-Sensitive Discovery on page 33. 

Warning: When a context-sensitive discovery is enabled, the discovery process automatically chooses the 

correct Context agent for any particular device. For this reason, you should not manually enable or disable 

Context agents, either through the configuration files or through the Discovery Configuration GUI. 

Note: These agents require Telnet access and the Telnet Helper, as described at the beginning of the section 

Types of Agent on page 242. 

Table 52: Context Agents 

Agent Name Function 

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. 

Task-specific Discovery Agents 

Table 53 lists task-specific discovery agents. 

Table 53: Task-specific Discovery Agents (1 of 4) 


You can restrict the scope of the VRF contexts discovered by configuring the optional 

DiscoAgentDiscoveryScoping section in the .agnt file. The configurable options 

are the following: 

IncludeVRF – allows the discovery of the named VRF. 

ExcludeVRF – does not discover the specified VRF. 

VRF names are case-sensitive. The wildcard "*" may 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. 

AlliedTelesynATSwitch Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The AlliedTelesynATSwitch agent discovers Ethernet switches made by Allied Telesyn. 

AlteonSwitch Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


This agent retrieves layer 2 connectivity information from Alteon load balancers. 

261


262 



ARPCache Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The ARPCache agent assists in populating the Helper Server with IP to MAC address 

mappings in preparation for the Ethernet-based discovery agents. 

You must run this agent if you are running a layer 2 discovery. This agent is optional if you 

are running a layer 3 discovery. However, it can be more efficient to use the ARP Cache 

discovery agent because in most network environments the ARP helper can only run on one 

subnet at a time. 

ASM Determines whether Netcool/ASMs for the following commercial server and database 

products are running on a device: 

Oracle 

Apache 

Microsoft SQL Server 

Microsoft Exchange 

Microsoft Internet Information Server (IIS) 

Microsoft Active Directory 

IBM WebSphere 

BEA WebLogic 

SAP 

Sybase ASE 

IBM Lotus Notes/Domino Server 

The ASM agent determines whether an application is running by querying 

Netcool/ASM-specific MIBs for the device. These MIBs are installed by default when you 

install Netcool/Precision IP. 

The ASM agent can only retrieve this information from network devices on which 

Netcool/ASM is deployed. Typically, you would deploy a Netcool/ASM sub-agent on each 

commercial server and database product which is running on a device and whose 

performance you wish to monitor. For more information on Netcool/ASM, see the 

Netcool/SSM Administration Guide. 

CM Retrieves data from cable modems connected to a cable modem terminating services 

device. 

Note: If activated, this agent retrieves a large amount of information. Activating this agent 

may therefore place a heavy load on memory. You should only activate this agent if specific 

cable modem information is required beyond that provided by other agents. 




CMTS Discovers cable modem terminating services devices. This agent also discovers cable 

modem connectivity. 



Note: If activated, this agent retrieves a large amount of information. Activating this agent 

may therefore place a heavy load on memory. You should only activate this agent if specific 

cable modem information is required beyond that provided by other agents. 

ExtraDetails Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The ExtraDetails agent is a text-based agent that builds on the basic SNMP information 

already retrieved by the Details agent. 

This agent retrieves the following information: 

sysDescr 

sysLocation 

sysUpTime 

sysServices 

ifNumber 

HPNetworkTeaming Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The HPNetworkTeaming agent discovers secondary NICs on HP Proliant Teamed network 

cards. 

If this agent is not enabled, only the primary NIC on an HP Proliant device will be discovered 

(as a local neighbour to the server) because only this NIC resides in the ifTable. This agent 

will create all NICs as local neighbours to the server. 

IfStackTable Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The IfStackTable determines the interface stacking hierarchy on devices that support 

the RFC 2863 MIB. 

JuniperERXIfStackTable Before enabling this agent, it is necessary to configure Telnet access and the Telnet Helper, 

as described at the beginning of the section Types of Agent on page 242. 

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. 

263


264 



LoopbackDetails Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The LoopbackDetails agent is used to ensure that the management interface of a device is 

used in the topology andin subsequent monitoring as the main IP/name combination. The 

agent retrieves information needed to identify the management interfaces. This data is then 

used in the NamingFromLoopbackDetails stitcher. 

SSM Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The SSM agent retrieves MIB information by SNMP from devices running Netcool/SSM 

agents. This agent retrieves information such as the software installed on the device, 

running processes, CPU utilization, storage devices on this entity, free disk space, and so on. 

The SSM agent can only retrieve this information from network devices on which the 

Netcool/SSM Agent is deployed. Typically, you would deploy a Netcool/SSM Agent on 

devices whose performance you wish to monitor. For more information on the Netcool/SSM 

Agent, see the Netcool/SSM Application Guide. 

SSMOracle Before enabling this agent, it is necessary to configure SNMP access and the SNMP Helper, as 


The Netcool/SSM application and the Oracle monitoring package must also be running. 

The SSMOracle agent retrieves MIB information by SNMP from devices running Netcool/SSM 

agents. This agent retrieves information such as the Oracle database names, fields, and 

database sizes. 

The SSMOracle agent can only retrieve this information from network devices on which the 

Netcool/SSM Agent is deployed. Typically, you would deploy a Netcool/SSM Agent on 

devices whose performance you wish to monitor. For more information on the Netcool/SSM 

Agent, see the Netcool/SSM Application Guide. 


9.3 Enabling and Disabling the Agents 


Enabling and Disabling the Agents 

By specifying whether or not a given discovery agent is to run during a discovery, you can perform 

layer-specific, protocol-specific, and device-technology-specific discoveries. This section explains how to 

enable and disable the discovery agents by configuring OQL inserts into the DiscoAgents.cfg 

configuration file. For a quick reference guide to the agents that must be run for a given type of discovery, 

see Selecting Agents To Run on page 267. The discovery agents can also be enabled and disabled using the 

Discovery Configuration Tool, as described in Chapter 4: Network Discovery Using the Network Discovery 

GUI on page 85. 

Enabling and Disabling the Discovery Agents Prior to a Discovery 

The AssocAddressRetProcessing.stch stitcher determines which discovery agents are active by 

evaluating the records in the disco.agents table. The stitcher also ensures that only the agents for 

which disco.agents.m_Valid is set to 1 are allowed to run during the discovery. 

Setting a Discovery Agent to Be Active 

In order to ensure that a discovery agent is active, locate the relevant insertion in the DiscoAgents.cfg 

file and ensure that the m_Valid column is set to one. The following example activates the 

IpRoutingTable discovery agent. 


( 


) 

values 

( 

'IpRoutingTable', 1, 0, 0, 2 

); 

The following example OQL inserts activate the Details and Associated Address agents. 


( 


) 

values 

( 

'Details', 1, 0, 0, 1 

); 


( 


) 

values 

265


266 

( 

); 

'AssocAddress', 1, 0, 0, 2 

Enabling the ARP Cache Agent 

The ARP Cache agent is designed to assist in MAC address to IP address resolution during the discovery 

process. You must ensure that this agent is running during a layer 2 discovery by ensuring that the insert 

into the disco.agents table has its m_Valid column set to 1 before starting the discovery. 


( 


) 

values 

( 

'ArpCache', 1, 0, 0, 2 

); 

The ArpCache agent is optional but recommended for layer 3 discoveries. Setting the ArpCache agent status 

to active ensures that the DetailsRetProcessing stitcher passes entities across to the ArpCache 

agent, which helps to speed up the discovery process. 

Setting a Discovery Agent to Be Inactive 

In order to ensure that the discovery agents that you do not want to run are disabled, locate the insertions 

for these agents in the DiscoAgents.cfg file and ensure that the m_Valid column is set to 0. The 

following example deactivates the StandardSwitch and the SuperStack3ComSwitch discovery agents. 


( 


) 

values 

( 

'StandardSwitch', 0, 1, 1, 3 

); 


( 


) 

values 

( 

'SuperStack3ComSwitch', 0, 1, 1, 3 

); 


9.4 Selecting Agents To Run 


Selecting Agents To Run 

This section provides a guide to selecting the right agents for your discovery. Criteria are given for selecting 

which IP layer and standard agents to run. 

If your network uses non-IP protocols such as CDP, ATM, or MPLS, you should also read Discovering 

Device Protocols on page 271 and Chapter 11: Configuring an MPLS Discovery on page 325. If you need to 

discover devices with virtual routers, you should also read Context-Sensitive Discovery on page 33. 

Which IP layer Agents to Use 

The IP layer agents that you need to use depend on the devices on your network: 

If you do not want to have your IP routing tables accessed, you must only use the IpBackupRoutes 

agent. 

This agent is not used by default as it has the following drawbacks: 

– It retrieves data from a table that is not dynamic. If the router has not been refreshed, then the 

data retrieved by this agent may be spurious. 

– The table is large and therefore takes a long time to download. 

If there are modern devices on the network, you must use the IpRoutingTable agent and the 

IpForwardingTable agent. 

These agents provide an accurate picture of IP layer connectivity and are therefore used by default. 

Which Standard Agents To Use 

The standard agents that you need to use depend on the information you require and the devices on your 

network: 

The TraceRoute agent can be used if there is a firewall on the network, since SNMP calls cannot 

always be made through firewalls. If you use the TraceRoute agent, you must specify, as a discovery 

seed, the subnet node for the subnet on the other side of the firewall. 

The ArpCache agent retrieves the physical address of a device, so is only required (in conjunction 

with the Switch agents) when performing layer 2 discoveries. 

Frame Relay agents should be run in conjunction with the IP layer agents if you need to add DLCI 

information to the interfaces of Frame Relay devices. 

Switch agents must be run for a layer 2 discovery. 

The device-specific and protocol-specific agents are only required to discover the devices or protocols 

to which they relate. 

267


Which Specialized Agents To Run 

268 

Several agents included with the Precision Server need only be run if you need to discover certain device 

types or network technologies. These agents are only available if the appropriate option was selected at install 

time. You can install any of the specialized agents into an existing Netcool/Precision IP installation by 

running the installation script again and selecting the appropriate options. For more information, see the 

Netcool/Precision IP Installation and Deployment Guide. 

The specialized agents that you need to run depend on the devices and protocols in your network: 

The Extreme agent can be used to extract layer 2 connectivity information, EDP neighbors, and 

VLAN details from Extreme switches. 

The ExtremeESRP agent discovers Extreme Standby Routing Table information from Extreme 

routing switches. 

The PnniForeSys agent discovers physical ATM connections between devices by using the PNNI 

(Private Network-to-Network Interface) connectivity information provided by the Marconi ASX 

series switches. 

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 

switches. 

The CellPath90 agent discovers the ATM connection of a CellPath 90 WAN (Wide Area Network) 

multiplexer. 

The Marconi3810 agent discovers the Ethernet connectivity of the ES-3810 switches running 

operating system version 4.x.x. 

The MariposaAtm agent discovers the ATM connectivity of the SE420 and SE440 IADs. 

Note: The Ethernet switching and Frame Relay capabilities of these devices are not currently certified 

by Micromuse. 

The ILMI agent discovers connectivity between ATM devices running ILMI that support the ATM 

Forum's ATM MIB. The CiscoPVC agent retrieves PVC data from Cisco devices. 

The AtmForumPnni agent discovers connectivity between devices running ATM Forum PNNI that 

correctly support the ATM Forum's PNNI MIB. 

For Cisco devices, run the CiscoMPLSSnmp agent if you have the MPLS MIBs enabled on a device, 

otherwise, use the CiscoMPLSTelnet agent. 



Selecting Agents To Run 

For Juniper devices, run the JuniperMPLSTelnet agent if you wish to discover MPLS paths. 

For Juniper ERX devices (formerly Unisphere), the UnisphereMPLSTelnet agent must be used to 

discover MPLS paths, as these devices are sufficiently different to the Juniper "M" series routers that a 

different agent is required. 

Suggested List of Agents for a Layer 3 Discovery 

This section gives you a list of which agents you should run for a layer 3 discovery. The exact choice of agents 

depends on your network. 

Tip: Some routers support layer 2 technologies. For example, when an ATM card is located in a router 

chassis, layer 3 discovery agents, such as the IpRoutingTable agent, only discover interfaces with an IP 

address. Therefore, in order to fully discover all the interfaces on routers that support layer 2 technologies, 

you must run the appropriate agents, as listed under Suggested List of Agents for a Layer 2 Discovery below. 

When running a layer 3 discovery, the following agents must be run: 

Details and AssocAddress 

A combination of the following IP layer agents: 

– IpRoutingTable 

– IpBackupRoutes 

– IpRoutingTable and IpForwardingTable 

HSRP 

VRRP 

TraceRoute (if firewalls are present) 

Suggested List of Agents for a Layer 2 Discovery 

This section provides a list of agents that you should run for a layer 2 discovery. The exact choice of agents 

depends on your network. 

269


270 

When running a layer 2 discovery, the following agents must be run: 

Details and AssocAddress 

A combination of the following IP layer agents: 

– IpRoutingTable 

– IpBackupRoutes 

– IpRoutingTable and IpForwardingTable 

Switch 

FrameRelay 

ArpCache 

ATM 

FDDI 

HSRP 

VRRP 

MPLS 


9.5 Discovering Device Protocols 


Discovering Device Protocols 

In order 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. Some examples of device protocols that are supported 

by the Precision Server are: 

Frame Relay 

Private Network-Network Interface (PNNI) 

Cisco Discovery Protocol (CDP) 

Hot Standby Routing Protocol (HSRP) 

Fibre Distributed Data Interface (FDDI) 

Asynchronous Transfer Mode (ATM) 

Integrated Local Management Interface (ILMI) 

Multiprotocol Label Switching (MPLS) 

Example: Discovering Devices that Use CDP 

The CDP discovery agent, defined in the NCHOME/precision/disco/agents/CDP.agnt agent 

file, must be enabled prior to beginning the discovery in order to discover devices that use CDP. You can 

enable the CDP agent by ensuring that the value of the m_Valid column is set to 1, as shown in the 

following insert. 


( 


) 

values 

( 

'CDP', 1, 7, 0, 3 

); 

Configuring Extreme Devices 

In order to achieve a detailed layer 2 discovery, ensure that your Extreme devices are configured to enable 

SNMP access and dot1dFdbTable population. This configuration change should only be required on 

switches running a version of ExtremeWare ® prior to 6.1.8. To do this, send the following commands to 

each Extreme device: 

enable snmp access 

enable dot1dFdbTable 

271


9.6 Filtering Devices Sent to the Agents 

272 

In the default discovery data flow, devices that have been found by the finders are sent to the Details agent, 

which retrieves basic device details. The device is then sent to the Associated Address agent, which checks 

that the device has not already been discovered using another interface, and downloads all the associated IP 

addresses. 

The AssocAddressRetProcessing stitcher distributes the details of devices that have not already been 

discovered to the appropriate discovery agent. If an agent has no filter defined, it accepts any device that is 

sent to it, although you can configure the agent filters if necessary. The following reasons explain why you 

might want to filter the devices that a given discovery agent processes: 

To speed up the discovery process. By reducing the range of devices an agent has to consider, you 

reduce the amount of processing that agent has to perform. 

To avoid the processing of sensitive devices. 

To restrict certain devices to a particular discovery agent. 

Introduction to the Discovery Agent Filter 

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 

The supported devices filter is a filter against the attributes of the agentTemplate.despatch table, 

so you can filter against attributes such as those listed in Table 54. 

Table 54: Columns of the agentTemplate.despatch Table (1 of 2) 

Column name Description 

m_Name The unique name of the network entity. 

m_UniqueAddress The unique IP address of the network entity. 

m_Protocol The protocol of the discovered device. 

(1) IP 

(2) IP-NAT 

m_ObjectId The device class (a textual representation of an ASN.1 address). 


Table 54: Columns of the agentTemplate.despatch Table (2 of 2) 

Column name Description 


Filtering Devices Sent to the Agents 

m_SnmpAccessIP If present, this column overrides the IP address used for SNMP access to devices using 

the Helper Server. 

m_HaveAccess A flag indicating whether SNMP access to the device is available: 

The DiscoAgentSupportedDevices( ); section accepts full OQL comparison tests using 

comparison operators such as like, < , > , = , and , as demonstrated by the examples in the following 

section. Detailed information about comparison tests in OQL can be found in Appendix B: The Object 

Query Language on page 479. 

As shown by the examples below, when using the like operator, backslashes must be used to escape the . 

character, which would otherwise be treated as a wildcard. 

Example Filters 

(1) Have Access 

(0) No Access 

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\..*' ) 

AND 

( m_ObjectId '1.3.6.1.4.1.9.1.226' ) 

) " 

); 

The following example shows a configuration for the CoreBuilder3ComSwitch.agnt definition 

file. This agent only accepts devices with the Object ID 1.3.6.1.4.1.2272.2. 


( 

" ( m_ObjectId = '1.3.6.1.4.1.43.1.9.13.3.1' ) " 

); 

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. 


( 

273


274 

); 

" ( m_UniqueAddress like '10\.10\.2\..*' ) " 

The following example shows the combination of multiple filter conditions. The agent only accepts devices: 

With the Object ID 1.3.6.1.4.1.9.5.7. 

With an IP Address beginning 10.10. 

That do not have the name clandestine. 


( 

"( 

( 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].*' ) 

)" 

); 

Tip: Altering agent definition files can introduce parse errors.To check your agent for parse errors, you can 

run the agent in debug mode and examine the debug output. The following example shows one way to do 

this. 

Example: Running a discovery agent in debug mode 

If you have defined a poll using your stitcher with the key MYSTITCHER, you can use the following 

command to run ncp_timedstitcher in full debug mode and pipe the output to a file named 

mydebug.out: 

ncp_m_timedtstitcher -domain TEST -latency 100000 -service Monitor2ObjServ -debug 4 

-key MYSTITCHER >&mydebug.out& 

Note: This command uses csh under UNIX. You should use the appropriate equivalent for your system. 

Internal Filtering 

In addition to the supported devices filter, most agents perform additional internal filtering to ensure they 

can operate appropriately on the devices passed to them. The default supported devices filters of most agents 

are inclusive, sending all devices from potentially supported vendors to the agent. The agents check for the 

required MIB variables and do not process the device if the required information is not available. 



Filtering Devices Sent to the Agents 

Tip: Keeping your supported devices filter reasonably inclusive helps to ensure that a particular agent can 

handle new devices that are not radically different but that have different OIDs with no additional 

configuration. 

275


9.7 Partial Matching 

Examples 

276 

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 make any modifications to the 

discovery agent definition files in order 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. 

In order 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. 

The following example could be appended to the IpForwardingTable.agnt definition file to disable 

partial matching on discovered devices for which m_ObjectId='1.3.6.1.4.1.9.1.209' (that is, 

Cisco 2600 routers). 

DiscoRouterPartialMatchRestrictions 

( 

"(m_ObjectId='1.3.6.1.4.1.9.1.209')" 

); 

Specifying the IOS Revision in Which Partial Matching Is Supported 

If necessary, you can also specify the IOS (Internetwork Operating System) revision in which partial 

matching is supported for a given type of router. The following example ensures 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 only attempted if the router is running IOS version 12.2 or higher. The value assigned to 

m_MibVar indicates the MIB variable from which the IOS revision can be determined, that is, in this case 

the IOS revision can be determined by retrieving the sysDescr variable from the device. 


( 

"(m_ObjectId='1.3.6.1.4.1.9.1.48', m_OSVersion>='12.2', 

m_MibVar='sysDescr')" 

); 


Wildcards 


Partial Matching 

You can use wildcards in conjunction with the like operator as shown by the following example. The 

following example ensures that partial matching is not used by any device for which the Object ID begins 

with 1.3.6.1.4.1.2773, that is, Redstone devices. When using the like operator, backslashes must 

be used to escape the . character. 


( 

"(m_ObjectId like '1\.3\.6\.1\.4\.1\.2773\..*')" 

); 

Combining Partial Match Restrictions 

You can combine as many partial match restrictions as necessary, separating the restrictions using commas. 

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. 


( 

"(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\..*')" 

); 

277


9.8 Retrieving Extra Information 

278 

It is possible to configure the discovery agents to retrieve extra information from devices and store this 

information in the ExtraInfo column of the topology database. In order to specify that extra information 

be retrieved by a given discovery agent, you must 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 must be made to the agent definition are described in the following sections. 

Changing the Agent Type 

The start of the discovery agent definition file identifies the type of agent. This can be one of the following: 

DiscoCompiledAgent{}, which indicates that this is a compiled discovery agent (with a 

corresponding shared library in the NCHOME/precision/lib directory). 

DiscoDefinedAgent{}, which indicates that this is a text-based discovery agent (with no 

corresponding shared library). 

DiscoCombinedAgent{}, which indicates that this discovery agent 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. 

In order 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{}. 

The Mediation and Processing Layers 

The process of retrieving extra information from devices and adding 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 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 

{ 



} 

Retrieving Extra Information 

// 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). 

} 

The Mediation Layer Filter 

The mediation layer filter is an optional filter that restricts the SNMP requests for extra information to 

specific devices. If you include a condition within the DiscoMediationSnmpGetFilter{} section 

within the DiscoAgentMediationFilter{}, then 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 Mediation Layer 

The structure of the mediation layer, where the actual SNMP and ICMP requests are performed, is shown 

below. 

DiscoAgentMediationLayer 

{ 

DiscoSnmpRequests 

{ 

DiscoSnmpGetResponse( ARGUMENT, VARIABLE ); 

DiscoSnmpGetNextResponse( ARGUMENT, VARIABLE, ); 

DiscoSnmpGetAccessParameters( VARIABLE ); 

} 

DiscoICMPRequests 

{ 

DiscoICMPGetTrace( VARIABLE ); 

} 

} 

279


280 

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. 

If 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. 

DiscoSnmpGetResponse(); 

DiscoSnmpGetResponse(); performs an SNMP Get request. The simple form of this rule takes two 

arguments, separated by a comma. The first 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 ); 

DiscoSnmpGetAccessParameters(); 

DiscoSnmpGetAccessParameters(); retrieves the SNMP access parameters for the device, as 

shown by the following example. 

DiscoSnmpGetAccessParameters( "m_AccessParam" ); 

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. 


DiscoICMPGetTrace(); 



DiscoICMPGetTrace(); retrieves the IP addresses in the path to the device, as shown by the following 

example. 

DiscoICMPGetTrace( "m_Trace" ); 

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. 

The Processing Layer 

The processing layer is where the retrieved information is added to the entity records. The structure of the 

processing layer is shown below. Both the DiscoAgentProcLayerAddTags{} and 

DiscoAgentProcLayerAddLocalTags{} sections are optional (although if both are omitted, no 

extra information is stored in the database records). 

DiscoAgentProcessingLayer 

{ 

DiscoAgentProcLayerAddTags 

{ 

DiscoAddTagSnmpGet( KEY ); 

DiscoAddTagSnmpGetNext( KEY ); 

DiscoAddTagSnmpGetAccessParameters( 

"m_AccessParam" ); 

DiscoAddTagTrace( "m_Trace" ); 

} 

DiscoAgentProcLayerAddLocalTags 

{ 

DiscoAddTagSnmpGet( 

TAG FROM KEY WHERE CONDITION ); 

DiscoAddTagSnmpGetNext( 

TAG FROM KEY WHERE CONDITION ); 

} 

} 

281


282 

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 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 as follows. 

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 as follows: 

TAG specifies the field name of the tag to be added. 

KEY indicates the key assigned to the value returned in the mediation layer. 

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) ) 

); 

Special Case: Adding Information to the master.entityByNeighbor Table 

If you configure a discovery agent to download any of the MIB variables listed in Table 55 and add those 

variables to the entity under the corresponding names, then they are used to populate the corresponding 

columns in the MODEL master.entityByNeighbor table. These columns can only be populated 

for entities that contain the RelatedTo field, that is, entities that are related to other entities. 

Table 55: Variables Used to Populate the master.entityByNeighbor Table 

MIB variable Name under which variable must be configured to be added to entity Column to be populated 

ifSpeed m_IfSpeed Speed 

ifRelType m_IfRelType RelType 

ifProtocol m_IfProtocol Protocol 

ifDuplex m_IfDuplex Duplex 

283


9.9 Discovering SPVCs 

284 

The spvc.pl script can be used to trace SPVCs on your network. To use this script you must also have 

the Perl API component ncp_perl installed. 

Once you have run a discovery, you can run the SPVC script using the following command, substituting 

your domain name where Precision is specified: 

ncp_perl NCHOME/precision/scripts/perl/scripts/spvc.pl -domain 

Precision 

SPVC Script Process Flow 

Once started, the SPVC script runs through the following steps: 

1. The script begins by loading ATM-specific MIB information from the 

NCHOME/precision/mibs directory. 

2. When prompted, enter the name of a discovered ATM device from which you want to start tracing 

an SPVC. If you enter an invalid name, or the name of a device that has not been discovered, the 

script exits. 

3. The script retrieves and displays the interface details for the specified device. When prompted, enter 

the number of the interface that you are interested in. 

4. The script retrieves and displays details of the VPI (Virtual Path Identifier) and VCI (Virtual Channel 

Identifier) pairs for the specified interface. 

5. When prompted, enter the details of the pair of interest in the following format: VPI.VCI. For 

example, to trace the path of VPI 0 and VCI 37, enter 0.37. 

6. The script now traces the path of the SPVC. When the script has completed tracing the SPVC, the 

connections on the path in both directions are listed on the screen. The script also populates the Path 

Tool in ncp_desktop with the SPVC information. For information on using the Precision 

Desktop to view SPVC paths, see the Netcool/Precision IP Desktop Guide. 


10. Helper_system.fm July 6, 2005 

Chapter 10: The Discovery Helper System 

This chapter introduces the Helper System, a subsystem of DISCO that is used to retrieve device 

information from the network. 


Introduction to the Helper System on page 286 

Starting the Helper Server on page 288 

Configuring the Helpers on page 289 

SNMP and Telnet Device Access Configuration on page 298 

The Helper Databases on page 307 

Connecting to Helpers on Different Subnets on page 319 

Communication Between DISCO and the Helper Server on page 321 



10.1 Introduction to the Helper System 

The Helpers 

286 

This chapter describes the Helper System and the configuration adjustments you might want to make to it. 

Configuring the Helper System can help to speed up network discovery, and is for advanced users only. 

Although the discovery agents are responsible for retrieving 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. 

The helpers are specialized applications that retrieve information from the network on demand. They have 

no understanding of the retrieved information. 

The helpers retrieve information from devices and deposit the information in the Helper Server for retrieval 

by the agents. By default there are five helpers, which are described in Table 56. 

Table 56: Helpers Available with Netcool/Precision IP 

Helper Executable Configuration file Description 

ARP ncp_dh_arp NCHOME/etc/precision/ 

DiscoARPHelperSchema.cfg 

DNS ncp_dh_dns NCHOME/etc/precision/ 

DiscoDNSHelperSchema.cfg 

PING ncp_dh_ping NCHOME/etc/precision/ 

DiscoPingHelperSchema.cfg 

SNMP ncp_dh_snmp NCHOME/etc/precision/ 

DiscoSnmpHelperSchema.cfg 


SnmpStackSchema.cfg 


SnmpStackSecurityInfo.cfg 

TELNET ncp_dh_telnet NCHOME/etc/precision/ 

DiscoTelnetHelperSchema.cfg 


TelnetStackPasswords.cfg 


TelnetStackSchema.cfg 

Performs IP address to MAC address 

resolution. 

Performs IP address to device name 

resolution. 

Either pings each device in a subnet, an 

individual IP address or a broadcast or 

multicast address. The result of the ping 

could be used to populate the MIB of the 

device. 

Returns results of an SNMP request such 

as Get, GetNext and GetBulk. 

Returns the results of a Telnet operation 

into a specified device. 



Introduction to the Helper System 



page 10. 

Helper System Operation 

At startup, the Helper Server loads up the Helper Server schema from the 

DiscoHelperServerSchema.cfg configuration file and creates the appropriate helper databases. 

The Helper Server also creates a Helper Manager for every helper database. 

The Helper Manager is responsible for managing the way in which the helper handles requests from the 

Helper Server to retrieve network device data. The Helper Manager specifies: 

The request timeout 

The time to live for the returned variables 

Whether multiple requests are to be processed in serial or parallel 

When the Helper Manager detects a request for network data from the Helper Server, it instructs the 

associated helper to retrieve the data from the network. 

Dynamic Timeouts 

The Helper System uses dynamic timeouts to handle network requests. For example, if the SNMP helper 

has been asked to perform a long list of SNMP Get requests, the helper might begin to slow down and 

therefore exceed the timeout. A static timeout would cause the retrieval of data to terminate (with data lost) 

despite the fact that the device is still responding with data. To prevent this situation, the helpers incorporate 

a dynamic timeout system in which they take note of long SNMP Get requests and recalculate and update 

the timeout as the SNMP daemons of the device begin to slow down. 

287


10.2 Starting the Helper Server 

288 

It is good practice to configure the Helper Server to be started automatically by CTRL at the appropriate 

time, by making the appropriate OQL insertion into the services.inTray table of CTRL. 

Alternatively, you can start the Helper Server manually using the following command line. Optional 

arguments are shown enclosed in square brackets: 

ncp_d_helpserv –domain DOMAIN_NAME [ -debug DEBUG ] [ -help ] [ -version ] 



-domain DOMAIN_NAME The name of the domain under which to run the Helper Server. 

-debug DEBUG The level of debugging output (1-4, where 4 represents the most detailed 

output). 

-help Displays the command line options. Does not start the component even if used 

in conjunction with other arguments. 



Starting the Helpers 

Provided that the Helper Server is launched by CTRL, the individual helpers are automatically started as 

and when they are required. For more information about CTRL, see Chapter 2: Process Control with CTRL 

on page 47. 

The only situation in which you might need to configure an insert for an individual helper into the 

disco.managedProcesses table would be if you wanted to start that helper on a remote machine 

(that is, a machine other than the one that is running the Helper Server). In this situation you would 

explicitly insert the required helper into the disco.managedProcesses table, specifying the 

appropriate remote host in the m_Host field. 


10.3 Configuring the Helpers 

The default configuration is sufficient for most networks. However, you may decide to alter the 

configuration for the following reasons: 


Configuring the Helpers 

In order to speed up the discovery process, you could reduce the helper timeouts and number of 

retries. 

If you have a very reliable network in which devices respond quickly, you can specify a small default 

timeout. 

You may 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. 

In order to reduce the amount of network traffic caused by a discovery, you could increase the 

timeout and disable broadcast and multicast pinging. 

Configuring the ARP Helper 

You can configure the ARP helper by appending OQL inserts to the DiscoARPHelperSchema.cfg 

configuration file. The ARPHelper database consists of the configuration table, described in 

Table 58. 

Table 58: 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. 

Example Configuration of the ARP Helper 

The following example insert configures the ARP helper to use one thread. 

insert into ARPHelper.configuration 

( 

m_NumThreads 

) 

values 

( 

1 

); 

289


Configuring the DNS Helper 

290 

You can configure the DNS helper by appending OQL inserts to the DiscoDNSHelperSchema.cfg 

configuration file. The DNSHelper database consists of the configuration table, described in 

Table 59, which must only contain one record, and the methods table, described in Table 60. 

Table 59: DNSHelper.configuration Database Table Schema 


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. 

m_TimeOut Integer The maximum time to wait for a response from a device 

(seconds). 

Table 60: DNShelper.methods Database Table Schema 


m_MethodName PRIMARY KEY 

NOT NULL 

UNIQUE 

Example Configuration of the DNS Helper 

The following example inserts configure the DNS helper using the tables described above. 

insert into DNSHelper.configuration 

( 

Text The name of the method. 

m_MethodType Integer The type of the method: 

(0) System 

(1) DNS 

(2) File 

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_NameDomain Text Domain name; for example, micromuse.com. 

m_FileName Text The filename, if appropriate. 

m_FileOrder Integer The order of the files: 

(0) Name first, then IP address 

(1) IP address, then name 

m_TimeOut Integer Time out for the request in seconds. 


m_NumThreads, m_MethodList, m_TimeOut 

) 

values 

( 

1, ['HostsFile'] , 5 

); 

insert into DNSHelper.methods 

( 

m_MethodName, m_MethodType, m_FileName, m_FileOrder 

) 

values 

( 

'HostsFile', 2, 'etc/hosts', 1 

); 

Configuring the PING Helper 



You can configure the PING helper by appending OQL inserts to the 

DiscoPingHelperSchema.cfg configuration file. The pingHelper database consists of the 

configuration table, described in Table 61, which must only contain one record. 

Table 61: pingHelper.configuration Database Table Schema 



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_NumRetries Integer The number of times a device is to be re-pinged. 

m_InterPingTime Integer The time interval in milliseconds between 

successive ping attempts of subnet addresses. 

m_Broadcast Integer Flag used to enable or disable broadcast address 

pinging: 

(1) Enable 

(0) Disable 

m_Multicast Integer Flag used to enable or disable multicast address 

pinging: 

(1) Enable 

(0) Disable 

291


292 

Although pinging broadcast and multicast addresses allows devices to be discovered quicker than other 

detection methods, it is sometimes less desirable to do so under certain network conditions; for instance, 

when the network is heavily congested. 

Example Configuration of the Ping Helper 

The following insert configures the Ping helper to: 

Use 20 threads of process execution. 

Wait a maximum of 250 ms for a reply from a device. 

Retry unresponsive devices a maximum of five times. 

Wait 50 ms between pinging devices in a subnet. 

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 

); 

Configuring the SNMP Helper 

You can configure the SNMP helper by appending OQL inserts to the 

DiscoSnmpHelperSchema.cfg configuration file. The snmpHelper database specifies the general 

rules of SNMP information retrieval. It consists of the configuration table, described in Table 62, 

which must only contain one record. 

Table 62: snmpHelper.configuration Database Table Schema 



m_TimeOut Integer The maximum time to wait for a reply from a device, 

in milliseconds. 

m_NumRetries Integer The number of attempts to retrieve SNMP variable(s) 

from a device. 


Example Configuration of the SNMP Helper 

The following example configuration causes the SNMP helper to behave as follows: 



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. 

A three second timeout period is allowed 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, up 

to a maximum of one (m_NumRetries) times. 

insert into snmpHelper.configuration 

( 

m_NumThreads, 

m_TimeOut, 

m_NumRetries, 

) 

values 

( 

1 20, 3000, 1 

); 

Configuring the Telnet Helper 

You can configure the Telnet helper using OQL inserts to the DiscoTelnetHelperSchema.cfg 

configuration file. The telnetHelper database consists of two tables: the configuration table, 

described in Table 63, and the deviceConfig table, described in Table 64. 

You can configure the Telnet helper to use the Secure Shell (SSH) program. SSH enables authentication and 

provides more secure communications over the network. For more information, see Configuring Telnet 

Device Access on page 303. 

The configuration table specifies the general rules of receiving information from remote devices. 

Table 63: telnetHelper.configuration Database Table Schema 


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. 

293


294 

The deviceConfig table sets device-specific configuration options. 

Table 64: telnetHelper.deviceConfig Database Table Schema 


m_SysObjectId 

optional 

Text 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_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_PageLengthCmd Text The command to issue in order to set the output page length. 

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_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_ContinueCmd Text 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_TransmissionDelay Integer This option allows you to customise 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. 


Configuring the Telnet Helper 



The following insert can be appended to the DiscoTelnetHelperSchema.cfg configuration file to 

configure the operation of the Telnet helper. 

insert into telnetHelper.configuration 

( 

m_NumThreads, 

m_TimeOut, 

m_Retries 

) 

values 

( 

20, 

5000, 

3 

); 

The above insert configures the Telnet helper to: 

Use 20 threads of process execution. 

Wait a maximum of 5000 ms for a reply from a device. 

Retry the request up to 3 times. 

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. 

This section provides examples of 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 usually vary with the device vendor. Therefore by setting these options 

based on the sysObjectID MIB variable and hence based on the vendor, you are able to configure values, 

for all Cisco devices, for example, regardless of where these devices are in the network. 

Example Configuring Settings for Devices from a Specific Vendor 

The following is a typical example configuration and shows how to configure settings for all devices from a 

specific vendor: 

insert into telnetHelper.deviceConfig 

( 

m_SysObjectId, 

m_PageLengthCmd, 

295


296 

) 

values 

( 

); 

m_PageLength, 

m_ContinueMsg, 

m_ContinueCmd 

"1.3.6.1.4.1.9.1.", "terminal length", 0, ".*[Mm]ore.*", " " 

The above insert configures: 

1.3.6.1.4.1.9.1. as the the sysObjectID MIB variable to match for this configuration 

entry. All devices with OIDs of the form 1.3.6.1.4.1.9.1.* will be matched. In general, these 

are Cisco IOS devices, although there are exceptions. 

‘terminal length’ is the command that sets the output page length for Cisco devices. 

Note: This command varies with devices of different vendor types. 

No paging. 

Prompt from remote device. 

The response to send to the remote device for it to continue paged output. 

The DiscoTelnetHelperSchema.cfg configuration file contains inserts with default 

device-specific configuration settings for the following vendor types 

Cisco IOS devices 

Cisco Cat OS devices 

Juniper JUNOS devices 

Juniper ERX devices 

Huawei devices 

Dasan devices 

The following example configures device settings based on an IP address: 

Example Configuring Device Settings Based on an IP Address 

insert into telnetHelper.deviceConfig 

( 

m_IpOrSubNet, 

m_NetMaskBits, 

m_PageLengthCmd, 


) 

values 

( 

); 

m_PageLength, 

m_ContinueMsg, 

m_ContinueCmd 

192.168.112.0, 24, "set length", 0, ".*wish to continue.*", "y" 

The above insert configures: 

192.168.112.0 as the IP address. 

‘set length’ (default value) sets the output page length. 

No paging. 

Prompt from remote device. 

The response to send to the remote device for it to continue paged output. 



297


10.4 SNMP and Telnet Device Access Configuration 

298 

The SNMP helper, the Telnet helper, and other components such as MONITOR require SNMP or Telnet 

access to devices in order to perform their function. This section describes how to configure inserts into the 

device access databases. Any Netcool/Precision IP components that require SNMP or Telnet access use the 

settings from these databases. In this section, the SNMP helper and the Telnet helper are used as 

representative examples of these processes. 

Configuring SNMP Device Access 

Netcool/Precision IP components such as the SNMP helper that require SNMP access use two SNMP 

device access and password configuration files to gain access to devices on the network: 

SnmpStackSchema.cfg defines the snmpStack database. You should not need to alter this 

file. 

SnmpStackSecurityInfo.cfg contains any necessary inserts into the snmpStack 

database. All the inserts given in this section must be contained within this file. 

Community strings can be configured on a per-device or per-subnet basis, to allow the SNMP helper to 

retrieve MIB variables from devices. 

The database that contains the security configuration is called the snmpStack database. It contains the 

following tables: 

configuration 

verSecurityCache 

verSecurityTable 

accessParameters 

These tables are described in the following sections. 



SNMP and Telnet Device Access Configuration 

The configuration table, described in Table 65, controls the general operation of the SNMP helper. 

Table 65: snmpStack.configuration Database Table Schema 


m_AutoVersion Externally defined 

Boolean data type 

m_AllowOQL Externally defined 


The SNMP helper caches the community strings used to access the devices during a discovery in the 

snmpStack.verSecurityCache table. This allows subsequent discoveries to proceed faster as the 

SNMP access parameters are already known. It also reduces the number of authentication traps that can be 

generated when searching for the correct access parameters. 

The access parameters are cached in the following location: 

SnmpStack.Cache.snmpStack.verSecurityCache.DOMAIN 

Boolean Integer Flag controlling automatic SNMP versioning: 

(1) Use automatic SNMP versioning. The SNMP 

helper initially attempts to use SNMP V3 for device 

access; if unsuccessful, it uses SNMP V2, then SNMP 

V1. 

(0) Do not use automatic versioning. The SNMP 

helper ignores the entries in the versions table. 

Boolean Integer Flag controlling OQL access to the SnmpHelper 

database: 

(1) Allowed OQL access to the cached community 

strings for the devices discovered. 

(2) Do not allow OQL access. 

m_ExpireAfter Long The time, in seconds, after which to expire the 

cached community string for device if it has not 

been used. The default value of zero does not 

expire cache community strings. 

By default the snmpStack.verSecurityCache table can be accessed by ncp_oql on the 

SnmpHelper service. However if there are security concerns, access to this table can be disabled by 

changing the value of m_AllowOQL in the snmpStack.configuration database table (see 

Table 65). The snmpStack.verSecurityCache table is described in Table 66. 

Table 66: snmpStack.verSecurityCache Database Table Schema (1 of 2) 


m_HostName Not NULL 

PRIMARY KEY 

Text The hostname to which the cached SNMP access 

parameters correspond. 

m_SNMPVersion Integer The version of SNMP used to access this device. 

m_Password Text The community string used to access this device. 

299


300 

Table 66: snmpStack.verSecurityCache Database Table Schema (2 of 2) 


m_SNMPVer3Level Integer Specifies level of SNMPv3 security used. 

m_SecurityName Text If using SNMPv3 then this contains the security 

name. 

m_AuthPswd Text If using SNMPv3 then this contains the auth 

password. 

m_PrivPswd Text If using SNMPv3 then this contains the priv 

password. 

m_TimeLastUsed Long The timestamp of the last time the device was 

accessed. 

m_SnmpPort Integer The SNMP port on the target device. 

The verSecurityTable, described in Table 67, allows you to map an IP or subnet address with an 

SNMP version (1, 2, or 3). The security parameters must be configured, as specified by the SNMP version, 

in order to gain SNMP access to the network device(s). 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. 

Table 67: snmpStack.verSecurityTable Database Table Schema (1 of 2) 


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_SNMPVersion Integer The SNMP version that this configuration applies to. 

(0) SNMP V1 

(1) SNMP V2 

(2) SNMP V3 

m_Password Text The password to try for this IP or subnet address; for 

example, community string. 

m_Type Integer An integer classification of the password type; for 

example: 

(2) SNMP Get password. 

m_SNMPVer3Level Integer Integer representation of the SNMP V3 security level. 


Table 67: snmpStack.verSecurityTable Database Table Schema (2 of 2) 


m_SNMPVer3Details Object of type 

V3SecInfo 



An object representation of the authpassword and/or 

privpassword details for SNMP V3. 

m_SecurityName Text The SNMP V3 security password. 

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. 

The accessParameters table allows you to change the way in which the SNMP helper handles the 

retrieval of large non-scalar variables for particular devices or subnets. Any values inserted into this table 

override the values for m_GetNextBoundary and m_GetNextSlowDown that have been specified in 

the snmpHelper.configuration table. 

Table 68: snmpStack.accessParameters Database Table Schema 


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_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_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_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. 

301


302 

Example SNMP Versioning Configuration 

The following example turns auto-versioning off, enables OQL access, and instructs the SNMP helper not 

to expire cached community strings. 

insert into snmpStack.configuration 

( 

m_AutoVersion, m_AllowOQL, m_ExpireAfter 

) 

values 

( 

0, 1, 0 

); 

Example Configuration of the SNMP verSecurityTable 

Provided that 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. 


( 


m_Password, 



m_SecurityName, 

) 

values 

( 

0, 

'public', 

2, 

{ 



}, 

'authPriv' 

); 

Example Configuration of the SNMP verSecurityTable With a Non-Standard SNMP Port 

This examples 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. 



( 

) 

values 

( 

); 

m_IpOrSubNetVer, 

m_NetMaskBitsVer, 


m_Password, 



m_SecurityName, 

m_SnmpPort, 

192.168.64.0, 

24, 

0, 

'public', 

2, 

{ 



}, 

'authPriv' 

6161 

Configuring Telnet Device Access 



Netcool/Precision IP components such as the Telnet helper that require Telnet access use two Telnet device 

access and password configuration files to gain access to devices on the network: 

TelnetStackSchema.cfg defines the telnetStack database. You should not need to alter 

this file. 

TelnetStackPasswords.cfg contains any necessary inserts into the telnetStack 

database. All the inserts given in this section should be contained within this file. 

You must configure the access parameters for every IP or subnet address by appending OQL inserts to the 

TelnetPasswordSchema.cfg configuration file. 

You can 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. 

Note: SSH within Netcool/Precision IP currently supports password-based authentication or no 

authentication. It does not support RSA signature authentication. 

303


304 

Example Telnet Device Access Configuration For a Subnet 

The following example insert configures the Telnet access parameters for a subnet. 

insert into telnetStack.passwords 

( 

m_IpOrSubNet, 


m_Password, 

m_Username, 

m_PwdPrompt, 

m_LogPrompt, 

m_ConPrompt, 

m_SSHSupport 

) 

values 

( 

'192.168.200.0', 

25, 

'3v3rt0n', 

'user', 

'.*assword:.*', 

'.*ogin.*', 

'.*onsole>.*', 

1 

); 

The above insert specifies: 

A subnet address of 192.168.200.0 with a netmask of 25. 

The password and username to use to access the device. 

The password, login and console prompts to expect from the device. 

The devices on this subnet support SSH. 

Example Telnet Device Access Configuration For a Single IP Address 

The following example insert shows how you can configure the access parameters for a single IP address. 

insert into telnetStack.passwords 

( 

m_IpOrSubNet, 


m_Password, 

m_Username, 

m_PwdPrompt, 

m_LogPrompt, 


) 

values 

( 

); 

m_ConPrompt, 

m_SSHSupport 

'172.16.1.21', 

32, 

'', 

'', 

'.*assword.*', 

'.*sername.*', 

'.*Morr.*', 

0 

The above insert specifies: 



A single IP address of 172.16.1.21. The address is identified as a single address by the fact that 

m_NetMaskBits=32. 

The password and username to use to access the device. 

The password, login and console prompts to expect from the device. 

This device does not support SSH. 

Telnet Helper Password Configuration 

You must configure the access parameters in order to enable the Telnet helper to gain access to devices on 

your network. This is done by configuring the access and password configuration file, 

TelnetStackPasswords.cfg. 

Note: No Telnet passwords are set up in the out-of-the-box configuration, as these prompts and passwords 

are totally user-dependent. 

The access configuration database (the telnetStack database), consists of one table—the passwords 

table. 

Table 69: telnetStack.passwords Database Table Schema (1 of 2) 


m_IpOrSubNet Text IP or subnet address depending on value of 

m_NetMaskBits. 

m_NetMaskBits Integer The subnet mask. If set to 32, m_IpOrSubNet is taken 

to be a single IP address. 

305


306 

Table 69: telnetStack.passwords Database Table Schema (2 of 2) 


m_Password NOT NULL Text The password to try for this subnet or IP address. 

Default = "\n" (carriage return). 

m_Username Text The username to try for this subnet or IP address. 

Default = "". 

m_PwdPrompt Text Password prompt to expect from remote device. 

Default = ".*assword:.*". 

m_LogPrompt Text Login prompt to expect from remote device. 

Default = ".*ogin:.*". 

m_ConPrompt Text Console prompt to expect from remote device. Default 

= "^.*[a-zA-Z0-9].*[$%>#]$". 

m_SSHSupport Boolean Integer Flag to indicate whether or not to use SSH support for 

this device: 

(1) Use SSH support for this device. 

(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. 


10.5 The Helper Databases 

When the Helper Server starts, it creates a database for each helper that is to be run. 

The following sections describe the helper databases. 

The ARP Helper database 


The Helper Databases 

The ARPHelper database stores information about the requests the ARP helper makes from the network. 

The ARPHelper database schema is described in Table 70. 

Table 70: ARPHelper Database Schema 

Database Defined in Fully Qualified Database Table Names 

ARPHelper NCHOME/etc/precision/ 

DiscoHelperServerSchema.cf 

g 

The ARPHelperTable database table, described in Table 71, configures the general operation of the 

ARP helper. 

Table 71: ARPHelper.ARPHelperTable Database Table Schema 

ARPHelper.ARPHelperTable 

ARPHelper.ARPHelperConfig 


RivHelperRequestReplyKey PRIMARY KEY 

NOT NULL 

UNIQUE 

Text A unique key interface to the databases of 

the Helper Server for Reply requests. 

RivHelperRequestGetKey NOT NULL Text A key interface to the databases of the 

Helper Server for Get requests. 

RivHelperDbTimeToDie Long64 Indicates how long the requested 

information is to live within the Helper 

Server. 

m_HostIp NOT NULL Text IP address of the device to interrogate. 

m_HostSubnet Text Subnet of the host device to be 

interrogated. 

m_HostMask Text The subnet mask of the host device to be 

interrogated. 

m_HostMac Text The physical address of the device (MAC 

address). 

307


308 

The ARPHelperConfig table, described in Table 72, contains configuration information for the ARP 

helper. 

Table 72: ARPHelper.ARPHelperConfig Database Table Schema 


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: 

m_HelperDoQueryVBs 

optional 

m_HelperDoNotQueryVBs 

optional 

Object type 

varbinds 

Object type 

varbinds 

(0) Do not use cache 

(1) Use cache 

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. 

List of helper inputs that do not query the 

database. This field overrides the value specified 

in m_HelperDoWeQuery. 

m_HelperDoWeStore Integer Indicates whether the Helper Server stores any 

replies from the helpers in its database: 

m_HelperDoStoreVBs 

optional 

m_HelperDoNotStoreVBs 

optional 

m_HelperDebugLevel 

optional 

m_HelperLogfile 

optional 

Object type 

varbinds 

Object type 

varbinds 

(0) Do not store replies in database 

(1) Store replies in database 

List of helper inputs that always store data in the 

Helper Server database. This field overrides the 

value of m_HelperDoWeStore. 

List of helper inputs that never store data in the 

Helper Server databases. This field overrides the 

value of m_HelperDoWeStore. 

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. 




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. 

Example ARP Helper Database Configuration 

The following example insert gives a typical ARP helper configuration. 

insert into ARPHelper.ARPHelperConfig 

( 

m_HelperDbTimeout, 

m_HelperReqTimeout, 

m_HelperStartupTimeout, 

m_HelperDoWeQuery, 

m_HelperDoWeStore 

) 

values 

( 

259200, 1200, 90, 0, 0 

); 

The DNS Helper Database Schema 

Table 73 describes the DNSHelper database. 

Table 73: DNS Helper Database Schema 


DNSHelper NCHOME/etc/precision/ 

DiscoHelperServerSchema.cfg 

DNSHelper.DNSHelperTable 

DNSHelper.DNSHelperConfig 

309


310 

The DNSHelper database table, described in Table 74, stores information about the requests the ARP 

helper makes from the network. 

Table 74: DNSHelper.DNSHelperTable Database Table Schema 



NOT NULL 

UNIQUE 

Text A unique key for Reply requests. 

RivHelperRequestGetKey NOT NULL Text A key for Get requests. 

RivHelperDbTimeToDie Long64 How long the requested information is to 

live within the Helper Server. 

m_HostName Text The host name for this IP address. 

m_HostIp Text The IP addresses for this host. 

RivHelperRequestOutput Atom The response data. 

The DNSHelperConfig table, described in Table 75, holds configuration information for the DNS 

helper. 

Table 75: DNSHelper.DNSHelperConfig Database Table Schema (1 of 2) 



before the database expires. 



m_HelperStartupTimeout Long64 The default helper start-up timeout, that is, the 




database or whether it queries the network using a 

helper: 


optional 


optional 

Object type 

varbinds 

Object type 

varbinds 


(1) Use cache 


database. This field overrides the value of 

m_HelperDoWeQuery. 

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. 


Table 75: DNSHelper.DNSHelperConfig Database Table Schema (2 of 2) 


Example DNS Helper Database Configuration 

The following example insert shows a typical DNS helper configuration. 

insert into DNSHelper.DNSHelperConfig 

( 






) 

values 

( 

259200, 1200, 90, 0, 0 

); 






optional 


optional 


optional 


optional 

Object type 

varbinds 

Object type 

varbinds 




Helper Server database. This field overrides 

m_HelperDoWeStore. 


Helper Server databases. This field overrides 



m_Logfile. 


helper. 

311


The Ping Helper Database Schema 

312 

Table 76 describes the PingHelper database. 

Table 76: PingHelper Database Schema 


PingHelper NCHOME/etc/precision/ 

DiscoHelperServerSche 

ma.cfg 

The schema of the PingHelperTable database table is described in Table 77. 

Table 77: PingHelper.PingHelperTable Database Table Schema 

PingHelper.PingHelperTable 

PingHelper.PingHelperConfig 



NOT NULL 

UNIQUE 

Text A key interface to the databases of the 

Helper Server for Reply requests. 

RivHelperRequestGetKey NOT NULL Text A key interface to the databases of the 

Helper Server for Get requests. 



m_HostIp Atom IP address to ping. 

m_HostSubnet Text Subnet of the IP address to ping. 

m_HostMask Text The subnet mask of the address to ping. 

m_PingRequestType Integer The type of ping request: 

(1) Individual address 

(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. 



The schema of the PingHelperConfig database table is described in Table 78. 

Table 78: PingHelper.PingHelperConfig Database Table Schema 






m_HelperReqTimeout Long64 The helper request timeout that is, how long 




when requested to. 


database or whether it queries the network 

using a helper: 


optional 


optional 

Object type 

varbinds 

Object type 

varbinds 


(1) Use cache 


database. This field overrides 




item is found in the database then the network 

is not queried. 




optional 


optional 


optional 

m_HelperLogFile 

optional 

Object type 

varbinds 

Object type 

varbinds 










the file specified in m_HelperLogfile. 


helper. 

313


314 

Example Ping Helper Database Configuration 

The following insert provides a typical example configuration of the PingHelper database. 

insert into PingHelper.PingHelperConfig 

( 






) 

values 

( 

259200, 1200, 90, 0, 0 

); 

The SNMP Helper Database Schema 

Table 79 gives the schema of the SNMPHelper database. 

Table 79: SNMPHelper Database Schema 

Database name Defined in Fully qualified database table names 

SnmpHelper NCHOME/etc/precision/ 


The schema of the SNMPHelperTable database table is described in Table 80. 

Table 80: SnmpHelper.SnmpHelperTable Database Table Schema (1 of 2) 



NOT NULL 

UNIQUE 

SnmpHelper.SnmpHelperTable 

SnmpHelper.SnmpHelperConfig 

Text A key interface to the databases of the Helper 

Server for Reply requests. 

RivHelperRequestGetKey NOT NULL Text A key interface to the databases of the Helper 

Server for Get requests. 

RivHelperDbTimeToDie Long64 How long the requested information is to live 

within the Helper Server. 


m_CommunitySuffix Text The suffix to the community string. 

m_OID NOT NULL Atom Object ID for the Get request. 


Table 80: SnmpHelper.SnmpHelperTable Database Table Schema (2 of 2) 


The schema of the SNMPHelperConfig database table is described in Table 81. 



m_SnmpIndex Atom The index of the Get request (if it is a Get 

request). 

m_RequestType Integer Type of request: 

(0) Get 

(1) GetNext 

(2) GetBulk 


Table 81: SnmpHelper.SnmpHelperConfig Database Table Schema (1 of 2) 








when requested to. 


database or whether it queries the network 

using a helper: 


optional 


optional 

Object type 

varbinds 

Object type 

varbinds 


(1) Use cache 






item is found in the database then the network 

is not queried. 





315


316 

Table 81: SnmpHelper.SnmpHelperConfig Database Table Schema (2 of 2) 



optional 


optional 


optional 


optional 

Example SNMP Helper Database Configuration 

The following insert provides an example configuration of the SNMP helper database. 

insert into SnmpHelper.SnmpHelperConfig 

( 






) 

values 

( 

259200, 1200, 90, 0, 0 

); 

The Telnet Helper Database Schema 

Table 82 describes the TELNETHelper database. 

Table 82: TELNETHelper Database Schema 

Object type 

varbinds 

Object type 

varbinds 

List of helper inputs that always store data in 

the Helper Server database. This field overrides 


List of helper inputs that never store data in 

the Helper Server databases. This field 

overrides m_HelperDoWeStore. 



Text The full path and file for the logfile of the 

current helper. 


TelnetHelper NCHOME/etc/precision/ 


TelnetHelper.TelnetHelperTable 

TelnetHelper.TelnetHelperConfig 


The TelnetHelperTable database table schema is described in Table 83. 

Table 83: TelnetHelper.TelnetHelperTable Database Table Schema 



Table 84 gives the schema of the TelnetHelperConfig table. 


NOT NULL 

UNIQUE 


Text A unique request reply key interface to the 

databases of the Helper Server. 

RivHelperRequestGetKey NOT NULL Text A request get key interface to the 

databases of the Helper Server. 




m_TelnetCommand Text The Telnet command. 


Table 84: TelnetHelper.TelnetHelperConfig Database Table Schema (1 of 2) 






m_HelperStartupTimeout Long64 The default helper start-up timeout, that is, the 




database or whether it queries the network using 

a helper: 


optional 


optional 

Object type 

varbinds 

Object type 

varbinds 


(1) Use cache 





database before querying the network. If the item 

is found in the database then the network is not 

queried. 

317


318 

Table 84: TelnetHelper.TelnetHelperConfig Database Table Schema (2 of 2) 





optional 


optional 


optional 


optional 

Object type 

varbinds 

Object type 

varbinds 

Example Telnet Helper Database Configuration 

The following example insert gives a typical configuration of the Telnet helper database. 

insert into TelnetHelper.TelnetHelperConfig 

( 






) 

values 

( 

259200, 1200, 90, 0, 0 

); 












helper. 


10.6 Connecting to Helpers on Different Subnets 


Connecting to Helpers on Different Subnets 

If necessary you can configure the Helper Server to connect to helpers running on a separate subnet by 

creating a database table called HelperName.HelperNameClientId. You can create and populate 

a ClientId table for a given helper by appending OQL inserts to the 

DiscoHelperServerSchema.cfg configuration file. 

In order to use helpers running on a separate subnet, you must first configure the Netcool/Precision IP 

Rendezvous message bus for communication between the two subnets. See the Netcool/Precision IP 

Installation and Deployment Guide for details about configuring Rendezvous. 

The ClientId table, described in Table 85, must be in the following format: 

Helper_name.Helper_nameClientId. 

Table 85: ClientId table 


m_HostName NOT NULL Text The name of the host on which the helper is running. 

m_Subnet NOT NULL Text The subnet of the host. 

m_NetMask Integer The netmask. 

The Helper Server checks for the existence of a ClientId table when it distributes requests to the helpers. 

By default, no ClientId tables are created, so any requests passed to the helpers are sent to the locally 

connected helpers. 

If a ClientId table exists, the Helper Server uses the remote helper on the specified subnet, if the 

appropriate helper is connected. If no helper is connected on the specified subnet, the Helper Server uses a 

local helper instead, or launches a local helper using CTRL if there are no active local helpers. 

Example Configuration of the ARP Helper 

The following example insert creates and populates a ClientId table for the ARP helper. The insert 

ensures that the Helper Server forwards requests appropriate to the ARP helper to the helper connected to 

the specified device and subnet instead of using the local ARP helper. 

create table ARPHelper.ARPHelperClientId 

( 

m_HostName text not null, 

m_Subnet text not null, 

m_NetMask int 

); 

insert into ARPHelper.ARPHelperClientId 

( 

m_HostName, m_Subnet, m_NetMask 

319


320 

) 

values 

( 

); 

"swallow", '194.203.201.0', 25 




10.7 Communication Between DISCO and the Helper Server 

If the helpers and the Helper Server are running on a different host to DISCO, then DISCO and the Helper 

System communicate using a TCP socket-based connection. However, the initial communication of the 

server address is accomplished using a multicast process. A client (discovery agents and helpers are clients to 

the Helper Server) sends a multicast request for the address of the server to participating Precision Server 

processes. The server responds with its connection details, and a TCP connection is established. This 

connection then becomes the private link between the server and the client process. You can specify the exact 

multicast address and port number for communication between processes through the Service Data 

configuration file, ServiceData.cfg. 

The ServiceData Configuration File 

The ServiceData configuration file is a dynamic file that is constantly updated by Precision Server 

processes. Every Precision Server service (that is, component or process) using a TCP socket adds a line to 

the file on start up containing information about the service. The service removes the line from the 

configuration file when it terminates. The information appended to the configuration file is listed below: 

The service name 

The service domain 

The service IP address 

The service port number 

The server on which the process is being run 

In the example configuration file shown below, the first service called MulticastService shows the 

multicast address and port number. The second service shows that the Helper service is running on the 

DEMO domain, and includes information about the IP address, port number and the name of the server 

where the Helper service is running. 

-- 

-- Server data file - contains info on servers and the general multicast 

-- address to use. 

-- 

SERVICE: MulticastService DOMAIN: ANY_PRECISION_DOMAIN ADDRESS: 225.13.13.13 PORT: 

33000 

SERVICE: Helper DOMAIN: DEMO ADDRESS: 192.168.31.8 PORT: 51153 SERVERNAME: britanicus 

DYNAMIC: YES 

321


322 

Defining Fixed Helper Ports 

When helpers are located on different hosts that are behind a firewall, you need to dedicate a port on the 

server machine for communication with the helpers. You also need to dedicate a port on each of the 

machines where one or more helpers are running for communication with the server. You do this by 

modifying the ServiceData.cfg file on the Netcool/Precision IP installation on the server machine 

and on each of the Netcool/Precision IP installations on each of the remote hosts where helpers are running. 

Note: Netcool/Precision IP needs to be installed on each of the remote hosts where helpers are running. 

To set fixed port settings for helpers on the server machine: 

1. On the server machine, start the Helper server. For information on how to do this, see Starting the 

Helper Server on page 288. 

2. Make a backup copy of the ServiceData.cfg file. 

3. Edit the ServiceData.cfg file and copy the line relevant to the helper (or helpers) for which 

you want to fix a static port. 

The line may look something like this: 


britanicus DYNAMIC: YES 

The port for the helper in this example has been assigned on a dynamic basis by Rendezvous. 

4. Change the PORT setting to the desired value. 

5. Change the string DYNAMIC:YES to DYNAMIC:NO. 


To set fixed port settings for the server on the helper host: 


2. On the server, edit the ServiceData.cfg file and copy the line that you edited to set fixed port 

settings for helpers on the server machine. 

3. Edit the ServiceData.cfg file on the helper host and paste the line that you copied in Step 2. 

Using the example above, this line looks like this: 


britanicus DYNAMIC: NO 


5. Repeat steps 1 to 4 for each of the helpers that requires a fixed port setting. 


Changing the Multicast Address 



In order to modify the multicast address used by the Precision Server processes, you have to edit the address 

and the port of the first line of the ServiceData.cfg configuration file, as shown below. 

-- 

-- Server data file - contains info on servers and the general 

-- multicast address to use. 

-- 

SERVICE: MulticastService DOMAIN: DOMAIN_NAME ADDRESS: MULTICAST_ADDRESS PORT: 

PORT_NUMBER 

In the above statement: 

MulticastService refers to the Precision Server service that is being configured to use a 

particular multicast address. Valid entries include Model, Events, Class, Auth, Exec, Ctrl. 

DOMAIN_NAME indicates the domain name of the service that is to use the specified multicast 

address. It is possible to set the same service to use different multicast addresses for each domain that 

it is run in. Alternatively, you may replace the DOMAIN_NAME with ANY_PRECISION_DOMAIN, 

which means that the service is to use the same multicast address for all domains it is executed in. 

MULTICAST_ADDRESS indicates the multicast address to be used by the multicast service 

provider. 

PORT_NUMBER indicates the port number to be used by the multicast service provider. 

The multicast address in the configuration files must be the same for all devices that have clients which talk 

to each other. If this is not the case, processes on one device can talk but others are not able to listen because 

they are not tuned in to the right frequency. 

323


324 


11. MPLS.fm August 16, 2006 

Chapter 11: Configuring an MPLS Discovery 

This chapter explains how to discover MPLS networks. It explains which types of MPLS discovery you can 

perform using Netcool/Precision IP and leads you through the steps required to perform an MPLS 

discovery. 


About MPLS Discovery on page 326 

Configuring MPLS Agents and SNMP and Telnet Access on page 329 

Advanced MPLS Discovery on page 333 

Visualizing MPLS Topology on page 337 



11.1 About MPLS Discovery 

326 

Netcool/Precision IP supports the discovery of the following VPNs running across MPLS core networks: 

Layer 3 VPNs 

Enhanced Layer 2 VPNs 

For the enhanced Layer 2 VPNs, Netcool/Precision IP discovers point-to-point psuedowires linking two 

provider edge (PE) routers. 

The following sections specify the terminology and topology visualization conventions used in 

Netcool/Precision IP to refer to MPLS networks. 

Note: The pictures 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). For examples of the 

MPLS network views available from the Network Views GUI, see Visualizing MPLS Topology on page 337. 

Layer 3 MPLS VPNs 

Netcool/Precision IP can visualize layer 3 MPLS VPN topologies in the following ways: 

Core view 

Edge View 


Core View 


About MPLS Discovery 

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 the MPLS core, for each of the VPNs running across the 

MPLS core. Figure 79 provides an example of a core view showing a layer 3 VPN running over an MPLS 

core network. 

Dallas Site 

Figure 79: Core View 

Edge View 

Tokyo Site 

The edge view shows the PE routers and the MPLS cloud only. It does not provide visibility of the devices 

in the core. Figure 80 provides an example of an edge view showing a layer 3 VPN running over an MPLS 

core network. 

Dallas Site 

London Site 

CE – D 

Figure 80: Edge View 

London Site 

CE – D 

CE – L 

PE – L 

PE – D 

CE – L 

PE – L 

PE – D 

P P 

P 

MPLS Core 

Network 

PE – T 

PE – T 

CE – T 

CE – T 

Tokyo Site 

327


Enhanced Layer 2 MPLS VPNs 

328 

For enhanced Layer 2 VPNs, Netcool/Precision IP only provides an edge view of your MPLS core network. 

Netcool/Precision IP displays an enhanced Layer 2 VPN as a collection of point-to-point psuedowires. This 

means that if an enhanced Layer 2 VPN contains more than two provider edge (PE) routers, then 

Netcool/Precision IP displalys that VPN in multiple views, each view consisting of a single PE to PE 

point-to-point connection. 

Table 86 shows examples of enhanced Layer 2 VPNs with two and more than two PEs. The table also 

provides the number of psuedowires, and hence the number of views that Netcool/Precision IP displays for 

each VPN. 

Table 86: Number of Psuedowires for an Enhanced Layer 2 VPN 

Number of PEs in an Enhanced Layer 2 

VPN 

Number of Point-to-Point Psuedowires Number of Views Netcool/Precision IP 

Displays for this VPN 

2 1 1 

3 3 3 

4 6 6 



Configuring MPLS Agents and SNMP and Telnet Access 

11.2 Configuring MPLS Agents and SNMP and Telnet Access 

You configure an MPLS discovery in the same way that you configure the discovery of any other type of 

network. Configuration activities for an MPLS network include seeding, scoping, and the other standard 

discovery activities detailed in Chapter 4: Network Discovery Using the Network Discovery GUI on page 85 

(GUI-based configuration) and in Chapter 6: Network Discovery from the Command Line on page 175 

(command line-based configuration). 

In addition to standard discovery configuration activities, you also have to do the following: 

Enable one or more MPLS agents for your discovery. 

Configure the MPLS VPN discovery method. 

Configure SNMP and Telnet access to ensure that MPLS agents are able to access devices and are able 

to understand the output from devices. 

These activities are described in the following sections. 

Enabling MPLS Agents 

The following MPLS agents are provided. These agents, and the corresponding agent definition (.agnt) 

files, are listed below: 

Juniper Telnet agent (JuniperMPLSTelnet.agnt) 

Juniper ERX router agent (UnisphereMPLSTelnet.agnt) 

Cisco MPLS Telnet agent (CiscoMPLSTelnet.agnt) 

Cisco MPLS SNMP agent (CiscoMPLSSnmp.agnt) 

Laurel MPLS Telnet agent (LaurelMPLSTelnet.agnt) 

Note: The Laurel MPLS Telnet agent is intended for RT (RouteTarget) based discoveries only. 

These agents are able to discover MPLS VPN data from devices in the network. 

Note: If you have an MPLS network that supports both Layer 3 and enhanced Layer 2 VPNs, then the same 

MPLS agents will discover both types of VPN. Topoviz Network Views are also able to partition both Layer 

3 and enhanced Layer 2 VPNs simultaneously on the same core MPLS network. For an example of a 

Topoviz network view of a partitioned MPLS network showing both Layer 3 and enhanced Layer 2 VPN, 

see Figure 83 on page 339. 

329


! 

330 

It is recommended that where the MPLS network contains Cisco equipment both the Cisco MPLS Telnet 

and Cisco MPLS SNMP agents are enabled. These two agents complement each other, as follows: 

Cisco MPLS SNMP agent only targets devices with an IOS that fully supports SNMP-based MPLS 

discovery 

CiscoMPLSTelnet agent only targets devices running an IOS that does not fully support an SNMP 

based discovery 

Warning: Care must be taken when altering the CiscMPLSSnmp.agnt file. Some network devices may 

contain IOS versions that have a flaw that may impact 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 of the discovery to specific VPNs or VRFs. For details on how to do this, 

see Defining the Scope of an MPLS/VPN Discovery on page 333. 

Configuring MPLS Discovery Method 

You can discover MPLS VPNs in the following ways: 

Route Target (RT)-Based Discovery: Netcool/Precision IP uses VRF and RT information to determine 

which provider edge routers are involved in a VPN. 

Label Switched Path (LSP)-Based Discovery: Netcool/Precision IP uses VRF and LSP information to 

determine which provider edge (PE) routers are involved in a VPN and which provider core (P) 

routers are traversed by the LSPs within that VPN. 

Choose which MPLS discovery method to use by setting the Enable RT Based MPLS VPLN Discovery 

check box in the Network Discovery GUI, as described in Configuring Advanced Discovery Parameters on 

page 134. 

Check the Enable RT Based MPLS VPLN Discovery check box to enable RT-based MPLS 

discovery. 

Clear the Enable RT Based MPLS VPLN Discovery check box to enable LSP-based MPLS 

discovery. 

You can also perform this configuration manually by setting the value of the field m_RTBasedVPNs in 

the disco.config table, as described in Table A8 disco.config Database Table Schema on page 431. 



Configuring MPLS Agents and SNMP and Telnet Access 

Table 87 summarizes the differences between RT-based discovery and LSP-based discovery. 

Table 87: RT-Based Discovery and LSP-Based Discovery 

Type of Discovery Label Data Core View VPN Resolution 

RT-based discovery No label data is required for 

this type of discovery 

Configuring Telnet 

Discovery is faster 

LSP-based discovery Label data is discovered in 

order to trace LSPs 

Discovery is slower 

Consists of all MPLS-enabled 

devices 

Consists of devices 

traversed by the relevant 

LSPs 

VPNs resolved based on RT 

information 

VPNs resolved based on VRF 

information 

The CiscoMPLSTelnet, JuniperMPLSTelnet, LaurelMPLSTelnet, and UnisphereMPLSTelnet agents 

obtain data from devices primarily, although not exclusively, using Telnet. You must configure Telnet access 

to ensure that MPLS Telnet agents are able to access devices and are able to understand the output from 

devices.This involves the following activities: 

Populate the Telnet configuration file TelnetStackPasswords.cfg so the agents can access 

the target devices. For more information, see the following sections: 

– Configuring Telnet Device Access on page 303 for information on how to configure Telnet access 

to target devices using OQL inserts. 

– Setting Telnet Access Information on page 114 for information on how to configure Telnet access 

to target devices using the Network Discovery GUI. 

Configure the Telnet Helper so that agents can understand the output from devices. For more 

information, see Configuring the Telnet Helper on page 293. 

331


Configuring SNMP 

332 

The CiscoMPLSSnmp agent obtains data from devices using SNMP. You must configure SNMP access to 

ensure that this agent is able to access devices and is able to understand the output from devices.This involves 

the following activities: 

Configure SNMP access to devices, as described in the following sections: 

– Configuring SNMP Device Access on page 298 for information on how to configure SNMP 

access to target devices using OQL inserts. 

– Setting SNMP Passwords on page 111 for information on how to configure SNMP access to 

target devices using the Network Discovery GUI. 

Configure the SNMP Helper so that agents can understand the output from devices. For more 

information, see Configuring the SNMP Helper on page 292. 


11.3 Advanced MPLS Discovery 

This section covers the following advanced MPLS discovery techniques: 


Advanced MPLS Discovery 

Defining the scope of an MPLS discovery: enables you to restrict the scope of this discovery to a 

particular VPN or VRF 

Specifying a VPN name: enables you to configure your own VPN naming convention 

Fine Tuning Label Data Discovery: enables you to force label discovery regardless of the type of MPLS 

discovery selected 

Defining the Scope of an MPLS/VPN Discovery 

When configuring the discovery of one or more VPNs (Virtual Private Networks) running across an MPLS 

core, you can restrict the scope of this discovery to a particular VPN name or VRF (VPN Routing and 

Forwarding) table name. You restrict the scope by configuring the optional 

DiscoAgentDiscoveryScoping section in the *.agnt file. The configurable options are 

described in Table 88. 

Table 88: Defining the 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 

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. 

333


334 

Scoping by VPN name only works if 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 as follows: 

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 

// 


{ 

IncludeVPN = “Precision”; 

IncludeVRF = “V44:AcmeSheds”; 

} 

Precedence 

The order of precedence for Exclude and Include within the DiscoAgentDiscoveryScoping 

section is as follows: 

1. Exclude 

2. Include 



Advanced MPLS Discovery 

The order of precedence for VRF and VPN within the DiscoAgentDiscoveryScoping is as 

follows: 

1. VRF 

2. VPN 

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. 

Specifying a VPN Name 

The MPLSAddVPNNames stitcher extracts and constructs a VPN name from the list of paths discovered 

by the Path Tracing stitchers. The MPLSAddVPNNames stitcher can then add the VPN name to the device 

interfaces that fall under the paths belonging to the VPN. 

If you choose not to use the Cisco VRF naming convention, you can configure your own VPN naming 

convention by making the appropriate inserts into MPLSAddVPNNames.stch located in 

NCHOME/precision/disco/stitchers/. A good understanding of the stitcher language is 

essential before configuring the MPLSAddVPNNames.stch file. Detailed information about the stitcher 

language can be found in Appendix C: Stitchers and Stitcher Language on page 517. 

The following example shows where to modify the VPN name in the MPLSAddVPNNames.stch file, 

located in NCHOME/precision/disco/stitchers. 

//VPN Name Assignment 

// 

//Currently assigns the VRF name as the VPN Name if no VPN name 

//has been discovered by the agent, i.e., if the VRF name was not in 

//the Cisco format. 

// 

vpnName = eval(text, ‘&m_VPNName’); 

if (vpnName == NULL) 

{ 

vpnName = vrfName; //VPN=VRF, customize as required. 

} 



page 10. 

335


Fine Tuning Label Data Discovery 

336 

By default, the choice of whether or not the MPLS agents retrieve MPLS label data is determined by the 

chosen MPLS discovery method, as follows: 

If you choose RT-based discovery, then the MPLS agents do not retrieve label data. 

If you choose LSP-based discovery, then the MPLS agents retrieve label data. 

The MPLS discovery methods are described in Configuring MPLS Discovery Method on page 330. 

If you choose an RT-based discovery but you nevertheless wish to retrieve label data, then it is possible to 

do this manually by means of the following insert in the DiscoAgentDiscoveryScoping section of 

the appropriate MPLS.agnt file: 


{ 

GetMPLSLabelData = 1; 

} 


11.4 Visualizing MPLS Topology 


Visualizing MPLS Topology 

Visualization options for your MPLS discovery vary depending on whether you are discovering Layer 3 

VPNs or enhanced Layer 2 VPNs. 

Layer 3 VPNs: For Layer 3 VPNs, Netcool/Precision IP provides by default both an edge view and a 

core view of your MPLS core network. 

You can switch from the edge view to the core view by double-clicking on the MPLS cloud in 

Topoviz. 

Enhanced Layer 2 VPNs: For enhanced Layer 2 VPNs, Netcool/Precision IP only provides an edge 

view of your MPLS core network. Netcool/Precision IP displays an enhanced Layer 2 VPN as a 

collection of point-to-point psuedowires. 

This section provides examples of topology maps of MPLS core networks. The aim is to show how VPN 

and core views are displayed using Topoviz once an MPLS discovery is complete. For full information on 

how to partition an MPLS core network to display multiple VPNs on that MPLS core, see the 

Netcool/Precision IP Visualization Guide. 

Figure 81 provides an example of a Layer 3 edge view displayed using Topoviz Network Views. 

Figure 81: Edge View Showing the MPLS Core Network as a Cloud 

This corresponds to the edge view shown in Figure 80 Edge View on page 327. 

337


338 

Double-click on the MPLS CORE icon shown in Figure 81 to display a core view, as shown in Figure 82 

on page 338. 

Figure 82: Core View Showing the P Devices Within the MPLS Core 

This corresponds to the core view shown in Figure 79 Core View on page 327. 

Note: Topoviz does not display VRF information for a given PE router within a VPN. 



Visualizing MPLS Topology 

Figure 83 shows an example of a Layer 2 edge view displayed using Topoviz Network Views. This screenshot 

also shows the partitioning of an MPLS core network into Layer 2 and Layer 3 VPNs. 

Figure 83: Edge View of an Enhanced Layer 2 VPN 

339


340 


12. Managing_NAT_environments.fm July 6, 2005 

Chapter 12: Managing NAT Environments 

This chapter describes how Netcool/Precision IP can discover and manage Network Address Translation 

(NAT) environments. 


Network Address Translation (NAT) on page 342 

Configuring a NAT Discovery on page 346 

Adapting the Containment Model for Use with NAT on page 352 

Viewing NAT Environments Using Topoviz Network Views on page 353 



12.1 Network Address Translation (NAT) 

342 

This chapter introduces Network Address Translation and explains how the Precision Server can discover 

and manage NAT environments. 

Overview of NAT 

In order for any computer to access information on the Internet, it must have a unique IP address. However, 

the number of available IP addresses in the current format (a 32-bit number) is not enough to meet the 

growth in demand for access to the Internet. NAT was designed as a short term solution to the problem of 

address depletion. NAT provides a method of connecting multiple computers to an IP network, such as the 

Internet, 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. 

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. 



Network Address Translation (NAT) 

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 the following address ranges to be used by 

private networks: 

Class A: 10.0.0.0 to 10.255.255.255 

Class B: 172.16.0.0 to 172.31.255.255 

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. 

The Precision Server and NAT Environments 

The following section provides an overview of how Netcool/Precision IP manages NAT environments, and 

explains some of the restrictions on the types of NAT environment that are currently supported. 

The Precision Server 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. 

The Precision Server 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) 

appropriately. 

Restrictions on Using the Precision Server to Manage NAT Environments 

The following restrictions currently apply to the management of NAT environments using the Precision 

Server: 

The Precision Server can discover one or more NAT environments, but they must all be using static 

NAT address mapping. 

The Precision Server can discover devices in multiple NAT domains, regardless of whether the private 

IP addresses of the devices are duplicated in other NAT domains, as long as the public IP address of 

each device in each domain is unique. 

343


344 

Devices within a NAT domain that have only private IP addresses cannot be discovered or managed 

by the Precision Server. 

The discovery process must discover the NAT environment from outside, that is, from the public 

network. 

Virtual IP addresses such as HSRP (Hot Standby Routing Protocol) addresses cannot be mapped. 

The real physical address must be used. 

The following must be supplied before the discovery is run: 

– The addresses of all supported NAT gateways. 

– The NAT gateway translations must be discovered. This can be done 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 

This section describes how the process flow of a NAT discovery differs from the process flow of a normal 

discovery. 

For more information on the process flow of a normal discovery, see An Overview of the Discovery Process on 

page 25. 

Prerequisites 

There are extra prerequisites for running a NAT-enabled discovery. See Configuring a NAT Discovery on 

page 346. 

Downloading Translation Information 

NAT translation information is downloaded by the NAT agents into the database table 

translations.NATTemp 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 database 

table translations.NAT. 

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. 


Creating the Topology 


Network Address Translation (NAT) 

When the topology is created, two stitchers, AddBaseNATTags.stch and AddNATTags.stch, add 

NAT information to the topology record of each device in a NAT domain. 

Table 89: 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. 

345


12.2 Configuring a NAT Discovery 

346 

This section describes how to set up a NAT discovery. Follow the procedures in this section to: 

Enable NAT translation 

Define address spaces for each domain 

Configure trap handling 

Run the correct NAT agent 

Enabling NAT Translation 

Edit NCHOME/etc/precision/DiscoSchema.cfg to create or amend an insert into 

disco.NATStatus to set m_UsingNAT to 1 and m_NATStatus to 0. This sets the discovery system 

to use NAT translation. The schemas of all databases defined in DiscoSchema.cfg are described in 

Appendix A: The Discovery Databases on page 423. The completed insert must resemble the following: 

insert into disco.NATStatus 

( 

m_UsingNAT, 

m_NATStatus 

) 

values 

( 

1, 

0 

); 



page 10. 

Defining Address Spaces for Each Domain 

Edit DiscoSchema.cfg to create or amend an insert into 

translations.NATAddressSpaceIds to specify the IP address of your NAT gateways and the 

address space identifier you wish to use for each associated NAT domain. 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' 

insert into translations.NATAddressSpaceIds 

( 

m_NATGatewayIP, 

m_AddressSpaceId 

) 

values 

( 

'172.16.1.104', 

'NATDomain2' 

); 

Configuring Trap Handling 


Configuring a NAT Discovery 

When the Precision Server receives a trap, either using the Trap finder or the Trap Polling agent, it must 

retrieve the trap source address. You can configure the Precision Server to retrieve the trap source address 

from either the payload (that is, the private NAT address) or the IP header (that is, the public NAT address) 

of the trap. 

If you are configuring the Trap finder within a NAT environment, you must configure the Precision Server 

to retrieve the trap source address from the IP header. The reason for this is that the private NAT address in 

the payload is unique within the NAT address space but may not be unique outside of the NAT address 

space. However, the IP address in the header is unique. 

The option to retrieve the trap source address from the payload applies when a trap is redirected through a 

third party device. This invalidates the address held in the IP header. However, in a NAT environment, it 

is not possible to use the trap source address from the payload because this address may not be unique. 


In order to configure the Trap finder, you must modify the insert into the 

trapFinder.configuration database table in the DiscoTrapFinderSchema.cfg 

configuration file. 

Inserting a value of 1 (the default setting) into the 

trapFinder.configuration.m_SourceByPayload column configures the Trap finder 

to attempt to retrieve the trap source address from the trap payload. If there is no address in the 

payload, the Trap finder uses the header source address instead. 

Inserting a value of 0 into the trapFinder.configuration.m_SourceByPayload 

column configures the Trap finder to retrieve the trap source address from the header. 

347


348 

The following example insert shows how you might configure the Trap finder. 

insert into trapFinder.configuration 

( 

m_NumThreads, m_TrapPort, m_SourceByPayload 

) 

values 

( 

1, 162, 1 

); 

The above example insert configures the Trap finder to: 

Use 1 thread. 

Listen for traps on port 162. 

Attempt to retrieve the trap source address from the trap payload. 

Configuring the Trap Polling Agent 

If you have purchased the RCA and monitoring package, it is also necessary to configure the trap polling 

agent to take source addresses from payloads. See the Netcool/Precision IP Monitoring and RCA Guide for 

more information about MONITOR and the polling agents. 

Running the Appropriate Agent 

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. 

If you are using a NAT gateway other than a NetScreen Firewall or a Cisco Router, you must use the Perl 

agent NATTextFileAgent.pl. 


Running the NAT Gateway Agents 



The CiscoNATTelnet and NATNetScreen agents connect directly to the NAT gateways in order to 

download the address mappings. Before running these agents, you must have already enabled NAT 

translation (see Enabling NAT Translation on page 346) and configured trap handling (see Configuring Trap 

Handling on page 347). Perform the following steps 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. In order to activate an agent, you must alter the 

insert so that the m_Valid column for that agent is set to 1. In order to deactivate an agent, ensure 

that m_Valid=0. 

Note: You can also activate and deactivate the agents using the Discovery Configuration Tool, as 


The following example insert activates the CiscoNATTelnet agent. 


( 

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 as normal, as described in Chapter 6: Network Discovery from the Command Line on 

page 175. 

349


350 

Running the NATTextFileAgent Agent 

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. Before running the NATTextFileAgent agent, you must have already 

enabled NAT translation (see page 346) and configured trap handling (see Configuring Trap Handling on 

page 347). Perform the following steps to configure and run the agent: 

1. Ensure you have installed the Perl API. All Perl agents require the API in order to run. The API is 

installed by default in Netcool/Precision IP 3.6. 

To check whether the API is installed, check that the following file exists: 

NCHOME/precision/bin/ncp_perl 

If the file is listed, then this means that the Perl API is installed. For more information on installing 

Netcool/Precision IP, see the Netcool/Precision IP Installation and Deployment 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 wish to create your own mappings, then 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: 

– 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. 

– The outside global address of the device, that is, the public address of the device. 

– 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 PublicIP PrivateIP 

1.2.3.4 2.3.4.5 10.10.1.1 

1.2.3.4 2.3.4.6 10.10.1.2 

1.2.3.9 2.3.6.1 10.10.1.1 

1.2.3.9 2.3.6.2 10.10.1.2 




Note: The public IP address of a particular gateway translation is not necessarily the same as the public 

address from the point of view of the management station. It is the IP address that the Gateway 

retrieving from one port 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 'closer' to the management domain. 

4. Enable the agent. There is an insert into the disco.agents table in the DiscoAgents.cfg 

configuration file for every installed discovery agent. In order to activate an agent, alter the insert so 

that the m_Valid column for that agent is set to 1. In order to deactivate an agent, ensure that 

m_Valid=0. 

Note: You can also activate and deactivate agents using the Discovery Configuration Tool, as 


The following example insert activates the NATTextFileAgent agent. 


( 

m_AgentName, m_Valid, m_AgentClass, m_IsIndirect, m_Precedence, m_IsPerl 

) 

values 

( 

'NATTextFileAgent', 0, 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 executes 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. More information about stitcher syntax and the ActOnTimedTrigger stitcher trigger can be 

found in Appendix C: Stitchers and Stitcher Language on page 517. 

7. Run a discovery as normal, as described in Chapter 6: Network Discovery from the Command Line on 

page 175. 

351


12.3 Adapting the Containment Model for Use with NAT 

352 

The NATAddressSpaceContainers.stch stitcher creates virtual objects for each address space 

that contains the entities within that address space. This stitcher is not on by default. You can activate this 

stitcher by uncommenting the following line in the file 

NCHOME/precision/disco/stitchers/CreateScratchTopology.stch: 

// ExecuteStitcher("NATAddressSpaceContainers"); 



Viewing NAT Environments Using Topoviz Network Views 

12.4 Viewing NAT Environments Using Topoviz Network 

Views 

Using Topoviz network views you can partition Business Views on the values of any column in the topology 

record of an entity. For example, you could configure partitions on the field 

ExtraInfo->m_AddressSpace. This field contains an address space identifier 

NATAddressSpace, defined in the Topoviz MySQL database table interfaces. For more 

information on defining address spaces, see Enabling NAT Translation on page 346. 

For instructions on all aspects of using the Topoviz network views, including how to partition Business 

Views, see the Netcool/Precision IP Topology Visualization Guide. 

353


354 


13. MODEL.fm July 5, 2005 

Chapter 13: Accessing Topology Data in 

MODEL 

This chapter describes MODEL, the component responsible for the management, storage and distribution 

of the discovered network topology. 


About MODEL on page 356 

Starting MODEL on page 357 

About the Containment Model on page 359 

Accessing the Discovered Topology on page 363 

Reinstantiating the Containment Model on page 368 

Databases of MODEL on page 372 


Chapter 13: Accessing Topology Data in MODEL 

13.1 About MODEL 

356 

MODEL (ncp_model), the the topology manager and repository, is the component responsible for 

managing and storing the network topology. MODEL also acts as a server for the network topology, 

distributing it to other Precision Server components on demand. For example, the MySQL database used 

by Topoviz is populated with topology data from MODEL. AMOS (part of the RCA and Monitoring 

package) also uses the topology data from MODEL to perform RCA (Root Cause Analysis). 

After the discovery process has completed, the stitchers resolve the connectivity information to create the 

Scratch Topology and send it to MODEL. 

Entries in the Scratch Topology are only sent to MODEL if they pass a filter condition, known as the 

instantiate filter. You can specify an instantiation filter by editing the DiscoScope.cfg, appending an 

OQL insert into the scope.instantiateFilter table, as described in The instantiateFilter Table on 

page 445. If no filter is specified, all discovered devices are instantiated. 

During the transition of the discovered network topology from DISCO to MODEL, the devices are 

instantiated as instances of various classes as defined by the AOCs managed by CLASS. 


13.2 Starting MODEL 


Starting MODEL 

Micromuse recommends that CTRL, the domain process controller, is configured to launch and manage 

MODEL with STORE and CLASS specified as dependencies of MODEL. 

MODEL can also be started manually with the following command line; optional arguments are shown 

enclosed in square brackets. 

ncp_model –domain DOMAIN_NAME [ -cachesize SIZE_IN_MB ] [ -cachepercent 

PERCENTAGE_OF_CACHE_IN_MEMORY ] [ -debug DEBUG ] [ -help ] [ -latency LATENCY ] [ 

-version ] 




-cachepercent 







-domain DOMAIN_NAME The name of the domain under which to run MODEL. 





-latency LATENCY The maximum time in milliseconds (ms) that MODEL waits to connect 

to another Precision Server process by means of the messaging bus. 

This option is useful for large and busy networks where the default 

settings can cause processes to assume that there is a problem when 

in fact the communication delay is a result of network traffic. 







of the data is cached in core memory with the remainder being flushed to disk. These command line options 

are not intended to be used for permanent data storage as the cache is cleared when the process exits. 

357


Prerequisites for Running MODEL 

358 

The following are the prerequisites for running the MODEL component: 

MODEL must have access to a network topology, either because DISCO has completed a successful 

discovery and passed the topology to MODEL, or because there is a topology cache file in the 

NCHOME/var/precision directory (output from STORE as a result of a previous execution of 

MODEL). 




It is good practice to have STORE, the persistent storage engine, running. 

It is strongly recommended that CLASS is running and ready before starting MODEL. 


13.3 About the Containment Model 


About the Containment Model 

A key 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. 

Containers are objects that can ‘hold’ both elements and other containers. Elements and containers can 

represent logical or physical entities. 

Applying the Containment Principle 

The containment model used by the Precision Server can reflect the real world topology of the network that 

is being modelled, in a physical, logical or business-oriented sense. 

The example physical hierarchy shown in Figure 84 shows that a chassis can contain network interface cards, 

which can themselves contain individual ports. 

Figure 84: Modelling the Network Physically 

359


360 

The example logical hierarchy shown in Figure 85 shows that a network entity can contain Virtual Local 

Area Networks (VLANs), and the VLANs can themselves contain ports. 

Figure 85: Modelling the Network Logically 

Figure 86 shows how the Precision Server also uses VLAN objects to model containment. VLAN objects are 

created by the stitchers. They contain all the interfaces that exist on each VLAN. 

Figure 86: Modelling the Network Using Containment 

VLAN Naming 

The Precision Server uses a naming convention to identify the entity name, card and port numbers of 

specific ports, in the format EntityName [ card [ port ] ]. 

For example, port 12 on card 1 of chassis A would be identified as A[ 1 [ 12 ] ]. 

VLAN names can also be modified to reflect the business context in which a given VLAN is used. For 

example, you could rename VLAN 1, and 2 above to Sales and Marketing using stitchers. 


VLAN Trunking 


About the Containment Model 

When traffic from different VLANs is passed along a single trunk link between switches, this is represented 

in the Netcool/Precision IP containment model as shown in Figure 87. 

1 2 

If a port is being used for a trunk link, it contains logical sub-ports. The properties of the ports and sub-ports 

shown in Figure 87 are explained below: 

1. A sub-port connecting VLAN 2 on the switch to VLAN 2 on another switch. Sub-ports are contained 

by trunk ports. 

2. A sub-port connecting VLAN 3 on the switch to VLAN 3 on another switch. Sub-ports have no 

upward connections to their containing trunk port. 

3. A "normal" port. 

Dependencies 

3 

Figure 87: Logical Sub-Ports Contained within a Trunk Port 

Dependencies can be defined by the containment model. A container can be dependent upon the objects it 

contains. For example, VLAN1 may be dependent upon everything inside the VLAN1 container (that is, 

port 1, 2, 12, and 40). 

Since the Precision Server models the network using the concept of containment, these dependencies can be 

represented in the network topology, and applications that extend the functionality of the Precision Server 

can then consider these dependencies in their calculations. AMOS, for example, can consider dependencies 

when performing root cause analysis of network faults. 

Note: When one entity in a system cannot meaningfully exist without another entity it is said to be 

dependent. 

361


Generating the Containment Model 

362 

The containment model is generated at the end of the discovery process when the network topology is 

created. The default containment model represents both physical and logical containment: 

The physical containment model enables you to perform device management down to the port level. 

The logical containment model shows how objects are contained within logical containers that do not 

necessarily exist in the physical sense. One example is a VLAN container like the one shown in 

Figure 86 on page 360, which is a logical grouping of devices, cards, and ports that are not necessarily 

physically connected together or in the same location. The default logical containment model is based 

on VLAN containment. 

Altering the Containment Model 

The containment model is fully configurable, although this is an advanced feature of the discovery process. 

To generate a custom containment model, you must either modify the existing stitchers, or write a new 

stitcher and configure the existing stitchers to execute the new stitcher during the creation of the network 

topology. 

Two example stitchers, ExampleContainment1.stch and 

ExampleContainment2.stch are supplied to assist you in modifying the containment model. 

These stitchers can be executed by removing the comments before the ExecuteStitcher(); 

statements at the end of the CreateScratchTopology.stch stitcher. 

A full syntax definition of the stitcher language can be found in Appendix C: Stitchers and Stitcher 

Language on page 517. 


13.4 Accessing the Discovered Topology 


Accessing the Discovered Topology 

As soon as the discovery process has completed, the stitchers transfer the topology to MODEL. Once 

MODEL has received the topology, you can use the OQL Service Provider to interrogate the MODEL 

databases and query the topology. 

Prerequisites for Accessing the Network Topology Model 

Before you can interrogate the network topology: 

AUTH must be running. 

A topology must have been passed to MODEL, either because DISCO has completed a discovery and 

sent the topology to MODEL, or because MODEL has downloaded a cached topology from 

STORE. 

Querying the MODEL Databases 

The MODEL databases are described in more detail at the end of this chapter. To query the MODEL 

databases, login to the OQL Service Provider using a command line similar to the following. Substitute your 

domain name and username where NCOMS and admin are specified, and enter your password at the 

prompt. 

ncp_oql -domain NCOMS -service Model -username admin 



Password: 

|phoenix:1.> 

The Master Topology 

This section describes the tables of the master database of MODEL that relate to the containment model. 

The master.entityByName table 

The records in the master.entityByName table are in a format similar to the following. 

|phoenix:1.> select * from master.entityByName; 


........................................ 

{ 

ObjectId=802; 

EntityName='10.10.2.198'; 

Address=['','','10.10.2.198','']; 

Description='Cisco Systems WS-C6509 Cisco Catalyst Operating System 

Software, Version 5.3(2)CSX Copyright (c) 1995-1999 by Cisco Systems'; 

363


364 

EntityType=1; 

ClassName='MainNode'; 

EntityOID='1.3.6.1.4.1.9.5.44'; 

Contains=['10.10.2.198[ 0 [ 2 ] ]','10.10.2.198[ 1 [ 1 ] 

]','10.10.2.198[ 1 [ 2 ] ]','10.10.2.198[ 0 [ 1 ] ]' 

IsActive=1; 

CreateTime=982194922; 

ChangeTime=982194922; 

ActionType=0; 

LingerTime=3; 

} 

..... 

..... 

{ 

ObjectId=1002; 

EntityName='10.10.63.194[ 0 [ 1 ] ]'; 

Address=['','00:02:4A:7E:A4:54','10.10.130.248','']; 

EntityType=2; 

ClassName='Interface'; 

EntityOID='1.3.6.1.4.1.9.1.108'; 

UpwardConnections=['10.10.63.194']; 

IsActive=1; 

CreateTime=982194928; 

ChangeTime=982194928; 

ActionType=0; 

LingerTime=3; 

} 


|phoenix:1.> 

The columns in the master.entityByName table that relate to containment and connectivity are: 

The RelatedTo column, which lists all the entities that are connected to the network entity. 

The Contains column, which lists all the entities found to be contained within the current 

network entity. 

The UpwardConnections column, which lists all the containers that the entity is contained 

within. 

The Address column lists all the addresses that the current entity is known by. It would typically 

contain the MAC address and the IP address, in list items (1) and (2). List item numbering 

commences from (0). 

The master.entityByNeighbor Table 

The records in the master.entityByNeighbor table are in a format similar to the following. 

|phoenix:1.> select * from master.entityByNeighbor; 



.......................................... 

{ 

LeftId=974; 

LeftName='b041d-2-7513r2.Kazeem.San.COM[ 0 [ 13 ] ]'; 

RightName='10.10.2.224[ 0 [ 5 ] ]'; 

Speed=0; 

Protocol=0; 

RelType=0; 

Duplex=0; 

} 

..... 

..... 

{ 

LeftId=1001; 

LeftName='10.10.63.194[ 0 [ 3 ] ]'; 

RightName='10.10.2.247[ 0 [ 3 ] ]'; 

Speed=0; 

Protocol=0; 

RelType=0; 

Duplex=0; 

} 


|phoenix:1.> 



The columns in the master.entityByNeighbor table that relate to containment are: 

The LeftName column, which refers to the name of the network entity on the left hand side of the 

connection. The interpretation of the display format is identical to the EntityName column of the 

master.containers table. 

The RightName column, which refers to the name of the network entity on the right hand side of 

the connection. The interpretation of the display format is identical to the EntityName column of 

the master.containers table. 

The Containment Model 

Although the containment model generated by the stitchers may represent any type of containment, the 

default set of stitchers deduce a combination of physical and logical containment that is optimized for 

performing root cause analysis. 

The result of a query on the databases of MODEL is shown below. 

|phoenix:1.> select * from master.containers; 


.............................. 

{ 


EntityName='SUBNET / 10.10.63.212 / 255.255.255.252'; 

MemberName='10.10.63.214'; 

365


366 

} 

{ 


EntityName='10.10.63.194'; 

MemberName='10.10.63.194[ 0 [ 4 ] ]'; 

} 

..... 

..... 

{ 


EntityName='10.10.63.194'; 

MemberName='10.10.63.194[ 2 [ 4 ] ]'; 

} 

{ 

ObjectId=804; 

EntityName='b031c-1-6500s.Kazeem.San.COM'; 

MemberName='b031c-1-6500s.Kazeem.San.COM[ 7 [ 47 ] ]'; 

} 


|phoenix:1.> 

The format of the data in the master.containers table is subject to how the discovery has been 

stitched together. The default naming convention is shown above and explained in the following section. 

EntityName 

The master.containers.EntityName column holds one of the following: 

The IP address of the device. 

The resolved host name of the device. 

A subnet address with prefix SUBNET and subnet and netmask addresses. 

MemberName 

The master.containers.MemberName column shows a network entity that belongs to the 

corresponding EntityName. If the EntityName of the record has the SUBNET prefix, the 

MemberName column contains an IP address belonging to the subnet. 




Alternatively, if the EntityName contains a single IP address, the MemberName contains a card and port 

number of an entity that is contained within the corresponding EntityName. In this case, MemberName 

is in the following format. 

MemberName='EntityName[ CARD [ PORT ] ]' 

In the example above: 

EntityName refers to the entity within which the interface is contained. 

CARD refers to the card number and PORT refers to the port number. However, if CARD is equal to 

0 then PORT refers to the interface with ifIndex=PORT on the device. Therefore: 

– MemberName='10.10.63.194[ 2 [ 4 ] ]' refers to the interface attached to port 4 

on card 2 within the device 10.10.63.194. 

– MemberName='10.10.63.194[ 0 [ 4 ] ]' refers to the interface with ifindex 

value 4 on the device 10.10.63.194. 

367


13.5 Reinstantiating the Containment Model 

368 

When the completed discovery is sent from DISCO to MODEL, the discovered devices are instantiated to 

Active Object Classes (AOCs). If you subsequently alter the AOC hierarchy or definitions, either through 

the OQL Service Provider or the MONITOR Configuration tool, you can re-instantiate the containment 

model without having to restart the whole domain and the discovery process. 

The discovery process data flow is fully configurable, and can be started and restarted at any point using the 

appropriate stitcher. In order to re-instantiate the containment model, you must start the stitcher that sends 

the topology from DISCO to MODEL. 

The following example explains the steps to re-instantiate the topology using your modified AOC 

definitions. 

Identifying the Current Classes Used in MODEL (Optional) 

Before altering the AOC definitions and re-instantiating the topology, you may wish to check the classes 

that are currently in use, although this is an optional step. You can query the MODEL databases using the 

following commands. These commands return the names of the AOCs to which devices in the current 

topology have been instantiated. You must substitute your domain name and username where NCOMS and 

admin are specified. 

ncp_oql -domain NCOMS -username admin -service Model 



Password: 

|phoenix:1.> select ClassName from master.entityByName; 


{ 

ClassName='Device'; 

} 

{ 


} 

..... 

..... 

ClassName='MainNode'; 

} 

{ 

ClassName='CiscoSwitch'; 

} 


|phoenix:1.> 


Editing the AOC Definitions 

There are three ways to edit the AOC definitions: 


Reinstantiating the Containment Model 

The recommended method of changing the AOCs is to use the MONITOR Configuration tool. The 

MONITOR Configuration tool automatically passes any AOC changes to the CLASS databases. The 

MONITOR Configuration tool is described in the Netcool/Precision IP Monitoring and RCA Guide. 

It is possible to update the CLASS databases (and therefore the current AOC definitions) directly, 

using the OQL Service Provider, although this is not recommended. 

It is also possible to edit the AOC definitions by manually editing the AOC definition files using a 

text editor, although this is not recommended as there is a risk of introducing syntax errors. If you 

edit the AOC files, you must save the updated definitions to a new directory rather than overwriting 

the existing definitions. In order to activate any updates made by editing the text files, you must 

terminate and restart the CLASS component, specifying the updated files as the input for CLASS 

(using the -read_aocs_from command line option) when it is restarted. 

Restarting the Discovery Data Flow at the Appropriate Point 

Once you have updated the AOC definitions, and the updates have been passed to CLASS, you can 

re-instantiate the topology by restarting the discovery at the point at which the topology is passed from 

DISCO to MODEL. 

Note: The discovery data flow is fully configurable. If necessary you can restart the discovery at any point 

by activating the appropriate stitcher. For more information about the discovery stitchers, see Introduction 

to Discovery Stitchers on page 518. 

In order to re-instantiate the topology, you must: 

1. Confirm the existence of a scratchTopology, that is, make sure DISCO is in the rediscovery 

mode. 

2. Determine the name of the stitcher responsible for sending the topology to MODEL. 

3. Invoke that stitcher. 

Determining the Current Operational Mode of DISCO 

To determine whether DISCO is in the rediscovery mode (and that a Scratch Topology exists), query the 

disco.status table as shown below. You must substitute your domain name and username where 

NCOMS and admin are specified. 

ncp_oql -domain NCOMS -username admin -service Disco 


369


370 


Password: 



. 

{ 


m_Phase=1; 





} 


|phoenix:1.> 

From the results returned by the query, you can see that DISCO is currently in the rediscovery mode, that 

is, m_DiscoveryMode=1. 

Determining the Stitcher that Sends the Topology to MODEL 

To determine the name of the stitcher that sends the discovered network topology from DISCO to 

MODEL, you can perform a simple query on the stitchers database. The following query uses a like 

expression to return a list of stitchers whose names either contain the string Model or model. 

|phoenix:1.> select m_Name from stitchers.status 

|phoenix:2.> where m_Name like '.*[mM]odel.*'; 


.. 

{ 

m_Name='SendTopologyToModel'; 

} 


|phoenix:1.> 

The results returned by the OQL query show that the SendTopologyToModel stitcher is required. 

Invoking the SendTopologyToModel Stitcher 

To restart the discovery data flow by invoking the SendTopologyToModel stitcher, you must insert 

the stitcher into the stitchers.actions table, which instructs DISCO to start the specified stitcher 

immediately. The following insert would cause DISCO to start the stitcher. 

|phoenix:1.> insert into stitchers.actions 

|phoenix:1.> ( m_Name ) 

|phoenix:2.> values 

|phoenix:3.> ( 'SendTopologyToModel' ); 


. 



|phoenix:1.> 


Reinstantiating the Containment Model 

As soon as your OQL insert is accepted, the stitcher is invoked and the network topology is sent to MODEL. 

When the topology is sent, it is instantiated in accordance with the newly created AOC hierarchy. 

Confirming the Instantiation (Optional) 

You can check that the new topology has been instantiated in accordance with the instantiate rules specified 

by the new AOC hierarchy by interrogating the databases of MODEL, as shown by the following example 

query. You must substitute the appropriate domain and usernames. 

ncp_oql -domain NCOMS -username admin -service Model 



Password: 

|phoenix:1.> select ClassName from master.entityByName; 


......................... 

{ 

ClassName='Device'; 

} 

{ 


} 

..... 

..... 

{ 

ClassName='CiscoSwitch'; 

} 


|phoenix:1.> 

371


13.6 Databases of MODEL 

372 

At startup, MODEL waits for DISCO to finish the discovery process, create the Scratch Topology and insert 

it into the MODEL databases. The MODEL databases are shown in Table 91. 

Table 91: MODEL Databases 


master The central store for the network topology. 

translations Stores the definitions and translations of external data types used in the master 

database. 

model Used to track topology updates. 

The master Database Schema 

Table 92 describes the master database. 

Table 92: master Database Schema 


master NCHOME/etc/precision 

/ModelSchema.cfg 

master.entityByName 

master.entityByNeighbor 

master.containers 

The master database is responsible for holding all the network entities, their containment, and their 

connections. 


The entityByName Table 


Databases of MODEL 

The entityByName table, described in Table 93, holds information about all the discovered network 

entities. This table is active, populated with the information received from DISCO. Entries made into the 

entityByName table are also used to populate the containers table. 

Table 93: master.entityByName Database Table Schema (1 of 2) 


ObjectId PRIMARY KEY 

NOT NULL 

UNIQUE 

EntityName PRIMARY KEY 

NOT NULL 

UNIQUE 

Long integer The unique Object ID of the network entity. 

Text Unique descriptive name of a network entity. 

Address List of text List of OSI model layer 1 -7 addresses for the entity. 

Description Text Value of sysDescr MIB variable or other suitable 

description of the entity. 

EntityType Externally defined 

entityTypes data 

type 

Integer Element type of the entity. 

(0) Unknown 

(1) Chassis 

(2) Interface 

(3) Logical interface 

(4) VLAN object 

(5) Card 

(6) PSU 

(7) Logical collection 

(8) Module 

ClassName Text Class name of network entity (if applicable). 

EntityOID Text Value of sysOID MIB variable of the entity. 

Status Externally defined 

status data type 

Integer Flag showing status of the network entity. 

Security Text Password to access network entity (if applicable). 

RelatedTo List of text List of entities that are connected to the network 

entity. 

373


374 

Table 93: master.entityByName Database Table Schema (2 of 2) 


Contains List of text List of elements or other containers contained 

within the current network entity. 

UpwardConnections List of text List of containers that contain this entity. 

IsActive Externally defined 


The entityByNeighbor Table 

Boolean Integer Flag indicating whether an Active Object Class is 

needed: 

(1) Active Object Class is needed. 

(0) Active Object Class is not needed 

CreateTime Time Creation time of network entity record in table. 

ChangeTime Time Time of last modification to the network entity 

record. 

ActionType Externally defined 

actions data type 

ExtraInfo Externally defined 


LingerTime NOT NULL 

Default=3 

Integer The type of action associated with the record. 

Object A list of extra information. 

Integer The linger time is used during rediscovery so that 

the new topology can be merged with the existing 

topology. 

The value of LingerTime is decremented if the 

entity is not present in the new topology. The entity 

is only removed from the topology when the value 

of LingerTime reaches 0. 

The entityByNeighbor table, described in Table 94, holds connectivity information for each network 

entity. 

Table 94: master.entityByNeighbor Database Table Schema (1 of 2) 


LeftId PRIMARY KEY 

NOT NULL 

LeftName PRIMARY KEY 

NOT NULL 

RightName NOT NULL PRIMARY 

KEY 

Long integer The Object ID of the left-hand side connection. 

Text The entity name of the left-hand side connection. 

Text The entity name of the right-hand side 

connection. 


Table 94: master.entityByNeighbor Database Table Schema (2 of 2) 


The containers Table 


Databases of MODEL 

Speed Long64 The speed of the connection in bits per second 

(bps). 

Protocol Externally defined 

protocol data type 

RelType Externally defined 

connectionType data 

type 

Duplex Externally defined 


The containers table, described in Table 95, uses the containment model principle to consider each 

network entity as being contained by other network entities. The table, which is automatically populated as 

a result of entries made into the entityByName table, shows the parent of each entity, that is, the object 

that contains the present entity. 

Table 95: master.containers Database Table Schema 

The model Database Schema 

Table 96 describes the model database. 

Integer The transmission protocol type used by the 

connection. 

Integer The type of relationship. 

Boolean Integer Flag indicating whether link is bidirectional (that 

is, full duplex): 

(1) Link is bidirectional. 



NOT NULL 


NOT NULL 

(0) Link is not bidirectional. 

Long integer The unique Object ID of the network entity. 

Text Descriptive name of container network entity. 

MemberName NOT NULL Text The member name of the contained object. 

Table 96: model Database Schema 


model NCHOME/etc/precision/ 

ModelSchema.cfg 

model.config 

model.statistics 

375


376 

The model database is actively used to store information about the topology. This information is used 

during rediscovery so that topologies can be merged efficiently. 

The config Table 

The config table, described in Table 97, stores configuration information used internally by MODEL 

during rediscovery. 

Table 97: model.config Database Table Schema 


LingerTime PRIMARY KEY 

The statistics Table 

NOT NULL 

UNIQUE 

Integer LingerTime for the topology. 

ClassTimeOut NOT NULL Integer Timeout for the AOCs. 

The statistics table, described in Table 98, stores information about previous discoveries. 

Table 98: model.statistics Database Table Schema 


TopologyCount PRIMARY KEY 

NOT NULL 

UNIQUE 

Long A count of the number of times the topology 

has been sent from DISCO to MODEL. 

TopologySendFinished Integer Indicates whether DISCO has finished 

transferring the topology to MODEL. 

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. 


14. STORE.fm July 5, 2005 

Chapter 14: The Persistent Topology Store 

This chapter describes the Precision Server persistent storage engine, STORE, and its interaction with the 

rest of the Precision Server. 


STORE on page 378 

Starting STORE on page 379 

STORE Databases on page 381 



14.1 STORE 

378 

STORE is the persistent storage engine responsible for gathering all information generated by the Precision 

Server multicast traffic on the TIBCO bus (for example, topology and event traffic) and storing it to flat files 

on disk. The cached information can be used to restore your databases if one of the processes terminates 

unexpectedly. 

STORE listens to information (referred to as the subject) on the TIBCO multicast traffic bus. STORE can 

simultaneously listen to more than one subject. It can, for example, listen to topology update information, 

event information, or any particular information on the multicast frequency. 

STORE is inherently extensible because it can be configured to listen to traffic generated by other 

components as they are plugged in to the Precision Server. STORE is also domain-specific, so you can 

configure different instances of STORE to listen to subjects on multiple domains. 


14.2 Starting STORE 


Starting STORE 

It is good practice to ensure that CTRL is configured to launch and manage STORE. STORE can also be 

started manually using the following command line; optional arguments are shown enclosed in square 

brackets. 

ncp_store –domain DOMAIN_NAME [ -cachesize SIZE_IN_MB ] [ -cachepercent 

PERCENTAGE_OF_CACHE_IN_MEMORY ] [ -debug DEBUG ] [ -help ] [ -version ] [ -latency 

LATENCY ] 



-domain DOMAIN_NAME The name of the domain under which to run STORE. 



-latency LATENCY The maximum time in milliseconds (ms) that STORE waits to connect 






-cachepercent 






The default value is 0% cache. This ensures that STORE has a smaller 

memory footprint, as all its databases are stored on disk and not in 

memory. 









of the data is cached in core memory with the remainder being flushed to disk. 

379


Prerequisites for Running STORE 

380 

STORE has no prerequisites except that the domain that you wish to listen to has to be set up, and the 

processes within that domain have to be running before STORE can begin the persistent storage of data. 

Restoring Databases Using STORE 

STORE is supplied preconfigured and you do not normally need to make any configuration adjustments. 

The operation of STORE is transparent to the user. If a process terminates unexpectedly, restart the process 

to automatically populate its databases with any information that has been saved by STORE. 

If you configure CTRL to launch and manage the Precision Server processes, it is important that you 

configure STORE to be launched first (by specifying the process dependencies). Once STORE has been 

launched, any other processes automatically populate their databases with the cached information. 


14.3 STORE Databases 


STORE Databases 

STORE stores data from Netcool/Precision IP processes in a series of databases. By default this includes the 

system database, which configures the operation of STORE itself, and specialized databases for storing 

topology traffic from MODEL and event traffic to and from the RCA Engine. 

The databases used by STORE are listed in Table 100. 

Table 100: STORE Databases 


system Configures the operation of STORE. 

kernel Created by default to enable the storage of topology events. 

Network management application-specific 

databases 

These databases are described in detail in the following sections. 

The system Database Schema 

STORE can be configured to listen to any other subject by configuring an insert into the system database 

and creating the appropriate database. STORE needs a database for every subject on which it is to listen for 

data. 

Note: The term subject refers to the data traffic between processes, transmitted on the TIBCO 

Rendezvous bus. 

Table 101 describes the system database. 

Table 101: Synopsis of the system Database 

Other databases can be added to enable the storage of events specific 

to network management applications such as the RCA Engine. 


system NCHOME/etc/precision/ 

StoreSchema.cfg 

system.snoopers 

system.rollUps 

system.stateRules 



page 10. 

381


382 

STORE uses the system database to define the listening methodology, which includes the subjects to 

which it listens and the name of the databases that it updates. 

The snoopers Table 

The snoopers table, described in Table 102, stores a record for each subject to which STORE listens. 

Table 102: system.snoopers Database Table Schema 


Subject PRIMARY KEY 

UNIQUE 

NOT NULL 

Text The subject to listen to. 

DataArea NOT NULL Text The database into which information is inserted when 

STORE detects information on the subject to which it is 

listening. 

BaseTable NOT NULL Text The table of the database specified in DataArea into 

which information is inserted when detected. 

CreateRule Text The rule that is run to create records in the persistent store. 

ChangeRule Text The rule that is run to update records in the persistent store. 

DeleteRule Text The rule that is run to delete records from the persistent 

store. 

You can interpret each record in the snoopers table as follows: 

STORE listens for a Subject on the TIBCO Rendezvous bus and inserts incoming subjects into 

the DataArea.BaseTable. 

STORE ensures that the CreateRule, ChangeRule or DeleteRule are executed depending 

on the incoming subject. 


The rollUps Table 



The rollUps table, described in Table 103, specifies how often STORE executes the rules that govern the 

referential integrity of the STORE database tables. The timed fields work in a similar way to the UNIX 

command crontab, so that a value of 0 causes the rule to be executed on every interval of the field (that 

is, a value of 0 in the month field causes it to execute every month). 

Table 103: system.rollUps Database Table Schema 


Name PRIMARY KEY 

NOT NULL 

Text Name of the rollup rule. 

SchedMin Integer Run on this minute. 

SchedHour Integer Run on this hour. 

SchedDay Integer Run on this day. 

SchedDate Integer Run on this date. 

SchedMnth Integer Run on this month. 

SchedYear Integer Run on this year. 

DataArea Text The target database of the actions to be carried out on 

the rollup rule. 

BaseTable Text The target database of the actions to be carried out on 

the rollup rule. 

RollupRule Text The rule to be invoked by the presently defined rule. 

You can interpret each record in the rollUps table as follows: 

Run rule Name when the time is SchedHour, SchedMin every SchedDay day or on the date 

SchedDate of the month SchedMnth of year SchedYear. 

In addition, the rule Name runs the rollup rule RollupRule on the DataArea.BaseTable 


383


384 

The stateRules Table 

The stateRules table, described in Table 104, defines the rules to be used by STORE to create, update, 

delete, and manipulate records. This table also defines the criteria that must be met before a rule can be 

executed. 

Table 104: system.stateRules Database Table Schema 


Name PRIMARY KEY 

NOT NULL 

The kernel Database Schema 

Table 105 describes the kernel database. 

STORE uses the kernel database to store the topology event stream. The tables of the kernel database are 

both copies of the master.entityByName table of MODEL. The only difference is that the 

modelLog table is a record of all the entities in the topology and the activeModel is actively updated 

as records are added, deleted or updated. 

The modelLog table 

Text Name of the rule. 

Filter Text Rule execute criteria. 

Execute Text The OQL statements to execute. 



Table 105: Synopsis of the kernel Database 

Boolean Integer An activity status flag to determine whether the rule is 

currently running: 

(1) Rule is currently running. 

(0) Rule is not currently running. 


kernel NCHOME/etc/precision/ 


kernel.modelLog 

kernel.activeModel 

The modelLog table, described in Table 106, is a store of all the entities known in the network topology, 

regardless of their current status. By default, the modelLog table is configured as the target database table 

for Netcool/Precision IP topology events. This table is populated automatically when STORE starts up, but 

is not the target of the rules specified within the snoopers table, so it does not get updated and therefore 

remains the ‘persistent store’ of the network topology. 


Each record in the table represents a device in the network topology. 

Table 106: kernel.modelLog Database Table Schema (1 of 2) 



NOT NULL 


NOT NULL 


Long integer Unique Object ID of the network entity. 


Text Unique descriptive name of a network entity. 

Address List of text List of OSI model layer 1-7 addresses for the 

entity. 

Description Text Value of sysDescr MIB variable or other 

suitable description of the entity. 


entityTypes data type 


(0) Unknown 

(1) Chassis 

(2) Interface 



(5) Card 

(6) PSU 


(8) Module 

ClassName Text Class name of the network entity (if applicable). 




Integer Flag showing the status of the network entity. 


RelatedTo List of text List of connections to the network entity. 




385


386 

Table 106: kernel.modelLog Database Table Schema (2 of 2) 




The activeModel Table 

Boolean 

Integer 

Flag indicating whether an Active Object Class is 

needed: 


(0) Active Object Class is not needed. 



record. 





Integer Type of record. 


LingerTime NOT NULL Integer The linger count for entity removal during 

rediscovery. 

The activeModel table, described in Table 107, is a store of all the active entities in the network 

topology. The activeModel table tracks the active topology, since it is the target database table for the 

rules within the snoopers table entry for Netcool/Precision IP topology events, and is constantly updated 

as changes are made to the network topology. 

Table 107: kernel.activeModel Database Table Schema (1 of 2) 



NOT NULL 


NOT NULL 

Long integer Unique Object ID of the network entity. 

Text Unique descriptive name of the network entity. 

Address List of text List of OSI model layer 1-7 addresses for the entity. 

Description Text Value of sysDescr MIB variable or other suitable 



Table 107: kernel.activeModel Database Table Schema (2 of 2) 




type 



(0) Unknown 

(1) Chassis 

(2) Interface 



(5) Card 

(6) PSU 


(8) Module 


ClassName Text Class name of the network entity (if applicable). 




Integer Flag showing the status of the network entity. 


RelatedTo List of text List of connections to the network entity. 






Boolean Integer Flag indicating whether an Active Object Class is 

needed: 


(0) Active Object Class is not needed 



record. 





Integer Type of record. 


LingerTime NOT NULL Integer The linger count for entity removal during 

rediscovery. 

387


The fault Database Schema 

388 

Table 108 describes the fault database. 

Table 108: Synopsis of the fault Database 


fault NCHOME/etc/precision/ 


You can configure STORE to listen to events from other network management applications (such as the 

RCA Engine) as they become available, by appending inserts to the system database and defining a new 

database to store the data. By default, STORE is configured to persistently store event data from the RCA 

Engine (if available) using the fault database. 

The eventLog Table 

fault.eventLog 

fault.events 

fault.comments 

The eventLog table, described in Table 109, persistently stores data from the event stream of the RCA 

Engine. It is similar to the kernel.modelLog table in that it is initialized when STORE starts up, but 

is not updated by the stateRules. 

Table 109: fault.eventLog Database Table Schema (1 of 3) 


EventId PRIMARY KEY 

NOT NULL 

Long integer The event ID. 


Text The network entity associated with the 

NOT NULL 

event. 

ClassName Text The associated AOC. 

Description Text A textual description of the event. 

EventName Varchar (256) Name of the poll that created the event. 

EventType Externally defined 

eventType data type 

Severity PRIMARY KEY 

NOT NULL 

Externally defined 

severity data type 

Integer Type of event (event/data/alert). 

Integer The OSI Severity code. 






Contact Text The contact person responsible for the 

device that generated the event. 

AssignedTo Text The person that has been assigned the 

event. 

Acknowledged Externally defined 


Boolean Integer Flag denoting whether or not an event has 

been acknowledged: 

(1) Event has been acknowledged. 

(0) Event has not been acknowledged. 

Location Text Location of the device that generated the 

event. 

CorrelatedId List of type long 

integer 

List of associated eventIDs. 

EventGroupId Long integer List of associated events. 

ActionGlyph Text Alert display glyph (visual icon). 

CreateTime Long Time of first occurrence of event. 

ChangeTime Long Time of last occurrence of event. 

Occurred Integer Number of identical events that have 

occurred. 

CauseType Externally defined 

causes data type 



InternalAction Externally defined 

internalActions data 

type 

Integer The type of alert (symptom or root cause): 

(0) Unknown 

(1) Root cause 

(2) Symptom 

Integer The type of action that the event represents. 

Integer The internal action associated with the 

event. This may be one of the following: 

New 

Acknowledged 

Unacknowledged 

AgentAddress Text The location of the Polling agent. 




389


390 



Dist Integer Indicates whether the event is to be 

distributed with DIST. 

AlertType Text The type of alert; for example, a topology 

alert or a temporary alert. 

The events Table 

The events table, described in Table 110, is a master record of all events in the system. Each record in 

the table represents a complete event record, and is actively updated by the stateRules. 

Table 110: fault.events Database Table Schema (1 of 2) 


EventId PRIMARY KEY 

NOT NULL 

UNIQUE 

Long integer The event ID. 


Text The name of the network entity associated 

NOT NULL 

with the event. 

ClassName Text The associated AOC. 

Description Text A textual description of the event. 

EventName Varchar (256) Name of the poll that created the event. 

EventType Text A set of rules that are to be run on the event. 

Severity Externally defined 

eventType data type 

Contact PRIMARY KEY 

NOT NULL 


severity data type 

Integer Type of event (event/data/alert). 

Integer The OSI Severity code. 

AssignedTo Text The contact person responsible for the 

device that generated the event. 

Acknowledged Text The person that has been assigned the 

event. 


Table 110: fault.events Database Table Schema (2 of 2) 


Location Externally defined 




Boolean Integer Flag denoting whether or not an event has 

been acknowledged: 

(1) Event has been acknowledged. 

(0) Event has not been acknowledged. 

CorrelatedId Text Location of the device that generated the 

event. 

EventGroupId List of type long 

integer 

List of associated event IDs. 

ActionGlyph Long integer List of associated events. 

CreateTime Text Alert display glyph (visual icon). 

ChangeTime Long integer Time of first occurrence of event. 

Occurred Long integer Time of last change to the event (that is, the 

last time the event occurred). 

CauseType Integer Number of identical events that have 

occurred. 


causes data type 



AgentAddress Externally defined 


type 

Integer The type of alert (symptom or root cause): 

(0) Unknown 

(1) Root cause 

(2) Symptom 

Integer The type of action that the event represents 

(create/change/delete). 



New 

Acknowledged 


ExtraInfo Text The location of the Polling agent. 

Dist Externally defined 



AlertType Integer Indicates whether the event is to be 

distributed with DIST. 

Column name Text The type of alert; for example, a topology 

alert or a temporary alert. 

391


392 

The comments Table 

The comments table, described in Table 111, stores comments associated with the event records. 

Table 111: fault.comments Database Table Schema 


EventId NOT NULL Long integer The event ID. 

CreateTime NOT NULL Long The creation time of the comment. 

CreatedBy Text The writer of the comment. 

CommentBody Text The text of the comment itself. 



type 

Example Configurations: Configuring STORE to Listen for Topology 

Traffic 

The following example insert configures STORE to listen for topology traffic. 

insert into system.snoopers 

( 

Subject, DataArea, BaseTable, 

CreateRule, ChangeRule, DeleteRule 

) 

values 

( 

'RIVERSOFT.3.0.MODEL.NOTIFY', 'kernel', 'modelLog', 

'modelCreate', 'modelUpdate', 'modelDelete' 

); 

This example OQL insert above instructs STORE to: 

Listen to the RIVERSOFT.3.0.MODEL.NOTIFY bus (on which topology traffic is passed). 

Store data from this subject in the kernel.modelLog table. 



Apply the modelCreate, modelUpdate and modelDelete state rules. 

The kernel.modelLog table is described in Table 106 on page 385. The modelCreate, 

modelUpdate and modelDelete state rules are defined and explained in the following sections. 

New 

Acknowledged 



The modelCreate State Rule 

The following example creates the modelCreate rule, which is defined as follows: 

The rule is called modelCreate. 

No filter is to be applied. 



The rule itself extracts all the data from the record that has been received on the message bus and 

inserts the data into the kernel.activeModel table. 

insert into system.stateRules 

( 

Name, 

Filter, 

Execute, 

IsActive 

) 

values 

( 

'modelCreate', 

'', 

'insert into kernel.activeModel 

( eval(text, "RECORD_NAMES()") ) 

values 

( eval(text, "RECORD_VALUES()") );', 

1 

); 

The modelUpdate State Rule 

The following example creates the modelUpdate rule, which is defined as follows: 

The rule name is modelUpdate. 


The rule itself: 

– Deletes any existing record with the same Object ID as the new record from the 

kernel.activeModel database. It deletes the appropriate record by extracting the Object 

ID from the new record and using an OQL delete where statement. For more 

information about OQL, see Appendix B: The Object Query Language on page 479. 

– Extracts all the data from the record that has been received on the message bus and inserts the 

data into the kernel.activeModel table. 


( 

Name, 

393


394 

) 

values 

( 

); 

Filter, 

Execute, 

IsActive 

'modelUpdate', 

'', 

'delete from kernel.activeModel 

where 

( ObjectId=eval(long,"&ObjectId"); ); 

insert into kernel.activeModel 


values 


1 

The modelDelete State Rule 

The following example creates the modelDelete rule, which is defined as follows: 

The rule name is modelDelete. 

No filter is used. 

The rule deletes any existing record with the same Object ID as the new record from the 

kernel.activeModel database. It deletes the appropriate record by extracting the Object ID 

from the new record and using an OQL delete where statement. For more information about 

OQL, see Appendix B: The Object Query Language on page 479. 


( 

Name, 

Filter, 

Execute, 

IsActive 

) 

values 

( 

'modelDelete', 

'', 

'delete from kernel.activeModel 

where 

( ObjectId=eval(long,"&ObjectId") );', 

1 

); 




Example Configurations: Configuring STORE to Listen for Event Traffic 

The following OQL insert instructs STORE to: 

Listen to the RIVERSOFT.3.0.EVENT.NOTIFY bus (on which event traffic is passed). 

Store data from this subject in the fault.eventLog table. 

Apply the eventCreate, eventUpdate and eventDelete state rules. 

The fault.eventLog table is described in Table 109 on page 388. The eventCreate, 

eventUpdate and eventDelete state rules are defined and explained in the following sections. 

insert into system.snoopers 

( 

Subject, DataArea, BaseTable, 

CreateRule, ChangeRule, DeleteRule 

) 

values 

( 

'RIVERSOFT.3.0.EVENT.NOTIFY','fault','eventLog', 

'eventCreate','eventUpdate','eventDelete' 

); 

The eventCreate State Rule 

The following example creates the eventCreate rule, which is defined as follows: 

The rule is called eventCreate. 


The rule itself extracts all the data from the record that has been received on the message bus and 

inserts the data into the fault.events table. 


( 

Name, 

Filter, 

Execute, 

IsActive 

) 

values 

( 

'eventCreate', 

'', 

'insert into fault.events 


values 


395


396 

); 

1 

The eventUpdate State Rule 

The following example creates the eventUpdate rule, which is defined as follows: 

The rule name is eventUpdate. 


The rule itself: 

– Deletes any existing record with the same Event ID as the new record from the 

fault.events database. It deletes the appropriate record by extracting the Event ID from 

the new record and using an OQL delete where statement. For more information about 

OQL, see Appendix B: The Object Query Language on page 479. 

– Extracts all the data from the record that has been received on the message bus and inserts the 

data into the fault.events table. 


( 

Name, 

Filter, 

Execute, 

IsActive 

) 

values 

( 

'eventUpdate', 

'', 

'delete from fault.events 

where 

( EventId=eval(long,"&EventId"); ); 

insert into fault.events 


values 


1 

); 


The eventDelete State Rule 

The following example creates the eventDelete rule, which is defined as follows: 

The rule name is eventDelete. 

No filter is used. 



The rule deletes any existing record with the same Event ID as the new record from the 

fault.events database. It deletes the appropriate record by extracting the Event ID from the 

new record and using an OQL delete where statement. For more information about OQL, see 

Appendix B: The Object Query Language on page 479. 


( 

Name, 

Filter, 

Execute, 

IsActive 

) 

values 

( 

'eventDelete', 

'', 

'delete from fault.events 

where 

( EventId=eval(long,"&EventId") );', 

1 

); 

397


398 


15. CLASS.fm July 5, 2005 

Chapter 15: The Active Object Class Server 

This chapter describes CLASS, the component that manages and distributes information contained within 

the Active Object Classes (AOCs) to other Precision Server processes and any applications that may require 

class-based information. This chapter also describes how to manually edit the AOCs. 


Introduction to the AOC Server on page 400 

Starting CLASS on page 403 

The CLASS Database on page 405 

Manually Editing AOCs on page 409 



15.1 Introduction to the AOC Server 

400 

CLASS is the dynamic library management system responsible for managing the AOCs. It is the only 

component that has direct contact with the AOC definitions, and it distributes these definitions to any 

component that needs them. For example, CLASS distributes the poll definitions (polling instructions) to 

MONITOR, the component that is responsible for controlling network monitoring. 

The supplied MONITOR Configuration tool can be used to browse and modify the AOC definitions. 

When a change is made, the MONITOR Configuration tool automatically sends the updates to CLASS, 

which modifies its internal records and broadcasts the modifications to any component that requires them. 

MONITOR and the MONITOR Configuration tool are described in detail in the Netcool/Precision IP 


The Precision Server Aproach to Network Modelling 

In order to create a model of the network that is not only logical and efficient, but also able to adapt to 

network changes with minimal intervention, the Precision Server uses two key principles when modelling 

the network: object modelling and the containment model. 

Object modelling involves grouping together devices with similar properties. Management policies can then 

be defined for the group of objects as a whole, rather than for the individual devices. In the Precision Server, 

a hierarchy of Active Object Classes (AOCs) describes the characteristics and behavior of devices, and defines 

their management policies (that is, the rules that specify how the Precision Server handles a device of that 

class). 

Containment modelling is concerned with how devices are related to each other. The key benefit is that it 

models both the physical and logical relationships between devices. 

This section discusses the principles of object modelling and the containment model in more detail, before 

explaining how the Precision Server implements these concepts. 


Active Object Classes and the Precision Server 


Introduction to the AOC Server 

The Precision Server uses a class hierarchy to model network devices. An example is shown in Figure 88. 

Figure 88: Class Hierarchy of Network Devices 

The management policies specified in the class hierarchy described how to treat instances of devices and how 

to handle events relating to them. In the example shown in Figure 88, you may specify that you want to poll 

all discovered devices once every minute. This could be accomplished by making the specification a 

management policy of the root class Core. Any class that is located under the Core automatically inherits 

this policy unless specifically overridden in its class file. 

One subclass of Core in this example is Device, where you can specify the management policies for a 

generic device. Further down the hierarchy, you can classify devices by manufacturer and assign 

manufacturer-specific policies. For example, you can assign a policy for Cisco devices based on the value of 

the IOSrev MIB variable. The Cisco class can be specialized even further by specifying the policies for 

managing Cisco 7500 routers that are carried out automatically if a Cisco 7500 router is found. 

401


402 

The policies for a Cisco 7500 router could include: 

1. Ping the router once every minute (inherited from the Device class). 

2. Examine the MIB variable IOSrev (inherited from the Cisco subclass). 

3. Apply the management policies that are specific to the Cisco 7500 subclass. 

The advantage of the class hierarchy approach is that you can share common management tasks for routers 

amongst all routers, while specializing some tasks for particular types of router. 

Multiple Inheritance 

The Precision Server does not permit multiple inheritance, which is the ability of a new class to inherit the 

characteristics from more than one class. This prevents the situation where classes cannot be effectively 

managed (as the class hierarchy grows) because of poorly designed interrelationships between classes. 

Active Classes 

A key feature of the Precision Server is that the object classes specified in the class hierarchy are active, that 

is, the class description contains the actions that are taken automatically upon instantiation of an object class. 

Note: Instantiation is the act of creating a new object based on a class template. 

The use of active classes means that, when a given device is discovered, the system looks at the corresponding 

class file to determine what action to take with regard to the device. For example, if the Precision Server 

comes across a Cisco 7500 router on the network, the Cisco 7500 class file description automatically tells 

the system how to manage the 7500 upon instantiation. 

Another key feature of the AOCs is that they are dynamic. Alterations made to the class descriptions with 

the MONITOR Configuration tool are automatically broadcast to other components by the Precision 

Server class management system, CLASS. This means that the Precision Server can provide dynamic 

self-adapting network management because, as the Precision Server sees devices appearing and disappearing 

from the network topology, it automatically updates the network map and adopts the appropriate 

management policies. 


15.2 Starting CLASS 


Starting CLASS 

Micromuse recommends that CTRL, the domain process controller, is configured to start CLASS 

automatically at the appropriate time. CLASS can also be started manually with the following command 

line; optional arguments are shown enclosed in square brackets. 

ncp_class -domain DOMAIN_NAME [ -cachesize SIZE_IN_MB ] [ -cachepercent 

PERCENTAGE_OF_CACHE_IN_MEMORY ] [ -debug DEBUG ] [ -help ] [ -latency LATENCY ] [ 

-read_aocs_from DIRECTORY_NAME ] [ -version ] [ -write_aocs_to DIRECTORY_NAME ] 




-cachepercent 







-domain DOMAIN_NAME The name of the domain under which to run CLASS. 





-latency LATENCY The maximum time in milliseconds (ms) that CLASS waits to connect 





-read_aocs_from DIRECTORY_NAME The full path of the directory from which to read the AOC definitions. 



-write_aocs_to DIRECTORY_NAME The full path to which CLASS writes the current state of the Active 

Object Classes every minute. 

When CLASS is launched it obtains the AOC definitions either from a directory of AOC files or from the 

cache files contained in NCHOME/var/precision. 



page 10. 

403


404 

You can control the location of the source AOC definitions using the command line options. The possible 

combinations are as follows: 

If you omit the -read_aocs_from argument from the command line, CLASS automatically 

reads the cache files from NCHOME/var/precision if they are present. If there are no valid 

cache files, CLASS uses the definitions in NCHOME/precision/aoc. 

If you specify a directory using the -read_aocs_from option, CLASS initializes itself with the 

AOCs located in the specified directory. CLASS automatically moves any existing cache files to a 

backup directory. You should not normally use the -read_aocs_from argument when you 

restart CLASS, as any changes that were made using the MONITOR Configuration tool and written 

to the cache are lost. 

Regardless of the options specified, CLASS generates a warning if the files within the 

NCHOME/precision/aoc directory are more recent than the cache files contained within the 

NCHOME/var/precision directory. 

If you specify a -write_aocs_to directory, CLASS not only updates its cache during its operation, but 

also regularly writes a copy of the complete AOC definitions to the specified directory. If CLASS dies, you 

have an up-to-date version of the AOCs in a text format in addition to the cache. 

It is not advisable to write AOCs back to the directory from which they are read, since this would overwrite 

the original AOCs. 

Prerequisites for Running CLASS 

There are no prerequisites for running CLASS. 


15.3 The CLASS Database 


The CLASS Database 

The class database enables CLASS to manage the Active Object Classes (AOCs). It consists of two main 

tables, activeClasses and staticClasses, which are populated at startup as CLASS reads the 

AOC definitions. The two tables represent two different views of the class hierarchy. 

A third table, the policies table, is populated and used internally within the MONITOR Configuration 

tool. 

The class Database 

Table 113 describes the class database and its tables. 

Table 113: Synopsis of the class database and its tables 

Database class 

Defined in NCHOME/etc/precision/ClassSchema.cfg 

Fully qualified database table names class.activeClasses 

The activeClasses Table 

class.staticClasses 

class.policies 

The activeClasses table, described in Table 114, holds the full definition of every active AOC. 

Table 114: class.activeClasses Database Table Schema (1 of 2) 


ClassName PRIMARY KEY 

NOT NULL 

UNIQUE 

Text Unique name of the AOC. 

SuperClass NOT NULL Text Name of the parent AOC. 

Dictionary List of text List of data dictionaries used by the AOC. 

Instantiate NOT NULL Text Rules for instantiating the AOC. 

Extensions Externally defined 

extension data type 

Object of 

extension data 

type 

List of extensions contained within the AOC. 

VisualIcon NOT NULL Text The icon associated with this AOC (to be displayed 

in a GUI such as the Precision Desktop). 

405


406 

Table 114: class.activeClasses Database Table Schema (2 of 2) 


MenuRules Externally defined 

menurule data type 

Menu Externally defined 

menu data type 



The staticClasses Table 

List of object 

data type 

(object is of the 

menurule data 

type) 

List of object 

data type 


menu data 

type) 

A list of menu rules associated with the AOC. 

List of menu options available in the GUI for this 

AOC. 

Integer List of action types to be taken. 

The staticClasses table, described in Table 115, holds the contents of a raw AOC as it is defined in 

the .aoc file. 

Table 115: class.staticClasses Database Table Schema (1 of 2) 


ClassName PRIMARY KEY 

NOT NULL 

UNIQUE 

Text Unique name of the AOC. 

SuperClass NOT NULL Text Name of the parent AOC. 

Dictionary List of text List of data dictionaries used by the AOC. 

Instantiate NOT NULL Text Rules for instantiating the AOC. 

Extensions Externally defined 

extension data type 

Object of 

extension data 

type 

List of extensions contained within the AOC. 

VisualIcon NOT NULL Text The icon associated with this AOC. 

MenuRules Externally defined 

menurule data type 

List of object data 

type (object is of 

the menurule 

data type) 

A list of menu rules associated with the AOC. 


Table 115: class.staticClasses Database Table Schema (2 of 2) 


Menu Externally defined 

menu data type 



The policies Table 


List of object data 

type (object is of 

the menu data 

type) 

The CLASS Database 

List of menu options available in a GUI for this 

AOC. 

Integer A list of action types to be taken. 

The policies table, described in Table 116, stores a series of predefined management policies that can 

be configured in the MONITOR Configuration tool. These policies provide a high level interface into 

groups of network management policies that are supplied with the Netcool/Precision IP and that can be 

turned on and off, providing a limited level of flexibility to end users that is suitable for the majority of 

networks and much simpler to configure than editing every available parameter. 

Since the policies are predefined and supplied with Netcool/Precision IP you do not normally need to 

configure inserts into the policies table. Additionally, although the policies are included with the 

Netcool/Precision IP, this functionality is only applicable to users of the RCA Engine. 

Table 116: class.policies Database Table Schema 


PolicyName PRIMARY KEY 

NOT NULL 

UNIQUE 

Text Unique name of this set of management 

policies. 

PolicyDescription Text A description of the policy that appears in 

the Policy Editor of the MONITOR 


PolicyScope Text The AOC definition that contains the rule 

sets, event correlation rules and poll 

definitions that are used in this policy. 

PollDefinitions Externally defined 

polldefinition type 

RuleDefinitions Externally defined 

ruledefinition type 

ControlDefinitions Externally defined 

controldefinition 

type 

List of type object 


polldefinition type) 



ruledefinition type) 



controldefinition type) 

A list of poll definitions used in this policy 

and descriptions to be displayed in the 

MONITOR Configuration tool. 

A list of event correlation rules used in this 

policy. 

A list of the controls associated with this 

policy that are available in the MONITOR 

Configuration tool. 

407


408 

The description fields in the policies table contain text that appears in the MONITOR Configuration 

tool. You can configure the appearance of this text using HTML tags. The HTML tags available are listed 

in Table 117. 

Table 117: HTML Tags Available to Configure the Appearance of Text in the MONITOR Configuration Tool 

HTML tag Function 

Encloses bold text. 

Encloses text in italics. 

Encloses underlines text. 

Encloses subscript text. 

Encloses superscript text. 

Inserts a horizontal line. 


15.4 Manually Editing AOCs 

! 


Manually Editing AOCs 

The recommended method of editing AOC files is using the MONITOR Configuration tool. For detailed 

information on using the MONITOR Configuration tool, see the Netcool/Precision IP Monitoring and RCA 

Guide. It is possible to edit AOCs using vi or another text editor of your choice; however, this should not 

be done while any Precision Server or RCA Engine components are running. 

Warning: Whichever editing method you choose, Micromuse strongly recommend that you make a backup 

of any original AOCs you intend to edit. If you inadvertently overwrite an original, the backup copy can be 

restored. 

To create a copy of all the AOCs in the aoc directory, type the following commands: 

cd NCHOME/precision 

cp -pr aoc my_aocs 

This creates a copy of the contents of NCHOME/precision/aoc (the directory that contains all the 

AOC definitions by default) in a new directory, NCHOME/precision/my_aocs. You can now edit the 

class definitions in my_aocs, leaving your original definitions unaltered. When you start CLASS, you can 

do so using the -read_aocs_from option to specify the NCHOME/precision/my_aocs 

directory, so that your edited class definitions are read and broadcast to all other processes. 

If any problems occur as a result of editing an AOC definition, the file can be restored to its pre-edit status 

by typing the following commands: 

cd NCHOME/precision 

cp -pr aoc/name_of_original_file.aoc 

my_aocs/name_of_corrupted_file.aoc 

The Architecture of an AOC 

This section describes the syntax necessary for understanding the architecture of an AOC. 

Preliminaries 

To fully understand the functionality of the AOCs, review the sections of this guide that cover language 

prerequisites, including OQL and the semantics of the eval statement. 

409


410 

Basic Syntax 

The basic syntax and naming conventions described in Table 118 are used throughout the AOCs: 

Table 118: Syntax characters used in AOCs 

Character Name Meaning 

[ ] Square brackets Typically defines a list of items. There can be zero or more items within the 

brackets and each item must be separated by a single comma. 

{ } Curly brackets Typically defines an object. 

" " Double quotes Typically used to enclose assignments to various attributes (of datatype text) 

within an AOC. As a general rule all assignments use double quotes. 

' ' Single quotes Typically used to enclose evaluations of column names or system variables 

within an eval statement. Single quotes can be used within double quotes, 

but double quotes cannot be used within single quotes. 

, Single comma Typically used either as a separator between elements of a list or to terminate 

an assignment to a particular attribute. 

; Semi colon Typically used to terminate assignments to the major components listed 

below. 

AOC Components - An Overview 

The major components of the AOC, and their names as they appear in the AOC, are: 

The name of the active object class (active object) 

The super class (super_class) 

The data dictionary (data_dictionary) 

The instantiate rule (instantiate_rule) 

The application extensions (extension for Fault) 

– The event correlation rules (rules) 

– The poll definitions (poll_list) 

The visual icon (visual_icon) 

The menu methods (menu_rules) 

A Complete AOC File Explained 

This section deconstructs and analyzes an entire AOC file. 


The Name of the Active Object 



The active object attribute declares the name of the current class. Any unique text string is valid 

between the double quotes. The entire AOC file is contained within the first pair of curly brackets. A 

semicolon follows the final bracket to terminate the AOC. 

active object "Core" 

{ 

super_class = " "; 

data_dictionary = [ ]; 

... 

... 

menu_rules = { }; 

}; 

The Super Class 

Defines the name of the AOC from which the current class inherits. The name between the double quotes 

must be the name of an already-defined AOC. In the Netcool/Precision IP AOC hierarchy, Core is the only 

class that has an unassigned super_class. When editing any other class the super_class must never 

be left empty. 

super_class = ""; 

The Data Dictionary 

Contains the ASN.1 descriptions of all the data types used by the AOC. 

data_dictionary = [ "rivCore", "rivCoreAttributes", "rfc1213" ]; 

The Instantiate Rule 

A logical test against the attributes of the record of an entity in the master.EntityByName database 

of MODEL that defines how the system determines which class an object belongs to. The schema of the 

master.EntityByName database is defined in ModelSchema.cfg. If an object meets the 

instantiation criteria for more than one class, it automatically instantiates to the lowest leftmost class in the 

hierarchy. 

instantiate_rule = "EntityOID like '.*'"; // this instantiates 

//everything by default 

411


412 

The Application Extensions 

The extensions are additions to the AOCs used by the components of the RCA Engine. The RCA Engine 

extensions are: 

Event correlation rules (rules) 

Poll definitions (poll_list) 

The RCA Engine extensions appear in the AOC as follows. 

extension for Fault = { 

}; 

rules = [], 

poll_list = [] 

The event correlation rules are contained within the first pair of square brackets. The poll definitions are 

contained within the second pair of square brackets. 

The Event Correlation Rules 

The event correlation rules determine how AMOS (the event correlation engine) correlates events into alerts. 

Defining Multiple Event Correlation Rules 

The table below shows the syntax for defining N event correlation rules. 

rules = [ 

], 

{ path/ruleset/rulename 1 }, 

.... 

.... 

{ path/ruleset/rulename N } 

The event correlation rules are written in individual text files. Only the filename of the rule is specified in 

the AOC. By default, the full filename and path of a rule are specified as follows: 

NCHOME/precision/aoc/rca_rules/ruleset/rulename.rule 

You can keep your event correlation rules in a different directory to the above. In this case, you must provide 

an absolute path to the rule in the AOC. Within this section of the AOCs, absolute path names must begin 

with a forward slash '/', otherwise they are treated as being relative to 

NCHOME/precision/aoc/rca_rules. 

For a detailed explanation of the function and syntax of every attribute and sub-attribute of the event 

correlation rules, see the Netcool/Precision IP Monitoring and RCA Guide. 


The Poll Definitions 



The poll definitions specify the type of Polling agent used to poll the network, the agent executable and the 

stitcher used. They also define variables that the stitcher can access. 

poll_list = [ 

], 

{ poll 1 }, 

.... 

.... 

{ poll N } 

AOC Syntax and Defining Multiple Poll Definitions 

Within the square brackets there can be zero or more poll definitions. Each poll definition consists of a 

number of attributes, which may be boolean integers, text strings, or lists. Which attributes are used depends 

on the type of poll being conducted. For a full explanation of the function and attributes of the poll 

definitions, see the Netcool/Precision IP Monitoring and RCA Guide. 

A simplified example poll definition is given below. 

poll_list = [ 

] // end of poll_list 

{ // start of first poll definition 

Attribute 1, 

Attribute 2, 

... 

Attribute n, 

} //end of first poll definition 

413


414 

The Visual Icon 

The visual icon refers to a *.xpm image file in the NCHOME/precision/images directory. This icon 

is displayed in the MONITOR Configuration tool. The name between the double quotes must be a valid 

image filename in this directory. If the double quotes are left unassigned, the icon is inherited from the 

parent class. 

visual_icon = "DefaultIcon"; 

Menu Methods 

The menu methods enable users to interact with objects by selecting various menu actions from the 

Operator menu in the Precision Desktop. These menu actions are defined by the menu methods. 

menu_rules = [ 

]; 

{ rule 1 }, 

.... 

.... 

{ rule N } 

AOC Syntax and Defining Multiple Menu Methods 

Within the square brackets there can be zero or more menu methods. For more information on the 

configuration of menu methods, see the Netcool/Precision IP Desktop User Guide. 


16. TrapMux.fm July 5, 2005 

Chapter 16: The SNMP Trap Multiplexer 

This chapter describes the SNMP trap multiplexer, its function and its configuration. 


SNMP Trap Multiplexing on page 416 

Starting TrapMux on page 417 

Configuring TrapMux on page 418 

Replaying Traps on page 422 



16.1 SNMP Trap Multiplexing 

416 

In most networks, traps arrive on a single default port (usually port 162). This can cause problems if you 

have more than one process that needs to listen for traps, as only one process can bind to one port at a time. 

An example of this might be where you want to have the Trap Monitoring agent and the DISCO Trap agent 

both listening for traps. 

The solution is to have ncp_trapmux listen to a single port and forward all the traps it receives to a set 

of host/socket pairs or, using Rendezvous, to a set of domains. 

By default, TrapMux listens for traps on port 162, but you can change this by inserting an alternative port 

number into the trapMux.config database table. 

TrapMux 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. 


16.2 Starting TrapMux 


Starting TrapMux 

It is good practice to ensure that CTRL is configured to launch and manage TrapMux. TrapMux can also 

be started manually using the following command line; optional arguments are shown enclosed in square 

brackets. 

ncp_trapmux –domain DOMAIN_NAME [ -debug DEBUG ] [ -help ] [ -version ] [ -latency 

LATENCY ] 



-domain DOMAIN_NAME The name of the domain under which to run TrapMux. 

-debug DEBUG The level of debugging output (1-4, where 4 represents the most detailed output). 

-help Displays the command line options. Does not start the component even if used in 

conjunction with other arguments. 

-latency LATENCY The maximum time in milliseconds (ms) that TrapMux waits to connect to another 

Precision Server process by means of the messaging bus. This option is useful for 

large and busy networks where the default settings can cause processes to assume 

that there is a problem when in fact the communication delay is a result of network 

traffic. 



417


16.3 Configuring TrapMux 

418 

This section gives some examples of how you might configure TrapMux and describes how to control 

TrapMux using the OQL Service Provider. Schemas of the TrapMux databases are also included. 

Example TrapMux Configuration 

A typical session with ncp_trapmux would be as follows: 

1. Edit the schema file, NCHOME/etc/precision/TrapMuxSchema.cfg, to contain a set of 

host/socket pairs and a set of Rendezvous domains. This can be done by appending the following 

lines to the schema: 

insert into trapmux.sinkDomains (domain) values ("Test1"); 

insert into trapmux.sinkDomains (domain) values ("Test2"); 

insert into trapmux.sinkHosts (host, port) values ("test-host1", 5999); 

insert into trapmux.sinkHosts (host, port) values ("test-host2", 5999); 




2. Run TrapMux using the following command lines: 

ncp_trapmux -domain TEST1 

ncp_trapmux -domain TEST2 

In the above example, when a trap is sent to the machine that is running TrapMux: 

It is forwarded to test-host1, port 5999 and test-host2, port 5999. 

It is sent on the TEST1 and TEST2 domains. 

Controlling TrapMux Using the OQL Service Provider 

You can control TrapMux by logging into the OQL Service Provider and issuing commands to the 

trapMux.command database table. You can log into the OQL Service Provider using the following 

command, replacing DOMAIN_NAME and USER_NAME with your domain and usernames respectively: 

ncp_oql -domain DOMAIN_NAME -service TrapMux -username USER_NAME 

You can now issue commands such as the following to the TrapMux daemon. 


Start Capturing Traps 

The following insert instructs trapMux to start capturing traps: 

|phoenix:1.> insert into trapMux.command 

|phoenix:2.> (command) values( "capture_start" ); 


Stop Capturing Traps 

The following insert instructs trapMux to stop capturing traps: 


|phoenix:2.> (command) values( "capture_stop" ); 


Print Traps to a File 


Configuring TrapMux 

In the following example, FILENAME specifies the file to which the output is written, although if it is not 

specified, NCHOME/etc/precision/trapmux.out is used. 


|phoenix:2.> (command, fileName) values( "print", FILENAME ); 


The trapMux Database Schema 

Table 120 describes the trapMux database. 

Table 120: Synopsis of the trapMux database 

Database name trapMux 

Defined in NCHOME/etc/precision/TrapMuxSchema.cfg 

Fully qualified database table names trapmux.config 

trapmux.command 

trapmux.sinkDomains 

trapmux.sinkHosts 

419


420 


The config table, described in Table 121, contains the main configuration data for the TrapMux 

daemon. 

Table 121: trapMux.config Database Table Schema 


port Integer The port on which to listen for traps. 

The command Table 

The command table, described in Table 122, is an active table used to control the TrapMux daemon with 

a series of commands. The commands are described in Table 123. 

Table 122: trapMux.command Database Table Schema 


command NOT NULL Text The command to issue to the TrapMux daemon. 

fileName Text The file on which to perform the command (where 

applicable). 

The commands that can be issued to TrapMux are described in Table 123. 

Table 123: Commands Used to Control the TrapMux Daemon (1 of 2) 

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 TrapMux daemon 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). 

play Parse the human readable trap file and ‘play’ the traps with a small delay between traps. The 

default filename is NCHOME/etc/precision/trapmux.txt. 

play timed Parse the human readable trap file and ‘play’ the traps in the order of the time they were 

received, with the same delays between traps. The default filename is 

NCHOME/etc/precision/trapmux.txt. 

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). 


Table 123: Commands Used to Control the TrapMux Daemon (2 of 2) 

Command Function and Default Filename 

The sinkDomains Table 


Configuring TrapMux 

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. 

The sinkDomains table, described in Table 124, contains details of the domains to which traps are to be 

forwarded. 

Table 124: trapMux.sinkDomains Database Table Schema 


domain NOT NULL Text The domain name to which to forward traps. 

The sinkHosts Table 

The sinkHosts table, described in Table 125, contains details of the hosts to which traps are to be 

forwarded and their port numbers. 

Table 125: trapMux.sinkHosts Database Table Schema 


host NOT NULL Text The host name or IP address to which to forward traps. 

port NOT NULL Integer The corresponding port number. 

421


16.4 Replaying Traps 

422 

The TrapMux daemon can replay traps using a binary file or a human readable file, however, TrapMux can 

only generate binary files. If you have created a text readable file for traps, you can use the TrapMux daemon 

to recreate the trap events in the order specified in this file. 

Replay the File 

The following example insert instructs trapMux to replay traps from a file. 


|phoenix:2.> (command, fileName) values( "replay", "trapmux.out" ); 



A. Discovery_databases.fm August 16, 2006 

Appendix A: The Discovery Databases 

This chapter describes the databases used by DISCO, the component responsible for discovering network 

device existence and connectivity. 


Types of Databases on page 424 

Failover Recovery on page 426 

Configuration Database on page 431 

Discovery Scope Database on page 442 

Process Management Databases on page 448 

Subprocess Databases on page 454 

Tracking Discovery Databases on page 460 

Topology Databases on page 470 

Rediscovery Database on page 475 

Additional Databases on page 476 



A.1 Types of Databases 

424 

DISCO stores its configuration, management and operational information in various specialized databases, 

which are introduced below. You can interrogate these databases by logging into the service Disco using 

the OQL Service Provider. The OQL Service Provider is described in full in Chapter 5: Querying 

Netcool/Precision IP Databases on page 165. 

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

This section describes the databases of DISCO in functional groups. 

DISCO Configuration Databases 

You can use the disco database to configure the general options for the discovery process, and to track the 

discovery process. 

Discovery Scope Databases 

The scope database is responsible for limiting the extent or reach of a discovery. The range of IP addresses 

and devices that can potentially be considered by the discovery process is unlimited, so unless the scope of 

the discovery is restricted, DISCO would eventually attempt to discover the Internet. 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. 

Process Management Databases 

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 DISCO from the NCHOME/precision/disco/agents and 

NCHOME/precision/disco/stitchers directories. 



page 10. 

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. 


DISCO Subprocess Databases 


Types of Databases 

The finders, Details and agent databases are used actively during the discovery by the DISCO 

subprocesses to store information retrieved from the network. 

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 as 

appropriate based on a template that is defined in the DiscoSchema.cfg configuration file. 

Databases for Tracking the Discovery 

The workingEntities, instrumentation and translations databases record the known 

network entities and technologies, and can be used to track the progress of the discovery. 

The instrumentation database is a record of the different technologies that have been discovered in 

the network; for example, Virtual Local Area Network (VLAN) IDs and subnets. 

Topology Databases 

The fullTopology database is the first of the two topology databases. 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. 

The second topology database is the scratchTopology database, which holds the containment model 

deduced from the fullTopology database (and created by stitchers). This is the version of the topology 

that is sent to the MODEL component. 

Rediscovery Database 

The rediscoveryStore database holds information from previous discovery cycles that can be used 

for comparison purposes during a full or partial rediscovery. 

Additional Databases 

Further databases are also created by the stitchers when needed; for example, various topologies such as layer 

2, layer 3 and ATM have their own databases defined within the stitchers. 

425


A.2 Failover Recovery 

426 

This section describes the failover database. For information on starting and configuring failover, 

together with a full set of failover architecture diagrams, see the Netcool/Precision IP Installation and 


If the m_UseFailover 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 DISCO fails. A discovery running in failover 

mode is slower than a standard discovery, because failover recovery involves storing data on the disk 

throughout the discovery process. 

DISCO failover recovery is not to be confused with agent and finder failover recovery, which are configured 

directly from the disco.config database. If selected, agent and finder failover recovery operate 

regardless of whether DISCO failover recovery is implemented. 

Ignored Cached Data 

If DISCO is restarted in failover recovery mode, any cached data for the following tables are ignored: 

disco.config 

disco.managedProcesses 

disco.agents 

the entire scope database 

failover.config 

failover.doNotCache 

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 

Table A1 describes the failover database. 

Table A1: Synopsis of the failover Database (1 of 2) 

Database failover 


Table A1: Synopsis of the failover Database (2 of 2) 

Defined in NCHOME/etc/precision/DiscoSchema.cfg 

Fully qualified database table names failover.config 


The config table is described in Table A2.There must never be more than one insert into the 

failover.config table. 

Table A2: failover.config Database Table Schema 


failover.status 

failover.findRateDetails 

failover.doNotCache 

failover.restartPhaseAction 


m_InitialiseFromCache Externally 

defined 

Boolean data 

type 

Boolean 

Integer 

Failover Recovery 

Flag indicating whether to use the data that already 

exists in the cache: 

(0) Do not use cached data 

(1) Use cached data if any exists 

m_NumberOfRetries Integer 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 Default = 10 Integer How often the findRateDetails table is to be 

updated. After the specified number of devices have 

been found the table is updated. 

427


428 

The status Table 

The status table is described in Table A3. This table is active, so you must not configure inserts into it. 

Table A3: failover.status Database Table Schema 


m_NumberOfAttempts NOT NULL 

PRIMARY KEY 

The findRateDetails Table 

The findRateDetails table is described in Table A4. The findRateDetails table gives details 

of devices that have been found so far. This table is active and inserts must not be made in the schema file; 

the table is populated automatically. 

Table A4: failover.findRateDetails Database Table Schema 


m_StartTime NOT NULL 

PRIMARY KEY 

Integer The number of times that the DISCO process has 

attempted to restart with cached data. 

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. 

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. 


The doNotCache Table 


Failover Recovery 

To avoid caching a given table, it can be specified in the doNotCache table. This ensures that unnecessary 

cache files are not created, such as those for temporary tables defined within stitchers. The doNotCache 

table is shown in Table A5. 

Table A5: failover.doNotCache Database Table Schema 


m_DatabaseName NOT NULL Text The name of any database that is not to be cached 

during failover recovery. 

The restartPhaseAction Table 

The following tables must be cached in order to use the 

failover recovery mode, and therefore must not be listed 

in this table: 

disco.status 

failover.status 

The following tables must be cached, and therefore 

must not be listed in this table: 

The agent despatch and returns tables. 

finders.processing 

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. 

The restartPhaseAction table is shown in Table A6. This 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 A6: failover.restartPhaseAction Database Table Schema 


Use * to indicate all the tables of the database. 

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. 

429


Example failover Database Configuration 

430 

The following are example OQL inserts into the failover database tables that are appended to the 

DiscoSchema.cfg to configure DISCO when it is launched. 

Example Configuration of the failover.config Table 

The following OQL insert indicates that: 

Data already in the cache is used. 

DISCO can be restarted up to three times before any cached data is ignored. 

These values are only used if disco.config.m_UseFailover=1. 

insert into failover.config 

( 

m_InitialiseFromCache, 

m_NumberOfRetries 

) 

values 

( 1, 3 ); 

Example Configuration of the failover.doNotCache Table 

The following inserts specify that the following tables are not to be cached: 

The disco.config table. 

All the tables of the instrumentation database. 

insert into failover.doNotCache 

( 

m_DatabaseName, 

m_TableName 

) 

values 

( 

'disco', 'config' 

); 

insert into failover.doNotCache 

( 

m_DatabaseName, m_TableName 

) 

values 

( 

'instrumentation', '*' 

); 


A.3 Configuration Database 

Table A7 describes disco, the DISCO configuration database. 

Table A7: Synopsis of the disco Database 

Database disco 


Fully qualified database table names disco.config 



disco.managedProcesses 

disco.status 

disco.agents 

disco.NATStatus 

Configuration Database 

The config table, described in Table A8, configures the general operation of the discovery process. 

Table A8: disco.config Database Table Schema (1 of 4) 


m_NothngFndPeriod Float The maximum time lapse, in seconds, between 

device discovery necessary to fulfil the find-rate 

depreciation criteria for the completion of the 

device discovery phase. 

m_AvgeFindPeriod Float The average amount of time between the 

discovery of devices needed to fulfil the find rate 

depreciation criteria for the completion of the 

device discovery phase. 

m_PendingPerCent 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). 

m_CycleLimit Integer The number of discovery cycles to complete 

before instigating a full rediscovery (used by the 

FinalPhase stitcher). 

m_RestartAgents Integer A flag that determines whether DISCO attempts 

to restart discovery agents that fail during their 

operation. 

m_RestartFinders Integer Flag to determine whether to restart a failed 

finder. 

431


432 



m_DirScanIntvl Integer The time period between scans for 

modifications to the stitcher and agent files. 

m_UseFailover Externally 

defined 

Boolean data 

type 

Boolean 

Integer 

If changes are found, the stitcher and agent 

definitions are loaded and the appropriate 

changes are made to the stitchers and agents. 

Flag indicating whether or not failover recovery 

is to be implemented. Note that a discovery in 

failover recovery mode is slower than a standard 

discovery. 

(1) Use failover. The tables that are defined in 

the failover database are cached and DISCO can 

be restarted at any point. 

(0) Do not use failover. No tables are cached 

during the discovery and DISCO ignores any 

existing cache files if it is restarted. 

m_MinResidentSize Integer The minimum initial size of DISCO in kilobytes 

(KB). The maximum value you can specify is 500 

MB (512 000 KB). 

m_RebuildLayers Externally 

defined 

Boolean data 

type 

Boolean 

Integer 

Specifying an initial value speeds up the 

discovery by allocating the memory of DISCO in 

one block. 

Flag indicating whether or not to rebuild 

topology layers following partial rediscovery, 

that is, rediscovery of one or more individual 

devices. 

(1) Rebuild the layers. Following partial 

rediscovery, topology layers stitchers are run. 

Partial rediscovery takes longer but results in a 

complete topology. 

(0) Do not rebuild the layers. 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. 




m_ModelVlans Externally 

defined 

Boolean data 

type 

m_RTBasedVPNs Externally 

defined 

Boolean data 

type 


default = 0 

m_UseIfName Externally 

defined 

Boolean data 

type 

default = 0 

Boolean 

Integer 

Boolean 

Integer 

Boolean 

Integer 


Flag indicating whether or not 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. 

Flag indicating which type of MPLS discovery to 

perform. 

(1) Set this value to select route target 

(RT)-based MPLS discovery. In this type of 

discovery, no label data is required, so the 

discovery is faster. The MPLS core view consists 

of all MPLS-enabled devices. 

(0) Set this value to select label switch path 

(LSP)-based MPLS discovery. In this type of 

discovery, label data is discovered as this data is 

required in order to trace LSPs. The MPLS core 

view shows provider edge (PE) routers and 

provider (P) routers retrieved by tracing the 

label switched paths within the VPNs in scope. 

For more information on how to restrict the 

scope of an MPLS discovery to a particular VPN, 

see Defining the Scope of an MPLS/VPN Discovery 

on page 333. 

Flag indicating which naming strategy to use 

when building interfaces. 

(1) This setting indicates that you wish to use 

ifName or ifDescr to name the interfaces 

rather than their ifIndex, card or port 

information. 

(0) This setting indicates that you wish to to use 

the default naming strategy for any device 

interface. This strategy is as follows: 

baseName[[] 

433


434 



m_UseSysName Externally 

defined 

Boolean data 

type 

The managedProcesses Table 

default = 0 

m_CheckFileFinderReturns Externally 

defined 

Boolean data 

type 

default = 0 

Boolean 

Integer 

Boolean 

Integer 

Flag indicating which naming strategy to use 

when naming devices. 

(1) This setting indicates that you wish 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. 

(0) This setting indicates that you do not wish to 

name devices using the value of the SNMP 

sysName variable as the main source of 

naming information. 

Flag indicating whether to use the Ping finder to 

check the devices specified in the flat file 

supplied to the File finder. 

(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. 

(0) This setting indicates that you do not wish to 

perform any checking of the devices specified in 

the flat file supplied to the File finder. 

The managedProcesses table, described in Table A9, is a repository for all the subprocesses to be 

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 A9: disco.managedProcesses Database Table Schema (1 of 2) 


m_Name PRIMARY KEY 

UNIQUE 

NOT NULL 

Text The name of the process to be managed. 

m_Args List of text A list of command line arguments sent to the 

executable. 


Table A9: disco.managedProcesses Database Table Schema (2 of 2) 





m_Host Text The name of the host machine on which to run the 

executable. 

m_LogFile Text The name of the log file to which output is written. 

The status table, described in Table A10, can be used to monitor the overall progress of DISCO during 

the discovery process. The disco.status table is used and updated internally, and you must not make 

inserts into this table. 

Table A10: disco.status Database Table Schema (1 of 2) 


m_DiscoveryMode Integer The present discovery mode: 

(0) Full discovery 

(1) Partial discovery 

m_Phase Integer The current phase within the present discovery cycle. 

During the data collection stage, the phases are as 

follows: 

(0) The discovery has not yet started. 

(1) The main discovery phase in which device data is 

retrieved. Most discovery agents complete in this 

phase. 

(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: 

(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 35. 

435


436 

Table A10: disco.status Database Table Schema (2 of 2) 


m_BlackoutState Externally 

defined 

Boolean data 

type 

Boolean 

Integer 

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: 

(1) True (not accepting new devices) 

(0) False (accepting new devices) 

m_CycleCount Integer Current rediscovery cycle, that is, the current number 

of cycles DISCO has been through without actually 

building a topology. 

m_ProcessingNeeded Externally 

defined 

Boolean data 

type 

m_FullDiscovery Externally 

defined 

Boolean data 

type 

Boolean 

Integer 

Boolean 

Integer 

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). 

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: 

(0) The topology does not need reprocessing 

(1) The topology needs reprocessing 

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. 


The agents Table 



The agents table, described in Table A11, is used to specify the discovery agents that 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 (sets m_Valid=1). If m_Valid=0 

the agent is not run. 

Table A11: disco.agents Database Table Schema (1 of 2) 


m_AgentName PRIMARY KEY 

UNIQUE 

NOT NULL 

Text The unique name of the discovery agent. 

m_Valid Integer A flag determining whether or not the discovery agent is to 

be used: 

(1) Run the discovery agent 

(0) Do not run the discovery agent 

m_AgentClass Integer The category to which the current discovery agent 

belongs: 

(0) Routing agent 

(1) Switch agent 

(2) Hub agent 

(3) ILMI agent 

(4) FDDI agent 

(5) PNNI agent 

(6) Frame Relay agent 

(7) CDP agent 

(8) NAT agent 

m_IsIndirect Integer A flag indicating the type of connectivity information 

returned by the discovery agent: 

(0) Direct connectivity; for example, Routing agents 

(1) Indirect connectivity information; for example, Switch 

agents 

437


438 

Table A11: disco.agents Database Table Schema (2 of 2) 


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 if there is a conflict when 

merging device information to produce the 

workingEntities.finalEntity database table. 

m_HostName Text The name of the host machine on which to run the agent. 

m_DebugLevel Integer The level of debugging for the agent. 

m_LogFile Text The text file to which debugging output is written. 

m_NumThreads Integer The number of threads this agent runs. If not specified the 

default number is 10; the maximum allowed is 900. 

m_IsPerl Integer Set to 1 if this agent is a Perl agent. Set to 0 if this agent is 

not a Perl agent. If not present the agent is assumed not to 

be a Perl agent. 

The disco.agents table also indicates agent precedence, which may be used when merging device 

information to produce the workingEntities.finalEntity table. Precedence determines which 

records are used if duplicate or conflicting records are reported by different discovery agents. The following 

precedence applies: 

The Details agent has the lowest precedence as it is only designed to retrieve basic device information. 

Routing agents have the next highest precedence. Their connectivity information is only at the IP 

layer, however, so it is not as accurate as that returned by the switching agents. 

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. 


The NATStatus Table 



The NATStatus table, described in Table A12, is used to configure the discovery system to use NAT. For 

more information on discovering NAT environments, see Chapter 12: Managing NAT Environments on 

page 341. 

Table A12: disco.NATStatus Database Table Schema 


m_UsingNAT UNIQUE 

NOT NULL 

m_NATStatus UNIQUE 

NOT NULL 

Example Configuration of the disco.config Table 

The following OQL insert configures the following parameters: 

Boolean Integer This must be set to indicate whether the discovery uses 

multiple address spaces. Set this value to: 

1 if the discovery uses multiple address spaces. 

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. 

The average amount of time between device discovery is 250 milliseconds. 

0 if the discovery does not use multiple address spaces. 

Integer This column is populated automatically by the 

discovery process, and can be used to track the process 

of a NAT discovery. If making inserts into this table, this 

column must be set to 0. Possible values are: 

(0) Uninitialized 

(1) Seeded discovery with gateways 

(2) Awaiting gateway returns 

(3) Processing NAT translations 

(4) NAT translations complete 

The maximum allowable ratio of pending to processing devices is 20 percent. If this threshold is 

breached, a full discovery is instigated. 

The cycle limit is 5, that is, 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. 

The agent restart flag is 1, that is, DISCO is mandated to restart any discovery agent that fails in its 

operation. 

The finder restart flag is 1, that is, DISCO is mandated to restart any finder that fails in its operation. 

439


440 

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. 

This discovery is not using failover recovery. 


( 

m_NothngFindPeriod, 

m_AvgeFindPeriod, 

m_PendingPerCent, 

m_CycleLimit, 

m_RestartAgents, 

m_RestartFinders, 

m_DirScanIntvl 

m_UseFailover 

) 

values 

( 

300, 

0.25, 

20, 

5, 

1, 

1, 

0, 

0 

); 

Example Configuration of the disco.managedProcesses Table 

The following OQL insert configures the following subprocesses to be launched and managed, provided 

CTRL is running: 

The File finder 

The Ping finder 

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" 

Example Configuration of the disco.agents Table 

The following OQL inserts configure the following parameters: 



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. 

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) 


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) 



( 


) 

values 

( 

'ArpCache', 1, 0, 0, 2 

); 


( 


) 

values 

( 

'AtmForumPnni', 0, 5, 0, 5 

); 


( 

) 

values 

( 

); 


'BayEthernetHub', 0, 2, 1, 3 

441


A.4 Discovery Scope Database 

442 

The scope database is responsible for defining the devices and IP addresses to be considered during the 

discovery. You can limit the range of the discovery process to specific subnets and prevent devices from being 

discovered or instantiated. 

For example, you can specify that sensitive devices not be discovered and consequently not 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 the act of polling itself might cause the device to overload. 

The scope Database Schema 

Table A13 describes the scope database. 

Table A13: Synopsis of the scope Database 

Database scope 


Fully qualified database table names scope.zones 

The zones Table 

NCHOME/etc/precision/DiscoScope.cfg 

scope.detectionFilter 

scope.instantiateFilter 

The zones table, described in Table A14, allows you to define areas of the network to either be included 

or excluded from the discovery process. A zone is typically defined as a list of varbinds. Varbinds are name 

= value pairs. 



Discovery Scope Database 

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 A14: scope.zones Database Table Schema 


m_Protocol PRIMARY KEY 

NOT NULL 

m_Action NOT NULL 


netProtocol data type 


filtAction data type 

Integer An integer representation of the network 

protocol used by the presently defined zone. 

Currently only IP is supported: 

(0) Undefined 


Integer Action to perform for current zone: 

(0) Undefined 

(1) Include 

(2) Exclude 

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. 

443


444 

The detectionFilter Table 

The detectionFilter table is described in Table A15. If a filter is specified in the 

detectionFilter table, only devices matching it are discovered. Since 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. 

Table A15: scope.detectionFilter Database Table Schema 



UNIQUE 

NOT NULL 



Integer An integer representation of network protocol used by 

the presently defined zone. Currently only IP is 

supported: 

(0) Undefined 

m_Filter 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, 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. 



The instantiateFilter Table 



The instantiateFilter table is described in Table A16. If a filter is specified in the 

instantiateFilter table, only devices that pass the criteria are instantiated, that is, sent to MODEL. 

If no filter is specified, all discovered devices are instantiated. Since 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. 

Table A16: scope.instantiateFilter Database Table Schema 



UNIQUE 

NOT NULL 

Example scope Database Configuration 

The example OQL inserts into the scope database tables in this section would be appended to the 

DiscoScope.cfg configuration file in order to configure DISCO when it is launched. 

Tip: In the detectionFilter and the instantiateFilter tables of the scope database, the 

m_Protocol column is UNIQUE. Therefore, there must be no more than one insert into either table per 

protocol. 

Configuration of the scope.zones Table 

The following example creates two inclusion zones for the current discovery. Both zones are defined using 

a single insert. 


( 

m_Protocol, 

m_Action, 

m_Zones 

) 

values 

( 



Integer An integer representation of the network protocol used 

by the presently-defined zone. Currently only IP is 

supported: 

(0) Undefined 

m_Filter Text A textual representation of an attribute filter against the 

columns of the 

scratchTopology.entityByName table; for 

example, m_ObjectId or m_Addresses. 


445


446 

); 

1, 

1, 

[ 

] 

{ 

}, 

{ 

} 

m_Subnet="172.16.1.0" 

m_NetMask=24 

m_Subnet="172.16.2.*" 

The previous OQL insert specifies the following: 

The network uses the Internet Protocol (m_Protocol=1). 

Any devices that fall into the present zone are to be included in the discovery (m_Action=1). 

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. 

Preventing the Detection of Devices 

The following example insert defines a detection filter. Since there must only be one insert into the 

scope.detectionFilter table, multiple conditions for the Internet Protocol must be defined using 

a single insert, as shown here. The conditions of the filter can be combined using the OQL keywords AND 

and OR. 


( 

m_Protocol, m_Filter 

) 

values 

( 

1, 

"( 

( m_UniqueAddress '10.10.63.234' ) 

AND 


)" 

); 




The above example filter ensures that only the following are further interrogated by the discovery: 

Devices that do not have the IP address 10.10.63.234. 

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 in order to 

escape the . character, which would otherwise be treated as a wildcard. 

Restricting Instantiation Based on Object ID 

The following example insert defines an instantiation filter. This example prevents the instantiation 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 instantiated. 


( 

m_Protocol, 

m_Filter 

) 

values 

( 

1, // The backslash is used here to escape the . 

"( // which would otherwise be treated 

// as a wildcard. 


)" 

); 

More Information 

For further information about configuring the scope of the discovery, as well as additional complex example 

inserts, see Chapter 7: Scoping a Discovery on page 207. 

447


A.5 Process Management Databases 

448 

On startup, DISCO populates the agent and stitcher databases with information extracted from the 

discovery agent and discovery stitcher files. Throughout its operation, 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. 

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. 

The agents Database Schema 

Table A17 describes the agents database. 

Table A17: Synopsis of the agents Database 

Database name agents 


Fully qualified database table names agents.definitions 

agents.victims 

agents.status 


The definitions Table 



The definitions table, described in Table A18, contains scheduling information for every discovery 

agent in Netcool/Precision IP, extracted from the information in the discovery agent file. 

Table A18: agents.definitions Database Table Schema 



UNIQUE 

NOT NULL 

m_Type Externally defined 

agentType data type 

The victims Table 

Text Name of the agent. 

Integer Agent Type: 

(0) Undefined 

(1) Precompiled 

(2) Text defined 

(3) Combination 

m_Text NOT NULL Text Textual description of agent rules. 

m_ExecuteOn Text The host on which to execute the agent. 

m_Phase Default = 1 Integer The discovery phase by the end of which the agent is 

expected to complete. 

m_UpdTime Long integer The time of the last modification, which determines 

whether the agent has changed since its definition 

was stored. 

The victims table, described in Table A19, contains an extraction of the criteria that determine which 

devices get sent to the agent. 

Table A19: agents.victims Database Table Schema 



UNIQUE 

NOT NULL 


m_Filter Text The filter condition that determines which devices are 

sent to the agent. 

449


450 


The status table, described in Table A20, contains information about the present status of the agent. 

Table A20: agents.status Database Table Schema 



UNIQUE 

NOT NULL 

m_State Externally defined 

agentState data type. 

Default = 0 

The stitchers Database Schema 

Table A21 describes the stitchers database. 


Integer The current state of the agent: 

(0) Undefined 

(1) Not running 

(2) Start up 

(3) Running 

(4) Finished 

(5) Died 

m_NumConnects Default = 0 Integer The number of times that DISCO has connected to 

the agent. 

Table A21: Synopsis of the stitchers Database 

Database name stitchers 


Fully qualified database table names stitchers.definitions 

stitchers.triggers 

stitchers.status 

stitchers.actions 


The definitions Table 



The definitions table, described in Table A22, contains the scheduling information for every 

discovery stitcher. 

Table A22: stitchers.definitions Database Table Schema 



UNIQUE 

NOT NULL 


stitcherType data type 

The triggers Table 

Text Name of the stitcher. 

Integer Stitcher Type: 

(0) Undefined 

(1) Precompiled 

(2) Text defined 

m_Text Text Textual description of stitcher rules. 

m_Phase Default = 0 Integer The discovery phase by the end of which the 

stitcher is expected to complete. 

m_UpdTime Long integer The time of the last modification to the stitcher. 

The triggers table, described in Table A23, contains an extraction of the criteria that determine the 

trigger for the stitcher. 

Table A23: stitchers.triggers Database Table Schema (1 of 2) 



UNIQUE 

NOT NULL 


451


452 

Table A23: stitchers.triggers Database Table Schema (2 of 2) 


m_Type Integer The type of stitcher trigger: 

m_Trigger Externally defined 

ruleTrigger data type 


The status table, described in Table A24, contains the information about the present status of the 

stitcher. 

Table A24: stitchers.status Database Table Schema 

The actions Table 

(0) Undefined 

(1) On the completion of some other activity; for 

example, another stitcher or a discovery phase 

(2) On a table insert 

(3) On demand 

(4) On a timer 

Object Description of the stitcher trigger. 



UNIQUE 

NOT NULL 


stchrState data type 

Default = 0 


Integer The current state of the stitcher: 

(0) Undefined 

(1) Start up 

(2) Running 

(3) Finished 

(4) Not maintained (the stitcher is not having its state 

maintained) 

The actions table is described in Table A25. If a stitcher is inserted into this table, DISCO runs the 

stitcher. Once the stitcher has completed, its entry is deleted from the 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 A25: stitchers.actions Database Table Schema 



NOT NULL 


453


A.6 Subprocess Databases 

454 

This section focuses on the databases used by the discovery subprocesses. These databases are defined within 

the DISCO configuration file, DiscoSchema.cfg, and include: 

The finders database, used by the finders to store information about device existence. 

The Details database, used by the Details agent to store basic device information. 

The discovery agent databases, which are created using a template. 

The finders Database Schema 

Table A26 describes of the finders database. 

Table A26: Synopsis of the finders Database 

Database finders 


Fully qualified database table names finders.despatch 

finders.returns 

finders.pending 

finders.processing 

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, 

as described in An Overview of the Discovery Process on page 25. 


The despatch Table 


Subprocess Databases 

The despatch table contains a record of all the requests sent to the finders and the current status of the 

requests. 

Table A27: finders.despatch Database Table Schema 


m_Finder PRIMARY KEY 

The returns Table 

NOT NULL 

m_FindRequest PRIMARY KEY 

UNIQUE 

NOT NULL 

Text The name of the finder responsible for the request. 

Text The OQL request sent to the finder named above. 

m_Request Status Integer The current status of the request sent to the finder. 

When a finder finds a device it returns the information to the 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, 

described in The Blackout State on page 35, the finders return the information to the pending table. 

The returns table, described in Table A28, 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 A28: finders.returns Database Table Schema 


m_UniqueAddress PRIMARY KEY 

UNIQUE 

NOT NULL 

Text The IP address of the discovered network entity. 

m_Name Text The unique name of the network entity. 

m_Creator Text The finder that created this record. 

m_Protocol Integer The protocol of the discovered device: 



455


456 

The pending Table 

The finders operate throughout the discovery process, so the pending table exists to accept device 

information when the returns table has been locked out by DISCO. The returns table has to be 

locked during data processing because the fact that the data collection stage has completed does not 

necessarily mean that all the devices on the network have been discovered. 

Network entities that have been sent to the pending table, described in Table A29, are processed after the 

current discovery cycle has been completed. 

Table A29: finders.pending Database Table Schema 



UNIQUE 

NOT NULL 

The processing Table 



m_Creator Text The finder that created this record in the 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. 



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 


Table A30: finders.processing Database Table Schema (1 of 2) 



UNIQUE 

NOT NULL 




Table A30: finders.processing Database Table Schema (2 of 2) 


The rediscovery Table 



m_Creator Text The finder that created this record in the 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. 

The Details Database Schema 

Table A32 describes the details database. The Details agent is responsible for retrieving 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. 





translations.NATAddressSpaceIds table. If 

the discovery is not using NAT, or if the device is in the 

public domain, this value is NULL. 

Table A31: finders.rediscovery Database Table Schema 


m_Address PRIMARY KEY 

NOT NULL 

Text The address to ping. 

m_RequestType Int The type of address: 

(1) Individual 

(2) Subnet 

m_NetMask Text The net mask if the Address refers to a subnet. 

Table A32: Synopsis of the Details Database (1 of 2) 

Database Details 

457


458 

Table A32: Synopsis of the Details Database (2 of 2) 


Fully qualified database table names Details.despatch 

A stitcher takes the information from the Details.returns table and sends it to the Associated 

Address agent and ultimately the appropriate discovery agent. 

The 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 A33: Details.despatch Database Table Schema 

The returns Table 

Details.returns 



NOT NULL 

Text Unique IP address of the network entity. 

m_Name Text Unique name of an entity on the network. 


The returns table is an active table that 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. 



m_AddressSpace Text The name of the NAT address space to which the 

device belongs. This value is set in the 


the discovery is not using NAT, or if the device is in 

the public domain, this value is NULL. 

Table A34: Details.returns Database Table Schema (1 of 2) 



m_UniqueAddress NOT NULL Text Layer 3 address. 


Table A34: Details.returns Database Table Schema (2 of 2) 







m_ObjectId Text Textual representation of the device class (an ASN.1 

address). 

m_Description Text Value of sysDescr MIB variable of the entity. 

m_HaveAccess Externally defined 


Integer Flag indicating whether there is SNMP access to the 

device: 


(0) No Access 

m_UpdAgent Text The agent that updated this device. 

m_LastRecord Externally defined 


Boolean 

Integer 

A flag indicating whether this is the last record for 

this entity (that is, whether the entity has been 

completely processed): 

(1) True 

(0) False 








Object Any extra information. 

459


A.7 Tracking Discovery Databases 

460 

During the course of the discovery process, DISCO keeps a record of every element discovered in the 

network regardless of 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. For more information on these 

databases, see the following sections: 

The translations Database on page 460. 

The instrumentation Database Schema on page 463. 

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 only populated 

at the end of the discovery process. This database is described in The workingEntities database on page 467. 

The translations Database 

Table A35 describes the translations database. 

Table A35: Synopsis of the translations database 

Database name translations 


Fully qualified database table name translations.ipToBaseName 

translations.vlans 

translations.NAT 

translations.NATtemp 



The ipToBaseName Table 


Tracking Discovery Databases 

The translations.ipToBaseName table is a registry of discovered devices and the IP addresses 

associated with those devices. Where 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 A36: translations.ipToBaseName Database Table Schema 


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. 



translations.NATAddressSpaceIds table. If the 

discovery is not using NAT, or if the device is in the public 


The vlans Table 

The translations.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 it is part of. 

Table A37: translations.vlans Database Table Schema 


m_Name NOT NULL 

PRIMARY KEY 

m_VlanID NOT NULL 

PRIMARY KEY 

Text The name of the device associated with this entry. 

Text The VLAN identifier on the device. 

m_Subnet Text The subnet the VLAN appears to be associated with. 

m_NetMask Text The subnet mask. 






461


462 

The NAT Table 

The translations.NAT table is used to hold static NAT mappings. The mapped devices are 

discovered even if they are outside the scope of the discovery. For example inserts into this table, see Enabling 

NAT Translation on page 346. 

Table A38: translations.NAT Database Table Schema 


m_OutsideGlobalAddr PRIMARY KEY 

The NATtemp Table 

NOT NULL 

Text The public address. 

m_InsideLocalAddr NOT NULL 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.NATAddressSpaceId 

s table. If the discovery is not using NAT, or if 

the device is in the public domain, this value 

is NULL. 

The translations.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 A39: translations.NATtemp Database Table Schema 


m_OutsideAddr PRIMARY KEY 

NOT NULL 

Text The public address of the device. 

m_InsideAddr NOT NULL Text The private address of the device. 




If the discovery is not using NAT, or if the device is in 



The NATAddressSpaceIds Table 



The translations.NATAddressSpaceIds table is used to identify the IP addresses of NAT 

gateways and specify an address space identifier for each one. For example insert into this table, see Defining 

Address Spaces for Each Domain on page 346. 

Table A40: translations.NATAddressSpaceIds Database Table Schema 


m_NATGatewayIP PRIMARY KEY 

NOT NULL 

The instrumentation Database Schema 

Table A41 describes the instrumentation database. 

Text The IP address of the gateway. 

m_AddressSpaceId 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. 

Table A41: Synopsis of the instrumentation Database 

Database name instrumentation 


Fully qualified database table names instrumentation.ipAddresses 

instrumentation.name 

instrumentation.subNet 

instrumentation.vlan 

instrumentation.frameRelay 

instrumentation.ciscoFrameRelay 

instrumentation.hsrp 

instrumentation.pnniPeerGroup 

instrumentation.fddi 

The instrumentation database provides a list of discovered devices grouped by technology. You can 

therefore perform OQL queries to retrieve the names of all discovered subnets, VLANs, Frame Relay 

devices, and so on. 

463


464 

The ipAddresses Table 

The ipAddresses table contains a record of the unique IP addresses discovered in the network. 

Table A42: instrumentation.ipAddresses Database Table Schema 



The name Table 

The name table contains a record of the unique name of every discovered device. 

The subNet Table 

UNIQUE 

NOT NULL 

Table A43: instrumentation.name Database Table Schema 



UNIQUE 

NOT NULL 

Text The IP address of a discovered network entity. 

The subNet table contains a record of every discovered subnet address and mask. 

Table A44: instrumentation.subNet Database Table Schema 

Text The name of a discovered network entity. 


m_SubNet PRIMARY KEY 

UNIQUE 

NOT NULL 

m_NetMask UNIQUE 

NOT NULL 

Text The subnet address of a discovered subnet. 

Text The subnet mask of a discovered subnet. 


The vlan Table 

The vlan table contains a record of every discovered VLAN. 

Table A45: instrumentation.vlan Database Table Schema 


m_Vlan UNIQUE Integer The ID of the discovered VLAN. 

The frameRelay Table 

The frameRelay table contains a record of every discovered Frame Relay device. 

Table A46: instrumentation.frameRelay Database Table Schema 


m_IfDlci PRIMARY KEY 

UNIQUE 

NOT NULL 

m_IfIndex PRIMARY KEY 

NOT NULL 

The ciscoFrameRelay Table 



Integer The Frame Relay device Data Link Connection 

Identifier. 

Integer The unique value for each device interface. 

The ciscoFrameRelay table contains a record of every discovered Cisco Frame Relay device. 

Table A47: instrumentation.ciscoFrameRelay Database Table Schema 


m_UniqueKey UNIQUE 

NOT NULL 

m_FRIfIndex PRIMARY KEY 

NOT NULL 

m_FRDlci PRIMARY KEY 

UNIQUE 

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. 

465


466 

The hsrp Table 

The hsrp table contains a record of every discovered Hot Standby Router Protocol (HSRP) device. 

Table A48: instrumentation.hsrp Database Table Schema 


m_GroupAddress PRIMARY KEY 

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

The fddi Table 

NOT NULL 

UNIQUE 

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. 

Table A49: instrumentation.pnniPeerGroup Database Table Schema 


m_PeerGroupId PRIMARY KEY 

NOT NULL 

UNIQUE 

The fddi table contains the Fibre Distributed Data Interface (FDDI) nodes that have been discovered. 

Table A50: instrumentation.fddi Database Table Schema 

Text The lowest level PNNI peer group identifier. 



NOT NULL 

m_StationManagmentTask PRIMARY KEY 

NOT NULL 

Text The unique address of the node. 

Integer The station management task for that node. 


The workingEntities database 

Table A33 describes the workingEntities database. 

Table A51: Synopsis of the workingEntities Database 

Database name workingEntities 


Fully qualified database table name workingEntities.finalEntity 

The finalEntity Table 


workingEntities.containment 


The workingEntities.finalEntity table is a central repository for information about discovered 

entities. 

Table A52: workingEntities.finalEntity Database Table Schema (1 of 2) 



NOT NULL 

UNIQUE 

Text Unique name of the discovered entity. 

m_Creator NOT NULL Text Name of agent (or finder) that discovered the 

entity. 

m_ObjectId Text Device class (a textual representation of the ASN.1 

address). 

m_Description Text Description of the device, taken from the 

sysDescr MIB variable for the entity. 

m_UniqueAddress Text IP address of the network entity. 

m_IsActive Externally defined 




Boolean Integer Indicates whether the entity is active: 

(2) Indicates that the entity is discovered but is not 

in scope. Entities that are not in scope are not 

monitored by Netcool/Precision IP. 

(1) Entity is active. 

(0) Entity is inactive. 

Boolean Integer Flag indicating whether SNMP access to the device 

is available: 

(1) SNMP access is available 

(0) No SNMP Access 

467


468 

Table A52: workingEntities.finalEntity Database Table Schema (2 of 2) 


m_EntityType Externally defined 

entityType data type 

The containment Table 

The workingEntities.containment table is a central repository for information about 

containment information for discovered entities.It shows the containment relationships between all entities 

in the workingEntities.finalEntity table. 

For example, assume the workingEntities.finalEntity table contains a number of distinct 

entities, including the following: 

A device with IP address 1.2.3.4 

An interface on this device, 1.2.3.4[0[1]] 

The workingEntities.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 

workingEntities.containment table, as follows: 

m_Container=’1.2.3.4’ 

m_Part=’1.2.3.4[0[1]]’ 

m_IsPhysical=1 

m_LinkType=1 

Integer Element type description of the discovered entity: 

(0) Unknown type 

(1) Base entity 

(2) Local neighbor 

(3) Remote neighbor 

m_BaseName Text The name of the Base Entity for this device. 




If the discovery is not using NAT, or if the device is 

in the public domain, this value is NULL. 



m_LocalNbr Externally defined 


Object Extra information requested by the agent. 

Object Information about the local neighbor. 




Note that m_Container and m_Part are each unique names of entities on the network, each with a 

unique m_Name in the workingEntities.finalEntity table. 

Table A53: workingEntities.finalEntity Database Table Schema 


m_Container PRIMARY KEY 

NOT NULL 

m_Part PRIMARY KEY 

NOT NULL 

Text 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. 

Text 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. 

m_IsPhysical Boolean Integer Flag indicating whether the containment is physical 

or logical: 

(1) Physical Containment 

(0) Logical Containment 

m_LinkType Int Value indicating mode of data transfer between 

m_Container and m_Part. The following values 

are possible: 

(0) No data is transmitted. 

(1) Data is transmitted both ways. 

(2) Data travels from m_Container to m_Part. 

(3) Data travels from m_Part to m_Container. 

469


A.8 Topology Databases 

470 

DISCO employs 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. When the full topology has been generated, another stitcher 

generates the containment model and stores the information in containers in the scratchTopology 

database, which is then sent to MODEL. 

The fullTopology Database Schema 

Table A54 describes the fullTopology database schema. 

Table A54: Synopsis of the fullTopology Database 

Database fullTopology 


Fully qualified database table names fullTopology.entityByNeighbor 

The entityByNeighbor Table 

The entityByNeighbor table contains information about connectivity between discovered devices. 

Table A55: fullTopology.entityByNeighbor Database Table Schema 



NOT NULL 

m_NbrName PRIMARY KEY 

NOT NULL 

m_NbrType Externally defined 

connectionType 

data type 

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: 

(2) Main-to-Local 

(3) Local-to-Remote 


The scratchTopology Database Schema 

Table A56 describes the scratchTopology database. 

Table A56: Synopsis of the scratchTopology Database 

Database name scratchTopology 


Fully qualified database table name scratchTopology.entityByName 


The entityByName table contains the deduced network model. 

Table A57: scratchTopology.entityByName Database Table Schema (1 of 2) 



NOT NULL 

UNIQUE 


Text Unique name of the network entity. 


m_Addresses List of text List of OSI model layer 1-7 addresses for the entity. 

m_Description Text Value of sysDescr MIB variable or other suitable 




type 

Integer Element type of the entity: 

(0) Unknown 

(1) Chassis 

(2) Interface 


(4) Vlan object 

(5) Card 

(6) PSU 

(7) Subnet 

(8) Module 

m_ObjectId Text The device class to which the network entity 

belongs. This is a textual representation of the 

ASN.1 address. 

471


472 

Table A57: scratchTopology.entityByName Database Table Schema (2 of 2) 




The impactTopology Database Schema 

Table A58 describes the impactTopology database. 


Boolean Integer Flag indicating the state of the entity: 

(1) Active 

(0) Not Active 

m_Contains List of text List of elements or other containers contained 


m_Upward 

Connections 

List of text List of containers that contain this entity. 

m_RelatedTo List of text List of entities that are connected to the network 

entity. 





Table A58: Synopsis of the impactTopology Database 

Database name impactTopology 

Boolean Integer Flag indicating whether SNMP access to the entity is 

available: 


(0) No Access 

Any additional information. 


Fully qualified database table name impactTopology.entityByName 

The entityByName table is an exact copy of the scratchTopology.entityByName database 

table. 

By default, the stitched topology from the scratchTopology DISCO database is considered the final 

topology and is passed to MODEL. Experienced users might wish to preview and approve the topology 

before it is passed to MODEL. For example, if you have configured a rediscovery with different parameters 

to your initial discovery, you may wish to preview the results before overwriting the current topology held 

in MODEL. 




Instructions on how to do this by copying the topology from the scratchTopology database to the 

impactTopology database are given in the comments in CreateAndSendTopology.stch. 

These instructions, and the impactTopology database, are provided for the convenience of advanced 

users only. Previewing the topology would involve writing your own stitcher and is not supported by 

Micromuse. 

Table A59: impactTopology.entityByName Database Table Schema (1 of 2) 



NOT NULL 

UNIQUE 


m_Addresses List of text List of OSI model layer 1-7 addresses for the entity. 

m_Description Text Value of sysDescr MIB variable or other suitable 


m_Type Externally 

defined 

entityTypes 

data type 

Integer Element type of the entity: 

(0) Unknown 

(1) Chassis 

(2) Interface 


(4) Vlan object 

(5) Card 

(6) PSU 

(7) Subnet 

(8) Module 

m_ObjectId Text The device class to which the network entity belongs. This 

is a textual representation of the ASN.1 address. 

m_State Externally 

defined 

Boolean data 

type 

Boolean 

Integer 

Flag indicating the state of the entity: 

(1) Active 

(0) Not Active 

m_Contains List of text List of elements or other containers contained within the 

current network entity. 

m_UpwardConnections List of text List of containers that contain this entity. 

m_RelatedTo List of text List of entities that are connected to the network entity. 

473


474 

Table A59: impactTopology.entityByName Database Table Schema (2 of 2) 


m_HaveAccess Externally 

defined 

Boolean data 

type 

m_ExtraInfo Externally 

defined vblist 

data type 

Boolean 

Integer 

Object type 

vblist 

Flag indicating whether SNMP access to the entity is 

available: 


(0) No Access 

Any additional information. 


A.9 Rediscovery Database 

The rediscoveryStore database is used for comparison purposes in rediscovery mode. 

Table A60: Synopsis of the rediscoveryStore database 

Database Defined in Fully qualified database table names 

rediscoveryStore NCHOME/etc/precision/ 

DiscoSchema.cfg 

The dataLibrary Table 


Rediscovery Database 

The dataLibrary table is used as a reference point during rediscovery mode to compare the previous 

and present states. 

Table A61: rediscoveryStore.dataLibrary Database Table Schema 


The rediscoveredEntities Table 

rediscoveryStore.dataLibrary 

rediscoveryStore.rediscoveredEntities 


m_UniqueAddress Text The IP address of a discovered network entity. 

m_CompareDb NOT NULL Text The entity that is used to compare this network entity. 

The rediscoveredEntites table stores entities found during a rediscovery. 

Table A62: rediscoveryStore.rediscoveredEntities Database Table Schema 

Column name Constraints Datatype Description 


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. 

475


A.10 Additional Databases 

476 

The databases of each discovery agent are based on a template called the agentTemplate database. 

The agentTemplate Database Schema 

Table A63 describes the agentTemplate database. 

Table A63: Synopsis of the agentTemplate database 

Database name agentTemplate 


Fully qualified database table names agentTemplate.despatch 

The Discovery Agent Despatch Table 

agentTemplate.returns 

When a device has been interrogated by the Details agent it is passed to the Associated Address agent to 

check that the device has not already been discovered. Provided the device has not already 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 A64. 

As soon as the device details are placed in the despatch table, the agent attempts to retrieve connectivity 

information pertaining to the device. 

Table A64: agentTemplate.despatch Database Table Template (1 of 2) 



NOT NULL 


m_UniqueAddress NOT NULL Text Unique IP address of the network entity. 




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. 


Table A64: agentTemplate.despatch Database Table Template (2 of 2) 


The Discovery Agent Returns Table 


Additional Databases 





device is in the public domain, this value is NULL. 



Boolean 

Integer 

Flag indicating whether there is SNMP access to 

the device: 


(0) No Access 

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 A65. 

Table A65: agentTemplate.returns Database Table Schema (1 of 2) 


m_Name NOT NULL Text Unique name of an entity on the network. 

m_UniqueAddress NOT NULL Text Layer 3 address of this entity. 




m_ObjectId Text Textual representation of the device class (an 

ASN.1 address). 





m_LocalNbr Externally defined 

neighbor data type 

m_RemoteNbr Externally defined 

nbrsNeighbor data 

type 

Boolean Integer Flag indicating whether there is SNMP access to 

the device: 


(0) No Access 

Object Any extra information specified by the user in 

the agent definition file. 

Object Direct neighbors (interfaces). 

Object Remote neighbors connected to interfaces. 

m_UpdAgent Text The agent that updated this device. 

477


478 

Table A65: agentTemplate.returns Database Table Schema (2 of 2) 


m_SnmpAccessIP Text If present, overrides the IP address used for 

SNMP access to devices using the Helper Server. 





device is in the public domain, this value is NULL. 

m_LastRecord Externally defined 


Boolean Integer Is this the last record for this entity: 

(1) True 

(0) False 


B. Object_Query_Language.fm August 16, 2006 

Appendix B: The Object Query Language 

This chapter describes the Object Query Language (OQL), which Netcool/Precision IP uses to manipulate 

and store data in databases. 


Introduction to OQL on page 480 

Creating a Database or Table on page 485 

Inserting Data into a Table on page 490 

Selecting Data from a Table on page 493 

Conditional Tests in OQL on page 495 

Using Select to Perform Subqueries on page 498 

Selecting Data into Another Table on page 501 

Updating a Record in a Table on page 503 

Listing the Databases or Tables on page 505 

Deleting a Record from a Database Table on page 507 

Deleting a Database or Table on page 508 

The Eval Statement on page 509 



B.1 Introduction to OQL 

480 

OQL is a version of the Structured Query Language (SQL) that has been designed for use in 

Netcool/Precision IP. The components create and interact with their databases using OQL. 

You can use OQL to create new databases or insert data into existing databases (to configure the operation 

of Netcool/Precision IP components) by amending the component schema files. You can also issue OQL 

statements using the OQL Service Provider, for example, to create or modify databases, insert data into 

databases and retrieve data. The OQL Service Provider is described in Chapter 5: Querying Netcool/Precision 

IP Databases on page 165. 

Key Differences Between OQL and SQL 

OQL differs from SQL in that: 

OQL supports object referencing within tables. Objects can be nested within objects. 

Not all SQL keywords are supported within OQL. Keywords that are not relevant to 

Netcool/Precision IP have been removed from the syntax. 

OQL can perform mathematical computations within OQL statements. 

General Rules of OQL 

The following rules apply to OQL statements: 

Quotes in OQL 

All complete statements must be terminated by a semi-colon. 

A list of entries in OQL is usually separated by commas but not terminated by a comma. 

Strings of text are enclosed by matching quotation marks. The rules for quotation mark usage are 

described below. 

In OQL the TEXT datatype must be enclosed by matching quotation marks (either single or double quotes). 

The example below is a standard OQL insert into the CTRL services.inTray table, showing values 

of the TEXT data type enclosed in double quotes, an integer value that is not enclosed in any quotation 

marks, and a LIST OF TYPE TEXT that is enclosed in square brackets. The comma separated data within 

the list is enclosed in double quotes. 


( 

serviceName, servicePath, domainName, argList, retryCount 

) 

values 


( 

); 

"ncp_disco", "/opt/netcool/precision/Solaris2/bin", "MYDOMAIN", 

[ "-domain" , "NCOMS" , "-latency" , "60000" ], 5 

Punctuation Used in OQL 

Table B1 shows the punctuation used in the OQL syntax. 

Table B1: Punctuation Used in the OQL Syntax 

Symbol Meaning 

- Subtraction, negative. 

+ Addition, positive. 

* Multiplication or a wild card that matches any characters within its expression. 

( Encloses items in a list, for example, following the insert into statement. 

) Encloses items in a list, for example, following the insert into statement. 

, Separates entries in a list. 

[ ] Encloses items of the list datatype. 

{ } Encloses items of the object datatype. 

. Separates database, table and column names. 

; Terminates OQL statements. 

~ Matches regular expressions. 

-> Retrieves a sub value of an object. 

Comments in OQL 


Introduction to OQL 

Comments in OQL are introduced by -- or //. If a comment requires a carriage return, the characters on 

the next line must also be commented out. 

-- This is a valid OQL comment. 

// This is also a valid OQL comment. 

481


Logical operators of OQL 

482 

Table B2 describes the logical operators you can use in OQL. 

Table B2: Logical Operators of OQL 

Keyword Brief description 

AND Combines search conditions, all of which must be true in order for the condition to be passed. 

OR Combine search conditions, one of which must be true in order for the condition to be passed. 

Precedence and Association of Operators 

The rules for precedence and association of operators determine the grouping of operators with operands, 

and indicate the order in which the operators in an expression are executed. For complex expressions, use 

parentheses to avoid ambiguity. Table B3 describes the operators that are used in the Object Query 

Language. 

Table B3: OQL Operators in Order of Decreasing Precedence 

Operator Description Associativity Precedence 

- Negative sign Non-associative 1 (Highest) 

* Multiplication Left 2 

/ Division Left 2 

OR Logical OR Left 3 

AND Logical AND Left 4 

NOT Logical NOT Left 5 

= Equal to Left 6 

Not equal to Left 6 

< Less than Left 6 

> Greater than Left 6 

= Greater than or equal to Left 6 

+ Addition Left 7 

- Subtraction Left 7 (Lowest) 


Conventions Used in This Chapter 

The following conventions have been used in this chapter to explain the OQL syntax: 

OQL keywords and their required punctuation are shown in bold in examples. 

Parameters are shown in italics. 

[ Optional parameters are shown enclosed by square brackets ]. 

OQL commands are terminated with a semicolon. 

... following a list of parameters indicates that you can continue the list if necessary. 

OQL Service Provider command lines are shown with the example command line prompt 

|phoenix:1.> followed by relevant sample output. 


Introduction to OQL 

The system name within the prompt appears as phoenix within this manual. This is replaced by an 

appropriate value for your system, such as the host name. 

Sample Databases Used in This Appendix 

To illustrate the OQL keywords in use, this appendix uses a sample database, the staff database, which 

contains three tables: managers, employees and contractors. The data in this database (which is 

used throughout the examples in this chapter) is listed in Table B4, Table B5, and Table B6. 

Table B4: Data in the staff.managers Database Table 

EmployeeID Name Department Gender Age 

1 Matt Development M 28 

2 Irene Customer Services F 52 

3 Ernie Sales M 23 

4 Paul Marketing M 26 

5 Jim Support M 27 

Table B5: Data in the staff.employees Database Table 

EmployeeID Name Skills Gender Age 

6 Paul HTML, C++, Java M 26 

7 Carl Perl M 32 

8 Rob UNIX, Perl M 23 

9 Sarah Java, C++ F 24 

10 Lisa UNIX, HTML F 25 

483


484 

Table B6: Data in the staff.contractors Database Table 

EmployeeID Name Gender Age ExtraInfo 

11 James M 22 ContractLength = 6 months; Department = Marketing; 

12 Karen F 25 ContractLength = 5 months; Department = Sales; 

13 Jane F 26 ContractLength = 7 months; Department = Development; 

14 Richard M 23 ContractLength = 1 month; Department = Operations; 

15 Glenn M 28 ContractLength = 2 months; Department = Operations; 


B.2 Creating a Database or Table 

Datatypes 

Databases and tables are created using the create command. 

create database database_name ; 


Creating a Database or Table 

When creating a table, you must define all the columns of the table, specifying a datatype (for example, text 

or integer) and if applicable the column constraints and any default value. 

create table database_name.table_name 

( 

column_name [ constraints ] [ default default ] , 

[ column_name [ constraints ] [ default default ] , ] 

[ additional_columns ] 

[ unique ( column_name ) , ] 

[ counter ( column_name ) , ] 

[ timestamp ( column_name ) , ] 

); 

The entries within the brackets are separated by commas, although the last entry is not terminated by a 

comma. 

All columns must have an associated datatype that indicates the acceptable input for that column. Table B7 

shows the datatypes that are used in OQL: 

Table B7: Datatypes of OQL (1 of 2) 

Datatype Description 

TEXT Holds plain text. 

INT Holds integer values. 

INT TYPE datatype Holds a conversion of the declared datatype to an integer. 

FLOAT Holds decimal values. 

LONG Holds a 32-bit numerical value. 

LONG64 Holds a 64-bit numerical value. 

DATA Holds opaque data, typically of the binary format. 

LIST TYPE datatype Holds a list of particular datatypes. The list is enclosed in square brackets, []. 

OBJECT TYPE datatype Holds objects of particular datatypes. The object is enclosed in curly braces, {}. 

Objects hold a list of varbinds (name/value pairs). 

485


486 

Table B7: Datatypes of OQL (2 of 2) 


TIME Holds information pertaining to time. Although the TIME datatype is acceptable, 

it is evaluated by the OQL parser to LONG. 

IPADDRESS Holds IP addresses. Although the IPADDRESS datatype is acceptable, it is 

evaluated by the OQL parser to LONG. Therefore the IP address is stored as an 

integer value, like that produced by inet_addr(), instead of the more 

common period-separated string format. 

Objects and Varbinds 

An object is a comma separated list of varbinds enclosed by curly braces, where a varbind is a name/value 

pair, for example, ifIndex=20 or ifDescr="utp10/100". You can perform operations on one of 

the varbinds in an object using the -> symbol, as demonstrated in the examples in Selecting Based on Part of 

an Object on page 497 and Updating an Object on page 503. 

External Datatypes 

It is possible to define additional datatypes that map integers to the possible values of a column; these 

datatypes are referred to as external datatypes, since they are defined externally to the present schema. 

In order to use a datatype that has been defined in a previously loaded schema, the current schema must 

contain a statement of the following structure. 

data type datatype is external datatype ; 

Examples of the datatype declaration are shown below. 

data type boolean is external boolean 

data type entityTypes is external entityTypes 

After you have made these declarations you can use the datatypes boolean and entityTypes in the 

current schema, provided that they have also been defined in a previously loaded schema. 


Column Constraints 



Column constraints are restrictions on the data that can be inserted into a given column. Any of the 

constraints shown in Table B8 can be applied to any column. 

If multiple constraints are being specified for a single column, NOT NULL must be specified before 

PRIMARY KEY. 

Default Values 

Unique 

Counter 

Table B8: Column Constraints 

Constraint Description 

NOT NULL Indicates that the column must be assigned a value. 

NULL is not the same as zero or white space. 

PRIMARY KEY Denotes that the column is a primary key for the table. The primary keys can be used to join 

related tables in a multiple table query. 

The combination of data in the PRIMARY KEY columns of a given table must be unique, 

although the data in each individual column does not necessarily have to be unique. For 

example, the primary key might comprise the multiple fields of forename, surname, and age. 

The primary key is internally indexed and so provides faster query times, but slower insert 

and delete times. Unique and indexed fields are also internally indexed. 

List and object fields cannot be indexed, thus they cannot be set as primary keys, unique 

fields, nor as part of an index definition. 

A default value can be applied to a column when it is created with the default keyword. If an explicit value 

is not provided for that column when data is inserted, the specified default value is used. 

The optional unique column constraint ensures that all entries in the specified column are unique. The 

unique column is internally indexed and so provides faster query times, but slower insert and delete times. 

List and object fields cannot be indexed, thus they cannot be set as unique fields, nor as part of an index 

definition. 

The optional counter column constraint delegates the responsibility of counting duplicate records to the 

specified column. If you attempt to insert a duplicate record into the table, the insertion of the duplicate 

entry is suppressed and the value of the specified column is incremented in the record that already exists. 

487


Timestamp 

488 

The optional timestamp column constraint stores the date and time information for the creation of the 

record in the specified column of the database table. The timestamp properties are: 

Format: YYYY-MM-DD HH:MM:SS.nnnnn.... 

Range: 0001-01-01 00:00:00.......to 9999-12-31 23:59:59.999999....... 

Example of Database and Table Creation 

The following examples use the create keyword to create the sample staff database and define the tables. 

These example OQL statements illustrate the use of the column constraints and the default keyword. 

create database staff; // creates the staff database 

The following insert defines the managers table. 

create table staff.managers 

( 

EmployeeID int NOT NULL PRIMARY KEY, 

Name text NOT NULL, 

Department text default "Sales", 

Gender text, 

Age int, 

unique ( EmployeeID ) // indicates that the data in the 

// EmployeeID column must be unique. 

); 

For the managers table: 

The EmployeeID and Name columns cannot be NULL. 

The EmployeeID column is the primary key and must be unique. 

If no value is inserted into the Department column for a given record it takes the value "Sales". 

The following insert creates the staff.employees table. 

create table staff.employees 

( 



Skills list type text, 

Gender text, 

Age int // There is no comma here because this 

// is the last entry. 

); 


For the staff.employees table: 

The EmployeeID and Name columns cannot be NULL. 

The Skills column is a list of text strings. 

The following insert creates the staff.contractors table. 

create table staff.contractors 

( 



Gender text, 

Age int, 

ExtraInfo object type vblist, 

volatile 

); 

For the staff.contractors table: 

The ExtraInfo column contains a list of varbinds. 



489


B.3 Inserting Data into a Table 

490 

The following example shows how to insert data into a table using the insert keyword: 

insert into database_name.table_name 

( 

column 

[ , column ] 

[ , column ] 

[ ... ] 

) 

values 

( 

data 

[ , data ] 

[ , data ] 

[ ... ] 

); 

Each data value is inserted into the corresponding column name, so the number of data values (and the data 

types) must correspond with the number of column names specified. Although it is not good practice, it is 

acceptable to omit the list of column names. If you choose to omit the column names, the first value 

specified after the values keyword is inserted into the first column of the database, the second value into the 

second column, and so on. Additionally, if you omit the column names, the number of values must 

correspond to the number of columns in the database, so you must either insert a value into each database 

column or explicitly specify NULL for columns into which you do not wish to insert a value. 

Example of Inserting Data into a Database 

The population of the sample databases with data is shown in the examples below, which highlight some of 

the different valid forms of the insert statement. The following example specifies all the column names: 

insert into staff.managers 

( 

EmployeeID, Name, Department, Gender, Age 

) 

values 

( 

1, "Matt", "Development", "M", 28 

); 

The following example does not specify column names, but is still a valid insert because a value has been 

specified for each column of the database. 


values 

( 

2, "Janet", "Customer Services", "F", 27 


); 


// no column names are specified, so the values are inserted 

// into the columns in order. 

Inserting Data into a Table 

The following example specifies no value for the Department column, which is populated with the 

default value instead: 


( 

EmployeeID, Name, Gender, Age 

) 

values 

( 

3, "Phil", "M", 25 

// No value for Department has been specified. The column 

// therefore takes the default value "Sales" that was specified 

// when the table was created. 

); 

Example of an Invalid Insert 

Since staff.managers is unique on the EmployeeID column, the following insert would now be 

invalid. The following example would therefore be rejected, because there is already a record with 

EmployeeID=3. 


( 

EmployeeID, Name, Department, Gender, Age 

) 

values 

( 

3, "John", "Marketing", "M", 26 

); 

List and Object Data Types 

The following examples show the use of the list and object datatypes. The following example is an insert into 

the staff.employees table, where the Skills column has been defined as list type text. 

insert into staff.employees 

( 

EmployeeID, Name, Skills, Gender, Age 

) 

values 

( 

6, "Matt", [ "HTML", "C++", "Java" ], "M", 24 

); 

491


492 

The following example is an insert into the staff.contractors table, where the ExtraInfo 

column has been defined as object type vblist: 

insert into staff.contractors 

( 

EmployeeID, Name, Gender, Age, ExtraInfo 

) 

values 

( 

11, "James", "M", 22, { ContractLength=6, Department="Marketing" } 

); 

These inserts are shown for illustrative purposes. The remaining examples in this chapter assume that all the 

data shown in Table B4 on page 483, Table B5 on page 483 and Table B6 on page 484 has been inserted 

into the managers, employees and contractors tables of the staff database. 


B.4 Selecting Data from a Table 

You can query the data in a table using the select keyword. 

select comma_separated_column_list_or_wildcard 

from database_name.table_name 

[ where conditional_test ] ; 


Selecting Data from a Table 

The * symbol can be used as a wildcard in a select statement to return all the columns of the table. 

Alternatively a comma-separated list of columns can be specified. The select statement is shown below in use 

within the OQL Service Provider to query the staff.managers table (the following example output is 

for illustration only and has been abbreviated). 

|phoenix:1.> select * from staff.managers; 


..... 

{ 

EmployeeID=1; 

Name='Matt'; 

Department='Development'; 

Gender='M'; 

Age=28; 

} 

{ 

EmployeeID=2; 

.... 

.... 

} 


The following example shows a select statement that retrieves only specific fields from the 

staff.managers table. 

|phoenix:1.> select Name, Gender from staff.managers; 


..... 

{ 

Name='Matt'; 

Gender='M'; 

} 

{ 

Name='Irene'; 

Gender='F'; 

} 

{ 

Name='Ernie'; 

.... 

.... 

} 


493


494 

The following example uses a where clause to restrict the results. 

|phoenix:1.> select EmployeeID, Name from staff.managers 

|phoenix:2.> where Department = "Marketing"; 


. 

{ 

EmployeeID=4; 

Name='John'; 

} 



B.5 Conditional Tests in OQL 

The tests in Table B9 can be used in OQL, for example, in a select where statement. 

Table B9: Comparison Operators in OQL 

Symbol Description 

= Equal to. 

Not equal to. 

< Less than. 

> Greater than. 

= Greater than or equal to. 

Example Uses of the like Operator 

The following example query would return the complete records of all employees listed in the 

contractors table whose name begins with an upper-case letter J. 

|phoenix:1.> select EmployeeID, Name from staff.contractors 

|phoenix:2.> where Name like "J"; 


.. 

{ 

EmployeeID=11; 

Name='James'; 

} 

{ 

EmployeeID=13; 

Name='Jane'; 

} 



Conditional Tests in OQL 

like Compares for similarity using UNIX-style regular expressions. The like operator is 

more powerful than the traditional SQL implementations that use the more limited 

token matching for comparison. 

in Searches for the presence of a record within a specified table (using a subquery). 

The in operator can also be used to determine whether a specified value is 

contained in a list field. 

is null Tests whether the specified column is null (that is, has not been assigned a value). 

495


496 

The following example query identifies the records in the employees table that contain the lower-case 

letter r in the Name column. 

|phoenix:1.> select Name from staff.employees 

|phoenix:2.> where Name like ".*[r].*"; 


.. 

{ 

Name='Carl'; 

} 

{ 

Name='Sarah'; 

} 


The following example query identifies the records in the employees table for which the Name column 

begins with an upper-case C or upper-case R. 

|phoenix:1.> select Name from staff.employees 

|phoenix:2.> where Name like "^[CR]"; 


.. 

{ 

Name='Carl'; 

} 

{ 

Name='Rob'; 

} 


Example Use of the and Operator 

The following example uses the conjunctive operator and to combine two search conditions. 

|phoenix:1.> select Name, Gender from staff.managers 

|phoenix:2.> where Gender "M" and Gender "Male"; 


. 

{ 

Name='Janet'; 

Gender='F'; 

} 



Example Use of the or Operator 

The following example uses the or operator to combine two search conditions. 

|phoenix:1.> select Name, Age from staff.employees 

|phoenix:2.> where Name="Carl" or Name="Matt"; 


.. 

{ 

Name='Matt'; 

Age=24; 

} 

{ 

Name='Carl'; 

Age=28; 

} 


Selecting Based on Part of an Object 

The following example retrieves records from the staff.contractors table where 

Department="Operations" within the ExtraInfo column. 


|phoenix:2.> where ExtraInfo->Department="Operations"; 


.. 

{ 

Name='Richard'; 

Age=23; 

} 

{ 

Name='Glenn'; 

Age=28; 

} 



Conditional Tests in OQL 

497


B.6 Using Select to Perform Subqueries 

498 

Subqueries are queries embedded within queries using double brackets. 

The example below retrieves the Name and Age columns from any record in the staff.employees 

table whose Name also exists in the Name column of the staff.managers table. 


|phoenix:2.> where Name in 

|phoenix:3.> ( ( select Name from staff.managers ) ); 


.. 

{ 

Name='Matt'; 

Age=24; 

} 

{ 

Name='Rob'; 

Age=23; 

} 


Any valid query can be embedded within the double brackets. 

The following example subquery retrieves the Name and Age columns of the managers table where the 

value of the staff.managers.Age column matches one of the staff.employees.Age columns 

and is greater than 25. 

|phoenix:1.> select Name, Age from staff.managers 

|phoenix:2.> where Age in 

|phoenix:3.> ( 

|phoenix:4.> ( 

|phoenix:5.> select Age from staff.employees 

|phoenix:6.> where Age > 25 

|phoenix:7.> ) 

|phoenix:8.> ); 


. 

{ 

Name='Matt'; 

Age=28; 

} 


The query returns only one record. Although two records from the managers table have ages that match 

the employees table, only one of the matches is also over 25. 


Using Subqueries to Search a List 


Using Select to Perform Subqueries 

The following example uses a subquery to search a list, the Skills column of the staff.employees 

table. The name of the field to be searched is enclosed in parentheses. 

|phoenix:1.> select Name, Skills from staff.employees 

|phoenix:2.> where ( "C++" in (Skills) ); 


.. 

{ 

Name='Matt'; 

Skills=['HTML','C++','Java']; 

} 

{ 

Name='Sarah'; 

Skills=['Java','C++']; 

} 


Selecting Based on Part of a List 

You can use the list operators all, *, and any and a conditional test to select records based on part of a list, 

although these list operators can only be used at the end of an object definition. all and * return records 

where the conditional test is true for all items in a list. A query using the keyword any returns records where 

the conditional test is true for any of the items in the list. 

The following example retrieves all the records that contain "C++" anywhere in the list of Skills. 


|phoenix:2.> where Skills (any) = "C++"; 


.. 

{ 

Name='Matt'; 

Skills=['HTML','C++','Java']; 

} 

{ 

Name='Sarah'; 

Skills=['Java','C++']; 

} 


The following example returns the records that contain only "Perl" in the list of Skills. 


|phoenix:2.> where Skills (*) = "Perl"; 


. 

{ 

499


500 

Name='Carl'; 

Skills=['Perl']; 

} 


The list operators can also be used in table joins, as described on Using any, *, and all to Perform Table Joins 

on page 501. 


B.7 Selecting Data into Another Table 


Selecting Data into Another Table 

The select into statement retrieves data from one table and inserts it into another. The select into 

command does not delete the existing record. 

select column_or_wildcard [ , column ... ] 

into destination_database_name.destination_table_name 

from source_database_name.source_table_name 


The columns selected from the source table are inserted into the destination table in order, regardless of the 

column names and structure of the destination table. Omitting the optional where condition selects all the 

records from the source table. 

If you use a wildcard, all the columns from the source table are selected and inserted in order into the 

destination table. Any null columns in the source table are skipped in both the source and destination tables, 

for example, if the fourth column of the source table is null, the fourth column in the destination table is 

skipped. 

If you explicitly specify a list of columns to select from the source table, they are inserted into the destination 

table in the order in which they are specified (even if the order in which they are specified is not the order 

in which they exist in the source table). 

For example, the following statement would select the values of the Age and Gender columns of the 

staff.managers table and insert the values into the first two columns of the staff.employees 

table. 

select Age, Gender into staff.employees from staff.managers; 

The following example selects EmployeeID and Name from any record in the staff.employees 

table for which Name="Carl" and inserts the values into the first two columns of the 

staff.managers table. 

|phoenix:1.> select EmployeeID, Name 

|phoenix:2.> into staff.managers from staff.employees 

|phoenix:3.> where Name="Carl"; 


Using any, *, and all to Perform Table Joins 

The examples in this section show how the operators can also be used to perform table joins. 

501


502 

Matching Every Entry in Multiple Lists 

The following example only returns records where every entry in db.table1.m_List is equal to every 

entry in db.table2.m_OtherList. For example, if m_List = [ 1, 1, 1 ] and 

m_OtherList = [ 1, 1 ] they match, but if m_List = [ 1, 2, 1] and m_OtherList 

= [1, 1], they do not match. 

|phoenix:1.> select * from db.table1 , db.table2 

|phoenix:2.> where (db.table1.m_List( * ) = db.table2.m_OtherList( * ); 


Matching Any Entry in Multiple Lists 

The following example returns any record where any item in db.table1.m_List matches any item in 

db.table2.m_OtherList. For example, if m_List = [ 1, 2, 3 ] and m_OtherList = 

[ 3, 4 ] they match because 3 is in both lists. However, if m_List = [ 1, 2, 3 ] and 

m_OtherList = [ 4, 5] they do not match. 


|phoenix:2.> where (db.table1.m_List( any ) = db.table2.m_OtherList( any ); 


Matching All the Entries in One List with Any Entry in Another List 

The following example returns any record where all the entries in db.table1.m_List match any of the 

entries in db.table2.m_OtherList. For example, if m_List = [ 1, 2, 3 ] and 

m_OtherList = [ 3, 1, 2, 4 ] they match, because all the entries in m_List match an entry 

in m_OtherList. However, if m_List = [ 1, 2, 3 ] and m_OtherList = [ 3, 2, 4 

] then they do not match because not all the entries in m_List have a match in m_OtherList. 


|phoenix:2.> where (db.table1.m_List( * ) = db.table2.m_OtherList( any ); 


Matching Any of the Entries in One List with All the Entries in the Second List 

The following example returns any record where any of the entries in db.table1.m_List match all of 

the entries in db.table2.m_OtherList. For example, if m_List = [ 1, 2, 3 ] and 

m_OtherList = [ 2, 2 ] they match because one of the entries in m_List matches all the entries 

in m_OtherList. However, if m_List = [ 1, 2, 3 ] and m_OtherList = [ 1, 2, 3 

] they do not match, because there is no entry in m_List that is equal to every entry in m_OtherList. 


|phoenix:2.> where (db.table1.m_List( any ) = db.table2.m_OtherList( * ); 



B.8 Updating a Record in a Table 

Use the update keyword to update an existing record in a table. 

update database_name.table_name 

set column = value 

[ , column = value ... ] 


If the update statement is used without a where condition, all records are updated. 


Updating a Record in a Table 

The following example updates the Age column of the staff.managers table for any records where 

Name="John". 

|phoenix:1.> update staff.managers 

|phoenix:2.> set Age=27 

|phoenix:3.> where Name="John"; 


Updating a List 

The following example updates the Age and Skills columns of the staff.employees table where 

Name="Lisa". The following example updates a column of datatype LIST by updating the entire list. 

|phoenix:1.> update staff.employees 

|phoenix:2.> set Age=26, Skills=["UNIX", "HTML", "C"] 

|phoenix:3.> where Name="Lisa"; 


It is also possible to update a single item within the list, referencing the item using an integer that indicates 

its position in the list (where 0 is the first item). 

The following example updates the Skills column, modifying any existing list where "C" is the third 

item and changing that item in the list to "C++". 

|phoenix:1.> update staff.employees 

|phoenix:2.> set Skills(2)=["C++"] 

|phoenix:3.> where Skills(2)="C"; 


Updating an Object 

The following example updates part of an object, referencing the varbind to be updated using the -> 

symbol. 

|phoenix:1.> update staff.contractors 

|phoenix:2.> set ExtraInfo->ContractLength=2 

503


504 

|phoenix:3.> where ExtraInfo->ContractLength=1; 


ContractLength is updated to 2 in any records where the ContractLength within the 

ExtraInfo field was set to 1. 


B.9 Listing the Databases or Tables 

Examples 


Listing the Databases or Tables 

The show keyword lists the databases, columns, or tables of the current service, as shown in the following 

examples: 

show databases ; 

show tables from database_name ; 

show table database_name.table_name ; 

The following example shows all the databases of the current service. 

|phoenix:1.> show databases; 


. 

{ 

databases = [ 'staff' ] 

} 


The following example shows all the tables from the staff database. 

|phoenix:1.> show tables from staff; 


. 

{ 

tables = [ 'managers', 'employees', 'contractors' ] 

} 


The following example shows the full schema of the staff.managers table. 

|phoenix:1.> show table staff.managers; 


..... 

{ 

schema = { 

EmployeeID = { 

DataType = 'text'; 




Unique = 'Y'; 

} 

Name = { 

Datatype = 'text'; 

..... 

..... 

}; 

505


506 

} 



B.10 Deleting a Record from a Database Table 

! 

You can delete a record from a table using the delete command, as in the example below. 

delete from database_name.table_name 



Deleting a Record from a Database Table 

Warning: Although the where condition is optional, omitting it deletes all the records in the table. 

Basic Example of Deletion 

The following example deletes all records from the staff.contractors table where 

Name="James". 

|phoenix:1.> delete from staff.contractors 

|phoenix:2.> where Name="James"; 


Deleting on Part of Object or List 

The following example removes records based on part of the contents of an object. 

|phoenix:1.> delete from staff.contractors // Delete records where 

|phoenix:2.> where ExtraInfo->Department="Marketing";// the Department in 

|phoenix:3.> go // ExtraInfo is Marketing. 

The following example removes records based on part of the contents of a list. 

|phoenix:1.> delete from staff.employees 

|phoenix:2.> where Skills(0)="Perl"; // Delete records where "Perl" 

|phoenix:3.> go // is the first list item. 

The following example removes records based on the entire contents of a list. 

|phoenix:1.> delete from staff.employees 

|phoenix:2.> where Skills=["HTML", "C++", "Java"]; 


507


B.11 Deleting a Database or Table 

508 

You can delete a database or table using the drop command, as in the examples below. 

drop table database_name.table_name ; 

drop database database_name ; 

Example of Deleting a Database and Table 

The following example deletes the entire staff.managers table. 

|phoenix:1.> drop table staff.managers; 


The following example deletes the entire staff database. 

|phoenix:1.> drop database staff; 



B.12 The Eval Statement 

Scope 


The Eval Statement 

The eval statement is a means of evaluating the value of a variable or a column within a record and 

converting it into another datatype (if necessary). Eval statements are used in combination with OQL in the 

stitchers to extract values from records in one database and insert those values into another database. This 

section introduces the eval statement and scope. 

The evaluation declaration evaluates a given variable or database record and extracts it to a specified 

datatype. 

eval ( datatype , string_or_database_column ) 

Using the eval statement, you can evaluate specified fields within database records and assign those fields to 

variables or other database columns if necessary. Ampersands are used to indicate the scope from which the 

record is taken. 

Examples of the use of eval statement within the context of the OQL language are shown below. 

m_CompareDb = eval( text, '&m_Creator' ) 

insert into kernel.activeModel values (eval( text, "$RECORD" )) 

delete from kernel.activeModel where (ObjectId=eval ( text, "&ObjectId" )) 

The concept of scope is used throughout the stitcher language as a means of referring to database records 

from within nested programming loops enclosed in curly braces { }. The example code extract below shows 

three nested scopes: 

{ 

} 

Start of the first scope (SCOPE1) 

.............. 

{ 

Start of the second scope (SCOPE2) 

.............. 

{ 

Start of third scope (SCOPE3) 

.............. 

.............. 

End of third scope (SCOPE3) 

} 

.............. 

End of the second scope (SCOPE2) 

} 

........... 

End of the first scope (SCOPE1) 

509


510 

The database records that are known within any given scope are said to be local to that scope. The eval 

statement uses a system of ampersands to refer either to these local records or to those records that are outside 

the current scope. The only restriction on references to records outside of the present scope is that you 

cannot reference database records known to scopes that are nested within the present scope. 

In the example code above: 

An eval statement within scope3 that refers to the EntityName column in a local database 

record would refer to it as &EntityName. 

An eval statement within scope3 that refers to the EntityName column in a record held in 

scope2 would refer to it as &&EntityName. 

An eval statement within scope3 that refers to the EntityName column in a record held in 

scope1 would refer to it as &&&EntityName. 

It would not be possible to refer to any record held in scope3 from scope2, but scope3 could 

refer to any record held in scope1 or scope2 using the appropriate number of ampersands. 

The eval Statement Syntax 

The eval statement has the following format: 

eval ( datatype , variable or database column to be evaluated ) 

In this statement: 

The first argument supplied to the eval statement is the datatype into which the second argument is 

converted. The datatype can be any of the OQL datatypes, such as text, int, list type text or object 

type vblist. 

The second argument is the expression that is to be evaluated, which can include: 

– Variable references, that are preceded by a dollar sign. The variables that can be referenced may 

be global variables such as system variables like $HOSTNAME, Netcool/Precision IP-defined 

variables such as $BaseEntity, and all the environment variables of the shell within which 

the Netcool/Precision IP executable is running, for example, NCHOME. 

– References to database columns known to the current scope or outside the current scope that are 

preceded by the appropriate number of ampersands. If the database column refers to an object, 

an entry within the object can be extracted using the target identifier -> (shown in use in OQL 

in Examples of the eval Statement in Use on page 511). 

– A manipulative statement that can be used to modify complex datatypes (such as lists or 

objects), concatenate two items together, delete item(s) from a list, and so on. 




– A special expression using the THIS keyword to move in and out of the data containment 

model. 

– Combinations of multiple evaluation expressions. 

Quotation Marks within eval Statements 

The variable or database column to be evaluated must be enclosed by matching quotation marks. If the eval 

statement is embedded within a set of quotes (in either Netcool/Precision IP language), the quotes enclosing 

the variable or database column must be of the alternate type to the quotes in which the eval statement is 

embedded. By default, when the eval statement does not occur within an embedded fragment, double 

quotes are used to enclose the variable or database column to be evaluated. 

Single Straight Back Quotes (``) 

Single straight back quotes are used within eval statements to enclose values that are not to be evaluated. 

For example, this type of quote is used with the CAT keyword to enclose text strings that are to be 

concatenated but not evaluated. In the following example, the strings [ [ and ] ] are included in the 

concatenated output but not evaluated. 

eval( text, 'CAT( &m_Name,‘[ [ ‘,&m_LocalNbr->m_IfIndex,‘ ] ]‘ )' ) 

The CAT keyword is described in Concatenating Lists on page 514. 

Examples of the eval Statement in Use 

The following example evaluates the contents of the m_Creator database column (held 1 level of scope 

away from the current scope) and inserts the value into myVariable, a previously declared variable of 

type text. 

myVariable = eval( text , '&m_Creator' ) 

The following example declares an integer variable called portNum and assigns to it the value extracted 

from m_LocalNbrPort held within an object called m_LocalNbr that is known two levels away from 

the present scope. m_LocalNbrPort is extracted from the object using the target identifier. 

int portNum = eval( int, "&&m_LocalNbr->m_LocalNbrPort" ) 

The following example shows the eval statement in use in the stitcher language within two foreach loops. 

foreach( connected ) 

{ 

foreach( uniqueConnector ) 

{ 

ExecuteOQL 

( 

"update tempFull.connected 

511


512 

} 

} 

); 

set m_RelatedTo = eval(text, '&m_NbrName') 

where m_Name = eval(text, '&&m_RelatedTo') 

);" 

Each of the foreach loops in the above example specifies a variable of type RecordList that has 

already been assigned the results of an OQL query. The first loop repeats everything within its curly braces 

for each record in the RecordList variable connected. Nested within the foreach( connected 

){ } loop is a second loop, that repeats everything within its curly braces for each record in the 

RecordList variable uniqueConnector. 

The ExecuteOQL statement that is nested inside both loops updates the tempFull.connected 

database using an eval statement to extract columns from the records held in the two variables: 

The statement eval(text,'&m_NbrName') refers to the m_NbrName column contained 

within the local scope, that is, held in the uniqueConnector variable. 

The statement eval(text,'&&m_RelatedTo') refers to the m_RelatedTo column 

contained one level away from the local scope, that is, held in the connected variable. 

Extraction of Record Values and Fields in OQL 

There are two special functions that are used within eval statements in OQL that simplify the process of 

extracting record field names and record values: 

RECORD_NAMES() extracts all field names of the current database record being considered. 

RECORD_VALUES() extracts the values of all fields within the current database record being 

considered. 

An example of these functions from the StoreSchema.cfg configuration file is shown below. In this 

example an eval statement is used to extract all the column names and values from a record instead of having 

to extract each column name and value using an individual eval statement. 


( Name, Filter, Execute, IsActive, ) 

values 

( 

'modelCreate','', 

'insert into kernel.activeModel 

( eval( text, "RECORD_NAMES()" ) ) 

values 

( eval( text, "RECORD_VALUES()" ) );', 

1 

); 




In addition to being shorter, this method of extracting values has the advantage that you do not need to 

know anything about the column names, datatypes or even how many columns there are. 

Advanced Use of the eval Statement 

This section describes the advanced use of the eval statement. 

Character Escape Sequences 

You must escape characters that would otherwise have special meaning in an eval statement using a 

double-backslash \\. The comma, dollar, ampersand and open and close brackets can be escaped as shown 

below. 

\\, -- Escapes the comma. 

\\$ -- Escapes the dollar. 

\\& -- Escapes the ampersand. 

\$ -- Escapes the open bracket. 

\$ -- Escapes the close bracket. 

Eval Statement Keywords 

It is possible to perform complex operations within eval statements using a series of keywords, shown in 

Table B10. 

Table B10: Table of Valid eval Statement Keywords 

Keyword Synopsis of Keyword Function 

APPEND Appends data to a list or object. 

APPENDUNIQUE Appends data to a list or object only if it does not already exist within the list. 

CAT Concatenates a series of items together. 

DELETE Deletes an item from a list. 

LENGTH Indicates the length of a list or the number of items it holds. 

LOOKUP Allows the use of lookup tables and enables the use of a default human-readable return value in 

the event of a lookup failure. 

THIS Retrieves information pertaining to the containers within the containment model. 

513


514 

Concatenating Lists 

The CAT keyword concatenates data within an eval statement. 

CAT( comma separated list of items to be concatenated ) 

The items to be concatenated together can be any of the following: 

A reference to a database record (preceded by the appropriate number of ampersands). 

A reference to a system or Netcool/Precision IP variable. 

A text string enclosed within single straight back quotes, for example, ‘item‘. 

eval( text, 'CAT(‘UNCONNECTED_NODES / ‘,&m_Subnet,‘ / ‘,&m_SubnetMask)' ) 

If m_Subnet='172.16.2.0' and m_SubnetMask='255.255.255.0', the above example 

would evaluate to the following text string: 

UNCONNECTED_NODES / 172.16.2.0 / 255.255.255.0 

In the following example, the target identifier extracts the value of a varbind within an object. 

eval( text, 'CAT( &m_Name,‘[ ‘,&m_LocalNbr->m_IfIndex,‘ ]‘ )' ) 

If the values m_Name="172.16.1.239" and m_IfIndex=63 entered into the example above, this 

example would evaluate to the following string: 

172.16.1.239[ 63 ] 

Deleting Data from a List 

The DELETE statement removes the items in the second list from the first list. 

DELETE( List or reference to a column of type list , 

List or reference to a column of type list ) 




In the following example, the output would be the result of removing all items in the EventId list from 

the CorrelatedId list. 

eval( list type text, 'DELETE( &CorrelatedId , &EventId )' 

Finding the Number of Items in a List 

The LENGTH keyword returns the number of items in the specified list. The following example would 

return the number of items in the list CorrelatedId. 

eval( int, 'LENGTH( &CorrelatedId )' 

Evaluating the Containment Model 

The THIS keyword can be used to move recursively through the containment model. 

THIS( Number of levels to traverse up the containment model , 

Number of levels to traverse down the containment model , 

FLAG ) -> Part of object to retrieve 

The number of levels to traverse up or down the model can either be specified as an integer or as the variable 

$PHYSICAL, which indicates that the recursion terminates at the top of the containment model. 

FLAG denotes whether all the levels encountered during the recursion through the different containment 

model levels are to be accumulated into a list, or if only the final destination is to be considered. The possible 

values of FLAG are: 

$INCLUDERECURSED. All entities encountered in the containment model during the recursion of 

the levels are included and accumulated together as a list. 

$EXCLUDERECURSED. All entities encountered during the recursion through the containment 

model are excluded. Only the final entity at the end of the recursion is considered. 

An example of THIS in use is shown below. This example evaluates EntityName by traversing 1 level 

down the model and accumulating all encountered entities into a list. 

eval( list type text, 'THIS(0, 1, $INCLUDERECURSED) ->EntityName' ) 

Omitting the number of levels and the flag extracts a value from the current entity, as shown below. 

eval( text, 'THIS->EntityName' ) 

Performing a Lookup 

The LOOKUP keyword allows the use of lookup tables and enables the use of a default human-readable 

return value in the event of a lookup failure. This section shows an example of a lookup operation on the 

ifAdminStatus MIB variable. 

515


516 

The following is an example of a lookup record which maps ifAdminStatus strings to their enumerated 

values: 

{ 

} 

ifAdminStatus = 

{ 

up = 1, 

down = 2, 

testing = 3 

} 

The following eval clause performs a lookup of the enumerated value of the string up within this record 

and returns a value of 1. The default return value in the event of a lookup failure is NULL. 

eval( text, 'LOOKUP( ’up’,&ifAdminStatus )' 

In this clause, no default human-readable return value in the event of a lookup failure has been provided. 

This is therefore equivalent to the eval clause shown below: 

eval( text, ( ’&ifAdminStatus->up’ ) 

The following eval clause performs a lookup of the enumerated value of the string dummy within this 

record and provides the option of a default human-readable return value. The string dummy does not exist 

in the record and therefore this clause returns the defined human-readable return value of unknown. 

eval( text, 'LOOKUP( ’dummy’,&ifAdminStatus, ’unknown’)' 


C. Stitchers_and_language.fm July 5, 2005 

Appendix C: Stitchers and Stitcher Language 

This chapter describes the function of the default discovery stitchers, the structure of a text-based stitcher, 

and describes the syntax of the stitcher language that is used to create and customize text-defined stitchers. 


Introduction to Discovery Stitchers on page 518 

List of Default Discovery Stitchers on page 521 

Stitcher Language on page 535 

Stitcher Text File Structure on page 540 

Stitcher Rules on page 544 



C.1 Introduction to Discovery Stitchers 

518 

Stitchers are versatile and configurable processes used extensively during the discovery and monitoring 

processes that facilitate data transfer by taking information from one database, processing it, and placing it 

in its new form in another database or sending it to another process. The stitchers can also be modified for 

particular occurrences, for example, strange configurations, or devices being added or removed. 

There are two types of stitcher: 

Discovery Stitchers 

Discovery stitchers, which are used during the network discovery process. 

Monitoring stitchers, which are used during network monitoring. 

Discovery stitchers have two general areas of responsibility but are syntactically the same: 

Data collection stitchers pass records from finders to discovery agents, from discovery agents to other 

discovery agents, and from discovery agents to finders, thus feeding the discovery process. 

Data processing stitchers are activated in the final phase of the discovery. They build the various layers 

of the topology that are then merged to produce the scratch topology that is sent to MODEL. 

Monitoring Stitchers 

Monitoring stitchers are used during network monitoring. More information about these stitchers can be 

found in the Netcool/Precision IP Monitoring and RCA Guide. 

Stitcher Formats 

Stitchers can either be text-based or precompiled. 

Text-based Stitchers 

Text-based stitchers are defined in a plain text file using the stitcher language. The text file defines the 

processing that the stitcher performs and the reasons why the stitcher is triggered. 

A text-based stitcher can also invoke any other stitcher regardless of whether it is precompiled or text-based. 

Precompiled Stitchers 

Precompiled stitchers are written by Micromuse in C++ and shipped with the Precision Server. The 

precompiled stitchers are designed for computationally intensive operations that they can handle more 

efficiently than the text-based stitchers. 



Introduction to Discovery Stitchers 

The precompiled stitchers are controlled by a text-based stitcher, which contains the stitcher trigger 

conditions. When the text-based stitcher is executed, it calls and executes the precompiled stitcher. 

Structure of the Stitchers 

Each stitcher definition file consists of two main sections: 

The stitcher triggers specify the actions or conditions that cause the stitcher to run. 

The stitcher rules define the processing that the stitcher conducts. 

Stitcher Triggers 

Stitchers can be triggered by any of the following conditions: 

The completion of other processes (for example, finders, agents, and other stitchers). 

The insertion of data into a specified database table. 

The end of a specified discovery cycle phase. 

Stitchers can also act: 

According to a preconfigured time frequency. 

When asked to do so, that is, on-demand. 

You can retrieve stitcher trigger information for the discovery stitchers by performing an OQL query on the 

stitchers.triggers table that resides within DISCO. This table is created and updated by a 

periodic scan that DISCO performs on the stitcher files in the 

NCHOME/precision/disco/stitchers directory. 



page 10. 

Stitchers are also used during the network monitoring process. The monitoring stitchers are stored in the 

NCHOME/precision/monitor/stitchers directory, and activated on-demand when required by 

one of the Polling agents. For more details on network monitoring, and the use of stitchers, see the 


You can run a specific stitcher by entering the stitcher name in the only field of the 

stitchers.actions table, whereupon DISCO will attempt to execute the specified stitcher. For 

example, if you update the stitchers.actions table value with ’Restitcher’, then DISCO will 

attempt to restitch the topology. You can use this functionality to propogate any modifications throughout 

the topology. 

519


520 

Stitcher Rules 

Stitcher rules define the actual processing that the stitcher is to conduct. The rules are written in the stitcher 

language, which is described later in this chapter. Special stitcher language commands allow OQL 

statements to be made by the stitchers, so a stitcher can retrieve information from a database and manipulate 

it. The end result is the distribution of processed information into the appropriate final destination table. 


C.2 List of Default Discovery Stitchers 

Stitchers supplied with Netcool/Precision IP are stored in the following directories: 


List of Default Discovery Stitchers 

NCHOME/precision/disco/stitchers holds the text-based discovery stitchers (text files 

with a .stch extension). 

NCHOME/precision/lib contains the libraries for the precompiled discovery stitchers. 

NCHOME/precision/monitor/stitchers holds the text-based monitoring stitchers (text 

files with a .stch extension). 

NCHOME/precision/monitor/lib contains the libraries for the precompiled monitoring 

stitchers. 

Table C1 shows a list and description of all the discovery stitchers currently included with the Precision 

Server, although you should note that this list is subject to change. 

Table C1: List of Netcool/Precision IP Discovery Stitchers (1 of 14) 

Stitcher Function 

AddBaseNATTags Updates all the private NAT addresses that have a private address with their 

public address and adds a tag denoting the private address. 

AddBasicContainment Part of the mechanism for containment stitching. This stitcher inserts 

containment information into the simple chassis. 

AddCardContainment Adds card objects to the workingEntities.containment table. 

AddEntityContainment Adds general entity information to the workingEntities.containment 

table. 

AddGlobalVlans Builds global Virtual Local Area Network (VLAN) objects using the 

translations.vlans table. 

AddIfStackContainment Adds if stack objects to the workingEntities.containment table. 

AddLogicalToIpToBaseName Adds logical information to the translations.ipToBaseName table. 

AddLoopbackTag Adds a tag to the ExtraInfo column of the topology database indicating 

that an interface is a globally addressable loopback interface. 

521


522 



AddNoConnectionsToLayer The final topology layer is constructed by merging the topology information 

from the various layers. If there is a mismatch in connectivity information 

provided by the different layers, information from the more detailed layer takes 

precedence. 

For example, the Network Layer (layer 3) provides information indicating that a 

router interface is connected to another router interface. However, information 

from the more detailed Data Link Layer (layer 2) shows that there is actually a 

switch between the two router interfaces. 

The AddNoConnectionsToLayer is used in cases where it is necessary to 

remove a connection at one layer but keep the connection at a different layer. 

AddSwitchRoutingLinks Adds switch routing data (that assists AMOS when performing Root Cause 

Analysis) to the topology database. 

AddTechnologyType.stch Optional stitcher called by the PostScratchProcessing.stch stitcher. This stitcher 

is commented out by default. If enabled, this stitcher creates a technology type 

variable for each interface object. This variable can then be used to create 

technology based network views in Topoviz. See the Netcool/Precision IP 

Topology Visualization Guide for more information on network views. 

The stitcher creates the technology type variable by adding an 

m_Technology field to the ExtraInfo field within the 

scratchTopology.entityByName table for each interface object. The 

m_Technology field is a string, such as Ethernet, ATM, and so on. The 

stitcher contains a large collection of default technology types; more can be 

added by directly altering the stitcher. 

There is a small processing load associated with activating this stitcher, and this 

will slow down your discovery slightly. 

AddUnconnectedContainment Takes all the discovered entities that are unconnected, that is, that do not have 

a parent (except for their main node or interface) and gives them a default 

containment. 

AddVlanContainers Uses information in the workingEntities.finalEntity and 

translations.vlans tables to add VLAN objects to the 

workingEntities.containment table. 

AgentRetProcessing Processes data from thereturns table of each table. 

AgentRetToInstrumentationCiscoFrame 

Relay 

Populates the instrumentation.ciscoFrameRelay table with 

information from the returns table of the appropriate agent. 

AgentRetToInstrumentationFddi Populates the instrumentation.fddi table with information from the 

returns table of the appropriate agent. 

AgentRetToInstrumentationFrameRelay Populates the instrumentation.frameRelay table with information 

from the returns table of the appropriate agent. 






AgentRetToInstrumentationHSRP Populates the instrumentation.hsrp table with information from the 


AgentRetToInstrumentationIp Populates the instrumentation.ip table with information from the 


AgentRetToInstrumentationName Populates the instrumentation.name table with information from the 


AgentRetToInstrumentationPnniPgi Populates the instrumentation.pnniPeerGroup table with 

information from the returns table of the appropriate agent. 

AgentRetToInstrumentationSubnet Populates the instrumentation.subNet table with information from the 


AgentRetToInstrumentationVlan Populates the instrumentation.vlan table with information from the 


ASMAgentRetProcessing Based on MIB variable data retrieved by the ASM stitcher, this stitcher 

generates a list of Netcool/ASM sub agents running on a given device. Each 

Netcool/ASM sub-agent running on a device corresponds to a commercial 

server or database product running on that device. The list of Netcool/ASMs is 

used as input to the MySQL database in Topoviz and enables autopartitioning 

of devices within a network based on the commercial server or database 

products running on those devices. 

ASRetProcessing Used in MPLS discoveries where devices in different customer VPNs have 

identical IP addresses. This stitcher performs the processing necessary to 

differentiate between these devices and correctly resolve device connectivity. 

This stitcher is called by the AsAgent agent and works in conjunction with the 

ASMap.txt file in NCHOME/precision/etc. For more information on the 

AsAgent agent, see Deduplicating Identical IP Addresses in Different VPNs on 

page 255. 

AssocAddressRetProcessing Processes data in the AssocAddress.returns table, sending the device 

details to the appropriate discovery agent if the device has not already been 

discovered. 

BGPLayer Builds the BGP layer created by BGP agent. In common with other layer 

stitchers, this stitcher receives input from relevant agents. This input consists of 

entity records containing local and remote neighbor data fields. The stitcher 

uses these records to work out the local and remote connections for each 

entity. 

523


524 



BuildContainment Calls the following stitchers to add different types of objects to the 

workingEntities.finalEntity table: 

AddBasicContainment stitcher, which adds device containment 

information. 

AddCardContainment stitcher, which adds card containment 

information. 

AddIfStackContainment stitcher, which adds interface stack 

containment information. 

AddEntityContainment stitcher, which adds general containment 

information. 

NATAddressSpaceContainment stitcher, which adds containment 

information associated with NAT address spaces. 

AddVlanContainers stitcher, which adds VLAN containment 

information. 

You can comment out lines in this stitcher as appropriate in order to exclude 

types of objects that are not needed. 

BuildFinalEntity Builds the records for a single chassis. This stitcher is called by the 

BuildFinalEntityTable stitcher. 

BuildFinalEntityTable Uses the entries in the translations.ipToBaseName table to populate 

the workingEntities.finalEntity table. 






BuildInterfaceName Used to control the naming of interfaces. By default, this stitcher is called by 

the BuildFinalEntity stitcher. 

The default naming strategy for any device interface is as follows: 

baseName[[]] 

Alternatively Netcool/Precision IP uses the following default naming 

convention if the card and port are not valid: 

baseName[0[]] 

You can use the BuildInterfaceName stitcher to change the naming 

convention for an interface in one of the following ways: 

Specify that you wish to use ifName or ifDescr to name the interfaces 

rather than their ifIndex, card or port information. For example, using 

this option interfaces would have names similar to the following: 

baseName[eth0/0] 

In this example eth0 is the ifName of an interface. 

In order to do this, change the value of m_UseIfName in the 

disco.config table, as described in The config Table on page 431. 

Modify the BuildInterfaceName stitcher directly to specify any 

desired interface naming convention. 

BuildLayers Activated in the final phase to implement the stitchers that build the layer 

databases. 

BuildMPLSContainers This stitcher calls the BuildVPNContainers and BuildVRAndVRFContainers 

stitchers. It builds VPN, VR and VRF containers. 

BuildNATTranslation Builds a global translation table for all NAT devices. 

BuildVPNContainers Creates objects to represent the MPLS VPNs within the system. 

BuildVRAndVRFContainers Creates virtual router (VR) and virtual routing and forwarding table (VRF) 

objects within the system. These objects are useful for displaying MPLS 

information. 

CabletronLayer Determines connectivity information based on Cabletron data returned by the 

discovery agents. 

CDPLayer Determines connectivity information based on the data returned by the CDP 

agent. 

CheckAndSendNATGatewaysToArpCac 

he 

Sends the NAT gateways to the ArpCache agent. 

CheckForMasterLink Looks for connections lower down the interface stack, that take precedence 

over connections higher up. 

CheckIndirectResponse Handles indirect ICMP responses due to NAT. 

525


526 



CheckInterfaceStatus Checks the ifOperStatus data and updates the interfaces status where the 

ifOperStatus is not 1. 

CMTSLayer Uses the data downloaded by the CMTS agent to build the connection 

information between cable modem termination systems and the attached 

cable modem devices. 

ContextAgentRetProcessing Merges the outputs of all the Context agents for each entity. It then inserts the 

results of this merge into the AssocAddress.despatch table, using the 

DetailsOrContextRetProcToAgent stitcher. For more information on the 

context-sensitive discovery data flow, see Discovering Device Details 

(Context-Sensitive) on page 28. 

CreateAndSendTopology Activates the stitchers that create the topology and send the final Scratch 

Topology to MODEL. 

CreateImpactTopology An optional stitcher that can be used to make a copy of the Scratch Topology 

before it is sent to MODEL. See The entityByName Table on page 472 for more 

details. 

CreateNetworkManagementCards This stitcher creates NetworkManagementCard objects, if desired. 

CreateScratchTopology Creates the scratch topology. 

CreateTrunkConnections Modifies the containment model to take account of VLAN trunks. 

CreateVlanEntity This stitcher creates a single VLAN entity object by adding VLAN data to the 

Scratch Topology. 

DetailsOrContextRetProcToAgent This stitcher is equivalent to DetailsRetProcessing but handles 

context-sensitive discovery. It processes entities from the 

details.returns table, and sends the details to the despatch table of the 

relevant Context agent. For more information on the context-sensitive 

discovery data flow, see Discovering Device Details (Context-Sensitive) on 

page 28. 

DetailsRetProcessing Processes entities from the details.returns table, and sends the details 

to the AssocAddress.despatch table. 






DetectionFilter Determines whether a given device passes the detection filter and is to be 

discovered based on the detectionFilter defined in the scope 

database. 

By default, the discovery filters do not filter out the Netcool/Precision IP host 

machine. This is because this machine usually also serves as the polling station 

for root cause analysis. In order for root cause analysis to work correctly, the 

polling station, and hence the Netcool/Precision IP host machine, must be part 

of the topology. For more information on root cause analysis, see the 


If you need to filter out the Netcool/Precision IP host machine using the 

detectionFilter, then you need to modify the DetectionFilter stitcher 

and remove the sections of code indicated by comments that prevent the 

Netcool/Precision IP host machine from being filtered. 

DetermineOSPFDomains Tags devices and interfaces with OSPF domain information. This stitcher is 

called by the OSPFLayer stitcher. 

DiscoShutdown Activated when DISCO is shut down. Calls the RefreshDiscoveryTables stitcher. 

ExampleContainment1 An example stitcher that could be modified to configure the containment 

model. 

ExampleContainment2 An example stitcher that could be modified to configure the containment 

model. 

FddiLayer Deduces the Fddi layer topology. 

Feedback Sends device details back to the Ping finder to re-seed the discovery. 

FinalPhase Activated in the final phase to implement the final stitchers. 

FindAddressSpace Identifies the address space of an IP address. 

FindGatewayInterfaces Identifies the gateway interface on NAT translation devices. 

FindPhysIpForVirtIp Used in resolution of HSRP issues. Finds the physical IP address corresponding 

to a virtual HSRP address. 

FnderProcToDetailsDesp Sends entities from the finders.processing table to the 

Details.despatch table. 

FnderRediscoveryToPingFinder Sends data from the finders.rediscovery table to the Ping finder. 

FnderRetProcessing Processes entities in the finders.despatch table, and sends the details to 

the Details agent. 

FullDiscovery Determines whether a full discovery is to be run. 

HubFdbToConnections A precompiled stitcher that processes all of the connections for the Ethernet 

hubs. It also requires the connectivity information from the Ethernet switch 

discovery. 

527


528 



IlmiLayer Creates the ILMI (Interim Local Management Interface) topology connections 

based upon ATM ILMI information. 

InitiateNATGatewayDiscovery Seeds the Ping finder with the NAT gateway addresses. 

InstantiationFilter Determines whether a given entity is to be instantiated (that is, sent to 

MODEL), based on the instantiateFilter defined in the scope 

database. 

By default, the discovery filters do not filter out the Netcool/Precision IP host 

machine. This is because this machine usually also serves as the polling station 

for root cause analysis. In order for root cause analysis to work correctly, the 

polling station, and hence the Netcool/Precision IP host machine, must be part 

of the topology. For more information on root cause analysis, see the 


If you need to filter out the Netcool/Precision IP host machine using the 

instantiateFilter , then you need to modify the InstantiationFilter 

stitcher and remove the sections of code indicated by comments that prevent 

the Netcool/Precision IP host machine from being filtered. 

IPLayer Creates the IP layer topology connections. 

IpToBaseName Populates the translations.ipToBaseName table with information from 

the AssocAddress agent. 

IsForcedRediscovery This stitcher is used to determine if a finder insert is part of a forced 

rediscovery. Forced rediscovery contrasts with reactive rediscovery, the mode 

that DISCO adopts after completion of a discovery. In this mode a device is 

usually only rediscovered if it is new or if the finder insert references a trap, 

thus suggesting that the entity has been modified. 

Forced rediscoveries are launched using the Network Discovery GUI, as 

described in Running Discoveries and Rediscoveries on page 139. 

For more information on rediscovery mode, see Conducting a Full or Partial 

Rediscovery on page 40. 

IsInScope Used by other stitchers to check that an entity is within the scope of the 

discovery (that is, within the scope defined in the scope.zones table). 

MergeLayers Merges the layer topologies. 

ModifyIPContainment Modifies the containment of IP interfaces on non IP forwarding devices so that 

they are not upwardly connected. This is required to trace root cause. 

MPLSAddPathnames Updates the MPLS interface records with information on path membership. 

MPLSAddVPNNames Determines what paths belong to which VPNs, and updates the MPLS interface 

records with the information on the VPN/Path membership. 






MPLSCE Tries to resolve CE to PE connectivity for VRF interfaces on a PE where the 

connecting CE has not been identified. It uses layer 3 information to try to find 

the correct connectivity. 

MPLSFindConnectionInStack Adds connections to MPLS interfaces where they were not previously found, 

but have been found at other layers of the interface stack. 

MPLSFindInterfaceInStack Finds an interface at a different layer of the interface stack to an MPLS interface. 

MPLSInterfaceStackTrace Iterates up or down the interface stack to try to find a connection at a layer 

other than the MPLS layer. 

MPLSPathDiscovery Identifies labels switched paths (LSPs) between provider edge (PE) routers 

across an MPLS core. Starts path traces from the PE devices. The entry point 

stitcher sets up the path trace database, and begins a path trace for each 

possible path, calling other stitchers to update the records with path and VPN 

information. 

MPLSProcessing Determines which kind of MPLS discovery to perform based on the value of the 

field m_RTBasedVPNs in the disco.config table. 

If m_RTBasedVPNs equals 1, then route target-based MPLS post-layer 

processing is performed. The MPLSProcessing stitcher calls the 

RTBasedVPNDiscovery stitcher to perform this processing. The MPLS 

discovery results in the ability to display an edge view only. 

If m_RTBasedVPNs equals 0, then label switched path (LSP)-based 

post-layer processing is performed. The MPLSProcessing stitcher calls 

the MPLSPathDiscovery stitcher to perform this processing. The MPLS 

discovery results in the ability to display an edge view and a core view. 

For more information on edge views and core views of an MPLS core network, 

see About MPLS Discovery on page 326. 

NameResolution Finds entities where the name has not been resolved and attempts to resolve 

the entity name based on the resolved names of the other interfaces of the 

device. 

NamingFromLoopbackDetails Provided there is a LoopBack agent running, this stitcher updates the names in 

the translations.ipToBaseName table. 

NATAddressSpaceContainers Optional stitcher that builds NAT container objects holding devices within a 

particular address space and creates inserts into the 

workingEntities.finalEntity table for these NAT container objects. 

Also builds relevant entries into the workingEntities.containment 

table. 

NATAgentRetProcessing Processes the output from the NAT gateway agents. 

NATFnderRetProcessing Performs processing of NAT devices. 

529


530 



NATGatewayRetProcessing Used in discoveries involving NAT gateways where one or more of the 

management interfaces of the NAT gateway device is in private address space. 

This stitcher performs the processing necessary to determine whether each 

management interface is in public or private address space. This stitcher is 

called by the NATGatewayAgent agent and works in conjunction with the 

NATGateways.txt file in NCHOME/precision/etc. For more 

information on the NATGatewayAgent agent, see Configuring NAT Gateway 

Management Interfaces on page 257. 

NATTimer Triggers rediscovery of NAT gateways. 

OSPFLayer Creates a topology of the OSPF routing within the network. This OSPF routing 

information is used by the DetermineOSPFDomains stitcher in order to tag 

devices and interfaces with OSPF domain information. 

PeerBasedPWDiscovery Used in discovery of enhanced Layer 2 VPNs on an MPLS core network. This 

stitcher identifies MPLS psuedowire connections retrieved by the Cisco MPLS 

agents and adds information on these connections to the relevant network 

entities for viewing in Topoviz. The information is stored as a psuedowire VPN 

and provides information on the two provider edge (PE) router ends of the 

psuedowire. For more information on enhanced Layer 2 VPN discovery, see 

Chapter 11: Configuring an MPLS Discovery on page 325. 

PingFinderScopeRefresh Tells the Ping Finder to refresh its scope. This stitcher is activated by the 

Network Discovery GUI when you refresh the scope and thereby ensure that 

the Ping finder has an up-to-date scope. 

PnniLayer Creates the PNNI topology connections provided the connections at both ends 

have been discovered. 






PostLayerProcessing A holder for all the functionality that is required following the creation of the 

layers. Calls the following stitchers: 

AddGlobalVlans 

AddSwitchRoutingLinks 

AddUnconnectedContainment 

BuildMPLSContainers 

BuildVRAndVRFContainers 

BuildVPNContainers 

CreateTrunkConnections 

CreateVlanEntity 

MPLSAddVPNNames 

MPLSPathDiscovery 

MPLSInterfaceStackTrace 

MPLSFindConnectionInStack 

MPLSFindInterfaceInStack 

MPLSAddPathNames 

PVCPathMemberships 

PVCTracePath 

PVCProcessingRecord 

PVCTraceAway 

PVCTraceCrossConnected 

PVCNamePath 

PVCProcessedRecord 

ProcessSwitchModules 

PostScratchProcessing A holder for functionality to occur following the creation of the scratch 

topology. Calls the following stitchers: 

CreateNetworkManagementCards 

InstantiationFilter: This stitcher is run as many times as necessary in order 

to check whether a given entity needs to be sent to MODEL. 

SendTopologyToModel 

AddTechnologyType 

PresetLayer Can be used to "preset" undiscoverable connections, if required. This stitcher is 

not used by default. 

This stitcher contains advanced configuration settings. Any changes should be 

made by Micromuse certified personnel only. 

531


532 



ProcessSwitchModules Identifies which switch modules have their own IP addresses. 

ProcRemoteConns Takes a record containing a remote neighbor and processes remote 

connections if the agent that discovered it supports indirect connections. 

ProfilingEndFinal 

ProfilingPhase1 



ProfilingStartFinal 

These stitchers populate the disco.profilingData table, providing data 

on discovery duration, memory usage, and a broad overview of the results of 

the discovery. This information is used by Micromuse in the estimation of 

scaling, and provides you with an overview of discovery performance. 

PVCNamePath Adds the name of a PVC path to the internal atmPVCs.memberships 


PVCPathMemberships Executed automatically by CreateScratchTopology.stch during the 

discovery process. Uses the connectivity information from the Scratch 

Topology and the PVC information retrieved by the CiscoPVC agent to trace 

the PVCs across the network. 

PVCProcessedRecord Updates the atmPVCs database to indicate which record is currently being 

processed. 

PVCProcessingRecord Updates the atmPVCs database to indicate which record is currently being 

processed. 

PVCTraceAway Performs PVC tracing. 

PVCTraceCrossConnected Performs PVC tracing. 

PVCTracePath Performs PVC tracing for a given interface using the other PVC tracing stitchers 

to trace all the paths through the entire ATM section of the network. 

PVCTraceTowards Performs PVC tracing. 

RebuildFinalEntityTable This stitcher is very similar to the BuildFinalEntityTable. It also uses the entries 

in the translations.ipToBaseName table to populate the 

workingEntities.finalEntity table. The difference is that this stitcher 

is used in rediscovery mode rather than full discovery mode. 

RecreateAndSendTopology This stitcher is very similar to the CreateAndSendTopology.stch. It also 

activates the stitchers that create the topology and sends the final Scratch 

Topology to MODEL. The difference is that this stitcher is used in rediscovery 

mode rather than full discovery mode. 

RecreateScratchTopology This stitcher is similar to CreateScratchTopology.stch. The difference is that this 

stitcher is used in rediscovery mode rather than full discovery mode. 

ReDoIpToBaseName Refreshes the translations.ipToBaseName table. 

RefreshDiscoveryTables Refreshes the discovery database tables. 




RefreshLayerDatabase Refreshes a given layer topology database. 

RefreshSubnets Refreshes a given subnet database. 



RemoveVlanMacAddress Removes MAC addresses of logical VLAN interfaces from switch agent returns 

tables. This stitcher is not used by default. 

ResetNATMainNodes Resets the IP of devices whose addresses have been translated by NAT from the 

private IP we use to resolve connectivity back to the public IP for monitoring. 

This allows the devices to be connected and visualized correctly and also 

remain accessible for monitoring purposes. 

ResolveHSRPIssues Checks for entities that have been discovered through their virtual Hot 

Standby Routing Protocol (HSRP) address. In that situation, the stitcher 

updates the discovery agent returns tables and the 

translations.ipToBaseName to show the correct physical interface. 

ResolveVRRPAssocAddresses Resolves issues caused by VRRP addresses. In such a situation, the stitcher 

updates the discovery agent returns tables and the 

translations.ipToBaseName to show the correct physical interface. 

Restitcher Re-stitches the topology together. 

RTBasedVPNDiscovery Discovers MPLS VPNs based on route target usage. This results in an edge view 

only which shows the MPLS core network with provider edge (PE) routers for 

VPNs and VRFs within the scope of the discovery. This view does not show the 

provider (P) routers within the MPLS core network and associated LSPs (label 

switched paths) that link these P routers. For each PE router discovered, 

Netcool/Precision IP holds information on the route targets imported into and 

exported from that PE router. This enables you to identify which VPNs use 

which PE routers. 

SendTopologyToModel Sends the stitched topology to MODEL. 

SubnetConnections Creates subnet entities and inserts into each of the interfaces belonging to the 

subnet. At layer 3 level the interfaces within a subnet are all considered to be 

connected, so any connections not already discovered are added to the IP layer 

database. 

SubnetToIPLayer Adds default layer-three containment and/or connectivity. 

SRPLayer Builds the SRP layer to hold the containment information discovered by the 

SRP agent. In common with other layer stitchers, this stitcher receives input 

from relevant agents. This input consists of entity records containing local and 

remote neighbor data fields. The stitcher uses these records to work out the 

local and remote connections for each entity. 

SwitchFdbToConnections Copies entries from the Switch agent returns tables to the connections 

table. 

533


534 



SwitchStpToConnections Builds a new layer based on the SwitchStp connectivty. Processes the data 

from the STP agent to create correctly named local and remote entity 

connection records in the stpTopology database. 

In common with other layer stitchers, this stitcher receives input from relevant 

agents. This input consists of entity records containing local and remote 

neighbor data fields. The stitcher uses these records to work out the local and 

remote connections for each entity. 

SysNameNaming Causes the system to name devices using the SNMP sysName where the data is 

valid. This is an optional stitcher that is off by default. 

TagManagedEntities Adds a tag to each of the interfaces of a main node indicating whether that 

interface should be monitored or not. This tag is in the m_ExtraInfo field 

and is called m_IsManaged. The tag can take the values 0 or 1, where 0 

indicates that the interface must not be monitored. The m_IsManaged values 

for all interfaces in a main node are concatenated and stored in the 

m_ExtraInfo field for the main node, within m_UnmanagedInterfaces, 

using the format: [, , ..... ], 

where the IfIndices are the ifIndices of the interfaces you do not want the 

system to monitor. By default, the stitcher sets m_IsManaged to 0 for certain 

predefined types of interface, such as virtual interfaces. You can specify other 

interface types that you do not want the system to monitor by adding to a 

where clause within the stitcher. 

TagManagementInterfaces Tags the interface that has the IP address used as the main access IP address for 

a given entity. This stitcher is used in root cause analysis. 

TraceRouteConnectivity Updates the IPLayer.entityByNeighbor table with connectivity 

information retrieved from the TraceRoute agent returns data. 


C.3 Stitcher Language 


Stitcher Language 

This section describes the stitcher language, including datatypes, operators, comments and quotation marks. 

Stitcher Language Structural Statements 

The stitcher text files consist of a series of structural statements that enclose the stitcher rules (the actual 

processing) and the trigger conditions. 

The structure of a stitcher file is shown in Stitcher Text File Structure on page 540. Table C2 lists the stitcher 

language structural statements. 

Table C2: Stitcher Language Structural Statements 

Structural Statement Description See page 

CompiledStitcher{ } Declares the present stitcher as a compiled stitcher and introduces 

its trigger conditions. 

UserDefinedStitcher{ } Declares the present stitcher as a user-defined stitcher and 

introduces its externs (monitoring stitchers only), trigger conditions 

and stitcher rules. 

StitcherTrigger{ } Introduces the list of requirements that must be fulfilled before the 

stitcher can be executed. 

StitcherRules{ } Introduces a list of rules to be executed by the stitcher. 544 

Stitcher Trigger Conditions 

The trigger conditions for the stitcher, specified within the StitcherTrigger{} section, are listed in 

Table C3. 

Table C3: Generic Stitcher Trigger Conditions 

Stitcher Trigger Condition Description See page 

ActOnDemand( ); Declares that the stitcher is executed on-demand. 542 

ActOnTableInsert( ); Declares that the current stitcher starts when data is inserted in the 

specified database table. 

ActOnTimedTrigger( ); Declares that the stitcher must be executed on the specified 

frequency. 

RequiresStitchers( ); Declares that the current stitcher starts when the specified stitcher 

has finished. 

540 

540 

540 

542 

542 

541 

535


536 

The following conditions are only applicable to the discovery stitchers. 

Table C4: Discovery-Specific Stitcher Trigger Conditions 


Stitcher Trigger Condition Description See page 

DiscoRequiresAgents( ); Declares that the stitcher starts when the specified discovery 

agent has finished. 

DiscoRequiresLastPhase( ); Declares that the stitcher can only be executed in the last 

discovery cycle phase. 

DiscoRequiresPhase( ); Declares that the stitcher can only be executed on completion of 

the specified discovery cycle phase. 

The stitcher rules are specified within the StitcherRules{} section. They conduct the actual 

processing. Table C5 lists the stitcher rules that can be used in any stitcher. 

Table C5: Generic Stitcher Rules (1 of 2) 

Stitcher Rule Description See Page 

ExecEvalOnRecord( ); Executes an eval statement on a record. 553 

ExecuteOQL( ); Instructs the stitcher to execute an OQL statement. 549 

ExecuteStitcher( ); Executes the specified stitcher. 552 

GetInScopeRecord( ); Returns the record currently in scope. 550 

GetRecordFromScope( ); Returns details of a record in the specified scope. 550 

IsInSubnet( ); Determines whether or not a particular IP address falls within a 

specified subnet based on the netmask. 

MatchPattern( ); Performs string extraction based on regular expressions. 554 

MergeEntities( ); Merges entities into a single record. 553 

Print( ); Prints the specified variables to the standard output. 554 

PrintRecord( ); Prints the record currently in scope to the standard output for 

debugging purposes. 

RetrieveOQL( ); Creates a list of the datatype RecordList generated by an 

OQL query. 

RetrieveSingleOQL( ); Executes an OQL query and retrieves the first record returned. 549 

RetrieveOQLFromService(); Executes an OQL query using the specified service and returns 

the results as a list of the datatype RecordList. 

541 

541 

541 

553 

553 

549 

549 


Table C5: Generic Stitcher Rules (2 of 2) 

Discovery Stitcher-Specific Rules 

Table C6 lists the stitcher rules that can only be used in the discovery stitchers. 

Monitoring Stitcher-Specific Rules 



Stitcher Rule Description See Page 

SendAllOQLToService( ); Sends a series of records to the 'Model' service. 551 

SendOQLToService( ); Instructs the stitcher to send OQL statement(s) to a currently 

active service. 

Table C6: Discovery Specific Stitcher Rules 

Stitcher rule Description See page 

DiscoSendOQLToFinder( ); Instructs the stitcher to send OQL statement(s) to a finder. 557 

DiscoRefresh( ); Instructs the finders to restart their operation, for example, 

when performing a rediscovery. 

IsRecordInFilter( ); Determines whether the record passes the detection or 

instantiation filter. 

DiscoDiscoveryCycleComplete; Notifies the process of the completion of a discovery cycle. 558 

For more information on monitoring stitchers, including the stitcher rules, see the Netcool/Precision IP 


Stitcher Language Programming Constructs 

Table C7 lists the stitcher language programming constructs. 

Table C7: Stitcher Language Programming Constructs 

Stitcher keyword Description See page 

delete Deletes lists created by the RetrieveOQL function. 548 

else Executes statements where the conditional test specified with the if loop is not 

passed. 

for Defines a loop that is repeated a specified number of times. 545 

foreach Performs an action on each member of a list of datatype RecordList. 547 

if Executes statements if a conditional test is passed. 546 

while Defines a loop that repeats while a condition holds true. 546 

546 

550 

557 

558 

537


Stitcher Language Datatypes 

538 

Table C8 lists the stitcher language datatypes that are assigned to variables used within the stitcher rules. 

Table C8: Stitcher Language Datatypes 


float Stores floating point values (monitoring stitchers only). 

int Stores integer values. 

Record Stores a single returned record. 

RecordList Stores lists created by the RetrieveOQL function. 

text Stores string values. 

Stitcher Language Relational Operators 

Table C9 lists the relational operators. 

Table C9: Stitcher Language Relational Operators 

Operator Description 

== Test for equality. 

!= Test for non-equality. 

< Test for less than. 

> Test for greater than. 

= Test for greater than or equal to. 

Comments in Stitchers 

Comments in stitchers are introduced by -- or //, as shown in the following example. If a comment 

requires a carriage return, the characters on the next line must also be commented out. 

-- This is a valid stitcher language comment. 

// This is also a valid stitcher language comment. 


Precedence and Association of Operators 



The rules for precedence and association of operators determine the grouping of operators with operands, 

and indicate the order in which the operators in an expression are executed. For complex expressions, use 

parentheses to avoid ambiguity. Table C10 lists the operators that are used in the stitcher language. 

Table C10: Operators in the Stitcher Language in Order of Decreasing Precedence 

Operator Description Associativity Precedence 

- Negative sign Non-associative 1 (Highest) 

* Multiplication Left 2 

/ Division Left 2 

OR Logical OR Left 3 

AND Logical AND Left 4 

NOT Logical NOT Left 5 

= Equal to Left 6 

Not equal to Left 6 

< Less Left 6 

> Greater than Left 6 

= Greater than or equal to Left 6 

+ Addition Left 7 

- Subtraction Left 7 (Lowest) 

Quotes in the Stitcher Language 

OQL statements embedded within the stitcher language (for example, within the ExecuteOQL(); 

statement) are enclosed in double quotes. If quotes are needed inside the embedded OQL, they must be 

single quotes even if double quotes would normally be used. The following example shows an embedded 

OQL statement that is enclosed in double quotes. The TEXT datatype within the statement is enclosed in 

single quotes: 

ExecuteOQL( 

"select m_Name from finders.returns where m_Creator = 'PingFinder';" 

); 

Elsewhere in the stitcher language, single quotes are generally used, as shown in the following example: 

ExecuteStitcher( 'CreateAndSendTopology' ); 

539


C.4 Stitcher Text File Structure 

540 

All discovery stitchers have a text file associated with them that is located in 

NCHOME/precision/disco/stitchers. The structure of a stitcher text file depends on the type 

of stitcher (that is, compiled, text-based discovery stitcher or text-based monitoring stitcher). 

Compiled Stitchers 

The compiled stitchers are identified as such in the text file with the CompiledStitcher{} statement, 

which encloses the trigger conditions. The full structure of a compiled stitcher is shown below. 

!CompiledStitcher 

{ 

StitcherTrigger 

{ 

List of stitcher trigger conditions 

} 

} 

Text-Based Discovery Stitchers 

Text-based discovery stitchers are identified as text-based with the UserDefinedStitcher{} 

statement. This statement encloses the trigger conditions and the stitcher rules (which carry out the actual 

stitcher processing). 

The full structure of a text-based discovery stitcher is shown below. 

!UserDefinedStitcher 

{ 


{ 

List of stitcher trigger conditions 

} 

StitcherRules 

{ 

List of stitcher rules 

} 

} 

Stitcher Trigger Conditions 

The stitcher trigger conditions specify the conditions that must be met in order for the stitcher to be 

executed. The trigger conditions are defined within the StitcherTrigger{} statement. The available 

stitcher triggers are shown in use below. Although the triggers are shown and discussed individually, it is 

possible to enclose multiple stitcher triggers within the StitcherTrigger{} section, each of which 

must be terminated by a semicolon. 



Stitcher Text File Structure 

The following section describes the stitcher triggers. For information on monitoring stitcher-specific 

triggers, see the Netcool/Precision IP Monitoring and RCA Guide. 

Stitchers Activated When a Specified Discovery Agent Completes Its 

Operation 

The following trigger indicates that the stitcher must start when the specified agent or agents have completed 

their operation. The name of each agent must be enclosed in double quotes. If multiple agents are specified 

the list must be separated by commas. 


{ 

DiscoRequiresAgents( "Discovery_agent" ); 

} 

Stitchers Activated During a Specified Discovery Phase 

The following trigger indicates that the stitcher starts on completion of a specified discovery phase. 


{ 

DiscoRequiresPhase( Integer_indicating_discovery_phase ); 

} 

Stitchers Activated During the Last Discovery Phase 

The following trigger indicates that the stitcher starts during the last discovery phase. No input is required. 


{ 

DiscoRequiresLastPhase(); 

} 

Stitchers Activated When a Specified Stitcher Completes Its Operation 

The following trigger indicates that the stitcher starts when the specified stitcher or stitchers have completed 

their operation. The name of each stitcher must be enclosed in double quotes. If multiple stitchers are 

specified the list must be separated by commas. 


{ 

RequiresStitcher( "Stitcher" ); 

} 

541


542 

Stitchers Activated When Data Is Inserted into a Specified Database Table 

The following trigger specifies that the stitcher starts every time data is inserted into the specified database 

table. 


{ 

ActOnTableInsert( "database_name", "table_name" ); 

} 

On Demand Stitchers 

Stitchers that are to be activated when invoked by the user or another stitcher have an on-demand trigger, 

as shown below. No input is required. 


{ 

ActOnDemand(); 

} 

Stitchers Activated According to a Frequency 

Stitchers that are to be activated according to a frequency (evaluated relative to the time DISCO started) 

have a trigger similar to the following. 


{ 

ActOnTimedTrigger( ( frequency_attribute ) values ( value ); ); 

} 

Table C11 lists the frequency attributes. 

Table C11: Frequency Attributes 

Attribute Description Value passed to attribute 

m_DayOfWeek Specifies that the stitcher is to be 

executed on a certain day every 

week. 

m_DayOfMonth Specifies repeated stitcher 

execution on a specific day of every 

month. 

m_TimeOfDay Specifies execution at a particular 

time every day. 

m_Interval Specifies stitcher execution at a 

given interval. 

Integer representing the day, where Sunday=0 and 

Saturday=6. 

Integer from 1 to 31 representing the day of the month on 

which to execute the stitcher. If you specify 31 and the 

present month only has 28, 29 or 30 days, the timer 

automatically defaults to the last day of the month. 

Integer representing the time of the day in 24 hour format, 

for example, execution at 2 pm every day would be 

indicated by 1400. 

An integer representing the number of hours between 

execution. 



Stitcher Text File Structure 

It is possible to combine either the weekly (m_DayOfWeek) or monthly (m_DayOfMonth) time interval 

options with the time of day (m_TimeOfDay) option to specify exactly when you want the stitcher to 

execute. However, it is not possible to combine any of the configuration options with the m_Interval 

option, which takes precedence over any other attribute. 

Examples of Timed Triggers 

In the following example, the stitcher is configured to execute every 60 hours. 


{ 

ActOnTimedTrigger 

( 

( m_interval ) values ( 60 ); 

); 

} 

In the following example, the stitcher is configured to execute every Monday at 3:15 pm. 


{ 

ActOnTimedTrigger 

( 

( m_DayOfWeek, m_TimeOfDay ) values ( 1, 1515 ); 

); 

} 

Note: A stitcher can only contain one ActOnTimedTrigger trigger, that is, only one trigger activated 

according to a frequency. So, for example, if you wish to set a trigger so that a specific stitcher action is 

performed on two days in a week such as Monday and Thursday, you need to define two stitchers and place 

an ActOnTimedTrigger trigger in each. 

543


C.5 Stitcher Rules 

544 

The following section describes the processing that takes place within the curly braces of the 

StitcherRules{} section of the text-based stitchers. The stitcher rules are separated by spaces. 

Variables Within the Stitcher Rules 

Variables in the stitchers must be declared before they can be used. The declaration is in the following 

format. 

datatype name = initial_value ; 

Variables can be declared anywhere within the StitcherRules{}. Although variables must be assigned 

an initial value, it can be NULL. Once a variable has been declared it can be used throughout the current 

stitcher, but can only accept values of the appropriate datatype. Some examples of variable declaration are 

shown below. 

The following example declares an integer variable called router and assigns to it an initial value of 0. 

int router = 0; 

The following example declares a text variable called router2 and assigns to it the string "upper". 

text router2 = "upper"; 

Once a variable has been created, its value can be updated at any time. It is also possible to assign the result 

of an eval statement or a calculation to a variable. The rules for operator precedence and associativity in 

the Netcool/Precision IP languages are defined in Precedence and Association of Operators on page 539. 

The RecordList and Record Data types 

Variables of the RecordList and Record datatypes are used to store retrieved OQL records in a 

variable. A variable with one of these datatypes is defined, like a text or integer variable, by specifying the 

datatype and variable name and assigning a value to the variable. The results of an OQL query can be 

assigned to the variable using the RetrieveOQL(); rule, which contains an OQL query enclosed in 

double quotes. The RetrieveOQL(); rule is defined in Stitcher Rules: RetrieveOQL() on page 549. 

The following example declares a variable called discoRes, specifies the datatype for the variable as 

RecordList, and assigns the results of a query on the disco.status database table to discoRes. 

RecordList discoRes=RetrieveOQL // Declares discoRes to be a 

( // RecordList variable and 

"select m_DiscoveryMode // assigns the results of the 

from disco.status;" // query to discoRes. 

); 




The Record datatype is used in the same way, but variables of the Record datatype only hold one record. 

The following example shows the Record datatype in use. 

Record newEntity = GetInScopeRecord(); 

The GetInScopeRecord(); stitcher rule is described on Stitcher Rules: GetInScopeRecord() on 

page 550. 

Variable Declaration and Use 

Variables of the Record and RecordList types do not have to be declared on the same line as the 

assignment of the output from stitcher rules like RetrieveOQL();. As long as the variable has previously 

been declared it can be assigned the output from a RetrieveOQL(); rule. The following example is also 

a valid use of the Record datatype. 

Record newEntity = NULL; 

newEntity = GetInScopeRecord(); 

Programming Constructs: Looping within the Stitcher Rules 

The relational operators, listed in Table C9 on page 538, can be used to compare variables and perform 

conditional tests, in conjunction with the stitcher language programming constructs such as for, 

foreach, while and if. These constructs can be nested within each other. 

The for Loop 

The for loop is used to repeat a set of rules a given number of times. The for loop takes the following 

format. 

for( variable_assignment ; conditional_test ; change_to_variable ) 

{ 

List of stitcher rules to execute 

} 

The process flow of the for loop is as follows: 

1. On the first loop, the variable_assignment assigns a value to a previously declared variable. 

2. The conditional_test is evaluated. 

545


546 

3. If the test evaluates true: 

– The stitcher rules within the curly braces are executed. 

– The change_to_variable is performed. 

– The loop returns to step 2. 

4. When the conditional_test evaluates false, the loop terminates. 

An example of a for loop is shown below. This loop repeats until variable1 is no longer less than 

variable2 (variable1 is increased by 1 on each complete loop). 

int variable1 = 0; // 

Declares variable1 as an integer. 

for( variable1 = 0 ; variable1 < variable2 ; variable1 = variable1 + 1 ) 

{ 


} 

The while Loop 

The while loop is used to execute a series of instructions while a specified condition remains true. The 

while loop takes the following format. 

while( conditional_test ) 

{ 


} 

The while loop repeats as long as the conditional test evaluates to true. An example while loop is shown 

below. 

while( count < numberOfLayers ) 

{ 


} 

The above loop repeats as long as the value of the count variable is less than the value of 

numberOfLayers. 

The if Loop 

The if loop performs an action if a particular condition is satisfied. The if loop takes the following format. 

if( conditional_test ) 

{ 

List of stitcher rules to execute if the condition is TRUE 

} 




The list of stitcher rules are executed if the conditional test is satisfied. It is also possible to specify a list of 

stitcher rules to execute if the condition is not satisfied, as shown below. 

if( conditional_test ) 

{ 

List of stitcher rules to execute if the condition is TRUE 

} 

else 

{ 

List of stitcher rules to execute if the condition is FALSE 

} 

An example of the if loop in use is shown below. If myVariable is equal to 1, the first OQL statement 

is executed, otherwise the second OQL statement is executed. 

if( myvariable == 1 ) 

{ 

ExecuteOQL 

( 

"insert into database.table 

( m_Name, 

m_BaseName ) 

values 

( "Agent", 

"BaseName" );" 

); 

} 

else 

{ 

ExecuteOQL 

( 

"insert into another.table 

( m_Name, 

m_BaseName ) 

values 

( "Agent", 

"BaseName" );" 

); 

} 

The foreach Loop 

The foreach loop performs an action on every record stored in a variable of type RecordList. The 

foreach loop has the following syntax. 

foreach( variable of type RecordList ) 

{ 


} 

547


548 

The following example shows how the foreach loop repeats the list of stitcher rules for every record in 

the list. 

foreach( remoteNames ) 

{ 

ExecuteOQL 

( 

"insert into CDPLayer.entityByNeighbor 

( 

m_Name, m_NbrName, m_NbrType 

) 

values 

( 

eval(text, '&m_LocalName'), 

eval(text, '&m_Name'), 

eval(int, '$RemoteNeighbor') 

);" 

); 

} 

The example assumes that a variable called remoteNames has already been defined and a list of OQL 

records has been assigned to it. The foreach loop executes the specified OQL insert for every record in 

the list, extracting the values to insert from the records using eval statements. 

Stitcher Rules: Delete() 

The delete rule removes lists and records that have been created and are no longer needed. The syntax is 

shown below. 

delete( variable of type Record or RecordList ); 

It is good practice to delete lists after they are no longer needed, as this releases memory. 

Some examples are shown below. 

delete( notIpSwitchNbrs ); 

delete( ethernetSwitches ); 


Stitcher Rules: ExecuteOQL() 



The ExecuteOQL(); rule executes an OQL statement on the databases of the current service (that is, 

the DISCO databases for the discovery stitchers). The OQL statement is enclosed in brackets and 

surrounded by double quotes. 

ExecuteOQL( "Any valid OQL statement" ); 

The following example shows how the ExecuteOQL() rule is used to delete all the records in the 

finders.pending table. 

ExecuteOQL( "delete * from finders.pending;" ); 

Stitcher Rules: RetrieveOQL() 

The RetrieveOQL(); rule executes an OQL query on the databases of the current service (that is, the 

DISCO databases for the discovery stitchers). The results can be assigned to a variable of the type 

RecordList. 

RetrieveOQL( "Any valid OQL query" ); 

The following example shows the results of a query on the finders.returns table being assigned to a 

previously declared variable of datatype RecordList called devicesFound. 

devicesFound = RetrieveOQL( "select m_Name from finders.returns;" ); 

Stitcher Rules: RetrieveSingleOQL() 

RetrieveSingleOQL(); rule is a version of the RetrieveOQL(); rule that returns only the first 

result of the OQL query, regardless of how many records are returned. The result can be assigned to a 

variable of the Record datatype. 

RetrieveSingleOQL( "Any valid OQL query" ); 

Stitcher Rules: RetrieveOQLFromService() 

The RetrieveOQLFromService(); rule executes an OQL query on the databases of the specified 

service. The results can be assigned to a variable of the type RecordList. 

RetrieveOQLFromService( "Any valid OQL query", "OQL service name" ); 

The following example shows the results of a query on the model.config table from the service Model 

being assigned to a previously declared variable of datatype RecordList called configData. 

configData = RetrieveOQLFromService( 

"select * from model.config;", 

549


550 

"Model" 

); 

Stitcher Rules: GetInScopeRecord() 

The GetInScopeRecord(); rule retrieves the record currently in scope. The rule requires no input. 

The results are to be assigned to a variable of type Record. 

GetInScopeRecord(); 

Stitcher Rules: GetRecordFromScope() 

The GetRecordFromScope(); rule retrieves a record from the specified scope (for example, for use 

when nested within a foreach loop). The rule requires an integer that indicates the scope from which to 

retrieve the record, where 0 indicates the current scope, 1 indicates the scope one level of nesting away, and 

so on. 

The results must be assigned to a variable of type Record. 

GetRecordFromScope 

( 

integer indicating the scope from which to retrieve the record 

); 

Stitcher Rules: SendOQLtoService() 

The SendOQLToService(); rule executes an OQL statement on the databases of the specified service. 

The syntax of the rule is as follows. 

SendOQLToService( "OQL service name" , "Any valid OQL statement" ); 

The following example shows how the rule is used to perform an insert into the EXEC actions.inTray 

table. 

SendOQLToService( 

"Exec", 

"insert into actions.inTray 

( ActionId, Path, RunCount ) 

values 

( 1234, "/usr/sbin/ping", 5 );" 

); 


Stitcher Rules: SendAllOQLToService() 



The SendAllOQLToService(); rule sends all the records in a variable of type RecordList to the 

'Model' service. The syntax of the rule is as follows. 

SendAllOQLToService( 

"OQL service name" , 

variable of type RecordList, 

"Any valid OQL insert statement", 

"stitcher to be invoked to test each record" 

); 

The SendAllOQLToService(); rule is used to send the topology to MODEL. In the following 

example, impactData is a variable of type RecordList that contains a series of records. The data from 

these records is extracted using eval statements, and the InstantiationFilter.stch stitcher is 

invoked for each record to determine whether the entity is to be instantiated to an AOC. 

SendAllOQLToService( 

"Model", // Send OQL to this 

service 

impactData, // Send the records 

from this variable 

"insert into master.entityByName 

( ObjectId, EntityName, Address, Description, EntityType, 

EntityOID, ExtraInfo, RelatedTo, Contains, 

UpwardConnections, ActionType, IsActive, ClassName ) 

values 

( 0, eval(text, '&m_Name'), eval(list type text, '&m_Addresses'), 

eval(text, '&m_Description'), eval(int, '&m_Type'), 

eval(text, '&m_ObjectId'), eval(object type vbList, '&m_ExtraInfo'), 

eval(list type text, '&m_RelatedTo'), 

eval(list type text, '&m_Contains'), 

eval(list type text, '&m_UpwardConnections'), 0, 1, NULL );", 

"InstantiationFilter" // 

Invoke this stitcher for each record 

); 

551


Stitcher Rules: ExecuteStitcher() 

552 

The ExecuteStitcher(); function executes the specified stitcher. Once the invoked stitcher has 

completed, control is passed back to the original stitcher and the remaining stitcher rules are executed in 

sequence. The syntax of the ExecuteStitcher() function is given below. 

ExecuteStitcher( 'Stitcher' ); 

An optional comma-separated list of variables to be passed to the stitcher can also be specified after the 

stitcher name. 

The following example executes the ProcessAffectedRemoteSwitches.stch stitcher without 

passing any arguments. 

ExecuteStitcher( 'ProcessAffectedRemoteSwitches' ); 

The following example executes the SwitchFdbToConnections.stch stitcher and passes two 

variables to the stitcher. 

ExecuteStitcher( 'SwitchFdbToConnections' , 'agent1' , 'agent2' ); 

Extracting Variables Passed to a Stitcher 

The stitcher invoked using the ExecuteStitcher(); rule can extract the variables that have been 

passed to it by evaluating the special variable ARG_N using an eval statement, where N is the number of 

the variable (for example, ARG_1 represents the first variable passed to the stitcher, ARG_2 represents the 

second variable, and so on). 


Stitcher Rules: ExecEvalOnRecord() 



The ExecEvalOnRecord(); rule executes the supplied eval statement on the named record. The 

output can be assigned to a variable of the appropriate type. 

ExecEvalOnRecord( Record_variable , eval statement ); 

The following example shows how a text variable called name being assigned the evaluation of the 

EntityName field of the currentRec variable. 

text name=ExecEvalOnRec( currentRec , eval(text, '&EntityName' ); 

Stitcher Rules: IsInSubnet() 

The IsInSubnet(); rule determines whether a specified IP address is in a given subnet, based on the 

subnet mask. 

IsInSubnet( IP_address , subnet , subnet_mask ); 

The rule returns an integer where 0 indicates that the IP address is not in the subnet and 1 indicates that the 

IP address is in the subnet. 

Stitcher Rules: MergeEntities() 

The MergeEntities(); rule merges two variables of type Record. 

MergeEntities( 

new_record , old_record , integer_indicating_precedence 

); 

The output of the rule can be assigned to a variable of type Record. The integer indicates precedence, 

where 1 indicates that the new record take precedence over the old record, and 0 indicates that the old record 

takes precedence. 

Stitcher Rules: PrintRecord() 

The stitcher language allows information to be printed to the standard output (for example, for debugging 

purposes). The PrintRecord(); stitcher rule prints the entire record currently in scope. 

No input is required for the PrintRecord rule, it needs to be issued within the scope of the record to be 

printed, as shown by the example below. In this example, PrintRecord() is used to print the records 

within a variable of datatype RecordList called snmpResults. 

foreach( snmpResults ) 

{ 

553


554 

PrintRecord(); 

Stitcher Rules: Print() 

} 

The Print() rule also sends information to the standard output, but differs from PrintRecord() in 

that the information to be printed must be specified. Two comma separated arguments must be specified 

within the brackets of Print(). The arguments can be any of the following: a quoted string (which may 

be empty), an unquoted string (which may be a symbol definition name or may be NULL), an integer, or 

an eval statement. 

An example of the Print() rule that prints the current time to the standard output is shown below. 

Print ( "CPU time:", eval (text, "$TIME") ); 

Stitcher Rules: MatchPattern() 

The MatchPattern() rule performs string extraction based on regular expressions. The rule determines 

how many times a regular expression pattern was found in a target string. The rule also enables you to create 

variables based on subpatterns found in the target string. The syntax of the MatchPattern() rule is as 

follows: 

MatchPattern( target_string,pattern_string ); 

Both the target string and pattern string can be any of the following: 

Defined string 

Variable 

eval statement 

The following examples show some possible forms of the MatchPattern() rule. 

Both the target string and the pattern string are defined strings: The following example returns the 

value 3 as the pattern was matched three times. 

int count=MatchPattern( "Hello Hello Hello","Hello" ); 

Both the target string and the pattern string are variables: The following example also returns the 

value 3. 

text target="Hello Hello Hello"; 

text pattern="Hello"; 

int count=MatchPattern( target,pattern ); 


Use of an eval statement: 

text target="Hello Hello Hello"; 

int count=MatchPattern( target,eval(text, "$pattern") ); 

String Extraction 



The MatchPattern() rule can also extract text from the target string by creating variables based on 

subpatterns found in the target string. These variables take the name REGEXN, where N is a number which 

identifies the variable. 

The following example shows how variables are assigned. 

[1] text target="Testing Testing One 2 Three"; 

[2] text pattern= 

"([^[:space:]]+)[[:space:]]+([^[:space:]]+)[[:space:]]+([^[:space:]]+)[[:space:]] 

+([[:digit:]]+)[[:space:]]+([^[:space:]]+).*"; 

[3] int count=MatchPattern( target,pattern ); 

[4] while( count > 0 ) 

[5] { 

[6] Print("Count ", count); 

[7] Print("Match ", REGEX0); 

[8] Print("SubMatch1 ", REGEX1); 





[13] 

[14] count = count - 1; 

[15] } 

The round brackets in the pattern string defined in line 2 identify a subpattern to be extracted and placed 

within a REGEX variable. In this example there is one match only; hence there is one variable (REGEX0), 

which matches the full pattern, and five submatches, (REGEX1 to REGEX5), set as follows: 

Table C12: Extraction of Variables Based on Subpatterns 

Variable Value Type 

REGEX0 Testing Testing One 2 Three Match 

REGEX1 Testing Submatch 

REGEX2 Testing Submatch 

REGEX3 One Submatch 

REGEX4 2 Submatch 

REGEX5 Three Submatch 

555


556 

If there is more than one match, then more REGEX variables are created. For example, if there were three 

matches, then 18 REGEX variables would be created. In this case, the variables REGEX0, REGEX6, and 

REGEX12 would correspond to the full matching pattern, while variables REGEX1-5, REGEX7-11, and 

REGEX13-18 would correspond to the subpatterns within each full match. 

Note: If you run the MatchPattern() rule a second time, then it overwrites previous values held in the 

REGEX variables. It is recommended that you store any extracted data prior to running the 

MatchPattern() rule a second time. 

Psuedowire Example 

This section provides a more realistic example based on data received from an MPLS stitcher. Assume that 

the following psuedowire data string is retrieved from the stitcher: 

Layer-2 VPN Statistics: 

Instance: vpls1 

Local interface: fe-1/3/0.0, Index: 71 

Multicast packets: 375747 

Multicast bytes : 34780885 

Flooded packets : 96012 

Flooded bytes : 9213657 

Local interface: vt-1/2/0.32768, Index: 72 

Remote PE: 10.1.230.4 





Instance: vpls1 

Local interface: fe-1/3/0.0, Index: 71 





Local interface: vt-1/2/0.32768, Index: 72 

Remote PE: 10.1.230.4 






You can extract the data from this string by writing a stitcher which incorporates code with the 

MatchPattern() rule, as follows: 



[1] text pattern= 

"Instance:[[:space:]]+([^[:space:]]+)[[:space:]]*[\n\r][[:space:]]* 

[\n\r][[:space:]]*Localinterface:[[:space:]]+([^,]+),[[:space:]]+Index: 

[[:space:]]+([[:digit:]]+)[[:space:]]*[\n\r][[:space:]]*Multicast packets 

[[:space:]]*:[[:space:]]+[[:digit:]]+[[:space:]]*[\n\r][[:space:]]*Multicast 

bytes[[:space:]]*:[[:space:]]+[[:digit:]]+[[:space:]]*[\n\r][[:space:]]*Flooded 

packets[[:space:]]*:[[:space:]]+[[:digit:]]+[[:space:]]*[\n\r][[:space:]]*Flooded 

bytes[[:space:]]*:[[:space:]]+[[:digit:]]+[[:space:]]*[\n\r][[:space:]]*[\n\r][[: 

space:]]*Local interface:[[:space:]]+([^,]+),[[:space:]]+Index:[[:space:]]+ 

([[:digit:]]+)[[:space:]]*[\n\r][[:space:]]*Remote PE:[[:space:]]+([^ \t\n\r]+) 

[[:space:]]*[\n\r].*"; 

[2] int count = MatchPattern( eval ( text,$target ), pattern); 

[3] while(count > 0) 

[4] { 

[5] Print("Count ", count); 

[6] Print("Match ", REGEX0); 

[7] Print("SubMatch 1 ", REGEX1); 






[13] 

[14] count = count - 1; 

[15] } 

In line 2 of this example, $target is the psuedowire data string received from the MPLS stitcher. 

Discovery-specific Stitcher Rules: DiscoSendOQLToFinder() 

Stitchers can send OQL strings directly to any of the finders using the DiscoSendOQLToFinder(); 

rule. This rule sends OQL requests over a TCP socket connection instead of the Rendezvous Bus. 

DiscoSendOQLToFinder( "Finder", "OQL_statement" ); 

Discovery-specific Stitcher Rules: DiscoRefresh() 

The DiscoRefresh(); rule resets the finders and clears the Helper Server tables. It can be passed 

information indicating the areas to refresh. 

DiscoRefresh( "Finder_or_Helper" ); 

The following examples show the various forms of the DiscoRefresh(); rule. 

DiscoRefresh( "PingFinder" ); // Refresh the Ping finder. 

DiscoRefresh( "PingFinder", "1.2.3.0", "255.255.255.0" ); // Refresh the Ping finder 

557


558 

// rule for the subnet 1.2.3.0 (causing the subnet to be pinged again). 

DiscoRefresh( "TrapFinder" ); // Refresh the Trap finder. 

DiscoRefresh( "SnifferFinder" ); // Refresh the Sniffer finder. 

DiscoRefresh( "FileFinder" ); // Refresh the File finder. 

DiscoRefresh( "Helper", "SnmpHelper", "m_HostIp", "1.2.3.4" ); 

// Refresh all records in the SNMP Helper SNMP store where m_HostIp="1.2.3.4". 

Discovery-specific Stitcher Rules: IsRecordInFilter() 

The IsRecordInFilter(); rule is used by the DetectionFilter.stch and 

InstantiationFilter.stch stitchers to determine whether the current record passes the filter 

condition. The rule returns an integer, where 1 indicates that the record passes the filter and 0 indicates that 

the record does not pass the filter. 

IsRecordInFilter( "Filter_condition" , variable_of_Record_datatype ); 

In the DetectionFilter.stch and InstantiationFilter.stch stitchers, the filter 

condition is extracted from the DISCO scope database using an eval statement. 

Discovery-specific Stitcher Rules: DiscoDiscoveryCycleComplete 

The DiscoDiscoveryCycleComplete; rule notifies the DISCO process that the discovery cycle is 

complete. The rule takes no arguments. 

DiscoDiscoveryCycleComplete; 


Discovery_GuideIX.fm August 16, 2006 4:06 pm 

Index 

Symbols 

$NCHOME, see NCHOME 

%NCHOME%, see NCHOME 

A 

Active Object Classes, see AOCs 

AND (OQL) 482 

AOCs 

application extensions 412 

architecture of 409 

backing up 409 

data dictionary 411 

editing 369 

instantiate rule 411 

instantiation 402 

introduction to 400 

menu methods 414 

multiple inheritance 402 

overview of components 410 

structure of 410–414 

super class 411 

syntax of 410 

visual icon 414 

architecture, Precision Server 12 

ARP helper 

configuring 289 

database 289 

AUTH 

command line attributes 73 

database 82 


prerequisites 73 

starting 73 

Netcool/Precision IP 3.6 Discovery Configuration Guide 559 

B 

blackout state 35 

broadcast pinging 222 

C 

CLASS 

see also AOCs 

command line options 403 

database 405 



starting up 403 

communication, between processes 15, 321 

components 

binary names 56 

dependencies 56 

service names 171 

CONFIG 


starting 162 

configuration files 

CTRL 49 

definition 18 

DISCO 23 

discovery agents 272 

domain-specific 18 

finders 220 

helpers 286 

TrapMux 418 

configuring advanced discovery parameters 133 

configuring DNS helpers 127 

configuring Network Address Translation 130 

containment model 

altering 362 

generating 362 

Index

Index 


logical containment 360 

physical containment 359 

re-instantiating 368 

VLAN trunking 361 

VLANs 360 

Context agent 

enabling 33 

within the discovery process 28 

core components 

and the Precision Server 12 

core view of MPLS network 327 

CTRL 


configuration files 49 

database 64 

dynamic configuration changes 63 


managed processes 49, 56 


querying databases of 60 

setting up domains 49 

starting 59 

terminating services 62 

unmanaged processes 49, 57 

D 

daemons (Helper System) 287 

data dictionary 411 

databases 

see also OQL 

agents 424, 448 

ARP helper 289 

CLASS 405 

CTRL 64 

Details agent 457 

DISCO configuration 424, 431 

discovery scope 424, 442 

DNS helper 309 

failover 426 

finders 425, 454 

MODEL 372 

querying, see OQL Service Provider 

rediscovery 425, 475 

restoring using STORE 380 

SNMP helper 299 

stitchers 424, 450 

STORE 381 

Telnet helper 305 

topology 425, 470 

tracking discovery 425, 460 

TrapMux 419 

dependencies, component 56 

devices, removing from the network 45 

DISCO 


components of 23 

configuration databases 431 

configuration files 23, 181 


starting 178 

discovery 

see also finders , tracking the discovery , stitchers 

blackout state 35 

completion criteria 205 

configuration methods 86 

configuration using Network Discovery GUI 96 




context-sensitive 

enabling 33 

process flow 28 

creating the topology, process flow of 31 

data collection stage 35 

data processing stage 37 

defining exceptions to 34 

discovering associated device addresses, process 

flow of 29 

discovering device connectivity, process flow of 30 

discovering device details, process flow of 27 

discovering device existence, process flow of 26 

enabling discovery agents 119 

560 Netcool/Precision IP 3.6 Discovery Configuration Guide

multiphasing 38 

overview 25–33 

phases 35 

rediscovery 40 

restricting 34 

seeding 100 

seeding File finder 103 

seeding Ping finder 100 

seeding Sniffer finder 106 

seeding Trap finder 109 

setting discovery filters 120 

setting SNMP access 111 

setting Telnet access 114 

stages 35 

starting 190 

discovery agents 

activating 184 

agentTemplate database 241 

Associated Address agent 240 

ATM 252 

CDP 259 

configuring MPLS agents 329 

Context agents 261 

database template 241 

deactivating 186 

Details agent 240 

disabling 266 

discovering SPVCs 284 

enabling 265 

ethernet switches 243 

extra information 278 

FDDI 259 

filtering devices 272 

IP layer agents 267 

layer 2 269 

layer 3 249, 269 

MPLS 254 

MPLS scoping requirements 333 

MPLS telnet configuration 331, 332 

NAT 256 

networking layer 249 

partial matching 276 

protocol-specific 271 

selecting 267 

specialized agents 268 

standard agents 267 

task-specific 261 

triggers 32 

types 242 

discovery configuration 

Helper Server 186 

Ping finder 183 

scoping 183 

SNMP passwords 187 

task list 181 

telnet passwords 188 

Discovery Configuration tab 87 

discovery cycle 25 

discovery scope 

databases 442 

defining a single inclusion zone 98, 209 

defining exclusion zones 211 

defining multiple inclusion zones 210 

defining NAT zones 211 

defining using Network Discovery GUI 97 

devices with out of scope interfaces 218 

editing existing inclusion zone 100 

reasons for restricting 208 

restricting instantiation 214 

restricting interrogation 212 

sensitive devices 208 

specific devices 212 

types of scoping 208 

Discovery Status tab 91 

DNS helper 


database 290 

domains 

domain-specific configuration files 18 


multiple 50 

multiple domains on Windows 54 

single 49 


Index

Index 

E 

single domain on Windows 52 

edge view of MPLS network 327 


eval statement 509 

advanced use 513 

concatenating lists 514 

containment model, evaluating 515 

deleting data from a list 514 

keywords 513 

performing a lookup 515 

quotation marks 511 

syntax 510 

Extreme devices, discovering 271 

F 

failover 

database 426 

enabling 426 

File finder 


database 228 

parse rules 229 

parsing files 229 

verifying device existence 232 

finders 



forcing rediscovery 44 

full discovery 

overview 138 

running 139 

full rediscovery 

running 139 

H 

Helper manager, see Helper System 

Helper Server, see Helper System 

Helper System 

command line 288 

configuration file 287 


connecting to different subnets 319 

daemons 287 

databases 307 

dynamic timeouts 287 

Helper manager 287 


operation 287 

starting 288 

static timeout 287 

telnet access 303 

helpers, see Helper System 

562 Netcool/Precision IP 3.6 Discovery Configuration Guide 

I 

instantiate rule 411 

instantiation 13, 402 

L 

label-switched path, see LSP 

layer 2 VPNs 328 

LSP-based MPLS discovery 330 

M 

message bus 14 

methods for MPLS discovery 330 

minimum discovery configuration requirements 97 

MODEL 


databases 372 



querying databases 363 

starting 357 

MONITOR Configuration tool 400

MPLS discovery 


configuring stitchers 335 

core view 327 

edge view 327 

LSP 330 

methods 330 

overview 254, 326 

psuedowires 328 

route target 330 

scoping requirements 333 

Telnet agents configuration 331, 332 

multicast 

changing the address 17, 323 

communication 15, 321 

pinging 222 

multiphasing 38 

multiple inheritance 402 

N 

NAT, see Network Address Translation 

NCHOME 10, 23, 52, 72, 180, 220, 287, 335, 346, 358 

ncp_auth, see AUTH 

ncp_class, see CLASS 

ncp_config, see CONFIG 

ncp_ctrl, see CTRL 

ncp_d_helpserv, see Helper Server 

ncp_df_file, see File finder 

ncp_df_ping, see Ping finder 

ncp_df_ping, see Ping finder 

ncp_df_sniffer, see Sniffer finder 

ncp_df_trap, see Trap finder 

ncp_dh_arp, see ARP helper 

ncp_dh_dns, see DNS helper 

ncp_dh_snmp, see SNMP helper 

ncp_dh_telnet, see Telnet helper 

ncp_disco, see DISCO 

ncp_discoconfig, see Discovery Configuration Tool 

ncp_install_services 51 

ncp_model, see MODEL 

ncp_monitorconfig, see MONITOR Configuration Tool 

ncp_oql, see OQL Service Provider 

ncp_store, see STORE 

ncp_trapmux, see TrapMux 

ncp_userconfig, see User Configuration Tool 

Netcool GUI Foundation 

and the Network Discovery GUI 86 

and the OQL Workbench 167 

definition 86 

Netcool Suite home directory, see NCHOME 

Netcool/Precision IP 

core components 12 

Network Address Translation 

configuring discovery 346 

configuring trap handling 347 

containment model 352 

defining address spaces 346 

discovery process flow 344 

discovery restrictions 343 

dynamic 342 

enabling translation 346 

overview 342 

selecting agents 348 

static 342 

viewing NAT environments 353 

Network Discovery GUI 

access using Precision Admin page 87 

accessing 86 

and the Netcool GUI Foundation 86 




data input buttons 90 

defining discovery scope 97 

description of user interface 89 

Discovery Configuration toolbar 88 


limitations for context-sensitive discovery 33 

minimum requirements for discovery 97 


Index

Index 

online help 88 

overview 86 


running a full discovery 139 

running a full rediscovery 139 

running a partial rediscovery 140 

seeding a discovery 100 






setting SNMP access 111, 114 

Status and Control toolbar 91 

wizard 86, 143–161 

NGF, see Netcool GUI Foundation 

NOT NULL (OQL) 487 

O 

object modelling 400 

objects and varbinds 486 

online help for Network Discovery GUI 88 

operators (OQL) 481 

OQL 

AND 482 

column constraints 487 

comparison operators 495 

conditional tests 495 

counter 487 

creating a database or table 485 

datatypes 485 

default values 487 

deleting a database or table 508 

deleting a record 507 

general rules 480 

inserting data into a table 490 


list and object datatypes 491 

logical operators 482 

NOT NULL 487 

objects and varbinds 486 

operators, list of 481 

OR 482 

PRIMARY KEY 487 

punctuation 481 


selecting data from a table 493 

selecting data into another table 501 

showing the databases 505 

SQL, key differences 480 

subqueries 498 

timestamp 488 

unique 487 

updating a record 503 

OQL Service Provider 

command line history 172 


listing databases 173 

running a query from the command line 172 


starting 169 

OQL Workbench 

accessing 167 

and the Netcool GUI Foundation 167 

OQL Workbench tab 167 

OR (OQL) 482 


P 

partial discovery 

overview 138 

partial matching 276 

partial rediscovery 

running 140 

permissions 

user profile 81 

Ping finder 

broadcast pinging 222 


database 221, 227 

multicast pinging 222 

scoping 224

seeding 222 

status 192 

Ping helper 


database 291 

Precision Admin page 

access to MySQL database settings 87 

access to Network Discovery GUI 87 

access to OQL Workbench 87, 167 

Discovery Configuration tab 87 

Discovery Status tab 91 

OQL Workbench tab 167 

precompiled stitchers 518 

PRIMARY KEY (OQL) 487 

process controller, see CTRL 

psuedowires 328 

Q 

quotation marks 

eval statements 511 

OQL 480 

stitcher language 539 

R 


databases 475 

forcing rediscoveries of particular devices 44 

full 40 

overview 138 

partial 40 

with the Network Discovery GUI 138 

route target-based MPLS discovery 330 

running a full discovery 139 

running a full rediscovery 139 

running a partial rediscovery 140 

S 

scope 

see also Ping finder 509 


seeding discovery 100 






Services 

Windows services run as specific user 52 

services, terminating 62 


setting SNMP access 111, 114 

Sniffer finder 


database 234 

SNMP 

daemons (Helper System) 287 

versioning 302 

SNMP helper 

community string and device access 

configuration 298 


database 292 

SPVCs, discovering 284 

SQL, and OQL 480 

stitcher language 

comments 538 

compiled stitchers 540 

datatypes 538 

for loop 545 

foreach loop 547 

if loop 546 


operator association 539 

operator precedence 539 

programming constructs 537 


relational operators 538 

stitcher triggers 535 


Index

Index 

text-based discovery stitchers 540 

trigger conditions 540 

variable declaration 545 

variables 544 

while loop 546 

stitchers 

list of default discovery 521 

rules 536 

structure of 519 

triggers 32, 519 

STORE 


configuring for event traffic 395 

configuring for topology traffic 392 

databases 381 



restoring databases using 380 

starting 379 

super class 411 

T 

Telnet helper 


databases 293 

password configuration 305 

terminating services 62 

TIB/Rendezvous 14 

topology 

creation, process flow of 31 

databases 372, 470 

prerequisites for accessing 363 

tracking the discovery 

completion 205 

databases 460 

devices found by Details agent 196 

devices found by finders 195 

NAT status 193 

Ping finder status 192 

specific devices 202 

status 192 

stitchers 194 

which agents are enabled 193 

Trap finder 

database 236 

description of 236 

trap descriptions 236 

TrapMux 



database 419 


replaying traps 422 

starting 417 

traps 

description of 236 

forwarding 416 

multiplexing 416 

replaying 422 


U 

User Configuration Tool 


starting 74 

user management 70 

with the Netcool GUI Foundation 70 

user profiles 

creating and editing 78 

default 72 


permissions 81 

users 

AUTH and 70 

authentication 70 

configuring permissions 71 

creating 71 

creating and editing 75 

default 72 


profiles 71

V 

VLANs 

naming convention 360 

trunking 361 

W 

Windows 

configuring domains 51 

handling processes as services 51 

overview 20 

running services as a specific user 52 

setting up a single domain 52 

setting up multiple domains 54 

wizard-based network discovery 86, 143–161 


Index

Index 

568 Netcool/Precision IP 3.6 Discovery Configuration Guide

ackmatter.fm August 16, 2006 

Contact Information 

Corporate 

Region Address Telephone Fax World Wide Web 

USA Micromuse Inc. (HQ) 

650 Townsend Street 

San Francisco 

CA 94103 

USA 

Europe Micromuse Ltd. 

Disraeli House 

90 Putney Bridge Road 

London SW18 1DA 

United Kingdom 

Asia-Pacific Micromuse Ltd. 

Level 25 

77 St Georges Terrace 

Perth WA 6000 

Australia 

Technical Support 

1-800-Netcool (638 2665) 

+1 415 568 9800 

Region Telephone Fax 

USA 1-800-Netcool (800 638 2665) 

+1 415 568 9800 (San Francisco) 

+1 415 568 9801 http://www.micromuse.com 

+44 (0) 20 8875 9500 +44 (0) 20 8875 9995 http://www.micromuse.co.uk 

+61 (0) 8 9213 3400 +61 (0) 8 9325 5030 http://www.micromuse.com.au 

+1 415 568 9801 

Europe +44 (0) 20 8877 0073 (London, UK) +44 (0) 20 8875 0991 

Asia-Pacific +61 (0) 8 9213 3470 (Perth, Australia) 

Online 

+10 800 852 1012 (North China) 

+10 800 152 1012 (South China) 

+61 (0) 8 9486 1116 

Team E-Mail World Wide Web 

Licensing Temporary Licenses: temp.licensing@micromuse.com 

Permanent Licenses: perm.licensing@micromuse.com 

support.micromuse.com/helpdesk/licenses 

Support support@micromuse.com support.micromuse.com 


Contact Information 

570

Netcool/Precision IP Discovery Configuration Guide 3.6

You also want an ePaper? Increase the reach of your titles

Delete template?

Save as template?