SevOne SDN Collector Set Collector Using 'launch configure' Option

About

This document provides a description of the configure option available from the launch script. This option has been added to the launch script to make it easier for SevOne SDN Collector users to configure various parameters and gather network data. For any help regarding the launch, please contact IBM SevOne Support team.

settings.env file is used as the configuration file for the successful operation of the collector. By default, settings.env file is located in /opt/cisco-aci-agent/conf directory. For multi-site support, an additional file multi_site_config.json is required. This file, by default, is also located in /opt/cisco-aci-agent/conf directory.

Installer

An installer is added to the configure option of the launch script to easily configure both the settings.env and multi_site_config.json files. It provides the purpose of each parameter as well as its current value that will be overridden. Please execute the steps below.

Execute the Installer
$ ./launch configure --conf-path <directory path for settings.env/multi_site_config.json files (optional)>
Scenario# 1
If no directory path is provided, the launch script defaults to /opt/cisco-aci-agent/conf (default path) for the settings.env and multi_site_config.json files.
  • If the settings.env and multi_site_config.json files are not found in the default path, the launch script creates these files using sample files found in this directory and the installer acts on these files.
  • If the settings.env and multi_site_config.json files are found in the default path, these files are provided to the installer.

Scenario# 2
If a directory path is provided to the launch script and either one or both settings files are not present in that directory, the missing file(s) are created in the directory path provided in the launch command. The missing files are created using the sample files available in /opt/cisco-aci-agent/conf and the installer acts on these files.

Scenario# 3
If a non-existent directory path or the path of a file is provided, the launch script defaults to /opt/cisco-aci-agent/conf (default path) and works similar to Scenario# 1.

Validate Files

  • The installer validates all required parameters in settings.env and multi_site_config.json files.
  • If any required parameter(s) are missing from the settings.env and/or multi_site_config.json files, the installer exits and provides a detailed message of the missing parameter and the file it is missing from. If all required parameters are set, the validation completes successfully and you will see the following message.

    File <file_name> validated successfully


    where <file_name> can be settings.env, if the settings.env file was successfully validated or multi_site_config.json, if the multi_site_config.json file was successfully validated.

