The `syslog-ng.conf` manual page


syslog-ng.conf — configuration file




The AxoSyslog application is a flexible and highly scalable system logging application. Typically, AxoSyslog 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 AxoSyslog, and collect the log messages from the various applications, files, and other sources. The clients send all important log messages to the remote AxoSyslog server, where the server sorts and stores them.

Basic concepts of AxoSyslog

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

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

Sources and destinations are independent objects, log paths define what AxoSyslog 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 AxoSyslog 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, AxoSyslog 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 AxoSyslog

  • 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.conf configuration file are case sensitive. Object definitions (also called statements) have the following syntax:

        type-of-the-object identifier-of-the-object {<parameters>};
    • Type of the object: One of source, destination, log, filter, parser, rewrite rule, or template.

      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 AxoSyslog configuration file are case sensitive.

      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.

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

    • 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); };
  • 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: 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)); };
  • Some options are global options, or can be set globally, for example, whether AxoSyslog should use DNS resolution to resolve IP addresses.

        options { use-dns(no); };
    • Objects can be used before definition.

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

    • To add comments to the configuration file, start a line with # and write your comments. These lines are ignored by AxoSyslog.

      #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); ...
    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( port(1999)); };
destination d_tcp { network("" port(1999) localport(999)); };
log { source(s_localhost); destination(d_tcp); };

The AxoSyslog 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 AxoSyslog configuration file using the following syntax:

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

Example: Using global options

To disable domain name resolving, add the following line to the AxoSyslog configuration file:

options { use-dns(no); };

The sources, destinations, and filters available in AxoSyslog are listed below. For details, see the AxoSyslog documentation.

Table: Available source drivers

lidarr(), prowlarr(), radarr(), readarr(), sonarr(), whisparr() Collect Pi-hole FTL logs
darwin-oslog(), darwin-oslog-stream() Collect native macOS system logs
default-network-drivers() Receive and parse common syslog messages
internal() Collect internal messages
file() Collect messages from text files
wildcard-file() Collect messages from multiple text files
hypr-audit-trail(), hypr-app-audit-trail() Fetch events from the Hypr REST API
jellyfin() Collect Jellyfin logs
linux-audit() Collect messages from Linux audit logs
kubernetes() Collect and parse messages in the Kubernetes CRI (Container Runtime Interface) format
mbox() Convert local email messages to log messages
mqtt() Fetch messages from MQTT brokers
network() Collect messages using the RFC3164 protocol
nodejs() Receive JSON messages from nodejs applications
osquery() Collect and parse osquery result logs
opentelemetry() Receive logs, metrics, and traces from OpenTelemetry clients over the OpenTelemetry Protocol (OTLP/gRPC)
pacct() Collect process accounting logs on Linux
pihole-ftl() Collect Pi-hole FTL logs
pipe() Collect messages from named pipes
program() Receive messages from external applications
python() Server-style Python source that receives messages
python-fetcher() Write a fetcher-style Python source
qbittorrent() Collect qBittorrent logs
snmptrap() Read Net-SNMP traps
sun-streams() Collect messages on Sun Solaris
syslog() Collect messages using the IETF-syslog protocol
syslog-ng-otlp() Receive logs from another node using OpenTelemetry
system() Collect the system-specific log messages of a platform
systemd-journal() Collect messages from the systemd-journal system log storage
systemd-syslog() Collect systemd messages using a socket
tcp(), tcp6(), udp(), udp6() OBSOLETE - Collect messages from remote hosts using the BSD syslog protocol
unix-stream(), unix-dgram() Collect messages from UNIX domain sockets
stdin() Collect messages from the standard input stream

Table 2. Available destination drivers

amqp() Publish messages using AMQP
bigquery() Send messages to Google BigQuery
collectd() Send metrics to collectd
discord() Send alerts and notifications to Discord
elasticsearch2() DEPRECATED - Send messages directly to Elasticsearch version 2.0 or higher
elasticsearch-http() Send messages to Elasticsearch using the HTTP Bulk API
file() Store messages in plain-text files
google-pubsub() Send messages to Google Pub/Sub
graphite() Send metrics to Graphite
graylog2() Send logs to Graylog
hdfs() Store messages on the Hadoop Distributed File System (HDFS)
java() Post messages over HTTP using Java
http() Post messages over HTTP without Java
kafka() Publish messages to Apache Kafka (Java implementation)
kafka-c() Publish messages to Apache Kafka (C implementation)
loggly() Send logs to Loggly
logmatic() Send logs to
logscale() Send messages to Falcon LogScale
loki() Send messages to Grafana Loki
mongodb() Store messages in a MongoDB database
mqtt() Send messages to an MQTT broker
network() Send messages to a remote log server using the RFC3164 protocol
openobserve-log() Send messages to OpenObserve
opensearch() Send messages to OpenSearch
osquery() Send log messages to osquery's syslog table
opentelemetry() Send logs, metrics, and traces to OpenTelemetry
pipe() Send messages to named pipes
program() Send messages to external applications
pseudofile() Deliver messages to special files
python() Write custom Python destinations
redis() Store name-value pairs in Redis
riemann() Monitor your data with Riemann
s3() Send log messages to Amazon Simple Storage Service (S3)
slack() Send alerts and notifications to a Slack channel
smtp() Generate SMTP messages (emails) from logs
snmp() Send SNMP traps
splunk-hec-event() Send messages to Splunk HEC
sql() Store messages in an SQL database
stdout() Send messages to standard output
stomp() Publish messages using STOMP
sumologic-http(), sumologic-syslog() Send messages to Sumo Logic
syslog() Send messages to a remote logserver using the IETF-syslog protocol
syslog-ng() Forward logs to another syslog-ng node
syslog-ng-otlp() Forward logs to another node using OpenTelemetry
tcp(), tcp6(), udp(), udp6() OBSOLETE - Send messages to a remote log server using the legacy BSD-syslog protocol
telegram() Send messages to Telegram
unix-stream(), unix-dgram() Send messages to UNIX domain sockets
usertty() Send messages to a user terminal

Table 3. Filter functions

facility()Filter messages based on the sending facility.
filter()Call another filter function.
host()Filter messages based on the sending host.
in-list()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 IPv4 address of the sending host.
netmask6()Filter messages based on the IPv6 address of the sending host.
program()Filter messages based on the sending application.
rate-limit()Limit messages rate based on arbitrary keys in each message.
source()Select messages of the specified AxoSyslog source statement.
tags()Select messages having the specified tag.




See also


Getting help

  • The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
  • For news and notifications about AxoSyslog, visit the Axoflow blog.
  • If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow