Configuration

Perform the following steps to configure and start the Cisco ACI collector. SSH, SOAP, and SevOne NMS user accounts must have administrative privileges.

SSH into SevOne NMS or the system on which the collector needs to be deployed.
```
$ ssh root@<NMS appliance>
```
Download the following (latest) files from IBM Passport Advantage (https://www.ibm.com/software/passportadvantage/pao_download_software.html) via Passport Advantage Online. However, if you are on a legacy / flexible SevOne contract and do not have access to IBM Passport Advantage but have an active Support contract, please contact IBM SevOne Support for the latest files. You must place these files in /root directory of SevOne NMS appliance.
1. cisco-aci-agent-solution-v6.6.0-build-235714.tar.gz
2. cisco-aci-agent-solution-v6.6.0-build-235714.tar.gz.sha256.txt
3. signature-tools- -build.<###>.tgz
  For example, signature-tools-2.0.1-build.1.tgz
4. signature-tools- -build.<###>.tgz.sha256.txt
  For example, signature-tools-2.0.1-build.1.tgz.sha256.txt

Execute the following commands to verify the checksum of the code signing tool before extracting it.

$ (cat $(ls -Art signature-tools-*.tgz.sha256.txt | \
tail -n 1) | sha256sum --check)

$ sudo tar xvfz $(ls -Art signature-tools-*.tgz | \
tail -n 1) -C /

Extract the latest build.

$ tar xvf cisco-aci-agent-solution-v6.6.0-build-235714.tar.gz

Perform the pre-check of your environment and monitor the output. Ensure that there are no failures reported in the output.
```
$ SevOne-act check tables
```
The pre-check must complete successfully before you can continue to the next step. If the pre-check does not complete successfully, please resolve the issue(s) before continuing or contact IBM SevOne Support .
Execute the following command, if the installation is on SevOne NMS appliance.

If the installation is not on SevOne NMS appliance, then skip to Step 7.

These steps must be performed on both the leader and HSA appliance in a cluster environment.
```
$ ./install.sh --configure
```
In SevOne Cisco SDN Collector 6.6 Solution, the install script operates on the settings.env and multi_site_config.json files. The user may choose to keep these files in a specific directory and provide the directory path as an argument to the install script's --conf-path option.
```
$ ./install.sh --configure --conf-path <directory path for settings.env/multi_site_config.json file>
```
The --conf-path argument must be an absolute path. If the settings files in /opt/cisco-aci-agent/conf directory are used, the user may choose to not provide the directory path in --conf-path argument.

If your SevOne NMS is SSL-verified, provide the CA bundle to the install script using the --ssl-verify option.
```
$ ./install.sh --configure --ssl-verify <path-to-CA-bundle>
```
The --ssl-verify argument must be an absolute path. If this option is used, please make sure the following variables are set in the settings.env file.
- SEVONE_API_SECURITY=True
- SEVONE_API_COLLECTION_PORT=443
- SEVONE_API_CONFIG_PORT=443
If you do not know the path of the CA bundle, please contact IBM SevOne Support .
If your SevOne NMS is using https and it is not SSL-verified, please add the following variable to the settings.env file.
- SEVONE_API_SSL_VERIFY=False
It will perform the following tasks:
1. Enables and starts Docker services, if required
2. Sets up the prerequisite directories and files
3. Validates the checksum file
4. Extracts the cisco-aci-agent-solution-v6.6.0-build-235714.tar.gz file
5. Loads the Docker image
6. Adds execute permissions to the launch script
7. Extracts a sample certificate-private key pair that can be used for Signature-based Authentication.
  
  Do not use the sample keys as they are the same for all customers. You must generate your own signature pair.
8. Executes the installer to setup the settings.env and multi_site_config.json files. This option can also be executed independently by user using the launch script. For detailed instructions, please refer to SevOne SDN Collector Set Collector Using 'launch configure' Option.
  
  To create fault filters based on the latest filters available for SDN 6.6, please refer to SevOne SDN Collector Filter Alerts Using 'launch generate-fault-config' Option.
  
  Sample
  Provide settings for PAS
```
#### Provide settings for PAS ####
PAS hostname or IP [192.168.1.1]:
PAS administrator username [admin]:
PAS administrator password [********]:
PAS API use https [False]:
PAS API Collection port [80]:
PAS API Config port [80]:
Validating NMS Credentials...
Validation completed successfully...
```
  Please make sure to provide valid inputs for the following prompts.
  - PAS hostname or IP
  - PAS administrator username
  - PAS administrator password
  Provide settings for ACI Datasource
```
#### Provide settings for ACI Datasource ####
Collect information from multisite manager [False]:
Version of the ACI running on the APICs []:
########## Below is the list of configured sites. Resetting it will cause a deletion of all existing sites ##########
{
    "name": "Site Name",
    "mso_ip": "192.168.1.1",
    "mso_uid": "user",
    "mso_password": "password",
    "device_name_prefix": "Site Name",
    "fault_configuration_filename": ""
}
Would you like to reset the configured sites?  [YES/Y/N/NO]:
Add site [YES/Y/N/NO]:
Site Name [Site Name]:
APIC hostname or IP [192.168.1.1]:
APIC administrator username [user]:
APIC administrator password [********]:
Device Name Prefix [Site Name]:
Fault Configuration FileName []:
Add site [YES/Y/N/NO]:
Validating ACI DS Credentials...
Validation for ACI DS Credentials is successful...
```
  Please make sure to provide valid inputs for the following prompts.
  - Site Name
  - APIC hostname or IP
  - APIC administrator username
  - APIC administrator password
  - Device Name Prefix
  - Fault Configuration FileName
  If the Collect information from multisite manager prompt value is set to true, you will see the following prompts.
  - Multisite manager hostname or ip
  - Multisitemanager administrator username
  - Multisite manager administrator password
  - Version of the ACI running on the APICs
  Provide settings for Collector
```
#### Provide settings for Collector ####
Collect health and fault statistics for ACI physical devices [True]:
Collect traffic statistics for ACI physical devices [True]:
Collect health and fault statistics for ACI policy model [True]:
Collect traffic statistics for ACI policy model [True]:
Collect ACI faults and Create Alarms in the PAS [True]:
Collect data for topology report [True]:
Collect health & fault statistics on ACI connectedhypervisors and virtual machines [False]:
Collect statistics on external switches visible to the ACI fabric [False]:
Prefix for NMS alert summary []:
Path of the folder to contain the collector logs [/var/log/cisco-aci-agent-logs/]:
Collector log file name [cisco-aci-agent.log]:
Minimum Loglevel for collector logs. Accepted values are CRITICAL, ERROR, WARNING, INFO and DEBUG [INFO]:
No prefix in Spines, Leaves and APIC [False]:
```
  Please do not update the default value for the following settings.
  - Path of the folder to contain the collector logs
  - Collector log file name
  - Minimum Loglevel for collector logs
9. Extracts and handles the dependencies required for ACI. This includes installing the autossh package, creating a systemD service, modifying sshd's settings, restarting the sshd service and starting the autossh tunnel forwarding service. The step was created as a shortcut when installing on SevOne NMS appliances. However, it will not work when the installation is not on SevOne NMS appliance.
  - In a pop-up editor, you will see content similar to the sample below.
  Sample
```
# TARGET=apic # this is the name
# LOCAL_ADDR=0.0.0.0 # which local interface to bind to <all>
# LOCAL_PORT=9999 # which local port to use
# APIC_ADDR=172.21.100.250 # where is the apic
# APIC_PORT=443 # what port is the API on the APIC

TARGET=apic
LOCAL_ADDR=0.0.0.0
LOCAL_PORT=9999
APIC_ADDR=172.21.100.250
APIC_PORT=443
```
  - Press Ctrl+x . However, if you attempt to install via WebEx, Ctrl+x is not possible from the WebEx session. You will need a local user to perform this step for you.
10. Refreshes the cache so that any device-ids maintained in a cache on the machine may be deleted.
11. Adds objects and indicators to SevOne NMS. This includes setting the topology constraints and create Object Types, Indicator Types, Device Groups and rules, and Metadata Schema .
12. Sets up logrotate.
  
  Import OOTB Reports
  
  To import out-of-the-box (OOTB) reports, please execute the following command.
  
  The command below to import OOTB reports, is not required to be run on an HSA.
```
$ ./install.sh --import-ootb-reports
```
  OOTB reports will be imported to your SevOne NMS only when the --import-ootb-reports flag is enabled.
Execute the following command, if the installation is not on SevOne NMS appliance .

If the installation is on SevOne NMS appliance, then skip to Step 8.
```
$ ./install.sh --configure --non_pas_device
```
In SevOne Cisco SDN Collector 6.6 Solution, the install script operates on the settings.env and multi_site_config.json files. The user may choose to keep these files in a specific directory and provide the directory path as an argument to the install script's --conf-path option.
```
$ ./install.sh --configure --conf-path <directory path for settings.env/multi_site_config.json file>
```
The --conf-path argument must be an absolute path. If the settings files in /opt/cisco-aci-agent/conf directory are used, the user may choose to not provide the directory path in --conf-path argument.

If your SevOne NMS is SSL-verified, provide the CA bundle to the install script using the --ssl-verify option.
```
$ ./install.sh --configure --ssl-verify <path-to-CA-bundle>
```
The --ssl-verify argument must be an absolute path. If this option is used, please make sure the following variables are set in the settings.env file.
- SEVONE_API_SECURITY=True
- SEVONE_API_COLLECTION_PORT=443
- SEVONE_API_CONFIG_PORT=443
If you do not know the path of the CA bundle, please contact IBM SevOne Support.
If your SevOne NMS is using https and it is not SSL-verified, please add the following variable to the settings.env file.
- SEVONE_API_SSL_VERIFY=False
It will perform the following tasks:
1. Sets up the prerequisite directories and files
2. Validates the checksum file
3. Extracts the cisco-aci-agent-solution-v6.6.0-build-235714.tar.gz file
4. Loads the Docker image
5. Adds execute permissions to the launch script
6. Extracts a sample certificate-private key pair that can be used for Signature-based Authentication.
  
  Do not use the sample keys as they are the same for all customers. You must generate your own signature pair.
7. Executes the installer to setup the settings.env and multi_site_config.json files. This option can also be executed independently by the user using the launch script. For detailed instructions, please refer to SevOne SDN Collector Set Collector Using 'launch configure' Option.
  
  To create fault filters based on the latest filters available for SDN 6.6, please refer to SevOne SDN Collector Filter Alerts Using 'launch generate-fault-config' Option.
  
  Sample
  Provide settings for PAS
```
#### Provide settings for PAS ####
PAS hostname or IP [192.168.1.1]:
PAS administrator username [admin]:
PAS administrator password [********]:
PAS API use https [False]:
PAS API Collection port [80]:
PAS API Config port [80]:
Validating NMS Credentials...
Validation completed successfully...
```
  Please make sure to provide valid inputs for the following prompts.
  - PAS hostname or IP
  - PAS administrator username
  - PAS administrator password
  Provide settings for ACI Datasource
```
#### Provide settings for ACI Datasource ####
Collect information from multisite manager [False]:
Version of the ACI running on the APICs []:
########## Below is the list of configured sites. Resetting it will cause a deletion of all existing sites ##########
{
    "name": "Site Name",
    "mso_ip": "192.168.1.1",
    "mso_uid": "user",
    "mso_password": "password",
    "device_name_prefix": "Site Name",
    "fault_configuration_filename": ""
}
Would you like to reset the configured sites?  [YES/Y/N/NO]:
Add site [YES/Y/N/NO]:
Site Name [Site Name]:
APIC hostname or IP [192.168.1.1]:
APIC administrator username [user]:
APIC administrator password [********]:
Device Name Prefix [Site Name]:
Fault Configuration FileName []:
Add site [YES/Y/N/NO]:
Validating ACI DS Credentials...
Validation for ACI DS Credentials is successful...
```
  Please make sure to provide valid inputs for the following prompts.
  - Site Name
  - APIC hostname or IP
  - APIC administrator username
  - APIC administrator password
  - Device Name Prefix
  - Fault Configuration FileName
  If the Collect information from multisite manager prompt value is set to true, you will see the following prompts.
  - Multisite manager hostname or ip
  - Multisitemanager administrator username
  - Multisite manager administrator password
  - Version of the ACI running on the APICs
  Provide settings for Collector
```
#### Provide settings for Collector ####
Collect health and fault statistics for ACI physical devices [True]:
Collect traffic statistics for ACI physical devices [True]:
Collect health and fault statistics for ACI policy model [True]:
Collect traffic statistics for ACI policy model [True]:
Collect ACI faults and Create Alarms in the PAS [True]:
Collect data for topology report [True]:
Collect health & fault statistics on ACI connectedhypervisors and virtual machines [False]:
Collect statistics on external switches visible to the ACI fabric [False]:
Prefix for NMS alert summary []:
Path of the folder to contain the collector logs [/var/log/cisco-aci-agent-logs/]:
Collector log file name [cisco-aci-agent.log]:
Minimum Loglevel for collector logs. Accepted values are CRITICAL, ERROR, WARNING, INFO and DEBUG [INFO]:
No prefix in Spines, Leaves and APIC [False]:
```
8. Refreshes the cache so that any device-ids maintained in a cache on the machine may be deleted.
9. Adds objects and indicators to SevOne NMS. This includes setting the topology constraints and create Object Types, Indicator Types, Device Groups and rules, and Metadata Schema.
10. Sets up logrotate.
Change directory to /opt/cisco-aci-agent. This is the default product directory on the system.
```
$ cd /opt/cisco-aci-agent
```
Execute the following command to run the collector one time to initiate the build of all new devices, objects, and indicators.
```
$ ./launch build
```
If the user has stored the settings.env and multi_site_config.json files in a directory other than the default directory, /opt/cisco-aci-agent/conf, the directory path must be passed as an argument using the --conf-path option in the launch script.
```
$ /opt/cisco-aci-agent/launch build --conf-path <directory path for settings.env/multi_site_config.json file>
```
The --conf-path argument must be an absolute path.

If your SevOne NMS is SSL-verified, please provide the CA bundle to the install script using the --ssl-verify option.
```
$ /opt/cisco-aci-agent/launch build --ssl-verify <path-to-CA-bundle>
```
The --ssl-verify argument must be an absolute path. If this option is used, please make sure the following variables are set in the settings.env file.
- SEVONE_API_SECURITY=True
- SEVONE_API_COLLECTION_PORT=443
- SEVONE_API_CONFIG_PORT=443
If you do not know the path of the CA bundle, please contact IBM SevOne Support.
If your SevOne NMS is using https and it is not SSL-verified, please add the following variable to the settings.env file.
- SEVONE_API_SSL_VERIFY=False
Execute the following command to run the collector in various modes. The collector runs in dry-count , dry-detail , live , and sim modes.
```
$ ./launch build [--mode mode] [--conf-path <configuration directory>] [--ssl-verify <path-to-CA-bundle>]
```
If --mode argument is not passed in the command above, the collector by default, runs in collection mode.
If --conf-path argument is not passed in the command above, the default directory, /opt/cisco-aci-agent/conf is used.
Collector queries configured APICs and creates ACI controller, switch, and fabric (Cisco POD) devices in SevOne NMS. Please login to SevOne NMS appliance and check Devices > Discovery Manager.

Please confirm that Discovery Queue is empty before proceeding to the next step.
Execute the following command to run the collector to gather and store ACI data in SevOne NMS continuously.
```
$ ./launch run
```
If the user has stored the settings.env and multi_site_config.json files in a directory other than the default (/opt/cisco-aci-agent/conf), the directory path must be provided as an argument to the launch script's --conf-path option in the crontab.
```
$ ./launch run --conf-path <directory path for settings.env/multi_site_config.json file>
```
The --conf-path argument must be an absolute path.

If your SevOne NMS is SSL-verified, provide the CA bundle to the install script using the --ssl-verify option.
```
$ ./launch run --ssl-verify <path-to-CA-bundle>
```
The --ssl-verify argument must be an absolute path. If this option is used, please make sure the following variables are set in the settings.env file.
- SEVONE_API_SECURITY=True
- SEVONE_API_COLLECTION_PORT=443
- SEVONE_API_CONFIG_PORT=443
If you do not know the path of the CA bundle, please contact IBM SevOne Support.
If your SevOne NMS is using https and it is not SSL-verified, please add the following variable to the settings.env file.
- SEVONE_API_SSL_VERIFY=False
Perform the following actions to configure the cron file for data collection. When running on SevOne NMS cluster, please execute the below crontab on both the leader and HSA so that failover can be handled.
1. Execute the following command.
```
$ crontab -e
```
2. Add following line to start the collection agent.
```
*/5 * * * * /opt/cisco-aci-agent/launch run
```
  If the user has stored the settings.env and multi_site_config.json files in a directory other than the default (/opt/cisco-aci-agent/conf), the directory path must be provided as an argument to the launch script's --conf-path option in the crontab.
```
*/5 * * * * /opt/cisco-aci-agent/launch run --conf-path <directory path for settings.env/multi_site_config.json files>
```
  The --conf-path argument must be an absolute path.
  
  If your SevOne NMS is SSL-verified, provide the CA bundle to the install script using the --ssl-verify option.
```
*/5 * * * * /opt/cisco-aci-agent/launch run --ssl-verify <path-to-CA-bundle>
```
  The --ssl-verify argument must be an absolute path. If this option is used, please make sure the following variables are set in the settings.env file.
  - SEVONE_API_SECURITY=True
  - SEVONE_API_COLLECTION_PORT=443
  - SEVONE_API_CONFIG_PORT=443
  If you do not know the path of the CA bundle, please contact IBM SevOne Support.
  If your SevOne NMS is using https and it is not SSL-verified, please add the following variable to the settings.env file.
  - SEVONE_API_SSL_VERIFY=False
  You may use this for both the leader and the HSA appliance crontab entry. It checks the /SevOne.masterslave.master file for its value to determine whether it needs to run or not.
3. Save and close the file.
  After installing the cron, it might take a few minutes before it executes the job. You can monitor the cron logs using the following command.
```
tail -f  /var/log/cron  | grep launch
```
  Once a log appears as a result of this command, press Ctrl+C to exit. You can then proceed to verify that data appears in SevOne NMS.