1source: Extensions/Syslog.md 2path: blob/master/doc/ 3 4# Setting up syslog support 5 6This document will explain how to send syslog data to LibreNMS. 7Please also refer to the file Graylog.md for an alternate way of 8integrating syslog with LibreNMS. 9 10## Syslog server installation 11 12### syslog-ng 13 14For Debian / Ubuntu: 15 16```ssh 17apt-get install syslog-ng 18``` 19 20For CentOS / RedHat 21 22```ssh 23yum install syslog-ng 24``` 25 26Once syslog-ng is installed, edit the relevant config file (most 27likely /etc/syslog-ng/syslog-ng.conf) and paste the following: 28 29```bash 30@version:3.5 31@include "scl.conf" 32 33# syslog-ng configuration file. 34# 35# This should behave pretty much like the original syslog on RedHat. But 36# it could be configured a lot smarter. 37# 38# See syslog-ng(8) and syslog-ng.conf(5) for more information. 39# 40# Note: it also sources additional configuration files (*.conf) 41# located in /etc/syslog-ng/conf.d/ 42 43options { 44 chain_hostnames(off); 45 flush_lines(0); 46 use_dns(no); 47 use_fqdn(no); 48 owner("root"); 49 group("adm"); 50 perm(0640); 51 stats_freq(0); 52 bad_hostname("^gconfd$"); 53}; 54 55source s_sys { 56 system(); 57 internal(); 58}; 59 60source s_net { 61 tcp(port(514) flags(syslog-protocol)); 62 udp(port(514) flags(syslog-protocol)); 63}; 64 65######################## 66# Destinations 67######################## 68destination d_librenms { 69 program("/opt/librenms/syslog.php" template ("$HOST||$FACILITY||$PRIORITY||$LEVEL||$TAG||$R_YEAR-$R_MONTH-$R_DAY $R_HOUR:$R_MIN:$R_SEC||$MSG||$PROGRAM\n") template-escape(yes)); 70}; 71 72filter f_kernel { facility(kern); }; 73filter f_default { level(info..emerg) and 74 not (facility(mail) 75 or facility(authpriv) 76 or facility(cron)); }; 77filter f_auth { facility(authpriv); }; 78filter f_mail { facility(mail); }; 79filter f_emergency { level(emerg); }; 80filter f_news { facility(uucp) or 81 (facility(news) 82 and level(crit..emerg)); }; 83filter f_boot { facility(local7); }; 84filter f_cron { facility(cron); }; 85 86######################## 87# Log paths 88######################## 89log { 90 source(s_net); 91 source(s_sys); 92 destination(d_librenms); 93}; 94 95# Source additional configuration files (.conf extension only) 96@include "/etc/syslog-ng/conf.d/*.conf" 97 98 99# vim:ft=syslog-ng:ai:si:ts=4:sw=4:et: 100``` 101 102Next start syslog-ng: 103 104```ssh 105service syslog-ng restart 106``` 107 108Add the following to your LibreNMS `config.php` file to enable the Syslog extension: 109 110```php 111$config['enable_syslog'] = 1; 112``` 113 114 115If no messages make it to the syslog tab in LibreNMS, chances are you experience an issue with SELinux. If so, create a file mycustom-librenms-rsyslog.te , with the following content: 116 117``` 118module mycustom-librenms-rsyslog 1.0; 119 120require { 121 type syslogd_t; 122 type httpd_sys_rw_content_t; 123 type ping_exec_t; 124 class process execmem; 125 class dir { getattr search write }; 126 class file { append getattr execute open read }; 127} 128 129#============= syslogd_t ============== 130allow syslogd_t httpd_sys_rw_content_t:dir { getattr search write }; 131allow syslogd_t httpd_sys_rw_content_t:file { open read append getattr }; 132allow syslogd_t self:process execmem; 133allow syslogd_t ping_exec_t:file execute; 134``` 135 136Then, as root, execute the following commands: 137 138```ssh 139checkmodule -M -m -o mycustom-librenms-rsyslog.mod mycustom-librenms-rsyslog.te 140semodule_package -o mycustom-librenms-rsyslog.pp -m mycustom-librenms-rsyslog.mod 141semodule -i mycustom-librenms-rsyslog.pp 142``` 143 144 145### rsyslog 146 147If you prefer rsyslog, here are some hints on how to get it working. 148 149Add the following to your rsyslog config somewhere (could be at the 150top of the file in the step below, could be in `rsyslog.conf` if you 151are using remote logs for something else on this host) 152 153``` 154# Listen for syslog messages on UDP:514 155$ModLoad imudp 156$UDPServerRun 514 157``` 158 159Create a file called `/etc/rsyslog.d/30-librenms.conf`and add the following depending on your version of rsyslog. 160 161=== "Version 8" 162 ``` 163 # Feed syslog messages to librenms 164 module(load="omprog") 165 166 template(name="librenms" 167 type="string" 168 string= "%fromhost%||%syslogfacility%||%syslogpriority%||%syslogseverity%||%syslogtag%||%$year%-%$month%-%$day% %timegenerated:8:25%||%msg%||%programname%\n") 169 action(type="omprog" 170 binary="/opt/librenms/syslog.php" 171 template="librenms") 172 173 & stop 174 ``` 175 176=== "Version 7" 177 ``` 178 #Feed syslog messages to librenms 179 $ModLoad omprog 180 181 $template librenms,"%fromhost%||%syslogfacility%||%syslogpriority%||%syslogseverity%||%syslogtag%||%$year%-%$month%-%$day% %timegenerated:8:25%||%msg%||%programname%\n" 182 183 *.* action(type="omprog" binary="/opt/librenms/syslog.php" template="librenms") 184 185 & stop 186 187 ``` 188 189=== "Legacy" 190 ``` 191 # Feed syslog messages to librenms 192 $ModLoad omprog 193 $template librenms,"%FROMHOST%||%syslogfacility-text%||%syslogpriority-text%||%syslogseverity%||%syslogtag%||%$YEAR%-%$MONTH%-%$DAY% %timegenerated:8:25%||%msg%||%programname%\n" 194 195 $ActionOMProgBinary /opt/librenms/syslog.php 196 *.* :omprog:;librenms 197 ``` 198 199If your rsyslog server is recieving messages relayed by another syslog 200server, you may try replacing `%fromhost%` with `%hostname%`, since 201`fromhost` is the host the message was received from, not the host 202that generated the message. The `fromhost` property is preferred as 203it avoids problems caused by devices sending incorrect hostnames in 204syslog messages. 205 206Add the following to your LibreNMS `config.php` file to enable the Syslog extension: 207 208```php 209$config['enable_syslog'] = 1; 210``` 211 212### logstash 213 214If you prefer logstash, and it is installed on the same server as 215LibreNMS, here are some hints on how to get it working. 216 217First, install the output-exec plugin for logstash: 218 219```bash 220/usr/share/logstash/bin/logstash-plugin install logstash-output-exec 221``` 222 223Next, create a logstash configuration file 224(ex. /etc/logstash/conf.d/logstash-simple.conf), and add the 225following: 226 227``` 228input { 229syslog { 230 port => 514 231 } 232} 233 234 235output { 236 exec { 237 command => "echo `echo %{host},,,,%{facility},,,,%{priority},,,,%{severity},,,,%{facility_label},,,,``date --date='%{timestamp}' '+%Y-%m-%d %H:%M:%S'``echo ',,,,%{message}'``echo ,,,,%{program} | sed 's/\x25\x7b\x70\x72\x6f\x67\x72\x61\x6d\x7d/%{facility_label}/'` | sed 's/,,,,/||/g' | /opt/librenms/syslog.php &" 238 } 239 elasticsearch { 240 hosts => ["10.10.10.10:9200"] 241 index => "syslog-%{+YYYY.MM.dd}" 242 } 243} 244``` 245 246Replace 10.10.10.10 with your primary elasticsearch server IP, and set 247the incoming syslog port. Alternatively, if you already have a 248logstash config file that works except for the LibreNMS export, take 249only the "exec" section from output and add it. 250 251Add the following to your LibreNMS `config.php` file to enable the Syslog extension: 252 253```ssh 254$config['enable_syslog'] = 1; 255``` 256 257# Syslog Clean Up 258 259Can be set inside of `config.php` 260 261```php 262$config['syslog_purge'] = 30; 263``` 264 265The cleanup is run by daily.sh and any entries over X days old are 266automatically purged. Values are in days. See here for more Clean Up 267Options [Link](../Support/Cleanup-options.md) 268 269# Client configuration 270 271Below are sample configurations for a variety of clients. You should 272understand the config before using it as you may want to make some 273slight changes. Further configuration hints may be found in the file Graylog.md. 274 275Replace librenms.ip with IP or hostname of your LibreNMS install. 276 277Replace any variables in <brackets> with the relevant information. 278 279## syslog 280 281```config 282*.* @librenms.ip 283``` 284 285## rsyslog 286 287```config 288*.* @librenms.ip:514 289``` 290 291## Cisco ASA 292 293```config 294logging enable 295logging timestamp 296logging buffer-size 200000 297logging buffered debugging 298logging trap notifications 299logging host <outside interface name> librenms.ip 300``` 301 302## Cisco IOS 303 304```config 305logging trap debugging 306logging facility local6 307logging librenms.ip 308``` 309 310## Cisco NXOS 311 312```config 313logging server librenms.ip 5 use-vrf default facility local6 314``` 315 316## Juniper Junos 317 318```config 319set system syslog host librenms.ip authorization any 320set system syslog host librenms.ip daemon any 321set system syslog host librenms.ip kernel any 322set system syslog host librenms.ip user any 323set system syslog host librenms.ip change-log any 324set system syslog host librenms.ip source-address <management ip> 325set system syslog host librenms.ip exclude-hostname 326set system syslog time-format 327``` 328 329## Huawei VRP 330 331```config 332info-center loghost librenms.ip 333info-center timestamp debugging short-date without-timezone // Optional 334info-center timestamp log short-date // Optional 335info-center timestamp trap short-date // Optional 336//This is optional config, especially if the device is in public ip and you dont'want to get a lot of messages of ACL 337info-center filter-id bymodule-alias VTY ACL_DENY 338info-center filter-id bymodule-alias SSH SSH_FAIL 339info-center filter-id bymodule-alias SNMP SNMP_FAIL 340info-center filter-id bymodule-alias SNMP SNMP_IPLOCK 341info-center filter-id bymodule-alias SNMP SNMP_IPUNLOCK 342info-center filter-id bymodule-alias HTTP ACL_DENY 343``` 344 345## Huawei SmartAX (GPON OLT) 346 347```config 348loghost add librenms.ip librenms 349loghost activate name librenms 350``` 351 352## Allied Telesis Alliedware Plus 353 354```config 355log date-format iso // Required so syslog-ng/LibreNMS can correctly interpret the log message formatting. 356log host x.x.x.x 357log host x.x.x.x level <errors> // Required. A log-level must be specified for syslog messages to send. 358log host x.x.x.x level notices program imish // Useful for seeing all commands executed by users. 359log host x.x.x.x level notices program imi // Required for Oxidized Syslog hook log message. 360log host source <eth0> 361``` 362 363If you have permitted udp and tcp 514 through any firewall then that 364should be all you need. Logs should start appearing and displayed 365within the LibreNMS web UI. 366 367## Windows 368 369By Default windows has no native way to send logs to a remote syslog server. 370 371Using this how to you can download Datagram-Syslog Agent to send logs 372to a remote syslog server (LibreNMS). 373 374### Note 375 376Keep in mind you can use any agent or program to send the logs. We are 377just using this Datagram-Syslog Agent for this example. 378 379[Link to How to](http://techgenix.com/configuring-syslog-agent-windows-server-2012/) 380 381You will need to download and install "Datagram-Syslog Agent" for this how to 382[Link to Download](http://download.cnet.com/Datagram-SyslogAgent/3001-2085_4-10370938.html) 383 384# External hooks 385 386Trigger external scripts based on specific syslog patterns being 387matched with syslog hooks. Add the following to your LibreNMS 388`config.php` to enable hooks: 389 390```ssh 391$config['enable_syslog_hooks'] = 1; 392``` 393 394The below are some example hooks to call an external script in the 395event of a configuration change on Cisco ASA, IOS, NX-OS and IOS-XR 396devices. Add to your `config.php` file to enable. 397 398## Cisco ASA 399 400```ssh 401$config['os']['asa']['syslog_hook'][] = Array('regex' => '/%ASA-(config-)?5-111005/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 402``` 403 404## Cisco IOS 405 406```ssh 407$config['os']['ios']['syslog_hook'][] = Array('regex' => '/%SYS-(SW[0-9]+-)?5-CONFIG_I/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 408``` 409 410## Cisco NXOS 411 412```ssh 413$config['os']['nxos']['syslog_hook'][] = Array('regex' => '/%VSHD-5-VSHD_SYSLOG_CONFIG_I/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 414``` 415 416## Cisco IOSXR 417 418```ssh 419$config['os']['iosxr']['syslog_hook'][] = Array('regex' => '/%GBL-CONFIG-6-DB_COMMIT/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 420``` 421 422## Juniper Junos 423 424```ssh 425$config['os']['junos']['syslog_hook'][] = Array('regex' => '/UI_COMMIT:/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 426``` 427 428## Juniper ScreenOS 429 430```ssh 431$config['os']['screenos']['syslog_hook'][] = Array('regex' => '/System configuration saved/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 432``` 433 434## Allied Telesis Alliedware Plus 435 436**Note:** At least software version 5.4.8-2.1 is required. `log host 437x.x.x.x level notices program imi` may also be required depending on 438configuration. This is to ensure the syslog hook log message gets sent 439to the syslog server. 440 441```ssh 442$config['os']['awplus']['syslog_hook'][] = Array('regex' => '/IMI.+.Startup-config saved on/', 'script' => '/opt/librenms/scripts/syslog-notify-oxidized.php'); 443``` 444 445# Configuration Options 446 447## Matching syslogs to hosts with different names 448 449In some cases, you may get logs that aren't being associated with the 450device in LibreNMS. For example, in LibreNMS the device is known as 451"ne-core-01", and that's how DNS resolves. However, the received 452syslogs are for "loopback.core-nw". 453 454To fix this issue, you can configure LibreNMS to translate the 455incoming syslog hostname into another hostname, so that the logs get 456associated with the correct device. 457 458Example: 459 460```ssh 461$config['syslog_xlate'] = array( 462 'loopback0.core7k1.noc.net' => 'n7k1-core7k1', 463 'loopback0.core7k2.noc.net' => 'n7k2-core7k2' 464); 465``` 466