Configuring the DLA

The Discovery Library Adapter (DLA) requires a configuration properties file in order to determine the data source to connect to, the domain to query, the target directory for Discovery Library books and logging parameters.

1. Go to $NMGUI_HOME/adapters/ncp_dla and copy the ncp_dla.properties file to a domain-specific version by appending the name of the file with the domain name, for example, ncp_dla.properties.NCOMS.
2. Specify the Network Manager domain name by assigning a value to the ncp.dla.precisionDomain property.
   The default domain name is NCOMS.
3. Optional: To enable cross-domain inventory for the DLA, configure the following properties.

   Set this property to true:

   ncp.dla.crossDomains=true

   Add one or more domains in a comma-separated list:

   
   ncp.dla.crossDomains=Domain1,Domain2

   Note: You need to enable cross-domain discovery and run at least two cross-domain discoveries in order to get cross-domain inventory information.
4. Optional: You can set the path to a temporary directory the DLA should use while generating the output if you do not want it to use the operating system's default temporary directory. Use the ncp.dla.scratchDirectory parameter to set the full path to a temporary directory, for example ncp.dla.scratchDirectory=/opt/space/temp. The DLA attempts to create this directory if it does not exist.
5. Set the CDM objects you want to have data generated for. Use the ncp.dla.generationFilter parameter to specify the values in a comma-separated list. The possible values are as follows:
   • ComputerSystem - generates the following data for devices:
     • ComputerSystem
     • SnmpSystemGroup
     • OperatingSystem
     • IpInterface for IpDevice, devices with no SNMP access
     • Router
     • Bridge
   • LTE - generates the following data for LTE classes:
     • Function
     • HomogeneousCollection
     • Zone
     • Card
     • NetworkInterface
   • Networking - generates the following data for networks:
     • L2Interface
     • IpInterface
     • IpV4Address
     • IpV6Address
     • IpNetwork
   • Physical - generates the following data for physical classes:
     • PowerSupply
     • Fan
     • Chassis
     • Sensor
     • PhysicalPackage
     • Card
     • Daughter Card

   To generate data you must add a value using the following format to the ncp.dla.generationFilter parameter:

   ncp_dla.generationFilter=ComputerSystem[,data]

   Where data is one of the specific types of data listed in this step.

   Examples:

   • To generate system data, add the following values to the parameter:

     ncp_dla.generationFilter=ComputerSystem

     Note: At a minimum, you must specify this value. If you do not specify any values in the ncp.dla.generationFilter parameter, then the DLA will not generate any data.
   • To generate system and LTE data, add the following values to the parameter:

     ncp_dla.generationFilter=ComputerSystem,LTE

   • To generate system and network connectivity-related data, add the following values to the parameter:

     ncp_dla.generationFilter=ComputerSystem,Networking

6. Optional: You can define the URL to use for the contextual launching into other systems. Set the ncp.dla.contextualLaunchURL parameter to the topology value you want to launch into, and specify the host name and port for the Topoviz topology server. The default is to launch into the Hop View.
   For example, to set up the contextual launch into the Structure Browser:

   ncp.dla.contextualLaunchURL=https://hostname:16316/ibm/console/ncp_structureview/Launch.do?entityId=

7. Optional: If you change the value of the ncp.dla.datasource.autoConnect to false, specify the RDBMS access details by editing the following parameters that define the database that the DLA connects to for generating Discovery Library books:

   ncp.dla.datasource.type

   Specify the RDBMS type, the default is Db2®:

   • Db2
   • Oracle

   ncp.dla.datasource.driver

   Specify the JDBC driver to use:

   • com.ibm.db2.jcc.Db2Driver
   • oracle.jdbc.driver.OracleDriver

   ncp.dla.datasource.url

   Specify the JDBC URL for connecting to the NCIM database:

   • jdbc:db2://host_name:port_number/database_name
   • jdbc:oracle:thin:@//host_name:port_number/service_name where service_name is the Oracle service name that refers to the Oracle database instance running on the server.

   ncp.dla.datasource.schema

   The NCIM database schema name, typically ncim

   ncp.dla.datasource.ncpgui.schema

   The NCPGUI database schema name, typically ncpgui

   ncp.dla.datasource.username

   The database username, typically ncim

   ncp.dla.datasource.password

   The database user password

   ncp.dla.datasource.encrypted

   Whether the database password is encrypted [true|false]

   If set to true, you must specify a valid value for ncp.dla.datasource.keyFile, and you must use the encrypted password referenced in your $NMGUI_HOME/profile/etc/tnm/tnm.properties file.

   ncp.dla.datasource.keyFile

   Specify the full path and name of the cryptographic key file that is used in the $NMGUI_HOME/profile/etc/tnm/tnm.properties file.

   ncp.dla.datasource.loginTimeout

   The login timeout, default 5 seconds

