logging configuration - cisco€¦ · logging configuration...

Logging Configuration

The following describes how to enable audit and event logging on the controller.

• Logging Configuration Overview, page 1

Logging Configuration OverviewThe Learning Network License system enables audit, event, and general logging by default on the controller.It also automatically enables Smart Licensing logging after you register your controller with Smart Licensing.See the following table for descriptions and default file output locations.

Table 1: Controller Logging Descriptions and Default Output Locations

Default Output LocationsDescriptionLog Type

~/SCA/logs/sca.log

console (ERROR severity andabove)

system transactionsaudit logging

/var/log/user.log

~/SCA/logs/sca.log


events the system generates,tracking:

• agents connecting to ordisconnecting from thecontroller

• anomaly events (INFOseverity)

• updated anomaly eventswhere the severity increases

event logging

~/SCA/logs/sca.log


general system informationgeneral logging

Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.1 1

Default Output LocationsDescriptionLog Type

/var/log/user.log

~/SCA/services/sa-server/sa-server.log

Smart Licensing transactions,including when you register thecontroller, and when you use agentlicense entitlements

Smart Licensing logging

~/SCA/services/pxgrid/pxg.loglogging related to pxGridintegration with ISE

pxGrid logging

The agent logs general system information to multiple log files, located on the agent at ~/DLA/LOG.

The Controller Logging Configuration FileThe controller uses the logback logging framework to log information, including anomaly events,agent/controller connection and disconnection events, audit logging, general system logging, and SmartLicensing logging. Cisco provides a sample configuration file on the controller at ~/SCA/sample_logback.xml.This file provides an example of logging configuration syntax. If you copy this file and rename it tosca-logback.xml, you can update the logging configuration settings.

If you incorrectly configure sca-logback.xml due to invalid or malformed XML syntax, the system logsan error message to the console, but does not start logging. If you incorrectly configure sca-logback.xmldue to unrecognized nodes, options, or class names, the system logs an error message to the console. Itthen loads the remaining valid configuration in the file, and otherwise loads default logging settings.

Note

Beneath the parent configuration node are the following:

• logger - the class that provides the level of log messages

• root - the root logger class

• appender - the class that output the log message

By default, the root logger is configured to log INFO messages to the console and the ~/SCA/logs/sca.loglog file. However, note that the console appender is configured to log ERROR and above by default, so INFOmessages are not displayed on the console.

The com.cisco.sln.utils.log.ScaCefLogger logger does not have a logging level configured, but inheritslogging INFO messages. By default, this logger logs the CEF messages, which are INFO level, to the/var/log/user.log log file, ~/SCA/logs/sca.log log file, and the console.

For more information on logback, see http://logback.qos.ch/documentation.html.

syslog Export to External HostsWithin the sample_logback.xml configuration file, the ScaCefLogger logger controls logging anomaly CEFevents to syslog. You can modify this configuration to change the host that receives these events.

Cisco Stealthwatch Learning Network License Virtual Service Installation Guide, Version 1.12

Logging ConfigurationThe Controller Logging Configuration File

http://logback.qos.ch/documentation.html

sca-logback.xml Creation

To update the logging configuration, first copy the sample_logback.xml file and rename it to sca-logback.xml,then open it and view the markup.

General Configuration

By default, the system checks sca-logback.xml for changes every minute. If it detects changes, the systemupdates the logging configuration. To disable this check, set the scan attribute equal to false.

If you set the scan attribute equal to false, you must restart the controller's processes before the systemupdates logging configuration.

Note

The following default configuration root element configuration controls this setting.<configuration scan="true"></configuration>If you want to change the sca-logback.xml check frequency, add the scanPeriod attribute to theconfiguration element, and set it equal to a number of seconds, minutes, hours, or days. The followingprovides an example.<configuration scan="true" scanPeriod="10 seconds"></configuration>

ScaCefLogger Logger Configuration

The following is the ScaCefLogger default configuration.<logger name="com.cisco.sln.utils.log.ScaCefLogger">

<appender-ref ref="SYSLOG" /></logger>

If you need to change logging level, add a level attribute to the ScaCefLogger logger element. The followingprovides an example.

<logger name="com.cisco.sln.utils.log.ScaCefLogger" level="TRACE"><appender-ref ref="SYSLOG" />

</logger>If you need to stop logging, add level="OFF" as an attribute to the ScaCefLogger logger element. The followingprovides an example.

<logger name="com.cisco.sln.utils.log.ScaCefLogger" level="OFF"><appender-ref ref="SYSLOG" />

</logger>

