1. Syslog Alerts

1.1. Objective

Syslog can be used as channel to convey alerts as an alternative or a complement to e-mail.

An alert is an investigation set to be ran periodically. The alert is triggered only if the investigation yields some result. On the other hand, if the investigation returns zero rows, nothing is sent.

1.2. Limitations

Works only with one Engine instance per Engine server.

1.3. Specifying an alert to be transmitted via Syslog

The Finder can be used to easily set an existing alert to be sent via Syslog.

See doc/3.2.4/WorkingWithFinder/UsingNEXThinkAlerts#Advanced_Alert_configuration_options for instructions.

For testing purposes, the old way of defining alerts is to do it directly on the Engine:

Login to the Engine via ssh
type:
```
nxinfo shell
```

type:

create alert_def(login_id,name,description,type,frequency,action,parameters,display_parameters,extra)

where:

login_id	is the id of the login the alert will be attached to.
name	is the alert name.
description	ignored.
type	should be set to investigation.
frequency	can be hourly, daily or weekly.
action	should be syslog.
parameters	defines the selector; is a subset of the XML representation of the investigation.
display_parameters	defines the order of the alert's fields; is a subset of the XML representation of the investigation.
extra	should be empty.

Example:

create alert_def(1,"source with unsuccessful connections","list of sources with more than unsuccessful connections in the lasthour", investigation, hourly, syslog, "<parameters><selector>select source.id,source.name,source.mac_addresses with connections where event.status=rejected or event.status=no_host or event.status=no_service</selector></parameters>","<parameters><fields><field>source.name</field><field>source.id</field><field>connections</field><field>source.mac_addresses</field></fields></parameters>","")

1.4. Configuring the syslog facility

The Syslog facility is configured by means of the /etc/sysconfig/rsyslog (RH/CentOS) file. Please refer to this file and its documentation (man syslog.conf 5).
To avoid some Syslog to summarize like: "last message repeated x times", have the following in the config file:
```
SYSLOGD_OPTIONS="-m 0 -r" -r Disable the compression of repeated instances of the same line.
```
NEXThink is using the facility local5. By default, Syslog messages are all sent to /var/log/messages.
For a quick test, do:
```
logger -p local5.notice "Your message"
```
and you should see a line similar to the following appear in /var/log/messages:
```
Jun  4 15:20:52 nxt-l23 yoda: Your message
```
The Engine sends the messages in UTF-8, and Syslog will preserve the encoding.
The maximum length of any syslog message is 16'777'216 bytes.
For more information about Syslog, please refer to http://www.syslog.org/

1.5. How to modify syslog default port (UDP/514) to send packets to remote syslog server

On the “client” (machine sending the logs) :
1. Edit /etc/syslog.conf and add the following line :
  - ```
  local5.=notice @IP_ADDRESS_OF_REMOTE_SERVER
  local5.=debug  -/var/log/kengine
  local5.=info   -/var/log/kengine
```
  By adding that line and keeping the default config, the logs will be stored on the client machine and sent to the log server as well.
2. Edit /etc/services and modify this line with the new udp port (here's the udp port 515):
  - ```
  syslog          515/udp
```
  - Make sure you allow that port in the firewall configuration on the log server.
3. Restart the syslog service
  - ```
  # service syslog restart
```
On the log server :
1. Edit /etc/sysconfig/syslog and change SYSLOGD_OPTIONS to match the following :
  - ```
  SYSLOGD_OPTIONS="-m 0 -r"
```
- -r : listen over the network, only necessary for log servers
2. Edit /etc/services and modify this line with the new udp port (here's the udp port 515):
  - ```
  syslog          515/udp
```
  - Make sure you allow that port in the firewall configuration on the log server
3. Restart the syslog service
  - ```
  # service syslog restart
```

All message from the syslog client will go to the syslog server using UDP port 515 in this sample.

1.6. Syslog alert format

Syslog is line-oriented
An alert consist syntactically as a table.
So the alert is split as follows into separate Syslog lines:
- one line consisting of the investigation title and the number of rows
- one line per row
If multiple alerts are sent, they should not interleave
Each row is encoded as follows:
- investigation title | cell | cell... |
A cell is encoded as follows:
- Multiple values are separated by # (for example, for cells representing fields that are arrays, e.g. binary.paths)
- \, | or # in a cell is escaped by a \ prefix.
- A newline in a cell is represented by \\n
Cell contents is encoded in UTF-8.

Example:

May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation [7]
May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation |21|Apple Inc|iMac7,1|1|Intel Core 2 Duo CPU T7700 @ 2.40GHz|2|2.4GHz|2GB|WDC WD3200AAJS-40RYA0 298.1GB|W87361N8X8A|W87361N8X8A|
May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation |9|INTEL|D915GAG|2|Intel Pentium 4 CPU 3.00GHz|2|3GHz|2GB|HDS722516VLAT20 153.4GB|||
May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation |14|INTEL|DX58SO|1|Intel Pentium III Xeon processor|4|2.7GHz|6GB|WDC WD2502ABYS-01B7A0 233.8GB|||
May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation |7|Apple Inc|iMac7,1|1|Intel Core 2 Duo CPU T7700 @ 2.40GHz|2|2.4GHz|2GB|WDC WD3200AAJS-40RYA0 298.1GB|W87361PXX8A|W87361PXX8A|
May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation |11|Apple Inc|iMac7,1|1|Intel Core 2 Duo CPU T7700 @ 2.40GHz|2|2.4GHz|2GB|WDC WD3200AAJS-40RYA0 298.1GB|W87361Q9X8A|W87361Q9X8A|
May 28 13:05:00 nxt NX: [2010-05-28 13:04:00] Test Investigation |1|INTEL|DX58SO|1|Intel Pentium III Xeon processor|4|2.7GHz|6GB|WDC WD2502ABYS-01B7A0 233.8GB|||

Example 2:

May 28 13:05:00 nxt NX: [2008-12-09 13:00:00] source with unsuccessful connections [2]
May 28 13:05:00 nxt NX: [2008-12-09 13:00:00] source with unsuccessful connections |ICINF119PC27|53|00:01:80:5d:d5:22#a2:af:8a:f5:67:eb|
May 28 13:05:00 nxt NX: [2008-12-09 13:00:00] source with unsuccessful connections |ICINF119PC27|5\\\\-\\\3|00:01:\#80:5d:d5:22#-\\-\|-\\|

First row has a array cell, second row too, plus escaped characters.

1.7. Semantics

The fields have names corresponding to the data model.
You will need a knowledge of it in order to interpret these fields. Please ask your NEXThink contact to get a copy.
The numeric fields are postfixed by a magnitude and a unit (e.g. GB for gigabyte). Please ask your NEXThink contact for information.

1.8. Sample Parser

The attached Python script demonstrates how the parsing can be achieved: parse_syslog.py

CategoryEngine CategoryIntegration

advanced/Syslog Alerts