Configuration

  • Once the validation completes successfully, configure parameters in the settings.env file.

    After entering the user details for SevOne NMS and ACI data source, the configuration script will verify the user credentials and authority (valid for APIC only).

    PAS hostname or IP, administrator username, and administrator password are required parameters. Please assign valid values to these parameters.

    For example,

    PAS hostname or IP [192.168.1.1] :

    where,
    PAS hostname or IP is the prompt followed by its current value, 192.168.1.1, in this example.

    This prompt is directly mapped to SEVONE_API_HOST in settings.env file.

    settings.env file: List of prompts and their respective mappings

    Promt Mapped Parameter Information
    PAS hostname or IP SEVONE_API_HOST (required)
    PAS administrator username SEVONE_API_USER (required)
    PAS administrator password SEVONE_API_PASSWORD (required)
    PAS API use https SEVONE_API_SECURITY (optional)
    PAS API Collection port SEVONE_API_COLLECTION_PORT (optional)
    PAS API Config port SEVONE_API_CONFIG_PORT (optional)

    settings.env.sample file

    SEVONE_API_HOST=192.168.1.1
    SEVONE_TRANSPORT=api
    SEVONE_API_USER=admin
    SEVONE_API_PASSWORD=sevone
    SEVONE_API_CONFIG_VERSION=v2
    SEVONE_API_COLLECTION_VERSION=v2
    SEVONE_API_SECURITY=False
    SEVONE_API_COLLECTION_PORT=80
    SEVONE_API_CONFIG_PORT=80
    SEVONE_LOG_LEVEL=DEBUG
    SEVONE_PERSIST=sqlite
    SEVONE_LOG_FILE=/var/log/cisco-aci-agent-logs/cisco-aci-agent-uc.log
    SEVONE_API_READ_TIMEOUT=60
    DISTRIBUTE_ON_ALL_PEERS=False
    DISTRIBUTION_PEERS_LIST=Empty
    
  • Now, configure the parameters in the multi_site_config.json file.
    APIC/MSM hostname or IP, administrator username, administrator password, site name, device name prefix, and APIC version string are required parameters. Please assign valid values to these parameters.
    multi_site_config.json file: List of prompts and their respective mappings
    Promt Mapped Parameter Information
    Collect information from multisite manager is_multi_site_mode (optional)
    Version of the ACI running on the APICs apic_version_string (required parameter) (required)
    If is_multi_site_mode is set to false, the user would want to provide the information for each site individually rather than have the collector read it from the Multisite Controller. In this case, the installer will first print the list of configured sites (if the sites were already configured manually in the settings file) and then warn the user that the information on these sites will be lost if the user decides to continue.
    Prompt Mapped Parameter Information
    Site Name name (required)
    APIC hostname or IP ip (required)
    APIC administrator username username (required)
    APIC administrator password password (required)
    Device Name Prefix device_name_prefix (required)
    Fault Configuration FileName fault_configuration_filename (optional)
    If is_multi_site_mode is set to true, you will get the following prompts to access the Cisco Multisite Controller.
    Prompt Mapped Parameter Information
    Multisite manager protocol mso_protocol (required)
    Multisite manager hostname or ip mso_ip (required)
    Multisite manager administrator username mso_uid (required)
    Multisite manager administrator password mso_password (required)
    Version of the ACI running on the APICs apic_version_string (required)
    Prompt Mapped Parameter Information
    Collect health and fault statistics for ACI physical devices do_nodes (optional)
    Collect traffic statistics for ACI physical devices do_nodes_traffic (optional)
    Collect health and fault statistics for ACI policy model do_pod (optional)
    Collect traffic statistics for ACI policy model do_pod_traffic (optional)
    Collect ACI faults and Create Alarms in the PAS do_subscription (optional)
    Collect data for topology report do_topology (optional)
    Collect health & fault statistics on ACI connected hypervisors and virtual machines do_virt (optional)
    Collect statistics on ACI connected hypervisors and virtual machines do_virt_stats (optional)
    Collect statistics on external switches visible to the ACI fabric do_ext (optional)
    Path of the folder to contain the collector logs cisco_log_filepath (optional)
    Collector log file name cisco_log_filename (optional)
    Minimum log level for collector logs. Accepted values are CRITICAL, ERROR, WARNING, INFO and DEBUG cisco_log_level (optional)
    No prefix in Spines, Leaves and APIC no_prefix (optional)
    Prefix for NMS alert summary fault_prefix (optional)
    multisiteconfig.json.sample file
    {
      "do_nodes": true,
      "do_nodes_traffic": true,
      "do_pod": true,
      "do_pod_traffic": true,
      "do_virt": false,
      "do_virt_stats": false,
      "do_ext": false,
      "do_subscription": true,
      "do_topology": true,
      "cisco_log_filepath": "/var/log/cisco-aci-agent-logs/",
      "cisco_log_filename": "cisco-aci-agent.log",
      "cisco_log_level": "INFO",
      "apic_version_string": "",
      "is_multi_site_mode": false,
      "mso_protocol": "https",
      "mso_ip": "192.168.1.1",
      "mso_uid": "user",
      "mso_password": "password",
      "sites": [
        {
          "name": "Site Name",
          "mso_protocol": "https",
          "mso_ip": "192.168.1.1",
          "mso_uid": "user",
          "mso_password": "password",
          "device_name_prefix": "Site Name",
          "fault_configuration_filename": ""
        }
      ],
      "poll_interval": 300,
      "max_wait_time": 300,
      "meta_topology_interval": 1500,
      "poller_threads": 5,
      "meta_threads": 10,
      "misc_threads": 10,
      "no_threads": false,
      "lb_round": true,
      "do_extended": true,
      "do_bytes": true,
      "do_packets": false,
      "do_meta": true,
      "do_widget": false,
      "skip_bad_nic": true,
      "skip_off_vm": true,
      "skip_tunnelif": true,
      "dn_order": true,
      "page_size": 10000,
      "apic_connection_timeout": 30,
      "sleep_time": 200,
      "read_timeout": 90,
      "subscribe_to": "FAULTS",
      "alert_timeout": 300,
      "key": "",
      "certificate": "",
      "create_missing_types": false,
      "merge_existing_devices": true,
      "dry_run": false,
      "dry_run_detailed": false,
      "dry_sim": false,
      "dump_filepath": "",
      "fallback": false,
      "sim_filepath": "",
      "sim_run": false
    }
    
    It is assumed that the admin credentials for each site APIC controlled by the Multisite Controller are identical to the credentials for the Multisite Controller. If the user updates any information for any sites controlled by the Multisite Controller, then the user may update the site's array manually after the completion of the launch configure. For example, if a site with hostname great.site.com has a password abc12345 and apic_version_string 4.0(2d) while the controller has a password abc123 and apic_version_string 3.2(2d), then it may be configured as below in the multi_site_config.json file.
    
    ....
    "apic_version_string" : "3.2(2d)",
    "mso_protocol" : "https",
    "mso_ip" : "x.mso.com",
    "mso_uid" : "admin",
    "mso_password" : "abc123",
    "sites" : [
      {
        "mso_protocol" : "https",
        "mso_ip" : "great.site.com",
        "mso_password" : "abc12345",
        "apic_version_string" : "4.0(2d)"
      }
     ]
    ...
    
    Internally, for each site, ip, uid, and password are prefixed with mso. The mso_ip in the site's array is used to look up the site name where the changes are to be made and hence it is a mandatory field.
  • Post execution of the installer, the settings.env and multi_site_config.json files will be overwritten with the new settings provided by the user.
  • The following parameters are not prompted as they need to be set manually.
    • dry_sim
    • create_missing_types
    • alert_timeout
    • fallback
    • skip_tunnelif
    • read_timeout
    • poll_interval
    • lb_round
    • sleep_time
    • skip_bad_nic
    • skip_off_vm
    • key
    • certificate
    • poller_threads
    • page_size
    • meta_threads
    • misc_threads
    • no_threads
    • max_wait_time
    • sim_run
    • dump_filepath
    • sim_filepath
    • merge_existing_devices
    • meta_topology_interval
    • fault_configuration_filename

