Difference between revisions of "Syslog-ng"

From ArchWiki
Jump to navigation Jump to search
(Creating Filters for Messages: Fix error)
m (rm gap)
 
(52 intermediate revisions by 23 users not shown)
Line 1: Line 1:
 
{{Lowercase title}}
 
{{Lowercase title}}
[[Category:Daemons and system services]]
+
[[Category:Logging]]
{{Note|After upgrading to systemd, syslog-ng is unnecessary for most users and can be uninstalled, since the systemd journal provides this functionality.}}
+
[[Category:Daemons]]
 +
[[ja:Syslog-ng]]
 +
{{Related articles start}}
 +
{{Related|rsyslog}}
 +
{{Related articles end}}
  
==Overview==
+
[[w:syslog-ng|syslog-ng]] is a [[w:syslog|syslog]] implementation which can take log messages from sources and forward them to destinations, based on powerful filter directives.
syslog-ng takes incoming log messages from defined '[[Syslog-ng#Sources|sources]]' and forwards them to the appropriate [[Syslog-ng#Destinations|destinations]], based on powerful [[Syslog-ng#Creating Filters for Messages|filter]] directives. In a typical simple set-up, syslog-ng will read messages from three sources:
 
# the default {{ic|/dev/log}} device, where most logs are sent
 
# syslog-ng "internal" log messages
 
# {{ic|/proc/kmsg}} kernel messages
 
  
Sources are defined using the "source" directive. These incoming messages are then filtered according to defined filters ("filter" keyword), i.e. according to originating program or log level, and sent to the appropriate "destination". Destinations include log files (e.g. {{ic|/var/log/messages.log}}), printing messages on a console and remote servers. The pivotal function is [[Syslog-ng#Log Paths|log]]. This function defines which filters should be applied to a certain source, and where the resulting messages should be sent to.
+
{{Note|With [[systemd/Journal|systemd's journal]], syslog-ng is not needed by most users.}}
  
==Example configuration file==
+
== Overview ==
For a quick start, here there is a classic configuration file slightly modified from the one in the
 
[http://www.gentoo.org/doc/en/security/security-handbook.xml?part=1&chap=3#doc_chap4 Gentoo Security Guide], the default {{ic|syslog-ng.conf}} provided with the source distribution, and my own personal preferences. This example includes logging from a chrooted bind source and logging to a remote server destination.
 
  
{{hc|/etc/syslog-ng/syslog-ng.conf|<nowiki>@version: 3.0
+
syslog-ng takes incoming log messages from defined '[[#Sources|sources]]' and forwards them to the appropriate [[#Destinations|destinations]], based on powerful [[#Creating Filters for Messages|filter]] directives. In a typical simple set-up, syslog-ng will read messages from three sources:
# For a description of syslog-ng configuration file directives, please read
 
# the syslog-ng Administrator's guide at:
 
#
 
# http://www.balabit.com/dl/html/syslog-ng-admin-guide_en.html/bk01-toc.html
 
#
 
 
 
##########################################################
 
# OPTIONS
 
#
 
options {
 
  create_dirs(yes);
 
  # use_dns(no);
 
  use_dns(persist_only);
 
  dns_cache_hosts(/etc/hosts);
 
  dns_cache_expire(87600);
 
 
 
  # disable the chained hostname format in logs (default is enabled)
 
  chain_hostnames(0);
 
 
 
  # the number of lines fitting in the output queue
 
  log_fifo_size(512);
 
 
 
  # enable or disable directory creation for destination files
 
  create_dirs(yes);
 
 
 
  # default owner, group, and permissions for log files (defaults are 0, 0, 0600)
 
  owner(root);
 
  group(log);
 
  perm(0640);
 
 
 
  # default owner, group, and permissions for created directories (defaults are 0, 0, 0700)
 
  dir_owner(root);
 
  dir_group(root);
 
  dir_perm(0740);                                                                                                                                                                                                                                       
 
 
 
  # the time to wait before a died connection is re-established (default is 60)
 
  time_reopen(10);
 
 
 
  # the time to wait before an idle destination file is closed (default is 60)
 
  time_reap(360);
 
 
 
  # default no
 
  use_fqdn(no);
 
 
 
  keep_hostname(yes);
 
 
 
  # disable stats
 
  stats_freq(0);
 
};
 
  
 +
# the default {{ic|/dev/log}} device, where most logs are sent
 +
# syslog-ng "internal" log messages
 +
# {{ic|/proc/kmsg}} kernel messages
  
##########################################################
+
Sources are defined using the "source" directive. These incoming messages are then filtered according to defined filters ("filter" keyword), i.e. according to originating program or log level, and sent to the appropriate "destination". Destinations include log files (e.g. {{ic|/var/log/messages.log}}), printing messages on a console and remote servers. The pivotal function is [[#Log Paths|log]]. This function defines which filters should be applied to a certain source, and where the resulting messages should be sent to.
# SOURCES
 
#
 
source local_src {
 
  # message generated by syslog-ng
 
  internal();
 
  
  # standard Linux log source (this is the default place for the syslog() function to send logs to)
+
== Installation ==
  unix-stream("/dev/log");
 
  
  # from a chrooted bind install
+
[[Install]] the {{Pkg|syslog-ng}} package.
  unix-stream("/var/named/chroot/dev/log");
 
  
  # messages from the kernel
+
To use syslog-ng, [[start]]/[[enable]] {{ic|syslog-ng@default.service}}.
  file("/proc/kmsg" program_override("kernel: "));
 
};
 
  
# source s_syslog { syslog(ip(127.0.0.1) port(1999) transport("tcp")); };
+
=== systemd/journald integration ===
# source s_pipe { pipe("/dev/pipe" pad_size(2048)); };
 
  
 +
syslog-ng pulls in the messages from the systemd journal by default. Keeping {{ic|1=ForwardToSyslog=no}} in {{ic|/etc/systemd/journald.conf}} is recommended in order to avoid the overhead associated with the socket and to avoid [https://github.com/balabit/syslog-ng/issues/314 needless error messages in the log]. If on the other hand you do not want to store your logs twice and turn ''journald'''s {{ic|1=Storage=none}}, you '''will''' need {{ic|1=ForwardToSyslog=yes}}, as ''syslog-ng'' tries to follow the 'journald' journal file.
  
 
+
See [[#syslog-ng and systemd journal]] for more details.
##########################################################
 
# DESTINATIONS
 
#
 
destination d_file { file("/var/log/$YEAR.$MONTH.$DAY/everything.log" template("$HOUR:$MIN:$SEC [$LEVEL] [$FACILITY] [$PROGRAM] $MSG\n") template_escape(no)); };
 
 
 
destination d_askapacheloghost {
 
  tcp("askapacheloghost.dyndns.org" port(65514));
 
  udp("askapacheloghost.dyndns.org" port(65514));
 
  udp("askapacheloghost.dyndns.org" port(514));
 
};
 
                                                                                                                                                                                                                                 
 
destination d_authlog { file("/var/log/auth.log"); };
 
destination d_cron { file("/var/log/cron.log"); };
 
destination d_daemon { file("/var/log/daemon.log"); };
 
destination d_kern { file("/var/log/kern.log"); };
 
destination d_lpr { file("/var/log/lpr.log"); };
 
destination d_user { file("/var/log/user.log"); };
 
destination d_uucp { file("/var/log/uucp.log"); };
 
destination d_ppp { file("/var/log/ppp.log"); };
 
 
 
destination d_mail { file("/var/log/mail.log"); };
 
destination d_mailinfo { file("/var/log/mail.info"); };
 
destination d_mailwarn { file("/var/log/mail.warn"); };
 
destination d_mailerr { file("/var/log/mail.err"); };
 
 
 
destination d_newscrit { file("/var/log/news/news.crit"); };
 
destination d_newserr { file("/var/log/news/news.err"); };
 
destination d_newsnotice { file("/var/log/news/news.notice"); };
 
 
 
destination d_debug { file("/var/log/debug"); };
 
destination d_messages { file("/var/log/messages"); };
 
 
 
destination d_everything { file("/var/log/everything"); };
 
destination d_console { usertty("root"); };
 
destination d_console_all { file("/dev/tty12"); };
 
destination d_loghost { udp("loghost" port(999)); };
 
destination d_xconsole { pipe("/dev/xconsole"); };
 
 
 
 
 
 
 
##########################################################
 
# FILTERS
 
#
 
filter f_auth { facility(auth); };
 
filter f_authpriv { facility(auth, authpriv); };                                                                                                                                                                                             
 
filter f_syslog { program(syslog-ng); };
 
filter f_cron { facility(cron); };
 
filter f_daemon { facility(daemon); };
 
filter f_kernel { facility(kern) and not filter(f_iptables); };
 
filter f_lpr { facility(lpr); };
 
filter f_mail { facility(mail); };
 
filter f_news { facility(news); };
 
filter f_user { facility(user); };
 
filter f_uucp { facility(cron); };
 
filter f_news { facility(news); };
 
filter f_ppp { facility(local2); };
 
filter f_debug { not facility(auth, authpriv, news, mail); };
 
filter f_messages { level(info..warn) and not facility(auth, authpriv, mail, news, cron) and not program(syslog-ng) and not filter(f_iptables); };
 
filter f_everything { level(debug..emerg); };
 
filter f_emergency { level(emerg); };
 
filter f_info { level(info); };
 
filter f_notice { level(notice); };
 
filter f_warn { level(warn); };
 
filter f_crit { level(crit); };
 
filter f_err { level(err); };
 
filter f_iptables { match("IN=" value("MESSAGE")) and match("OUT=" value("MESSAGE")); };
 
filter f_acpid { program("acpid"); };
 
filter f_failed { match("failed" value(MESSAGE)); };
 
filter f_denied { match("denied" value(MESSAGE)); };
 
filter f_noshorewall { not match("Shorewall" value(MESSAGE)); };              # Filter everything except regex keyword Shorewall
 
filter f_shorewall { match("Shorewall" value(MESSAGE)); };                    # Filter regex keyword Shorewall
 
 
 
 
 
 
 
 
 
##########################################################
 
# LOG
 
#
 
log { source(local_src); destination(d_askapacheloghost); };
 
log { source(local_src); destination(d_file); };
 
 
 
log { source(local_src); filter(f_authpriv); destination(d_authlog); };
 
log { source(local_src); filter(f_user); destination(d_user); };
 
 
 
log { source(local_src); filter(f_cron); destination(d_cron); };
 
log { source(local_src); filter(f_daemon); destination(d_daemon); };
 
log { source(local_src); filter(f_kern); destination(d_kern); };
 
log { source(local_src); filter(f_lpr); destination(d_lpr); };
 
log { source(local_src); filter(f_mail); destination(d_mail); };
 
log { source(local_src); filter(f_uucp); destination(d_uucp); };
 
log { source(local_src); filter(f_mail); filter(f_info); destination(d_mailinfo); };
 
log { source(local_src); filter(f_mail); filter(f_warn); destination(d_mailwarn); };
 
log { source(local_src); filter(f_mail); filter(f_err); destination(d_mailerr); };
 
log { source(local_src); filter(f_news); filter(f_crit); destination(d_newscrit); };
 
log { source(local_src); filter(f_news); filter(f_err); destination(d_newserr); };
 
log { source(local_src); filter(f_news); filter(f_notice); destination(d_newsnotice); };
 
log { source(local_src); filter(f_debug); destination(d_debug); };
 
log { source(local_src); filter(f_messages); destination(d_messages); };
 
log { source(local_src); filter(f_ppp); destination(d_ppp); };
 
log { source(local_src); destination(d_messages); };
 
 
 
#default log
 
log { source(local_src); destination(console_all); };</nowiki>
 
}}
 
 
 
{{Note|The line "unix-stream("/dev/log");" can prevent syslog-ng from starting on some systems. If you have this, and see "syslog-ng.service start request repeated too quickly, refusing to start", removing that line may fix your problem.}}
 
  
 
== Sources ==
 
== Sources ==
Line 200: Line 37:
 
  source <identifier> { source-driver(params); source-driver(params); ... };
 
  source <identifier> { source-driver(params); source-driver(params); ... };
  
You can look at the identifiers and source-drivers in the [http://www.balabit.com/support/documentation/ official manuals].  
+
You can look at the identifiers and source-drivers in the [https://www.syslog-ng.com/technical-documents official manuals].  
 
This will follow the manual to explain the configuration file above. The unix-stream() source-driver opens the given AF_UNIX
 
This will follow the manual to explain the configuration file above. The unix-stream() source-driver opens the given AF_UNIX
[http://en.wikipedia.org/wiki/Berkeley_sockets socket] and starts listening on it for messages.  
+
[[wikipedia:Berkeley_sockets|socket]] and starts listening on it for messages.  
 
The internal() source-driver gets messages generated by syslog-ng.
 
The internal() source-driver gets messages generated by syslog-ng.
  
Line 211: Line 48:
 
kernsrc gets messages from file {{ic|/proc/kmsg}}
 
kernsrc gets messages from file {{ic|/proc/kmsg}}
 
  source kernsrc { file("/proc/kmsg"); };
 
  source kernsrc { file("/proc/kmsg"); };
 
  
 
In the default configuration file after emerging syslog-ng, the source is defined as:
 
In the default configuration file after emerging syslog-ng, the source is defined as:
Line 217: Line 53:
  
 
Reading messages by {{ic|pipe("/proc/kmsg")}} gives a better performance but because it opens its argument in read-write mode can be a security
 
Reading messages by {{ic|pipe("/proc/kmsg")}} gives a better performance but because it opens its argument in read-write mode can be a security
hazard as the [http://www.balabit.com/sites/default/files/documents/syslog-ng-v3.0-guide-admin-en.html/index.html-single.html#configuring_sources_pipe syslog-ng admin guide] states in section 3.3.3:
+
hazard as the [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide/21#TOPIC-1121850 syslog-ng admin guide] states:
  
"Pipe is very similar to the file() driver, but there are a few differences, for example pipe() opens its argument in read-write mode, therefore it is not recommended to be used on special files like {{ic|/proc/kmsg}}." (You can follow this discussion in [http://forums.gentoo.org/viewtopic-t-558161.html this post].)
+
"Pipe is very similar to the file() driver, but there are a few differences, for example pipe() opens its argument in read-write mode, therefore it is not recommended to be used on special files like {{ic|/proc/kmsg}}." (You can follow this discussion in [https://forums.gentoo.org/viewtopic-t-558161.html this post].)
  
 
To open a port to read data from a remote server a source must be defined with this syntax:
 
To open a port to read data from a remote server a source must be defined with this syntax:
Line 228: Line 64:
  
 
to receive log messages via TCP. Both listen on port 514.
 
to receive log messages via TCP. Both listen on port 514.
 +
 +
=== syslog-ng and systemd journal ===
 +
Starting with syslog-ng version 3.6.1 the default {{ic|system()}} source on Linux systems using systemd uses journald as its standard {{ic|system()}} source.
 +
 +
If you wish to use both the journald and syslog-ng files, ensure the following settings are in effect. For systemd-journald, in the {{ic|/etc/systemd/journald.conf}} file, {{ic|1=Storage=}} either set to {{ic|auto}} or unset (which defaults to auto) and {{ic|1=ForwardToSyslog=}} set to {{ic|no}} or unset (defaults to no). For {{ic|/etc/syslog-ng/syslog-ng.conf}}, you need the following {{ic|source}} stanza:
 +
 +
{{bc|<nowiki>
 +
source src {
 +
  system();
 +
  internal();
 +
};</nowiki>}}
 +
 +
If, on the other hand, you wish ''not'' to retain the journald logs, but only syslog-ng's text logs, set {{ic|<nowiki>Storage=volatile</nowiki>}} and {{ic|1=ForwardToSyslog=yes}} in {{ic|/etc/systemd/journald.conf}}. This will store journald in ram. As of syslog-ng 3.6.3, syslog-ng is using journald as the system(); source so if you set {{ic|1=Storage=none}}, the systemd journal will drop all messages and '''not''' forward them to syslog-ng.
 +
 +
After the change [[restart]] the {{ic|systemd-journald.service}} and {{ic|syslog-ng@default.service}} daemons.
  
 
== Destinations ==
 
== Destinations ==
Line 258: Line 109:
 
''<nowiki>May 11 23:42:31 mimosinnet su(pam_unix)[18569]: session opened for user root by (uid=1000)</nowiki>'', use the following:
 
''<nowiki>May 11 23:42:31 mimosinnet su(pam_unix)[18569]: session opened for user root by (uid=1000)</nowiki>'', use the following:
 
  filter f_auth { facility(auth); };
 
  filter f_auth { facility(auth); };
 
  
 
The facility expression can use the boolean operators {{ic|and}}, {{ic|or}}, and {{ic|not}}, so the following filter
 
The facility expression can use the boolean operators {{ic|and}}, {{ic|or}}, and {{ic|not}}, so the following filter
Line 289: Line 139:
 
The following for example sends messages from {{ic|src}} source to {{ic|mailinfo}} destination filtered by {{ic|f_info}} filter.
 
The following for example sends messages from {{ic|src}} source to {{ic|mailinfo}} destination filtered by {{ic|f_info}} filter.
 
  log { source(src); filter(f_mail); filter(f_info); destination(mailinfo); };
 
  log { source(src); filter(f_mail); filter(f_info); destination(mailinfo); };
 
  
 
== Tips and Tricks ==
 
== Tips and Tricks ==
Line 391: Line 240:
 
  postgres=# CREATE ROLE syslog WITH LOGIN;
 
  postgres=# CREATE ROLE syslog WITH LOGIN;
 
  postgres=# \password syslog    # Using the \password function is secure because
 
  postgres=# \password syslog    # Using the \password function is secure because
  postgres=# \password logwriter # the password isn't saved in history.
+
postgres=# CREATE ROLE logwriter WITH LOGIN;
 +
  postgres=# \password logwriter # the password is not saved in history.
 
  postgres=# CREATE DATABASE syslog OWNER syslog;
 
  postgres=# CREATE DATABASE syslog OWNER syslog;
  postgres=# \q # You're done here for the moment
+
  postgres=# \q # You are done here for the moment
  
 
Edit {{ic|pg_hba.conf}} to allow {{ic|syslog}} and {{ic|logwriter}} to establish a connection to PostgreSQL.
 
Edit {{ic|pg_hba.conf}} to allow {{ic|syslog}} and {{ic|logwriter}} to establish a connection to PostgreSQL.
  
{{hc|/var/lib/postgresql/8.4/data/pg_hba.conf|
+
{{hc|/var/lib/postgres/data/pg_hba.conf|
 
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
 
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
  
Line 405: Line 255:
  
 
Tell PostgreSQL to reload the configuration files:
 
Tell PostgreSQL to reload the configuration files:
  /etc/rc.d/postgresql-8.4 reload
+
   
 +
# systemctl reload postgresql
  
Edit {{ic|/etc/syslog-ng.conf}} so that it knows where and how to write to PostgreSQL. syslog-ng will utilize the {{ic|logwriter}} role.
+
Edit {{ic|/etc/syslog-ng/syslog-ng.conf}} so that it knows where and how to write to PostgreSQL. syslog-ng will utilize the {{ic|logwriter}} role.
  
 
{{bc|<nowiki>...
 
{{bc|<nowiki>...
Line 423: Line 274:
 
   indexes("datetime", "host", "program", "pid", "message"));
 
   indexes("datetime", "host", "program", "pid", "message"));
 
};
 
};
 
  
 
log { source(src); destination(d_pgsql); };</nowiki>
 
log { source(src); destination(d_pgsql); };</nowiki>
Line 429: Line 279:
  
 
Finally, restart syslog-ng.
 
Finally, restart syslog-ng.
  /etc/rc.d/syslog-ng restart
+
  # systemctl restart syslog-ng
  
 
And check to see if things are being logged.
 
And check to see if things are being logged.
Line 456: Line 306:
 
   group("log");
 
   group("log");
 
   ts_format(iso);      #make ISO-8601 timestamps
 
   ts_format(iso);      #make ISO-8601 timestamps
 +
  #frac-digits(3);    #optional time to nearest millisecond
 
  };
 
  };
  
 
Then:
 
Then:
  # /etc/rc.d/syslog-ng reload
+
  # systemctl reload syslog-ng
  
 
'''After''' :
 
'''After''' :
Line 483: Line 334:
 
  define LOG_INFO        6      /* informational */
 
  define LOG_INFO        6      /* informational */
 
  define LOG_DEBUG      7      /* debug-level messages */
 
  define LOG_DEBUG      7      /* debug-level messages */
 
  
 
=== Macros and Variables ===
 
=== Macros and Variables ===
Macros can be used in both templates, and in destination file names.  [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/reference-macros.html Macros of syslog-ng OSE].
+
Macros can be used in both templates, and in destination file names.  [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide/60#TOPIC-1122008 Macros of syslog-ng OSE].
  
 
The following code will write the log lines to {{ic|/var/log/test.log}} in the format of {{ic|<nowiki>macroname=value@</nowiki>}}.   
 
The following code will write the log lines to {{ic|/var/log/test.log}} in the format of {{ic|<nowiki>macroname=value@</nowiki>}}.   
Line 500: Line 350:
 
You can create your own value list as below once syslog-ng is restarted with:
 
You can create your own value list as below once syslog-ng is restarted with:
 
{{ic|<nowiki>tail /var/log/test.log|tr "@" "\n"</nowiki>}}
 
{{ic|<nowiki>tail /var/log/test.log|tr "@" "\n"</nowiki>}}
 
  
 
{{bc|<nowiki>
 
{{bc|<nowiki>
Line 550: Line 399:
 
YEAR_DAY=148
 
YEAR_DAY=148
 
</nowiki>}}
 
</nowiki>}}
 +
 +
=== Receive and parse common syslog messages ===
 +
Starting from version 3.16 syslog-ng is capable to receive and parse messages on the most common ports with the most common parsers using the [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide/17#TOPIC-1121831 default-network-drivers()] source driver.
 +
* Default listening ports:
 +
** 514, both TCP and UDP, for RFC3164 (BSD-syslog) formatted traffic
 +
** 601 TCP, for RFC5424 (IETF-syslog) formatted traffic
 +
** 6514 TCP, for TLS-encrypted traffic
 +
* Automatic parsers:
 +
** RFC3164 message parser
 +
** RFC5424 message parser
 +
** [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide/68#TOPIC-1122040 Cisco parser]
 +
** Structured [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide/ewmm-intro EWMM parser]
 +
** Other application adapters (Splunk Common Information Model (CIM), iptables, or sudo)
  
 
=== See Also ===
 
=== See Also ===
Line 555: Line 417:
  
 
== External Links ==
 
== External Links ==
* [http://www.balabit.com/network-security/syslog-ng/opensource-logging-system/overview syslog-ng OSE Project Page]
+
* [https://www.syslog-ng.com/products/open-source-log-management/ syslog-ng OSE Main Page]
* [http://www.balabit.com/support/documentation/ Portal to syslog-ng Documentation]
+
* [https://github.com/balabit/syslog-ng syslog-ng OSE Project Page on GitHub]
** [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/index.html The syslog-ng 3.4 Administrator Guide]
+
* [https://www.syslog-ng.com/technical-documents Portal to syslog-ng Documentation]
** [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/syslog-ng-parameter-index.html List of syslog-ng 3.4 Parameters]
+
** [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide The syslog-ng 3.20 Administrator Guide]
** [http://www.balabit.com/sites/default/files/documents/syslog-ng-ose-3.4-guides/en/syslog-ng-ose-v3.4-guide-admin/html/reference-macros.html List of syslog-ng 3.4 Macros]
+
** [https://www.syslog-ng.com/technical-documents/doc/syslog-ng-open-source-edition/3.20/administration-guide/60#TOPIC-1122008 List of syslog-ng 3.20 Macros]
* [http://freshmeat.net/projects/syslog-ng/ syslog-ng Project Page on Freshmeat]
+
* [https://www.syslog-ng.com/community/ syslog-ng Blogs]
* [http://en.gentoo-wiki.com/wiki/Syslog-ng Gentoo syslog-ng wiki]
+
* [http://freshmeat.sourceforge.net/projects/syslog-ng/ syslog-ng Project Page on Freecode]
* [http://www.gentoo.org/doc/en/security/security-handbook.xml?part=1&chap=3 Gentoo Security Handbook on Logging]
+
* [https://wiki.gentoo.org/wiki/Syslog-ng Gentoo syslog-ng wiki]
* [http://www.kdough.net/docs/syslog_postgresql/ Syslog Logging with PostgreSQL HOWTO]
+
* [https://wiki.gentoo.org/wiki/Security_Handbook/Logging Gentoo Security Handbook on Logging]
* [http://en.wikipedia.org/wiki/ISO_8601 ISO_8601] Wikipedia page for ISO 8601
+
* [https://www.pcwdld.com/what-is-syslog-including-servers-and-ports What is Syslog? Logging with PostgreSQL HOWTO]
* [http://tools.ietf.org/html/rfc3164 RFC 3164] - The BSD syslog Protocol
+
* [[wikipedia:ISO 8601|ISO 8601]] on Wikipedia
* [http://tools.ietf.org/html/rfc3164 RFC 5424] - The Syslog Protocol
+
* [https://tools.ietf.org/html/rfc3164 RFC 3164] - The BSD syslog Protocol
** [http://tools.ietf.org/html/rfc5425 RFC 5425] - Transport Layer Security (TLS) Transport Mapping for Syslog
+
* [https://tools.ietf.org/html/rfc3164 RFC 5424] - The Syslog Protocol
** [http://tools.ietf.org/html/rfc5425 RFC 5426] - Transmission of Syslog Messages over UDP
+
** [https://tools.ietf.org/html/rfc5425 RFC 5425] - Transport Layer Security (TLS) Transport Mapping for Syslog
** [http://tools.ietf.org/html/rfc5425 RFC 5427] - Textual Conventions for Syslog Management
+
** [https://tools.ietf.org/html/rfc5425 RFC 5426] - Transmission of Syslog Messages over UDP
** [http://tools.ietf.org/html/rfc5425 RFC 5428] - MIB for PacketCable and IPCablecom-Compliant Devices
+
** [https://tools.ietf.org/html/rfc5425 RFC 5427] - Textual Conventions for Syslog Management
* [http://tools.ietf.org/html/rfc3339 RFC 3339] - Date and Time on the Internet: Timestamps
+
** [https://tools.ietf.org/html/rfc5425 RFC 5428] - MIB for PacketCable and IPCablecom-Compliant Devices
 +
* [https://tools.ietf.org/html/rfc3339 RFC 3339] - Date and Time on the Internet: Timestamps

Latest revision as of 13:44, 16 March 2019

syslog-ng is a syslog implementation which can take log messages from sources and forward them to destinations, based on powerful filter directives.

Note: With systemd's journal, syslog-ng is not needed by most users.

Overview

syslog-ng takes incoming log messages from defined 'sources' and forwards them to the appropriate destinations, based on powerful filter directives. In a typical simple set-up, syslog-ng will read messages from three sources:

  1. the default /dev/log device, where most logs are sent
  2. syslog-ng "internal" log messages
  3. /proc/kmsg kernel messages

Sources are defined using the "source" directive. These incoming messages are then filtered according to defined filters ("filter" keyword), i.e. according to originating program or log level, and sent to the appropriate "destination". Destinations include log files (e.g. /var/log/messages.log), printing messages on a console and remote servers. The pivotal function is log. This function defines which filters should be applied to a certain source, and where the resulting messages should be sent to.

Installation

Install the syslog-ng package.

To use syslog-ng, start/enable syslog-ng@default.service.

systemd/journald integration

syslog-ng pulls in the messages from the systemd journal by default. Keeping ForwardToSyslog=no in /etc/systemd/journald.conf is recommended in order to avoid the overhead associated with the socket and to avoid needless error messages in the log. If on the other hand you do not want to store your logs twice and turn journald's Storage=none, you will need ForwardToSyslog=yes, as syslog-ng tries to follow the 'journald' journal file.

See #syslog-ng and systemd journal for more details.

Sources

syslog-ng receives log messages from a source. To define a source you should follow the following syntax:

source <identifier> { source-driver(params); source-driver(params); ... };

You can look at the identifiers and source-drivers in the official manuals. This will follow the manual to explain the configuration file above. The unix-stream() source-driver opens the given AF_UNIX socket and starts listening on it for messages. The internal() source-driver gets messages generated by syslog-ng.

Therefore, the following means: src gets messages from the /dev/log socket and syslog-ng.

source src { unix-stream("/dev/log"); internal(); };

The kernel sends log messages to /proc/kmsg and the file() driver reads log messages from files. Therefore, the following means: kernsrc gets messages from file /proc/kmsg

source kernsrc { file("/proc/kmsg"); };

In the default configuration file after emerging syslog-ng, the source is defined as:

source src { unix-stream("/dev/log"); internal(); pipe("/proc/kmsg"); };

Reading messages by pipe("/proc/kmsg") gives a better performance but because it opens its argument in read-write mode can be a security hazard as the syslog-ng admin guide states:

"Pipe is very similar to the file() driver, but there are a few differences, for example pipe() opens its argument in read-write mode, therefore it is not recommended to be used on special files like /proc/kmsg." (You can follow this discussion in this post.)

To open a port to read data from a remote server a source must be defined with this syntax:

source s_net { udp(); };

for UDP or

source s_net { tcp(); };

to receive log messages via TCP. Both listen on port 514.

syslog-ng and systemd journal

Starting with syslog-ng version 3.6.1 the default system() source on Linux systems using systemd uses journald as its standard system() source.

If you wish to use both the journald and syslog-ng files, ensure the following settings are in effect. For systemd-journald, in the /etc/systemd/journald.conf file, Storage= either set to auto or unset (which defaults to auto) and ForwardToSyslog= set to no or unset (defaults to no). For /etc/syslog-ng/syslog-ng.conf, you need the following source stanza:

source src {
  system();
  internal();
};

If, on the other hand, you wish not to retain the journald logs, but only syslog-ng's text logs, set Storage=volatile and ForwardToSyslog=yes in /etc/systemd/journald.conf. This will store journald in ram. As of syslog-ng 3.6.3, syslog-ng is using journald as the system(); source so if you set Storage=none, the systemd journal will drop all messages and not forward them to syslog-ng.

After the change restart the systemd-journald.service and syslog-ng@default.service daemons.

Destinations

In syslog-ng, log messages are sent to files. The syntax is very similar to sources:

destination <identifier> {destination-driver(params); destination-driver(params); ... };

You will be normally logging to a file, but you could log to a different destination-driver: pipe, Unix socket, TCP-UDP ports, terminals or to specific programs. Therefore, this means sending authlog messages to /var/log/auth.log:

destination authlog { file("/var/log/auth.log"); };

If the user is logged in, usertty() sends messages to the terminal of the specified user. If you want to send console messages to root's terminal if it is logged in:

destination console { usertty("root"); };

Messages can be sent to a pipe with pipe(). The following sends xconsole messages to the pipe /dev/xconsole. This needs some more configuration, so you could look at the sub-section xconsole below.

destination xconsole { pipe("/dev/xconsole"); };

To send messages on the network, use udp(). The following will send your log data out to another server.

destination remote_server { udp("10.0.0.2" port(514)); };

Creating Filters for Messages

The syntax for the filter statement is:

filter <identifier> { expression; };

Functions can be used in the expression, such as the function facility() which selects messages based on the facility codes. The Linux kernel has a few facilities you can use for logging. Each facility has a log-level; where debug is the most verbose, and panic only shows serious errors. You can find the facilities, log levels and priority names in /usr/include/sys/syslog.h. To filter those messages coming from authorization, like May 11 23:42:31 mimosinnet su(pam_unix)[18569]: session opened for user root by (uid=1000), use the following:

filter f_auth { facility(auth); };

The facility expression can use the boolean operators and, or, and not, so the following filter selects those messages not coming from authorization, network news or mail:

filter f_debug { not facility(auth, authpriv, news, mail); };

The function level() selects messages based on its priority level, so if you want to select informational levels:

filter f_info { level(info); };

Functions and boolean operators can be combined in more complex expressions. The following line filters messages with a priority level from informational to warning not coming from auth, authpriv, mail and news facilities:

filter f_messages { level(info..warn) and not facility(auth, authpriv, mail, news); };

Messages can also be selected by matching a regular expression in the message with the function match("regex" value("TEMPLATE")). For example:

filter f_failed { match("failed" value("MESSAGE")); };

here is a list of templates :

 "AMPM", "BSDTAG", "DATE, C_DATE, R_DATE, S_DATE", "DAY, C_DAY, R_DAY, S_DAY", "FACILITY", "FACILITY_NUM", "FULLDATE, C_FULLDATE, R_FULLDATE, S_FULLDATE", "FULLHOST", "FULLHOST_FROM", "HOUR, C_HOUR, R_HOUR, S_HOUR", "HOUR12, C_HOUR12, R_HOUR12, S_HOUR12", "HOST", "HOST_FROM", "ISODATE, C_ISODATE, R_ISODATE, S_ISODATE", "LEVEL_NUM", "LOGHOST", "MIN, C_MIN, R_MIN, S_MIN", "MONTH, C_MONTH, R_MONTH, S_MONTH", "MONTH_ABBREV, C_MONTH_ABBREV, R_MONTH_ABBREV, S_MONTH_ABBREV", "MONTH_NAME, C_MONTH_NAME, R_MONTH_NAME, S_MONTH_NAME", "MONTH_WEEK, C_MONTH_WEEK, R_MONTH_WEEK, S_MONTH_WEEK", "MSEC, C_MSEC, R_MSEC, S_MSEC", "MSG or MESSAGE", "MSGHDR", "MSGID", "MSGONLY", "PID", "PRI", "PRIORITY or LEVEL", "PROGRAM", "SDATA, .SDATA.SDID.SDNAME", "SEC, C_SEC, R_SEC, S_SEC", "SOURCEIP", "SEQNUM", "STAMP, R_STAMP, S_STAMP", "SYSUPTIME", "TAG", "TAGS", "TZ, C_TZ, R_TZ, S_TZ", "TZOFFSET, C_TZOFFSET, R_TZOFFSET, S_TZOFFSET", "UNIXTIME, C_UNIXTIME, R_UNIXTIME, S_UNIXTIME", "USEC, C_USEC, R_USEC, S_USEC", "YEAR, C_YEAR, R_YEAR, S_YEAR", "WEEK, C_WEEK, R_WEEK, S_WEEK", "WEEK_ABBREV, C_WEEK_ABBREV, R_WEEK_ABBREV, S_WEEK_ABBREV", "WEEK_DAY, C_WEEK_DAY, R_WEEK_DAY, S_WEEK_DAY", "WEEKDAY, C_WEEKDAY, R_WEEKDAY, S_WEEKDAY", "WEEK_DAY_NAME, C_WEEK_DAY_NAME, R_WEEK_DAY_NAME, S_WEEK_DAY_NAME".

To filter messages received from a particular remote host, the host() function must be used:

filter f_host { host( "192.168.1.1" ); };

Log Paths

syslog-ng connects sources, filters and destinations with log statements. The syntax is:

log {source(s1); source(s2); ...
filter(f1); filter(f2); ...
destination(d1); destination(d2); ...
flags(flag1[, flag2...]); };

The following for example sends messages from src source to mailinfo destination filtered by f_info filter.

log { source(src); filter(f_mail); filter(f_info); destination(mailinfo); };

Tips and Tricks

After understanding the logic behind syslog-ng, many possible and complex configuration are possible. Here there are some examples.

Have syslog-ng reload the configuration file

You can make syslog-ng re-evaluate the configuration file. You can do so manually by sending a SIGHUP to the process, or call the reload function with systemctl:

# systemctl reload syslog-ng

Failover Logging to Remote Host

This setup shows how to send the default unencrypted syslog packets across both TCP and UDP protocols, using the standard port (514) and an alternate port. This is sending the same output to the same machine 4 different ways to try and make sure packets make it. Mostly useful if you are debugging a remote server that fails to reboot. The different ports and protocols are to make it past any firewall filters or other network problems. Also useful for port-forwarding and using tunnels. Something like this setup is ideal to tunnel across an ssh connection that the prone-to-failover host initiates through a reverse connection.

#sending to a remote syslog server on TCP and UDP ports (not encrypted)
destination askapache_failover_loghost {
    tcp("208.86.158.195" port(25214));
    udp("208.86.158.195" port(25214));
    udp("mysyslog1.dyndns.org" port(514));
};
log { 
    source(src); 
    destination(askapache_failover_loghost);
};

And then on the loghost receiving these logs:

#a USB redirected console for flexible viewing
destination debugging_console {
    file("/dev/ttyU1");
};

# listens on IP addresses and ports, sets the incoming settings
source prone_to_failover_host {
    tcp(ip(208.86.158.195),port(25214));
    udp(ip(208.86.158.195) port(25214));

    udp(default-facility(syslog) default-priority(emerg));
    tcp(default-facility(syslog) default-priority(emerg));
}

# log it
log {
    source(prone_to_failover_host); 
    destination(debugging_console);
};

Move log to another file

In order to move some log from /var/log/messages to another file:

#sshd configuration
destination ssh { file("/var/log/ssh.log"); };
filter f_ssh { program("sshd"); };
log { source(src); filter(f_ssh); destination(ssh); };

Configuring as a loghost

Configuring your system to be a loghost is quite simple. Drop the following into your configuration, and create the needed directory. With this simple configuration, log filenames will be based on the FQDN of the remote host, and located in /var/log/remote/. After creating the remote directory, reload your syslog-ng configuration.

source net { udp(); };
destination remote { file("/var/log/remote/${FULLHOST}-log"); };
log { source(net); destination(remote); };

Improve Performance

syslog-ng's performance can be improved in different ways:

Write every so often

It seems that the old sync(X) option is called flush_lines(X) now, where the writing to the file is buffered for X lines. Default is 0 (no buffering).

Avoid redundant processing and disk space

A single log message can be sent to different log files several times. For example, in the initial configuration file, we have the following definitions:

destination cron { file("/var/log/cron.log"); };
destination messages { file("/var/log/messages"); };
filter f_cron { facility(cron); };
filter f_messages { level(info..warn) 
       and not facility(auth, authpriv, mail, news); };
log { source(src); filter(f_cron); destination(cron); };
log { source(src); filter(f_messages); destination(messages); };

The same message from the cron facility will end up in both the cron.log and messages files. To change this behavior we can use the final flag, ending up further processing with the message. Therefore, in this example, if we want messages from the cron facility not ending up in the messages file, we should change the cron's log sentence by:

 log { source(src); filter(f_cron); destination(cron); flags(final); };

another way is to exclude the cron facility from f_messages filter:

 filter f_messages { level(info..warn) and not facility(cron, auth, authpriv, mail, news); };

PostgreSQL Destination

This section will use two roles: syslog and logwriter. syslog will be the administrator of the database syslog and logwriter will only be able to add records to the logs table.

No longer needed to create table for logs. syslog-ng will create automatically.

psql -U postgres
postgres=# CREATE ROLE syslog WITH LOGIN;
postgres=# \password syslog    # Using the \password function is secure because
postgres=# CREATE ROLE logwriter WITH LOGIN;
postgres=# \password logwriter # the password is not saved in history.
postgres=# CREATE DATABASE syslog OWNER syslog;
postgres=# \q # You are done here for the moment

Edit pg_hba.conf to allow syslog and logwriter to establish a connection to PostgreSQL.

/var/lib/postgres/data/pg_hba.conf
# TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD

host    syslog      logwriter   192.168.0.1/24        md5
host    syslog      syslog      192.168.0.10/32       md5

Tell PostgreSQL to reload the configuration files:

# systemctl reload postgresql

Edit /etc/syslog-ng/syslog-ng.conf so that it knows where and how to write to PostgreSQL. syslog-ng will utilize the logwriter role.

...
#
# SQL logging support
#

destination d_pgsql {
  sql(type(pgsql)
  host("127.0.0.1") username("logwriter") password("password")
  database("syslog")
  table("logs_${HOST}_${R_YEAR}${R_MONTH}${R_DAY}") #or whatever you want, example ${HOST}" for hosts, ${LEVEL}" for levels.. etc
  columns("datetime timestamp with time zone", "host varchar(32)", "program varchar(16)", "pid varchar(16)", "message varchar(200)")
  values("$R_ISODATE", "$HOST", "$PROGRAM", "$PID", "$MSG")
  indexes("datetime", "host", "program", "pid", "message"));
};

log { source(src); destination(d_pgsql); };

Finally, restart syslog-ng.

# systemctl restart syslog-ng

And check to see if things are being logged.

psql -U logwriter -d syslog
syslog=> SELECT * FROM <your table name> ORDER BY datetime DESC LIMIT 10;

ISO 8601 timestamps

Before :

#logger These timestamps are not optimal.
#tail -n 1 /var/log/messages.log
Feb 18 14:25:01 hostname logger: These timestamps are not optimal.
#

Add ts_format(iso); to /etc/syslog-ng/syslog-ng.conf in the options section. Example:

options {
  stats_freq (0);
  flush_lines (0);
  time_reopen (10);
  log_fifo_size (1000);
  long_hostnames(off); 
  use_dns (no);
  use_fqdn (no);
  create_dirs (no);
  keep_hostname (yes);
  perm(0640);
  group("log");
  ts_format(iso);      #make ISO-8601 timestamps
  #frac-digits(3);     #optional time to nearest millisecond 
};

Then:

# systemctl reload syslog-ng

After :

#logger Now THAT is a timestamp!
#tail -n 2 /var/log/messages.log
Feb 18 14:25:01 hostname logger: These timestamps are not optimal.
2010-02-18T20:23:58-05:00 electron logger: Now THAT is a timestamp!
#

RFC 3339 timestamps

Same as above, except use rfc3339 instead of iso for ts_format

Log Levels

Log levels are defined separately for each logged facility in syslog-ng config. Available log levels are listed in /usr/include/sys/syslog.h :

define LOG_EMERG       0       /* system is unusable */
define LOG_ALERT       1       /* action must be taken immediately */
define LOG_CRIT        2       /* critical conditions */
define LOG_ERR         3       /* error conditions */
define LOG_WARNING     4       /* warning conditions */
define LOG_NOTICE      5       /* normal but significant condition */
define LOG_INFO        6       /* informational */
define LOG_DEBUG       7       /* debug-level messages */

Macros and Variables

Macros can be used in both templates, and in destination file names. Macros of syslog-ng OSE.

The following code will write the log lines to /var/log/test.log in the format of macroname=value@.

template t_test { template("PROGRAM=$PROGRAM@PID=$PID@BSDTAG=$BSDTAG@TAG=$TAG@TAGS=$TAGS@FACILITY=$FACILITY@FACILITY_NUM=$FACILITY_NUM@LEVEL=$LEVEL@LEVEL_NUM=$LEVEL_NUM@PRI=$PRI@PRIORITY=$PRIORITY@FULLHOST=$FULLHOST@FULLHOST_FROM=$FULLHOST_FROM@HOST=$HOST@HOST_FROM=$HOST_FROM@LOGHOST=$LOGHOST@MSGHDR=$MSGHDR@MSGID=$MSGID@MSGONLY=$MSGONLY@MSG=$MSG@MESSAGE=$MESSAGE@SOURCE=$SOURCE@SOURCEIP=$SOURCEIP@SOURCE_IP=$SOURCE_IP@SEQNUM=$SEQNUM@UNIXTIME=$UNIXTIME@FULLDATE=$FULLDATE@ISODATE=$ISODATE@DATE=$DATE@STAMP=$STAMP@TZ=$TZ@TZOFFSET=$TZOFFSET@SEC=$SEC@MIN=$MIN@HOUR=$HOUR@HOUR12=$HOUR12@DAY=$DAY@WEEK=$WEEK@WEEK_DAY=$WEEK_DAY@WEEK_DAY_ABBREV=$WEEK_DAY_ABBREV@WEEK_DAY_NAME=$WEEK_DAY_NAME@MONTH=$MONTH@MONTH_ABBREV=$MONTH_ABBREV@MONTH_NAME=$MONTH_NAME@MONTH_WEEK=$MONTH_WEEK@YEAR=$YEAR@YEAR_DAY=$YEAR_DAY
\n"); template_escape(no); };

destination d_test { file("/var/log/test.log" template(t_test)); };

log { source(s_local); destination(d_test); flags(final); };

You can create your own value list as below once syslog-ng is restarted with: tail /var/log/test.log|tr "@" "\n"

PROGRAM=kernel
PID=
BSDTAG=4A
TAG=04
TAGS=.source.s_local
FACILITY=kern
FACILITY_NUM=0
LEVEL=warning
LEVEL_NUM=4
PRI=4
PRIORITY=warning
FULLHOST=www.askapache.com
FULLHOST_FROM=www.askapache.com
HOST=www.askapache.com
HOST_FROM=www.askapache.com
LOGHOST=
MSGHDR=kernel: 
MSGID=
MSGONLY=Firewall: *INVALID* IN=eth0 OUT= MAC=00:00 SRC=x.x.x.x DST=198.101.159.98 LEN=40 TOS=0x00 PREC=0x00 TTL=113 ID=7730 DF PROTO=TCP SPT=52369 DPT=80 WINDOW=0 RES=0x00 ACK RST URGP=0 
MSG=Firewall: *INVALID* IN=eth0 OUT= MAC=00:00 SRC=x.x.x.x DST=198.101.159.98 LEN=40 TOS=0x00 PREC=0x00 TTL=113 ID=7730 DF PROTO=TCP SPT=52369 DPT=80 WINDOW=0 RES=0x00 ACK RST URGP=0 
MESSAGE=Firewall: *INVALID* IN=eth0 OUT= MAC=00:00 SRC=x.x.x.x DST=198.101.159.98 LEN=40 TOS=0x00 PREC=0x00 TTL=113 ID=7730 DF PROTO=TCP SPT=52369 DPT=80 WINDOW=0 RES=0x00 ACK RST URGP=0 
SOURCE=s_local
SOURCEIP=127.0.0.1
SOURCE_IP=
UNIXTIME=1369742458
FULLDATE=2013 May 28 08:00:58
ISODATE=2013-05-28T08:00:58-04:00
DATE=May 28 08:00:58
STAMP=2013-05-28T08:00:58-04:00
TZ=-04:00
TZOFFSET=-04:00
SEC=58
MIN=00
HOUR=08
HOUR12=
DAY=28
WEEK=21
WEEK_DAY=3
WEEK_DAY_ABBREV=Tue
WEEK_DAY_NAME=Tuesday
MONTH=05
MONTH_ABBREV=May
MONTH_NAME=May
MONTH_WEEK=4
YEAR=2013
YEAR_DAY=148

Receive and parse common syslog messages

Starting from version 3.16 syslog-ng is capable to receive and parse messages on the most common ports with the most common parsers using the default-network-drivers() source driver.

  • Default listening ports:
    • 514, both TCP and UDP, for RFC3164 (BSD-syslog) formatted traffic
    • 601 TCP, for RFC5424 (IETF-syslog) formatted traffic
    • 6514 TCP, for TLS-encrypted traffic
  • Automatic parsers:
    • RFC3164 message parser
    • RFC5424 message parser
    • Cisco parser
    • Structured EWMM parser
    • Other application adapters (Splunk Common Information Model (CIM), iptables, or sudo)

See Also

  • Netconsole A kernel module that sends all kernel log messages (i.e. dmesg) over the network to another computer, without involving user space (e.g. syslogd).

External Links