Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
SYSLOG-NG.CONF(5)	The syslog-ng.conf manual page	     SYSLOG-NG.CONF(5)

NAME
       syslog-ng.conf -	syslog-ng configuration	file

SYNOPSIS
       syslog-ng.conf

DESCRIPTION
       This manual page	is only	an abstract; for the complete documentation of
       syslog-ng, see The syslog-ng Open Source	Edition	Administrator Guide[1]
       or the official syslog-ng website[2].

       The syslog-ng OSE application is	a flexible and highly scalable system
       logging application. Typically, syslog-ng is used to manage log
       messages	and implement centralized logging, where the aim is to collect
       the log messages	of several devices on a	single,	central	log server.
       The different devices - called syslog-ng	clients	- all run syslog-ng,
       and collect the log messages from the various applications, files, and
       other sources. The clients send all important log messages to the
       remote syslog-ng	server,	where the server sorts and stores them.

       The syslog-ng application reads incoming	messages and forwards them to
       the selected destinations. The syslog-ng	application can	receive
       messages	from files, remote hosts, and other sources.

       Log messages enter syslog-ng in one of the defined sources, and are
       sent to one or more destinations.

       Sources and destinations	are independent	objects; log paths define what
       syslog-ng does with a message, connecting the sources to	the
       destinations. A log path	consists of one	or more	sources	and one	or
       more destinations; messages arriving from a source are sent to every
       destination listed in the log path. A log path defined in syslog-ng is
       called a	log statement.

       Optionally, log paths can include filters. Filters are rules that
       select only certain messages, for example, selecting only messages sent
       by a specific application. If a log path	includes filters, syslog-ng
       sends only the messages satisfying the filter rules to the destinations
       set in the log path.