Stop Installer

Press the Ctrl-C to stop the execution of the installer. The installer will immediately exit and the settings files will maintain its values as before the installer was executed via the launch configure command.

Malinformed File

If the multi_site_config.json file is a malformed JSON document, the execution of the installer results in an error and the installer exits immediately. The user must be careful to validate that the multi_site_config.json file is a valid JSON document before executing the installer.

Appendix - Description of Mapped Parameters and its Default Values

The table below contains a description of mapped parameters in settings.env and multi_site_config.json files respectively.

settings.env

Mapped Parameter Description Default Value
SEVONE_TRANSPORT Setting that tells the collector to use SevOne NMS REST API. api NOTE: This shouldn't be changed.
SEVONE_API_HOST The IP address of SevOne NMS PAS. For HSA environment, you must use the VIP Address for SevOne NMS HSA pair. 192.168.1.1
SEVONE_API_USER SevOne NMS user name for an administrator-level account. admin
SEVONE_API_PASSWORD SevOne NMS password. sevone
SEVONE_API_CONFIG_PORT The API config port. HTTP on port 80 and HTTPS on port 443. 80
SEVONE_API_COLLECTION_PORT The API communication port. HTTP on port 80 and HTTPS on port 443. 80
SEVONE_API_CONFIG_VERSION The REST API version for SevOne NMS PAS. v2 NOTE: This shouldn't be changed.
SEVONE_API_COLLECTION_VERSION The REST API version for SevOne NMS PAS. v2 NOTE: This shouldn't be changed.
SEVONE_API_SECURITY Decides whether HTTPS is being used or not. false
SEVONE_LOG_LEVEL Log level to run the process with. Value can be DEBUG, INFO, WARNING, ERROR, or CRITICAL. WARNING
SEVONE_PERSIST SevOne persistence mechanism. Value can be ram, sqlite, or none. However, the preferred setting for this is sqlite, as setting it to ram or none might result in memory overload or data loss. ram NOTE: sqlite is a preferred setting.
SEVONE_LOG_FILE The log file path for SevOne Universal Collector library. /var/log/cisco-aci-agent-logs/cisco-aci-agent-uc.log
DISTRIBUTE_ON_ALL_PEERS If set to true, will distribute the devices across the cluster on its own on all the peers. However, if set to false, it will send data to local peer or given a list of peers (if provided). true
DISTRIBUTION_PEERS_LIST The flag expects a list of peers to distribute data. If you want to restrict devices to a particular peer or a set of peers, please contact IBM SevOne Support. This flag will work only when DISTRIBUTE_ON_ALL_PEERS is set to false. empty
SEVONE_API_READ_TIMEOUT Read timeout for SevOne REST API connection. 60 seconds
SEVONE_API_SSL_VERIFY The REST API verifies the SSL certificate by default. Please set the value to true if certificate verification is needed. false