The system logs anomaly event CEF messages with an INFO logging level. The ScaCefLogger loggerinherits INFO logging level from the parent root logger. If you change the ScaCefLogger logging level,select a level that contains INFOmessages (TRACE, DEBUG, INFO). If you override this with a level that doesnot include INFO messages (WARN, ERROR), the system cannot write anomaly event messages to syslog.

Note

The appender-ref element references the SYSLOG appender which controls the host that receives these anomalyevents.



SYSLOG Appender Configuration

The SYSLOG appender, by default, logs to the syslog on the local host. The following is the default SYSLOGappender configuration.

<appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender"><syslogHost>localhost</syslogHost><facility>USER</facility><suffixPattern>%msg</suffixPattern>

</appender>The syslogHost element controls the target for the logged anomaly events. Update this to the hostname ofyour external host or SIEM to export syslog to that host.

The facility element controls the syslog facility. LOCAL0 through LOCAL7 are unused facilities you can definefor custom purposes.

Because the USER facility generates the events, Cisco recommends you keep this setting.Note

The suffixPattern element controls the format of the non-standard message component. See http://logback.qos.ch/manual/layouts.html for the discussion of PatternLayout and more information on how toconfigure suffixPattern.

To define a port on the host other than the default port 514, you can add the port element as a child of theappender element and define a different port in that element's text. The following provides an example.

<appender name="SYSLOG" class="ch.qos.logback.classic.net.SyslogAppender"><syslogHost>externalHostName</syslogHost><port>515</port><facility>USER</facility><suffixPattern>%msg</suffixPattern>

</appender>

Changes Saved

Save your changes to the file. The system updates the logging configuration the next time it checks the file.

Log File Location

The system by default outputs the anomaly events to /var/log/user.log.

Updating a syslog Target Host

Before You Begin

• Log into the controller VM console.



http://logback.qos.ch/manual/layouts.html

http://logback.qos.ch/manual/layouts.html

SUMMARY STEPS

1. cd ~/SCA

2. cp sample_logback.xml sca-logback.xml

3. vi sca-logback.xml

4. If you want to change the logging level, add level="TRACE" or level="DEBUG" as an attribute to theScaCefLogger logger element, or level="OFF" as an attribute to the ScaCeflogger logger element todisable anomaly event logging.

5. If you want to define a port for the syslog host other than the default port 514, add a port element as achild of the SYSLOG appender element, then add the port number as the port element text.

6. Press Esc, then enter :wq!, then press Enter.

DETAILED STEPS

PurposeCommand or Action

Change to the ~/SCA directory.cd ~/SCA

Example:

Step 1

user@host:~$ cd ~/SCA

Make a copy of the sample_logback.xmlconfiguration file, and name itsca-logback.xml.

cp sample_logback.xml sca-logback.xml

Example:user@host:~/SCA$ cp sample_logback.xml sca-logback.xml

Step 2

Open the sca-logback.xml configurationfile in vi.

vi sca-logback.xml

Example:

Step 3

user@host:~/SCA$ vi sca-logback.xml

Change the logging level, or disable it.If you want to change the logging level, add level="TRACE" orlevel="DEBUG" as an attribute to the ScaCefLogger logger element, or

Step 4

level="OFF" as an attribute to the ScaCeflogger logger element todisable anomaly event logging.

Example:<logger name="com.cisco.sln.utils.log.ScaCefLogger"

level="TRACE">

Update the target syslog host port.If you want to define a port for the syslog host other than the defaultport 514, add a port element as a child of the SYSLOG appender element,then add the port number as the port element text.

Step 5

Example:<port>515</port>

Save your changes and close the file.Press Esc, then enter :wq!, then press Enter.

Example:

Step 6




:wq!

What to Do Next

• View ~/SCA/logs/console.log to verify that the controller updated the logging configuration.

• View the logs to see syslog messages. The log destination depends on the facility you defined in theSyslogAppender appender. By default, the USER facility logs to /var/log/user.log.

Logging TimestampsBy default, sca.log and console.log use Coordinated Universal Time (UTC) timestamps.

In contrast, pxg.log, saserver.log, and sca_monitor.log use timestamps based on your current localtimezone. You can edit the logging properties files and run sed to update those logs to use UTC timestamps.

Updating Logging Configuration Files for UTC TimestampsUpdate the log4j.properties files to update timestamps from your local configured timezone to UTCtimezones. Find the following lines:

log4j.appender.file.layout=org.apache.log4j.PatternLayoutlog4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L -

%m%n

And update the lines to add the bold text:log4j.appender.file.layout=org.apache.log4j.EnhancedPatternLayoutlog4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-dd HH:mm:ss}{UTC} %-5p %c{1}:%L

- %m%n

Before You Begin


SUMMARY STEPS

1. cd ~/SCA/services/pxgrid

