This document is posted to help you gain knowledge. Please leave a comment to let me know what you think about it! Share it to your friends and learn new things together.
Cisco Stealthwatch Learning Network License ReleaseNotesThis document provides basic information for the Cisco Stealthwatch Learning Network License (Learning Network License)system, including instructions for supported installation and upgrade paths.
Make sure you thoroughly read and understand these release notes, which describe supported platforms, and product and webbrowser compatibility. They also contain detailed information on prerequisites, warnings, and specific installation or deploymentinstructions for the following appliances:
• agents on an Integrated Services Router (ISR) with a UCS E-Series blade server (Cisco 2921, 2951, 2945, 2945E, or 4451)
• agents on an ISR as a virtual service (container) (Cisco 4431 or 4451)
• controller on a host running an ESXi hypervisor
Learning Network License OverviewLearning Network License is a new anomaly detection and mitigation capability developed by Cisco. Unlike other Stealthwatchnetwork-based anomaly detection solutions that use telemetry data from devices across the enterprise network, Learning NetworkLicense deploys agents via Integrated Services Routers (ISR) that run as virtual services, or installed on UCS E-Series blade servers.These agents send evidentiary telemetry back to the controller, a centralized management console. This greatly reduces the volumeof data needed to support the solution. Learning Network License also uses machine learning technology to maintain mitigationpolicies that can detect and mitigate threats and policy violations via these agents.
Distributed Architecture
Learning Network License uses a fully distributed architecture. Agents are placed at the edges of your network, located in containerson a router, such as in branch office locations, where they monitor your network locally and report any anomalous activity back tothe controller.
Each agent becomes uniquely customized to its environment, using machine learning algorithms and techniques to learn what isnormal (baseline), and consequently detect anomalies. Each agent autonomously models traffic characteristics thanks to various datafeeds such as NetFlow records, deep packet inspection (DPI) of raw packets (such as DNS), and local states available on the networkelement.
Agents may also be used to mitigate anomalous activity by installing drop policies on the host network element for anomalous traffic.The Learning Network License architecture is highly scalable. Each agent builds its own models, avoids forwarding heavy trafficover the WAN for centralized analysis, and is highly lightweight in terms of memory and CPU consumption.
Centralized Management and Analysis
The controller is the user’s point of entry to Learning Network License. It is a highly scalable application running in the datacenterthat orchestrates the agents. The controller aggregates and stores information that the agents provide, and increases their context withinformation from different sources, such as threat intelligence from Identity Services Engine (ISE) and Platform Exchange Grid(pxGrid), Cisco's Talos Security Intelligence and Research Group (Talos), and DNS transaction details. It provides a way to retrieveall information for analysis and gives the user the ability to control the system and provide feedback to agents.
2
Anomaly Detection
Anomaly detection is the ability for a system such as Learning Network License to build a complex representation (model) of normaltraffic, capturing potentially a very high number of dimensions (time of day, nature of traffic, number of packets per flow, flowduration, time of day, unseen traffic, etc.) with high granularity. The system then uses these models to detect “outliers” or anomalies,used in turn to detect security attacks and vulnerabilities. Such systems make extensive use of machine learning algorithms, usually(but not exclusively) unsupervised.
Relevance Learning
Relevance Learning is crucial to Learning Network License. False Positives (FP) usually refer to events that have been incorrectlydetermined as anomalous by anomaly detection (AD). For example, if a system is trained to recognize a car and misclassifies a bikeas a car, this is said to be a FP.
In the general context of AD, the notion of FP is usually subtler, and may encompass both a true misclassification (from a machinelearning standpoint) and events that are irrelevant for the user, which may be subjective. In order to allow such a system to constantlyimprove its efficacy by raising anomalies that are relevant for the user, it makes use of a notion of relevance and builds an internalrelevance model using machine learning algorithms.
Upon reviewing an anomaly, the user has the ability to provide like/dislike feedback, allowing Learning Network License to learnthe user relevance and adapt itself so as to constantly improve the relevance of the anomalies raised by the system. This feedback isextremely useful for the system to constantly improve how it reports anomalies.
Mitigation Policies
Agents may be used not only for AD, but also for anomaly mitigation. Anomalies are reported by each agent to the controller, wheredetail is provided in order to fully understand the nature of the anomalous activity. Once the anomalous activity is understood, theuser may choose to take action to prevent the anomalous traffic from being forwarded through the network, where it may potentiallydo harm.
The controller allows the user to select a mitigation action for an anomaly. For example, the user may choose to drop the anomaloustraffic on the local router adjacent to the detecting agent. Alternatively, the user may choose to drop all traffic to or from an anomaloushost wherever it is seen in the network. Thousands of agents across the network may be informed to take mitigation action locally,to stop anomalous activity wherever it may be seen. Mitigation policies, with the corresponding action, may be installed for a fixedduration of time, after which they are automatically removed, or they may be installed indefinitely until further action is taken by theuser to remove them.
External System Integration
The Learning Network License system takes advantage of additional threat intelligence information available in the network to provideadditional insights into anomalous activity.
If you have deployed Cisco’s Identity Services Engine (ISE), the controller communicates with ISE via the pxGrid API to ingest arich set of personalized information regarding network users, their locations, and other attributes. This database of information iscontinually updated and consulted as anomalous activity is detected in your network to provide finer detail regarding offending hosts,possibly even identifying the name of the user, his current location (e.g. switch and switch port to which he is connected), etc.
The controller also takes advantage of a Talos database containing IP addresses known to have been involved in anomalous activityin the past, including the nature of that activity. The Talos database is an additional source of threat intelligence information, providingadditional detail for Learning Network License anomalies.
Brand MappingDuring the installation process, and when using the controller web UI, branding may be different than the branding presented in thedocumentation. See the following table for brand naming conventions.
Related DocumentationDownload the following documents at http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.html for information on upgrading and configuring your system:
Documentation UpdatesNote the following regarding the documentation:
• When accessing the documentation at http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.html, the HTML content for a given book or chapter may appear twice in the link. The PDFversions of the documentation do not display this behavior.
• The datasheet at http://www.cisco.com/c/en/us/products/collateral/security/stealthwatch-learning-network-license/datasheet-c78-737494.htmlmay not contain the proper requirements for the controller. Cisco recommends configuring a controllerVM on an ESXi host managing 1-50 agents with 24 GB of RAM, 8 vCPUs, and 400 GB of hard disk storage. For a controlleron an ESXi host managing 51-1000 agents, Cisco recommends 64 GB of RAM, 16 vCPUs, and 4 TB of hard disk storage.
Learning Network License OVA File DownloadDownload the Learning Network License OVA files at http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.html for installation. See the Cisco Stealthwatch LearningNetwork License UCS E-Series Blade Server Installation Guide and Cisco Stealthwatch Learning Network License Virtual ServiceInstallation Guide and for more information on installation procedures.
Learning Network License controller, which manages up to1000 agents.
sln-sca-k9-1.0.ova
Learning Network License agent, deployed as a virtual serviceto a Network Element's NIM-SSD, which detects anomaliesin traffic and applies mitigations to the host Network Element
sln-dla-44xx-cont-150Gs-3Gr-k9-1.0.ova
Learning Network License agent, deployed as a virtual serviceto a Network Element's bootflash, which detects anomalies intraffic and applies mitigations to the host Network Element
sln-dla-44xx-cont-250Ms-3Gr-k9-1.0.ova
Learning Network License agent, installed on a UCS E-Seriesblade server, which detects anomalies in traffic and appliesmitigations to the host Network Element
sln-dla-ucse-k9-1.0.ova
Web Browser and Screen Resolution Compatibility
Web Browser Compatibility
The user interface has been tested on the browsers listed in the following table. Cisco recommends using Google Chrome to accessthe controller web UI.
Table 3: Supported Web Browsers
Browser
Google Chrome (Version 51 or greater, 64-bit)
Mozilla Firefox (Version 45 or greater)
5
You cannot use certain versions of the vSphere Web Client Integration Plugin for Learning NetworkLicense-supported versions of Google Chrome to deploy VMs. The web client continually prompts youto reinstall the plugin when you attempt to deploy the VM. See https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2114800 for more information.
To deploy VMs:
Note
• download the standalone vSphere Client, or
• upgrade your vCenter Server to Version 5.5 Update 3a, or
• install the plugin for Mozilla Firefox.
Screen Resolution Compatibility
Cisco requires selecting a screen resolution that is at least 1200x800 pixels. The controller web user interface is incompatible withlower resolutions. Higher resolutions optimize the display.
Important Update and Compatibility NotesTo upgrade your deployment to a newer version, first deploy a newer version controller. Migrate your configuration and databasesettings from the older version controller to the newer version controller, and restart the services on the newer version controller.Then remove the older version controller. Because you migrated the database, the newer version controller manages all the sameagents that the older version controller managed. See Controller Upgrade Overview, on page 7 for more information.
To complete the update, use the controller to remotely upgrade your agents installed on UCS E-Series blade servers and deployed asvirtual services. See Upgrading Agents Installed on a UCS E-Series Blade Server, on page 31 and Upgrading Agents Deployed asVirtual Services, on page 20 for more information.
Upgrade PrerequisitesDownload the upgrade files at http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.html:
• sln-sca-k9-1.0.ova - the new version controller OVA
• sln-dla-44xx-cont-150Gs-3Gr-k9-1.0.ova - the new version agent OVA for virtual service deployment to an ISR's NIM-SSD
• sln-dla-44xx-cont-250Ms-3Gr-k9-1.0.ova - the new version agent OVA for virtual service deployment to an ISR's bootflash
• sln-dla-ucse-k9-1.0.tgz - the new version agent gzipped upgrade package for installing on a UCS-E server
During the upgrade process, the ESXi hypervisor running the controller will run both the old version controller and the new versioncontroller at the same time. Ensure you have enough space to run both VMs.
Upgrading the ControllerUpgrade the controller by migrating your current configuration settings and database from your existing controller to a new versioncontroller. Migrating your controller settings allows you to manage the existing agents without reconfiguring the controller/agentconnection.
Downgrading your controller version is not supported. If you need to downgrade your controller, contactCisco Support.
Note
Procedure
Step 1 Download the new version controller OVA. See Upgrade Prerequisites, on page 6 for more information.Step 2 Disable all managed agents on the controller. See Disabling Agents on the Controller, on page 7 for more information.Step 3 Backup the existing controller database. See Controller Database Backup, on page 8 for more information.Step 4 Download the existing controller database backup and configuration files. See Controller Configuration Backup, on page
9 for more information.Step 5 Deploy the new version controller OVA to the ESXi host. See Controller Deployment, on page 12 for more information.Step 6 Upload the controller database backup and configuration files to the new version controller. See Controller Configuration
and Database Migration, on page 18 for more information.Step 7 Migrate the controller database to the new controller. See Migrating the Controller Database, on page 18 for more
information.Step 8 Uninstall the old version controller. See Controller Removal from an ESXi Host, on page 19 for more information.
Controller Upgrade OverviewThe controller upgrade involves migrating the existing controller's configuration files and database to the new version controller.
On the existing controller, disable all agents, stop the controller processes, then backup the database to a .gz archive file. Downloadthe database archive and various controller configuration files.
Then, deploy the new version controller OVA to the ESXi host, and perform initial configuration. Upload the database archive andcontroller configuration files to the new controller, and start the controller's processes to migrate the database.
Finally, uninstall the old version controller from the ESXi host.
Disabling Agents on the Controller
Before you backup controller files, disable all managed agents.
Before You Begin
• Log into the controller web UI.
7
Procedure
Step 1 Select DLAS.Step 2 Click Disable to disable a agent, then click Continue.Step 3 Repeat the previous step for each managed agent.
What to Do Next
• Backup controller files and settings, as described in the next section.
Controller Backup
The controller stores anomalies and other related information in the database. Backing this up to a .gz archive file allows you tomigrate your system's anomalies to the new version controller.
The system saves general controller settings, Smart Licensing settings, and pxGrid integration settings in various configuration files.It also stores public key certificates for the controller, Smart Licensing, and pxGrid integration. Migrating these files preserves yoursystem and configuration settings, and allows you to establish trusted connections without regenerating certificates.
You can also save your existing log files and store them in another location, or move them to the new version controller.
Controller Database BackupTo backup the database, first stop the controller's processes using the sca.sh shell script, then use the script to create a .gz archivefile containing the database's contents. The script creates the file in a backups folder, with the current data and time in the file name.If you generate multiple backups, migrate only the most recent database backup file.
Backing Up the Controller Database
Before You Begin
• Log into the existing controller VM console.
Procedure
PurposeCommand or Action
Change to the /SCA directory.cd /SCA
Example:
Step 1
user@host:~$ cd /SCA
Stop the controller processes../sca.sh stop
Example:
Step 2
user@host:~/SCA$ ./sca.sh stop
Generate an archive file containing the databasebackup.
./sca.sh backup
Example:
Step 3
user@host:~/SCA$ ./sca.sh backup
8
PurposeCommand or Action
Change to the /backups directory.cd backups
Example:
Step 4
user@host:~/SCA$ cd backups
List the contents. Note the name of the most recentarchive file.
ls
Example:
Step 5
user@host:~/SCA/backups$ ls
What to Do Next
• Use an FTP client to download the database archive file and other configuration files and public key certificates, as describedin the next section.
Controller Configuration Backup
The controller stores separate configuration files, log files, and public key certificates for the controller and controller web UI, SmartLicensing, and pxGrid integration. At a minimum, you must download the controller and controller web UI configuration files andcertificates. If you registered your controller with Smart Licensing, you must download those configuration files and certificates.Similarly, if you configured pxGrid integration, you must download those configuration files and certificates for migration.
You do not need to save the log files for migration. You can migrate them, or copy them to external storage for future analysis. Thenew controller generates additional log files once you start its processes and configure logging.
Controller Configuration Files
Configuration Files
Several of the files may share the same name.When you download the files, also recreate the directory structure, to prevent overwritingfiles.
When you copy log files to the new version controller, the loggers append new log information in the files, rather than overwriteexisting log information.
Controller Database
Table 4: Controller Database Archive
DescriptionFile PathFile Name
archive file containing the controllerdatabase contents
/SCA/backupssln-db-<datetimestamp>.sql.gz
9
Controller and Controller Web UI Configuration
You do not need to migrate the log files to the new version controller. If you want to migrate your logging settings, migratersyslog.conf and 50-default.conf.
If you used your enterprise's public key certificates to connect to the controller web UI, or you changed any controller web UI settings,such as port used for connections, authentication settings, and so on, download nginx.conf.
If you migrate the public key certificates, you do not need to regenerate certificates on the new version controller when you run thesetup script.
Table 5: Controller and Controller Web UI Configuration Files
DescriptionFile PathFile Name
configuration file with general controllersettings
/SCAsca.conf
public key certificate used to establishcomunications with agents
/SCAsca_cert.pem
trust store containing agent public keycertificates
/SCAtruststore.jks
trust store containing controller publickey certificates
/SCAkeystore.jks
controller log files/SCA/logs*.log
configuration file with rsyslog settings/etcrsyslog.conf
public key certificate used to establishcommunications with controller web UIusers
/VIZ/confslnviz.pem
private key associated with the publicslnviz.pem public key certificate
/VIZ/confslnviz.key
controller web UI log files/VIZ/conf/logs*.log
controller web UI configuration file/VIZ/confnginx.conf
10
Smart Licensing Configuration
You do not need to migrate the Smart Licensing configuration files if you have not registered your controller with Smart Licensing.You do not need to migrate the log files to the new version controller.
Rather than copy individual files, you can copy the /SCA/services/sa-server directory, and all files in the directory.
Table 6: Smart Licensing Configuration Files
DescriptionFile PathFile Name
configuration file with Smart Licensingsettings
/SCA/services/sa-serversa.properties
Smart Licensing logging configurationfile
/SCA/services/sa-serverlog4j.properties
public key certificate used to configurewith the Licensing Authority
Backing Up the Controller FilesAt a minimum, you must backup the database archive and the controller non-logging files. If you registered your controller withSmart Licensing, backup the Smart Licensing configuration files. If you configured pxGrid integration, backup the pxGrid integrationconfiguration files.
Before You Begin
• Install an FTP client on the host to which you will download the backup files.
Procedure
Step 1 Using the FTP client, connect to the existing controller VM.Step 2 Using Controller Configuration Files, on page 9 as a guide, transfer the files you need for upgrade.
Controller Deployment
Cisco provides the controller as a downloadable OVA file. You can deploy this OVA file to a host running an ESXi hypervisor.
The first time you log into the virtual machine, the system prompts you to change the default administrator password.
Deploying the OVA File
Before You Begin
• Download the OVA file.
• Download VMware vSphere Client from https://my.vmware.com/web/vmware/downloads and install it.
Step 1 Open vSphere Client, and connect to the ESXi hypervisor where you want to install the OVA file.Step 2 Select File > Deploy OVF Template.Step 3 Click Browse to select your OVA file, then click Next.Step 4 Review the OVF Template Details, then click Next.Step 5 Enter a Name, select an inventory location, then click Next.Step 6 Click the Thick Provision Lazy Zeroed radio button, then click Next.Step 7 Select a Destination Network from your inventory to map to a Source Network. You can map the following default
networks, then click Next.
• eth0 to Main Network
• eth1 (disconnected) to Alt1 Network
• eth2 (disconnected) to Alt2 NetworkIf you only need to configure eth0, you canmap eth1 and eth2 to the same network.Note
Step 8 Review your deployment settings and click Finish.The deployment may take 30minutes to an hour or longer, depending on your environment.Note
Step 9 Click Close after the deployment completes.
What to Do Next
• Power on the virtual machine and login, as described in the next section.
Powering On the Virtual Machine
Before You Begin
• Deploy the OVA file to the ESXi hypervisor, as described in the previous section.
Procedure
Step 1 Open vSphere Client, and connect to the ESXi hypervisor where you deployed the virtual machine.Step 2 Select Home > Inventory > VMs and Templates.Step 3 Select the virtual machine from the navigation tree.Step 4 Select Inventory > Virtual Machine > Power > Power On.Step 5 Click the Console tab, then click in the console pane to shift your focus to the virtual machine console.
To shift your focus from the virtual machine console to your local host, pressCtrl-Alt.Note
Step 6 Log in with the default administrator username (sln) and the default administrator password (cisco). When prompted,change the default administrator password.
13
What to Do Next
• Run the setup script to configure the virtual machine, as described in the next section.
Controller Setup Script
The controller setup script directs you to configure the following controller settings:
Table 8: Controller Setup Script Settings
DescriptionRequired?Setting
basic interface configurationyeseth0 interface
IP address and hostname to access thecontroller web UI
yescontroller web UI IPv4 address andhostname
enables SSH loginrecommended, but not requiredSSH service
synchronizes time among controller,agent, and ISR
yesNTP server
encrypts management communicationbetween controller and agent
yescontroller self-signed certificate,generated or provided
encrypts connections to the controllerweb UI
yescontroller web UI self-signed certificate,generated or provided
recommended, but not requireddomain suffix search list
After you configure these settings, you can log into the controller web user interface to verify your settings. Note that the interfacedoes not display anomalies, as the controller does not yet manage any agents.
Configuring the Controller with the Setup ScriptIf you need multiple interfaces on multiple subnets, when configuring networking, you can also configure eth1 and eth2.
Before You Begin
• Log into the controller VM console.
14
Procedure
PurposeCommand or Action
Change directories.cd ~/
Example:
Step 1
user@host:~$ cd ~/
Run the setup script.sudo ./setup-system at the command promptto run the setup script. Enter the administratorpassword if prompted.
Configure the eth0 interface.1 (configure eth0)Step 4
Configure the controller VM hostname. You must enter a fullqualified domain name.
hostname, then hostname, then y to confirmStep 5
Configure the interface's IPv4 address, along with a netmaskand gateway.
ipv4, then ipv4-address, then ipv4-netmask,then ipv4-gateway, then y to confirm
Step 6
Modify the virtual machine's list of DNS servers.dns, then dns-servers, then y to confirmStep 7
If you want to configure the domain suffix search list, run thesearch command.
search, then domain-suffixes, then y to confirmStep 8
View the interface's network settings, hostname, and DNSsettings. If any of these are missing or incorrect, repeat thatconfiguration.
viewStep 9
Save your changes and continue with interface configuration.exitStep 10
Exit interface configuration and continue.4 (exit interface configuration)Step 11
Enable SSH login.y (enable SSH login)Step 12
Configure NTP servers used to synchronize time between thecontroller and agent. Enter a space-delimited list of NTP serverfully-qualified domain names (FQDNs) or IPv4 addresses.
y, then ntp-servers, then y to confirmStep 13
Generate a controller self-signed certificate, used for encryptingcontroller/agent communication.
y (generate certificate)Step 14
Generate a controller web UI self-signed certificate, used forencrypting user connections to the controller web user interface.
y (generate certificate)Step 15
Optionally, specify the certificate subject distinguished name(DN).
y (specify the distinguished name)Step 16
Optionally, provide the DN information.country-code, then state, then locality, thenorganization, then organizational-unit, thencommon-name, then email
Step 17
15
Controller Setup Script ExampleThe following displays excerpts from running the setup script, along with sample user inputs:It's best to set up networking for eth0, and also DNS servicesat this point.
Do you want to set up networking now? (y or n)[n]y
...
Enter an action (exit to exit): ipv4
Change IPv4 Address, Netmask, and Gateway
Interface eth0 is manually configured.It will be changed to a 'static' configurationusing with the parameters provided.A return (with no data) will cause the entry to remain unchanged.enter new IPv4 address (w/optional "/masklen") [ ]: 209.165.201.2enter new IPv4 netmask [ ]: 255.255.255.224enter new IPv4 gateway (or "-" to delete) [ ]: 209.165.201.1
Enter new hostname [hostname]: newhostnameThe hostname will be set to: newhostname
is this correct? (y or n)[n] y
...
Enter an action (exit to exit): dns
Change DNS Servers
Enter multiple DNS server IP addresses separated by spaces.Enter new DNS Servers (or "-" to delete) []: 209.165.202.132 209.165.202.133
The DNS Servers will be set to: 209.165.202.132 209.165.202.133
is this correct? (y or n)[n] y
...
Enter an action (exit to exit): search
Change the DNS Suffix Search List
The DNS Search List is a list of one or more domain suffixes,such as 'sales.example.com example.com', to allow identifyinghosts using a relative name, instead of a fully-qualified name.
Enter new DNS Search List []: sales.example.com example.com
The DNS Search List will be set to: sales.example.com example.com
DNS Server 1: 208.67.222.222DNS Server 2: 208.67.220.220
Current interface: eth0
...
Enter an action (exit to exit): exit
...
Checking SSH service status
Do you want to enable SSH service now? (y or n)[n] y
...
Use of NTP synchronization between the SCA, DLAs, and Network Elementsis critical to the operation of SLN.
Do you want configure NTP servers now? (y or n)[n] y
Please enter a space-separated list of NTP serverFQDNs or IP addresses: 209.165.202.134 209.165.202.135
This will remove any configured NTP servers and add thespecified servers: 209.165.202.134 209.165.202.135
Do you want to proceed with this change? (y or n)[n] y
...
Do you want to make a self-signed certificate for the SCA?(y or n)[n] y
...
Do you want to generate a different Viz certificate?(y or n)[n] y
...
A simple Distinguished Name (DN) subject of "CN=Cisco_SLN_VIZ" will beused in the certificate unless you prefer to specify the DN components.Do you want to interactively specify the cert subject DN?(y or n)[n] y
...
Country Name (2 letter code) [AU]: USState or Province Name (full name) [Some-State]: StateLocality Name (eg, city) []: CityOrganization Name (eg, company) [Internet Widgits Pty Ltd]:Example CorporationOrganizational Unit Name (eg, section) []: Example SectionCommon Name (e.g. server FQDN or YOUR name) []: www.example.comEmail Address []: [email protected]
...
17
Done. This script may be re-run to re-do basic setup if needed
Controller Configuration and Database Migration
After you deploy the new version controller, upload the configuration files and database archive to the same file paths. Migrate thedatabase archive to the new version controller, then restart the controller processes.
If you copied logging configuration files, restart the rsyslog service.
Uploading Backed Up Files to the Controller
Procedure
Step 1 Using the FTP client, connect to the new controller VM.Step 2 Using Controller Configuration Files, on page 9 as a guide, transfer the files you need for upgrade to the correct file
paths.
Migrating the Controller Database
Before You Begin
• Connect to the new version controller VM console.
• Upload the database archive file to the new version controller.
Procedure
PurposeCommand or Action
Change to the /SCA directory.cd ~/SCA
Example:
Step 1
user@host:~$ cd ~/SCA
Stop the controller processes../sca.sh stop
Example:
Step 2
user@host:~/SCA$ ./sca.sh stop
Remove existing logs and create an empty controllerdatabase.
./sca.sh clean
Example:
Step 3
user@host:~/SCA$ ./sca.sh clean
Migrate the database archive to the new versioncontroller database.
./sca.sh restore
Example:
Step 4
user@host:~/SCA$ ./sca.sh restore
18
PurposeCommand or Action
Backup the controller database and upgrade the databaseschema.
./sca.sh dbupgrade
Example:
Step 5
user@host:~/SCA$ ./sca.sh dbupgrade
Start the controller processes../sca.sh start
Example:
Step 6
user@host:~/SCA$ ./sca.sh start
Restarting the rsyslog Service
Procedure
PurposeCommand or Action
Restart the rsyslog service.From the controller VM console on the ESXi hypervisor, service rsyslog
restart
Step 1
Example:user@host:~$ service rsyslog restart
Controller Removal from an ESXi Host
Removing a controller from an ESXi host requires connecting to the ESXi host and deleting the controller VM.
Removing a VM from an ESXi Host
Procedure
Step 1 Open vSphere Client, and connect to the ESXi hypervisor where you want to remove the VM.Step 2 Select View > Inventory > Hosts and Clusters.Step 3 Highlight the VM you want to remove.Step 4 Select Inventory > Virtual Machine > Power > Power Off and wait for the VM to power off.Step 5 Right-click the VM you want to remove, and select Delete from Disk. Confirm the deletion.
Agent Remote UpgradeYou can upgrade your Learning Network License deployment's agents from the controller. Each type of agent has a different upgradeprocedure:
19
• agents deployed as a virtual service - Download the new version of the agent OVA file. Modify the install.yaml configurationfile to point to the new agent OVA file, then run the installation_auto.py script to update the agents.
• agents installed on a UCS E-Series blade server - Download the agent upgrade .tgz tar file. Modify the upgrade.yaml agentupgrade properties file to point to the upgrade tar file, and to the agents to upgrade. Run the upgrade_auto.py script to updatethe agents.
You can upgrade all agents deployed as a virtual service at one time. You can upgrade all agents installed on UCS E-Series bladeservers at one time.
Upgrading Agents Deployed as Virtual ServicesYou can use an controller install script, and update a properties file's settings, to upgrade your agents deployed as virtual services.Update the properties file to point to the new agent OVA file, and change any settings as necessary. The install script uses the propertiesfile to deploy the new agent OVA to all configured ISRs, perform necessary configuration, and manage the agents with the controller.You can upgrade multiple agents at once, depending on how you modify the configuration file.
Procedure
Step 1 Download the OVA file to the controller.Step 2 Update the install and upgrade properties file with the updated file path information, and optionally change any existing
ISR and virtual service configuration information.Step 3 Run the install script to perform the upgrade.
Install Script Overview
Running the agent install script (installation_auto.py) requires configuring an agent install and upgrade properties file(install.yaml) with agent, ISR, and network settings. You can configure the file to deploy multiple agents at one time. This filecontains global settings, which apply to all deployed agents, and branch-specific settings, which apply only to one ISR and agent.
When you run the install script, it reads the properties file, and does the following for each agent:
• uploads the OVA file to the ISR
• configures flexible NetFlow for Learning Network License
• configures a virtual service named sln and deploys the agent
• configures ISR and agent network settings
• adds the new agent to the controller
Agent Install and Upgrade Properties File Upgrade OverviewThe agent install and upgrade properties file (install.yaml) is in YAML format, and stores settings as key-value pairs. The installscript uses these settings to upgrade 1 or more agents at a time. The file stores global settings, which apply to each agent upgrade,and per-branch settings, which are specific to a specific ISR and agent. You define one set of global settings per file, and one set ofper-branch settings for each agent you want to upgrade.
20
If you previously deployed agents using the agent properties file, and are now using it to upgrade agents, you must change thedla_ova_copy: src_ova_path setting to point to the new OVA file, and the other dla_ova_copy settings as necessary. You canmodify the other settings as necessary for the upgrade.
If you installed agents as virtual services manually, and you named your virtual service something otherthan sln, or your virtual interfaces something other than VirtualPortGroup1 and VirtualPortGroup2,you must manually remove those, then run the upgrade script.
Note
You can define multiple usernames and passwords in the properties file, which the install script uses during the upgrade process. Ifyou comment out a password property by placing a pound sign (#) at the beginning of that line, the script prompts you for thatpassword while running. However, if you comment out the dla_password or ne_password property as a global setting, the scriptprompts you for the first agent where the property is not defined. It then uses the password you enter for every agent which does nothave dla_password or ne_password defined.
Usernames and passwords stay in the properties file after you finish upgrading the agents. Remove thisinformation after the upgrade completes.
Note
Agent Properties File Settings
Global Property Settings
The following are the global property settings. You can define any of these per-branch, except for the sca_webui_login settings. Ifyou define dla_ova_copy: src_host, dla_ova_copy: src_username, or dla_ova_copy: src_password per-branch, you must alsodefine each setting globally. Note that the per-branch setting overrides the global setting.
When you run the script, it prompts you for any password you do not define.
The syntax below is presented as an example. Do not copy and paste this into the property file. Improperformatting and spacing in the property file will cause the script to fail.
n/an/agroup of properties used tocopy the agent OVA from asource host that is capable ofSCP file copying, such as thecontroller, to the ISR
dla_ova_copy
yesIPv4 address or DNS nameIP address of the hostcontaining the agent OVA,from which the script willcopy the file
src_host
yesstringusername the script uses to loginto the Linux console of thehost containing the agent OVA
src_username
yesstring, cannot be NULLpassword for src_usernamesrc_password
yesstring, must contain filepathand filename
filepath on the source hostwhere the agent OVA islocated, such as/home/sln/agent.ova, inquotation marks
src_ova_path
yesbootflash or harddisk
Specify bootflash only ifyour ISR does not have a harddrive installed. If your ISR hasa hard drive, and you specifybootflash, the script ignoresthe setting and uploads to thehard drive.
bootflash to upload the agentOVA to the ISR's flashmemory, or harddisk toupload the agent OVA to theISR's hard drive
dst_store
Table 10: vir_portgroup_1 Properties
Required?ValidationDescriptionProperty
n/an/agroup of properties used tocreate the VirtualPortGroup1 virtual interface
vir_portgroup_1
22
Required?ValidationDescriptionProperty
yesstringname of an interface on yourISR through which thecontroller can reach the agent.The script uses this toconfigure the NetworkElement side of the ctl/mgmtinterface.
ip_unnum
no, see Configuring VRFForwarding on the ISR, onpage 27 for more information
stringname of the non-default VRFinstance on your ISR that theip_unnum interface belongs to.If you added the interface to anon-default VRF instance, youmust configure this so thescript can properly copy theOVA file to the router.
vrf_forwarding
Table 11: vir_portgroup_2 Properties
Required?ValidationDescriptionProperty
n/an/agroup of properties used tocreate the VirtualPortGroup2 virtual interface
vir_portgroup_2
yesIPv4 addressNetwork Element IP addresson the virtual-service DataTransfer interface. The scriptuses this to configure theNetwork Element side of theData Transfer interface.
Because traffic over thisinterface does not leave therouter, specify a private IPaddress.
ne_ip
nosubnet maskThe netmask for ne_ipne_mask
yesIPv4 addressAgent IP address on thevirtual-service Data Transferinterface. The script uses thisto configure the agent side ofthe Data Transfer interface.
Because traffic over thisinterface does not leave therouter, specify a private IPaddress.
dla_dat_ip
23
Required?ValidationDescriptionProperty
nosubnet maskthe netmask for dla_dat_ipdla_dat_mask
Table 12: ne_username Property
Required?ValidationDescriptionProperty
yesstringa username with a privilegelevel of 15 that the installscript uses to log into the ISR,to execute CLI commands
ne_username
Table 13: ne_password Property
Required?ValidationDescriptionProperty
no, the script prompts you ifnot defined
If you do not define thene_password property as aglobal property, the scriptprompts you the first time itattempts to deploy an agentwhere the configured branchproperties also do not containne_password. However, thescript reuses that password forevery remaining agentdeployment for whichne_password is not defined.
string, cannot be NULLthe password for ne_usernamene_password
Table 14: ne_port Property
Required?ValidationDescriptionProperty
nointegerthe TCP port the upgradescript uses when connectingvia SSH to the ISR. Ifundefined, this defaults to 22.
ne_port
24
Table 15: dla_password Property
Required?ValidationDescriptionProperty
no, the script prompts you ifcommented out
If you do not define thedla_password property as aglobal property, the scriptprompts you the first time itattempts to deploy an agentwhere the configured branchproperties also do not containdla_password. However, thescript reuses that password forevery remaining agentdeployment for whichdla_password is not defined.
string, cannot be NULL, mustbe a minimum of 6 characters
password configured for theagent admin account when thescript deploys the agent, toreplace the default adminpassword
dla_password
Table 16: dla_ne_login Properties
Required?ValidationDescriptionProperty
n/an/agroup of properties used todefine agent credentials to loginto the Network Element
dla_ne_login
yesstringusername the agent uses to loginto the ISR to learn aboutinterfaces and installmitigations.
username
no, the script prompts you ifcommented out
string, cannot be NULLpassword for the agentusername
password
Table 17: sca_webui_login Properties
Required?ValidationDescriptionProperty
n/an/agroup of properties used todefine install script credentialsto log into the controller webUI
sca_webui_login
yesstringusername the script uses to loginto the controller web UI toadd agents to the controller,and configure agent attributes.
username
25
Required?ValidationDescriptionProperty
no, the script prompts you ifcommented out
string, cannot be NULLpassword to log into thecontroller.
password
Branch-Specific Property Settings
The following are the branch-specific property settings. For each new set of branch settings, you must preface them with a dash (-).
The syntax below is presented as an example. Do not copy and paste this into the property file. Improperformatting and spacing in the property file will cause the script to fail.
The dla_description and ne_ctl_ip properties can only be updated through the install script on initial agent installation. If youwant to update the agent description after installation, modify it in the controller web UI. See theCisco Stealthwatch Learning NetworkLicense Configuration Guide for more information.
Table 18: branches Properties
Required?ValidationDescriptionProperty
n/an/agroup of settings used toconfigure a specific agent ona branch Network Element
branches
yes
You can only modify this oninitial agent installation.
IPv4 addressIP address for the physicalinterface defined forvir_portgroup_1: ip_unnum
that the script uses to connectto the network element, and toadd an agent to the controller
ne_ctl_ip
yesIPv4 addressa routable IP address for theagent on the control interfacethat the ne_ctl_ip can reach,so the controller can reach theagent
dla_ctl_ip
yessubnet maskmask for dla_ctl_ipdla_ctl_mask
26
Required?ValidationDescriptionProperty
yesIPv4 addressdefault gateway the agent usesfor non-local destinations,generally the same IP addressas ne_ctl_ip
dla_ctl_gw
yesstringagent hostname, used by thescript to generate uniquenames for per-branch log files,used by the controller toconnect to the dla_ctl_ip, andused by the controller web UIas the agent's unique name
dla_hostname
no
if undefined, the scriptpopulates the description withthe dla_hostname value, or thedla_ctl_host_sca IP address ifyou defined it
You can only modify this oninitial agent installation.
string, up to 256 characters,surrounded by doublequotation marks (")
agent descriptiondla_description
yesa comma-delimited array,surrounded by brackets ([]),with each interface namesurrounded by single quotes(')
a list of ISR branch-facinginterfaces on which the scriptconfigures Flexible NetFlowfor Learning Network License
ne_netflow_interfaces:ifnames
noIPv4 addressagent IP address used by thecontroller to reach the agent ifthe agent hostname is notresolvable in DNS, or if theagent control IP address isbehind a NAT or PAT. If youdo not define this, the scriptadds the agent to the controllerusing the dla_hostname value.
dla_ctl_host_sca
Configuring VRF Forwarding on the ISRIn the install.yaml properties file, if you added the vir_portgroup_1: ip_unnum interface to a non-default VPN routing andforwarding (VRF) instance on your ISR, you must define the vir_portgroup_1: vrf_forwarding property in the file. This allowsthe script to properly copy the .ova file to the router using SCP.
On the ISR, you must also configure the vir_portgroup_1: ip_unnum interface as the source address for an SSH client device, sothe script can properly copy the .ova file.
27
Before You Begin
• Define vrf_forwarding in the install.yaml properties file. See Agent Properties File Settings, on page 21 for more information.
• Log into the ISR console.
Procedure
PurposeCommand or Action
Enable privileged EXEC mode.enable
Example:Router> enable
Step 1
Enter global configuration mode.config t
Example:Router# config t
Step 2
Specify the ip_unnum interface as the source for an SSHclient device.
ip ssh source-interface <ip_unnum>
Example:Router(config)# ip ssh source-interfaceGigabitEthernet0/0/0
Step 3
Exit global configuration mode and return to privilegedEXEC mode.
exit
Example:Router(config)# exit
Step 4
Updating the Agent Install and Upgrade Properties File for Upgrades
Before You Begin
• Log into the controller VM console.
Procedure
PurposeCommand or Action
Navigate to the /install_upgrade/containerdirectory.
cd /install_upgrade/container
Example:user@host:~$ cd /install_upgrade/container
Step 1
Rename the install.yaml.example file toinstall.yaml.
If you have not previously modified the properties file for aninstallation or upgrade, run mv install.yaml.example
Update the properties file with the OVA filelocation settings.
Update the configuration file dla_ova_copy settings, includingdla_ova_copy: src_ova_path.
Step 4
Save your changes and close the file.Press Esc, then enter :wq! and press Enter.Step 5
What to Do Next
• Run the install script to upgrade the agents, as described in Running the Install Script, on page 30.
Install Script OperationThe install script (installation_auto.py) deploys agents as virtual services based on settings in the agent install and upgradeproperties file (install.yaml).
Based on the properties file settings and the script options you select, the script attempts to deploy agents in batches, copying the.ova file to the ISR, then deploying it.
The script copies the .ova file to the ISR based on the properties file settings. However, if you copy the.ova file to the ISR, and configure the properties file setting to upload the .ova to the same filepath, thescript deploys the agent using the .ova file already on the ISR.
Note
As the script runs, it displays progress updates on the console every 10 seconds. These updates display the total number of agents todeploy, the number in progress, and the number that succeeded and failed.
If you commented out password properties in the install.yaml properties file, the script prompts you during the progress updates.For agent passwords, if you did not define a global password, the first time the script deploys an agent without a password defined,it prompts you for the password, then uses this password for all remaining agents without a password defined. The script also logsits progress to several log files.
You can exit the script at any time by pressing Ctrl-C.
Install Script OptionsAppend the following options to the command line when running the script for the following functionality:
29
Table 19: Install Script Options
DescriptionOption
Configure the script to deploy this number of agents in a batchat one time.
The script defaults to deploying 50 agents in a batch. If younotice failed deployments when running the script, try loweringthe batch size.
-b <integer>
Reference the install.yaml properties file.-c install.yaml
Removes all Learning Network License configuration and thevirtual service from the ISR. If you want to upgrade your agentsto the same version, run the script using --clean_only first,then run the script without --clean_only.
--clean_only
Copies the .ova file specified in the properties file to thedestination filepath on the ISR, even if an .ova file with thesame name is present at that destination filepath.
-f
Deploy all agents configured in the properties file, even if theyhave been previously installed successfully.
If you do not define this option, the script only deploys agentsthat previously failed to deploy properly.
-i
Show help for options.-h
Perform local validation of the referenced properties file.-v
Perform validation of the referenced properties file, includingconnecting to the network element and validating interfacenames.
-V
Run a basic installation with the following command:python3 installation_auto.py -c install.yaml
Running the Install Script
Before You Begin
• Log into the controller VM console.
30
Procedure
PurposeCommand or Action
Navigate to the /container directory.cd /opt/cisco/sln/install_upgrade/container
Example:user@host:~$ cd /opt/cisco/sln/install_upgrade/container
Step 1
Run the installation_auto.py installscript.
installation_auto.py -c install.yaml, then enter your passwordwhen prompted
Provide passwords when prompted.If you did not update install.yaml with passwords, enter those whenprompted.
Step 3
Upgrading Agents Installed on a UCS E-Series Blade ServerYou can use an controller upgrade script, and update a configuration file's settings, to upgrade your deployment's agents installed onUCS E-Series blade servers. Download the .tgz upgrade file. Update the configuration file to point to the upgrade file, and the agentsto be modified. The upgrade script first verifies the code signing of the upgrade package. It then references the configuration file todeploy the upgrade package to all configured agents, shuts down the agent, removes pre-upgrade files and saves locally generatedfiles, upgrades the agent version, and starts the agent.
Procedure
Step 1 Download the .tgz file, then upload it to the controller. See UCS-E Agent Upgrade Package Overview, on page 31 formore information.
Step 2 Update the upgrade configuration file with the file path information and agent settings. See Agent Upgrade ConfigurationFile Overview, on page 33 for more information.
Step 3 Run the upgrade script to verify the upgrade package and perform the upgrade. See Upgrade Script Overview, on page36 for more information.
UCS-E Agent Upgrade Package Overview
The upgrade package for agents deployed to UCS E-Series blade servers is a .tgz gzipped tar file. The archive contains the followingfiles:
Table 20: Upgrade Package Contents
DescriptionFile Name
a Debian package that contains the upgrade filesciscosln-dla_<version>_amd64.deb
31
DescriptionFile Name
a signature file for the Debian packageciscosln-dla_<version>_amd64.deb.signature
a Python script used to verify the code signing, using the CiscoRoot CA M2 certificate (crcam2.cer) and Subordinate CAInnerspace CA SHA-512 certificate (innerspace.cer), eitherincluded as part of the controller install or downloaded fromCisco
cisco_x509_verify_release.py
a public key certificate signed by the Cisco Root CA M2 andSubordinate CA Innerspace CA SHA-512 certificates, used toverify the code signing
sln_pubkey.der
a text file that describes the upgrade package's contents, andhow to manually verify the code signing
README
You canmanually verify the code signing by running the cisco_x509_verify_release.py verification script. This file is also availableon the controller at /opt/cisco/sln/install_upgrade. See the README file for more information.
Downloading the Upgrade Package
Procedure
Step 1 In your web browser, navigate to http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.html.
Step 2 Download the .tgz upgrade package.
What to Do Next
• Upload the upgrade package to the controller.
Uploading the Upgrade Package to the Agent
Procedure
Step 1 Using an FTP client, connect to your controller.Step 2 Copy the upgrade package to the /opt/cisco/sln/install_upgrade/ucse directory.
What to Do Next
• Update the configuration file, as described in the next section.
Agent Upgrade Configuration File OverviewThe agent upgrade properties file (upgrade.yaml) is in YAML format, and stores settings as key-value pairs. The install script usesthese settings to upgrade 1 or more agents. The file stores global settings, which apply to all agent upgrade, and per-branch settings,which apply to a specific agent.
Update the global settings to point to the upgrade .tgz file. Optionally, you can define the administrator password, if it is the samefor all agents. The script checks code signing files installed with the controller, but you can also reference an alternative path for CAcertificates downloaded from Cisco.
The upgrade process requires agent passwords, which you can define in the configuration file. If you comment out the dla_passwordproperty by adding a pound sign (#) at the beginning of the line, the script prompts you for this information while running. Passwordsadded to the configuration file remain in the file after you finish upgrading the agents. Remove them after the upgrade completes ifthis is a concern.
You can define the agent password globally, per-branch, or both globally and per-branch. The script usesthe global agent password when upgrading a agent, unless the configuration file contains a per-branchagent password. If you do not define a global password, the first time the script attempts to update a agentwithout a password, it prompts you for the password. The script then reuses that password for everyremaining agent without a password.
Note
Agent Upgrade Properties File Settings
Global Property Settings
The following are the global property settings. If you do not define dla_password, the script prompts you for that information.
The syntax below is presented as an example. Do not copy and paste this into the property file. Improperformatting and spacing in the property file will cause the script to fail.
filepath and name of theupgrade package file on thelocal system, which theupgrade script uses to upgradethe agent
upgrade_pkg
33
Required?ValidationDescriptionProperty
nostring, must contain filepathand filename
filepath and name of the CiscoRoot CA M2 certificate inPEM or DER format, used forcode-signing verification. Ifcommented out, the scriptdownloads the certificate fromcisco.com.
ca_file
nostring, must contain filepathand filename
filepath and name of theSubordinate CA InnerspaceCA SHA-512 certificate inPEM or DER format, used forcode-signing verification. Ifcommented out, the scriptdownloads the certificate fromcisco.com.
sub_ca_file
no, prompted as the script runsif not defined
If you do not define thedla_password property as aglobal property, the scriptprompts you the first time itattempts to deploy an agentwhere the configured branchproperties also do not containdla_password. However, thescript reuses that password forevery remaining agentdeployment for whichdla_password is not defined.
string, cannot be NULLpassword for the username tolog into the agent via SSH.You can also specify thisper-branch.
dla_password
nointegerport used by the script to SSHlog into the agent
dla_port
nostringusername used by the script tolog into the agent via SSH. Ifcommented out, the script usessln.
dla_username
nostring, must contain filepathand filename
a filepath and name of acode-signing verificationscript the script uses to verifythe package. If commentedout, the script uses theverification script included inthe upgrade package.
code_signing_verify_script
34
Branch-Specific Property Settings
The following are the branch-specific property settings. You must preface each new set of branch settings with a dash (-).branches:
-dla_hostname: <dla-hostname>dla_ip: <dla-ip>
Table 22: Branch-Specific Properties
Required?ValidationDescriptionProperty
n/an/agroup of settings used toupgrade a specific agent on abranch Network Element
branches
yesstringagent hostname used by thescript to connect to the agentvia SSH, and to generateunique names for per-branchlog files.
dla_hostname
noIPv4 addressthe agent management IPaddress. If defined, the scriptconnects to this IP addressinstead of the agent hostname.
dla_ip
Updating the Agent Upgrade Properties File
Before You Begin
• Log into the controller VM console.
Procedure
PurposeCommand or Action
Navigate to the /ucs directory.cd /opt/cisco/sln/install_upgrade/ucse
Example:user@host:~$ cd /opt/cisco/sln/install_upgrade/ucse
Step 1
Rename the upgrade.yaml.example file toupgrade.yaml.
If you have not previously modified the properties file for an installationor upgrade, run mv upgrade.yaml.example upgrade.yaml.
Update the upgrade properties file.Update the upgrade properties file, using Agent Upgrade Properties FileSettings, on page 33 as a guide.
Step 4
Save your changes and close the file.Press Esc, then enter:wq! and press Enter.Step 5
What to Do Next
• Run the upgrade script to upgrade the agents, as described in Upgrading Agents Using the Upgrade Script, on page 37.
Upgrade Script OverviewThe upgrade script (upgrade_auto.py) upgrades agents based on settings in the agent upgrade properties file (upgrade.yaml).
The script first unpacks the upgrade package, and verifies that the package contains the necessary files. It then runs thecisco_x509_verify_release.py code signing verification script to verify the Debian package. The script downloads the Cisco RootCA M2 certificate (crcam2.cer) and Subordinate CA Innerspace CA SHA-512 certificate (innerspace.cer) from cisco.com. Thescript signs the included sln_pubkey.der certificate with the 2 CA certificates, and uses that to verify the code signing.
If your controller cannot access the internet, you can download the Cisco CA certificates from http://www.cisco.com/security/pki/ , upload them to the controller, then update the configuration file to pointto these certificates. If you manually download the certificates, check for and re-download updatedcertificates on a periodic basis.
Note
If the code signing verification is successful, based on the configuration settings and the options you select, the script attempts toupgrade agents. The script:
• uploads the Debian package over SCP to a agent
• shuts down the agent
• removes the prior version files, saving any locally-generated files
• installs the new version files to upgrade the agent
• starts the agent
As the script runs, it displays progress updates on the console every 10 seconds. These updates display the total number of agents toupgrade, the number in progress, and the number that succeeded and failed. If you did not provide agent passwords in the upgradeproperties file, the script prompts you during the progress updates. The script also logs its progress to several log files.
You can exit the script at any time by pressing Ctrl-C.
Append the following options to the command line when running the script for the following functionality:
Table 23: Upgrade Script Options
DescriptionOption
Configure the script to upgrade this number of agents in a batchat one time.
The script defaults to upgrading 50 agents in a batch. If younotice failed upgrades when running the script, try loweringthe batch size.
-b <integer>
Reference the upgrade.yaml agent upgrade properties file.-c upgrade.yaml
Downgrade all agents configured in the upgrade propertiesfile. The upgrade packages you reference in the upgradeproperties file must be a lower version than the current runningversion on the agents.
-d
Upgrade all agents configured in the upgrade properties file,even if they have been previously upgraded successfully.
If you do not define this option, the script only upgrades agentsthat previously failed to deploy properly.
-i
Show help for options.-h
Reinstall the current version on all agents configured in theupgrade properties file. The upgrade package you reference inthe upgrade properties file must be the same version as thecurrent agents.
-s
Perform local validation of the referenced upgrade propertiesfile.
-v
Perform validation of the referenced upgrade properties file,including connecting to the network element and validatinginterface names.
-V
Run an upgrade of agents installed on a UCS E-Series blade server with the following command:python3 upgrade_auto.py -c upgrade.yaml
Upgrading Agents Using the Upgrade Script
Before You Begin
• Log into the controller VM console.
37
Procedure
PurposeCommand or Action
Navigate to the /install_upgrade/ucsedirectory.
cd /opt/cisco/sln/install_upgrade/ucse
Example:user@host:~$ cd /opt/cisco/sln/install_upgrade/ucse
Step 1
Run the upgrade_auto.py upgrade script.upgrade_auto.py -c upgrade.yaml, then enter your password whenprompted
Provide passwords when prompted.If you did not update upgrade.yaml with passwords, enter those whenprompted.
Step 3
What to Do Next
• Check the installation log files, as described in Script Logs, on page 38.
Script LogsThese files include:
• aa_summary - The pass/fail status for each agent deployment. By default, the script references this file, and only deploys agentsthat failed to deploy properly.
• <dla-hostname>_commands - The ISR and agent commands the script ran successfully for this agent.
• <dla-hostname>_logs - The installation information logged as the script ran for this agent, including error information.
Accessing the Install Script Logs
Before You Begin
• Log into the controller VM console.
Procedure
PurposeCommand or Action
Navigate to the /LOGS directory.cd /opt/cisco/sln/install_upgrade/ucse/LOGS
Example:user@host:~$ cd /opt/cisco/sln/install_upgrade/ucse/LOGS
Step 1
38
PurposeCommand or Action
Open the log file in the vi text editor.vi <logfile>
Known DefectsThe following known defects are reported in this release:
Table 24: Known Defect Summaries and Workarounds
WorkaroundSummaryHeadline and Identifier
Update the ISR startup configuration toensure there are no long delays for IPaddress name resolution.
Alternatively, if you configure NTP orDNS on the ISR, ensure you enter allinformation correctly.
If you improperly configure an NTP orDNS server domain name or IP addresson the ISR, virtual service deploymentfails.
ISR-WAAS installation on 4451 is gated- EZConfig workflow failure(CSCuv02189)
Configure a network element user IDwith full administrator privileges in theinstall.yaml configuration file.
If you configure a network element userID (ne_username) that does not containfull administrator privileges in theinstall.yaml configuration file, thenrun the installation_auto.pyinstallation script, agent installation failsfor all routers for which that script logsin as that username.
Need oneClick to handle enable promptson router (CSCuz67015)
No workaround.If you try to download a PCAP file froman anomaly, the system checks the agentfor that file, even if the controller alreadyhas the PCAP, and the agent has deletedit.
SCA: PCAP request via REST sendsrequest to dla each time its executed(CSCuz94811)
No workaround.From an agent's dashboard, if you applyan application group filter, then click acluster name, the cluster details do notdisplay an application group breakdownor a host count.
Viz: DLA dashboard does not showHostcount or application breakdown(CSCva00554)
No workaround.From an agent's dashboard, if you applyan application group filter, then click acluster name, the cluster details do notdisplay threat flags for hosts.
SCA: DLA stats hosts for Dashboarddoes not contain Talos information(CSCva00561)
Manually reconfigure the settings, orreupload missing files. See the CiscoStealthwatch Learning Network LicenseVirtual Service Installation Guide formore information on reconfiguring thesettings.
If you upgrade an agent deployed as avirtual service, you lose the following:enabled SSH remote login enabled, anytrusted CA certificates used to verify anon-self-signed controller public keycertificate, allowing self-signedcertificates, enabled trust on first use(TOFU), saved controller certificatefingerprints, and any customconfiguration files related to off-pathdeployment.
packaging: oneclick container upgrademay lose some settings (CSCva00727)
Do not change the password fortruststore.jks or keystore.jks.
On the controller, if you configure apassword for truststore.jks orkeystore.jks other than sln123, thesystem throws an error messagecontaining a stack trace, and implyingthat the truststore or keystore wastampered with.
SCA: need clean error when truststorepassword is incorrect (CSCva01824)
Log into the controller web UI andmanually enable the disabled agents.
If your Learning Network Licensedeployment is in Smart LicensingEvaluation Mode, and you restart thecontroller, managed agents are disabledafter the controller restarts.
DLAs are disabled after SCA restart(CSCva03920)
If you have a parent interface with a QoSpolicy configured, apply a mitigation tothe parent interface, not the sub-interface.Similarly, if you have a sub-interfacewith a QoS policy configured, apply amitigation to the sub-interface, not theparent interface.
If you have a QoS policy configured ona parent interface, and then configure amitigation policy for a sub-interface ofthe parent interface, the mitigation doesnot work on the sub-interface. Similarly,if you have a QoS policy configured ona sub-interface, then configure amitigation policy for the sub-interface'sparent interface, the mitigation does notwork on the parent interface.
Mitigation: Allowed on Subinterfacewhen Parent has (Customer) Policy(CSCva09042)
No workaround.If you create a large amount ofmitigations at once, or you reboot anagent or its host ISR, the controller maytake an extended period of time to sendall mitigations to the agent.
SCA: Mitigation: Very slow mitigationpush down to router (CSCva13178)
Contact Cisco Support for helpdiagnosing the root cause for the crash.
If you enable packet buffer capture (PBC)on a virtual service-based agent, and theagent crashes, the agent does not alwaysgenerate a core file.
No core if dla_ncc crashes for ContainerDLA, and PBC or DNS/DPI Enabled(CSCva22018)
No workaround.When you add a new agent to thecontroller, the agent may remain in aPartial status for up to 30 minutes.
DLC: DLA may remain in partial statefor longer than few seconds on VIZ(CSCva22411)
Remove the ip traffic-export featurefrom the interface if you do not need it.
On G2 ISRs, if you configure the iptraffic-export feature on a routerinterface, PCAP files or DNS informationmay be unavailable for anomaliesdetected over that interface.
PBC: Silent failure when PBC enabledbut conflicting customer config.(CSCva28341)
Go to http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.htmlto access the Learning Network Licensedocumentation.
If you click on the Help link in thecontroller web UI, no online help isavailable.
no help screens (CSCva30278)
When you configure an agent, ignore thedisplayed configuration status.
If you add an agent to a controller andclick Configure, the controller web UIdisplays a configured status, regardlessof actual configuration status.
DLA Appears as "Configured" when itis Not (CSCva30289)
Disable the user account with the error,and create another user account with adifferent username, and correct full nameand email address.
You cannot modify the full name or emailaddress associated with a user accountafter you create the account.
SCA: Cannot modfyuser full name noremail address after user is created(CSCva30440)
Disable the user account if you do notwant users logging into the system withit.
You cannot delete a user account afteryou create the account.
SCA: Cant delete user after user iscreated (CSCva30461)
Do not set http { interface to anyvalue other than localhost.
The comments in sample_sca.conf donot mention that if you set the http {
interface setting to 0.0.0.0, based onother settings, this allows non-TLS accessto the REST API. The comments also donot mention that if you set http {
interface to any value besideslocalhost, users can access thecontroller through non-TLS connections,allowing them to view clear text data andauthentication tokens.
sample_sca.conf may inadvertentlyencourage users to disable TLS(CSCva32120)
When modifying sca.conf, follow thesample_sca.conf syntax exactly,including spacing.
The system is very strict when parsingthe sca.conf configuration file,specifically regarding nodes defined withan equal sign, such as modules = {, andnodes defined without an equal sign, suchas ise {.
sca.sh is overly restrictive on parsingsca.conf for values (CSCva32126)
No workaround, but you can ignore theerror message and add the agent.
When you click the Add a DLA buttonto add an agent in the controller web UI,the system returns an error message,though there is no actual error.
Viz throws an error when a DLA is added(CSCva39924)
No workaround, but you can ignore theerror message.
If you upgrade an agent deployed as avirtual service using theinstallation_auto.py install andupgrade script, and you already removedthe OVA file you used to install theagent, the script throws an error statingit could not delete the OVA file.
DLA Container Upgrade should succeedeven if delete of prior ova fails(CSCva42023)
Navigate the discarded anomalies fromthe anomaly inbox instead of from thediscarded anomaly's details.
If you are viewing a discarded anomaly'sdetails, the left and right arrows do notnavigate to the previous or next discardedanomaly.
Viz: left/right arrow in Discardedanomalies do not work as expected(CSCva42049)
After the setup-system script finishesrunning, run sudo service
ciscosln-sca start from the Linuxcommand line to manually start thecontroller service.
If you run the controller's setup-systemscript and the controller's service is notrunning, the script does not start theservice.
sca not started after system-setup is runthe first time (CSCva65925)
For AssistanceThank you for using Cisco products.
For information on obtaining documentation, using the Cisco Bug Search Tool (BST), submitting a service request, and gatheringadditional information about the Firepower System, seeWhat’s New in Cisco Product Documentation at http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html.
Subscribe toWhat’s New in Cisco Product Documentation, which lists all new and revised Cisco technical documentation, as an RSSfeed and deliver content directly to your desktop using a reader application. The RSS feeds are a free service.
If you have any questions or require assistance with the Cisco Stealthwatch Learning Network License system, please contact CiscoSupport:
• Visit the Cisco Support site at http://support.cisco.com.