8. Use the ncp.dla.refresh.book parameter to specify whether the DLA should refresh existing Discovery Library books or create new ones. The default option is false; this default option creates new instances.

   ncp.dla.refresh.book=false

9. Use the ncp.dla.lte.topology parameter to export LTE control and user plane topology. This option can produce very large amounts of data for large networks. The volume of data generated might have an adverse affect on your TADDM deployment.. The default option is false.

   ncp.dla.lte.topology=false

10. Optional: You can limit the scope of data collection to one or more network views by setting the ncp.dla.network.view parameter to filter the data of selected network views only.
    Using standard SQL operators, define an SQL segment that is appended to the networkView.name field during the DLA query. The parameter must have a value starting with one of the following SQL operators:

    • =
    • <>
    • !=
    • IN
    • NOT IN
    • LIKE
    • NOT LIKE

    For example, the following defines the scope to use only the BGP Networks network view for the scope of the data collection:

    ncp.dla.network.view=='BGP Networks'

    Note: The DLA does not support double quotation marks. Everything after the initial equal sign in the previous example is part of the value defined, even the second equal (=) sign.

    Another example is the following where the scope for the data collection is defined as any network view containing the name Cisco (notice the standard SQL wildcard character % used):

    ncp.dla.network.view=LIKE 'Cisco%'

11. Use the ncp.dla.entity.details parameter to specify whether the DLA should query for entity detail data and export this data as an extended attribute. The default option is false.

    ncp.dla.entity.details=false

12. Use the ncp.dla.signatureGenExcludeMAC parameter to exclude certain MAC addresses from the signature generation algorithm.
    This is useful when MAC addresses present on network devices are duplicated across the network, and you want to prevent the signature generation process from unnecessarily generating the same signature multiple times.

    To use this capability, for each potentially duplicated MAC address in the network you must enter a signatureGenExcludeMAC property. The format of this property is as follows: ncp.dla.signatureGenExcludeMAC.n=MAC

    Where:

    • n is an incrementing number for each exclusion starting from 1.
    • MAC is the colon-delimited MAC address to exclude from the signature generation process.
    For example, the default values in the ncp_dla.properties file specify the that following MAC addresses are to be excluded from the signature generation process:

    • 00:00:00:00:00:00, which is an all-zero default MAC address.
    • 02:00:00:00:00:04, which is a Juniper fpx1 internal interface MAC address.
    • 00:0B:CA:FE:00:00, which is a Juniper bme0 management interface MAC address.

    ncp.dla.signatureGenExcludeMAC.1=00:00:00:00:00:00
    ncp.dla.signatureGenExcludeMAC.2=02:00:00:00:00:04
    ncp.dla.signatureGenExcludeMAC.3=00:0B:CA:FE:00:00

13. Use the ncp.dla.signatureOverride parameter to manually configure the signature used by the DLA on a per-device basis, in this way bypassing automated signature generation.
    This is useful when the devices exported by the DLA are not properly reconciled within TADDM, such as when the signature attribute differs for the same device.

    In order to use this capability, for each device whose signature you want to override you must know the following information:

    1. Network Manager entityName
    2. TADDM signature
    3. SignatureOverride property

    The format of this property is as follows: ncp.dla.signatureOverride.n=entityName=signature

    Where:

    • n is an incrementing number for each override starting from 1.
    • entityName is the Network Manager entityName of the device to apply the signature to.
    • signature is a valid CDM signature of the form IP address(MAC address) or IP address.

    Note: You must ensure that you choose a signature IP and MAC address relating to the specified device when using this capability.
    For example, to override the signature for the devices "fred" and "barney", add the following configuration properties:

    ncp.dla.signatureOverride.1=fred=172.20.1.6(00:21:28:FF:1A:3A)
    ncp.dla.signatureOverride.2=barney=172.20.1.7(00:21:EE:6B:1A:2A)

14. Specify how the Discovery Library books generated by the DLA should be transferred by specifying the following parameter:

    ncp.dla.datasink.type

    How Discovery Library books are transferred. Options are as follows:

    FILE

    The Discovery Library books are locally copied to the target directory /opt/IBM/netcool/core/var/precision/ccmdb. If you specify this option, skip step 15 and proceed to step 18.

    FTP

    The Discovery Library books are transferred to a remote server by FTP. If you specify this option, you must complete step 15

    ncp.dla.datasink.targetDirectory

    The target directory for Discovery Library book files

    Note: If you are running the DLA on a server other than the GUI server and want to place the generated books that server, you can specify the connection parameters in the ncp_dla.properties file by uncommenting and editing the parameters around ncp.dla.datasink.targetDirectory.