2. sudo vi log4j.properties, then enter your password when prompted3. Update the lines listed above.4. Press Esc, then enter :wq!.5. cd ~/SCA/services/sa-server

6. sudo vi log4j.properties, then enter your password when prompted7. Update the lines listed above.8. Press Esc, then enter :wq!.


Logging ConfigurationLogging Timestamps

DETAILED STEPS


Change to the ~/SCA/services/pxgriddirectory.

cd ~/SCA/services/pxgrid

Example:user@host:~$ cd ~/SCA/services/pxgrid

Step 1

Open log4j.properties in the vi texteditor as a superuser.

sudo vi log4j.properties, then enter your password when prompted

Example:user@host:~/SCA/services/pxgrid$ sudo vi log4j.properties

Step 2

Update the log4j.properties file touse UTC timestamps.

Update the lines listed above.

Example:

log4j.appender.file.layout=org.apache.log4j.EnhancedPatternLayout

Step 3

log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-ddHH:mm:ss}{UTC} %-5p %c{1}:%L - %m%n

Save your changes, then exit the vi texteditor.

Press Esc, then enter :wq!.Step 4

Change to the~/SCA/services/sa-server directory.

cd ~/SCA/services/sa-server

Example:user@host:~$ cd ~/SCA/services/sa-server

Step 5

Open log4j.properties in the vi texteditor as a superuser.

sudo vi log4j.properties, then enter your password when prompted

Example:user@host:~/SCA/services/sa-server$ sudo vi log4j.properties

Step 6

Update the log4j.properties file touse UTC timestamps.

Update the lines listed above.

Example:

log4j.appender.file.layout=org.apache.log4j.EnhancedPatternLayout

Step 7

log4j.appender.file.layout.ConversionPattern=%d{yyyy-MM-ddHH:mm:ss}{UTC} %-5p %c{1}:%L - %m%n

Save your changes, then exit the vi texteditor.

Press Esc, then enter :wq!.Step 8

Updating UTC Timestamps for the Controller Monitor LogsRun sed to display UTC timestamps in the sca_monitor.log log file.

Before You Begin



Logging ConfigurationLogging Timestamps

DETAILED STEPS


Run sed to update how the sca_monitor.log logfile displays timestamps.

sed -ie 's/(date /(date --utc /' SCA/sca_monitor.sh

Example:user@host:~$ sed -ie 's/(date /(date --utc /'SCA/sca_monitor.sh

Step 1

Accessing Audit and Event Log Files

Before You Begin

• Log into the controller VM console on the ESXi hypervisor.

SUMMARY STEPS

1. cd ~/var/log

2. vi syslog or vi user.log

DETAILED STEPS


Change to the /var/log directory.cd ~/var/log

Example:

Step 1

user@host:~$ cd ~/var/log

Edit the syslog or user.log log file.vi syslog or vi user.log

Example:

Step 2

user@host:~/var/log$ vi syslog

Example:user@host:~/var/log$ vi user.log

Audit Log FieldsFor Version 1.0, the system logs each audit log message in the following format:

userId [timestamp] category > {jsonData}


Logging ConfigurationAccessing Audit and Event Log Files

Table 2: Audit Log Version 1.0 Field Descriptions

DescriptionField

ID of the user associated with the transactionuserId

Date and time the transaction occurredtimestamp

The type of transactioncategory

Information associated with the transaction typejsonData

For Version 1.1 and greater, the system logs each audit log message in the following format:

[timestamp] - User(userInfo) - source: category > {jsonData}

Table 3: Audit Log Version 1.1 and Greater Field Descriptions

DescriptionField

ISO8061 timestamp when the transaction occurredtimestamp

One of the following values related to users:

• unknown - an unknown user

• id - a user's ID (username unknown)

• id, username - a user's ID and username

userInfo

the source that generated the audit log message:

• authentication - user authentication duringlogin, user logout, and user account passwordchange

• configuration - configuration applied to anagent by the controller

• dla - agent configuration, such as enable,disable, and certificate pinning

• download - PCAP file download

• mitigation - mitigation creation, deletion, andreversion

• pbc - PCAP file download requests

• user - user account creation, update, andconversion to an API user

• whitelisting - whitelist rule creation anddeletion

source



DescriptionField

the type of transaction task requested by the user, andthe success or failure, depending on the source

category

information associated with the transaction type,depending on the source

jsonData

Event Log Fields

Table 4: Event Log Field Descriptions

DescriptionField

The date and time the system detected the event.timestamp

The host that logged the message.host

The CEF version, always 0.version

The associated vendor, always Cisco.deviceVendor

The associated vendor product, always SLN.deviceProduct

The controller version.deviceVersion

The event type:

• SLN_ANOMALY for anomaly events

• SLN_DLA for agent health status events

signatureID

