### Example .install file pattern for syslog-ng Python module

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

This is an example of the content for a .install file in packaging/debian/ that captures the files of a custom Python module after installation. The file should be named syslog-ng-mod-<yourmodule>.install and contain wildcard patterns for the module files.

```plaintext
usr/lib/syslog-ng/python/syslogng/modules/<yourmodule>/*
```

--------------------------------

### Config API test example

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Use this pattern when the feature has a config.create_*() helper. It creates a source, parser, filter, and destination, then starts syslog-ng and asserts the destination received the expected number of logs.

```python

def test_with_config_api(config, syslog_ng):
    """Modern test using Config API."""

    source = config.create_example_msg_generator_source(num=5, freq=0)
    parser = config.create_syslog_parser()
    filter_obj = config.create_filter("facility(syslog)")
    dest = config.create_file_destination(file_name="output.log")

    config.create_logpath(statements=[source, parser, filter_obj, dest])

    syslog_ng.start(config)
    assert len(dest.read_logs(5)) == 5

```

--------------------------------

### Enable and start syslog-ng

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/contrib/solaris-packaging/solaris10_install.txt

Command to enable and start the syslog-ng service.

```shell
# svcadm enable -t svc:/system/syslog-ng:default
```

--------------------------------

### Raw config test example

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Use this pattern when the feature lacks a Config API helper, such as map-value-pairs parser. It sets a raw config string, starts syslog-ng, and reads the output file directly to assert the number of logs.

```python

def test_with_raw_config(config, syslog_ng):
    """Test map-value-pairs parser using raw config."""

    raw_config = f"""
@version: {config.get_version()}

source s_gen {{
    example-msg-generator(num(5) freq(0) template("test"));
}};

parser p_map {{
    map-value-pairs(key("MSG*" rekey(add-prefix("foo."))));
}};

destination d_file {{
    file("output.log" template("${{foo.MSG}}\n"));
}};

log {{ source(s_gen); parser(p_map); destination(d_file); }};
"""

    config.set_raw_config(raw_config)
    syslog_ng.start(config)

    # Read file directly (relative to current working directory)
    import time
    time.sleep(1)
    with open("output.log", 'r') as f:
        logs = f.readlines()
    assert len(logs) == 5

```

--------------------------------

### Get the dockcross helper for linux-arm64

Source: https://github.com/syslog-ng/syslog-ng/wiki/Cross-compile-syslog-ng

Downloads the dockcross helper script for the linux-arm64 cross-compile toolchain and makes it executable. Requires Docker to be installed on the build machine.

```bash
$ docker run --rm dockcross/linux-arm64 > dockcross
$ chmod +x dockcross
```

--------------------------------

### Add DNF repository and install syslog-ng

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Add the DNF repository, refresh metadata, and install syslog-ng on RHEL. Run as root.

```shell
sudo curl -o /etc/yum.repos.d/syslog-ng-ose-stable.repo https://ose-repo.syslog-ng.com/yum/syslog-ng-ose-stable.repo
```

```shell
sudo dnf makecache
```

```shell
sudo dnf install syslog-ng
```

--------------------------------

### Install syslog-ng with apt

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Install syslog-ng on Debian/Ubuntu systems using the APT package manager. Run as root.

```shell
apt install syslog-ng
```

--------------------------------

### Update and install syslog-ng via APT

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Update your repositories and install syslog-ng after adding the APT repository.

```shell
sudo apt update
```

```shell
sudo apt install syslog-ng
```

--------------------------------

### InstantAckTracker Usage

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

Example of initializing an InstantAckTracker, which provides callbacks as soon as messages are delivered, without preserving order.

```APIDOC
## InstantAckTracker

### Description
Initializes an InstantAckTracker to receive acknowledgements as soon as messages are delivered, without preserving original ordering.

### Usage
In the `init` method of a `LogFetcher` subclass, create an `InstantAckTracker` instance, passing the `ack_callback` parameter.

### Parameters
- **ack_callback** (callable) - Required - A function that takes a single argument (the acknowledged message bookmark).

### Example
```python
class MyFetcher(LogFetcher):
    def init(self, options):
        self.ack_tracker = InstantAckTracker(ack_callback=self.message_acked)
        return True

    def message_acked(self, acked_message_bookmark):
        pass
```
```

--------------------------------

### Install syslog-ng with DESTDIR

Source: https://github.com/syslog-ng/syslog-ng/wiki/Cross-compile-syslog-ng

Installs the cross-compiled syslog-ng into /work/build/install, preserving the root filesystem layout (e.g., /usr/local/bin/syslog-ng becomes /work/build/install/usr/local/bin/syslog-ng).

```bash
$ make install DESTDIR=/work/build/install
```

--------------------------------

### Unpack and install syslog-ng and libdbi8 packages

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/contrib/solaris-packaging/solaris10_install.txt

Commands to unpack and install the syslog-ng Premium Edition and libdbi8 packages using gunzip and pkgadd. The commands include installing libiconv and libgcc dependencies first.

```shell
# libiconv-1.11-sol9-sparc-local.gz
# libgcc-3.4.6-sol9-sparc-local.gz
# gunzip syslog-ng_<version_number>_sparc.pkg.gz
# gunzip libdbi8_<version>_<arch>.gz
# pkgadd -d libiconv-1.11-sol9-sparc-local
# pkgadd -d libgcc-3.4.6-sol9-sparc-local
# pkgadd -d syslog-ng_<version_number>_sparc.pkg
# pkgadd -d libdbi8_<version>_<arch>.pkg
```