CONFIGURING SYSLOG-NG
       o   The main body of the	configuration file consists of object
	   definitions:	sources, destinations, logpaths	define which log
	   message are received	and where they are sent. All identifiers,
	   option names	and attributes,	and any	other strings used in the
	   syslog-ng configuration file	are case sensitive. Objects must be
	   defined before they are referenced in another statement. Object
	   definitions (also called statements)	have the following syntax:

	       object_type object_id {<options>};

	   o   Type of the object: One of source, destination, log, filter,
	       parser, rewrite rule, or	template.

	   o   Identifier of the object: A unique name identifying the object.
	       When using a reserved word as an	identifier, enclose the
	       identifier in quotation marks.

		   Tip
		   Use identifiers that	refer to the type of the object	they
		   identify. For example, prefix source	objects	with s_,
		   destinations	with d_, and so	on.

	   o   Parameters: The parameters of the object, enclosed in braces
	       {parameters}.

	   o   Semicolon: Object definitions end with a	semicolon (;).

	   For example,	the following line defines a source and	calls it
	   s_internal.

	       source s_internal { internal(); };

	   The object can be later referenced in other statements using	its
	   ID, for example, the	previous source	is used	as a parameter of the
	   following log statement:

	       log { source(s_internal); destination(d_file); };

       o   The parameters and options within a statement are similar to
	   function calls of the C programming language: the name of the
	   option followed by a	list of	its parameters enclosed	within
	   brackets and	terminated with	a semicolon.

	       option(parameter1, parameter2); option2(parameter1, parameter2);

	   For example,	the following source statement has three options; the
	   first two options (file() and follow_freq())	have a single
	   parameter, while the	third one (flags()) has	two parameters:

	       source s_tail { file("/var/log/apache/access.log"
		   follow_freq(1) flags(no-parse, validate-utf8)); };

	   Objects may have required and optional parameters. Required
	   parameters are positional, meaning that they	must be	specified in a
	   defined order. Optional parameters can be specified in any order
	   using the option(value) format. If a	parameter (optional or
	   required) is	not specified, its default value is used. The
	   parameters and their	default	values are listed in the reference
	   section of the particular object.

	   Example 1. Using required and optional parameters The unix-stream()
	   source driver has a single required argument: the name of the
	   socket to listen on.	Optional parameters follow the socket name in
	   any order, so the following source definitions have the same
	   effect:

	       source s_demo_stream1 {
		       unix-stream("/dev/log" max-connections(10) group(log)); };
	       source s_demo_stream2 {
		       unix-stream("/dev/log" group(log) max-connections(10)); };

       o   Some	options	are global options, or can be set globally, for
	   example, whether syslog-ng OSE should use DNS resolution to resolve
	   IP addresses. Global	options	are detailed in	???.

	       options { use_dns(no); };

       o   All identifiers, attributes,	and any	other strings used in the
	   syslog-ng configuration file	are case sensitive.

       o   Objects can be used before definition.

       o   To add comments to the configuration	file, start a line with	# and
	   write your comments.	These lines are	ignored	by syslog-ng.

	       # Comment: This is a stream source
	       source s_demo_stream {
		       unix-stream("/dev/log" max-connections(10) group(log)); };

       The syntax of log statements is as follows:

	   log {
	       source(s1); source(s2); ...
	       optional_element(filter1|parser1|rewrite1); optional_element(filter2|parser2|rewrite2);...
	       destination(d1);	destination(d2); ...
	       flags(flag1[, flag2...]);
	       };

       The following log statement sends all messages arriving to the
       localhost to a remote server.

	   source s_localhost {	tcp(ip(127.0.0.1) port(1999) );	};
	   destination d_tcp { tcp("10.1.2.3" port(1999); localport(999)); };
	   log { source(s_localhost); destination(d_tcp); };

       The syslog-ng application has a number of global	options	governing DNS
       usage, the timestamp format used, and other general points. Each	option
       may have	parameters, similarly to driver	specifications.	To set global
       options,	add an option statement	to the syslog-ng configuration file
       using the following syntax:

	   options { option1(params); option2(params); ... };

       The sources, destinations, and filters available	in syslog-ng are
       listed below. For details, see The syslog-ng Administrator Guide[1].

       -       .sp
       Table 1.	Source drivers available in syslog-ng
       +-------------------+----------------------------+
       |Name		   | Description		|
       +-------------------+----------------------------+
       |internal()	   | Messages generated		|
       |		   | internally	in syslog-ng.	|
       +-------------------+----------------------------+
       |file()		   | Opens the specified file	|
       |		   | and reads messages.	|
       +-------------------+----------------------------+
       |pipe(),	fifo	   | Opens the specified named	|
       |		   | pipe and reads messages.	|
       +-------------------+----------------------------+
       |pacct()		   | Reads messages from the	|
       |		   | process accounting	logs on	|
       |		   | Linux.			|
       +-------------------+----------------------------+
       |program()	   | Opens the specified	|
       |		   | application and reads	|
       |		   | messages from its standard	|
       |		   | output.			|
       +-------------------+----------------------------+
       |sun-stream(), sun- | Opens the specified	|
       |streams()	   | STREAMS device on Solaris	|
       |		   | systems and reads incoming	|
       |		   | messages.			|
       +-------------------+----------------------------+
       |syslog()	   | Listens for incoming	|
       |		   | messages using the	new	|
       |		   | IETF-standard syslog	|
       |		   | protocol.			|
       +-------------------+----------------------------+
       |system()	   | Automatically detects	|
       |		   | which platform syslog-ng	|
       |		   | OSE is running on,	and	|
       |		   | collects the native log	|
       |		   | messages of that platform.	|
       +-------------------+----------------------------+
       |tcp(), tcp6()	   | Listens on	the specified	|
       |		   | TCP port for incoming	|
       |		   | messages using the	BSD-	|
       |		   | syslog protocol over IPv4	|
       |		   | and IPv6 networks,		|
       |		   | respectively.		|
       +-------------------+----------------------------+
       |udp(), udp6()	   | Listens on	the specified	|
       |		   | UDP port for incoming	|
       |		   | messages using the	BSD-	|
       |		   | syslog protocol over IPv4	|
       |		   | and IPv6 networks,		|
       |		   | respectively.		|
       +-------------------+----------------------------+
       |unix-dgram()	   | Opens the specified unix	|
       |		   | socket in SOCK_DGRAM mode	|
       |		   | and listens for incoming	|
       |		   | messages.			|
       +-------------------+----------------------------+
       |unix-stream()	   | Opens the specified unix	|
       |		   | socket in SOCK_STREAM mode	|
       |		   | and listens for incoming	|
       |		   | messages.			|
       +-------------------+----------------------------+

       Table 2.	Destination drivers available in syslog-ng
       +-----------------+----------------------------+
       |Name		 | Description		      |
       +-----------------+----------------------------+
       |file()		 | Writes messages to the     |
       |		 | specified file.	      |
       +-----------------+----------------------------+
       |fifo(),	pipe()	 | Writes messages to the     |
       |		 | specified named pipe.      |
       +-----------------+----------------------------+
       |program()	 | Forks and launches the     |
       |		 | specified program, and     |
       |		 | sends messages to its      |
       |		 | standard input.	      |
       +-----------------+----------------------------+
       |sql()		 | Sends messages into an SQL |
       |		 | database. In	addition to   |
       |		 | the standard	syslog-ng     |
       |		 | packages, the sql()	      |
       |		 | destination requires	      |
       |		 | database-specific packages |
       |		 | to be installed. Refer to  |
       |		 | the section appropriate    |
       |		 | for your platform in	???.  |
       +-----------------+----------------------------+
       |syslog()	 | Sends messages to the      |
       |		 | specified remote host      |
       |		 | using the IETF-syslog      |
       |		 | protocol. The IETF	      |
       |		 | standard supports message  |
       |		 | transport using the UDP,   |
       |		 | TCP,	and TLS	networking    |
       |		 | protocols.		      |
       +-----------------+----------------------------+
       |tcp() and tcp6() | Sends messages to the      |
       |		 | specified TCP port of a    |
       |		 | remote host using the BSD- |
       |		 | syslog protocol over	IPv4  |
       |		 | and IPv6, respectively.    |
       +-----------------+----------------------------+
       |udp() and udp6() | Sends messages to the      |
       |		 | specified UDP port of a    |
       |		 | remote host using the BSD- |
       |		 | syslog protocol over	IPv4  |
       |		 | and IPv6, respectively.    |
       +-----------------+----------------------------+
       |unix-dgram()	 | Sends messages to the      |
       |		 | specified unix socket in   |
       |		 | SOCK_DGRAM style (BSD).    |
       +-----------------+----------------------------+
       |unix-stream()	 | Sends messages to the      |
       |		 | specified unix socket in   |
       |		 | SOCK_STREAM style (Linux). |
       +-----------------+----------------------------+
       |usertty()	 | Sends messages to the      |
       |		 | terminal of the specified  |
       |		 | user, if the	user is	      |
       |		 | logged in.		      |
       +-----------------+----------------------------+

       Table 3.	Filter functions available in syslog-ng	OSE
       +----------------------+----------------------------+
       |Name		      |	Description		   |
       +----------------------+----------------------------+
       |facility()	      |	Filter messages	based on   |
       |		      |	the sending facility.	   |
       +----------------------+----------------------------+
       |filter()	      |	Call another filter	   |
       |		      |	function.		   |
       +----------------------+----------------------------+
       |host()		      |	Filter messages	based on   |
       |		      |	the sending host.	   |
       +----------------------+----------------------------+
       |level()	or priority() |	Filter messages	based on   |
       |		      |	their priority.		   |
       +----------------------+----------------------------+
       |match()		      |	Use a regular expression   |
       |		      |	to filter messages based   |
       |		      |	on a specified header or   |
       |		      |	content	field.		   |
       +----------------------+----------------------------+
       |message()	      |	Use a regular expression   |
       |		      |	to filter messages based   |
       |		      |	their content.		   |
       +----------------------+----------------------------+
       |netmask()	      |	Filter messages	based on   |
       |		      |	the IP address of the	   |
       |		      |	sending	host.		   |
       +----------------------+----------------------------+
       |program()	      |	Filter messages	based on   |
       |		      |	the sending application.   |
       +----------------------+----------------------------+
       |source()	      |	Select messages	of the	   |
       |		      |	specified syslog-ng OSE	   |
       |		      |	source statement.	   |
       +----------------------+----------------------------+
       |tags()		      |	Select messages	having the |
       |		      |	specified tag.		   |
       +----------------------+----------------------------+

