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 Administrator	Guide[1] or the	official syslog-ng
       website[2].

       The 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.

BASIC CONCEPTS OF
       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.

       Other optional elements that can	appear in log statements are parsers
       and rewriting rules. Parsers segment messages into different fields to
       help processing the messages, while rewrite rules modify	the messages
       by adding, replacing, or	removing parts of the messages.

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. Object definitions
	   (also called	statements) have the following syntax:

	       type-of-the-object identifier-of-the-object {<parameters>};

	   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.

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

		   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.

		   Note
		   Repeating a definition of an	object (that is, defining the
		   same	object with the	same id	more than once)	is not
		   allowed, unless you use the @define allow-config-dups 1
		   definition in the configuration file.

	   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 file() driver in the following source statement
	   has three options: the filename (/var/log/apache/access.log),
	   follow-freq(), and flags(). The follow-freq() option	also has a
	   parameter, while the	flags()	option 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("<path-to-socket>" max-connections(10) group(log)); };
	       source s_demo_stream2 {
		       unix-stream("<path-to-socket>" group(log) max-connections(10)); };

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

	       options { use-dns(no); };

       o   Objects can be used before definition.

       o   Objects can be defined inline as well. This is useful if you	use
	   the object only once	(for example, a	filter). For details, see ???.

       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("<path-to-socket>" 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 {	network(ip(127.0.0.1) port(1999)); };
	   destination d_tcp { network("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); ... };

       Example 2. Using	global options

       To disable domain name resolving, add the following line	to the
       syslog-ng configuration file:

	   options { use-dns(no); };

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

       Table 1.	Source drivers available in syslog-ng
       +------------------+----------------------------+
       |Name		  | Description		       |
       +------------------+----------------------------+
       |file()		  | Opens the specified	file   |
       |		  | and	reads messages.	       |
       +------------------+----------------------------+
       |internal()	  | Messages generated	       |
       |		  | internally in syslog-ng.   |
       +------------------+----------------------------+
       |network()	  | Receives messages from     |
       |		  | remote hosts using the     |
       |		  | BSD-syslog protocol	over   |
       |		  | IPv4 and IPv6. Supports    |
       |		  | the	TCP, UDP, and TLS      |
       |		  | network protocols.	       |
       +------------------+----------------------------+
       |pipe()		  | Opens the specified	named  |
       |		  | pipe and reads messages.   |
       +------------------+----------------------------+
       |program()	  | Opens the specified	       |
       |		  | application	and reads      |
       |		  | messages from its standard |
       |		  | output.		       |
       +------------------+----------------------------+
       |sun-stream(),	  | Opens the specified	       |
       |sun-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  is running |
       |		  | on,	and collects the       |
       |		  | native log messages	of     |
       |		  | that platform.	       |
       +------------------+----------------------------+
       |systemd-journal() | Collects messages directly |
       |		  | from the journal of	       |
       |		  | platforms that use	       |
       |		  | systemd.		       |
       +------------------+----------------------------+
       |systemd-syslog()  | Collects messages from the |
       |		  | journal using a socket on  |
       |		  | platforms that use	       |
       |		  | systemd.		       |
       +------------------+----------------------------+
       |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		    |
       +---------------+----------------------------+
       |elasticsearch2 | Sends messages	to an	    |
       |	       | Elasticsearch server. The  |
       |	       | elasticsearch2	driver	    |
       |	       | supports Elasticsearch	    |
       |	       | version 2 and newer.	    |
       +---------------+----------------------------+
       |file()	       | Writes	messages to the	    |
       |	       | specified file.	    |
       +---------------+----------------------------+
       |hdfs()	       | Sends messages	into a file |
       |	       | on a Hadoop Distributed    |
       |	       | File System (HDFS)[3]	    |
       |	       | node.			    |
       +---------------+----------------------------+
       |kafka()	       | Publishes log messages	to  |
       |	       | the Apache Kafka[4]	    |
       |	       | message bus, where	    |
       |	       | subscribers can access	    |
       |	       | them.			    |
       +---------------+----------------------------+
       |loggly()       | Sends log messages to the  |
       |	       | Loggly[5]		    |
       |	       | Logging-as-a-Service	    |
       |	       | provider.		    |
       +---------------+----------------------------+
       |logmatic()     | Sends log messages to the  |
       |	       | Logmatic.io[6]		    |
       |	       | Logging-as-a-Service	    |
       |	       | provider.		    |
       +---------------+----------------------------+
       |mongodb()      | Sends messages	to a	    |
       |	       | MongoDB[7] database.	    |
       +---------------+----------------------------+
       |network()      | Sends messages	to a remote |
       |	       | host using the	BSD-syslog  |
       |	       | protocol over IPv4 and	    |
       |	       | IPv6. Supports	the TCP,    |
       |	       | UDP, and TLS network	    |
       |	       | protocols.		    |
       +---------------+----------------------------+
       |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.		    |
       +---------------+----------------------------+
       |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
       +----------------------+----------------------------+
       |Name		      |	Description		   |
       +----------------------+----------------------------+
       |facility()	      |	Filter messages	based on   |
       |		      |	the sending facility.	   |
       +----------------------+----------------------------+
       |filter()	      |	Call another filter	   |
       |		      |	function.		   |
       +----------------------+----------------------------+
       |host()		      |	Filter messages	based on   |
       |		      |	the sending host.	   |
       +----------------------+----------------------------+
       |inlist()	      |	File-based whitelisting	   |
       |		      |	and blacklisting.	   |
       +----------------------+----------------------------+
       |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   |
       |		      |	on 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  source	   |
       |		      |	statement.		   |
       +----------------------+----------------------------+
       |tags()		      |	Select messages	having the |
       |		      |	specified tag.		   |
       +----------------------+----------------------------+

FILES
       /usr/local/

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

SEE ALSO
       syslog-ng(8)

	   Note
	   For the detailed documentation of see The 3.28 Administrator
	   Guide[8]

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

	   For news and	notifications about of syslog-ng, visit	the syslog-ng
	   blogs[10].

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

COPYRIGHT
NOTES
	1. The	Administrator Guide
	   https://www.balabit.com/support/documentation/

	2. the official	syslog-ng website
	   https://www.balabit.com/log-management

	3. Hadoop Distributed File System (HDFS)
	   http://hadoop.apache.org/

	4. Apache Kafka
	   http://kafka.apache.org

	5. Loggly
	   https://www.loggly.com/

	6. Logmatic.io
	   https://logmatic.io/

	7. MongoDB
	   https://www.mongodb.com

	8. The	3.28 Administrator Guide
	   https://www.balabit.com/documents/syslog-ng-ose-latest-guides/en/syslog-ng-ose-guide-admin/html/index.html

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

       10. syslog-ng blogs
	   https://syslog-ng.org/blogs/

3.28				  06/22/2020		     SYSLOG-NG.CONF(5)

NAME | SYNOPSIS | DESCRIPTION | BASIC CONCEPTS OF | 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&sektion=5&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help