--------------------------------

### Debian: Create <package-name>.install file

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/packaging/README.md

Create a file named <package-name>.install that lists the files debhelper should install. Each line is a shell-like wildcard pattern.

```text
usr/lib/syslog-ng/*/libsecure-logging.so
usr/bin/slog*

```

--------------------------------

### Install syslog-ng on Arch Linux

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Install syslog-ng on Arch Linux using pacman.

```shell
pacman -S syslog-ng
```

--------------------------------

### Build and install slogencrypt executable

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/secure-logging/slogencrypt/CMakeLists.txt

Defines the slogencrypt executable from slogencrypt.c, adds the secure-logging include directory, links required libraries, and installs the binary to bin.

```cmake
add_executable(slogencrypt slogencrypt.c)
target_include_directories (secure-logging PUBLIC ${CMAKE_CURRENT_SOURCE_DIR})	
target_link_libraries(slogencrypt eventlog syslog-ng syslog-ng-secure-logging)
install(TARGETS slogencrypt RUNTIME DESTINATION bin)
```

--------------------------------

### Complete hypr-audit-trail() source configuration with all options

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/syslogng/modules/hypr/README.md

Full configuration example for hypr-audit-trail() showing all optional parameters: page-size(), initial-hours(), application-skip-list(), log-level(), flags(), and ignore-persistence().

```syslog-ng
    source s_hypr {
        hypr-audit-trail(
            url('https://<custom domain>.hypr.com')
            bearer-token('<base64 encoded bearer token>')
            page-size(<number of results to return in a single page>)
            initial-hours(<number of hours to search backward on initial fetch>)
            application-skip-list('HYPRDefaultApplication', 'HYPRDefaultWorkstationApplication')
            log-level('INFO')
            flags(<optional flags passed to the source>)
            ignore-persistence(<yes/no>)
        );
    };
```

--------------------------------

### Install syslog-ng on macOS with Homebrew

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Install syslog-ng on macOS using Homebrew.

```shell
brew install syslog-ng
```

--------------------------------

### Install PostgreSQL driver for SQL destination

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/contrib/solaris-packaging/solaris10_install.txt

Commands to install the PostgreSQL driver package. Requires the SUNWpostgr-libs package to be installed from the Solaris 10 install DVD.

```shell
# gunzip libdbd8-pgsql_<version>_<arch>.gz
# pkgadd -d libdbd8-pgsql_<version>_<arch>.pkg
```

--------------------------------

### Basic syslog-ng configuration

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Basic syslog-ng configuration that reads system logs from /dev/log and writes them to a single file. Use as a starting point for a minimal setup.

```config
@version: current
@include "scl.conf"

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

```

--------------------------------

### Mixing Config API with Raw Config (Correct)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Correct example: use either pure Config API or pure raw config, not both. Option 1 uses Config API; Option 2 uses raw config and reads file directly.

```python
# Option 1: Pure Config API
dest = config.create_file_destination(file_name="output.log")
config.create_logpath(statements=[source, dest])

# Option 2: Pure Raw Config
raw_config = "..."
config.set_raw_config(raw_config)
# Read file directly, don't use dest.get_stats()
```

--------------------------------

### Install SQLite driver for SQL destination

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/contrib/solaris-packaging/solaris10_install.txt

Commands to install the SQLite driver package. Requires downloading and installing the sqlite-3.3.6-sol9-sparc-local package from sunfreeware.com.

```shell
# gunzip sqlite-3.3.6-sol9-sparc-local.gz 
# pkgadd -d sqlite-3.3.6-sol9-sparc-local
# gunzip libdbd8-sqlite_<version>_<arch>.gz
# pkgadd -d libdbd8-sqlite_<version>_<arch>.pkg
```

--------------------------------

### Install MySQL driver for SQL destination

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/contrib/solaris-packaging/solaris10_install.txt

Commands to install the MySQL driver package for syslog-ng. Requires downloading and installing mysql-5.0.41-sol9-sparc-local and openssl-0.9.8e-sol9-sparc-local from sunfreeware.com first.

```shell
# gunzip <pkg>.gz; pkgadd -d <pkg> 
# gunzip libdbd8-mysql_<version>_<arch>.gz
# pkgadd -d libdbd8-mysql_<version>_<arch>.pkg
```

--------------------------------

### Install syslog-ng on RHEL with dnf

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Install syslog-ng on RHEL using dnf. The latest versions are available from the DNF repository, provided as-is without warranty.

```shell
dnf install syslog-ng
```

--------------------------------

### Native syntax example for a destination driver

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

Shows the desired native syslog-ng syntax for a destination driver, which is more readable and familiar to syslog-ng users.

```syslog-ng
destination whatever {
    my-destination(option1(value) option2(value));
};
```

--------------------------------

### Dummy Java destination implementation (TestClass.java)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/java/README.md

Extends TextLogDestination from syslog-ng-core.jar. Implements init(), deinit(), queue(), and flush() methods. The init() method prints 'START' and 'Initialize test destination', queue() prints 'This is queue!' plus the message, and flush() returns true.

```java
import org.syslog_ng.*;

public class TestClass extends TextLogDestination {

  public TestClass(long handle) {
    super(handle);
  }

  public boolean init()
  {
    System.out.println("START");
    System.out.println("Initialize test destination");
    return true;
  }

  public void deinit()
  {
    System.out.println("Deinitialize object");
  }

  public boolean queue(String message)
  {
    System.out.println("This is queue!" + message);
    return true;
  }

  public boolean flush()
  {
    return true;
  }
}
```