Description of the event log message.name

Integer representing the event severity:

• 0 for low

• 5 for medium

• 10 for high

severity

Information related to the anomaly event. If this is anagent health status event, this contains no data.

extension



Event Log Message Examples

The system logs each event log message in CEF. When the system adds an event log message to the syslog,it prepends a timestamp and host, in the following format:timestamp host CEF:version|deviceVendor|deviceProduct|deviceVersion|signatureID|name|severity|extension

The following describes a connection between agent and controller has gone down:Jan 1 00:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_DLA|CON_DOWN|0|deviceExternalId=1

The following describes an agent in safe mode:Jan 1 21:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_DLA|DLA is in safe mode|0|

The following describes an updated agent configuration:Jan 1 11:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_DLA_INTERFACES|Interfaces have changed on dla 2|5|

The following describes a user asking for more anomalies:Jan 1 21:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_MORE_LESS|User admin asked for more anomalies|0|

The following describes a sample anomaly:Jan 1 22:12:34 exampleHost CEF:0|Cisco|SLN|92-prod-1.0|SLN_ANOMALY|Small total number of bytes (10.00 bytes)from an external mixed host in Chile (RM) 200.10.9.23 in Chile (anomalous trafficenters and exits the branch)|10|deviceExternalId=1 dst=192.0.2.14 dvchost=samplenameexternalId=1923 startTime=2016-01-01T22:08:00Z

Smart Licensing Log FieldsThe system logs each Smart Licensing log message in the following format:

timestamp hostname userId: %CISCO-SMART-LIC% message

Table 5: Smart Licensing Log Field Descriptions

DescriptionField

Date and time the transaction occurredtimestamp

Name of the host where the transaction occurredhostname

ID of the user associated with the transactionuserId

The log messagemessage

Accessing Controller General Log Files

Before You Begin

• Log into the controller VM console on the ESXi hypervisor.


Logging ConfigurationAccessing Controller General Log Files

SUMMARY STEPS

1. cd ~/SCA

2. vi SCA.log

DETAILED STEPS


Change to the /SCA directory.cd ~/SCA

Example:

Step 1

user@host:~$ cd ~/SCA

Edit the SCA.log general controller log file.vi SCA.log

Example:

Step 2

user@host:~/SCA$ vi SCA.log

Accessing Agent Log Files

Before You Begin

• For an agent deployed to a UCS E-Series blade server, log into the agent VM console on the ESXihypervisor. For an agent deployed as a virtual service, log into the virtual service console, then exit theinitial menu to access the administrator settings.

SUMMARY STEPS

1. 1) File access

2. 1) Log files

3. 1) List log files

4. 2) View log file

5. Enter a log file name. You can use the asterisk character (*) as a wild card.6. :qto exit

DETAILED STEPS


Access the File access menu options.1) File access

Example:

Step 1

Enter a number: 1


Logging ConfigurationAccessing Agent Log Files


Access the log files options.1) Log files

Example:

Step 2

Enter a number: 1

List the available agent log files.1) List log files

Example:

Step 3

Enter a number: 1

View log files.2) View log file

Example:

Step 4

Enter a number: 2

Select a log file to view.Enter a log file name. You can use the asterisk character (*) asa wild card.

Step 5

Example:Enter filename, or a pattern for a menu of files:

log-name

Exit viewing the log file.:qto exit

Example:

Step 6

:q

Exporting Agent Troubleshooting FilesYou can export your agent troubleshooting files to an external host. Do this when directed by Cisco Support.

Before You Begin

• For an agent deployed to a UCS E-Series blade server, log into the agent VM console on the ESXihypervisor. For an agent deployed as a virtual service, log into the virtual service console, then exit theinitial menu to access the administrator settings.

SUMMARY STEPS

1. 1) File access

2. 5) ML debug files

3. 1) List ML debug files

4. 2) Send ML debug files to remote system, then ip-address, then username, then press Enter, thenpassword


Logging ConfigurationExporting Agent Troubleshooting Files

DETAILED STEPS


Access the File access menu options.1) File access

Example:

Step 1

Enter a number: 1

Access the log files options.5) ML debug files

Example:

Step 2

Enter a number: 5

List the available debugging files.1) List ML debug files

Example:

Step 3

Enter a number: 1

Export the debugging files to a remotesystem.

2) Send ML debug files to remote system, then ip-address, thenusername, then press Enter, then password

Example:Enter a number: 2Name or address of remote host []? 192.168.0.1

Step 4

Destination username []? adminThe destination filename path can absolute, or relativeto home dir.Destination filename [scala.out]:admin@remotehost's password: <password>


Logging ConfigurationExporting Agent Troubleshooting Files

logging configuration - cisco€¦ · logging configuration...

Documents