multi_site_config.json

Mapped Parameter Description Default Value
do_nodes Enable the Node devices - spines, leaves, and controllers. true
do_nodes_traffic Enable Node devices' network statistics. true
do_pod Enable the POD device. true
do_pod_traffic Enable POD device's network statistics. true
do_virt Poll for VMs and HVs. false
do_virt_stats Poll for network statistics of VMs and HVs. false
do_ext Poll external switches. false
do_subscription Enable subscription to Cisco APIC. true NOTE: If true, the collector starts the subscription to the APIC in (n+1)th iteration; where n is derived using the meta_topology_interval. Please note that subscription is not possible with key based authentication, please use password authentication.
do_topology Enable topology information. true NOTE: If true, the collector populates the topology information in SevOne NMS in every nth iteration; where n is derived using the meta_topology_interval.
cisco_log_filepath Absolute path of folder where collector logs should be generated. "/var/log/cisco-aci-agent-logs/"
cisco_log_filename Name of the log file. "cisco-aci-agent.log"
cisco_log_level Granularity level for the log. Should be one of CRITICAL, ERROR, WARNING, INFO, and DEBUG. "INFO"
apic_version_string The complete version of Cisco APIC. "" NOTE: Enter a valid APIC version such as "4.0(2d)" or "3.2(2d)" or any valid version.
is_multi_site_mode If set to true, run the collector in multisite mode, in which case details of the Multi Site Orchestrator (MSO) need to be provided for subsequent keys (mso_ip, mso_uid, and mso_password). If false, please provide details of the Cisco APIC for these keys. false
mso_protocol The connection protocol required to connect with Cisco APIC / Multi Site Orchestrator(MSO). https
mso_ip The IP address or hostname for the Cisco APIC or the Multi Site Orchestrator (MSO). "192.168.1.1"
mso_uid For the traditional way, enter the user name for the Cisco APIC or the Multi Site Orchestrator (MSO). If you are using TACACS+ support, you will set mso_uid as apic:. For example, mso_uid=apic:tacacs_login\test2. "user"
mso_password The password for the Cisco APIC or the Multi Site Orchestrator (MSO). "password"
sites Set of configurations specific to the individual sites in a multi-site orchestration. [{ "name": "Site Name", "mso_ip": "192.168.1.1", "mso_uid": "user", "mso_password": "password", "device_name_prefix": "Site Name" }]
poll_interval Frequency of polling data in seconds. 300
max_wait_time Maximum wait time in seconds for the thread pool before it cancels the future processing of a thread. 300
meta_topology_interval Frequency of polling metadata and topology in seconds. 1500
poller_threads The number of poller threads. 5
meta_threads The number of threads for collecting metadata. 5
misc_threads Used to set IP addresses of devices, object descriptions, fetch and save topology. 10
no_threads Run the collector in single threaded mode. false
lb_round Enables load balancing of API requests among clustered APIC controllers. true
do_extended Enable extended polling for additional object types. true
do_bytes Collect statistics in bytes. true NOTE: If both do_bytes and do_packets are set to false, no traffic/stats data will be collected.
do_packets Collect statistics in packets. false NOTE: If both do_bytes and do_packets are set to false, no traffic/stats data will be collected.
do_meta Enable metadata. true NOTE: If true, the collector populates the metadata in SevOne NMS in every nth iteration; where n is derived using the meta_topology_interval.
do_widget Enable only metadata that is used by widgets. false
skip_bad_nic Skip VM network interfaces with an IP address of 0.0.0.0. true
skip_off_vm Skip VMs that have been powered off. true
skip_tunnelif Skip polling the POD for Tunnel Interfaces. true
dn_order Request objects to be sorted by DN in the APIC API query. true
page_size The page size to use for paginating API requests. 10000
apic_connection_timeout The amount in seconds to wait before timing out on attempting to connect to the APIC. 30
sleep_time The time to sleep after APIC API queries in milliseconds. 200
read_timeout Sets the read timeout in seconds for the time to wait before first byte received from APIC API query responses. 90
subscribe_to Enable subscriptions for which API classes to subscribe to. "FAULTS"
alert_timeout The amount in seconds to wait before timing out on attempting to link alerts to devices and objects. 300
key The path to the private key file inside the docker container. By default, /aci-auth is mounted to the running directory of the launch script - such as password/credentials. For example, KEY=/aci-auth/private.key ""
certificate Certificate name specified on the APIC for key authentication. ""
create_missing_types Run the collector in installation mode. When running in this mode, it will not collect any data but create Object Types, Indicator Types, Device Groups and Rules, Topology constraints, and Metadata schema. false
merge_existing_devices Reuse the device if a device with same IP already exists in SevOne NMS. This setting is ignored for the following cases:
  • In Multi Site setups
  • For devices with IP address 0.0.0.0
  • If there are multiple devices with the same IP address already existing in SevOne NMS.