--------------------------------

### Example: Using elasticsearch-c in a log statement

Source: https://github.com/syslog-ng/syslog-ng/wiki/GSoC-2018-Proposal:-ElasticSearch-destination:-native(C)-REST-API-(definit3)

Complete syslog-ng configuration example that connects a file source to the new 'elasticsearch-c' destination. The destination uses 'cluster("syslog-ng")' and a template that formats the message as JSON with an @timestamp field.

```syslog-ng
source mysrc {
        file("/myfolder/examplesrc");
};

destination mydest {
elasticsearch-c(cluster("syslog-ng")
		template($(format-json --scope rfc5424 --exclude DATE --key ISODATE @timestamp=${ISODATE}))
);
};

log {
    source(mysrc);
    destination(mydest);
};
```

--------------------------------

### Quick start: run syslog-ng container

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-deb.md

Starts a detached syslog-ng container named 'syslog-ng', publishing UDP port 514, TCP ports 601 and 6514, using the latest tag.

```shell
docker run -d --name syslog-ng \
    -p 514:514/udp -p 601:601/tcp -p 6514:6514/tcp \
    balabit/syslog-ng:latest
```

--------------------------------

### Syslog priority calculation examples

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Python constants showing how to compute syslog priority values using the formula priority = facility * 8 + level. Each example includes a comment with the facility and level used.

```python
PRI_SYSLOG_ALERT = 41  # facility=5 (syslog) * 8 + level=1 (alert)
PRI_KERN_DEBUG = 7     # facility=0 (kern) * 8 + level=7 (debug)
PRI_DAEMON_ALERT = 25  # facility=3 (daemon) * 8 + level=1 (alert)
```

--------------------------------

### Install cross-compile dependencies and fix cpp symlink

Source: https://github.com/syslog-ng/syslog-ng/wiki/Cross-compile-syslog-ng

Installs the minimal dependencies for cross-compiling syslog-ng to arm64. The first command creates a symlink to fix a missing 'cpp' binary that the configure script cannot find; the second installs libglib2.0-dev and pkg-config for the arm64 architecture.

```bash
# this one fixes an issue within the container, "cpp" is unfortunately only
# available with a versioned binary, which the configure script does not find.
$ sudo ln -s /usr/bin/aarch64-linux-gnu-cpp-4.9
/usr/bin/aarch64-linux-gnu-cpp

# this is the minimal set of dependencies to compile syslog-ng, you might need
# others the bundled sources should however give you a pretty ok feature set
$ sudo apt-get install libglib2.0-dev:arm64 pkg-config:arm64
```

--------------------------------

### Missing Syslog Parser Before Facility/Level Filter (Wrong)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Incorrect example: facility filter won't match anything because the priority field is not parsed.

```python
config.create_logpath(statements=[
    source,
    config.create_filter("facility(syslog)"),  # Won't match anything!
    dest,
])
```

--------------------------------

### Multiple sources in logpath with Config API

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Example of creating a logpath with multiple sources, a parser, a filter, and a destination using the Config API.

```python
config.create_logpath(statements=[
    source1,
    source2,
    source3,
    parser,
    filter_obj,
    dest,
])
```

--------------------------------

### Compile syslog-ng from source

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Standard build command for compiling syslog-ng from source. Requires fetching and installing all build dependencies beforehand.

```bash
$ ./configure && make && make install
```

--------------------------------

### regexp-parser example with named pattern

Source: https://github.com/syslog-ng/syslog-ng/wiki/GSoC-2021-Proposal:-Add-regexp-parser()-(Xiaoyu-Qiu)

Example configuration that generates a name-value pair `.regexp.foo` when the message content is `foo ...`. Uses prefix `.regexp.` and pattern `(?<DN>foo)`.

```syslog-ng
parser { 
    regexp-parser(prefix(".regexp.") pattern("(?<DN>foo)") template("${MESSAGE}"));
};
```

--------------------------------

### Run syslog-ng with -Fedv

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/dbld/README.md

Run syslog-ng after a successful compilation and installation.

```bash
$ /install/syslog-ng/sbin/syslog-ng -Fedv
```

--------------------------------

### Python asyncio-based LogSource plugin example

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

This snippet shows a Python implementation of a syslog-ng LogSource plugin that uses asyncio to run two concurrent message sequences. It posts LogMessage instances at 1-second and 1.5-second intervals, and handles cancellation via the request_exit method. The run method starts the asyncio event loop, and the main method gathers the two sequences.

```python
from syslogng import LogSource
from syslogng import LogMessage
import asyncio

class MySource(LogSource):
    cancelled = False

    def run(self):
        asyncio.run(self.main())

    async def main(self):
        await asyncio.gather(self.sequence1(), self.sequence2())

    async def sequence1(self):
        while not self.cancelled:
            await asyncio.sleep(1)
            self.post_message(LogMessage("message1"))

    async def sequence2(self):
        while not self.cancelled:
            await asyncio.sleep(1.5)
            self.post_message(LogMessage("message2"))

    def request_exit(self):
        self.cancelled = True
```

--------------------------------

### Run syslog-ng with default configuration

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/README.md

Starts syslog-ng with the default configuration, exposing UDP port 514 and TCP port 601. Ensure these ports are not already in use on the host to avoid conflicts.

