Cisco Stealthwatch Learning Network License Release Notes · Table 2: Learning Network License OVA...

Cisco Stealthwatch Learning Network License Release Notes

Cisco Stealthwatch Learning Network License Release Notes 2

Learning Network License Overview 2

Brand Mapping 3

Related Documentation 4

Documentation Updates 4

Learning Network License OVA File Download 4

Web Browser and Screen Resolution Compatibility 5

Important Update and Compatibility Notes 6

Upgrade Prerequisites 6

Upgrading the Controller 7

Agent Remote Upgrade 19

Script Logs 38

Known Defects 39

For Assistance 42

Revised: August 8, 2016,

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.

3

Table 1: System and Product Brand Mapping

Product BrandingSystem Branding

Cisco Stealthwatch Learning Network License, LearningNetwork License

Stealthwatch Learning Networks, SLN

agentDistributed Learning Agent, DLA

controllerSLN Centralized Agent, SCA

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:

• Cisco Stealthwatch Learning Network License UCS E-Series Blade Server Quick Start Guide

• Cisco Stealthwatch Learning Network License Virtual Service Quick Start Guide

• Cisco Stealthwatch Learning Network License UCS E-Series Blade Server Installation Guide

• Cisco Stealthwatch Learning Network License Virtual Service Installation Guide

• Cisco Stealthwatch Learning Network License Configuration Guide

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.

4

http://www.cisco.com/c/en/us/support/security/stealthwatch-learning-network-license/tsd-products-support-series-home.html




http://www.cisco.com/c/en/us/products/collateral/security/stealthwatch-learning-network-license/datasheet-c78-737494.html

http://www.cisco.com/c/en/us/products/collateral/security/stealthwatch-learning-network-license/datasheet-c78-737494.html



Table 2: Learning Network License OVA Files

DescriptionFile Name

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.

6

https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2114800

https://kb.vmware.com/selfservice/microsites/search.do?language=en_US&cmd=displayKC&externalId=2114800



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


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


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

configuration file with rsyslog rulessettings

/etc/rsyslog.d50-default.conf

syslog log file containing audit and eventlogging

/var/logsyslog

log file containing event log messages/var/loguser.log

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


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

/SCA/services/sa-servercall_home_ca

Smart Licensing log file/SCA/services/sa-serversa-server.log

pxGrid Integration Configuration

If you have multiple ISE server certificates, you must export them all.

Rather than copy individual certificates, you can copy the /SCA/services/pxgrid/certificates directory, and all files in thedirectory.

Table 7: pxGrid Integration Configuration Files


configuration file containing pxGridintegration configuration settings

/SCA/services/pxgridapp.properties

pxGrid integration logging configurationfile

/SCA/services/pxgridlog4j.properties

public key certificate the controller usesto integrate with pxGrid and obtain ISEuser identity information

/SCA/services/pxgridpxGridClient.cer

private key associated with thepxGridClient.cer certificate

/SCA/services/pxgridpxGridClient.key

CA root certificate used to signpxGridClient.cer

/SCA/services/pxgridca_root.cer

11


archive file containingpxGridClient.cer, pxGridClient.key,and ca_root.cer

/SCA/services/pxgridpxGridClient.p12

public key certificate associated with theISE server

/SCA/services/pxgridisemnt.der

pxGrid client identity keystore generatedfrom the pxGridClient.p12 archive

/SCA/services/pxgrid/certificatespxGridClient.jks

controller trusted keystore/SCA/services/pxgrid/certificatesroot3.jks

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.

12

https://my.vmware.com/web/vmware/downloads

Procedure

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

provides additional DNS-related contextfor anomalies

recommended, but not requiredDNS server

provides additional DNS-related contextfor anomalies

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


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.

Step 2

Example:user@host:~$ sudo ./setup-system

Configure networking.y (configure networking)Step 3

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

The following attributes will be changed:

new IPv4 address: 209.165.201.2new IPv4 netmask: 255.255.255.224new IPv4 gateway: 209.165.201.1new IPv4 network: 209.165.201.0new IPv4 broadcast: 209.165.201.255

is this correct? (y or n)[n] y

...

Enter new hostname [hostname]: newhostnameThe hostname will be set to: newhostname


...

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


...

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


...

Enter an action (exit to exit): view

16

The current network configuration for eth0:

Operating state: UPIPv4 Address: 209.165.201.2IPv4 Netmask: 255.255.255.224IPv4 Network: 209.165.201.0IPv4 Broadcast: 209.165.201.255

IPv4 gateway: 209.165.201.1

Hostname: newhostname

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


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


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


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.

Note

dla_ova_copy:src_host: <source-host-ip>src_username: <source-host-user>src_password: <source-host-password>src_ova_path: <source-host-ova-filepath>dst_store: <dest-store-location>