15. Optional: If you specified the option FTP for the ncp.dla.datasink.type property, specify the following additional parameters:

    ncp.dla.datasink.server

    The IP address or hostname of the remote FTP server.

    ncp.dla.datasink.port

    The TCP port to use, default 21

    ncp.dla.datasink.binary

    Whether binary FTP transfers should be used [true|false]

    ncp.dla.datasink.passive

    Whether passive FTP transfers should be made [true|false]

    ncp.dla.datasink.username

    The FTP username to use

    ncp.dla.datasink.password

    The FTP user password to use

    ncp.dla.datasink.encrypted

    Whether or not the FTP password is encrypted [true|false]

    ncp.dla.datasink.keyFile

    Specify the full path and name of the cryptographic key file that is used in the $NMGUI_HOME/profile/etc/tnm/tnm.properties file.

16. Optional: You can limit the scope of data collection by filtering the results by chassis identifiers. Do this by specifying an SQL query within the ncp.dla.chassis.ids parameter.
    Specifying a filter using the ncp.dla.chassis.ids property enables you to retrieve only the ComputerSystem records that match the entity ids returned by the SQL query.

    Note: This filtering method is preferable to filtering using the ncp.dla.network.view parameter, as it enables you to more precisely specify the chassis of interest.
    The following example shows an SQL query that returns the chassis identifiers that were tagged on the network edge.

    Note: For ease of reading this SQL query is presented indented on multiple lines. However, in the ncp_dla.properties configuration file, the entire SQL query must be presented on a single line; otherwise the operation will return an error.

    ncp.dla.chassis.ids=SELECT e.mainNodeEntityId 
                        FROM entity e 
                        INNER JOIN domainMgr  d ON d.domainMgrId = e.domainMgrId 
                        WHERE d.domainName = 'NCPPUP' AND EXISTS
                             (SELECT ed.entityId FROM entityDetails ed 
                              WHERE ed.entityId = e.entityId 
                              AND ed.keyName = 'NetworkEdge' 
                              AND ed.keyValue = 1)
                        GROUP BY e.mainNodeEntityId

17. Optional: You can exclude model and manufacturer information from the output using the ncp.dla.ExcludeModel and ncp.dla.ExcludeManufacturer parameters.
    The format of these parameters is as follows:

    ncp.dla.ExcludeModel.N=MODEL_NAME
    ncp.dla.ExcludeManufacturer.N=MANUFACTURER_NAME

    Where:

    • N is a number that increments for each exclusion, starting from 1.
    • MODEL_NAME is a model name to exclude.
    • MANUFACTURER_NAME is a manufacturer name to exclude.

    Matching values are suppressed from the output.
    The following example shows how to exclude the manufacturers Windows and net-snmp.

    ncp.dla.ExcludeManufacturer.1=Windows
    ncp.dla.ExcludeManufacturer.2=net-snmp

18. Optional: Specify the log and trace level of the DLA by specifying a value for the ncp_dla.log.level and ncp_dla.trace.level properties.
    The default for ncp_dla.log.level is WARNING. The default for ncp_dla.trace.level is ALL. The following values are permitted:

    Option	Description
    CONFIG	Logs all events up to and including configuration changes.
    INFO	Logs only system state changes. This is the default setting.
    WARNING	Logs recoverable system errors.
    SEVERE	Logs unrecoverable system errors.
    FINE	Minimum level of tracing. The majority of stack traces appear at this level already and are written to the trace file. The trace file also includes all log messages. Note: When setting the logging level to FINE, FINER, FINEST, or ALL, both log files and trace files will contain information, and the trace files will include all messages from the log files in addition to the more technical details of operation. If any other logging level is set, the trace files remain empty.
    FINER	Medium level of tracing that provides more detailed debug messages.
    FINEST	Maximum level of tracing that produces very detailed technical information.
    ALL	Enables logging and tracing on all levels for the application.
    OFF	Disables all logging and tracing for the application.

19. Optional: Specify the directory where the log and trace files are created by specifying a value for the ncp_dla.log.directory property.

    The default is /tmp/ncp_dla_logs.

    Note: As of version 4.2, Fix Pack 15 of Network Manager, the DLA uses the same logging infrastructure as the GUI components. For information about configuring other aspects of logging, see Setting up logging for GUI.
20. Create a copy of the edited configuration file, giving the file a name of your choice.
21. Create a copy of the configuration for each Network Manager domain for which you want to create Discovery Library books.
    Remember: Create a configuration file for each Network Manager domain you want to generate Discovery Library books for, and append the name of the configuration file with the domain name (for example, ncp_dla.properties.NCOMS).