```bash
sudo docker run -it -p 514:514/udp -p 601:601 --name syslog-ng balabit/syslog-ng:latest
```

--------------------------------

### Example deb control entry for syslog-ng Python module

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

This is an example entry to add to packaging/debian/control for a custom Python module package. It defines the package name, architecture, dependencies, and description. The package depends on syslog-ng-core and syslog-ng-mod-python.

```plaintext
Package: syslog-ng-mod-<yourmodule>
Architecture: any
Multi-Arch: foreign
Depends: ${shlibs:Depends}, ${misc:Depends}, syslog-ng-core (>= ${source:Version}), syslog-ng-core (<< ${source:Version}.1~), syslog-ng-mod-python
Description: The short description of the package
 This is a longer description with dots separating paragraphs.
 .
 This package provides a collection of example plugins.
```

--------------------------------

### Test file source with wildcard-file

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Creates input files before starting syslog-ng, uses raw config for wildcard-file, and validates output. Includes a sleep to wait for processing.

```python
def test_file_source(config, syslog_ng):
    """Test wildcard file source."""

    # 1. Create files BEFORE starting syslog-ng
    os.makedirs("input", exist_ok=True)
    for i in range(3):
        with open(f"input/file{i}.log", 'a') as f:
            f.write("test message\n")

    # 2. Use raw config (wildcard-file has no Config API helper)
    raw_config = f"""
@version: {config.get_version()}
source s {{ wildcard-file(base-dir("input") filename-pattern("*.log")); }};
destination d {{ file("output.log"); }};
log {{ source(s); destination(d); }};
"""

    config.set_raw_config(raw_config)
    syslog_ng.start(config)

    # 3. Validate
    import time
    time.sleep(2)  # Wait for file processing
    assert os.path.exists("output.log")

```

--------------------------------

### Missing Syslog Parser Before Facility/Level Filter (Correct)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Correct example: adding create_syslog_parser() extracts facility/level from priority, enabling the filter to work.

```python
config.create_logpath(statements=[
    source,
    config.create_syslog_parser(),  # Extracts facility/level from priority
    config.create_filter("facility(syslog)"),
    dest,
])
```

--------------------------------

### Run syslog-ng with custom configuration

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-deb.md

Starts a syslog-ng container with a custom configuration file mounted read-only, and exposes the default ports (514/udp, 601/tcp, 6514/tcp).

```shell
docker run -d --name syslog-ng \
    -v /path/to/your/syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf:ro \
    -p 514:514/udp -p 601:601/tcp -p 6514:6514/tcp \
    balabit/syslog-ng:latest
```

--------------------------------

### Run syslog-ng container with custom configuration

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-rpm.md

Starts a syslog-ng container with a mounted custom configuration file. Requires --privileged, --cgroupns=host, and tmpfs mounts for systemd to work. The configuration file is mounted read-only at /etc/syslog-ng/syslog-ng.conf.

```shell
docker run -d --name syslog-ng-rpm \
    --privileged --cgroupns=host \
    --tmpfs /run --tmpfs /run/lock \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    -v /path/to/your/syslog-ng.conf:/etc/syslog-ng/syslog-ng.conf:ro \
    -p 514:514/udp -p 601:601/tcp -p 6514:6514/tcp \
    balabit/syslog-ng-rpm:latest
```

--------------------------------

### Example of self.flags dictionary

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

Example of the self.flags dictionary, which maps the state of the flags() option to a Dict[str, bool]. Shows the default values for each flag.

```python
{
    'parse': True,
    'check-hostname': False,
    'syslog-protocol': True,
    'assume-utf8': False,
    'validate-utf8': False,
    'sanitize-utf8': False,
    'multi-line': True,
    'store-legacy-msghdr': True,
    'store-raw-message': False,
    'expect-hostname': True,
    'guess-timezone': False,
    'header': True,
    'rfc3164-fallback': True,
}
```

--------------------------------

### Use crypto-parser in a log statement

Source: https://github.com/syslog-ng/syslog-ng/wiki/GSoC-2018-Proposal:-Crypto-Parser-(definit3)

Complete example connecting a source, a destination, and a crypto-parser in a log statement. The parser uses cipher(aes_256_cbc) and key("/myfolder/examplekey"); the key file must contain a secret key with the same number of bits as selected in the cipher option, otherwise an error message is displayed at startup.

```syslog-ng
source mysrc {
        file("/myfolder/examplesrc");
};

destination mydest {
    file("/myfolder/exampledest");
};

parser crypto_parser {
       crypto-parser(cipher(aes_256_cbc)
       				 key("/myfolder/examplekey"));
};

log {
    source(mysrc);
    parser(crypto_parser);
    destination(mydest);
};
```

--------------------------------

### Kafka destination with template() syntax in topic()

Source: https://github.com/syslog-ng/syslog-ng/wiki/GSoC2020-Idea-&-Project-list

Example syslog-ng configuration for the kafka() destination, demonstrating the use of template syntax in the topic() parameter to produce log messages on a per-host topic. The topic is set to 'syslog-ng.$HOST', and the key uses template expressions. This example is from the GSoC 2020 idea to add template() syntax support to the kafka() destination.

