Configuring the Cisco DNA REST collector

To use data from the Cisco DNA REST collector in a network discovery, you must configure the connection details between the Cisco DNA and Network Manager.

About this task

To configure the Cisco DNA REST collector, complete the following steps.

Procedure

  1. Change to the Cisco DNA REST collector directory: 
    cd $NCHOME/precision/collectors/javaCollectors/CiscoDNA/
  2. Within this directory, find the sample configuration file for the Cisco DNA REST collector and copy it to the working configuration file. 
    cp CiscoDNARestCollector.properties.sample CiscoDNARestCollector.properties
  3. Edit the collector configuration file:$NCHOME/precision/collectors/javaCollectors/CiscoDNA/CiscoDNARestCollector.properties

    This file includes the following configuration sections:

    • Collector specific properties
    • Data Acquisition properties
    • Data Source properties
    • REST Connection properties

    The following steps list the configurable parameters. Any properties in this file that are not described below are collector system-based configurations and not meant to be changed.

  4. Configure the collector port and log and trace parameters:
    port
    The port on which to run the collector. The port must match the port configured in the insert into the collectorFinder.collectorRules table in the DiscoCollectorFinderSeeds.cfg file. The default value is 8080.
    log.filename
    File name for the collector log file. You can also specify a pattern for the log file name using a set of system-defined elements. The default value is collector1.CiscoDNArest.log.
    log.level
    Takes one of the following values:
    • NONE
    • FINEST
    • FINER
    • FINE
    • CONFIGINFO
    • WARNING
    • SEVERE
    • ALL
    trace.filename
    File name for the collector trace file. You can also specify a pattern for the trace file name using a set of system-defined elements. The default value is collector1-trace.CiscoDNArest.log
    trace.level
    Takes one of the following values:
    • NONE
    • FINEST
    • FINER
    • FINE
    • CONFIGINFO
    • WARNING
    • SEVERE
    • ALL
  5. Configure data acquisition parameters for the collector:
    collectData
    Takes one of the following values. The default value is True.
    • True: Enables the collector. The collector collects data from the EMS.
    • False: Disables the collector. The collector does not collect data from the EMS.
    DataAcquisition.GetEntities
    Takes one of the following values. The default value is 1.
    1: Enable
    Enables download of physical entity data from the EMS.
    0: Disable
    Disables download of physical entity data from the EMS.
    DataAcquisition.GetLayer1Connections
    Takes one of the following values. The default value is 1.
    1: Enable
    Enables download of layer 1 connectivity data from the EMS.
    0: Disable
    Disables download of layer 1 connectivity data from the EMS.
    DataAcquisition.GetLayer2Connections
    Takes one of the following values. The default value is 1.
    1: Enable
    Enables download of layer 2 connectivity data from the EMS.
    0: Disable
    Disables download of layer 2 connectivity data from the EMS.
    DataAcquisition.GetLayer3Connections
    Takes one of the following values. The default value is 1.
    1: Enable
    Enables download of layer 3 connectivity data from the EMS.
    0: Disable
    Disables download of layer 3 connectivity data from the EMS.
    DataAcquisition.localDataDirectory
    The location to store the output files generated from the Cisco DNA via REST. A relative or full path to the directory location is required. You can not use $NCHOME. For example, /opt/IBM/netcool/core/precision/collectors/javaCollectors/CiscoDNA/data/
  6. You can optionally configure details about the source EMS in the Data Source properties section by configuring the following generic fields. Data from these fields is used by Network Manager to model the EMS.
    DataSource.id
    Unique identifier for the datasource, in the form of an integer. This field takes the value 1, indicating that this is the primary data source.
    DataSource.descr
    Description of the Cisco DNA data source.
    DataSource.emsHost
    IP address or hostname of the EMS.
    DataSource.emsPort
    Port of the EMS.
    DataSource.emsUserName
    The username used to connect to the Cisco DNA.
    DataSource.emsPassword
    The password for the user specified by the DataSource.emsUserName property.
    DataSource.emsName
    Name of the EMS.
    DataSource.emsVersion
    Version of the EMS.
    DataSource.emsIdentifier
    Identifier for the EMS and key to integrate the Network Manager collector with the Netcool Configuration Manager driver. For the Cisco DNA REST collector, this identifier must be set to CiscoDNArest.
    DataSource.emsRole
    Role of the EMS. This parameter can take one of the following values:
    • unknown
    • primary
    • backup
    • other
    DataSource.emsStatus
    Status of the EMS. This parameter can take one of the following values:
    • unknown
    • up
    • down
    • other
  7. Configure Web Services and REST connection properties for the collector:
    enableSSL
    Enable or disable SSL connectivity between the collector and the EMS server. This property takes the following values: true or false. The default is false.
    TLSVersion
    The version of the TLS protocol. The allowed value and the default version is TLSv1.2.
    MaxBufferSize
    The maximum size of REST response that the collector processes, measured in MB. The default is 1024.
    keyStoreFileName
    Specify the name of the keystore file that contains the SSL client certificate and trusted authority certificate. The keystore file must be placed in the directory specified in the pathToKeyStoreFile parameter.
    keyStorePassword
    Specify the password required to access the certificate specified by the keyStoreFileName property.
    pathToKeyStoreFile
    The full path to the keyStoreFileName directory. You must specify the relative or full path to the directory location. You can not use $NCHOME. For example, /opt/IBM/netcool/core/precision/collectors/javaCollectors/CiscoDNA.
    setResponseTimeout
    Specify how long (in seconds) the collector waits for a response from the EMS before timing out. The default is 300.
    setHttpVersion
    Specify the version of the HTTP protocol that the target system supports. For Cisco DNA, this property must be set to 1.0.
    setRefreshInterval

    Specify the interval (in seconds) that the collector waits between successive login refresh requests. The Cisco DNA session timeout period is 300 seconds (or 5 minutes), so this value must be less than 300. The default is 180.

    Tip: If your network has performance or stability issues, set a lower value than 180.
    setProtocol
    Set protocol for SSL for Cisco DNA. Default is TLSv1. Allowed values are: SSL, SSLv2, SSLv3, TLS, TLSv1, TLSv1.1, and TLSv1.2.
    skipEMSConnection
    If set to True, the discovery is run with the data that is cached on the server where the collector is running. If False, Network Manager connects to the EMS and requests new data.
    LocalDirectoryPath
    Location of the JSON files on the EMS server.
  8. Save the collector configuration file.
  9. Optional: Set up SSL between the collector and Network Manager.
    1. Obtain the required SSL certificates and the Trusted Authority certificate from the Cisco DNA server administrator.
    2. Add the certificates to a local Java keystore so that they can be referenced by the KeyStore property.
    3. If you have a key and a certificate from the server in separate files, you must combine them into a single PKCS12 format file to load into a new keystore. To convert the server certificate into PKCS12 format, use the following OpenSSL toolkit command:
      openssl pkcs12 -export -inkey key_file-in cert_file-out cert_pkcs12

      Where key_file is the key file retrieved from the server, cert_file is the certificate retrieved from the server, and cert_pkcs12 is the combined file in PKCS12 format for loading into the keystore.

    4. To create a Java keystore using the Keytool utility, follow these steps:
      1. Generate a keystore and self-signed certificate using the following command:
        keytool -genkey -keyalg RSA -alias alias_name -keystore keystore_file -storepass keystore_password -validity 360 -keysize 2048
      2. Import the SSL certificate from Cisco DNA into the newly created Java keystore file using the following command:
        keytool -import -trustcacerts -alias alias_name -file cert_file -keystore keystore_file
      3. Verify that the certificates are in a Java keystore using the following command:
        keytool -list -v -keystore keystore_file
    5. Set the keyStoreFileName and keyStorePassword properties in the collector property file.
    6. Set the enableSSL property in the collector property file to true.
    7. If required, configure the TLSVersion property in the collector property file.
    8. Ensure that the DataSource.emsPort property in the collector property file is set to the HTTPS port.
    9. Copy the generated keystore file into the directory specified in the pathToKeyStoreFile property.
  10. Use the script to start the collector. For example, use a command line similar to the following: 
    ./collector.sh -Xms512m -Xmx1024m -jar CiscoDNA/CiscoDNARestCollector.jar -propsFile CiscoDNA/CiscoDNARestCollector.properties