'\" t
.\"     Title: syslog-ng.conf
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
.\"      Date: 08/19/2016
.\"    Manual: The syslog-ng.conf manual page
.\"    Source: syslog-ng Open Source Edition 3.3
.\"  Language: English
.\"
.TH "SYSLOG\-NG\&.CONF" "5" "08/19/2016" "syslog\-ng Open Source Edition" "The syslog-ng.conf manual page"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
syslog-ng.conf \- syslog\-ng configuration file
.SH "SYNOPSIS"
.HP \w'\fBsyslog\-ng\&.conf\fR\ 'u
\fBsyslog\-ng\&.conf\fR
.SH "DESCRIPTION"
.PP
This manual page is only an abstract; for the complete documentation of syslog\-ng, see
\m[blue]\fB\fBThe syslog\-ng Open Source Edition Administrator Guide\fR\fR\m[]\&\s-2\u[1]\d\s+2
or
\m[blue]\fBthe official syslog\-ng website\fR\m[]\&\s-2\u[2]\d\s+2\&.
.PP
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
\fIsources\fR\&. The clients send all important log messages to the remote syslog\-ng server, where the server sorts and stores them\&.
.PP
The syslog\-ng application reads incoming messages and forwards them to the selected
\fIdestinations\fR\&. The syslog\-ng application can receive messages from files, remote hosts, and other
\fIsources\fR\&.
.PP
Log messages enter syslog\-ng in one of the defined sources, and are sent to one or more
\fIdestinations\fR\&.
.PP
Sources and destinations are independent objects;
\fIlog paths\fR
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
\fIlog statement\fR\&.
.PP
Optionally, log paths can include
\fIfilters\fR\&. 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\&.
.SH "CONFIGURING SYSLOG-NG"
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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:
.sp
.if n \{\
.RS 4
.\}
.nf
object_type object_id {<options>};
.fi
.if n \{\
.RE
.\}
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIType of the object\fR: One of
\fIsource\fR,
\fIdestination\fR,
\fIlog\fR,
\fIfilter\fR,
\fIparser\fR,
\fIrewrite\fR
rule, or
\fItemplate\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIIdentifier of the object\fR: A unique name identifying the object\&. When using a reserved word as an identifier, enclose the identifier in quotation marks\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBTip\fR
.ps -1
.br
Use identifiers that refer to the type of the object they identify\&. For example, prefix source objects with
\fIs_\fR, destinations with
\fId_\fR, and so on\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fIParameters\fR: The parameters of the object, enclosed in braces
\fI{parameters}\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fISemicolon\fR: Object definitions end with a semicolon (\fI;\fR)\&.
.RE
.sp
For example, the following line defines a source and calls it
\fIs_internal\fR\&.
.sp
.if n \{\
.RS 4
.\}
.nf
source s_internal { internal(); };
.fi
.if n \{\
.RE
.\}
.sp
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:
.sp
.if n \{\
.RS 4
.\}
.nf
log { source(s_internal); destination(d_file); };
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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\&.
.sp
.if n \{\
.RS 4
.\}
.nf
option(parameter1, parameter2); option2(parameter1, parameter2);
.fi
.if n \{\
.RE
.\}
.sp
For example, the following source statement has three options; the first two options (\fIfile()\fR
and
\fIfollow_freq()\fR) have a single parameter, while the third one (\fIflags()\fR) has two parameters:
.sp
.if n \{\
.RS 4
.\}
.nf
source s_tail { file("/var/log/apache/access\&.log"
    follow_freq(1) flags(no\-parse, validate\-utf8)); };