```syslog-ng
# this example causes syslog-ng to produce log messages on a per-host topic,
# called syslog-ng.<HOSTNAME>
destination d_kafka {
                kafka(config(
                             "queue.buffering.max.ms" => "1000",
                             "message.timeout.ms" => "5000",
                             "debug" => "all"
                      )
                      bootstrap-servers("localhost:9092")
                      flush-timeout-on-shutdown(1000)
                      topic("syslog-ng.$HOST")
                      key("${HOST}_${PROGRAM}_${PID}")
                      message("$(format-json --scope nv-pairs)"));

};
```

--------------------------------

### Missing freq=0 in example-msg-generator (Correct)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Correct example: setting freq=0 generates messages immediately, avoiding test timeouts.

```python
source = config.create_example_msg_generator_source(
    num=100,
    freq=0,  # Generate immediately
    template=config.stringify("message"),
)
```

--------------------------------

### Create a TLS network source with Config API

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Example of creating a network source with TLS transport using the Config API. Requires shared key and certificate files, and sets peer-verify to 'optional-untrusted'.

```python
source = config.create_network_source(
    transport="tls",
    tls={
        "key-file": copy_shared_file(testcase_parameters, "server.key"),
        "cert-file": copy_shared_file(testcase_parameters, "server.crt"),
        "peer-verify": '"optional-untrusted"',
    },
)
```

--------------------------------

### Missing freq=0 in example-msg-generator (Wrong)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Incorrect example: without freq=0, messages generate slowly over time, potentially causing test timeouts.

```python
source = config.create_example_msg_generator_source(
    num=100,
    template=config.stringify("message"),
)
# Test may timeout waiting for messages!
```

--------------------------------

### Structure: Focused test function

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Shows the recommended structure for a test function: setup, configure, execute, and validate, keeping the function under 20 lines.

```python
# Test description in comments (not docstring for compatibility)
#
def test_example(config, syslog_ng):
    """Brief docstring."""

    # 1. Setup (create test data if needed)
    expected = create_test_data()

    # 2. Configure
    config.create_logpath(statements=[source, dest])

    # 3. Execute
    syslog_ng.start(config)

    # 4. Validate
    validate_output(dest, expected)
```

--------------------------------

### Salt CLI command to generate syslog-ng source

Source: https://github.com/syslog-ng/syslog-ng/wiki/GSoC2014-Proposal:-Integration-with-configuration-management-systems-(ihrwein)

Example command for the Salt plugin that creates a new syslog-ng source with a file path and multi-line-mode option. The plugin builds an in-memory representation, serializes it to text, and validates it with syslog-ng --syntax-only before sending to machines.

```bash
$ salt '*' syslog-ng.new_source file=’/var/log/input.log’ multi-line-mode=indented
```

--------------------------------

### Filter syntax for single values

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Examples of creating filters with a single value for facility, level, and host.

```python
config.create_filter("facility(syslog)")
config.create_filter("level(debug)")
config.create_filter("host('server1')")
```

--------------------------------

### Command-line usage of autorel

Source: https://github.com/syslog-ng/syslog-ng/wiki/[GSoC'16]-Automated-release-generation-for-Syslog-ng

Example commands for the autorel tool: test the previously generated tarball with --test, and publish the release with --publish.

```bash
# Just test the previously generated tarball
$ autorel --test

# Woot! it works out fine, now publish the release
$ autorel --publish

```

--------------------------------

### SocketSender usage example (TCP and TLS)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/src/message_senders/README.md

Shows how to create SocketSender instances for TCP and TLS connections. The constructor takes an address family, address tuple, and options like dgram and ssl_enabled. The sendMessages method sends the message.

```python
from socket import AF_INET
from src.message_senders import SocketSender

# TCP connection
sender = SocketSender(AF_INET, ('localhost', 5514), dgram=0, repeat=100)
sender.sendMessages('test message')

# TLS connection
ssl_sender = SocketSender(
    AF_INET, ('localhost', 6514), 
    dgram=0, ssl_enabled=1, repeat=100
)
ssl_sender.sendMessages('secure message')
```

--------------------------------

### ConsecutiveAckTracker Usage

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

Example of initializing a ConsecutiveAckTracker in the init method of a LogFetcher, with a callback that receives the acknowledged message bookmark.

```APIDOC
## ConsecutiveAckTracker

### Description
Initializes a ConsecutiveAckTracker to track message acknowledgements in order. The callback is invoked when messages are acknowledged in the order they were generated.

### Usage
In the `init` method of a `LogFetcher` subclass, create a `ConsecutiveAckTracker` instance, passing the `ack_callback` parameter.

### Parameters
- **ack_callback** (callable) - Required - A function that takes a single argument (the acknowledged message bookmark).

### Example
```python
class MyFetcher(LogFetcher):
    def init(self, options):
        self.ack_tracker = ConsecutiveAckTracker(ack_callback=self.message_acked)
        return True

    def message_acked(self, acked_message_bookmark):
        pass
```
```

--------------------------------

### Get interactive shell in running container

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-deb.md

Starts an interactive bash shell inside the running syslog-ng container for inspection or debugging.

```shell
docker exec -it syslog-ng /bin/bash
```

--------------------------------

### BatchedAckTracker Usage

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/README.md

Example of initializing a BatchedAckTracker to track acknowledgements for individual messages, with batched callbacks after a timeout or batch size is reached.