true
dry_run Run the collector without ingesting into SevOne NMS. false
dry_run_detailed Execute a detailed dry-run to dump object; Only valid with dry-run. false
dry_sim Execute a dry-run simulation. false
dump_filepath Path of the folder containing the dump files for each site to be used to simulate the data for collector in simulation mode. This folder should also contain the root log file, cisco-aci-agent.log. ""
fallback Fallback to only spine/leaf interface polling. false
sim_filepath Path of the folder containing the JSON files for each site to be used to simulate the data for collector in simulation mode. This folder should also contain the root log file, cisco-aci-agent.log. ""
sim_run Do a simulation run to dump object. false
fault_prefix Used to specify a prefix text in the summary field of alerts that are created from ACI faults. blank
no_prefix If set to true, the device_name_prefix will not be added to ACI Spines, Leaves, and Controllers (APIC). false
self_monitoring If set to true, the following device and object will be created.
  • Device: <Site-Name> SDN Selfmon
  • Object: selfmon (available with previously mentioned device)
The object is of type ACI SelfMon and the following indicators are associated with it.
  • Availability
  • Elapsed Time
  • Errors
  • Warnings
false

Any of the above mentioned flags when specified again in this section will override that particular setting for the site. The following mapped parameters are the configuration for sites that are not part of the global configurations.

Mapped Parameter Description Default Value
name Name of the site. This will be prefixed to the device names for all devices of this site. "Site Name" NOTE:
  • Please add a space after mapped parameter name.
  • If name is not provided, by default, the collector will use the value assigned to mso_ip parameter as the name.
device_name_prefix A prefix string that will be prefixed to the devices along with the site name. "Site Name" NOTE:
  • Please add a space after mapped parameter device_name_prefix.
  • The device_name_prefix must be unique for each site otherwise, the collector will not behave properly.
  • If device_name_prefix is not provided, all devices will be prefixed with the site name (defined in name parameter) by default.
fault_configuration_filename The name of the file containing configurations for filtering and mapping of severity for faults for the site. This file MUST be placed in the directory containing the multi_site_config.json and settings.env files. Empty string NOTE: For more details on configuring the .json file for fault configurations, please refer to SevOne SDN Collector Filter Alerts Using 'launch generate-fault-config' Option