.fi
.if n \{\
.RE
.\}
.sp
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\&.
.PP
\fBExample\ \&1.\ \&Using required and optional parameters\fR
The
\fIunix\-stream()\fR
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:
.sp
.if n \{\
.RS 4
.\}
.nf
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)); };
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
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
???\&.
.sp
.if n \{\
.RS 4
.\}
.nf
options { use_dns(no); };
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
All identifiers, attributes, and any other strings used in the syslog\-ng configuration file are case sensitive\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
Objects can be used before definition\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
To add comments to the configuration file, start a line with
\fI#\fR
and write your comments\&. These lines are ignored by syslog\-ng\&.
.sp
.if n \{\
.RS 4
.\}
.nf
# Comment: This is a stream source
source s_demo_stream {
        unix\-stream("/dev/log" max\-connections(10) group(log)); };
.fi
.if n \{\
.RE
.\}
.RE
.PP
The syntax of log statements is as follows:
.sp
.if n \{\
.RS 4
.\}
.nf
log {
    source(s1); source(s2); \&.\&.\&.
    optional_element(filter1|parser1|rewrite1); optional_element(filter2|parser2|rewrite2);\&.\&.\&.
    destination(d1); destination(d2); \&.\&.\&.
    flags(flag1[, flag2\&.\&.\&.]);
    };
.fi
.if n \{\
.RE
.\}
.PP
The following log statement sends all messages arriving to the localhost to a remote server\&.
.sp
.if n \{\
.RS 4
.\}
.nf
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); };
.fi
.if n \{\
.RE
.\}
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
options { option1(params); option2(params); \&.\&.\&. };
.fi
.if n \{\
.RE
.\}
.PP
The sources, destinations, and filters available in syslog\-ng are listed below\&. For details, see
\m[blue]\fB\fBThe syslog\-ng Administrator Guide\fR\fR\m[]\&\s-2\u[1]\d\s+2\&.

\-       .sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&Source drivers available in syslog-ng
.TS
allbox tab(:);
lB lB.
T{
Name
T}:T{
Description
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
internal()
T}:T{
Messages generated internally in syslog\-ng\&.
T}
T{
file()
T}:T{
Opens the specified file and reads messages\&.
T}
T{
pipe(), fifo
T}:T{
Opens the specified named pipe and reads messages\&.
T}
T{
pacct()
T}:T{
Reads messages from the process accounting logs on Linux\&.
T}
T{
program()
T}:T{
Opens the specified application and reads messages from its standard output\&.
T}
T{
sun-stream(), sun-streams()
T}:T{
Opens the specified \fISTREAMS\fR device on Solaris systems and reads incoming messages\&.
T}
T{
syslog()
T}:T{
Listens for incoming messages using the new IETF-standard syslog protocol\&.
T}
T{
system()
T}:T{
Automatically detects which platform syslog\-ng OSE is running on, and collects the native log messages of that platform\&.
T}
T{
tcp(), tcp6()
T}:T{
Listens on the specified TCP port for incoming messages using the BSD-syslog protocol over IPv4 and IPv6 networks, respectively\&.
T}
T{
udp(), udp6()
T}:T{
Listens on the specified UDP port for incoming messages using the BSD-syslog protocol over IPv4 and IPv6 networks, respectively\&.
T}
T{
unix-dgram()
T}:T{
Opens the specified unix socket in \fISOCK_DGRAM\fR mode and listens for incoming messages\&.
T}
T{
unix-stream()
T}:T{
Opens the specified unix socket in \fISOCK_STREAM\fR mode and listens for incoming messages\&.
T}
.TE
.sp 1
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&2.\ \&Destination drivers available in syslog-ng
.TS
allbox tab(:);
lB lB.
T{
Name
T}:T{
Description
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
file()
T}:T{
Writes messages to the specified file\&.
T}
T{
fifo(), pipe()
T}:T{
Writes messages to the specified named pipe\&.
T}
T{
program()
T}:T{
Forks and launches the specified program, and sends messages to its standard input\&.
T}
T{
sql()
T}:T{
Sends messages into an SQL database\&. In addition to the standard syslog\-ng packages, the \fIsql()\fR destination requires database\-specific packages to be installed\&. Refer to the section appropriate for your platform in ???\&.
T}
T{
syslog()
T}:T{
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\&.
T}
T{
tcp() and tcp6()
T}:T{
Sends messages to the specified TCP port of a remote host using the BSD-syslog protocol over IPv4 and IPv6, respectively\&.
T}
T{
udp() and udp6()
T}:T{
Sends messages to the specified UDP port of a remote host using the BSD-syslog protocol over IPv4 and IPv6, respectively\&.
T}
T{
unix-dgram()
T}:T{
Sends messages to the specified unix socket in \fISOCK_DGRAM\fR style (BSD)\&.
T}
T{
unix-stream()
T}:T{
Sends messages to the specified unix socket in \fISOCK_STREAM\fR style (Linux)\&.
T}
T{
usertty()
T}:T{
Sends messages to the terminal of the specified user, if the user is logged in\&.
T}
.TE
.sp 1
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&3.\ \&Filter functions available in syslog-ng OSE
.TS
allbox tab(:);
lB lB.
T{
Name
T}:T{
Description
T}
.T&
l l
l l
l l
l l
l l
l l
l l
l l
l l
l l.
T{
facility()
T}:T{
Filter messages based on the sending facility\&.
T}
T{
filter()
T}:T{
Call another filter function\&.
T}
T{
host()
T}:T{
Filter messages based on the sending host\&.
T}
T{
level() or priority()
T}:T{
Filter messages based on their priority\&.
T}
T{
match()
T}:T{
Use a regular expression to filter messages based on a specified header or content field\&.
T}
T{
message()
T}:T{
Use a regular expression to filter messages based their content\&.
T}
T{
netmask()
T}:T{
Filter messages based on the IP address of the sending host\&.
T}
T{
program()
T}:T{
Filter messages based on the sending application\&.
T}
T{
source()
T}:T{
Select messages of the specified syslog\-ng OSE source statement\&.
T}
T{
tags()
T}:T{
Select messages having the specified tag\&.
T}
.TE
.sp 1
.SH "FILES"
.PP
/usr/local/
.PP
/usr/local/etc/syslog\-ng\&.conf
.SH "SEE ALSO"
.PP
\fBsyslog\-ng\fR(8)
.PP
\m[blue]\fB\fBThe syslog\-ng OSE 3\&.3 Administrator Guide\fR\fR\m[]\&\s-2\u[1]\d\s+2
.PP
If you experience any problems or need help with syslog\-ng, visit
\m[blue]\fBvisit the syslog\-ng wiki\fR\m[]\&\s-2\u[3]\d\s+2
or the
\m[blue]\fB\fBsyslog\-ng mailing list\fR\fR\m[]\&\s-2\u[4]\d\s+2\&.
.PP
For news and notifications about of syslog\-ng, visit the
\m[blue]\fB\fBsyslog\-ng Insider Blog\fR\fR\m[]\&\s-2\u[5]\d\s+2\&.
.SH "AUTHOR"
.PP
This manual page was written by the BalaBit Documentation Team <documentation@balabit\&.com>\&.
.SH "COPYRIGHT"
.SS ""
.PP
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+)\&.
.SH "NOTES"
.IP " 1." 4
\fBThe syslog-ng Open Source Edition Administrator Guide\fR
.RS 4
\%http://www.balabit.com/support/documentation/
.RE
.IP " 2." 4
the official syslog-ng website
.RS 4
\%http://www.balabit.com/network-security/syslog-ng/
.RE
.IP " 3." 4
visit the syslog-ng wiki
.RS 4
\%http://www.balabit.com/wiki/syslog-ng-faq
.RE
.IP " 4." 4
\fBsyslog-ng mailing list\fR
.RS 4
\%https://lists.balabit.hu/mailman/listinfo/syslog-ng
.RE
.IP " 5." 4
\fBsyslog-ng Insider Blog\fR
.RS 4
\%http://insider.blogs.balabit.com
.RE