FILES
       /usr/local/

       /usr/local/etc/syslog-ng.conf

SEE ALSO
       syslog-ng(8)

       The syslog-ng OSE 3.3 Administrator Guide[1]

       If you experience any problems or need help with	syslog-ng, visit visit
       the syslog-ng wiki[3] or	the syslog-ng mailing list[4].

       For news	and notifications about	of syslog-ng, visit the	syslog-ng
       Insider Blog[5].

AUTHOR
       This manual page	was written by the BalaBit Documentation Team
       <documentation@balabit.com>.

COPYRIGHT

       The authors grant permission to copy, distribute	and/or modify this
       manual page under the terms of the GNU General Public License Version 2
       or newer	(GPL v2+).

NOTES
	1. The syslog-ng Open Source Edition Administrator Guide
	   http://www.balabit.com/support/documentation/

	2. the official	syslog-ng website
	   http://www.balabit.com/network-security/syslog-ng/

	3. visit the syslog-ng wiki
	   http://www.balabit.com/wiki/syslog-ng-faq

	4. syslog-ng mailing list
	   https://lists.balabit.hu/mailman/listinfo/syslog-ng

	5. syslog-ng Insider Blog
	   http://insider.blogs.balabit.com

syslog-ng Open Source Edition	  12/21/2016		     SYSLOG-NG.CONF(5)

NAME | SYNOPSIS | DESCRIPTION | CONFIGURING SYSLOG-NG | FILES | SEE ALSO | AUTHOR | COPYRIGHT | NOTES

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=syslog-ng.conf&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help