'\" t
.\"     Title: syslog-ng.conf
.\"    Author: [see the "Author" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/28/2023
.\"    Manual: The syslog-ng.conf manual page
.\"    Source: 3.28
.\"  Language: English
.\"
.TH "SYSLOG\-NG\&.CONF" "5" "02/28/2023" "3\&.28" "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 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 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\&.
.SH "BASIC CONCEPTS OF"
.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\&.
.PP
Other optional elements that can appear in log statements are
\fIparsers\fR
and
\fIrewriting rules\fR\&. 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\&.
.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\&. Object definitions (also called statements) have the following syntax:
.sp
.if n \{\
.RS 4
.\}
.nf
type\-of\-the\-object identifier\-of\-the\-object {<parameters>};
.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\&.
.sp
All identifiers, attributes, and any other strings used in the syslog\-ng configuration file are case sensitive\&.
.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
\fBs_\fR, destinations with
\fBd_\fR, and so on\&.
.sp .5v
.RE
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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
\fI@define allow\-config\-dups 1\fR
definition in the configuration file\&.
.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
\fB{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 (\fB;\fR)\&.
.RE
.sp
For example, the following line defines a source and calls it
\fBs_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
\fIfile()\fR
driver in the following source statement has three options: the filename (/var/log/apache/access\&.log),
\fIfollow\-freq()\fR, and
\fIflags()\fR\&. The
\fIfollow\-freq()\fR
option also has a parameter, while the
\fIflags()\fR
option 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("<path\-to\-socket>" max\-connections(10) group(log)); };
source s_demo_stream2 {
        unix\-stream("<path\-to\-socket>" 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 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
.\}
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
.\}
Objects can be defined inline as well\&. This is useful if you use the object only once (for example, a filter)\&. For details, see
???\&.
.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
\fB#\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("<path\-to\-socket>" 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 { 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); };
.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
\fBExample\ \&2.\ \&Using global options\fR
.PP
To disable domain name resolving, add the following line to the syslog\-ng configuration file:
.sp
.if n \{\
.RS 4
.\}
.nf
options { use\-dns(no); };
.fi
.if n \{\
.RE
.\}
.PP
The sources, destinations, and filters available in syslog\-ng are listed below\&. For details, see
\fBThe syslog\-ng Administrator Guide\fR\&.
.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{
file()
T}:T{
Opens the specified file and reads messages\&.
T}
T{
internal()
T}:T{
Messages generated internally in syslog\-ng\&.
T}
T{
network()
T}:T{
Receives messages from remote hosts using the BSD\-syslog protocol over IPv4 and IPv6\&. Supports the TCP, UDP, and TLS network protocols\&.
T}
T{
pipe()
T}:T{
Opens the specified named pipe and reads messages\&.
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  is running on, and collects the native log messages of that platform\&.
T}
T{
systemd\-journal()
T}:T{
Collects messages directly from the journal of platforms that use systemd\&.
T}
T{
systemd\-syslog()
T}:T{
Collects messages from the journal using a socket on platforms that use systemd\&.
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
l l
l l
l l
l l
l l.
T{
elasticsearch2
T}:T{
Sends messages to an Elasticsearch server\&. The \fIelasticsearch2\fR driver supports Elasticsearch version 2 and newer\&.
T}
T{
file()
T}:T{
Writes messages to the specified file\&.
T}
T{
hdfs()
T}:T{
Sends messages into a file on a \m[blue]\fBHadoop Distributed File System (HDFS)\fR\m[]\&\s-2\u[3]\d\s+2 node\&.
T}
T{
kafka()
T}:T{
Publishes log messages to the \m[blue]\fBApache Kafka\fR\m[]\&\s-2\u[4]\d\s+2 message bus, where subscribers can access them\&.
T}
T{
loggly()
T}:T{
Sends log messages to the \m[blue]\fBLoggly\fR\m[]\&\s-2\u[5]\d\s+2 Logging\-as\-a\-Service provider\&.
T}
T{
logmatic()
T}:T{
Sends log messages to the \m[blue]\fBLogmatic\&.io\fR\m[]\&\s-2\u[6]\d\s+2 Logging\-as\-a\-Service provider\&.
T}
T{
mongodb()
T}:T{
Sends messages to a \m[blue]\fBMongoDB\fR\m[]\&\s-2\u[7]\d\s+2 database\&.
T}
T{
network()
T}:T{
Sends messages to a remote host using the BSD\-syslog protocol over IPv4 and IPv6\&. Supports the TCP, UDP, and TLS network protocols\&.
T}
T{
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{
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
.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.
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{
inlist()
T}:T{
File\-based whitelisting and blacklisting\&.
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 on 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  source statement\&.
T}
T{
tags()
T}:T{
Select messages having the specified tag\&.
T}
.TE
.sp 1
.SH "FILES"
.PP
/usr/
.PP
/etc/syslog\-ng/syslog\-ng\&.conf
.SH "SEE ALSO"
.PP
\fBsyslog\-ng\fR(8)
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
For the detailed documentation of see
\m[blue]\fB\fBThe 3\&.28 Administrator Guide\fR\fR\m[]\&\s-2\u[8]\d\s+2
.PP
If you experience any problems or need help with syslog\-ng, visit the
\m[blue]\fB\fBsyslog\-ng mailing list\fR\fR\m[]\&\s-2\u[9]\d\s+2\&.
.PP
For news and notifications about of syslog\-ng, visit the
\m[blue]\fB\fBsyslog\-ng blogs\fR\fR\m[]\&\s-2\u[10]\d\s+2\&.
.sp .5v
.RE
.SH "AUTHOR"
.PP
This manual page was written by the Balabit Documentation Team <documentation@balabit\&.com>\&.
.SH "COPYRIGHT"
.SH "NOTES"
.IP " 1." 4
\fBThe  Administrator Guide\fR
.RS 4
\%https://www.balabit.com/support/documentation/
.RE
.IP " 2." 4
the official syslog-ng website
.RS 4
\%https://www.balabit.com/log-management
.RE
.IP " 3." 4
Hadoop Distributed File System (HDFS)
.RS 4
\%http://hadoop.apache.org/
.RE
.IP " 4." 4
Apache Kafka
.RS 4
\%http://kafka.apache.org
.RE
.IP " 5." 4
Loggly
.RS 4
\%https://www.loggly.com/
.RE
.IP " 6." 4
Logmatic.io
.RS 4
\%https://logmatic.io/
.RE
.IP " 7." 4
MongoDB
.RS 4
\%https://www.mongodb.com
.RE
.IP " 8." 4
\fBThe  3.28 Administrator Guide\fR
.RS 4
\%https://www.balabit.com/documents/syslog-ng-ose-latest-guides/en/syslog-ng-ose-guide-admin/html/index.html
.RE
.IP " 9." 4
\fBsyslog-ng mailing list\fR
.RS 4
\%https://lists.balabit.hu/mailman/listinfo/syslog-ng
.RE
.IP "10." 4
\fBsyslog-ng blogs\fR
.RS 4
\%https://syslog-ng.org/blogs/
.RE