vir_portgroup_1:ip_unnum: <parent-interface>vrf_forwarding: <parent-interface-vrf>

vir_portgroup_2:ne_ip: <private-ip-1>ne_mask: <private-ip-1-mask>dla_dat_ip: <private-ip-2>dla_dat_mask: <private-ip-2-mask>

ne_username: <ne-user>ne_password: <ne-password>ne_port: <tcp-port>dla_password: <dla-password>dla_ne_login:

username: <dla-ne-user>password: <dla-ne-password>

sca_webui_login:username: <sca-user>password: <sca-password>

21

Table 9: dla_ova_copy Properties

Required?ValidationDescriptionProperty

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


n/an/agroup of properties used tocreate the VirtualPortGroup1 virtual interface

vir_portgroup_1

22


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


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


nosubnet maskthe netmask for dla_dat_ipdla_dat_mask

Table 12: ne_username Property


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


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


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


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


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


string, cannot be NULLpassword for the agentusername

password

Table 17: sca_webui_login Properties


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



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 (-).


Note

branches:-ne_ctl_ip: <parent-interface-ip>dla_ctl_ip: <control-ip>dla_ctl_mask: <control-ip-mask>dla_ctl_gw: <control-ip-gateway>dla_hostname: <dla-hostname>dla_description: <dla-description>ne_netflow_interfaces:

ifnames: ['<branch-interface-1>','<branch-interface-2>','branch-interface-N>'......]dla_ctl_host_sca: <dla-ip-for-sca>

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


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


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


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


Procedure


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

install.yaml.

Step 2

28


Example:user@host:/opt/cisco/sln/install_upgrade/container$ mvinstall.yaml.example install.yaml

Open the install.yaml properties file in thevi text editor.

vi install.yaml, then enter your password when prompted.

Example:user@host:/opt/cisco/sln/install_upgrade/container$ viinstall.yaml

Step 3

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


30

Procedure


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

Example:user@host:/opt/cisco/sln/install_upgrade/container$installation_auto.py -c install.yaml

Step 2

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


a Debian package that contains the upgrade filesciscosln-dla_<version>_amd64.deb

31


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.

32



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.


Note

upgrade_pkg: <package-name>.tgzca_file: <ca-certificate-filepath>sub_ca_file: <sub-ca-cert-filepath>code_signing_verify_script: <script-filepath>dla_password: <dla-password>dla_port: <dla-port>dla_username: <dla-username>

Table 21: Global Properties


yesstring, must contain filepathand filename

filepath and name of theupgrade package file on thelocal system, which theupgrade script uses to upgradethe agent

upgrade_pkg

33


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


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


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


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


Procedure


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.

Example:user@host:/opt/cisco/sln/install_upgrade/ucse$ mvupgrade.yaml.example upgrade.yaml

Step 2

35


Open the upgrade.yaml upgrade propertiesfile in the vi text editor.

vi upgrade.yaml, then enter your password when prompted.

Example:user@host:/opt/cisco/sln/install_upgrade/ucse$ viupgrade.yaml

Step 3

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.

36

http://www.cisco.com/security/pki/

http://www.cisco.com/security/pki/

Upgrade Script Options

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


37

Procedure


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

Step 2

Example:user@host:/opt/cisco/sln/install_upgrade/ucse$upgrade_auto.py -c upgrade.yaml

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


Procedure


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


Open the log file in the vi text editor.vi <logfile>

Example:user@host:/opt/cisco/sln/install_upgrade/ucse/LOGS$ viaa_summary

Step 2

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)

39

https://bst.cloudapps.cisco.com/bugsearch/bug/CSCuv02189

https://bst.cloudapps.cisco.com/bugsearch/bug/CSCuz67015

https://bst.cloudapps.cisco.com/bugsearch/bug/CSCuz94811

https://bst.cloudapps.cisco.com/bugsearch/bug/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)

40








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)

41














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.

• Email Cisco Support at [email protected].

42






http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html

http://www.cisco.com/c/en/us/td/docs/general/whatsnew/whatsnew.html

http://support.cisco.com

• Call Cisco Support at 1.408.526.7209 or 1.800.553.2447.

43

Europe HeadquartersAsia Pacific HeadquartersAmericas HeadquartersCisco Systems International BVAmsterdam, The Netherlands

Cisco Systems (USA) Pte. Ltd.Singapore

Cisco Systems, Inc.San Jose, CA 95134-1706USA

Cisco has more than 200 offices worldwide. Addresses, phone numbers, and fax numbers are listed on theCisco Website at www.cisco.com/go/offices.

Cisco Stealthwatch Learning Network License Release Notes · Table 2: Learning Network License OVA...

Documents

Transcript of Cisco Stealthwatch Learning Network License Release Notes · Table 2: Learning Network License OVA...