To configure AxoSyslog, edit the syslog-ng.conf file with any regular text editor application. The location of the configuration file depends on the platform you are running AxoSyslog, and how you have installed AxoSyslog it.

Native packages of a platform (like the ones downloaded from Linux repositories) typically place the configuration file under the /etc/syslog-ng/ directory.
Containers: When running AxoSyslog in a container, typically you map an external file to the /etc/syslog-ng/syslog-ng.conf file within the container. Check the mapped volumes of your container, and edit the external file.
Kubernetes: If you’re running AxoSyslog in Kubernetes and have installed it with helm, usually you configure AxoSyslog by editing a values.yaml file, and redeploying AxoSyslog. Often the syslog-ng.conf part is under the config.raw section in the values.yaml file. For details, see Parameters of the AxoSyslog collector Helm chart.

2 - The configuration syntax in detail

Every syslog-ng.conf configuration file must begin with a line containing version information. For syslog-ng version 4.5, this line looks like:

   @version: 4.5.0

If the configuration file does not contain the version information, syslog-ng assumes that the file is for version 2.x. In this case it interprets the configuration and sends warnings about the parts of the configuration that should be updated. Version 3.0 and later can operate with configuration files of version 2.x, but the default values of certain parameters have changed since 3.0.
@version: current sets the configuration version to the currently installed version.

Example: A simple configuration file

The following is a very simple configuration file for syslog-ng: it collects the internal messages of syslog-ng and the messages from /dev/log into the /var/log/messages_syslog-ng.log file.

   @version: 4.5.0
    source s_local {
        unix-dgram("/dev/log"); internal();
    };
    destination d_file {
        file("/var/log/messages_syslog-ng.log");
    };
    log {
        source(s_local); destination(d_file);
    };

As a syslog-ng user described on a mailing list:

Alan McKinnon
The syslog-ng’s config file format was written by programmers for programmers to be understood by programmers. That may not have been the stated intent, but it is how things turned out. The syntax is exactly that of C, all the way down to braces and statement terminators.

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 syslog-ng.conf configuration file are case sensitive.
  Note
```
<p>Use identifiers that refer to the type of the object they identify. For example, prefix source objects with <code>s_</code>, destinations with <code>d_</code>, and so on.</p>
```
  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. Global options are detailed in Global options.
```
    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). For details, see Defining configuration objects inline.
- 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));
    };
```

Note

Before activating a new configuration, check that your configuration file is syntactically correct using the syslog-ng --syntax-only command.

To activate the configuration, reload the configuration using the /etc/init.d/syslog-ng reload command.

3 - Notes about the configuration syntax

When you are editing the syslog-ng.conf configuration file, note the following points:

The configuration file can contain a maximum of 6665 source / destination / log elements.
When writing the names of options and parameters (or other reserved words), the hyphen (-) and underscore (_) characters are equivalent, for example, max-connections(10) and max_connections(10) are both correct.
Numbers can be prefixed with + or - to indicate positive or negative values. Numbers beginning with zero (0) or 0x are treated as octal or hexadecimal numbers, respectively.
Starting with AxoSyslog version 3.5, you can use suffixes for kilo-, mega-, and gigabytes. Use the Kb, Mb, or Gb suffixes for the base-10 version, and Kib, Mib, or Gib for the base-2 version. That is, 2MB means 2000000, while 2MiB means 2097152. For example, to set the log-msg-size() option to 2000000 bytes, use log-msg-size(2Mb).

You can use commas (,) to separate options or other parameters for readability, AxoSyslog completely ignores them. The following declarations are equivalent:

    source s_demo_stream {
        unix-stream("<path-to-socket>" max-connections(10) group(log));
    };
    source s_demo_stream {
        unix-stream("<path-to-socket>", max-connections(10), group(log));
    };

When enclosing object IDs (for example, the name of a destination) between double-quotes ("mydestination"), the ID can include whitespace as well, for example:
```
    source "s demo stream" {
        unix-stream("<path-to-socket>" max-connections(10) group(log));
    };
```
For notes on using regular expressions, see Regular expressions.
You can use if {}, elif {}, and else {} blocks to configure conditional expressions. For details, see if-else-elif: Conditional expressions.

4 - Defining configuration objects inline

Starting with AxoSyslog 3.4, you can define configuration objects inline, where they are actually used, without having to define them in a separate placement. This is useful if you need an object only once, for example, a filter or a rewrite rule. Every object can be defined inline: sources, destinations, filters, parsers, rewrite rules, and so on.

To define an object inline, use braces instead of parentheses. That is, instead of <object-type> (<object-id>);, you use <object-type> {<object-definition>};

Example: Using inline definitions

The following two configuration examples are equivalent. The first one uses traditional statements, while the second uses inline definitions.

   source s_local {
        system();
        internal();
    };
    destination d_local {
        file("/var/log/messages");
    };
    log {
        source(s_local);
        destination(d_local);
    };

   log {
        source {
            system();
            internal();
        };
        destination {
            file("/var/log/messages");
        };
    };

5 - Using channels in configuration objects

Starting with AxoSyslog 3.4, every configuration object is a log expression. Every configuration object is essentially a configuration block, and can include multiple objects. To reference the block, only the top-level object must be referenced. That way you can use embedded log statements, junctions and in-line object definitions within source, destination, filter, rewrite and parser definitions. For example, a source can include a rewrite rule to modify the messages received by the source, and that combination can be used as a simple source in a log statement. This feature allows you to preprocess the log messages very close to the source itself.

To embed multiple objects into a configuration object, use the following syntax. Note that you must enclose the configuration block between braces instead of parenthesis.

   <type-of-top-level-object> <name-of-top-level-object> {
        channel {
            <configuration-objects>
        };
    };

Example: Using channels

For example, to process a log file in a specific way, you can define the required processing rules (parsers and rewrite expressions) and combine them in a single object:

   source s_apache {
        channel {
            source {
                file("/var/log/apache/error.log");
            };
            parser(p_apache_parser);
        };
    };
    log {
        source(s_apache); ...
    };

The s_apache source uses a file source (the error log of an Apache webserver) and references a specific parser to process the messages of the error log. The log statement references only the s_apache source, and any other object in the log statement can already use the results of the p_apache_parserparser.

Note

You must start the object definition with a channel even if you will use a junction, for example:

   parser demo-parser() {
        channel {
            junction {
                channel { ... };
                channel { ... };
            };
        };
    };

If you want to embed configuration objects into sources or destinations, always use channels, otherwise the source or destination will not behave as expected. For example, the following configuration is good:

   source s_filtered_hosts {
        channel{
            source {
                pipe("/dev/pipe");
                syslog(ip(192.168.0.1) transport("tcp"));
                syslog(ip(127.0.0.1) transport("tcp"));
            };
            filter {
                netmask(10.0.0.0/16);
            };
        };
    };

6 - Global and environmental variables

You can define global variables in the configuration file. Global variables are actually name-value pairs. When syslog-ng processes the configuration file during startup, it automatically replaces name with value. To define a global variable, use the following syntax:

   @define name "value"

The value can be any string, but special characters must be escaped (for details, see Regular expressions). To use the variable, insert the name of the variable enclosed between backticks (`, similarly to using variables in Linux or UNIX shells) anywhere in the configuration file. If backticks are meant literally, repeat the backticks to escape them. For example:

``not-substituted-value``

The value of the global variable can be also specified using the following methods:

Without any quotes, as long as the value does not contain any spaces or special characters. In other words, it contains only the following characters: a-zA-Z0-9_..
Between apostrophes, in case the value does not contain apostrophes.
Between double quotes, in which case special characters must be escaped using backslashes (\\).

Note

The environmental variables of the host are automatically imported and can be used as global variables.

In AxoSyslog 3.24 and later, the location of the configuration file is available as the syslog-ng-sysconfdir variable.

Example: Using global variables

For example, if an application is creating multiple log files in a directory, you can store the path in a global variable, and use it in your source definitions.

   @define mypath "/opt/myapp/logs"
    source s_myapp_1 {
        file("`mypath`/access.log" follow-freq(1));
    };
    source s_myapp_2 {
        file("`mypath`/error.log" follow-freq(1));
    };
    source s_myapp_3 {
        file("`mypath`/debug.log" follow-freq(1));
    };

The AxoSyslog application will interpret this as:

   @define mypath "/opt/myapp/logs"
    source s_myapp_1 {
        file("/opt/myapp/logs/access.log" follow-freq(1));
    };
    source s_myapp_2 {
        file("/opt/myapp/logs/error.log" follow-freq(1));
    };
    source s_myapp_3 {
        file("/opt/myapp/logs/debug.log" follow-freq(1));
    };

7 - Configuration identifier

Starting with AxoSyslog version 4.2, you can specify a configuration identifier in the syslog-ng.conf file, for example:

@config-id: cfg-20230404-13-g02b0850fc

This can be useful in managed environments, where AxoSyslog instances and their configuration are automatically deployed or generated.

To show the configuration ID, run syslog-ng-ctl config --id

This returns the ID of the currently active configuration, and the SHA256 hash of the configuration (the hash of the output of the syslog-ng-ctl config --preprocessed command). The output is similar to:

cfg-20230404-13-g02b0850fc (08ddecfa52a3443b29d5d5aa3e5114e48dd465e195598062da9f5fc5a45d8a83)

8 - Using modules

To increase its flexibility and simplify the development of additional modules, the AxoSyslog application is modular. The majority of AxoSyslog’s functionality is in separate modules. As a result, it is also possible to fine-tune the resource requirements of AxoSyslog (for example, by loading only the modules that are actually used in the configuration, or simply omitting modules that are not used but require large amount of memory).

Each module contains one or more plugins that add some functionality to AxoSyslog (for example, a destination or a source driver).

To display the list of available modules, run the syslog-ng --version command.
To display the description of the available modules, run the syslog-ng --module-registry command.
To customize which modules AxoSyslog automatically loads when AxoSyslog starts, use the --default-modules command-line option of AxoSyslog.
To request loading a module from the AxoSyslog configuration file, see Loading modules.

For details on the command-line parameters of AxoSyslog mentioned in the previous list, see the AxoSyslog man page at The syslog-ng manual page.

8.1 - Loading modules

The AxoSyslog application loads every available module during startup.

To load a module that is not loaded automatically, include the following statement in the AxoSyslog configuration file:

   @module <module-name>

Note the following points about the @module statement:

The @module statement is a top-level statement, that is, it cannot be nested into any other statement. It is usually used immediately after the @version statement.
Every @module statement loads a single module: loading multiple modules requires a separate @module statement for every module.
In the configuration file, the @module statement of a module must be earlier than the module is used.

Note

To disable loading every module automatically, set the autoload-compiled-modules global variable to 0 in your configuration file:

   @define autoload-compiled-modules 0

Note that in this case you have to explicitly load the modules you want to use.

Use the @requires statement to ensure that the specified module is loaded

To ensure that a module is loaded, include the following statement in the AxoSyslog configuration file or the external files included in the configuration file:

   @requires <module-name>

Note

If you include the @requires statement in the:

AxoSyslog configuration file, AxoSyslog attempts to load the required module. If it fails to load the module, AxoSyslog stops and an error message is displayed.
external files included in the configuration file, AxoSyslog attempts to load the required module. If it fails to load the module, only the external file is not processed.

Note that this is not true for modules marked as mandatory. You can make a dependency module mandatory by defining an error message after the @requires <module-name> statement, for example:

Example
@requires http "The http() driver is required for elasticsearch-http(). Install syslog-ng-mod-http to continue."

8.2 - Listing configuration options

Starting with AxoSyslog 3.25, you can use the syslog-ng-cfg-db.py utility to list the available options of configuration objects. For example, you can list all the options that can be set in the file source, and so on.

The syslog-ng-cfg-db.py utility has the following options:

The following command lists the contexts that the utility supports.
```
    syslog-ng-cfg-db.py
```
Note
Currently, sources and destinations are supported.
The following command lists the available drivers of a context:
```
    syslog-ng-cfg-db.py -c <source|destination>
```

The following command lists the available options of a specific driver and specifies the context and the driver:

    syslog-ng-cfg-db.py -c <source|destination> -d <driver>

For example, to list the options of the kafka-c() destination driver:

    syslog-ng-cfg-db.py -c destination -d kafka-c

The output includes the available options of the driver in alphabetical order, and the type of the option. For example:

    destination kafka-c(
        bootstrap-servers/kafka-bootstrap-servers(<string>)
        client-lib-dir(<string>)
        config/option()
        config/option(<string> <arrow> <string-or-number>)
        config/option(<string> <string-or-number>)
        flush-timeout-on-reload(<number>)
        flush-timeout-on-shutdown(<number>)
        frac-digits(<number>)
        key(<string>)
        local-time-zone/time-zone(<string>)
        log-fifo-size(<number>)
        message/template(<string>)
        on-error(<string>)
        persist-name(<string>)
        poll-timeout(<number>)
        properties-file(<path>)
        send-time-zone(<string>)
        sync-send(<yesno>)
        throttle(<number>)
        time-zone(<string>)
        topic(<string>)
        ts-format(<string>)
        workers(<number>)
        config/option(
            <string>(<string-or-number>)
        )
        key(
            <identifier>(<string>)
        )
        message/template(
            <identifier>(<string>)
        )
    )

Note

The script caches the list of the options, so if you want to rebuild the database, you have to use the -r option.

8.3 - Visualize the configuration

Starting with AxoSyslog 3.25, you can visualize the configuration of a running AxoSyslog instance using the syslog-ng-ctl --export-config-graph command. The command walks through the effective configuration, and exports it as a graph into a JSON structure.

The resulting JSON file can be converted into DOT file format that visualization tools (for example, Graphviz) can use. The package includes a Python script to convert the exported JSON file into DOT format: <syslog-ng-installation-directory>/contrib/scripts/config-graph-json-to-dot.py

You can convert the DOT file into PNG or PDF format using external tools.

9 - Managing complex configurations

The following sections describe some methods that can be useful to simplify the management of large-scale AxoSyslog installations.

9.1 - Including configuration files

The AxoSyslog application supports including external files in its configuration file, so parts of its configuration can be managed separately. To include the contents of a file in the AxoSyslog configuration, use the following syntax:

   @include "<filename>"

This imports the entire file into the configuration of AxoSyslog, at the location of the include statement. The <filename> can be one of the following:

A filename, optionally with full path. The filename (not the path) can include UNIX-style wildcard characters (*, ?). When using wildcard characters, AxoSyslog will include every matching file. For details on using wildcard characters, see Types and options of regular expressions.
A directory. When including a directory, AxoSyslog will try to include every file from the directory, except files beginning with a ~ (tilde) or a . (dot) character. Including a directory is not recursive. The files are included in alphabetic order, first files beginning with uppercase characters, then files beginning with lowercase characters. For example, if the directory contains the a.conf, B. conf, c.conf, D.conf files, they will be included in the following order: B.conf, D. conf, a.conf, c.conf.

When including configuration files, consider the following points:

The default path where AxoSyslog looks for the file depends on where AxoSyslog is installed. The syslog-ng --version command displays this path as Include-Path.
Defining an object twice is not allowed, unless you use the @define allow-config-dups 1 definition in the configuration file. If an object is defined twice (for example, the original configuration file and the file imported into this configuration file both define the same option, source, or other object), then the object that is defined later in the configuration file will be effective. For example, if you set a global option at the beginning of the configuration file, and later include a file that defines the same option with a different value, then the option defined in the imported file will be used.
- Files can be embedded into each other: the included files can contain include statements as well, up to a maximum depth of 15 levels.
- You cannot include complete configuration files into each other, only configuration snippets can be included. This means that the included file cannot have a @version statement.
- Include statements can only be used at top level of the configuration file. For example, the following is correct:
```
    @version: 4.5.0
    @include "example.conf"
```
  But the following is not:
```
    source s_example {
        @include "example.conf"
    };
```

Warning

The AxoSyslog application will not start if it cannot find a file that is to be included in its configuration. Always double-check the filenames, paths, and access rights when including configuration files, and use the --syntax-only command-line option to check your configuration.

9.2 - 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. Any AxoSyslog 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, options, parser, rewrite, root, source. The root blocks can be used in the “root” context of the configuration file, that is, outside any other statements.

Note that options can be used in blocks only in version 3.22 and later.

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 AxoSyslog is started or reloaded.

Example: Reusing configuration blocks

Suppose you are running an application on your hosts that logs into the /opt/var/myapplication.log file. Create a file (for example, myblocks.conf) that stores a source describing this file and how it should be read:

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

Include this file in your main syslog-ng.conf configuration file, reference the block, and use it in a logpath:

   @version: 4.5.0
    @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 AxoSyslog configuration file.

Example: Defining blocks with multiple elements

The following example defines a source, a destination, and a log path to connect them.

   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);
        };
    };

Note

Since the block is inserted into the AxoSyslog configuration when AxoSyslog is started, the block can be generated dynamically using an external script if needed. This is useful when you are running AxoSyslog on different hosts and you want to keep the main configuration identical.

If you want to reuse more than a single configuration object, for example, a logpath and the definitions of its sources and destinations, use the include feature to reuse the entire snippet. For details, see Including configuration files.

Mandatory parameters

You can express in block definitons that a parameter is mandatory by defining it with empty brackets (). In this case, the parameter must be overridden in the reference block. Failing to do so will result in an error message and initialization failure.

To make a parameter expand into nothing (for example, because it has no default value, like hook-commands() or tls()), insert a pair of double quote marks inside the empty brackets: ("")

Example: Mandatory parameters

The following example defines a TCP source that can receive the following parameters: the port where AxoSyslog listens (localport), and optionally source flags (flags).

   block source my_tcp_source(localport() flags("")) {
        network(port(`localport`) transport(tcp) flags(`flags`));
    };

Because localport is defined with empty brackets (), it is a mandatory parameter. However, the flags parameter is not mandatory, because it is defined with an empty double quote bracket pair (""). If you do not enter a specific value when referencing this parameter, the value will be an empty string. This means that in this case

   my_tcp_source(localport(8080))

will be expanded to:

   network(port(8080) transport(tcp) flags());

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 an empty double quote bracket pair ("") 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`

Example: Passing arguments to blocks

The following sample defines a file source block, which can receive the name of the file as a parameter. If no parameter is set, it reads messages from the /var/log/messages file.

   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.

The three dots (…) at the end of the argument list refer to any additional parameters. It tells AxoSyslog that this macro accepts __VARARGS__, therefore any name-value pair can be passed without validation. 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)
        );
    };

Example: Using arguments in blocks

The following example is the code of the pacct() source driver, which is actually a block that can optionally receive two arguments.

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

Example: Defining global options in blocks

The following example defines a block called setup-dns() to set DNS-related settings at a single place.

   block options setup-dns(use-dns()) {
        keep-hostname(no);
        use-dns(`use-dns`);
        use-fqdn(`use-dns`);
    dns-cache(`use-dns`);
    };
    
    options {
        setup-dns(use-dns(yes));
    };

9.3 - Generating configuration blocks from a script

Purpose:

The AxoSyslog 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 AxoSyslog 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 AxoSyslog configuration snippet.

Steps:

Navigate to the directory where you have installed AxoSyslog (for example, /opt/syslog-ng/share/include/scl/), and create a new directory, for example, apache-access-logs. The name of the directory will be used in the AxoSyslog configuration file as well, so use a descriptive name.
Create a file called plugin.conf in this new directory.
Edit the plugin.conf file and add the following line:
```
    @module confgen context(source) name(<directory-name>) exec("`scl-root`/<directory-name>/<my-script>")
```
Replace <directory-name> with the name of the directory (for example, apache-access-logs), and <my-script> with the filename of your script (for example, apache-access-logs.sh). You can reference the script in your AxoSyslog configuration file as a configuration block using the value name option.
The context option determines the type of the configuration snippet that the script generates, and 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. In the example, context(source) means that the output of the script will be used within a source statement.
You can pass parameters to the script. In the script these parameters are available as environment variables, and have the confgen_ prefix. For example, passing the --myparameter parameter becomes available in the script as the confgen_myparameter environment variable.
Write a script that generates the output you need, and formats it to a configuration snippet that AxoSyslog can use. The filename of the script must match with the filename used in plugin.conf, for example, apache-access-logs.sh.
The following example checks the /var/log/apache2/ directory and its subdirectories, and creates a source driver for every directory that contains an access.log file.
```
    #!/bin/bash
    for i in `find /var/log/apache2/ -type d`; do
        echo "file(\"$i/access.log\" flags(no-parse) program-override(\"apache2\"));";
    done;
```
The script generates an output similar to this one, where service* is the actual name of a subdirectory:
```
    file("/var/log/apache2/service1/access.log" flags(no-parse) program-override("apache2"));
    file("/var/log/apache2/service2/access.log" flags(no-parse) program-override("apache2"));
```
Include the plugin.conf file 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. For details on including configuration files, see Including configuration files.

Add the block you defined in the plugin.conf file to your AxoSyslog configuration file. You can reference the block using the value of the name option from the plugin.conf file, followed by parentheses, for example, apache-access-logs(). Make sure to use the block in the appropriate context of the configuration file, for example, within a source statement if the value of the context option in the plugin.conf file is source.

    @include "scl.conf"
    ...
    source s_apache {
        file("/var/log/apache2/access.log" flags(no-parse) program-override("apache2"));
        file("/var/log/apache2/error.log" flags(no-parse) program-override("apache2"));
        file("/var/log/apache2/ssl.log" flags(no-parse) program-override("apache2"));
        apache-access-logs();
    };

    log {
        source(s_apache); destination(d_central);
    };
    ...

Check if your modified AxoSyslog configuration file is syntactically correct using the syslog-ng --syntax-only command.
If your modified configuration is syntactically correct, load the new configuration file using the syslog-ng-ctl reload command.

10 - Python code in external files

You can extend and customize AxoSyslog easily by writing destinations, parsers, template functions, and sources in Python.

Instead of writing Python code into your AxoSyslog configuration file, you can store the Python code for your Python object in an external file. That way, it is easier to write, maintain, and debug the code. You can store the Python code in any directory in your system, but make sure to include it in your Python path.

When referencing a Python class from an external file in the class() option of a Python block in the AxoSyslog configuration file, the class name must include the name of the Python file containing the class, without the path and the .py extension. For example, if the MyDestination class is available in the /etc/syslog-ng/etc/pythonexample.py file, use class("pythonexample.MyDestination"):

   destination d_python_to_file {
        python(
            class("pythonexample.MyDestination")
        );
    };
    log {
        source(src);
        destination(d_python_to_file);
    };

Note

Starting with 3.26, AxoSyslog assigns a persist name to Python sources and destinations. The persist name is generated from the class name. If you want to use the same Python class multiple times in your AxoSyslog configuration, add a unique persist-name() to each source or destination, otherwise AxoSyslog will not start. For example:

   log {
        source { python(class(PyNetworkSource) options("port" "8080") persist-name("<unique-string>); };
        source { python(class(PyNetworkSource) options("port" "8081")); };
    };

Alternatively, you can include the following line in the Python package: @staticmethod generate_persist_name. For example:

   from syslogng import LogSource
      class PyNetworSource(LogSource):
        @staticmethod
        def generate_persist_name(options):
            return options["port"]
        def run(self):
            pass
        def request_exit(self):
            pass

If you store the Python code in a separate Python file and only include it in the AxoSyslog configuration file, make sure that the PYTHONPATH environment variable includes the path to the Python file, and export the PYTHON_PATH environment variable. For example, if you start AxoSyslog manually from a terminal and you store your Python files in the /opt/syslog-ng/etc directory, use the following command: export PYTHONPATH=/opt/syslog-ng/etc.

In production, when AxoSyslog starts on boot, you must configure your startup script to include the Python path. The exact method depends on your operating system. For recent Red Hat Enterprise Linux, Fedora, and CentOS distributions that use systemd, the systemctl command sources the /etc/sysconfig/syslog-ng file before starting AxoSyslog. (On openSUSE and SLES, /etc/sysconfig/syslog file.) Append the following line to the end of this file: PYTHONPATH="<path-to-your-python-file>", for example, PYTHONPATH="/opt/syslog-ng/etc".

To help debugging and troubleshooting your Python code, you can send log messages to the internal() source of AxoSyslog. For details, see Logging from your Python code.

11 - Logging from your Python code

You can extend and customize AxoSyslog easily by writing destinations, parsers, template functions, and sources in Python.

To debug and troubleshoot your Python code, AxoSyslog allows you to use the logger() method to send log messages to the internal() source of AxoSyslog. That way the diagnostic messages of your Python code are treated the same way as other such log messages of AxoSyslog. This has the following benefits:

The logger() method respects the log level settings of AxoSyslog. You can write error, warning, info, debug, and trace level messages.
You can follow what your Python code is doing even if AxoSyslog is running as a daemon in the background.

Logging to the internal() source is available in AxoSyslog version 3.20 and later.

To send log messages to the internal() source from Python

Add the following import to your Python code:
```
    import syslogng
```
Create a logger object:
```
    logger = syslogng.Logger()
```
Use the logger object in your Python code, for example:
```
    logger.info("This is a sample log message send from the Python code.")
```
You can use the following log levels: logger.error, logger.warning, logger.info, logger.debug, logger.trace

Make sure that your AxoSyslog configuration includes the internal() source, for example:

    source s_internal { internal(); };
    destination d_internal { file("/var/log/internal.txt"); };
    log {source(s_internal); destination(d_internal); };

The configuration file

1 - Location of the configuration file

2 - The configuration syntax in detail

Example: A simple configuration file

Note

Example: Using required and optional parameters

Note

3 - Notes about the configuration syntax

4 - Defining configuration objects inline

Example: Using inline definitions

5 - Using channels in configuration objects

Example: Using channels

Note

6 - Global and environmental variables

Note

Example: Using global variables

7 - Configuration identifier

8 - Using modules

8.1 - Loading modules

Note

Use the @requires statement to ensure that the specified module is loaded

Note

8.2 - Listing configuration options

Note

Note

8.3 - Visualize the configuration

9 - Managing complex configurations

9.1 - Including configuration files

Warning

9.2 - Reusing configuration blocks

Example: Reusing configuration blocks

Example: Defining blocks with multiple elements

Note

Mandatory parameters

Example: Mandatory parameters

Passing arguments to configuration blocks

Example: Passing arguments to blocks

Example: Using arguments in blocks

Example: Defining global options in blocks

9.3 - Generating configuration blocks from a script

Purpose:

Steps:

10 - Python code in external files

Note

11 - Logging from your Python code