syslog-ng Open Source Edition 3.16 - Administration Guide

Reusing configuration blocks

To create a reusable configuration snippet and reuse parts of a configuration file, you have to define the block (for example, a source) once, and reference it later. (Such reusable blocks are sometimes called a Source Configuration Library, or SCL.) Any syslog-ng object can be a block. Use the following syntax to define a block:

block type name() {<contents of the block>};

Type must be one of the following: destination, filter, log, parser, rewrite, root, source. The root blocks can be used in the "root" context of the configuration file, that is, outside any other statements.

Blocks may be nested into each other, so for example a block can be built from other blocks. Blocks are somewhat similar to C++ templates.

The type and name combination of each block must be unique, that is, two blocks can have the same name if their type is different.

To use a block in your configuration file, you have to do two things:

• Include the file defining the block in the syslog-ng.conf file — or a file already included into syslog-ng.conf. Version 3.7 and newer automatically includes the *.conf files from the <directory-where-syslog-ng-is-installed>/scl/*/ directories.

• Reference the name of the block in your configuration file. This will insert the block into your configuration. For example, to use a block called myblock, include the following line in your configuration:

  myblock()

  Blocks may have parameters, but even if they do not, the reference must include opening and closing parentheses like in the previous example.

The contents of the block will be inserted into the configuration when syslog-ng OSE is started or reloaded.

block source myappsource() {
        file("/opt/var/myapplication.log" follow-freq(1) default-facility(syslog)); };

@version: 3.16
@include "<correct/path>/myblocks.conf"
source s_myappsource { myappsource(); };
...
log { source(s_myappsource); destination(...); };

To define a block that defines more than one object, use root as the type of the block, and reference the block from the main part of the syslog-ng OSE configuration file.

block root mylogs() {
    source s_file {
        file("/var/log/mylogs.log" follow-freq(1));
    };
    destination d_local {
        file("/var/log/messages");
    };
    log {
        source(s_file); destination(d_local);
    };
};

Passing arguments to configuration blocks

Configuration blocks can receive arguments as well. The parameters the block can receive must be specified when the block is defined, using the following syntax:

block type block_name(argument1(<default-value-of-the-argument>) argument2(<default-value-of-the-argument>) argument3())

If an argument does not have a default value, use empty parentheses after the name of the argument. To refer the value of the argument in the block, use the name of the argument between backticks (for example, `argument1`).

block source s_logfile (filename("messages")) {
    file("/var/log/`filename`" );
};

source s_example {
    s_logfile(filename("logfile.log"));
};

If you reference the block with more arguments then specified in its definition, you can use these additional arguments as a single argument-list within the block. That way, you can use a variable number of optional arguments in your block. This can be useful when passing arguments to a template, or optional arguments to an underlying driver. To reference this argument-list, insert `__VARARGS__` to the place in the block where you want to insert the argument-list. Note that you can use this only once in a block. The following definition extends the logfile block from the previous example, and passes the optional arguments (follow-freq(1) flags(no-parse)) to the file() source.

block source s_logfile (filename("messages")) {
    file("/var/log/`filename`" `__VARARGS__`);
};

source s_example {
    s_logfile(filename("logfile.log") follow-freq(1) flags(no-parse));
};

block source pacct(file("/var/log/account/pacct") follow-freq(1)) {
    @module pacctformat
    file("`file`" follow-freq(`follow-freq`) format("pacct") tags(".pacct") `__VARARGS__`);
};

Generating configuration blocks from a script

Purpose:

The syslog-ng OSE application can automatically execute scripts when it is started, and can include the output of such script in the configuration file. To create and use a script that generates a part of the syslog-ng OSE configuration file (actually, a configuration block), complete the following steps. The steps include examples for collecting Apache access log files (access.log) from subdirectories, but you can create any script that creates a valid syslog-ng OSE configuration snippet.

source: Read, receive, and collect log messages

How sources work

A source is where syslog-ng receives log messages. Sources consist of one or more drivers, each defining where and how messages are received.

To define a source, add a source statement to the syslog-ng configuration file using the following syntax:

source <identifier> {
    source-driver(params); source-driver(params); ...
};

source s_demo_tcp {
    network(ip(10.1.2.3) port(1999));
};

source s_demo_two_drivers {
    network(ip(10.1.2.3) port(1999));
    network(ip(10.1.2.3) port(1999) transport("udp"));
};

source headerless_messages { network(default-facility(syslog) default-priority(emerg)); };

Define a source only once. The same source can be used in several log paths. Duplicating sources causes syslog-ng to open the source (TCP/IP port, file, and so on) more than once, which might cause problems. For example, include the /dev/log file source only in one source statement, and use this statement in more than one log path if needed.

To collect log messages on a specific platform, it is important to know how the native syslogd communicates on that platform. The following table summarizes the operation methods of syslogd on some of the tested platforms:

Each possible communication mechanism has a corresponding source driver in syslog-ng. For example, to open a unix socket with SOCK_DGRAM style communication use the driver unix-dgram. The same socket using the SOCK_STREAM style — as used under Linux — is called unix-stream.

source s_demo {
    internal();
    network(transport("udp"));
    unix-dgram("/dev/log");
};

The following table lists the source drivers available in syslog-ng.