```APIDOC
## BatchedAckTracker

### Description
Initializes a BatchedAckTracker to track acknowledgements for individual messages, accumulating them and calling the callback in batches after a timeout or when a batch size is reached.

### Usage
In the `init` method of a `LogFetcher` subclass, create a `BatchedAckTracker` instance, passing the `timeout`, `batch_size`, and `batched_ack_callback` parameters.

### Parameters
- **timeout** (int) - Required - Timeout in milliseconds for accumulating acknowledgements.
- **batch_size** (int) - Required - Number of outstanding messages to accumulate before triggering the callback.
- **batched_ack_callback** (callable) - Required - A function that takes a single argument (a list of acknowledged message bookmarks).

### Example
```python
class MyFetcher(LogFetcher):
    def init(self, options):
        self.ack_tracker = BatchedAckTracker(timeout=500, batch_size=100,
                                             batched_ack_callback=self.messages_acked)
        return True

    def messages_acked(self, acked_message_bookmarks):
        pass
```
```

--------------------------------

### Filter syntax for multiple values

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Examples of creating filters with multiple comma-separated values for facility and level.

```python
config.create_filter("facility(daemon,auth,lpr)")
config.create_filter("level(err,crit,alert)")
```

--------------------------------

### Run a single test file with pytest

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Command to run a single test file in the light test framework. Requires the build virtual environment and installation directory.

```bash
cd /path/to/syslog-ng/tests/light
/path/to/build/venv/bin/pytest -v \
    --installdir=/path/to/build/install \
    functional_tests/path/to/test_file.py
```

--------------------------------

### Configure example-diskq-source with file()

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/examples/sources/threaded-diskq-source/README.md

Configure the example-diskq-source driver to read from a disk-buffer file and forward messages to stdout. The source opens the file read-only, forwards its entire content, then polls for a new file at the specified path using time-reopen(). Removing or replacing the file is supported. Reloading or restarting syslog-ng resends all messages from the beginning. Intended for debugging only.

```syslog-ng
source s_diskq {
  example-diskq-source(file("/var/disk-buffers/syslog-ng-00000.rqf"));
};

log {
  source(s_diskq);

  destination {
    file("/dev/stdout");
  };
};
```

--------------------------------

### Run RPM image with privileged setup

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/README.md

Runs the RPM image with systemd as PID 1, using --privileged and cgroupns=host. This is usually sufficient on a plain Linux host with cgroup v2.

```bash
sudo docker run -d --privileged --cgroupns=host \
  --tmpfs /run --tmpfs /run/lock \
  -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
  -p 514:514/udp -p 601:601 -p 6514:6514 \
  --name syslog-ng balabit/syslog-ng-rpm:latest
```

--------------------------------

### Basic hypr-audit-trail() source configuration

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/python-modules/syslogng/modules/hypr/README.md

Minimal configuration for the hypr-audit-trail() source driver. Requires url() and bearer-token() options. Applications registered after syslog-ng starts are not recognized until restart.

```syslog-ng
    source s_hypr {
        hypr-audit-trail(
            url('https://<custom domain>.hypr.com')
            bearer-token('<base64 encoded bearer token>')
        );
    };
```

--------------------------------

### Filter syntax for range

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Example of creating a filter with a range for level, using the '..' operator to include all levels between the endpoints.

```python
config.create_filter("level(warning..crit)")  # warning, err, crit
```

--------------------------------

### Define light-check target

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/CMakeLists.txt

Runs pytest on the tests/light/functional_tests directory with the install directory specified, verbose output, and local variables shown. Depends on BuildPyVirtualEnv.

```cmake
add_custom_target(light-check
   COMMAND ${PYTHON_VENV_EXECUTABLE} -m pytest ${PROJECT_SOURCE_DIR}/tests/light/functional_tests --installdir=${CMAKE_INSTALL_PREFIX} --showlocals --verbosity=3 $$EXTRA_ARGS
   WORKING_DIRECTORY ${PROJECT_BINARY_DIR}
   DEPENDS BuildPyVirtualEnv)
```

--------------------------------

### Run syslog-ng RPM container on Docker Desktop (macOS / Windows)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-rpm.md

Starts the syslog-ng RPM container on Docker Desktop, requiring explicit tmpfs and cgroup mounts. Includes optional SYSTEMD_LOG_TARGET=console to route systemd boot messages to stdout.

```shell
docker run -d --name syslog-ng-rpm \
    --privileged --cgroupns=host \
    --tmpfs /run --tmpfs /run/lock \
    -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
    -e SYSTEMD_LOG_TARGET=console \
    -p 514:514/udp -p 601:601/tcp -p 6514:6514/tcp \
    balabit/syslog-ng-rpm:latest
```

--------------------------------

### Using read_log() Instead of read_logs(n) (Correct)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Correct example: read_logs(10) returns a list of 10 strings, allowing the assertion to pass.

```python
logs = dest.read_logs(10)  # Returns list of 10 strings
assert len(logs) == 10
```

--------------------------------

### HTTP destination configuration example

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/http/README.md

Complete syslog-ng configuration that sends logs to an HTTP server using PUT method with authentication, custom headers, and a body containing ISO date and message. The destination uses the http() driver with url, method, user_agent, user, password, headers, and body options.

```syslog-ng
@version: 3.28
@include "scl.conf"
source      s_system { system(); internal(); };
destination http_des {
    http(
        url("http://127.0.0.1:8000")
        method("PUT")
        user_agent("syslog-ng User Agent")
        user("user")
        password("password")
        headers("HEADER1: header1", "HEADER2: header2")
        body("${ISODATE} ${MSG}")
    );
};
log { source(s_system); destination(http_des); };
```

--------------------------------

### Resulting structured log output

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Example output message resulting from the structured log submission, showing the key=value format.

```text
name1=value1 name2=value2
```

--------------------------------

### Directory structure for functional tests

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Shows the directory layout under tests/light/functional_tests/, with subdirectories for each test category. Each feature gets its own subdirectory under the appropriate category.

```text
tests/light/functional_tests/
├── config_change/           # Config reload and change tests
├── destination_drivers/     # Destination-specific tests
│   ├── file_destination/
│   ├── network_destination/
│   ├── sql_destination/
│   └── unix_stream_destination/
├── filters/                 # Filter tests
├── logpath/                 # Logpath and flag tests
├── parsers/                 # Parser tests
│   ├── csv-parser/
│   ├── map-value-pairs/
│   └── regexp-parser/
├── performance/             # Performance/load tests
├── rewrites/                # Rewrite tests
├── source_drivers/          # Source-specific tests
│   ├── file_source/
│   ├── network_source/
│   └── syslog_source/
├── template_functions/      # Template function tests
└── templates/               # Template statement tests
```

--------------------------------

### Run dbld/rules help

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/dbld/README.md

General entrypoint for the dbld tool. Running without parameters has no side effect and lists available targets.

```bash
whoami@host:~/syslog-ng$ dbld/rules [help]
```

--------------------------------

### Mixing Config API with Raw Config (Wrong)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Incorrect example: mixing config API and raw config causes KeyError: 'processed' when accessing destination stats.

```python
dest = config.create_file_destination(file_name="output.log")
config.set_raw_config("source s { ... }; destination d { ... };")
dest.get_stats()  # KeyError: 'processed'
```

--------------------------------

### RHEL BuildRequires

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/packaging/README.md

Add a build dependency to the RHEL spec file packaging/rhel/syslog-ng.spec using a BuildRequires line. The example shows adding librdkafka-devel.

```plaintext
BuildRequires: librdkafka-devel

```

--------------------------------

### Run all light tests with make light-check

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Command to run the entire light test suite from the build directory.

```bash
cd /path/to/build
make light-check
```

--------------------------------

### Run syslog-ng RPM container on Linux host (cgroup v2)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-rpm.md

Starts the syslog-ng RPM container on a Linux host with cgroup v2. Requires --privileged and --cgroupns=host for systemd to work. Exposes UDP 514, TCP 601, and TCP 6514.

```shell
docker run -d --name syslog-ng-rpm \
    --privileged --cgroupns=host \
    -p 514:514/udp -p 601:601/tcp -p 6514:6514/tcp \
    balabit/syslog-ng-rpm:latest
```

--------------------------------

### FileSender usage example

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/src/message_senders/README.md

Creates a FileSender instance to send messages to a file or named pipe. The constructor takes a target path and optional repeat count. The sendMessages method sends the specified message.

```python
from src.message_senders import FileSender

sender = FileSender('log-pipe', repeat=100)
sender.sendMessages('test message')
```

--------------------------------

### Run app container with shared log volume

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/dockerhub-overview-deb.md

Starts a sibling container with a named volume for logs, which will be shared with the syslog-ng container via --volumes-from.

```shell
docker run -d --name app -v /var/log/app debian:trixie ...
```

--------------------------------

### Using read_log() Instead of read_logs(n) (Wrong)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Incorrect example: read_log() returns a single string, so asserting len(logs) == 10 fails.

```python
logs = dest.read_log()  # Returns single string
assert len(logs) == 10  # Will fail! logs is a string, not a list
```

--------------------------------

### Debian: Add Package stanza to debian/control

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/packaging/README.md

Add a new Package stanza to packaging/debian/control. Each line is an RFC822-like header; continuation lines start with whitespace, and an empty line is a dot on a continuation line. Adapt the description to your module.

```text
Package: syslog-ng-mod-slog
Architecture: any
Multi-Arch: foreign
Depends: ${shlibs:Depends}, ${misc:Depends}
Description: Enhanced system logging daemon (slog)
 syslog-ng is an enhanced log daemon, supporting a wide range of input
 and output methods: syslog, unstructured text, message queues,
 databases (SQL and NoSQL alike) and more.
 .
 Key features:
 .
  * receive and send RFC3164 and RFC5424 style syslog messages
  * work with any kind of unstructured data
  * receive and send JSON formatted messages
  * classify and structure logs with builtin parsers (csv-parser(),
    db-parser(), etc.)
  * normalize, crunch and process logs as they flow through the system
  * hand on messages for further processing using message queues (like
    AMQP), files or databases (like PostgreSQL or MongoDB).
 .
 This package provides the $(slog) template functions and command
 line utilities (slogencrypt, slogverify, slogkey).

```

--------------------------------

### Create example-msg-generator source

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

Use this to create a source that generates a fixed number of messages immediately. Set freq=0 to avoid delays. The template defines the message content.

```python
source = config.create_example_msg_generator_source(
    num=100,
    freq=0,  # CRITICAL: Generate immediately, not over time
    template=config.stringify("<41>Feb 11 10:00:00 host prog: test message"),
)

```

--------------------------------

### Run RPM image with minimal privileges

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/docker/README.md

Runs the RPM image with a less permissive setup: drops --privileged and adds only the SYS_ADMIN capability, keeping the cgroup and /run mounts.

```bash
sudo docker run -d \
  --cgroupns=host --cap-add SYS_ADMIN \
  --tmpfs /run --tmpfs /run/lock \
  -v /sys/fs/cgroup:/sys/fs/cgroup:rw \
  -p 514:514/udp -p 601:601 -p 6514:6514 \
  --name syslog-ng balabit/syslog-ng-rpm:latest
```

--------------------------------

### Incorrect mixing of Config API and Raw Config

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

This example shows the wrong approach of mixing Config API with raw config, which causes a KeyError: 'processed' when accessing destination stats. Use one or the other, never both.

```python

dest = config.create_file_destination(file_name="output.log")
config.set_raw_config("source s { ... };")  # BREAKS dest.get_stats()!

```

--------------------------------

### Add syslog-ng APT repository to sources

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/README.md

Add the syslog-ng APT repository to your sources. The first block shows the repository line format; the second writes it to /etc/apt/sources.list.d/syslog-ng-ose.list on newer OSes. Replace <os>-<codename>[-<architecture>] with your distribution (e.g., debian-trixie-arm64 for Debian 13 ARM64, debian-trixie for X86-64).

```shell
deb [signed-by=/etc/apt/keyrings/syslog-ng-ose.gpg] https://ose-repo.syslog-ng.com/apt/ stable <os>-<codename>[-<architecture>]
```

```shell
echo "deb [signed-by=/etc/apt/keyrings/syslog-ng-ose.gpg] https://ose-repo.syslog-ng.com/apt/ stable <os>-<codename>[-<architecture>]" | sudo tee /etc/apt/sources.list.d/syslog-ng-ose.list > /dev/null
```

--------------------------------

### Minimal Test Template

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/tests/light/TESTING_GUIDE.md

A complete runnable test that creates a message generator source, a file destination, and a logpath, then starts syslog-ng and asserts the output contains the expected message.

```python

#!/usr/bin/env python
#############################################################################
# Copyright (c) 2026 OneIdentity
#
# This program is free software; you can redistribute it and/or modify it
# under the terms of the GNU General Public License version 2 as published
# by the Free Software Foundation, or (at your option) any later version.
#############################################################################

# Test basic message generation and filtering.
#
def test_example(config, syslog_ng):
    """Test example message generation."""

    # 1. Create source (generates messages)
    source = config.create_example_msg_generator_source(
        num=10,
        freq=0,  # Generate immediately
        template=config.stringify("<41>Feb 11 10:00:00 host test: message"),
    )

    # 2. Create destination (writes to file)
    dest = config.create_file_destination(file_name="output.log")

    # 3. Create logpath (connect source to destination)
    config.create_logpath(statements=[source, dest])

    # 4. Start syslog-ng
    syslog_ng.start(config)

    # 5. Validate output
    assert "message" in dest.read_log()

```

--------------------------------

### Check syslog-ng service status with svcs

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/contrib/solaris-packaging/solaris10_install.txt

Run this command to verify that the syslog-ng service is installed and online. The expected output shows the service is online with the service identifier svc:/system/syslog-ng:default.

```shell
# svcs -a | grep syslog
```

```output
online 10:15:01 svc:/system/syslog-ng:default
```

--------------------------------

### Command line usage with --filter option

Source: https://github.com/syslog-ng/syslog-ng/wiki/GSoC-2015-Proposal:-syslog-ng-as-a-command-line-tool-(kvch)

Example command-line usages of the proposed --filter option to apply filters to the log path. The first filters for host "host1"; the second shows a potential OR-like syntax, though the exact semantics are not specified in the source.

```bash
$ syslog-ng --filter=host:"host1"
```

```bash
$ syslog-ng --filter=host:"host1ORhost:"host2"
```

--------------------------------

### Build syslog-ng for aarch64 with configure and make

Source: https://github.com/syslog-ng/syslog-ng/wiki/Cross-compile-syslog-ng

Builds syslog-ng for aarch64 by creating a build directory, running the configure script with --host aarch64-linux-gnu, and then running make. The configure output is long and omitted.

```bash
$ mkdir build
$ cd build
$ /work/configure --host aarch64-linux-gnu
# <long configure output>
$ make
```

--------------------------------

### syslog-ng configuration for Java destination (jar file)

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/modules/java/README.md

Configures a Java destination using a jar file in class_path. The example shows an elasticsearch2 destination with client-lib-dir, index, type, time-zone, client-mode, and cluster-url options. Includes internal and TCP sources.

```syslog-ng
@version: 3.28

options {
  threaded(yes);
};

source s_local {
        internal();
};

source s_network {
        tcp(port(5555));
};

destination d_elastic {
  elasticsearch2(
    client-lib-dir("/usr/share/elasticsearch/lib/")
    index("syslog-${YEAR}.${MONTH}.${DAY}")
    type("syslog")
    time-zone("UTC")
    client-mode("http")
    cluster-url("http://node01:9200 http://node02:9200")
  );
};

log {
  source(s_network);
  destination(d_elastic);
  flags(flow-control);
};
```

--------------------------------

### Prepare release with VERSION

Source: https://github.com/syslog-ng/syslog-ng/blob/develop/dbld/README.md

Automates version bumps for a release. Does not commit changes; leaves them for review.

```bash
$ ./dbld/rules prepare-release VERSION=3.28.1
```

--------------------------------

### Release flow sequence

Source: https://github.com/syslog-ng/syslog-ng/wiki/[GSoC'16]-Automated-release-generation-for-Syslog-ng

Shows the high-level sequence of the release process: prepare_release, then test_release, then publish_release.

```text
                    prepare_release => test_release => publish_release

```