4.8.0

We have new documentation

You can find our new up-to-date documentation in the new Administration Guide at syslog-ng.github.io.

Highlights

Default config version in configuration files

cfg: allow usage of current in config @version by default if it is not presented

This change allows syslog-ng to start even if the @version information is not present in the configuration file and treats the version as the latest in that case.

NOTE: syslog-ng will still raise a warning if @version is not present. Please use @version: current to confirm the intention of always using the latest version and silence the warning. (#5030)

BSD directory monitoring with kqueue

directory-monitor: Added a kqueue based directory monitor implementation.

wildcard-file() sources are using a directory monitor as well to aid detection of changes in the folders of the followed files. The new kqueue-based directory monitor uses far fewer resources than the poll based version on BSD-based systems.
(#5022)

See more at the new syslog-ng documentation.

Wildcard file source fine-tuning

wildcard-file(): Added a dedicated monitor_freq option to control the poll frequency of the change detection in the directories separately when the poll method is selected via the monitor-method() option.

The monitor-method() option controls only the change detection method in the directories, not the following of the file changes, and if poll is the selected method the frequency must not necessarily be the same, e.g. if the (earlier) commonly used follow-freq() is set to 0 for switching to the poll_fd_events method for file content change detection, that also might be meant a directory change poll with zero delays (if monitor-method() was set to poll as well), and that could cause a heavy CPU load unnecessarily.
(#4998)

See more at the new syslog-ng documentation.

Features

• s3(): Introduced server side encryption related options

  server-side-encryption() and kms-key() can be used to configure encryption.

  Currently only server-side-encryption("aws:kms") is supported.
  The kms-key() should be:

  • an ID of a key
  • an alias of a key, but in that case you have to add the alias/prefix
  • an ARN of a key

  To be able to use the aws:kms encryption the AWS Role or User has to have the following
  permissions on the given key:

  • kms:Decrypt
  • kms:Encrypt
  • kms:GenerateDataKey

  Check this page on why the kms:Decrypt is mandatory.

  Example config:

  destination d_s3 {
    s3(
      bucket("log-archive-bucket")
      object-key("logs/syslog")
      server-side-encryption("aws:kms")
      kms-key("alias/log-archive")
    );
  };
  

  See the S3 documentation for more details.
  (#4993)

• filter: Added numerical severity settings.

  The level filter option now accepts numerical values similar to facility.

  Example config:

  filter f_severity {
    level(4)
  };
  

  This is equivalent to

  filter f_severity {
    level("warning")
  };
  

  For more information, consult the documentation.
  (#5016)

• opentelemetry(), loki(), bigquery(): Added headers() option

  Enables adding headers to RPC calls.

  Example config:

  opentelemetry(
    ...
    headers(
      "my_header" = "my_value"
    )
  );
  

  (#5012)

• Added new proxy options to the syslog() and network() source drivers

  The transport(proxied-tcp), transport(proxied-tls), and transport(proxied-tls-passthrough) options are now available when configuring syslog() and network() sources.
  (#4544)

Bugfixes

• disk-buffer(): fix crash when pipeline initialization fails

  log_queue_disk_free_method: assertion failed: (!qdisk_started(self->qdisk))
  (#4994)

• rate-limit(): Fixed a crash which occured on a config parse failure.
  (#5033)

• Fixed potential null pointer deref issues
  (#5035)

• wildcard-file(): fix a crash and detection of file delete/move when using ivykis poll events

  Two issues were fixed

  • Fixed a crash in log pipe queue during file deletion and EOF detection (#4989)

    The crash was caused by a concurrency issue in the EOF and file deletion detection when using a wildcard-file() source.

    If a file is written after being deleted (e.g. with an application keeping the file open), or if these events happen concurrently, the file state change poller mechanism might schedule another read cycle even though the file has already been marked as fully read and deleted.

    To prevent this re-scheduling between these two checks, the following changes have been made:
    Instead of maintaining an internal EOF state in the WildcardFileReader, when a file deletion notification is received, the poller will be signaled to stop after reaching the next EOF. Only after both conditions are set the reader instance will be deleted.

  • Fixed the file deletion and removal detection when the file-reader uses poll_fd_events to follow file changes, which were mishandled. For example, files that were moved or deleted (such as those rolled by a log-rotator) were read to the end but never read again if they were not touched anymore, therefore switching to the new file never happened.
    (#4998)

• syslog-ng-ctl query: fix showing Prometheus metrics as unnamed values

  none.value=726685
  (#4995)

• macros: Fixed a bug which always set certain macros to string type

  The affected macros are $PROGRAM, $HOST and $MESSAGE.
  (#5024)

• syslog-ng-ctl query: show timestamps and fix g_pattern_spec_match_string assert
  (#4995)

• csv-parser(): fix escape-backslash-with-sequences dialect on ARM

  csv-parser() produced invalid output on platforms where char is an unsigned type.
  (#4947)

Other changes

• bigquery(), loki(), opentelemetry(), cloud-auth(): C++ modules can be compiled with clang

  Compiling and using these C++ modules are now easier on FreeBSD and macOS.
  (#4933)

• syslog-ng-ctl: do not show orphan metrics for stats prometheus

  As the stats prometheus command is intended to be used to forward metrics
  to Prometheus or any other time-series database, displaying orphaned metrics
  should be avoided in order not to insert new data points when a given metric
  is no longer alive.

  In case you are interested in the last known value of orphaned counters, use
  the stats or query subcommands.
  (#4921)

• s3(): new metric syslogng_output_event_bytes_total
  (#4958)

• multiline-options: Allow multi_line_timeout to be set to a non-integer value.

  Since multi_line_timeout is suggested to be set as a multiple of follow-freq, and follow-freq can be much smaller than one second, it makes sense to allow this value to be a non-integer as well.
  (#5002)

• packages/dbld: add support for Ubuntu 24.04 (Noble Numbat)
  (#4925)

• packages/dbld: add support for AlmaLinux 9
  (#5009)

• packages/dbld: added support for Fedora Rawhide and CentOS Stream 9 as testing platforms
  (#5009)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Alex Becker, Andras Mitzki, Arpad Kunszt, Attila Szakacs,
Balazs Scheidler, Bálint Horváth, Dmitry Levin, Hofi, Ilya Kheifets,
joohoonmaeng, ktzsolt, László Várady, Mate Ory, Natanael Copa,
Peter Czanik, qsunchiu, Robert Fekete, shifter, Szilárd Parrag,
Tamas Pal, Wolfram Joost

4.7.1

This is the combination of the news entries of 4.7.0 and 4.7.1.
4.7.1 hotfixed two crashes related to configuration reload.

Read Axoflow's blog post for more details.
You can read more about the new features in the AxoSyslog documentation.

Highlights

Collecting Jellyfin logs

The new jellyfin() source, reads Jellyfin logs from its log file output.

Example minimal config:

source s_jellyfin {
  jellyfin(
    base-dir("/path/to/my/jellyfin/root/log/dir")
    filename-pattern("log_*.log")
  );
};

For more details about Jellyfin logging, see:

• https://jellyfin.org/docs/general/administration/configuration/#main-configuration
• https://jellyfin.org/docs/general/administration/configuration/#log-directory

As the jellyfin() source is based on a wildcard-file() source, all of the
wildcard-file() source options are applicable, too.
(#4802)

Collecting *arr logs

Use the newly added *arr() sources to read various *arr logs:

• lidarr()
• prowlarr()
• radarr()
• readarr()
• sonarr()
• whisparr()

Example minimal config:

source s_radarr {
  radarr(
    dir("/path/to/my/radarr/log/dir")
  );
};

The logging module is stored in the <prefix><module> name-value pair,
for example: .radarr.module => ImportListSyncService.
The prefix can be modified with the prefix() option.
(#4803)

Features

• opentelemetry(), syslog-ng-otlp() source: Added concurrent-requests() option.

  This option configures the maximal number of in-flight gRPC requests per worker.
  Setting this value to the range of 10s or 100s is recommended when there are a
  high number of clients sending simultaneously.

  Ideally, workers() * concurrent-requests() should be greater or equal to
  the number of clients, but this can increase the memory usage.
  (#4827)

• loki(): Support multi-tenancy with the new tenant-id() option
  (#4812)

• s3(): Added support for authentication from environment.

  The access-key() and secret-key() options are now optional,
  which makes it possible to use authentication methods originated
  from the environment, e.g. AWS_... environment variables or
  credentials files from the ~/.aws/ directory.

  For more info, see:
  https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
  (#4881)

• gRPC based drivers: Added channel-args() option.

  Affected drivers are:

  • bigquery() destination
  • loki() destination
  • opentelemetry() source and destination
  • syslog-ng-otlp() source and destination

  The channel-args() option accepts name-value pairs and sets channel arguments
  defined in https://grpc.github.io/grpc/core/group__grpc__arg__keys.html

  Example config:

    opentelemetry(
      channel-args(
        "grpc.loadreporting" => 1
        "grpc.minimal_stack" => 0
      )
    );
  

  (#4827)

• ${TRANSPORT} macro: Added support for locally created logs.

  New values are:

  • "local+unix-stream"
  • "local+unix-dgram"
  • "local+file"
  • "local+pipe"
  • "local+program"
  • "local+devkmsg"
  • "local+journal"
  • "local+afstreams"
  • "local+openbsd"
    (#4777)

• tags: Added new built-in tags that help identifying parse errors.

  New tags are:

  • "message.utf8_sanitized"
  • "message.parse_error"
  • "syslog.missing_pri"
  • "syslog.missing_timestamp"
  • "syslog.invalid_hostname"
  • "syslog.unexpected_framing"
  • "syslog.rfc3164_missing_header"
  • "syslog.rfc5424_unquoted_sdata_value"
    (#4804)

• mqtt() source: Added ${MQTT_TOPIC} name-value pair.

  It is useful for the cases where topic() contains wildcards.

  Example config:

  log {
    source { mqtt(topic("#")); };
    destination { stdout(template("${MQTT_TOPIC} - ${MESSAGE}\n")); };
  };
  

  (#4824)

• template(): Added a new template function: $(tags-head)

  This template function accepts multiple tag names, and returns the
  first one that is set.

  Example config:

  # resolves to "bar" if "bar" tag is set, but "foo" is not
  template("$(tags-head foo bar baz)")
  

  (#4804)

• s3(): Use default AWS URL if url() is not set.
  (#4813)

• opentelemetry(), syslog-ng-otlp() source: Added log-fetch-limit() option.

  This option can be used to fine tune the performance. To minimize locking while
  moving messages between source and destination side queues, syslog-ng can move
  messages in batches. The log-fetch-limit() option sets the maximal size of
  the batch moved by a worker. By default it is equal to log-iw-size() / workers().
  (#4827)

• dqtool: add option for truncating (compacting) abandoned disk-buffers
  (#4875)

Bugfixes

• opentelemetry(): fix crash when an invalid configuration needs to be reverted
  (#4910)

• gRPC drivers: fixed a crash when gRPC drivers were used and syslog-ng was reloaded
  (#4909)

• opentelemetry(), syslog-ng-otlp() source: Fixed a crash.

  It occurred with multiple workers() during high load.
  (#4827)

• rename(): Fixed a bug, which always converted the renamed NV pair to string type.
  (#4847)

• With IPv6 disabled, there were linking errors
  (#4880)

Metrics

• http(): Added a new counter for HTTP requests.

  It is activated on stats(level(1));.

  Example metrics:

  syslogng_output_http_requests_total{url="http://localhost:8888/bar",response_code="200",driver="http",id="#anon-destination0#0"} 16
  syslogng_output_http_requests_total{url="http://localhost:8888/bar",response_code="401",driver="http",id="#anon-destination0#0"} 2
  syslogng_output_http_requests_total{url="http://localhost:8888/bar",response_code="502",driver="http",id="#anon-destination0#0"} 1
  syslogng_output_http_requests_total{url="http://localhost:8888/foo",response_code="200",driver="http",id="#anon-destination0#0"} 24
  

  (#4805)

• gRPC based destination drivers: Added gRPC request related metrics.

  Affected drivers:

  • opentelemetry()
  • syslog-ng-otlp()
  • bigquery()
  • loki()

  Example metrics:

  syslogng_output_grpc_requests_total{driver="syslog-ng-otlp",url="localhost:12345",response_code="ok"} 49
  syslogng_output_grpc_requests_total{driver="syslog-ng-otlp",url="localhost:12345",response_code="unavailable"} 11
  

  (#4811)

• New metric to monitor destination reachability

  syslogng_output_unreachable is a bool-like metric, which shows whether a
  destination is reachable or not.

  sum() can be used to count all unreachable outputs, hence the negated name.

  It is currently available for the network(), syslog(), unix-*()
  destinations, and threaded destinations (http(), opentelemetry(), redis(),
  mongodb(), python(), etc.).
  (#4876)

• destinations: Added "syslogng_output_event_retries_total" counter.

  This counter is available for the following destination drivers:

  • amqp()
  • bigquery()
  • http() and all http based drivers
  • java()
  • kafka()
  • loki()
  • mongodb()
  • mqtt()
  • opentelemetry()
  • python() and all python based drivers
  • redis()
  • riemann()
  • smtp()
  • snmp()
  • sql()
  • stomp()
  • syslog-ng-otlp()

  Example metrics:

  syslogng_output_event_retries_total{driver="http",url="http://localhost:8888/${path}",id="#anon-destination0#0"} 5
  

  (#4807)

• syslogng_memory_queue_capacity

  Shows the capacity (maximum possible size) of each queue.
  Note that this metric publishes log-fifo-size(), which only limits non-flow-controlled messages.
  Messages coming from flow-controlled paths are not limited by log-fifo-size(), their corresponding
  source log-iw-size() is the upper limit.
  (#4831)

Other changes

• opentelemetry(), syslog-ng-otlp() source: Changed the backpressure behavior.

  syslog-ng no longer returns UNAVAILABLE to the gRPC request, when it cannot forward
  the received message because of backpressure. Instead, syslog-ng will block until the
  destination can accept more messages.
  (#4827)

• opentelemetry(), syslog-ng-otlp() source: log-iw-size() is now split between workers.
  (#4827)

• APT packages: Dropped Debian Buster support.

  Old packages are still available, but new syslog-ng versions will not
  be available on Debian Buster
  (#4840)

• dbld: AlmaLinux 8 support
  (#4902)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Arpad Kunszt, Attila Szakacs, Balazs Scheidler, Bálint Horváth, Hofi,
Kovács, Gergő Ferenc, László Várady, Peter Marko, shifter

4.7.0

Read Axoflow's blog post for more details.
You can read more about the new features in the AxoSyslog documentation.

Highlights

Collecting Jellyfin logs

The new jellyfin() source, reads Jellyfin logs from its log file output.

Example minimal config:

source s_jellyfin {
  jellyfin(
    base-dir("/path/to/my/jellyfin/root/log/dir")
    filename-pattern("log_*.log")
  );
};

For more details about Jellyfin logging, see:

• https://jellyfin.org/docs/general/administration/configuration/#main-configuration
• https://jellyfin.org/docs/general/administration/configuration/#log-directory

As the jellyfin() source is based on a wildcard-file() source, all of the
wildcard-file() source options are applicable, too.
(#4802)

Collecting *arr logs

Use the newly added *arr() sources to read various *arr logs:

• lidarr()
• prowlarr()
• radarr()
• readarr()
• sonarr()
• whisparr()

Example minimal config:

source s_radarr {
  radarr(
    dir("/path/to/my/radarr/log/dir")
  );
};

The logging module is stored in the <prefix><module> name-value pair,
for example: .radarr.module => ImportListSyncService.
The prefix can be modified with the prefix() option.
(#4803)

Features

• opentelemetry(), syslog-ng-otlp() source: Added concurrent-requests() option.

  This option configures the maximal number of in-flight gRPC requests per worker.
  Setting this value to the range of 10s or 100s is recommended when there are a
  high number of clients sending simultaneously.

  Ideally, workers() * concurrent-requests() should be greater or equal to
  the number of clients, but this can increase the memory usage.
  (#4827)

• loki(): Support multi-tenancy with the new tenant-id() option
  (#4812)

• s3(): Added support for authentication from environment.

  The access-key() and secret-key() options are now optional,
  which makes it possible to use authentication methods originated
  from the environment, e.g. AWS_... environment variables or
  credentials files from the ~/.aws/ directory.

  For more info, see:
  https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html
  (#4881)

• gRPC based drivers: Added channel-args() option.

  Affected drivers are:

  • bigquery() destination
  • loki() destination
  • opentelemetry() source and destination
  • syslog-ng-otlp() source and destination

  The channel-args() option accepts name-value pairs and sets channel arguments
  defined in https://grpc.github.io/grpc/core/group__grpc__arg__keys.html

  Example config:

    opentelemetry(
      channel-args(
        "grpc.loadreporting" => 1
        "grpc.minimal_stack" => 0
      )
    );
  

  (#4827)

• ${TRANSPORT} macro: Added support for locally created logs.

  New values are:

  • "local+unix-stream"
  • "local+unix-dgram"
  • "local+file"
  • "local+pipe"
  • "local+program"
  • "local+devkmsg"
  • "local+journal"
  • "local+afstreams"
  • "local+openbsd"
    (#4777)

• tags: Added new built-in tags that help identifying parse errors.

  New tags are:

  • "message.utf8_sanitized"
  • "message.parse_error"
  • "syslog.missing_pri"
  • "syslog.missing_timestamp"
  • "syslog.invalid_hostname"
  • "syslog.unexpected_framing"
  • "syslog.rfc3164_missing_header"
  • "syslog.rfc5424_unquoted_sdata_value"
    (#4804)

• mqtt() source: Added ${MQTT_TOPIC} name-value pair.

  It is useful for the cases where topic() contains wildcards.

  Example config:

  log {
    source { mqtt(topic("#")); };
    destination { stdout(template("${MQTT_TOPIC} - ${MESSAGE}\n")); };
  };
  

  (#4824)

• template(): Added a new template function: $(tags-head)

  This template function accepts multiple tag names, and returns the
  first one that is set.

  Example config:

  # resolves to "bar" if "bar" tag is set, but "foo" is not
  template("$(tags-head foo bar baz)")
  

  (#4804)

• s3(): Use default AWS URL if url() is not set.
  (#4813)

• opentelemetry(), syslog-ng-otlp() source: Added log-fetch-limit() option.

  This option can be used to fine tune the performance. To minimize locking while
  moving messages between source and destination side queues, syslog-ng can move
  messages in batches. The log-fetch-limit() option sets the maximal size of
  the batch moved by a worker. By default it is equal to log-iw-size() / workers().
  (#4827)

• dqtool: add option for truncating (compacting) abandoned disk-buffers
  (#4875)

Bugfixes

• opentelemetry(), syslog-ng-otlp() source: Fixed a crash.

  It occurred with multiple workers() during high load.
  (#4827)

• rename(): Fixed a bug, which always converted the renamed NV pair to string type.
  (#4847)

• With IPv6 disabled, there were linking errors
  (#4880)

Metrics

• http(): Added a new counter for HTTP requests.

  It is activated on stats(level(1));.

  Example metrics:

  syslogng_output_http_requests_total{url="http://localhost:8888/bar",response_code="200",driver="http",id="#anon-destination0#0"} 16
  syslogng_output_http_requests_total{url="http://localhost:8888/bar",response_code="401",driver="http",id="#anon-destination0#0"} 2
  syslogng_output_http_requests_total{url="http://localhost:8888/bar",response_code="502",driver="http",id="#anon-destination0#0"} 1
  syslogng_output_http_requests_total{url="http://localhost:8888/foo",response_code="200",driver="http",id="#anon-destination0#0"} 24
  

  (#4805)

• gRPC based destination drivers: Added gRPC request related metrics.

  Affected drivers:

  • opentelemetry()
  • syslog-ng-otlp()
  • bigquery()
  • loki()

  Example metrics:

  syslogng_output_grpc_requests_total{driver="syslog-ng-otlp",url="localhost:12345",response_code="ok"} 49
  syslogng_output_grpc_requests_total{driver="syslog-ng-otlp",url="localhost:12345",response_code="unavailable"} 11
  

  (#4811)

• New metric to monitor destination reachability

  syslogng_output_unreachable is a bool-like metric, which shows whether a
  destination is reachable or not.

  sum() can be used to count all unreachable outputs, hence the negated name.

  It is currently available for the network(), syslog(), unix-*()
  destinations, and threaded destinations (http(), opentelemetry(), redis(),
  mongodb(), python(), etc.).
  (#4876)

• destinations: Added "syslogng_output_event_retries_total" counter.

  This counter is available for the following destination drivers:

  • amqp()
  • bigquery()
  • http() and all http based drivers
  • java()
  • kafka()
  • loki()
  • mongodb()
  • mqtt()
  • opentelemetry()
  • python() and all python based drivers
  • redis()
  • riemann()
  • smtp()
  • snmp()
  • sql()
  • stomp()
  • syslog-ng-otlp()

  Example metrics:

  syslogng_output_event_retries_total{driver="http",url="http://localhost:8888/${path}",id="#anon-destination0#0"} 5
  

  (#4807)

• syslogng_memory_queue_capacity

  Shows the capacity (maximum possible size) of each queue.
  Note that this metric publishes log-fifo-size(), which only limits non-flow-controlled messages.
  Messages coming from flow-controlled paths are not limited by log-fifo-size(), their corresponding
  source log-iw-size() is the upper limit.
  (#4831)

Other changes

• opentelemetry(), syslog-ng-otlp() source: Changed the backpressure behavior.

  syslog-ng no longer returns UNAVAILABLE to the gRPC request, when it cannot forward
  the received message because of backpressure. Instead, syslog-ng will block until the
  destination can accept more messages.
  (#4827)

• opentelemetry(), syslog-ng-otlp() source: log-iw-size() is now split between workers.
  (#4827)

• APT packages: Dropped Debian Buster support.

  Old packages are still available, but new syslog-ng versions will not
  be available on Debian Buster
  (#4840)

• dbld: AlmaLinux 8 support
  (#4902)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Arpad Kunszt, Attila Szakacs, Balazs Scheidler, Bálint Horváth, Hofi,
Kovács, Gergő Ferenc, László Várady, Peter Marko, shifter

4.6.0

Read Axoflow's blog post for more details.
You can read more about the new features in the AxoSyslog documentation.

Highlights

Forwarding logs to Google BigQuery

The bigquery() destination inserts logs to a Google BigQuery table via the
high-performance gRPC API.

Authentication is done via Application Default Credentials.

You can locate your BigQuery table with the project() dataset() and table()
options.

There are two ways to configure your table's schema.

• You can set the columns and their respective type and template with the
  schema() option. The available types are: STRING, BYTES, INTEGER,
  FLOAT, BOOLEAN, TIMESTAMP, DATE, TIME, DATETIME, JSON,
  NUMERIC, BIGNUMERIC, GEOGRAPHY, RECORD, INTERVAL.
• Alternatively you can import a .proto file with the protobuf-schema() option,
  and map the templates for each column.

The performance can be further improved with the workers(), batch-lines(),
batch-bytes(), batch-timeout() and compression() options. By default the
messages are sent with one worker, one message per batch and without compression.

Keepalive can be configured with the keep-alive() block and its time(),
timeout() and max-pings-without-data() options.

Example config:

bigquery(
    project("test-project")
    dataset("test-dataset")
    table("test-table")
    workers(8)

    schema(
        "message" => "$MESSAGE"
        "app" STRING => "$PROGRAM"
        "host" STRING => "$HOST"
        "pid" INTEGER => int("$PID")
    )

    on-error("drop-property")

    # or alternatively instead of schema():
    # protobuf-schema("/tmp/test.proto"
    #                 => "$MESSAGE", "$PROGRAM", "$HOST", "$PID")

    # keep-alive(time(20000) timeout(10000) max-pings-without-data(0))
);

Example .proto schema:

syntax = "proto2";
​
message CustomRecord {
  optional string message = 1;
  optional string app = 2;
  optional string host = 3;
  optional int64 pid = 4;
}

(#4733)
(#4770)
(#4756)

Collecting native macOS system logs

Two new sources have been added on macOS: darwin-oslog(), darwin-oslog-stream().
darwin-oslog() replaced the earlier file source based solution with a native OSLog
framework based one, and is automatically used in the system() source on darwin
platform if the darwinosl plugin is presented.

This plugin is available only on macOS 10.15 Catalina and above, the first version
that has the OSLog API.

darwin-oslog()

This is a native OSLog Framework based source to read logs from the local store of
the unified logging system on darwin OSes.
For more info, see https://developer.apple.com/documentation/oslog?language=objc

The following parameters can be used for customization:

• filter-predicate()
  • string value, which can be used to filter the log messages natively
  • default value: (eventType == 'logEvent' || eventType == 'lossEvent' || eventType == 'stateEvent' || eventType == 'userActionEvent') && (logType != 'debug')
  • for more details, see
    • man log
    • https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/Predicates/Articles/pSyntax.html
• go-reverse()
  • boolean value, setting to yes will provide a reverse-ordered log list
    (from latest to oldest)
  • default value: no
• do-not-use-bookmark()
  • boolean value, setting to yes will prevent syslog-ng from continuing to
    feed the logs from the last remembered position after a (re-)start, which means,
    depending on the other settings, the feed will always start from the end/beginning
    of the available log list
  • default value: no, which means syslog-ng will attempt to continue feeding from
    the last remembered log position after a (re-)start
• max-bookmark-distance()
  • integer value, maximum distance in seconds that far an earlier bookmark can point
    backward, e.g. if syslog-ng was stopped for 10 minutes and max-bookmark-distance
    is set to 60 then syslog-ng will start feeding the logs only from the last 60
    seconds at startup, 9 minutes of logs 'will be lost'
  • default value: 0, which means no limit
• read-old-records()
  • boolean value, controls if syslog-ng should start reading logs from the oldest
    available at first start (or if no bookmark can be found)
  • default value: no
• fetch-delay()
  • integer value, controls how much time syslog-ng should wait between reading/sending
    log messages, this is a fraction of a second, where wait_time = 1 second / n, so,
    e.g. n=1 means that only about 1 log will be read and sent in each second,
    and n=1 000 000 means only 1 microsecond (the allowed minimum value now!)
    will be the delay between read/write attempts
  • Use with care, though lower delay time can increase log feed performance, at the
    same time could lead to a heavy system load!
  • default value: 10 000
• fetch-retry-delay()
  • integer value, controls how many seconds syslog-ng will wait before a repeated
    attempt to read/send once it's out of available logs
  • default value: 1
• log-fetch-limit()
  • Warning: This option is now disabled due to an OSLog API bug
    (https://openradar.appspot.com/radar?id=5597032077066240), once it's fixed it
    will be enabled again
  • integer value, that limits the number of logs syslog-ng will send in one run
  • default value: 0, which means no limit

NOTE: the persistent OSLog store is not infinite, depending on your system setting usually,
it keeps about 7 days of logs on disk, so it could happen that the above options cannot
operate the way you expect, e.g. if syslog-ng was stopped for about more then a week it
could happen that will not be able to restart from the last saved bookmark position
(as that might not be presented in the persistent log anymore)

darwin-oslog-stream()

This is a wrapper around the OS command line "log stream" command that can provide a live
log stream feed. Unlike in the case of darwin-oslog() the live stream can contain
non-persistent log events too, so take care, there might be a huge number of log events
every second that could put an unusual load on the device running syslog-ng with this source.
Unfortunately, there's no public API to get the same programmatically, so this one is
implemented using a program() source.

Possible parameters:

• params()
  • a string that can contain all the possible params the macOS log tool can accept
  • see log --help stream for full reference, and man log for more details
  • IMPORTANT: the parameter --style is used internally (defaults to ndjson), so it
    cannot be overridden, please use other sysylog-ng features (templates, rewrite rules, etc.)
    for final output formatting
  • default value: --type log --type trace --level info --level debug,
    you can use `def-osl-stream-params` for referencing it if you wish to keep the
    defaults when you add your own

(#4423)

Collecting qBittorrent logs

The new qbittorrent() source, reads qBittorrent logs from its log file output.

Example minimal config:

source s_qbittorrent {
  qbittorrent(
    dir("/path/to/my/qbittorrent/root/log/dir")
  );
};

The root dir of the qBittorrent logs can be found in the
"Tools" / "Preferences" / "Behavior" / "Log file" / "Save path" field.

As the qbittorrent() source is based on a file() source, all of the file()
source options are applicable, too.

(#4760)

Collecting pihole FTL logs

The new pihole-ftl() source reads pihole FTL (Faster Than Light) logs, which
are usually accessible in the "Tools" / "Pi-hole diagnosis" menu.

Example minimal config:

source s_pihole_ftl {
  pihole-ftl();
};

By default it reads the /var/log/pihole/FTL.log file.
You can change the root dir of Pi-hole's logs with the dir() option,
where the FTL.log file can be found.

As the pihole-ftl() source is based on a file() source, all of the
file() source options are applicable, too.

(#4760)

Parsing Windows Eventlog XMLs

The new windows-eventlog-xml-parser() introduces parsing support for Windows Eventlog XMLs.

Its parameters are the same as the xml() parser.

Example config:

parser p_win {
    windows-eventlog-xml-parser(prefix(".winlog."));
};

(#4793)

Features

• cloud-auth(): Added support for user-managed-service-account() gcp() auth method.

  This authentication method can be used on VMs in GCP to use the linked service.

  Example minimal config, which tries to use the "default" service account:

  cloud-auth(
    gcp(
      user-managed-service-account()
    )
  )
  

  Full config:

  cloud-auth(
    gcp(
      user-managed-service-account(
        name("[email protected]")
        metadata-url("my-custom-metadata-server:8080")
      )
    )
  )
  

  This authentication method is extremely useful with syslog-ng's google-pubsub() destination,
  when it is running on VMs in GCP, for example:

  destination {
    google-pubsub(
      project("syslog-ng-test-project")
      topic("syslog-ng-test-topic")
      auth(user-managed-service-account())
    );
  };
  

  For more info about this GCP authentication method, see:

  • https://cloud.google.com/compute/docs/access/authenticate-workloads#curl
  • https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances
    (#4755)

• opentelemetry(), syslog-ng-otlp() sources: Added workers() option.

  This feature enables processing the OTLP messages on multiple threads,
  which can greatly improve the performance.
  By default it is set to workers(1).
  (#4774)

• opentelemetry(), syslog-ng-otlp() destinations: Added compression() option.

  This boolean option can be used to enable gzip compression in gRPC requests.
  By default it is set to compression(no).
  (#4765)

• opentelemetry(), syslog-ng-otlp() destinations: Added batch-bytes() option.

  This option lets the user limit the bytes size of a batch. As there is a
  default 4 MiB batch limit by OTLP, it is necessary to keep the batch size
  smaller, but it would be hard to configure without this option.

  Please note that the batch can be at most 1 message larger than the set
  limit, so consider this when setting this value.

  The default value is 4 MB, which is a bit below 4 MiB.

  The calculation of the batch size is done before compression, which is
  the same as the limit is calculated on the server.

  Example config:

    syslog-ng-otlp(
      url("localhost:12345")
      workers(16)
      log-fifo-size(1000000)
  
      batch-timeout(5000) # ms
      batch-lines(1000000) # Huge limit, batch-bytes() will limit us sooner
  
      batch-bytes(1MB) # closes and flushes the batch after the last message pushed it above the 1 MB limit
      # not setting batch-bytes() defaults to 4 MB, which is a bit below the default 4 MiB limit
    );
  

  (#4772)

• opentelemetry(), syslog-ng-otlp(): Added syslog-ng style list support.
  (#4794)

• $(tag) template function: expose bit-like tags that are set on messages.

  Syntax:
  $(tag <name-of-the-tag> <value-if-set> <value-if-unset>)

  Unless the value-if-set/unset arguments are specified $(tag) results in a
  boolean type, expanding to "0" or "1" depending on whether the message has
  the specified tag set.

  If value-if-set/unset are present, $(tag) would return a string, picking the
  second argument <value-if-set> if the message has <tag> and picking the
  third argument <value-if-unset> if the message does not have <tag>
  (#4766)

• set-severity() support for aliases: widespread aliases to severity values
  produced by various applications are added to set-severity().
  (#4763)

• flags(seqnum-all): available in all destination drivers, this new flag
  changes $SEQNUM behaviour, so that all messages get a sequence number, not
  just local ones. Previously syslog-ng followed the logic of the RFC5424
  meta.sequenceId structured data element, e.g. only local messages were to
  get a sequence number, forwarded messages retained their original sequenceId
  that we could potentially receive ourselves.

  For example, this destination would include the meta.sequenceId SDATA
  element even for non-local logs and increment that value by every message
  transmitted:

  destination { syslog("127.0.0.1" port(2001) flags(seqnum-all)); };

  This generates a message like this on the output, even if the message is
  not locally generated (e.g. forwarded from another syslog sender):

    <13>1 2023-12-09T21:51:30+00:00 localhost sdff - - [meta sequenceId="1"] f sdf fsd
    <13>1 2023-12-09T21:51:32+00:00 localhost sdff - - [meta sequenceId="2"] f sdf fsd
    <13>1 2023-12-09T21:51:32+00:00 localhost sdff - - [meta sequenceId="3"] f sdf fsd
    <13>1 2023-12-09T21:51:32+00:00 localhost sdff - - [meta sequenceId="4"] f sdf fsd
    <13>1 2023-12-09T21:51:32+00:00 localhost sdff - - [meta sequenceId="5"] f sdf fsd
  

  (#4745)

• loggen: improve loggen performance for synthetic workloads, so we can test
  for example up to 650k msg/sec on a AMD Ryzen 7 Pro 6850U CPU.
  (#4476)

Bugfixes

• metrics-probe(): Fixed not cleaning up dynamic labels for each message if no static labels are set.
  (#4750)

• regexp-parser(): Fixed a bug, which stored some values incorrectly if ${MESSAGE} was changed with a capture group.
  (#4759)

• network() source: fix marking originally valid utf-8 messages when sanitize-utf8 is enabled
  (#4744)

• python(): Fixed a memory leak in list typed LogMessage values.
  (#4790)

Packaging

• VERSION renamed to VERSION.txt: due to a name collision with C++ based
  builds on MacOS, the file containing our version number was renamed to
  VERSION.txt.
  (#4775)

• Added gperf as a build dependency.
  (#4763)

Notes to developers

• LogThreadedSourceDriver: Added multi-worker API, which is a breaking change.

  Check the Pull Request for inspiration on how to follow up these changes.
  (#4774)

Other changes

• network()/syslog() sources: support UTF-8 sanitization/validation of RFC 5424 and no-parse messages

  The sanitize-utf8, validate-utf8 flags are now supported when parsing RFC 5424 messages or when parsing is disabled.
  (#4744)

• APT packages: Added Ubuntu Mantic Minotaur.
  (#4737)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Attila Szakacs, Balazs Scheidler, Hofi, László Várady, Romain Tartière

4.5.0

You can read more about the new features in the AxoSyslog documentation.

Highlights

Sending log messages to OpenObserve

The openobserve-log() destination feeds OpenObserve via the JSON API.

Example config:

openobserve-log(
    url("http://openobserve-endpoint")
    port(5080)
    stream("default")
    user("[email protected]")
    password("V2tsn88GhdNTKxaS")
);

(#4698)

Sending messages to Google Pub/Sub

The google-pubsub() destination feeds Google Pub/Sub via the HTTP REST API.

Example config:

google-pubsub(
  project("syslog-ng-project")
  topic("syslog-ng-topic")
  auth(
    service-account(
      key("/path/to/service-account-key.json")
    )
  )
);

See the Google Pub/Sub documentation to learn more about configuring a service account.
(#4651)

Parsing PostgreSQL logs

The postgresql-csvlog-parser(): add a new parser to process CSV log formatted by
PostgreSQL (https://www.postgresql.org/docs/current/runtime-config-logging.html).
The CSV format is extracted into a set of name-value pairs.
(#4586)

Features

• http(): Added support for using templates in the url() option.

  In syslog-ng a template can only be resolved on a single message, as the same
  template might have different resolutions on different messages. A http batch
  consists of multiple messages, so it is not trivial to decide which message should
  be used for the resolution.

  When batching is enabled and multiple workers are configured it is important to
  only batch messages which generate identical URLs. In this scenario one must set
  the worker-partition-key() option with a template that contains all the templates
  used in the url() option, otherwise messages will be mixed.

  For security reasons, all the templated contents in the url() option are getting
  URL encoded automatically. Also the following parts of the url cannot be templated:

  • scheme
  • host
  • port
  • user
  • password
    (#4663)

• $TRANSPORT: this is a new name-value pair that syslog-ng populates
  automatically. It indicates the "transport" mechanism used to
  retrieve/receive the message. It is up to the source driver to determine
  the value. Currently the following values were implemented:

  BSD syslog drivers: tcp(), udp() & network()

  • rfc3164+tls
  • rfc3164+tcp
  • rfc3164+udp
  • rfc3164+proxied-tls
  • rfc3164+<custom logproto like altp>

  UNIX domain drivers: unix-dgram(), unix-stream()

  • unix-stream
  • unix-dgram

  RFC5424 style syslog: syslog():

  • rfc5426: syslog over udp
  • rfc5425: syslog over tls
  • rfc6587: syslog over tcp
  • rfc5424+<custom logproto like altp>: syslog over a logproto plugin

  Other drivers:

  • otlp: otel() driver
  • mqtt: mqtt() driver
  • hypr-api: hypr-audit-source() driver

  $IP_PROTO: indicate the IP protocol version used to retrieve/receive the
  message. Contains either "4" to indicate IPv4 and "6" to indicate IPv6.
  (#4673)

• network() and syslog() drivers: Added ignore-validity-period as a new flag to ssl-options().

  By specifying ignore-validity-period, you can ignore the validity periods
  of certificates during the certificate validation process.
  (#4642)

• tls() in udp()/tcp()/network() and syslog() drivers: add support
  for a new http() compatible ssl-version() option. This makes the TLS
  related options for http() and other syslog-like drivers more similar. This
  requires OpenSSL 1.1.0.
  (#4682)

• cloud-auth(): Added a new plugin for drivers, which implements different cloud related authentications.

  Currently the only supported authentication is GCP's Service Account for the http() destination.

  Example config:

  http(
    cloud-auth(
      gcp(
        service-account(
          key("/path/to/service-account-key.json")
          audience("https://pubsub.googleapis.com/google.pubsub.v1.Publisher")
        )
      )
    )
  );
  

  (#4651)

• csv-parser(): allow parsing the extracted values into matches ($1, $2, $3 ...)
  by omitting the columns() parameter, which normally specifies the column
  names.
  (#4678)

• --check-startup: a new command line option for syslog-ng along with the
  existing --syntax-only. This new option will do a complete configuration
  initialization and then exit with exit code indicating the result. Since
  this also initializes things like network listeners, it will probably not
  work when there is another syslog-ng instance running in the background. The
  recommended use of this option is a dedicated config check container, as
  explained in #4592.
  (#4646)

Bugfixes

• s3: Fixed an ImportError.

  ImportError: cannot import name 'SharedBool' from 'syslogng.modules.s3.s3_object'
  (#4700)

• loki(): fixed mixing non-related label values
  (#4713)

• type hinting: Parsing and casting fractions are now done locale independently.
  (#4702)

• metrics-probe(): Fixed a crash.

  This crash occurred when a metrics-probe() instance was used in multiple source threads,
  like a network() source with multiple connections.
  (#4685)

• flags() argument to various drivers: fix a potential crash in case a flag with at least 32 characters is used.
  No such flag is defined by syslog-ng, so the only way to trigger the crash is to use an invalid configuration file.
  (#4689)

• Fix $PROTO value for transport(tls) connections, previously it was set
  to "0" while in reality these are tcp connections (e.g. "6").

  Fix how syslog-ng sets $HOST for V4-mapped addresses in case of IPv6 source
  drivers (e.g. udp6()/tcp6() or when using ip-protocol(6) for tcp()/udp()).
  Previously V4-mapped addresses would be represented as
  "::ffff:<ipv4 address>". This is not wrong per-se, but would potentially
  cause the same host to be represented in multiple ways. With the fix,
  syslog-ng would just use "<ipv4 address>" in these cases.
  (#4673)

• db-parser(): support nested match characters in @QSTRING@ pattern parser
  (#4717)

Other changes

• LogSource and LogFetcher: additional documentation was added to these
  Python classes to cover explicit source-side batching functionalities (e.g.
  the auto_close_batch attribute and the close_batch() method).
  (#4673)

• rate-limit(): Renamed the template() option to key(), which better communicates the intention.
  (#4679)

• templates: The template-escape() option now only escapes the top-level template function.

  Before syslog-ng 4.5.0 if you had embedded template functions, the template-escape(yes) setting
  escaped the output of each template function, so the parent template function received an
  already escaped string. This was never the intention of the template-escape() option.

  Although this is a breaking change, we do not except anyone having a config that is affected.
  If you have such a config, make sure to follow-up this change. If you need help with it, feel
  free to open an issue or discussion on GitHub, or contact us on the Axoflow Discord server.
  (#4666)

• loki(): The timestamp() option now supports quoted strings.

  The valid values are the following, with or without quotes, case insensitive:

  • "current"
  • "received"
  • "msg"
    (#4688)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Attila Szakacs, Balazs Scheidler, Cedric Arickx, Fabrice Fontaine,
Hofi, László Várady, Romain Tartière, Szilard Parrag, yashmathne

4.4.0

Read Axoflow's blog post for more details.
You can read more about the new features in the AxoSyslog documentation.

Highlights

Sending messages between syslog-ng instances via OTLP/gRPC

The syslog-ng-otlp() source and destination helps to transfer the internal representation
of a log message between syslog-ng instances. In contrary to the syslog-ng() (ewmm())
drivers, syslog-ng-otlp() does not transfer the messages on simple TCP connections, but uses
the OpenTelemetry protocol to do so.

It is easily scalable (workers() option), uses built-in application layer acknowledgement,
out of the box supports google service authentication (ADC or ALTS), and gives the possibility
of better load balancing.

The performance is currently similar to ewmm() (OTLP is ~30% quicker) but there is a source
side limitation, which will be optimized. We measured 200-300% performance improvement with a
PoC optimized code using multiple threads, so stay tuned.

Note: The syslog-ng-otlp() source is only an alias to the opentelemetry() source.
This is useful for not needing to open different ports for the syslog-ng messages and other
OpenTelemetry messages. The syslog-ng messages are marked with a @syslog-ng scope name and
the current syslog-ng version as the scope version. Both sources will handle the incoming
syslog-ng messages as syslog-ng messages, and all other messages as simple OpenTelemetry
messages.
(#4564)

Grafana Loki destination

The loki() destination sends messages to Grafana Loki using gRPC.
The message format conforms to the documented HTTP endpoint:
https://grafana.com/docs/loki/latest/reference/api/#push-log-entries-to-loki

Example config:

loki(
    url("localhost:9096")
    labels(
        "app" => "$PROGRAM",
        "host" => "$HOST",
    )

    workers(16)
    batch-timeout(10000)
    batch-lines(1000)
);

Loki requires monotonic timestamps within the same label-set, which makes
it difficult to use the original message timestamp without the possibility
of message loss. In case the monotonic property is violated, Loki discards
the problematic messages with an error. The source of the timestamps can be
configured with the timestamp() option (current, received, msg).

(#4631)

S3 destination

The s3() destination stores log messages in S3 objects.

Minimal config:

s3(
    url("http://localhost:9000")
    bucket("syslog-ng")
    access-key("my-access-key")
    secret-key("my-secret-key")
    object-key("${HOST}/my-logs")
    template("${MESSAGE}\n")
);

Compression

Setting compression(yes) enables gzip compression, and implicitly adds a .gz suffix to the
created object's key. Use the compresslevel() options to set the level of compression (0-9).

Rotation based on object size

The max-object-size() option configures syslog-ng to finish an object if it reaches a certain
size. syslog-ng will append an index ("-1", "-2", ...) to the end of the object key when
starting a new object after rotation.

Rotation based on timestamp

The object-key-timestamp() option can be used to set a datetime related template, which gets
appended to the end of the object (e.g. "${R_MONTH_ABBREV}${R_DAY}" => "-Sep25"). When a log
message arrives with a newer timestamp template resolution, the previous timestamped object gets
finised and a new one is started with the new timestamp. Backfill messages do not reopen and append
the old object, but starts a new object with the key having an index appended to the old object.

Rotation based on timeout

The flush-grace-period() option sets the number of minutes to wait for new messages to arrive to
objects, if the timeout expires the object is finished, and a new message will start a new with
an index appended.

Upload options

The objects are uploaded with the multipart upload API. Chunks are composed locally. When a chunk
reaches a certain size (by default 5 MiB), the chunk is uploaded. When an object is finished, the
multipart upload gets completed and the chunks are merged by S3.

Upload parameters can be configured with the chunk-size(), upload-threads() and
max-pending-uploads() options.

Additional options

Additional options include region(), storage-class() and canned-acl().

(#4624)

Features

• http(): Added compression ability for use with metered egress/ingress

  The new features can be accessed with the following options:

  • accept-encoding() for requesting the compression of HTTP responses form the server.
    (These are currently not used by syslog-ng, but they still contribute to network traffic.)
    The available options are identity (for no compression), gzip or deflate.
    If you want the driver to accept multiple compression types, you can list them separated by
    commas inside the quotation mark, or write all, if you want to enable all available compression types.
  • content-compression() for compressing messages sent by syslog-ng. The available options are
    identity for no compression, gzip, or deflate.

  Below you can see a configuration example:

  destination d_http_compressed{
    http(url("127.0.0.1:80"), content-compression("deflate"), accept-encoding("all"));
  };
  

  (#4137)

• opensearch: Added a new destination.

  It is similar to elasticsearch-http(), with the difference that it does not have the type()
  option, which is deprecated and advised not to use.
  (#4560)

• Added metrics for message delays: a new metric is introduced that measures the
  delay the messages accumulate while waiting to be delivered by syslog-ng.
  The measurement is sampled, e.g. syslog-ng would take the very first message
  in every second and expose its delay as a value of the new metric.

  There are two new metrics:

  • syslogng_output_event_delay_sample_seconds -- contains the latency of
    outgoing messages
  • syslogng_output_event_delay_sample_age_seconds -- contains the age of the last
    measurement, relative to the current time.
    (#4565)

• metrics-probe: Added dynamic labelling support via name-value pairs

  You can use all value-pairs options, like key(), rekey(), pair() or scope(), etc...

  Example:

  metrics-probe(
    key("foo")
    labels(
      "static-label" => "bar"
      key(".my_prefix.*" rekey(shift-levels(1)))
    )
  );
  

  syslogng_foo{static_label="bar",my_prefix_baz="almafa",my_prefix_foo="bar",my_prefix_nested_axo="flow"} 4
  

  (#4610)

• systemd-journal(): Added support for enabling multiple systemd-journal() sources

  Using multiple systemd-journal() sources are now possible as long as each source uses a unique
  systemd namespace. The namespace can be configured with the namespace() option, which has a
  default value of "*".
  (#4553)

• stdout(): added a new destination that allows you to write messages easily
  to syslog-ng's stdout.
  (#4620)

• network(): Added ignore-hostname-mismatch as a new flag to ssl-options().

  By specifying ignore-hostname-mismatch, you can ignore the subject name of a
  certificate during the validation process. This means that syslog-ng will
  only check if the certificate itself is trusted by the current set of trust
  anchors (e.g. trusted CAs) ignoring the mismatch between the targeted
  hostname and the certificate subject.
  (#4628)

Bugfixes

• syslog-ng: fix runtime undefined symbol: random_choice_generator_parser' when executing syslog-ng -V or
  using an example plugin
  (#4615)

• Fix threaded destination crash during a configuration revert

  Threaded destinations that do not support the workers() option crashed while
  syslog-ng was trying to revert to an old configuration.
  (#4588)

• redis(): fix incrementing seq_num
  (#4588)

• python(): fix crash when using Persist or LogTemplate without global python{} code block in configuration
  (#4572)

• mqtt() destination: fix template option initialization
  (#4605)

• opentelemetry: Fixed error handling in case of insert failure.
  (#4583)

• pdbtool: add validation for types of <value> tags

  In patterndb, you can add extra name-value pairs following a match with the tags.
  But the actual value of these name-value pairs were never validated against their types,
  meaning that an incorrect value could be set using this construct.
  (#4621)

• grouping-by(), group-lines(): Fixed a persist name generating error.
  (#4478)

Packaging

• debian: Added tzdata-legacy to BuildDeps for recent debian versions.

  In the recent debian packaging some of the timezone info files moved
  to a new tzdata-legacy package from the standard tzdata package.
  (#4643)

• rhel: contrib/vim has been removed from the source.
  (#4607)

Other changes

• APT packages: Dropped support for Ubuntu Bionic.
  (#4648)

• vim: Syntax highlight file is no longer packaged.

  vim syntax files where previously installed by the RedHat packages of syslog-ng
  (but not the Debian ones). These files where sometime lagging behind, so in order
  to provide a more up-to-date experience on all platforms, regardless of the
  installation of the syslog-ng package, the vim syntax files have been moved to a
  dedicated repository syslog-ng/vim-syslog-ng that can be used using a plugin manager such as
  vim-plug, vim-pathogen or vundle.
  (#4607)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Alex Becker, Attila Szakacs, Balazs Scheidler, Bálint Horváth, Hofi,
László Várady, Romain Tartière, Szilard Parrag

4.3.1

This is the combination of the news entries of 4.3.0 and 4.3.1. 4.3.1 hotfixed
a python-parser() related crash and a metrics related memory leak. It also
added Ubuntu 23.04 and Debian 12 support for APT packages and the opensearch()
destination.

Read Axoflow's blog post for more details.

Highlights

parallelize() support for pipelines

syslog-ng has traditionally performed processing of log messages arriving
from a single connection sequentially. This was done to ensure message ordering
as well as most efficient use of CPU on a per message basis. This mode of
operation is performing well as long as we have a relatively large number
of parallel connections, in which case syslog-ng would use all the CPU cores
available in the system.

In case only a small number of connections deliver a large number of
messages, this behaviour may become a bottleneck.

With the new parallelization feature, syslog-ng gained the ability to
re-partition a stream of incoming messages into a set of partitions, each of
which is to be processed by multiple threads in parallel. This does away
with ordering guarantees and adds an extra per-message overhead. In exchange
it will be able to scale the incoming load to all CPUs in the system, even
if coming from a single, chatty sender.

To enable this mode of execution, use the new parallelize() element in your
log path:

log {
  source {
    tcp(
      port(2000)
      log-iw-size(10M) max-connections(10) log-fetch-limit(100000)
    );
  };
  parallelize(partitions(4));

  # from this part on, messages are processed in parallel even if
  # messages are originally coming from a single connection

  parser { ... };
  destination { ... };
};

The config above will take all messages emitted by the tcp() source and push
the work to 4 parallel threads of execution, regardless of how many
connections were in use to deliver the stream of messages to the tcp()
driver.

parallelize() uses round-robin to allocate messages to partitions by default.
You can however retain ordering for a subset of messages with the
partition-key() option.

You can use partition-key() to specify a message template. Messages that
expand to the same value are guaranteed to be mapped to the same partition.

For example:

log {
  source {
    tcp(
      port(2000)
      log-iw-size(10M) max-connections(10) log-fetch-limit(100000)
    );
  };
  parallelize(partitions(4) partition-key("$HOST"));

  # from this part on, messages are processed in parallel if their
  # $HOST value differs. Messages with the same $HOST will be mapped
  # to the same partition and are processed sequentially.

  parser { ... };
  destination { ... };
};

NOTE: parallelize() requires a patched version of libivykis that contains
this PR https://github.com/buytenh/ivykis/pull/25. syslog-ng source
releases bundle this version of ivykis in their source trees, so if you are
building from source, be sure to use the internal version
(--with-ivykis=internal). You can also use Axoflow's cloud native container
image for syslog-ng, named AxoSyslog
(https://github.com/axoflow/axosyslog-docker) which also incorporates this
change.

(#3966)

Receiving and sending OpenTelemetry (OTLP) messages

The opentelemetry() source, parser and destination are now available to receive, parse and send OTLP/gRPC
messages.

syslog-ng accepts logs, metrics and traces.

The incoming fields are not available through syslog-ng log message name-value pairs for the user by default.
This is useful for forwarding functionality (the opentelemetry() destination can access and format them).
If such functionality is required, you can configure the opentelemetry() parser, which maps all the fields
with some limitations.

The behavior of the opentelemetry() parser is the following:

The name-value pairs always start with .otel. prefix. The type of the message is stored in .otel.type
(possible values: log, metric and span). The resource info is mapped to .otel.resource.<...>
(e.g.: .otel.resource.dropped_attributes_count, .otel.resource.schema_url ...), the scope info
is mapped to .otel.scope.<...> (e.g.: .otel.scope.name, .otel.scope.schema_url, ...).

The fields of log records are mapped to .otel.log.<...> (e.g. .otel.log.body, .otel.log.severity_text, ...).

The fields of metrics are mapped to .otel.metric.<...> (e.g. .otel.metric.name, .otel.metric.unit, ...),
the type of the metric is mapped to .otel.metric.data.type (possible values: gauge, sum, histogram,
exponential_histogram, summary) with the actual data mapped to .otel.metric.data.<type>.<...>
(e.g.: .otel.metric.data.gauge.data_points.0.time_unix_nano, ...).

The fields of traces are mapped to .otel.span.<...> (e.g. .otel.span.name, .otel.span.trace_state, ...).

repeated fields are given an index (e.g. .otel.span.events.5.time_unix_nano).

The mapping of AnyValue type fields is limited.
string, bool, int64, double and bytes values are mapped with the respective syslog-ng name-value type
(e.g. .otel.resource.attributes.string_key => string_value), however ArrayValue and KeyValueList types
are stored serialized with protobuf type. protobuf and bytes types are not directly available for the
user, unless an explicit type cast is added (e.g. "bytes(${.otel.log.span_id})") or --include-bytes is passed
to name-value iterating template functions (e.g. $(format-json .otel.* --include-bytes), which will base64
encode the bytes content).

Three authentication methods are available in the source auth() block: insecure() (default), tls() and alts().
tls() accepts the key-file(), cert-file(), ca-file() and peer-verify() (possible values:
required-trusted, required-untrusted, optional-trusted and optional-untrusted) options.
ALTS is a simple to use authentication, only available within Google's infrastructure.

The same methods are available in the destination auth() block, with two differences: tls(peer-verify())
is not available, and there is a fourth method, called ADC, which accepts the target-service-account()
option, where a list of service accounts can be configured to match against when authenticating the server.

Example configs:

log otel_forward_mode_alts {
  source {
    opentelemetry(
      port(12345)
      auth(alts())
    );
  };

  destination {
    opentelemetry(
      url("my-otel-server:12345")
      auth(alts())
    );
  };
};

log otel_to_non_otel_insecure {
  source {
    opentelemetry(
      port(12345)
    );
  };

  parser {
    opentelemetry();
  };

  destination {
    network(
      "my-network-server"
      port(12345)
      template("$(format-json .otel.* --shift-levels 1 --include-bytes)\n")
    );
  };
};

log non_otel_to_otel_tls {
  source {
    network(
      port(12346)
    );
  };

  destination {
    opentelemetry(
      url("my-otel-server:12346")
      auth(
        tls(
          ca-file("/path/to/ca.pem")
          key-file("/path/to/key.pem")
          cert-file("/path/to/cert.pem")
        )
      )
    );
  };
};

(#4523)
(#4510)

Sending messages to CrowdStrike Falcon LogScale (Humio)

The logscale() destination feeds LogScale via the Ingest API.

Minimal config:

destination d_logscale {
  logscale(
    token("my-token")
  );
};

Additional options include:

• url()
• rawstring()
• timestamp()
• timezone()
• attributes()
• extra-headers()
• content-type()

(#4472)

Features

• afmongodb: Bulk MongoDB insert is added via the following options

  • bulk (yes/no) turns on/off bulk insert usage, no forces the old behavior (each log is inserted one by one into the MongoDB)
  • bulk_unordered (yes/no) turns on/off unordered MongoDB bulk operations
  • bulk_bypass_validation (yes/no) turns on/off MongoDB bulk operations validation
  • write_concern (unacked/acked/majority/n > 0) sets write concern mode of the MongoDB operations, both bulk and single

  NOTE: Bulk sending is only efficient if the used collection is constant (e.g. not using templates) or the used template does not lead to too many collections switching within a reasonable time range.
  (#4483)

• sql: Added 2 new options

  • quote_char to aid custom quoting for table and index names (e.g. MySQL needs sometimes this for certain identifiers)
    NOTE: Using a back-tick character needs a special formatting as syslog-ng uses it for configuration parameter names, so for that use: quote_char("``") (double back-tick)
  • dbi_driver_dir to define an optional DBI driver location for DBD initialization

  NOTE: libdbi and libdbi-drivers OSE forks are updated, afsql now should work nicely both on ARM and X86 macOS systems too (tested on macOS 13.3.1 and 12.6.4)

  Please do not use the pre-built ones (e.g. 0.9.0 from Homebrew), build from the master of the following

  • https://github.com/balabit-deps/libdbi-drivers
  • https://github.com/balabit-deps/libdbi

  (#4460)

• opensearch: Added a new destination.

  It is similar to elasticsearch-http(), with the difference that it does not have the type()
  option, which is deprecated and advised not to use.
  (#4560)

Bugfixes

• network(),syslog(),tcp() destination: fix TCP keepalive

  tcp-keepalive-*() options were broken on the destination side since v3.34.1.
  (#4559)

• Fixed a hang, which happend when syslog-ng received exremely low CPU time.
  (#4524)

• $(format-json): Fixed a bug where sometimes an unnecessary comma was added in case of a type cast failure.
  (#4477)

• Fix flow-control when fetch-limit() is set higher than 64K

  In high-performance use cases, users may configure log-iw-size() and
  fetch-limit() to be higher than 2^16, which caused flow-control issues,
  such as messages stuck in the queue forever or log sources not receiving
  messages.
  (#4528)

• int32() and int64() type casts: accept hex numbers as proper
  number representations just as the @NUMBER@ parser within db-parser().
  Supporting octal numbers were considered and then rejected as the canonical
  octal representation for numbers in C would be ambigious: a zero padded
  decimal number could be erroneously considered octal. I find that log
  messages contain zero padded decimals more often than octals.
  (#4535)

• Fixed compilation on platforms where SO_MEMINFO is not available
  (#4548)

• python: InstantAckTracker, ConsecutiveAckTracker and BatchedAckTracker are now called properly.

  Added proper fake classes for the InstantAckTracker, ConsecutiveAckTracker and BatchedAckTracker classes, and the wapper now calls the super class' constructor.
  Previusly the super class' constructor was not called which caused the python API to never call into the C API, which's result was that that the callback was never called.
  (#4549)

• python: Fixed a crash when reloading with a config, which uses a python parser with multiple references.
  (#4552)
  (#4567)

• mqtt(): Fixed the name of the stats instance (mqtt-source) to conform to the standard comma-separated format.
  (#4551)

• metrics: Fixed a memory leak which happened during reload, and was introduced in 4.3.0.
  (#4568)

Packaging

• scl.conf: The scl.conf file has been moved to /share/syslog-ng/include/scl.conf
  (#4534)

• C++ plugins: Some of syslog-ng's plugins now contain C++ code.

  By default they are being built if a C++ compiler is available.
  Disabling it is possible with --disable-cpp.

  Affected plugins:

  • lib/syslog-ng/libexamples.so
    • --disable-cpp will only disable the C++ part (random-choice-generator())
  • lib/syslog-ng/libotel.so

  (#4484)

• debian: A new module is added, called syslog-ng-mod-grpc.

  Its dependencies are: protobuf-compiler, protobuf-compiler-grpc, libprotobuf-dev, libgrpc++-dev.
  Building the module can be toggled with --enable-grpc.
  (#4510)

• pcre: syslog-ng now uses pcre2 (8 bit) as a dependency instead of pcre.

  The minimum pcre2 version is 10.0.
  (#4537)

Notes to developers

• lib/logmsg: Public field LogMessage::protected has been renamed to LogMessage::write_protected.

  Direct usage of this field is discouraged, instead use the following functions:

  • log_msg_is_write_protected()
  • log_msg_write_protect()
    (#4484)

• lib/templates: Public field LogTemplate::template has been renamed to LogTemplate::template_str.
  (#4484)

Other changes

• syslog-ng-cfg-db: Moved to a separate repository.

  It is available at: https://github.com/alltilla/syslog-ng-cfg-helper
  (#4475)

• disk-buffer: Added alternative option names

  disk-buf-size() -> capacity-bytes()
qout-size() -> front-cache-size()
mem-buf-length() -> flow-control-window-size()
mem-buf-size() -> flow-control-window-bytes()

  Old option names are still available.

  Example configs:

  tcp(
    "127.0.0.1" port(2001)
    disk-buffer(
      reliable(yes)
      capacity-bytes(1GiB)
      flow-control-window-bytes(200MiB)
      front-cache-size(1000)
    )
  );
  
  tcp(
    "127.0.0.1" port(2001)
    disk-buffer(
      reliable(no)
      capacity-bytes(1GiB)
      flow-control-window-size(10000)
      front-cache-size(1000)
    )
  );
  

  (#4526)

• selinux: Added RHEL9 support for the selinux policies

  Added RHEL9 support for the selinux policies at contrib/selinux
  (#4509)

• metrics: replace driver_instance (stats_instance) with metric labels

  The new metric system had a label inherited from legacy: driver_instance.

  This non-structured label has been removed and different driver-specific labels have been added instead, for example:

  Before:

  syslogng_output_events_total{driver_instance="mongodb,localhost:27017,defaultdb,,coll",id="#anon-destination1#1",result="queued"} 4
  

  After:

  syslogng_output_events_total{driver="mongodb",host="localhost:27017",database="defaultdb",collection="coll",id="#anon-destination1#1",result="queued"} 4
  

  This change may affect legacy stats outputs (syslog-ng-ctl stats), for example, persist-name()-based naming
  is no longer supported in this old format.
  (#4551)

• APT packages: Added Ubuntu Lunar Lobster and Debian Bookworm support.
  (#4561)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Andreas Friedmann, Attila Szakacs, Balazs Scheidler, Bálint Horváth,
Chuck Silvers, Evan Rempel, Hofi, Kovacs, Gergo Ferenc, László Várady,
Romain Tartière, Ryan Faircloth, vostrelt

4.3.0

Read Axoflow's blog post for more details.

Highlights

parallelize() support for pipelines

syslog-ng has traditionally performed processing of log messages arriving
from a single connection sequentially. This was done to ensure message ordering
as well as most efficient use of CPU on a per message basis. This mode of
operation is performing well as long as we have a relatively large number
of parallel connections, in which case syslog-ng would use all the CPU cores
available in the system.

In case only a small number of connections deliver a large number of
messages, this behaviour may become a bottleneck.

With the new parallelization feature, syslog-ng gained the ability to
re-partition a stream of incoming messages into a set of partitions, each of
which is to be processed by multiple threads in parallel. This does away
with ordering guarantees and adds an extra per-message overhead. In exchange
it will be able to scale the incoming load to all CPUs in the system, even
if coming from a single, chatty sender.

To enable this mode of execution, use the new parallelize() element in your
log path:

log {
  source {
    tcp(
      port(2000)
      log-iw-size(10M) max-connections(10) log-fetch-limit(100000)
    );
  };
  parallelize(partitions(4));

  # from this part on, messages are processed in parallel even if
  # messages are originally coming from a single connection

  parser { ... };
  destination { ... };
};

The config above will take all messages emitted by the tcp() source and push
the work to 4 parallel threads of execution, regardless of how many
connections were in use to deliver the stream of messages to the tcp()
driver.

parallelize() uses round-robin to allocate messages to partitions by default.
You can however retain ordering for a subset of messages with the
partition-key() option.

You can use partition-key() to specify a message template. Messages that
expand to the same value are guaranteed to be mapped to the same partition.

For example:

log {
  source {
    tcp(
      port(2000)
      log-iw-size(10M) max-connections(10) log-fetch-limit(100000)
    );
  };
  parallelize(partitions(4) partition-key("$HOST"));

  # from this part on, messages are processed in parallel if their
  # $HOST value differs. Messages with the same $HOST will be mapped
  # to the same partition and are processed sequentially.

  parser { ... };
  destination { ... };
};

NOTE: parallelize() requires a patched version of libivykis that contains
this PR https://github.com/buytenh/ivykis/pull/25. syslog-ng source
releases bundle this version of ivykis in their source trees, so if you are
building from source, be sure to use the internal version
(--with-ivykis=internal). You can also use Axoflow's cloud native container
image for syslog-ng, named AxoSyslog
(https://github.com/axoflow/axosyslog-docker) which also incorporates this
change.

(#3966)

Receiving and sending OpenTelemetry (OTLP) messages

The opentelemetry() source, parser and destination are now available to receive, parse and send OTLP/gRPC
messages.

syslog-ng accepts logs, metrics and traces.

The incoming fields are not available through syslog-ng log message name-value pairs for the user by default.
This is useful for forwarding functionality (the opentelemetry() destination can access and format them).
If such functionality is required, you can configure the opentelemetry() parser, which maps all the fields
with some limitations.

The behavior of the opentelemetry() parser is the following:

The name-value pairs always start with .otel. prefix. The type of the message is stored in .otel.type
(possible values: log, metric and span). The resource info is mapped to .otel.resource.<...>
(e.g.: .otel.resource.dropped_attributes_count, .otel.resource.schema_url ...), the scope info
is mapped to .otel.scope.<...> (e.g.: .otel.scope.name, .otel.scope.schema_url, ...).

The fields of log records are mapped to .otel.log.<...> (e.g. .otel.log.body, .otel.log.severity_text, ...).

The fields of metrics are mapped to .otel.metric.<...> (e.g. .otel.metric.name, .otel.metric.unit, ...),
the type of the metric is mapped to .otel.metric.data.type (possible values: gauge, sum, histogram,
exponential_histogram, summary) with the actual data mapped to .otel.metric.data.<type>.<...>
(e.g.: .otel.metric.data.gauge.data_points.0.time_unix_nano, ...).

The fields of traces are mapped to .otel.span.<...> (e.g. .otel.span.name, .otel.span.trace_state, ...).

repeated fields are given an index (e.g. .otel.span.events.5.time_unix_nano).

The mapping of AnyValue type fields is limited.
string, bool, int64, double and bytes values are mapped with the respective syslog-ng name-value type
(e.g. .otel.resource.attributes.string_key => string_value), however ArrayValue and KeyValueList types
are stored serialized with protobuf type. protobuf and bytes types are not directly available for the
user, unless an explicit type cast is added (e.g. "bytes(${.otel.log.span_id})") or --include-bytes is passed
to name-value iterating template functions (e.g. $(format-json .otel.* --include-bytes), which will base64
encode the bytes content).

Three authentication methods are available in the source auth() block: insecure() (default), tls() and alts().
tls() accepts the key-file(), cert-file(), ca-file() and peer-verify() (possible values:
required-trusted, required-untrusted, optional-trusted and optional-untrusted) options.
ALTS is a simple to use authentication, only available within Google's infrastructure.

The same methods are available in the destination auth() block, with two differences: tls(peer-verify())
is not available, and there is a fourth method, called ADC, which accepts the target-service-account()
option, where a list of service accounts can be configured to match against when authenticating the server.

Example configs:

log otel_forward_mode_alts {
  source {
    opentelemetry(
      port(12345)
      auth(alts())
    );
  };

  destination {
    opentelemetry(
      url("my-otel-server:12345")
      auth(alts())
    );
  };
};

log otel_to_non_otel_insecure {
  source {
    opentelemetry(
      port(12345)
    );
  };

  parser {
    opentelemetry();
  };

  destination {
    network(
      "my-network-server"
      port(12345)
      template("$(format-json .otel.* --shift-levels 1 --include-bytes)\n")
    );
  };
};

log non_otel_to_otel_tls {
  source {
    network(
      port(12346)
    );
  };

  destination {
    opentelemetry(
      url("my-otel-server:12346")
      auth(
        tls(
          ca-file("/path/to/ca.pem")
          key-file("/path/to/key.pem")
          cert-file("/path/to/cert.pem")
        )
      )
    );
  };
};

(#4523)
(#4510)

Sending messages to CrowdStrike Falcon LogScale (Humio)

The logscale() destination feeds LogScale via the Ingest API.

Minimal config:

destination d_logscale {
  logscale(
    token("my-token")
  );
};

Additional options include:

• url()
• rawstring()
• timestamp()
• timezone()
• attributes()
• extra-headers()
• content-type()

(#4472)

Features

• afmongodb: Bulk MongoDB insert is added via the following options

  • bulk (yes/no) turns on/off bulk insert usage, no forces the old behavior (each log is inserted one by one into the MongoDB)
  • bulk_unordered (yes/no) turns on/off unordered MongoDB bulk operations
  • bulk_bypass_validation (yes/no) turns on/off MongoDB bulk operations validation
  • write_concern (unacked/acked/majority/n > 0) sets write concern mode of the MongoDB operations, both bulk and single

  NOTE: Bulk sending is only efficient if the used collection is constant (e.g. not using templates) or the used template does not lead to too many collections switching within a reasonable time range.
  (#4483)

• sql: Added 2 new options

  • quote_char to aid custom quoting for table and index names (e.g. MySQL needs sometimes this for certain identifiers)
    NOTE: Using a back-tick character needs a special formatting as syslog-ng uses it for configuration parameter names, so for that use: quote_char("``") (double back-tick)
  • dbi_driver_dir to define an optional DBI driver location for DBD initialization

  NOTE: libdbi and libdbi-drivers OSE forks are updated, afsql now should work nicely both on ARM and X86 macOS systems too (tested on macOS 13.3.1 and 12.6.4)

  Please do not use the pre-built ones (e.g. 0.9.0 from Homebrew), build from the master of the following

  • https://github.com/balabit-deps/libdbi-drivers
  • https://github.com/balabit-deps/libdbi

  (#4460)

Bugfixes

• network(),syslog(),tcp() destination: fix TCP keepalive

  tcp-keepalive-*() options were broken on the destination side since v3.34.1.
  (#4559)

• Fixed a hang, which happend when syslog-ng received exremely low CPU time.
  (#4524)

• $(format-json): Fixed a bug where sometimes an unnecessary comma was added in case of a type cast failure.
  (#4477)

• Fix flow-control when fetch-limit() is set higher than 64K

  In high-performance use cases, users may configure log-iw-size() and
  fetch-limit() to be higher than 2^16, which caused flow-control issues,
  such as messages stuck in the queue forever or log sources not receiving
  messages.
  (#4528)

• int32() and int64() type casts: accept hex numbers as proper
  number representations just as the @NUMBER@ parser within db-parser().
  Supporting octal numbers were considered and then rejected as the canonical
  octal representation for numbers in C would be ambigious: a zero padded
  decimal number could be erroneously considered octal. I find that log
  messages contain zero padded decimals more often than octals.
  (#4535)

• Fixed compilation on platforms where SO_MEMINFO is not available
  (#4548)

• python: InstantAckTracker, ConsecutiveAckTracker and BatchedAckTracker are now called properly.

  Added proper fake classes for the InstantAckTracker, ConsecutiveAckTracker and BatchedAckTracker classes, and the wapper now calls the super class' constructor.
  Previusly the super class' constructor was not called which caused the python API to never call into the C API, which's result was that that the callback was never called.
  (#4549)

• python: Fixed a crash when reloading with a config, which uses a python parser with multiple references.
  (#4552)

• mqtt(): Fixed the name of the stats instance (mqtt-source) to conform to the standard comma-separated format.
  (#4551)

Packaging

• scl.conf: The scl.conf file has been moved to /share/syslog-ng/include/scl.conf
  (#4534)

• C++ plugins: Some of syslog-ng's plugins now contain C++ code.

  By default they are being built if a C++ compiler is available.
  Disabling it is possible with --disable-cpp.

  Affected plugins:

  • lib/syslog-ng/libexamples.so
    • --disable-cpp will only disable the C++ part (random-choice-generator())
  • lib/syslog-ng/libotel.so

  (#4484)

• debian: A new module is added, called syslog-ng-mod-grpc.

  Its dependencies are: protobuf-compiler, protobuf-compiler-grpc, libprotobuf-dev, libgrpc++-dev.
  Building the module can be toggled with --enable-grpc.
  (#4510)

• pcre: syslog-ng now uses pcre2 (8 bit) as a dependency instead of pcre.

  The minimum pcre2 version is 10.0.
  (#4537)

Notes to developers

• lib/logmsg: Public field LogMessage::protected has been renamed to LogMessage::write_protected.

  Direct usage of this field is discouraged, instead use the following functions:

  • log_msg_is_write_protected()
  • log_msg_write_protect()
    (#4484)

• lib/templates: Public field LogTemplate::template has been renamed to LogTemplate::template_str.
  (#4484)

Other changes

• syslog-ng-cfg-db: Moved to a separate repository.

  It is available at: https://github.com/alltilla/syslog-ng-cfg-helper
  (#4475)

• disk-buffer: Added alternative option names

  disk-buf-size() -> capacity-bytes()
qout-size() -> front-cache-size()
mem-buf-length() -> flow-control-window-size()
mem-buf-size() -> flow-control-window-bytes()

  Old option names are still available.

  Example configs:

  tcp(
    "127.0.0.1" port(2001)
    disk-buffer(
      reliable(yes)
      capacity-bytes(1GiB)
      flow-control-window-bytes(200MiB)
      front-cache-size(1000)
    )
  );
  
  tcp(
    "127.0.0.1" port(2001)
    disk-buffer(
      reliable(no)
      capacity-bytes(1GiB)
      flow-control-window-size(10000)
      front-cache-size(1000)
    )
  );
  

  (#4526)

• selinux: Added RHEL9 support for the selinux policies

  Added RHEL9 support for the selinux policies at contrib/selinux
  (#4509)

• metrics: replace driver_instance (stats_instance) with metric labels

  The new metric system had a label inherited from legacy: driver_instance.

  This non-structured label has been removed and different driver-specific labels have been added instead, for example:

  Before:

  syslogng_output_events_total{driver_instance="mongodb,localhost:27017,defaultdb,,coll",id="#anon-destination1#1",result="queued"} 4
  

  After:

  syslogng_output_events_total{driver="mongodb",host="localhost:27017",database="defaultdb",collection="coll",id="#anon-destination1#1",result="queued"} 4
  

  This change may affect legacy stats outputs (syslog-ng-ctl stats), for example, persist-name()-based naming
  is no longer supported in this old format.
  (#4551)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Andreas Friedmann, Attila Szakacs, Balazs Scheidler, Bálint Horváth,
Chuck Silvers, Evan Rempel, Hofi, Kovacs, Gergo Ferenc, László Várady,
Romain Tartière, Ryan Faircloth, vostrelt

4.2.0

Read Axoflow's blog post for more details.

Highlights

Sending messages to Splunk HEC

The splunk-hec-event() destination feeds Splunk via the HEC events API.

Minimal config:

destination d_splunk_hec_event {
  splunk-hec-event(
    url("https://localhost:8088")
    token("70b6ae71-76b3-4c38-9597-0c5b37ad9630")
  );
};

Additional options include:

• event()
• index()
• source()
• sourcetype()
• host()
• time()
• default-index()
• default-source()
• default-sourcetype()
• fields()
• extra-headers()
• extra-queries()
• content-type()

The splunk-hec-raw() destination feeds Splunk via the HEC raw API.

Minimal config:

destination d_splunk_hec_raw {
  splunk-hec-raw(
    url("https://localhost:8088")
    token("70b6ae71-76b3-4c38-9597-0c5b37ad9630")
    channel("05ed4617-f186-4ccd-b4e7-08847094c8fd")
  );
};

(#4462)

Smart multi-line for recognizing backtraces

multi-line-mode(smart):
With this multi-line mode, the inherently multi-line data backtrace format is
recognized even if they span multiple lines in the input and are converted
to a single log message for easier analysis. Backtraces for the following
programming languages are recognized : Python, Java, JavaScript, PHP, Go,
Ruby and Dart.

The regular expressions to recognize these programming languages are
specified by an external file called
/usr/share/syslog-ng/smart-multi-line.fsm (installation path depends on
configure arguments), in a format that is described in that file.

group-lines() parser: this new parser correlates multi-line messages
received as separate, but subsequent lines into a single log message.
Received messages are first collected into streams related messages (using
key()), then collected into correlation contexts up to timeout() seconds.
The identification of multi-line messages are then performed on these
message contexts within the time period.

  group-lines(key("$FILE_NAME")
              multi-line-mode("smart")
        template("$MESSAGE")
        timeout(10)
        line-separator("\n")
  );

(#4225)

HYPR Audit Trail source

hypr-audit-trail() & hypr-app-audit-trail() source drivers are now
available to monitor the audit trails for HYPR applications.

See the README.md file in the driver's directory to see usage information.

(#4175)

ebpf() plugin and reuseport packet randomizer

A new ebpf() plugin was added as a framework to leverage the kernel's eBPF
infrastructure to improve performance and scalability of syslog-ng.

Example:

source s_udp {
        udp(so-reuseport(yes) port(2000) persist-name("udp1")
                ebpf(reuseport(sockets(4)))
        );
        udp(so-reuseport(yes) port(2000) persist-name("udp2"));
        udp(so-reuseport(yes) port(2000) persist-name("udp3"));
        udp(so-reuseport(yes) port(2000) persist-name("udp4"));
};

NOTE: The ebpf() plugin is considered advanced usage so its compilation is
disabled by default. Please don't use it unless all other avenues of
configuration solutions are already tried. You will need a special
toolchain and a recent kernel version to compile and run eBPF programs.

(#4365)

Features

• network source: During a TLS handshake, syslog-ng now automatically sets the
  certificate_authorities field of the certificate request based on the ca-file()
  and ca-dir() options. The pkcs12-file() option already had this feature.
  (#4412)

• metrics-probe(): Added level() option to set the stats level of the generated metrics.
  (#4453)

• metrics-probe(): Added increment() option.

  Users can now set a template, which resolves to a number that modifies
  the increment of the counter. If not set, the increment is 1.
  (#4447)

• python: Added support for typed custom options.

  This applies for python source, python-fetcher source, python destination,
  python parser and python-http-header inner destination.

  Example config:

  python(
    class("TestClass")
    options(
      "string_option" => "example_string"
      "bool_option" => True  # supported values are: True, False, yes, no
      "integer_option" => 123456789
      "double_option" => 123.456789
      "string_list_option" => ["string1", "string2", "string3"]
      "template_option" => LogTemplate("${example_template}")
    )
  );
  

  Breaking change! Previously values were converted to strings if possible, now they are passed
  to the python class with their real type. Make sure to follow up these changes
  in your python code!
  (#4354)

• mongodb destination: Added support for list, JSON and null types.
  (#4437)

• add-contextual-data(): significantly reduce memory usage for large CSV
  files.
  (#4444)

• python(): new LogMessage methods for querying as string and with default values

  • get(key[, default])
    Return the value for key if key exists, else default. If default is
    not given, it defaults to None, so that this method never raises a
    KeyError.

  • get_as_str(key, default=None, encoding='utf-8', errors='strict', repr='internal'):
    Return the string value for key if key exists, else default.
    If default is not given, it defaults to None, so that this method never
    raises a KeyError.

    The string value is decoded using the codec registered for encoding.
    errors may be given to set the desired error handling scheme.

    Note that currently repr='internal' is the only available representation.
    We may implement another more Pythonic representation in the future, so please
    specify the repr argument explicitly if you want to avoid future
    representation changes in your code.
    (#4410)

• kubernetes() source: Added support for json-file logging driver format.
  (#4419)

• The new $RAWMSG_SIZE hard macro can be used to query the original size of the
  incoming message in bytes.

  This information may not be available for all source drivers.
  (#4440)

• syslog-ng configuration identifier

  A new syslog-ng configuration keyword has been added, which allows specifying a config identifier. For example:

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

  This keyword can be used for config identification in managed environments, where syslog-ng instances and their
  configuration are deployed/generated automatically.

  syslog-ng-ctl config --id can be used to query the active configuration ID and the SHA256 hash of the full
  "preprocessed" syslog-ng configuration. For example:

  $ syslog-ng-ctl config --id
  cfg-20230404-13-g02b0850fc (08ddecfa52a3443b29d5d5aa3e5114e48dd465e195598062da9f5fc5a45d8a83)
  

  (#4420)

• syslog-ng: add --config-id command line option

  Similarly to --syntax-only, this command line option parses the configuration
  and then prints its ID before exiting.

  It can be used to query the ID of the current configuration persisted on
  disk.
  (#4435)

• Health metrics and syslog-ng-ctl healthcheck

  A new syslog-ng-ctl command has been introduced, which can be used to query a healthcheck status from syslog-ng.
  Currently, only 2 basic health values are reported.

  syslog-ng-ctl healthcheck --timeout <seconds> can be specified to use it as a boolean healthy/unhealthy check.

  Health checks are also published as periodically updated metrics.
  The frequency of these checks can be configured with the stats(healthcheck-freq()) option.
  The default is 5 minutes.
  (#4362)

• $(format-json) and template functions which support value-pairs
  expressions: new key transformations upper() and lower() have been added to
  translate the caps of keys while formatting the output template. For
  example:

  template("$(format-json test.* --upper)\n")
  

  Would convert all keys to uppercase. Only supports US ASCII.
  (#4452)

• python(), python-fetcher() sources: Added a mapping for the flags() option.

  The state of the flags() option is mapped to the self.flags variable, which is
  a Dict[str, bool], for example:

  {
      '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,
  }
  

  (#4455)

Metrics

• network(), syslog(): TCP connection metrics

  syslogng_socket_connections{id="tcp_src#0",driver_instance="afsocket_sd.(stream,AF_INET(0.0.0.0:5555))",direction="input"} 3
  syslogng_socket_max_connections{id="tcp_src#0",driver_instance="afsocket_sd.(stream,AF_INET(0.0.0.0:5555))",direction="input"} 10
  syslogng_socket_rejected_connections_total{id="tcp_src#0",driver_instance="afsocket_sd.(stream,AF_INET(0.0.0.0:5555))",direction="input"} 96
  

  internal(): internal_events_queue_capacity metric

  syslog-ng-ctl healthcheck: new healthcheck value syslogng_internal_events_queue_usage_ratio
  (#4411)

• metrics: new network (TCP, UDP) metrics are available on stats level 1

  # syslog-ng-ctl stats prometheus
  
  syslogng_socket_receive_buffer_used_bytes{id="#anon-source0#3",direction="input",driver_instance="afsocket_sd.udp4"} 0
  syslogng_socket_receive_buffer_max_bytes{id="#anon-source0#3",direction="input",driver_instance="afsocket_sd.udp4"} 268435456
  syslogng_socket_receive_dropped_packets_total{id="#anon-source0#3",direction="input",driver_instance="afsocket_sd.udp4"} 619173
  
  syslogng_socket_connections{id="#anon-source0#0",direction="input",driver_instance="afsocket_sd.(stream,AF_INET(0.0.0.0:2000))"} 1
  

  (#4374)

• New configuration-related metrics:

  syslogng_last_config_reload_timestamp_seconds 1681309903
  syslogng_last_successful_config_reload_timestamp_seconds 1681309758
  syslogng_last_config_file_modification_timestamp_seconds 1681309877
  

  (#4420)

• destination: Introduced queue metrics.

  • The corresponding driver is identified with the "id" and "driver_instance" labels.
  • Available counters are "memory_usage_bytes" and "events".
  • Memory queue metrics are available with "syslogng_memory_queue_" prefix,
    disk-buffer metrics are available with "syslogng_disk_queue_" prefix.
  • disk-buffer metrics have an additional "path" label, pointing to the location of the disk-buffer file
    and a "reliable" label, which can be either "true" or "false".
  • Threaded destinations, like http, python, etc have an additional "worker" label.

  Example metrics

  syslogng_disk_queue_events{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00000.rqf",reliable="true",worker="0"} 80
  syslogng_disk_queue_events{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00001.rqf",reliable="true",worker="1"} 7
  syslogng_disk_queue_events{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00002.rqf",reliable="true",worker="2"} 7
  syslogng_disk_queue_events{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00003.rqf",reliable="true",worker="3"} 7
  syslogng_disk_queue_events{driver_instance="tcp,localhost:1235",id="d_network_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00000.qf",reliable="false"} 101
  syslogng_disk_queue_memory_usage_bytes{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00000.rqf",reliable="true",worker="0"} 3136
  syslogng_disk_queue_memory_usage_bytes{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00001.rqf",reliable="true",worker="1"} 2776
  syslogng_disk_queue_memory_usage_bytes{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00002.rqf",reliable="true",worker="2"} 2760
  syslogng_disk_queue_memory_usage_bytes{driver_instance="http,http://localhost:1239",id="d_http_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00003.rqf",reliable="true",worker="3"} 2776
  syslogng_disk_queue_memory_usage_bytes{driver_instance="tcp,localhost:1235",id="d_network_disk_buffer#0",path="/var/syslog-ng/syslog-ng-00000.qf",reliable="false"} 39888
  syslogng_memory_queue_events{driver_instance="http,http://localhost:1236",id="d_http#0",worker="0"} 15
  syslogng_memory_queue_events{driver_instance="http,http://localhost:1236",id="d_http#0",worker="1"} 14
  syslogng_memory_queue_events{driver_instance="tcp,localhost:1234",id="d_network#0"} 29
  syslogng_memory_queue_memory_usage_bytes{driver_instance="http,http://localhost:1236",id="d_http#0",worker="0"} 5896
  syslogng_memory_queue_memory_usage_bytes{driver_instance="http,http://localhost:1236",id="d_http#0",worker="1"} 5552
  syslogng_memory_queue_memory_usage_bytes{driver_instance="tcp,localhost:1234",id="d_network#0"} 11448
  

  (#4392)

• network(), syslog(), file(), http(): new byte-based metrics for incoming/outgoing events

  These metrics show the serialized message sizes (protocol-specific header/framing/etc. length is not included).

  syslogng_input_event_bytes_total{id="s_network#0",driver_instance="tcp,127.0.0.1"} 1925529600
  syslogng_output_event_bytes_total{id="d_network#0",driver_instance="tcp,127.0.0.1:5555"} 565215232
  syslogng_output_event_bytes_total{id="d_http#0",driver_instance="http,http://127.0.0.1:8080/"} 1024
  

  (#4440)

• disk-buffer: Added metrics for monitoring the available space in disk-buffer dir()s.

  Metrics are available from stats(level(1)).

  By default, the metrics are generated every 5 minutes, but it can be changed in the global options:

  options {
    disk-buffer(
      stats(
        freq(10)
      )
    );
  };
  

  Setting freq(0) disabled this feature.

  Example metrics:

  syslogng_disk_queue_dir_available_bytes{dir="/var/syslog-ng"} 870109413376
  

  (#4399)

• disk-buffer: Added metrics for abandoned disk-buffer files.

  Availability is the same as the disk_queue_dir_available_bytes metric.

  Example metrics:

  syslogng_disk_queue_capacity_bytes{abandoned="true",path="/var/syslog-ng/syslog-ng-00000.rqf",reliable="true"} 104853504
  syslogng_disk_queue_disk_allocated_bytes{abandoned="true",path="/var/syslog-ng/syslog-ng-00000.rqf",reliable="true"} 273408
  syslogng_disk_queue_disk_usage_bytes{abandoned="true",path="/var/syslog-ng/syslog-ng-00000.rqf",reliable="true"} 269312
  syslogng_disk_queue_events{abandoned="true",path="/var/syslog-ng/syslog-ng-00000.rqf",reliable="true"} 860
  

  (#4402)

• disk-buffer: Added capacity, disk_allocated and disk_usage metrics.

  • "capacity_bytes": The theoretical maximal useful size of the disk-buffer.
    This is always smaller, than disk-buf-size(), as there is some reserved
    space for metadata. The actual full disk-buffer file can be larger than this,
    as syslog-ng allows to write over this limit once, at the end of the file.

  • "disk_allocated_bytes": The current size of the disk-buffer file on the disk. Please note that
    the disk-buffer file size does not strictly correlate with the number
    of messages, as it is a ring buffer implementation, and also syslog-ng
    optimizes the truncation of the file for performance reasons.

  • "disk_usage_bytes": The serialized size of the queued messages in the disk-buffer file. This counter
    is useful for calculating the disk usage percentage (disk_usage_bytes / capacity_bytes)
    or the remaining available space (capacity_bytes - disk_usage_bytes).

  Example metrics:

  syslogng_disk_queue_capacity_bytes{driver_id="d_network#0",driver_instance="tcp,localhost:1235",path="/var/syslog-ng-00000.rqf",reliable="true"} 104853504
  syslogng_disk_queue_disk_allocated_bytes{driver_id="d_network#0",driver_instance="tcp,localhost:1235",path="/var/syslog-ng-00000.rqf",reliable="true"} 17284
  syslogng_disk_queue_disk_usage_bytes{driver_id="d_network#0",driver_instance="tcp,localhost:1235",path="/var/syslog-ng-00000.rqf",reliable="true"} 13188
  

  (#4356)

• kubernetes(): Added input_events_total and input_event_bytes_total metrics.

  syslogng_input_events_total{cluster="k8s",driver="kubernetes",id="#anon-source0",namespace="default",pod="log-generator-1682517834-7797487dcc-49hqc"} 25
  syslogng_input_event_bytes_total{cluster="k8s",driver="kubernetes",id="#anon-source0",namespace="default",pod="log-generator-1682517834-7797487dcc-49hqc"} 1859
  

  (#4447)

Bugfixes

• pdbtool test: fix two type validation bugs:

  1. When pdbtool test validates the type information associated with a name-value
     pair, it was using string comparisons, which didn't take type aliases
     into account. This is now fixed, so that "int", "integer" or "int64"
     can all be used to mean the same type.

  2. When type information is missing from a <test_value/> tag, don't
     validate it against "string", rather accept any extracted type.

  In addition to these fixes, a new alias "integer" was added to mean the same
  as "int", simply because syslog-ng was erroneously using this term when
  reporting type information in its own messages.
  (#4405)

• $(format-json): fix RFC8259 number violation

  $(format-json) produced invalid JSON output when it contained numeric values with leading zeros or + signs.
  This has been fixed.
  (#4415)

• grouping-by(): fix persist-name() option not taken into account
  (#4390)

• python(), db-parser(), grouping-by(), add-contextual-data(): fix typing compatibility with <4.0 config versions
  (#4394)

• python: Fixed a crash which occurred at reloading after registering a confgen plugin.
  (#4459)

• date-parser(): fix %z when system timezone has no daylight saving time
  (#4401)

• Consider messages consumed into correlation states "matching": syslog-ng's
  correlation functionality (e.g. grouping-by() or db-parser() with such
  rules) drop individual messages as they are consumed into a correlation
  contexts and you are using inject-mode(aggregate-only). This is usually
  happens because you are only interested in the combined message and not in
  those that make up the combination. However, if you are using correlation
  with conditional processing (e.g. if/elif/else or flags(final)), such
  messages were erroneously considered as unmatching, causing syslog-ng to
  take the alternative branch.

  Example:

  With a configuration similar to this, individual messages are consumed into
  a correlation state and dropped by grouping-by():

  log {
      source(...);
  
      if {
          grouping-by(... inject-mode(aggregate-only));
      } else {
          # alternative branch
      };
  };
  

  The bug was that these individual messages also traverse the else branch,
  even though they were successfully processed with the inclusion into the
  correlation context. This is not correct. The bugfix changes this behaviour.
  (#4370)

• netmask6(): fix crash when user specifies too long mask
  (#4429)

• afprog: Fixed possible freezing on some OSes
  (#4438)

• network(), syslog(), syslog-parser(): fix null termination of SDATA param names
  (#4429)

• python(): fix LogMessage subscript not raising KeyError on non-existent keys

  When message fields were queried (msg["key"]) and the given key did not exist,
  None or an empty string was returned (depending on the version of the config).

  Neither was correct, now a KeyError occurs in such cases.
  (#4410)

• $(python): fix template function prefix being overwritten when using datetime types
  (#4410)

• disk-buffer: Fixed queued messages stats counting, when a disk-buffer became corrupted.
  (#4385)

• $(format-json): fix escaping control characters

  $(format-json) produced invalid JSON output when a string value contained control characters.
  (#4417)

• disk-buffer(): fix deinitialization when starting syslog-ng with invalid configuration
  (#4418)

• python(): fix exception handling when LogMessage value conversion fails
  (#4410)

• json-parser(): Fixed parsing non-string arrays.

  syslog-ng now no longer parses non-string arrays to list of strings, losing the original type
  information of the array's elements.
  (#4396)

• disk-buffer: Fixed a rare race condition when calculating disk-buffer filename.
  (#4381)

• python-persist: fix off-by-one overflow
  (#4429)

Packaging

• The --with-python-venv-dir=path configure option can be used to modify the location of syslog-ng's venv.
  The default is still ${localstatedir}/python-venv.
  (#4465)

Other changes

• The sdata-prefix() option does not accept values longer than 128 characters.
  (#4429)

• grouping-by(): Remove setting of the ${.classifier.context_id}
  name-value pair in all messages consumed into a correlation context. This
  functionality is inherited from db-parser() and has never been documented
  for grouping-by(), has of limited use, and any uses can be replaced by the
  use of the built-in macro named $CONTEXT_ID. Modifying all consumed
  messages this way has significant performance consequences for
  grouping-by() and removing it outweighs the small incompatibility this
  change introduces. The similar functionality in db-parser() correlation is
  not removed with this change.
  (#4424)

• config: Added internal() option to sources, destinations, parsers and rewrites.

  Its main usage is in SCL blocks. Drivers configured with internal(yes) register
  their metrics on level 3. This makes developers of SCLs able to create metrics manually
  with metrics-probe() and "disable" every other metrics, they do not need.
  (#4451)

• The following Prometheus metrics have been renamed:

  log_path_{in,e}gress -> route_{in,e}gress_total
internal_source -> internal_events_total

  The internal_queue_length stats counter has been removed.
  It was deprecated since syslog-ng 3.29.
  (#4411)

syslog-ng Discord

For a bit more interactive discussion, join our Discord server:

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Alex Becker, Attila Szakacs, Balazs Scheidler, Hofi, László Várady,
Muhammad Shanif, Ricfilipe, Romain Tartière

4.1.1

This is the combination of the news entries of 4.1.0 and 4.1.1.
4.1.1 hotfixed a grouping-by() and db-parser() related crash.

Highlights

PROXY protocol v2 support (#4211)

We've added support for PROXY protocol v2 (transport(proxied-tcp)), a protocol
used by network load balancers, such as Amazon Elastic Load Balancer and
HAProxy, to carry original source/destination address information, as described
in https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

Metrics revised

Prometheus metric format (#4325)

A new metric system has been introduced to syslog-ng, where metrics are
identified by names and partitioned by labels, which is similar to the
Prometheus data model.

The syslog-ng-ctl stats prometheus command can be used to query syslog-ng
metrics in a format that conforms to the Prometheus text-based exposition
format.

syslog-ng-ctl stats prometheus --with-legacy-metrics displays legacy metrics
as well. Legacy metrics do not follow Prometheus' metric and label conventions.

Classification (metadata-based metrics) (#4318)

metrics-probe(), a new parser has also been added, which counts messages
passing through based on the metadata of each message. The parser creates
labeled metrics based on the fields of the message.

Both the key and labels can be set in the config, the values of the labels can
be templated. E.g.:

parser p_metrics_probe {
  metrics-probe(
    key("custom_key")  # adds "syslogng_" prefix => "syslogng_custom_key"
    labels(
      "custom_label_name_1" => "foobar"
      "custom_label_name_2" => "${.custom.field}"
    )
  );
};

With this config, it creates counters like these:

syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="bar"} 1
syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="foo"} 1
syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="baz"} 3

The minimal config creates counters with the key
syslogng_classified_events_total and labels app, host, program and
source. E.g.:

parser p_metrics_probe {
  metrics-probe();
};

With this config, it creates counters like these:

syslogng_classified_events_total{app="example-app", host="localhost", program="baz", source="s_local_1"} 3
syslogng_classified_events_total{app="example-app", host="localhost", program="bar", source="s_local_1"} 1
syslogng_classified_events_total{app="example-app", host="localhost", program="foo", source="s_local_1"} 1

Named log paths (path ingress/egress metrics) (#4344)

It is also possible to create named log paths, for example:

log top-level {
    source(s_local);

    log inner-1 {
        filter(f_inner_1);
        destination(d_local_1);
    };

    log inner-2 {
        filter(f_inner_2);
        destination(d_local_2);
    };
};

Each named log path counts its ingress and egress messages:

syslogng_log_path_ingress{id="top-level"} 114
syslogng_log_path_ingress{id="inner-1"} 114
syslogng_log_path_ingress{id="inner-2"} 114
syslogng_log_path_egress{id="top-level"} 103
syslogng_log_path_egress{id="inner-1"} 62
syslogng_log_path_egress{id="inner-2"} 41

Note that the egress statistics only count the messages which have been have not
been filtered out from the related log path, it does care about whether there
are any destinations in it or that any destination delivers or drops the
message.

The above three features are experimental; the output of stats prometheus
(names, labels, etc.) and the metrics created by metrics-probe() and named log
paths may change in the next 2-3 releases.

Features

• $(format-date): add a new template function to format time and date values

  $(format-date [options] format-string [timestamp])

  $(format-date) takes a timestamp in the DATETIME representation and
  formats it according to an strftime() format string. The DATETIME
  representation in syslog-ng is a UNIX timestamp formatted as a decimal
  number, with an optional fractional part, where the seconds and the
  fraction of seconds are separated by a dot.

  If the timestamp argument is missing, the timestamp of the message is
  used.

  Options:
  --time-zone <TZstring> -- override timezone of the original timestamp
  (#4202)

• syslog-parser() and all syslog related sources: accept unquoted RFC5424
  SD-PARAM-VALUEs instead of rejecting them with a parse error.

  sdata-parser(): this new parser allows you to parse an RFC5424 style
  structured data string. It can be used to parse this relatively complex
  format separately.
  (#4281)

• system() source: the system() source was changed on systemd platforms to
  fetch journal messages that relate to the current boot only (e.g. similar
  to journalctl -fb) and to ignore messages generated in previous boots,
  even if those messages were succesfully stored in the journal and were not
  picked up by syslog-ng. This change was implemented as the journald access
  APIs work incorrectly if time goes backwards across reboots, which is an
  increasingly frequent event in virtualized environments and on systems that
  lack an RTC. If you want to retain the old behaviour, please bypass the
  system() source and use systemd-journal() directly, where this option
  can be customized. The change is not tied to @version as we deemed the new
  behaviour fixing an actual bug. For more information consult #2836.

  systemd-journald() source: add match-boot() and matches() options to
  allow you to constrain the collection of journal records to a subset of what
  is in the journal. match-boot() is a yes/no value that allows you to fetch
  messages that only relate to the current boot. matches() allows you to
  specify one or more filters on journal fields.

  Examples:

  source s_journal_current_boot_only {
    systemd-source(match-boot(yes));
  };
  
  source s_journal_systemd_only {
    systemd-source(matches(
      "_COMM" => "systemd"
      )
    );
  };
  

  (#4245)

• date-parser(): add value() parameter to instruct date-parser() to store
  the resulting timestamp in a name-value pair, instead of changing the
  timestamp value of the LogMessage.

  datetime type representation: typed values in syslog-ng are represented as
  strings when stored as a part of a log message. syslog-ng simply remembers
  the type it was stored as. Whenever the value is used as a specific type in
  a type-aware context where we need the value of the specific type, an
  automatic string parsing takes place. This parsing happens for instance
  whenever syslog-ng stores a datetime value in MongoDB or when
  $(format-date) template function takes a name-value pair as parameter.
  The datetime() type has stored its value as the number of milliseconds since
  the epoch (1970-01-01 00:00:00 GMT). This has now been enhanced by making
  it possible to store timestamps up to nanosecond resolutions along with an
  optional timezone offset.

  $(format-date): when applied to name-value pairs with the datetime type,
  use the timezone offset if one is available.
  (#4319)

• stats: Added syslog-stats() global stats() group option.

  E.g.:

  options {
    stats(
      syslog-stats(no);
    );
  };
  

  It changes the behavior of counting messages based on different syslog-proto fields,
  like SEVERITY, FACILITY, HOST, etc...

  Possible values are:

  • yes => force enable
  • no => force disable
  • auto => let stats(level()) decide (old behavior)
    (#4337)

• kubernetes source: Added key-delimiter() option.

  Some metadata fields can contain .-s in their name. This does not work
  with syslog-ng-s macros, which by default use . as a delimiter. The added
  key-delimiter() option changes this behavior by storing the parsed
  metadata fields with a custom delimiter. In order to reach the fields, the
  accessor side has to use the new delimiter format, e.g. --key-delimiter
  option in $(format-json).
  (#4213)

Bugfixes

• Fix conditional evaluation with a dangling filter

  We've fixed a bug that caused conditional evaluation (if/else/elif) and certain logpath flags (final, fallback)
  to occasionally malfunction. The issue only happened in certain logpath constructs; examples can be found in the
  PR description.
  (#4058)

• python: Fixed a bug, where PYTHONPATH was ignored with python3.11.
  (#4298)

• disk-buffer: Fixed disk-queue file becoming corrupt when changing disk-buf-size().

  syslog-ng now continues with the originally set disk-buf-size().
  Note that changing the disk-buf-size() of an existing disk-queue was never supported,
  but could cause errors, which are fixed now.
  (#4308)

• dqtool: fix dqtool assign
  (#4355)

• example-diskq-source: Fixed failing to read the disk-queue content in some cases.
  (#4308)

• default-network-drivers(): Added support for the log-iw-size() option with a default value of 1000.
  Making it possible to adjust the log-iw-size() for the TCP/TLS based connections, when changing the max-connections() option.
  (#4328)

• apache-accesslog-parser(): fix rawrequest escaping binary characters
  (#4303)

• dqtool: Fixed dqtool cat failing to read the content in some cases.
  (#4308)

• Fixed a rare main loop related crash on FreeBSD.
  (#4262)

• Fix a warning message that was displayed incorrectly:
  "The actual number of worker threads exceeds the number of threads estimated at startup."
  (#4282)

• Fix minor memory leak related to tznames
  (#4334)

• db-parser(), grouping-by(): Fixed a crash introduced in 4.1.0.
  (#4366)

Packaging

• dbparser: libdbparser.so has been renamed to libcorrelation.so.
  (#4294)
• systemd-journal: Fixed a linker error, which occurred, when building with --with-systemd-journal=optional.
  (#4304)
  (#4302)

Notes to developers

• LogThreadedSourceDriver and Fetcher: implement source-side batching
  support on the input path by assigning a thread_id to dynamically spawned
  input threads (e.g. those spawned by LogThreadedSourceDriver) too. To
  actually improve performance the source driver should disable automatic
  closing of batches by setting auto_close_batches to FALSE and calling
  log_threaded_source_close_batch() explicitly.
  (#3969)

Other changes

• stats related options: The stats related options have been groupped to a new stats() block.

  This affects the following global options:

  • stats-freq()
  • stats-level()
  • stats-lifetime()
  • stats-max-dynamics()

  These options have been kept for backward compatibility, but they have been deprecated.

  Migrating from the old stats options to the new ones looks like this.

  @version: 4.0
  
  options {
      stats-freq(1);
      stats-level(1);
      stats-lifetime(1000);
      stats-max-dynamics(10000);
  };
  

  @version: 4.1
  
  options {
      stats(
          freq(1)
          level(1)
          lifetime(1000)
          max-dynamics(10000)
      );
  };
  

  Breaking change
  For more than a decade stats() was a deprecated alias to stats-freq(), now it is used as the name
  of the new block. If you have been using stats(xy), use stats(freq(xy)) instead.
  (#4337)

• kubernetes source: Improved error logging, when the pod was unreachable through the python API.
  (#4305)

• APT repository: Added .gz, .xz and .bz2 compression to the Packages file.
  (#4313)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Attila Szakacs, Balazs Scheidler, Bálint Horváth, Gergo Ferenc Kovacs,
Hofi, László Várady, Ronny Meeus, Szilard Parrag

4.1.0

Highlights

PROXY protocol v2 support (#4211)

We've added support for PROXY protocol v2 (transport(proxied-tcp)), a protocol
used by network load balancers, such as Amazon Elastic Load Balancer and
HAProxy, to carry original source/destination address information, as described
in https://www.haproxy.org/download/1.8/doc/proxy-protocol.txt

Metrics revised

Prometheus metric format (#4325)

A new metric system has been introduced to syslog-ng, where metrics are
identified by names and partitioned by labels, which is similar to the
Prometheus data model.

The syslog-ng-ctl stats prometheus command can be used to query syslog-ng
metrics in a format that conforms to the Prometheus text-based exposition
format.

syslog-ng-ctl stats prometheus --with-legacy-metrics displays legacy metrics
as well. Legacy metrics do not follow Prometheus' metric and label conventions.

Classification (metadata-based metrics) (#4318)

metrics-probe(), a new parser has also been added, which counts messages
passing through based on the metadata of each message. The parser creates
labeled metrics based on the fields of the message.

Both the key and labels can be set in the config, the values of the labels can
be templated. E.g.:

parser p_metrics_probe {
  metrics-probe(
    key("custom_key")  # adds "syslogng_" prefix => "syslogng_custom_key"
    labels(
      "custom_label_name_1" => "foobar"
      "custom_label_name_2" => "${.custom.field}"
    )
  );
};

With this config, it creates counters like these:

syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="bar"} 1
syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="foo"} 1
syslogng_custom_key{custom_label_name_1="foobar", custom_label_name_2="baz"} 3

The minimal config creates counters with the key
syslogng_classified_events_total and labels app, host, program and
source. E.g.:

parser p_metrics_probe {
  metrics-probe();
};

With this config, it creates counters like these:

syslogng_classified_events_total{app="example-app", host="localhost", program="baz", source="s_local_1"} 3
syslogng_classified_events_total{app="example-app", host="localhost", program="bar", source="s_local_1"} 1
syslogng_classified_events_total{app="example-app", host="localhost", program="foo", source="s_local_1"} 1

Named log paths (path ingress/egress metrics) (#4344)

It is also possible to create named log paths, for example:

log top-level {
    source(s_local);

    log inner-1 {
        filter(f_inner_1);
        destination(d_local_1);
    };

    log inner-2 {
        filter(f_inner_2);
        destination(d_local_2);
    };
};

Each named log path counts its ingress and egress messages:

syslogng_log_path_ingress{id="top-level"} 114
syslogng_log_path_ingress{id="inner-1"} 114
syslogng_log_path_ingress{id="inner-2"} 114
syslogng_log_path_egress{id="top-level"} 103
syslogng_log_path_egress{id="inner-1"} 62
syslogng_log_path_egress{id="inner-2"} 41

Note that the egress statistics only count the messages which have been have not
been filtered out from the related log path, it does care about whether there
are any destinations in it or that any destination delivers or drops the
message.

The above three features are experimental; the output of stats prometheus
(names, labels, etc.) and the metrics created by metrics-probe() and named log
paths may change in the next 2-3 releases.

Features

• $(format-date): add a new template function to format time and date values

  $(format-date [options] format-string [timestamp])

  $(format-date) takes a timestamp in the DATETIME representation and
  formats it according to an strftime() format string. The DATETIME
  representation in syslog-ng is a UNIX timestamp formatted as a decimal
  number, with an optional fractional part, where the seconds and the
  fraction of seconds are separated by a dot.

  If the timestamp argument is missing, the timestamp of the message is
  used.

  Options:
  --time-zone <TZstring> -- override timezone of the original timestamp
  (#4202)

• syslog-parser() and all syslog related sources: accept unquoted RFC5424
  SD-PARAM-VALUEs instead of rejecting them with a parse error.

  sdata-parser(): this new parser allows you to parse an RFC5424 style
  structured data string. It can be used to parse this relatively complex
  format separately.
  (#4281)

• system() source: the system() source was changed on systemd platforms to
  fetch journal messages that relate to the current boot only (e.g. similar
  to journalctl -fb) and to ignore messages generated in previous boots,
  even if those messages were succesfully stored in the journal and were not
  picked up by syslog-ng. This change was implemented as the journald access
  APIs work incorrectly if time goes backwards across reboots, which is an
  increasingly frequent event in virtualized environments and on systems that
  lack an RTC. If you want to retain the old behaviour, please bypass the
  system() source and use systemd-journal() directly, where this option
  can be customized. The change is not tied to @version as we deemed the new
  behaviour fixing an actual bug. For more information consult #2836.

  systemd-journald() source: add match-boot() and matches() options to
  allow you to constrain the collection of journal records to a subset of what
  is in the journal. match-boot() is a yes/no value that allows you to fetch
  messages that only relate to the current boot. matches() allows you to
  specify one or more filters on journal fields.

  Examples:

  source s_journal_current_boot_only {
    systemd-source(match-boot(yes));
  };
  
  source s_journal_systemd_only {
    systemd-source(matches(
      "_COMM" => "systemd"
      )
    );
  };
  

  (#4245)

• date-parser(): add value() parameter to instruct date-parser() to store
  the resulting timestamp in a name-value pair, instead of changing the
  timestamp value of the LogMessage.

  datetime type representation: typed values in syslog-ng are represented as
  strings when stored as a part of a log message. syslog-ng simply remembers
  the type it was stored as. Whenever the value is used as a specific type in
  a type-aware context where we need the value of the specific type, an
  automatic string parsing takes place. This parsing happens for instance
  whenever syslog-ng stores a datetime value in MongoDB or when
  $(format-date) template function takes a name-value pair as parameter.
  The datetime() type has stored its value as the number of milliseconds since
  the epoch (1970-01-01 00:00:00 GMT). This has now been enhanced by making
  it possible to store timestamps up to nanosecond resolutions along with an
  optional timezone offset.

  $(format-date): when applied to name-value pairs with the datetime type,
  use the timezone offset if one is available.
  (#4319)

• stats: Added syslog-stats() global stats() group option.

  E.g.:

  options {
    stats(
      syslog-stats(no);
    );
  };
  

  It changes the behavior of counting messages based on different syslog-proto fields,
  like SEVERITY, FACILITY, HOST, etc...

  Possible values are:

  • yes => force enable
  • no => force disable
  • auto => let stats(level()) decide (old behavior)
    (#4337)

• kubernetes source: Added key-delimiter() option.

  Some metadata fields can contain .-s in their name. This does not work
  with syslog-ng-s macros, which by default use . as a delimiter. The added
  key-delimiter() option changes this behavior by storing the parsed
  metadata fields with a custom delimiter. In order to reach the fields, the
  accessor side has to use the new delimiter format, e.g. --key-delimiter
  option in $(format-json).
  (#4213)

Bugfixes

• Fix conditional evaluation with a dangling filter

  We've fixed a bug that caused conditional evaluation (if/else/elif) and certain logpath flags (final, fallback)
  to occasionally malfunction. The issue only happened in certain logpath constructs; examples can be found in the
  PR description.
  (#4058)

• python: Fixed a bug, where PYTHONPATH was ignored with python3.11.
  (#4298)

• disk-buffer: Fixed disk-queue file becoming corrupt when changing disk-buf-size().

  syslog-ng now continues with the originally set disk-buf-size().
  Note that changing the disk-buf-size() of an existing disk-queue was never supported,
  but could cause errors, which are fixed now.
  (#4308)

• dqtool: fix dqtool assign
  (#4355)

• example-diskq-source: Fixed failing to read the disk-queue content in some cases.
  (#4308)

• default-network-drivers(): Added support for the log-iw-size() option with a default value of 1000.
  Making it possible to adjust the log-iw-size() for the TCP/TLS based connections, when changing the max-connections() option.
  (#4328)

• apache-accesslog-parser(): fix rawrequest escaping binary characters
  (#4303)

• dqtool: Fixed dqtool cat failing to read the content in some cases.
  (#4308)

• Fixed a rare main loop related crash on FreeBSD.
  (#4262)

• Fix a warning message that was displayed incorrectly:
  "The actual number of worker threads exceeds the number of threads estimated at startup."
  (#4282)

• Fix minor memory leak related to tznames
  (#4334)

Packaging

• dbparser: libdbparser.so has been renamed to libcorrelation.so.
  (#4294)
• systemd-journal: Fixed a linker error, which occurred, when building with --with-systemd-journal=optional.
  (#4304)
  (#4302)

Notes to developers

• LogThreadedSourceDriver and Fetcher: implement source-side batching
  support on the input path by assigning a thread_id to dynamically spawned
  input threads (e.g. those spawned by LogThreadedSourceDriver) too. To
  actually improve performance the source driver should disable automatic
  closing of batches by setting auto_close_batches to FALSE and calling
  log_threaded_source_close_batch() explicitly.
  (#3969)

Other changes

• stats related options: The stats related options have been groupped to a new stats() block.

  This affects the following global options:

  • stats-freq()
  • stats-level()
  • stats-lifetime()
  • stats-max-dynamics()

  These options have been kept for backward compatibility, but they have been deprecated.

  Migrating from the old stats options to the new ones looks like this.

  @version: 4.0
  
  options {
      stats-freq(1);
      stats-level(1);
      stats-lifetime(1000);
      stats-max-dynamics(10000);
  };
  

  @version: 4.1
  
  options {
      stats(
          freq(1)
          level(1)
          lifetime(1000)
          max-dynamics(10000)
      );
  };
  

  Breaking change
  For more than a decade stats() was a deprecated alias to stats-freq(), now it is used as the name
  of the new block. If you have been using stats(xy), use stats(freq(xy)) instead.
  (#4337)

• kubernetes source: Improved error logging, when the pod was unreachable through the python API.
  (#4305)

• APT repository: Added .gz, .xz and .bz2 compression to the Packages file.
  (#4313)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Attila Szakacs, Balazs Scheidler, Bálint Horváth, Gergo Ferenc Kovacs,
Hofi, László Várady, Ronny Meeus, Szilard Parrag

4.0.1

This is the combination of the news entries of 4.0.0 and 4.0.1.

This is a new major version of syslog-ng, ending the 3.x series which
started roughly 13 years ago, on 17th February 2009.

Like all releases in the 3.x series, 4.0.0 is not a breaking change either.
Long-term compatibility has been and continues to be an essential objective
of syslog-ng; thus, you can still run unchanged configurations that were
originally created for syslog-ng 3.0.0.

You can safely upgrade to 4.0.0 if you followed along 3.x, and you should
probably also consider upgrading if you are stuck with an older 3.x release.

The new version number primarily indicates that this version of syslog-ng is
much more than the software we released 13 years ago. While it does have
certain "big-bang" items in its feature list, new features were continuously
introduced throughout our 3.x series as well. Our engineering practices
have not changed simply because we were working on a new major release: this
is the continuation of our previous releases in every respect, produced in
the same manner, just with a more catchy version number.

For this reason, there is no separate deprecation or support period for 3.x
releases, similarly with our existing practice. We support earlier syslog-ng
releases by providing maintenance and fixes in the new release track.
Fixes to problems are not backported to earlier releases by the syslog-ng
project.

Highlights

Introduce runtime type information to name-value pairs

syslog-ng uses a data model where a log message contains an unordered set
of name-value pairs. The values stored in these name-value pairs are
usually textual, so syslog-ng has traditionally stored these values in
text format.

With the increase of JSON-based message sources and destinations, types
became more important. If we encounter a message where a name-value pair
originates from a JSON document, and this document contains a member that
is numeric, we may want to reproduce that as we send this data to a
consumer.

For example, sometimes we extract a numerical metric from a log message,
and we need to send this to a consumer, again with the correct type.

To be able to do this, we added runtime type information to the syslog-ng
message model: each name-value pair becomes a (name, type, value) triplet.

We introduced the following types:

• string: simple textual data, mostly utf8 (but not always)
• int: an integer representable by a 64 bit signed value
• double: a double precision floating point number
• boolean: true or false
• datetime: Date and Time represented by the milliseconds since epoch
• list: list of strings
• json: JSON snippet
• null: an unset value

Apart from the syslog-ng core supporting the notion of types, its use is
up to the sources, filters, rewrite rules, parsers and destinations that
set or make use of them in any way it makes the most sense for the component
in question.

Type-aware comparisons

syslog-ng uses filter expressions to make routing decisions and during the
transformation of messages. These filter expressions are used in filter
{} or if {} statements, for example.

In these expressions, you can use comparison operators. This example, for
instance, uses the '>' operator to check for HTTP response codes
greater-or-equal than 500:

     if ("${apache.response}" >= 500) {
     };

Earlier, we had two sets of operators, one for numeric (==, !=, <, >) and the
other for string-based comparisons (eq, ne, gt, lt).

The separate operators were cumbersome to use. Users often forgot which
operator was the right one for a specific case.

Typing allows us to do the right thing in most cases automatically, and a
syntax that allows the user to override the automatic decisions in the
rare case.

With that, starting with 4.0, the old-numeric operators have been
converted to be type-aware operators. It would compare as strings if both
sides of the comparisons are strings. It would compare numerically if at
least one side is numeric. A great deal of inspiration was taken from
JavaScript, which was considered to be a good model, since the problem
space is similar.

See this blog post for more details:
https://syslog-ng-future.blog/syslog-ng-4-progress-3-38-1-release/

Capture type information from JSON

When using json-parser(), syslog-ng converts all members of a JSON object
to syslog-ng name-value pairs. Prior to the introduction of type support,
these name-value pairs were all stored as strings. Any type information
originally present in the incoming JSON object was lost.

This meant that if you regenerated the JSON from the name-value pairs using
the $(format-json) template function, all numbers, booleans and other
types became strings in the output.

There has been a feature in syslog-ng that alleviated the loss of types.
This feature was called "type-hints". Type-hints tell $(format-json) to
use a specific type on output, independently of a name-value pair's
original type, but this type conversion needed to be explicit in the
configuration.

An example configuration that parses JSON on input and produces a JSON on
output:

log {
    source { ... };
    parser { json-parser(prefix('.json.')); };
    destination { file(... template("$(format-json .json.*)\n")); };
};

To augment the above with type hinting, you could use:

log {
    source { ... };
    parser { json-parser(prefix('.json.')); };
    destination { file(... template("$(format-json .json.* .json.value=int64(${.json.value})\n")); };
};

NOTE the presence of the int64() type hint in the 2nd example.

The new feature introduced with typing is that syslog-ng would
automatically store the JSON type information as a syslog-ng type, thus it
will transparently carry over types from inputs to output, without having
to be explicit about them.

Typing support for various components in syslog-ng

Typing is a feature throughout syslog-ng, and although the gust of it has
been explained in the highlights section, some further details are
documented in the list down below:

• type-aware comparisons in filter expressions: as detailed above, the
  previously numeric operators become type-aware, and the exact comparison
  performed will be based on types associated with the values we compare.

• json-parser() and $(format-json): JSON support is massively improved
  with the introduction of types. For one: type information is retained
  across input parsing->transformation->output formatting. JSON lists
  (arrays) are now supported and are converted to syslog-ng lists so they
  can be manipulated using the $(list-*) template functions. There are
  other important improvements in how we support JSON.

• set(), groupset(): in any case where we allow the use of templates,
  support for type-casting was added, and the type information is properly
  promoted.

• db-parser() type support: db-parser() gets support for type casts,
  assignments within db-parser() rules can associate types with
  values using the "type" attribute, e.g. <value name="foobar" type="integer">$PID</value>. The “integer” is a type-cast that
  associates $foobar with an integer type. db-parser()’s internal parsers
  (e.g. @NUMBER@) will also associate type information with a name-value
  pair automatically.

• add-contextual-data() type support: any new name-value pair that is
  populated using add-contextual-data() will propagate type information,
  similarly to db-parser().

• map-value-pairs() type support: propagate type information

• SQL type support: the sql() driver gained support for types, so that
  columns with specific types will be stored as those types.

• template type support: templates can now be casted explicitly to a
  specific type, but they also propagate type information from
  macros/template functions and values in the template string

• value-pairs type support: value-pairs form the backbone of specifying a
  set of name-value pairs and associated transformations to generate JSON
  or a key-value pair format. It also gained support for types, the
  existing type-hinting feature that was already part of value-pairs was
  adapted and expanded to other parts of syslog-ng.

• python() typing: support for typing was added to all Python components
  (sources, destinations, parsers and template functions), along with more
  documentation & examples on how the Python bindings work. All types except
  json() are supported as they are queried- or changed by Python code.

• on-disk serialized formats (e.g. disk buffer/logstore): we remain
  compatible with messages serialized with an earlier version of
  syslog-ng, and the format we choose remains compatible for “downgrades”
  as well. E.g. even if a new version of syslog-ng serialized a message,
  the old syslog-ng and associated tools will be able to read it (sans
  type information of course)

Improved support for lists (arrays)

For syslog-ng, everything is traditionally a string. A convention was
started with syslog-ng in v3.10, where a comma-separated format
could be used as a kind of array using the $(list-*) family of template
functions.

For example, $(list-head) takes off the first element in a list, while
$(list-tail) takes the last. You can index and slice list elements using
the $(list-slice) and $(list-nth) functions and so on.

syslog-ng has started to return such lists in various cases, so they can
be manipulated using these list-specific template functions. These
include the xml-parser(), or the $(explode) template function, but there
are others.

Here is an example that has worked since syslog-ng 3.10:

  # MSG contains foo:bar:baz
  # - the $(list-head) takes off the first element of a list
  # - the $(explode) expression splits a string at the specified separator, ':' in this case.
  $(list-head $(explode : $MSG))

New functions that improve these features:

• JSON arrays are converted to lists, making it a lot easier to slice
  and extract information from JSON arrays. Of course, $(format-json)
  will take lists and convert them back to arrays.

• The $* is a new macro that converts the internal list of match
  variables ($1, $2, $3 and so on) to a list, usable with $(list-*)
  template functions. These match variables have traditionally been
  filled by regular expressions when a capture group in a regexp
  matches.

• The set-matches() rewrite operation performs the reverse; it assigns
  the match variables to list elements, making it easier to use list
  elements in template expressions by assigning them to $1, $2, $3 and
  so on.

• Top-level JSON arrays (e.g. ones where the incoming JSON data is an
  array and not an object) are now accepted, and the array elements are
  assigned to the match variables.

Python support

syslog-ng has had support for Python-based processing elements since 3.7,
released in 2015, which was greatly expanded early 2017 (3.9, LogParser) and
late 2018 (3.18, LogSource and LogFetcher).

This support has now been improved in a number of ways to make its use both
easier and its potential more powerful.

A framework was added to syslog-ng that allows seamless implementation of
syslog-ng features in Python, with a look and feel of that of a native
implementation. An example for using this framework is available in the
modules/python-modules/example directory, as well as detailed
documentation in the form of modules/python-modules/README.md that is
installed to /etc/syslog-ng/python.

The framework consists of these changes:

• syslogng Python package: native code provided by the syslog-ng core
  has traditionally been exported in the syslogng Python module. An
  effort was made to make these native classes exported by the C layer
  more discoverable and more intuitive. As a part of this effort, the
  interfaces for all key Python components (LogSource, LogFetcher,
  LogDestination, LogParser) were exposed in the syslogng module, along
  with in-line documentation.

• /etc/syslog-ng/python: syslog-ng now automatically adds this directory to
  the PYTHONPATH so that you have an easy place to add Python modules required
  by your configuration.

• Python virtualenv support for production use: more sophisticated Python
  modules usually have 3rd party dependencies, which either needed to be
  installed from the OS repositories (using the apt-get or yum/dnf tools) or
  PyPI (using the pip tool). syslog-ng now acquired support for an embedded
  Python virtualenv (/var/lib/syslog-ng/python-venv or similar, depending on
  the installation layout), meaning that these requirements can be installed
  privately, without deploying them in the system PYTHONPATH where it might
  collide with other applications. The base set of requirements that
  syslog-ng relies on can be installed via the syslog-ng-update-virtualenv
  script, which has been added to our rpm/deb postinst scripts.

  Our mod-python module validates this virtualenv at startup and activates it
  automatically if the validation is successful. You can disable this behaviour
  by loading the Python module explicitly with the following configuration
  statement:

      @module mod-python use-virtualenv(no)
  

  You can force syslog-ng to use a specific virtualenv by activating it first,
  prior to executing syslog-ng. In this case, syslog-ng will not try to use
  its private virtualenv, rather it would use the one activated when it was
  started. It assumes that any requirements needed for syslog-ng
  functionality implemented in Python are deployed by the user. These
  requirements are listed in the /usr/lib/syslog-ng/python/requirements.txt
  file.

• SCL snippets in Python plugins: by adding an scl/whatever.conf file to
  your Python-based syslog-ng plugin, you can easily wrap a Python-based
  log processing functionality with a syslog-ng block {}, so the user can
  use a syntax very similar to native plugins in their main configuration.

• confgen in Python: should a simple block {} statement not be enough to
  wrap the functionality implemented in Python, the mod-python module now
  supports confgen functions to be implemented in Python. confgen
  has been a feature in syslog-ng for a long time that allows you to
  generate configuration snippets dynamically by executing an external
  program or script. This has now been ported to Python, e.g.
  syslog-ng can invoke a Python function to generate parts of its
  configuration.

  Example:

  @version: 4.0
  python {
  from syslogng import register_config_generator
  def generate_foobar(args):
          print(args)
          return "tcp(port(2000))"
  #
  # this registers a plugin in the "source" context named "foobar"
  # which would invoke the generate_foobar() function when a foobar() source
  # reference is encountered.
  #
  register_config_generator("source", "foobar", generate_foobar)
  };
  log {
          # we are actually calling the generate_foobar() function in this
          # source, passing all parameters as values in the "args" dictionary
          source { foobar(this(is) a(value)); };
          destination { file("logfile"); };
  };
  

Features

• kubernetes() source and kubernetes-metadata-parser(): these two
  components gained the ability to enrich log messages with Kubernetes
  metadata. When reading container logs, syslog-ng would query the Kubernetes
  API for the following fields and add them to the log-message. The returned
  meta-data is cached in memory, so not all log messages trigger a new query.

  .k8s.pod_uuid
  .k8s.labels.<label_name>
  .k8s.annotations.<annotation_name>
  .k8s.namespace_name
  .k8s.pod_name
  .k8s.container_name
  .k8s.container_image
  .k8s.container_hash
  .k8s.docker_id
  

• java() destinations: fixed compatibility with newer Java versions,
  syslog-ng is now able to compile up to Java 18.

• disk-buffer: Added prealloc() option to preallocate new disk-buffer
  files.
  (#4056)

• disk-buffer: The default value of truncate-size-ratio() has been changed to 1,
  which means truncation is disabled by default. This means that by default, the
  disk-buffer files will gradually become larger and will never reduce in size.
  This improves performance.
  (#4056)

• log-level(): added a new global option to control syslog-ng's own internal
  log level. This augments the existing support for doing the same via the
  command line (via -d, -v and -t options) and via syslog-ng-ctl. This change
  also causes higher log-levels to include messages from lower log-levels,
  e.g. "trace" also implies "debug" and "verbose". By adding this capability
  to the configuration, it becomes easier to control logging in containerized
  environments where changing command line options is more challenging.

  syslog-ng-ctl log-level: this new subcommand in syslog-ng-ctl allows
  setting the log level in a more intuitive way, compared to the existing
  syslog-ng-ctl verbose|debug|trace -s syntax.

  syslog-ng --log-level: this new command line option for the syslog-ng
  main binary allows you to set the desired log-level similar to how you
  can control it from the configuration or through syslog-ng-ctl.
  (#4091)

• network/syslog/tls context options: SSL_CONF_cmd support

  SSL_CONF_cmd TLS configuration support for network() and syslog() driver has been added.

  OpenSSL offers an alternative, software-independent configuration
  mechanism through the SSL_CONF_cmd interface to support a common
  solution for setting the so many various SSL_CTX and SSL options that
  can be set earlier via multiple, separated openssl function calls only.
  This update implements that similar to the mod_ssl in Apache.

  IMPORTANT: The newly introduced openssl-conf-cmds always has the
  highest priority, its content parsed last, so it will override any other
  options that can be found in the tls() section, does not matter if
  they appear before or after openssl-conf-cmds.

  As described in the SSL_CONF_cmd documentation, the order of operations
  within openssl-conf-cmds() is significant and the commands are executed
  in top-down order. This means that if there are multiple occurrences of
  setting the same option then the 'last wins'. This is also true for
  options that can be set multiple ways (e.g. used cipher suites and/or
  protocols).

  Example config:

  source source_name {
      network (
          ip(0.0.0.0)
          port(6666)
          transport("tls")
          tls(
              ca-dir("/etc/ca.d")
              key-file("/etc/cert.d/serverkey.pem")
              cert-file("/etc/cert.d/servercert.pem")
              peer-verify(yes)
  
              openssl-conf-cmds(
                  # For system wide available cipher suites use: /usr/bin/openssl ciphers -v
                  # For formatting rules see: https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html
                  # For quick and dirty testing try: https://github.com/rbsec/sslscan
                  #
                  "CipherString" => "ECDHE-RSA-AES128-SHA",                                   # TLSv1.2 and bellow
                  "CipherSuites" => "TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384",    # TLSv1.3+ (OpenSSl 1.1.1+)
  
                  "Options" => "PrioritizeChaCha",
                  "Protocol" => "-ALL,TLSv1.3",
              )
          )
      );
  };
  

• network/syslog/http destination: OCSP stapling support

  OCSP stapling support for network destinations and for the http() module has been added.

  When OCSP stapling verification is enabled, the server will be requested to send back OCSP status responses.
  This status response will be verified using the trust store configured by the user (ca-file(), ca-dir(), pkcs12-file()).

  Note: RFC 6961 multi-stapling and TLS 1.3-provided multiple responses are currently not validated, only the peer certificate is verified.

  Example config:

  destination {
  
      network("test.tld" transport(tls)
          tls(
              pkcs12-file("/path/to/test.p12")
              peer-verify(yes)
              ocsp-stapling-verify(yes)
          )
      );
  
      http(url("https://test.tld") method("POST") tls(peer-verify(yes) ocsp-stapling-verify(yes)));
  };
  

  (#4082)

• Python LogMessage class: get_pri() and get_timestamp() methods were added that
  allow the query of the syslog-style priority and the message timestamp,
  respectively. The return value of get_pri() is an integer, while
  get_timestamp() returns a Python datetime.datetime instance. Some macros
  that were previously unavailable from Python (e.g. the STAMP, R_STAMP and
  C_STAMP macros) are now made available.

• Python Logger: the low-level Logger class exported by syslog-ng was
  wrapped by a logging.LogHandler class so that normal Python APIs for logging
  can now be used.

• db-parser() and grouping-by(): added a prefix() option to both
  db-parser() and grouping-by() that allows specifying an extra prefix
  to be prepended to all name-value pairs that get extracted from messages
  using patterns or tags.

• csv-parser(): add a new dialect, called escape-backslash-with-sequences
  which uses "" as an escape character but also supports C-style escape
  sequences, like "\n" or "\r".

Bugfixes

• tcp(), network() or syslog() destinations: fixed a crash that could
  happen after reload when a kept-alive connection is terminated, in case
  the target server is configured using a hostname (and not an IP address)
  and that name becomes unresolvable (e.g. dropped from DNS or /etc/hosts)
  (#4044)

• python() destination: Fixed a crash, when trying to resolve the
  "R_STAMP", "P_STAMP" or "STAMP" macros from Python code.
  (#4057)

• Python LogSource & LogFetcher: a potential deadlock was fixed in
  acknowledgement tracking.

• Python LogTemplate: the use of template functions in templates
  instantiated from Python caused a crash, which has been fixed.

• grouping-by() persist-name() option: fixed a segmentation fault in the
  grammar.
  (#4180)

• $(format-json): fix a bug in the --key-delimiter option introduced in
  3.38, which causes the generated JSON to contain multiple values for the
  same key in case the key in question contains a nested object and
  key-delimiter specified is not the dot character.
  (#4127)

• add-contextual-data(): add compatibility warnings and update advise in
  case of the value field of the add-contextual-data() database contains an
  expression that resembles the new type-hinting syntax: type(value).

• syslog-ng --help screen: the output for the --help command line option has
  included sample paths to various files that contained autoconf style
  directory references (e.g. ${prefix}/etc for instance). This is now fixed,
  these paths will contain the expanded path. Fixes Debian Bug report #962839:
  https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=962839
  (#4143)

• csv-parser(): fixed the processing of the dialect() parameter, which was
  not taken into consideration.

• apache-accesslog-parser(): Apache may use backslash-style escapes in the
  request field, so support it by setting the csv-parser() dialect to
  escape-backslash-with-sequences. Also added validation that the
  rawrequest field contains a valid HTTP request and only extract verb,
  request and httpversion if this is the case.

• riemann: fixed severity levels of Riemann diagnostics messages, the error
  returned by riemann_communicate() was previously only logged at the trace
  level and was even incomplete: not covering the case where
  riemann_communicate() returns NULL.
  (#4238)

Packaging

• python: python2 support is now completely removed. syslog-ng can no
  longer be configured with --with-python=2.
  (#4057)

• python: Python 2 support is now completely removed from the syslog-ng
  functional test framework, called Light, too. Light will support only Python 3
  from now.
  (#4174)

• Python virtualenv support for development use: syslog-ng is now capable of
  using a build-time virtualenv, where all Python development tools are
  automatically deployed by the build system. You can control if you want to
  use this using the --with-python-packages configure option. There are
  three possible values for this parameter:

  • venv: denoting that you want to use the virtualenv and install
    all these requirements automatically using pip, into the venv.
  • system: meaning that you want to rely on the system Python
    without using a virtualenv. syslog-ng build scripts would install
    requirements automatically to the system Python path usually
    /usr/local/lib/pythonX.Y
  • none: disable deploying packages automatically. All
    dependencies are assumed to be present in the system Python before
    running the syslog-ng build process.

  Please note that syslog-ng has acquired quite a number of these
  development time dependencies with the growing number of functionality
  the Python binding offers, so using the system or none settings are
  considered advanced usage, meant to be used for distro packaging.

• make dist: fixed make dist of FreeBSD so that source tarballs can
  easily be produced even if running on FreeBSD.
  (#4163)

• Debian and derivatives: The syslog-ng-mod-python package is now built with python3 on the following platforms:

  • debian-stretch
  • debian-buster
  • ubuntu-bionic
    (#4057)

• dbld: Removed support for ubuntu-xenial.
  (#4057)

• dbld: Updated support from Fedora 35 to Fedora 37

• Leaner production docker image: the balabit/syslog-ng docker image stops
  pulling in logrotate and its dependencies into the image. logrotate
  recursively pulled in cron and exim4 which are inoperable within the
  image anyway and causes the image to be larger as well as increasing the
  potential attack surface.

• Debian packaging: logrotate became Suggested instead of Recommended to
  avoid installing logrotate by default.

• scl: To match the way scls are packaged in debian, we have added a syslog-ng-scl package.
  This makes it possible to upgrade from the official debian syslog-ng package to the ose-repo provided one.
  (#4252) (#4256)

Other changes

• sumologic-http() improvements

  Improved defaults: sumologic-http() originally sent incomplete
  messages (only the $MESSAGE part) to Sumo Logic by default. The new
  default is a JSON object, containing all name-value pairs. This is a
  breaking change if you used the default value as it was, but this is not
  really anticipated. To override the new message format or revert to the
  old default, the template() option can be used.

  sumologic-http() enables batching by default to significantly increase
  the destination's performance.

  The tls() block has become optional, Sumo Logic servers will be
  verified using the system's certificate store by default.
  (#4124)

Installation packages

• Debian/Ubuntu Packages
  https://github.com/syslog-ng/syslog-ng#debianubuntu

• RedHat, CentOS and Fedora Packages
  https://www.syslog-ng.com/community/b/blog/posts/rpm-packages-from-syslog-ng-git-head/

• docker image: Nightly production docker images are now available as balabit/syslog-ng:nightly
  (#4117)

• docker image: added jemalloc to the production image, which improves
  performance, decreases memory fragmentation and makes syslog-ng to
  return memory to the system much more aggressively.

• Removed support for Debian stretch.

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Andras Mitzki, Attila Szakacs, Attila Szalay, Balazs Scheidler, Bálint
Horváth, Gabor Nagy, István Hoffmann, Joshua Root, László Várady, Szilárd
Parrag

4.0.0

This is a new major version of syslog-ng, ending the 3.x series which
started roughly 13 years ago, on 17th February 2009.

Like all releases in the 3.x series, 4.0.0 is not a breaking change either.
Long-term compatibility has been and continues to be an essential objective
of syslog-ng; thus, you can still run unchanged configurations that were
originally created for syslog-ng 3.0.0.

You can safely upgrade to 4.0.0 if you followed along 3.x, and you should
probably also consider upgrading if you are stuck with an older 3.x release.

The new version number primarily indicates that this version of syslog-ng is
much more than the software we released 13 years ago. While it does have
certain "big-bang" items in its feature list, new features were continuously
introduced throughout our 3.x series as well. Our engineering practices
have not changed simply because we were working on a new major release: this
is the continuation of our previous releases in every respect, produced in
the same manner, just with a more catchy version number.

For this reason, there is no separate deprecation or support period for 3.x
releases, similarly with our existing practice. We support earlier syslog-ng
releases by providing maintenance and fixes in the new release track.
Fixes to problems are not backported to earlier releases by the syslog-ng
project.

Highlights

Introduce runtime type information to name-value pairs

syslog-ng uses a data model where a log message contains an unordered set
of name-value pairs. The values stored in these name-value pairs are
usually textual, so syslog-ng has traditionally stored these values in
text format.

With the increase of JSON-based message sources and destinations, types
became more important. If we encounter a message where a name-value pair
originates from a JSON document, and this document contains a member that
is numeric, we may want to reproduce that as we send this data to a
consumer.

For example, sometimes we extract a numerical metric from a log message,
and we need to send this to a consumer, again with the correct type.

To be able to do this, we added runtime type information to the syslog-ng
message model: each name-value pair becomes a (name, type, value) triplet.

We introduced the following types:

• string: simple textual data, mostly utf8 (but not always)
• int: an integer representable by a 64 bit signed value
• double: a double precision floating point number
• boolean: true or false
• datetime: Date and Time represented by the milliseconds since epoch
• list: list of strings
• json: JSON snippet
• null: an unset value

Apart from the syslog-ng core supporting the notion of types, its use is
up to the sources, filters, rewrite rules, parsers and destinations that
set or make use of them in any way it makes the most sense for the component
in question.

Type-aware comparisons

syslog-ng uses filter expressions to make routing decisions and during the
transformation of messages. These filter expressions are used in filter
{} or if {} statements, for example.

In these expressions, you can use comparison operators. This example, for
instance, uses the '>' operator to check for HTTP response codes
greater-or-equal than 500:

     if ("${apache.response}" >= 500) {
     };

Earlier, we had two sets of operators, one for numeric (==, !=, <, >) and the
other for string-based comparisons (eq, ne, gt, lt).

The separate operators were cumbersome to use. Users often forgot which
operator was the right one for a specific case.

Typing allows us to do the right thing in most cases automatically, and a
syntax that allows the user to override the automatic decisions in the
rare case.

With that, starting with 4.0, the old-numeric operators have been
converted to be type-aware operators. It would compare as strings if both
sides of the comparisons are strings. It would compare numerically if at
least one side is numeric. A great deal of inspiration was taken from
JavaScript, which was considered to be a good model, since the problem
space is similar.

See this blog post for more details:
https://syslog-ng-future.blog/syslog-ng-4-progress-3-38-1-release/

Capture type information from JSON

When using json-parser(), syslog-ng converts all members of a JSON object
to syslog-ng name-value pairs. Prior to the introduction of type support,
these name-value pairs were all stored as strings. Any type information
originally present in the incoming JSON object was lost.

This meant that if you regenerated the JSON from the name-value pairs using
the $(format-json) template function, all numbers, booleans and other
types became strings in the output.

There has been a feature in syslog-ng that alleviated the loss of types.
This feature was called "type-hints". Type-hints tell $(format-json) to
use a specific type on output, independently of a name-value pair's
original type, but this type conversion needed to be explicit in the
configuration.

An example configuration that parses JSON on input and produces a JSON on
output:

log {
    source { ... };
    parser { json-parser(prefix('.json.')); };
    destination { file(... template("$(format-json .json.*)\n")); };
};

To augment the above with type hinting, you could use:

log {
    source { ... };
    parser { json-parser(prefix('.json.')); };
    destination { file(... template("$(format-json .json.* .json.value=int64(${.json.value})\n")); };
};

NOTE the presence of the int64() type hint in the 2nd example.

The new feature introduced with typing is that syslog-ng would
automatically store the JSON type information as a syslog-ng type, thus it
will transparently carry over types from inputs to output, without having
to be explicit about them.

Typing support for various components in syslog-ng

Typing is a feature throughout syslog-ng, and although the gust of it has
been explained in the highlights section, some further details are
documented in the list down below:

• type-aware comparisons in filter expressions: as detailed above, the
  previously numeric operators become type-aware, and the exact comparison
  performed will be based on types associated with the values we compare.

• json-parser() and $(format-json): JSON support is massively improved
  with the introduction of types. For one: type information is retained
  across input parsing->transformation->output formatting. JSON lists
  (arrays) are now supported and are converted to syslog-ng lists so they
  can be manipulated using the $(list-*) template functions. There are
  other important improvements in how we support JSON.

• set(), groupset(): in any case where we allow the use of templates,
  support for type-casting was added, and the type information is properly
  promoted.

• db-parser() type support: db-parser() gets support for type casts,
  assignments within db-parser() rules can associate types with
  values using the "type" attribute, e.g. <value name="foobar" type="integer">$PID</value>. The “integer” is a type-cast that
  associates $foobar with an integer type. db-parser()’s internal parsers
  (e.g. @NUMBER@) will also associate type information with a name-value
  pair automatically.

• add-contextual-data() type support: any new name-value pair that is
  populated using add-contextual-data() will propagate type information,
  similarly to db-parser().

• map-value-pairs() type support: propagate type information

• SQL type support: the sql() driver gained support for types, so that
  columns with specific types will be stored as those types.

• template type support: templates can now be casted explicitly to a
  specific type, but they also propagate type information from
  macros/template functions and values in the template string

• value-pairs type support: value-pairs form the backbone of specifying a
  set of name-value pairs and associated transformations to generate JSON
  or a key-value pair format. It also gained support for types, the
  existing type-hinting feature that was already part of value-pairs was
  adapted and expanded to other parts of syslog-ng.

• python() typing: support for typing was added to all Python components
  (sources, destinations, parsers and template functions), along with more
  documentation & examples on how the Python bindings work. All types except
  json() are supported as they are queried- or changed by Python code.

• on-disk serialized formats (e.g. disk buffer/logstore): we remain
  compatible with messages serialized with an earlier version of
  syslog-ng, and the format we choose remains compatible for “downgrades”
  as well. E.g. even if a new version of syslog-ng serialized a message,
  the old syslog-ng and associated tools will be able to read it (sans
  type information of course)

Improved support for lists (arrays)

For syslog-ng, everything is traditionally a string. A convention was
started with syslog-ng in v3.10, where a comma-separated format
could be used as a kind of array using the $(list-*) family of template
functions.

For example, $(list-head) takes off the first element in a list, while
$(list-tail) takes the last. You can index and slice list elements using
the $(list-slice) and $(list-nth) functions and so on.

syslog-ng has started to return such lists in various cases, so they can
be manipulated using these list-specific template functions. These
include the xml-parser(), or the $(explode) template function, but there
are others.

Here is an example that has worked since syslog-ng 3.10:

  # MSG contains foo:bar:baz
  # - the $(list-head) takes off the first element of a list
  # - the $(explode) expression splits a string at the specified separator, ':' in this case.
  $(list-head $(explode : $MSG))

New functions that improve these features:

• JSON arrays are converted to lists, making it a lot easier to slice
  and extract information from JSON arrays. Of course, $(format-json)
  will take lists and convert them back to arrays.

• The $* is a new macro that converts the internal list of match
  variables ($1, $2, $3 and so on) to a list, usable with $(list-*)
  template functions. These match variables have traditionally been
  filled by regular expressions when a capture group in a regexp
  matches.

• The set-matches() rewrite operation performs the reverse; it assigns
  the match variables to list elements, making it easier to use list
  elements in template expressions by assigning them to $1, $2, $3 and
  so on.

• Top-level JSON arrays (e.g. ones where the incoming JSON data is an
  array and not an object) are now accepted, and the array elements are
  assigned to the match variables.

Python support

syslog-ng has had support for Python-based processing elements since 3.7,
released in 2015, which was greatly expanded early 2017 (3.9, LogParser) and
late 2018 (3.18, LogSource and LogFetcher).

This support has now been improved in a number of ways to make its use both
easier and its potential more powerful.

A framework was added to syslog-ng that allows seamless implementation of
syslog-ng features in Python, with a look and feel of that of a native
implementation. An example for using this framework is available in the
modules/python-modules/example directory, as well as detailed
documentation in the form of modules/python-modules/README.md that is
installed to /etc/syslog-ng/python.

The framework consists of these changes:

• syslogng Python package: native code provided by the syslog-ng core
  has traditionally been exported in the syslogng Python module. An
  effort was made to make these native classes exported by the C layer
  more discoverable and more intuitive. As a part of this effort, the
  interfaces for all key Python components (LogSource, LogFetcher,
  LogDestination, LogParser) were exposed in the syslogng module, along
  with in-line documentation.

• /etc/syslog-ng/python: syslog-ng now automatically adds this directory to
  the PYTHONPATH so that you have an easy place to add Python modules required
  by your configuration.

• Python virtualenv support for production use: more sophisticated Python
  modules usually have 3rd party dependencies, which either needed to be
  installed from the OS repositories (using the apt-get or yum/dnf tools) or
  PyPI (using the pip tool). syslog-ng now acquired support for an embedded
  Python virtualenv (/var/lib/syslog-ng/python-venv or similar, depending on
  the installation layout), meaning that these requirements can be installed
  privately, without deploying them in the system PYTHONPATH where it might
  collide with other applications. The base set of requirements that
  syslog-ng relies on can be installed via the syslog-ng-update-virtualenv
  script, which has been added to our rpm/deb postinst scripts.

  Our mod-python module validates this virtualenv at startup and activates it
  automatically if the validation is successful. You can disable this behaviour
  by loading the Python module explicitly with the following configuration
  statement:

      `@module mod-python use-virtualenv(no)`
  

  You can force syslog-ng to use a specific virtualenv by activating it first,
  prior to executing syslog-ng. In this case, syslog-ng will not try to use
  its private virtualenv, rather it would use the one activated when it was
  started. It assumes that any requirements needed for syslog-ng
  functionality implemented in Python are deployed by the user. These
  requirements are listed in the /usr/lib/syslog-ng/python/requirements.txt
  file.

• SCL snippets in Python plugins: by adding an scl/whatever.conf file to
  your Python-based syslog-ng plugin, you can easily wrap a Python-based
  log processing functionality with a syslog-ng block {}, so the user can
  use a syntax very similar to native plugins in their main configuration.

• confgen in Python: should a simple block {} statement not be enough to
  wrap the functionality implemented in Python, the mod-python module now
  supports confgen functions to be implemented in Python. confgen
  has been a feature in syslog-ng for a long time that allows you to
  generate configuration snippets dynamically by executing an external
  program or script. This has now been ported to Python, e.g.
  syslog-ng can invoke a Python function to generate parts of its
  configuration.

  Example:

  @version: 4.0
  python {
  from syslogng import register_config_generator
  def generate_foobar(args):
          print(args)
          return "tcp(port(2000))"
  #
  # this registers a plugin in the "source" context named "foobar"
  # which would invoke the generate_foobar() function when a foobar() source
  # reference is encountered.
  #
  register_config_generator("source", "foobar", generate_foobar)
  };
  log {
          # we are actually calling the generate_foobar() function in this
          # source, passing all parameters as values in the "args" dictionary
          source { foobar(this(is) a(value)); };
          destination { file("logfile"); };
  };
  

Features

• kubernetes() source and kubernetes-metadata-parser(): these two
  components gained the ability to enrich log messages with Kubernetes
  metadata. When reading container logs, syslog-ng would query the Kubernetes
  API for the following fields and add them to the log-message. The returned
  meta-data is cached in memory, so not all log messages trigger a new query.

  .k8s.pod_uuid
  .k8s.labels.<label_name>
  .k8s.annotations.<annotation_name>
  .k8s.namespace_name
  .k8s.pod_name
  .k8s.container_name
  .k8s.container_image
  .k8s.container_hash
  .k8s.docker_id
  

• java() destinations: fixed compatibility with newer Java versions,
  syslog-ng is now able to compile up to Java 18.

• disk-buffer: Added prealloc() option to preallocate new disk-buffer
  files.
  (#4056)

• disk-buffer: The default value of truncate-size-ratio() has been changed to 1,
  which means truncation is disabled by default. This means that by default, the
  disk-buffer files will gradually become larger and will never reduce in size.
  This improves performance.
  (#4056)

• log-level(): added a new global option to control syslog-ng's own internal
  log level. This augments the existing support for doing the same via the
  command line (via -d, -v and -t options) and via syslog-ng-ctl. This change
  also causes higher log-levels to include messages from lower log-levels,
  e.g. "trace" also implies "debug" and "verbose". By adding this capability
  to the configuration, it becomes easier to control logging in containerized
  environments where changing command line options is more challenging.

  syslog-ng-ctl log-level: this new subcommand in syslog-ng-ctl allows
  setting the log level in a more intuitive way, compared to the existing
  syslog-ng-ctl verbose|debug|trace -s syntax.

  syslog-ng --log-level: this new command line option for the syslog-ng
  main binary allows you to set the desired log-level similar to how you
  can control it from the configuration or through syslog-ng-ctl.
  (#4091)

• network/syslog/tls context options: SSL_CONF_cmd support

  SSL_CONF_cmd TLS configuration support for network() and syslog() driver has been added.

  OpenSSL offers an alternative, software-independent configuration
  mechanism through the SSL_CONF_cmd interface to support a common
  solution for setting the so many various SSL_CTX and SSL options that
  can be set earlier via multiple, separated openssl function calls only.
  This update implements that similar to the mod_ssl in Apache.

  IMPORTANT: The newly introduced openssl-conf-cmds always has the
  highest priority, its content parsed last, so it will override any other
  options that can be found in the tls() section, does not matter if
  they appear before or after openssl-conf-cmds.

  As described in the SSL_CONF_cmd documentation, the order of operations
  within openssl-conf-cmds() is significant and the commands are executed
  in top-down order. This means that if there are multiple occurrences of
  setting the same option then the 'last wins'. This is also true for
  options that can be set multiple ways (e.g. used cipher suites and/or
  protocols).

  Example config:

  source source_name {
      network (
          ip(0.0.0.0)
          port(6666)
          transport("tls")
          tls(
              ca-dir("/etc/ca.d")
              key-file("/etc/cert.d/serverkey.pem")
              cert-file("/etc/cert.d/servercert.pem")
              peer-verify(yes)
  
              openssl-conf-cmds(
                  # For system wide available cipher suites use: /usr/bin/openssl ciphers -v
                  # For formatting rules see: https://www.openssl.org/docs/man1.1.1/man3/SSL_CONF_cmd.html
                  # For quick and dirty testing try: https://github.com/rbsec/sslscan
                  #
                  "CipherString" => "ECDHE-RSA-AES128-SHA",                                   # TLSv1.2 and bellow
                  "CipherSuites" => "TLS_CHACHA20_POLY1305_SHA256:TLS_AES_256_GCM_SHA384",    # TLSv1.3+ (OpenSSl 1.1.1+)
  
                  "Options" => "PrioritizeChaCha",
                  "Protocol" => "-ALL,TLSv1.3",
              )
          )
      );
  };
  

• network/syslog/http destination: OCSP stapling support

  OCSP stapling support for network destinations and for the http() module has been added.

  When OCSP stapling verification is enabled, the server will be requested to send back OCSP status responses.
  This status response will be verified using the trust store configured by the user (ca-file(), ca-dir(), pkcs12-file()).

  Note: RFC 6961 multi-stapling and TLS 1.3-provided multiple responses are currently not validated, only the peer certificate is verified.

  Example config:

  destination {
  
      network("test.tld" transport(tls)
          tls(
              pkcs12-file("/path/to/test.p12")
              peer-verify(yes)
              ocsp-stapling-verify(yes)
          )
      );
  
      http(url("https://test.tld") method("POST") tls(peer-verify(yes) ocsp-stapling-verify(yes)));
  };
  

  (#4082)

• Python LogMessage class: get_pri() and get_timestamp() methods were added that
  allow the query of the syslog-style priority and the message timestamp,
  respectively. The return value of get_pri() is an integer, while
  get_timestamp() returns a Python datetime.datetime instance. Some macros
  that were previously unavailable from Python (e.g. the STAMP, R_STAMP and
  C_STAMP macros) are now made available.

• Python Logger: the low-level Logger class exported by syslog-ng was
  wrapped by a logging.LogHandler class so that normal Python APIs for logging
  can now be used.

• db-parser() and grouping-by(): added a prefix() option to both
  db-parser() and grouping-by() that allows specifying an extra prefix
  to be prepended to all name-value pairs that get extracted from messages
  using patterns or tags.

• csv-parser(): add a new dialect, called escape-backslash-with-sequences
  which uses "" as an escape character but also supports C-style escape
  sequences, like "\n" or "\r".

Bugfixes

• tcp(), network() or syslog() destinations: fixed a crash that could
  happen after reload when a kept-alive connection is terminated, in case
  the target server is configured using a hostname (and not an IP address)
  and that name becomes unresolvable (e.g. dropped from DNS or /etc/hosts)
  (#4044)

• python() destination: Fixed a crash, when trying to resolve the
  "R_STAMP", "P_STAMP" or "STAMP" macros from Python code.
  (#4057)

• Python LogSource & LogFetcher: a potential deadlock was fixed in
  acknowledgement tracking.

• Python LogTemplate: the use of template functions in templates
  instantiated from Python caused a crash, which has been fixed.

• grouping-by() persist-name() option: fixed a segmentation fault in the
  grammar.
  (#4180)

• $(format-json): fix a bug in the --key-delimiter option introduced in
  3.38, which causes the generated JSON to contain multiple values for the
  same key in case the key in question contains a nested object and
  key-delimiter specified is not the dot character.
  (#4127)

• add-contextual-data(): add compatibility warnings and update advise in
  case of the value field of the add-contextual-data() database contains an
  expression that resembles the new type-hinting syntax: type(value).

• syslog-ng --help screen: the output for the --help command line option has
  included sample paths to various files that contained autoconf style
  directory references (e.g. ${prefix}/etc for instance). This is now fixed,
  these paths will contain the expanded path. Fixes Debian Bug report #962839:
  https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=962839
  (#4143)

• csv-parser(): fixed the processing of the dialect() parameter, which was
  not taken into consideration.

• apache-accesslog-parser(): Apache may use backslash-style escapes in the
  request field, so support it by setting the csv-parser() dialect to
  escape-backslash-with-sequences. Also added validation that the
  rawrequest field contains a valid HTTP request and only extract verb,
  request and httpversion if this is the case.

• riemann: fixed severity levels of Riemann diagnostics messages, the error
  returned by riemann_communicate() was previously only logged at the trace
  level and was even incomplete: not covering the case where
  riemann_communicate() returns NULL.
  (#4238)

Packaging

• python: python2 support is now completely removed. syslog-ng can no
  longer be configured with --with-python=2.
  (#4057)

• python: Python 2 support is now completely removed from the syslog-ng
  functional test framework, called Light, too. Light will support only Python 3
  from now.
  (#4174)

• Python virtualenv support for development use: syslog-ng is now capable of
  using a build-time virtualenv, where all Python development tools are
  automatically deployed by the build system. You can control if you want to
  use this using the --with-python-packages configure option. There are
  three possible values for this parameter:

  • venv: denoting that you want to use the virtualenv and install
    all these requirements automatically using pip, into the venv.
  • system: meaning that you want to rely on the system Python
    without using a virtualenv. syslog-ng build scripts would install
    requirements automatically to the system Python path usually
    /usr/local/lib/pythonX.Y
  • none: disable deploying packages automatically. All
    dependencies are assumed to be present in the system Python before
    running the syslog-ng build process.

  Please note that syslog-ng has acquired quite a number of these
  development time dependencies with the growing number of functionality
  the Python binding offers, so using the system or none settings are
  considered advanced usage, meant to be used for distro packaging.

• make dist: fixed make dist of FreeBSD so that source tarballs can
  easily be produced even if running on FreeBSD.
  (#4163)

• Debian and derivatives: The syslog-ng-mod-python package is now built with python3 on the following platforms:

  • debian-stretch
  • debian-buster
  • ubuntu-bionic
    (#4057)

• dbld: Removed support for ubuntu-xenial.
  (#4057)

• dbld: Updated support from Fedora 35 to Fedora 37

• Leaner production docker image: the balabit/syslog-ng docker image stops
  pulling in logrotate and its dependencies into the image. logrotate
  recursively pulled in cron and exim4 which are inoperable within the
  image anyway and causes the image to be larger as well as increasing the
  potential attack surface.

• Debian packaging: logrotate became Suggested instead of Recommended to
  avoid installing logrotate by default.

Other changes

• sumologic-http() improvements

  Improved defaults: sumologic-http() originally sent incomplete
  messages (only the $MESSAGE part) to Sumo Logic by default. The new
  default is a JSON object, containing all name-value pairs. This is a
  breaking change if you used the default value as it was, but this is not
  really anticipated. To override the new message format or revert to the
  old default, the template() option can be used.

  sumologic-http() enables batching by default to significantly increase
  the destination's performance.

  The tls() block has become optional, Sumo Logic servers will be
  verified using the system's certificate store by default.
  (#4124)

Installation packages

• Debian/Ubuntu Packages
  https://github.com/syslog-ng/syslog-ng#debianubuntu

• RedHat, CentOS and Fedora Packages
  https://www.syslog-ng.com/community/b/blog/posts/rpm-packages-from-syslog-ng-git-head/

• docker image: Nightly production docker images are now available as balabit/syslog-ng:nightly
  (#4117)

• docker image: added jemalloc to the production image, which improves
  performance, decreases memory fragmentation and makes syslog-ng to
  return memory to the system much more aggressively.

• Removed support for Debian stretch.

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Andras Mitzki, Attila Szakacs, Attila Szalay, Balazs Scheidler, Bálint
Horváth, Gabor Nagy, István Hoffmann, Joshua Root, László Várady, Szilárd
Parrag

3.38.1

Highlights

Sneak peek into syslog-ng v4.0

syslog-ng v4.0 is right around the corner.

This release (v3.38.1) contains all major changes, however, they are
currently all hidden behind a feature flag.
To enable and try those features, you need to specify @version: 4.0 at the
top of the configuration file.

You can find out more about the 4.0 changes and features here.

Read our practical introduction to typing at
syslog-ng-future.blog.

Features

• grouping-by(): added inject-mode(aggregate-only)

  This inject mode will drop individual messages that make up the correlation
  context (key() groups) and would only yield the aggregate messages
  (e.g. the results of the correlation).
  (#3998)

• add-contextual-data(): add support for type propagation, e.g. set the
  type of name-value pairs as they are created/updated to the value returned
  by the template expression that we use to set the value.

  The 3rd column in the CSV file (e.g. the template expression) now supports
  specifying a type-hint, in the format of "type-hint(template-expr)".

  Example line in the CSV database:

  selector-value,name-value-pair-to-be-created,list(foo,bar,baz)
  (#4051)

• $(format-json): add --key-delimiter option to reconstruct JSON objects
  using an alternative structure separator, that was created using the
  key-delimiter() option of json-parser().
  (#4093)

• json-parser(): add key-delimiter() option to extract JSON structure
  members into name-value pairs, so that the names are flattened using the
  character specified, instead of dot.

  Example:
  Input: {"foo":{"key":"value"}}

  Using json-parser() without key-delimiter() this is extracted to:

    foo.key="value"
  

  Using json-parser(key-delimiter("~")) this is extracted to:

    foo~key="value"
  

  This feature is useful in case the JSON keys contain dots themselves, in
  those cases the syslog-ng representation is ambigious.
  (#4093)

Bugfixes

• Fixed buffer handling of syslog and timestamp parsers (CVE-2022-38725)

  Multiple buffer out-of-bounds issues have been fixed, which could cause
  hangs, high CPU usage, or other undefined behavior.
  (#4110)

• Fixed building with LibreSSL
  (#4081)

• network(): Fixed a bug, where syslog-ng halted the input instead of skipping a character
  in case of a character conversion error.
  (#4084)

• redis(): Fixed bug where using redis driver without the batch-lines option caused program crash.
  (#4114)

• pdbtool: fix a SIGABRT on FreeBSD that was triggered right before pdbtool
  exits. Apart from being an ugly crash that produces a core file,
  functionally the tool behaved correctly and this case does not affect
  syslog-ng itself.
  (#4037)

• regexp-parser(): due to a change introduced in 3.37, named capture groups
  are stored indirectly in the LogMessage to avoid copying of the value. In
  this case the name-value pair created with the regexp is only stored as a
  reference (name + length of the original value), which improves performance
  and makes such name-value pairs use less memory. One omission in the
  original change in 3.37 is that syslog-ng does not allow builtin values to
  be stored indirectly (e.g. $MESSAGE and a few of others) and this case
  causes an assertion to fail and syslog-ng to crash with a SIGABRT. This
  abort is now fixed. Here's a sample config that reproduces the issue:

  regexp-parser(patterns('(?<MESSAGE>.*)'));
  

  (#4043)

• set-tag: fix cloning issue when string literal were used (see #4062)
  (#4065)

• add-contextual-data(): fix high memory usage when using large CSV files
  (#4067)

Other changes

• The json-c library is no longer bundled in the syslog-ng source tarball

  Since all known OS package managers provide json-c packages nowadays, the json-c
  submodule has been removed from the source tarball.

  The --with-jsonc=internal option of the configure script has been removed
  accordingly, system libraries will be used instead. For special cases, the JSON
  support can be disabled by specifying --with-jsonc=no.
  (#4078)

• platforms: Dropped support for ubuntu-impish as it became EOL
  (#4088)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Alvin Šipraga, Andras Mitzki, Attila Szakacs, Balazs Scheidler,
Bálint Horváth, Daniel Klauer, Fabrice Fontaine, Gabor Nagy,
HenryTheSir, László Várady, Parrag Szilárd, Peter Kokai, Shikhar Vashistha,
Szilárd Parrag, Vivin Peris

3.37.1

Highlights

• kubernetes source: A new source for Kubernetes CRI (Container Runtime Interface) format.
  By default it tails the /var/log/containers folder which can be overriden with the base-dir() parameter.
  Example configuration:

  source {
    kubernetes();
    # or specifying the directory:
    # kubernetes(base-dir("/dir/to/tail"));
  };
  

  (#4015)
• mariadb-audit-parser: A new parser for mariadb/mysql audit plugin logs have been added.
  The parser supports the syslog output type's format, see mariadb page for details.
  (#3947)

Features

• internal(): add rcptid tag to all trace messages that relate to incoming
  log messages. This makes it easier to correlate parsing, rewriting and
  routing actions with incoming log messages.
  (#3972)

• syslog-parser(): allow comma (e.g. ',') to separate the seconds and the fraction of a
  second part as some devices use that character. This change applies to both
  to syslog-parser() and the builtin syslog parsing functionality of network
  source drivers (e.g. udp(), tcp(), network() and syslog()).
  (#3949)

• cisco-parser: add ISO 8601 timestamp support
  (#3934)

• network(), syslog() sources and destinations: added new TLS options sigalgs() and client-sigalgs()

  They can be used to restrict which signature/hash pairs can be used in digital signatures.
  It sets the "signature_algorithms" extension specified in RFC5246 and RFC8446.

  Example configuration:

  destination {
      network("test.host" port(4444) transport(tls)
          tls(
              pkcs12-file("/path/to/tls/test.p12")
              peer-verify(yes)
              sigalgs("RSA-PSS+SHA256:ed25519")
          )
      );
  };
  

  (#4000)

• set-matches() and unset-matches(): these new rewrite operations allow
  the setting of match variables ($1, $2, ...) in a single operation, based
  on a syslog-ng list expression.
  Example:

  # set $1, $2 and $3 respectively
  set-matches("foo,bar,baz");
  
  # likewise, but using a list function
  set-matches("$(explode ':' 'foo:bar:baz')");
  

  (#3948)

• $* macro: the $* macro in template expressions convert the match variables
  (e.g. $1, $2, ...) into a syslog-ng list that can be further manipulated
  using the list template functions, or turned into a list in type-aware
  destinations.
  (#3948)

• set-tag(): add support for using template expressions in set-tag() rewrite
  operations, which makes it possible to use tag names that include macro
  references.
  (#3962)

Bugfixes

• http() and other threaded destinations: fix $SEQNUM processing so that
  only local messages get an associated $SEQNUM, just like normal
  syslog()-like destinations. This avoids a [meta sequenceId="XXX"] SD-PARAM
  being added to $SDATA for non-local messages.
  (#3928)
• grouping-by(): fix grouping-by() use through parser references.
  Originally if a grouping-by() was part of a named parser statement and was
  referenced from multiple log statements, only the first grouping-by()
  instance behaved properly, 2nd and subsequent references were ignoring all
  configuration options and have reverted using defaults instead.
  (#3957)
• db-parser(): similarly to grouping-by(), db-parser() also had issues
  propagating some of its options to 2nd and subsequent references of a parser
  statement. This includes drop-unmatched(), program-template() and
  template() options.
  (#3957)
• match(), subst() and regexp-parser(): fixed storing of numbered
  (e.g. $1,$2, $3 and so on) and named capture groups in regular expressions
  in case the input of the regexp is the same as one of the match variables being
  stored. In some cases the output of the regexp was clobbered and an invalid
  value stored.
  (#3948)
• fix threaded(no) related crash: if threaded mode is disabled for
  asynchronous sources and destinations (all syslog-like drivers such as
  tcp/udp/syslog/network qualify), a use-after-free condition can happen due
  to a reference counting bug in the non-threaded code path. The
  threaded(yes) setting has been the default since 3.6.1 so if you are using
  a more recent version, you are most probably unaffected. If you are using
  threaded(no) a use-after-free condition happens as the connection closes.
  The problem is more likely to surface on 32 bit platforms due to pointer
  sizes and struct layouts where this causes a NULL pointer dereference.
  (#3997)
• set(): make sure that template formatting options (such as time-zone() or
  frac-digits()) are propagated to all references of the rewrite rule
  containing a set(). Previously the clone() operation used to implement
  multiple references missed the template related options while cloning set(),
  causing template formatting options to be set differently, depending on
  where the set() was referenced from.
  (#3962)
• csv-parser(): fix flags(strip-whitespace) and null-value handling
  for greedy column
  (#4028)

Other changes

• java()/python() destinations: the $SEQNUM macro (and "seqnum" attribute in
  Python) was erroneously for both local and non-local logs, while it should
  have had a value only in case of local logs to match RFC5424 behavior
  (section 7.3.1). This bug is now fixed, but that means that all non-local
  logs will have $SEQNUM set to zero from this version on, e.g. the $SEQNUM
  macro would expand to an string, to match the syslog() driver behaviour.
  (#3928)
• dbld: add support for Fedora 35 in favour of Fedora 33
  (#3933)
• debian: fix logrotate file not doing the file rotation. (The path and command was invalid.)
  (#4031)
• OpenSSL: add support for OpenSSL 3.0
  (#4012)
• The MD4 hash function ($(md4)) is no longer available when compiling syslog-ng with OpenSSL v3.0.
  MD4 is now deprecated, it will be removed completely in future versions.
  (#4012)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Andras Mitzki, Attila Szakacs, Balazs Scheidler, Ben Burrows,
Fᴀʙɪᴇɴ Wᴇʀɴʟɪ, Gabor Nagy, László Várady, mohitvaid,
Parrag Szilárd, Peter Kokai, Peter Viskup, Roffild,
Ryan Faircloth, Scott Parlane, Zoltan Pallagi

3.29.1

Highlights

• panos-parser(): parse Palo Alto PAN-OS logs

  Example:

  @include "scl.conf"
  
  log {
    source { network(transport("udp")); };
  
    parser { panos-parser(); };
  
    destination {
     elasticsearch-http(
       index("syslog-ng-${YEAR}-${MONTH}-${DAY}")
       type("")
       url("http://localhost:9200/_bulk")
       template("$(format-json
         --scope rfc5424
         --scope dot-nv-pairs --rekey .* --shift 1 --exclude *future_* --exclude *dg_hier_level_*
         --scope nv-pairs --exclude DATE --key ISODATE @timestamp=${ISODATE})")
     );
    };
  };
  

  (#3234)

Features

• snmptrap: improve error message when missing dependency
  (#3363)

• disk queue: reduce memory usage during load
  (#3352)

• Allow dupnames flag to be used in PCRE expressions, allowing duplicate names for named subpatterns
  as explained here: https://www.pcre.org/original/doc/html/pcrepattern.html#SEC16 .

  Example:

  filter f_filter1 {
    match("(?<FOOBAR>bar)|(?<FOOBAR>foo)" value(MSG) flags(store-matches, dupnames));
  };
  

  (#3381)

Bugfixes

• filter/regex: if there was a named match (?..)? that is optional to match, the previose or the next named matches might not be saved as named match.
  (#3393)

• tls: Fixed a bug, where ecdh-curve-list() were not applied at client side.
  (#3356)

• scratch-buffers: fix global.scratch_buffers_bytes.queued counter bug
  This bug only affected the stats_counter value, not the actual memory usage (i.e. memory usage was fine before)
  (#3355)

• wsl: fix infinite loop during startup
  (#3340)

• openbsd: showing grammar debug info for openbsd too, when -y command line option is used
  (#3339)

• stats-query: speedup syslog-ng-ctl query get "*" command.

  An algorithmic error view made syslog-ng-ctl query get "*" very slow with large number of counters.
  (#3376)

• syslogformat: fixing crashing with small invalid formatted logs see example in #3328
  (#3364)

• cfg: fix config reload crash via introducing on_config_inited in LogPipe
  (#3176)

• config: fix error reporting

  • Error reporting was fixed for lines longer than 1024 characters.
  • The location of the error was incorrectly reported in some cases.
    (#3383)

• disk queue: fix possible crash during load, and possible false positive corruption detection
  (#3342)

• db-parser, pdbtool, graphite-output: fix glib assertion error

  The assertion happened in these cases

  • dbparser database load
  • argument parsing in graphite-output
  • pdbtool merge commad

  Syslog-ng emitted a glib assertion warning in the cases above, even in successful executions.

  If G_DEBUG=fatal-warnings environment variable was used, the warning turned into a crash.
  (#3344)

• stats: fix stats-ctl query crash when trying to reset all the counters
  syslog-ng-ctl query get '*' --reset
  (#3361)

Packaging

• RHEL 7 packaging: fix logrotate file conflict with rsyslog
  (#3324)
• Debian packaging: python3-nose was removed from package dependencies.
  Pytest will run Python related unittests (for modules/python/pylib/syslogng/debuggercli/tests/)
  instead of nose.
  (#3343)

Notes to developers

• light: test for assertion errors in glib for each testcases
  (#3344)

• Fix signal handling when an external library/plugin sets SIG_IGN

  Previously, setting SIG_IGN in a plugin/library (for example, in a Python module) resulted in a crash.
  (#3338)

• func-test: removed logstore_reader check, which was never reached
  (#3236)

• plugin_skeleton_creator: fixing a compiler switch

  Wrong compiler switch used in plugin_skeleton_creator. This caused a compiler warning. The grammar debug info did not appear for that module, when -y command line option was used.
  (#3339)

• Light test framework: get_stats and get_query functions to DestinationDriver class

  Two new functions added to DestinationDriver class which can be used for getting the stats
  and query output of syslog-ng-ctl.
  (#3211)

Other changes

• internal(): limit the size of internal()'s temporary queue

  The internal() source uses a temporary queue to buffer messages.
  From now on, the queue has a maximum capacity, the log-fifo-size() option
  can be used to change the default limit (10000).

  This change prevents consuming all the available memory in special rare cases.
  (#3229)

• network plugins: better timer defaults for TCP keepalive

  From now on, syslog-ng uses the following defaults for TCP keepalive:

  • tcp-keepalive-time(): 60
  • tcp-keepalive-intvl(): 10
  • tcp-keepalive-probes(): 6

  Note: so-keepalive() is enabled by default.
  (#3357)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:
Andras Mitzki, Antal Nemes, Attila Szakacs, Balazs Scheidler, Christian Tramnitz, chunmeng, Gabor Nagy, Laszlo Budai, Laszlo Szemere, László Várady, MileK, Norbert Takacs, Peter Czanik, Péter Kókai, Terez Nemes.

3.28.1

Highlights

• http: add support for proxy option

  Example:

  log {
     source { system(); };
     destination { http( url("SYSLOG_SERVER_IP:PORT") proxy("PROXY_IP:PORT") method("POST") ); };
  };
  

  (#3253)

Features

• map: template function

  This template function applies a function to all elements of a list. For example: $(map $(+ 1 $_) 0,1,2) => 1,2,3.
  (#3301)

• use-syslogng-pid(): new option to all sources

  If set to yes, syslog-ng overwrites the message's ${PID} macro to its own PID.
  (#3323)

Bugfixes

• affile: eliminate infinite loop in case of a spurious file path

  If the template evaluation of a log message will result to a spurious
  path in the file destination, syslog-ng refuses to create that file.
  However the problematic log message was left in the msg queue, so
  syslog-ng was trying to create that file again in time-reopen periods.
  From now on syslog-ng will handle "permanent" file errors, and drop
  the relevant msg.
  (#3230)

• Fix minor memory leaks in error scenarios
  (#3265)

• crypto: fix hang on boot due to lack of entropy
  (#3271)

• Fix IPv4 UDP destinations on FreeBSD

  UDP-based destinations crashed when receiving the first message on FreeBSD due
  to a bug in destination IP extraction logic.
  (#3278)

• network sources: fix TLS connection closure

  RFC 5425 specifies that once the transport receiver gets close_notify from the
  transport sender, it MUST reply with a close_notify.

  The close_notify alert is now sent back correctly in case of TLS network sources.
  (#2811)

• disk-buffer: fixes possible crash, or fetching wrong value for logmsg nvpair
  (#3281)

• packaging/debian: fix mod-rdkafka Debian packaging
  (#3282)

• kafka destination: destination halts if consumer is down, and kafka's queue is filled
  (#3305)

• file-source: Throw error, when follow-freq() is set with a negative float number.
  (#3306)

• stats-freq: with high stats-freq syslog-ng emits stats immediately causing high memory and CPU usage
  (#3320)

• secure-logging: bug fixes (#3284)

  • template arguments are now consistently checked
  • fixed errors when mac file not provided
  • fixed abort when derived key not provided
  • fixed crash with slogkey missing parameters
  • fixed secure-logging on 32-bit architectures
  • fixed CMake build

Other changes

• dbld: Fedora 32 support (#3315)
• dbld: Removed Ubuntu Eoan (#3313)
• secure-logging: improvements (#3284)
  • removed 1500 message length limitation
  • slogimport has been renamed to slogencrypt
  • $(slog) will not start anymore when key is not found
  • internal messaging (warning, debug) improvements
  • improved memory handling and error information display
  • CMake build improvements
  • switched to GLib command line argument parsing
  • the output of slogkey -s is now parsable
  • manpage improvements

Notes to developers

• dbld: devshell is now upgraded to Ubuntu Focal
  (#3277)
• dbld/devshell: Multiple changes:
  • Added snmptrapd package.
  • Added support for both python2 and python3.
    (#3222)
• threaded-source: fully support default-priority() and default-facility()
  (#3304)
• CMake: fix libcap detection
  (#3294)
• Fix atomic_gssize_set() warning with new glib versions
  (#3286)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Airbus Commercial Aircraft, Andras Mitzki, Antal Nemes, Attila Szakacs,
Balazs Scheidler, Gabor Nagy, Laszlo Budai, Laszlo Szemere, László Várady,
Péter Kókai, Vatsal Sisodiya, Vivin Peris.

3.27.1

Highlights

• DESTIP/DESTPORT/PROTO: new macros. (#2899)
• set-facility(): add new rewrite operation to change the syslog facility associated with the message. (#3136)
• network tls: Added ca-file() option. With this option the user can set a bundled CA-file to verify the peer. (#3145)
• Forward integrity and confidentiality of logs (#3121): It is an experimental feature currently, we are still working on the final form with the authors.

Features

• DESTIP/DESTPORT/PROTO: new macros

  These new macros express the destination ip, destination port and used protocol on a source.

  The use-case behind the PR is as follows:

  • someone has an appliance which sends out log messages via both UDP and TCP
  • the format of the two are different, and he wants to capture either with the simplest possible filter
  • netmask() doesn't work because the IP addresses are the same
  • host() doesn't work because the hostnames are the same

  Example:

  log {
    source { network(localip(10.12.15.215) port(5555) transport(udp)); };
    destination { file("/dev/stdout" template("destip=$DESTIP destport=$DESTPORT proto=$PROTO\n")); };
  };
  

  Output:

  destip=10.12.15.215 destport=5555 proto=17
  

  (#2899)

• set-facility(): add new rewrite operation to change the syslog facility
  associated with the message.

  log {
      source { system(); };
      if (program("postfix")) {
        rewrite { set-facility("mail"); };
      };
      destination { file("/var/log/mail.log"); };
      flags(flow-control);
  };
  

  (#3136)

• network tls: Added ca-file() option. With this option the user can set a bundled CA-file to verify the peer.
  (#3145)

• http: When a HTTP response is received, emit a signal with the HTTP response code.
  (Later it can be extended to read the response and parse it in a slot...).

  This PR also extends the Python HTTP header module with the possibility of writing custom HTTP response code handlers. When someone implements an auth header plugin in Python, it could be useful (for example invalidating a cache).

  
  @version: 3.25
  
  python {
  from syslogng import Logger
  
  logger = Logger()
  
  class TestCounter():
      def __init__(self, options):
          self.header = options["header"]
          self.counter = int(options["counter"])
          logger.debug(f"TestCounter class instantiated; options={options}")
  
      def get_headers(self, body, headers):
          logger.debug(f"get_headers() called, received body={body}, headers={headers}")
  
          response = ["{}: {}".format(self.header, self.counter)]
          self.counter += 1
          return response
  
      def on_http_response_received(self, http_code):
          self.counter += http_code
          logger.debug("HTTP response code received: {}".format(http_code))
  
      def __del__(self):
          logger.debug("Deleting TestCounter class instance")
  };
  
  source s_network {
    network(port(5555));
  };
  
  destination d_http {
      http(
          python_http_header(
              class("TestCounter")
              options("header", "X-Test-Python-Counter")
              options("counter", 11)
              # this means that syslog-ng will trying to send the http request even when this module fails
              mark-errors-as-critical(no)
          )
          url("http://127.0.0.1:8888")
      );
  };
  
  log {
      source(s_network);
      destination(d_http);
      flags(flow-control);
  };
  

  (#3159)

• java/python: add support for the "arrow" syntax.

  options("key" => "value")
  

  (#3161) (#3247)

• python: persist support for python

  This feature enables users to persist data between reloads or restarts. The intended usage is to support bookmarking and acknowledgement in the future. It is not suitable for local database use cases.
  (#3171)

• rewrite: Added conditional set-tag() option. With this option the user can put condition statement inside set-tag option.

  rewrite { set-tag("tag" condition(match("test" value("MSG")))); };
  

  (#3190)

• scl: add sumologic destinations: sumologic-syslog() and sumologic-http()
  (#3194)

• iterate: new template function

  The iterate template function generates a series from an initial number and a next function.

  For example you can generate a sequence of nonnegative numbers with

  source {
    example-msg-generator(
      num(3)
      template("$(iterate $(+ 1 $_) 0)")
    );
  };
  

  (#3205)

• telegram: new max-size option

  Telegram message will be truncated for max-size size. Telegram does not accept message larger than 4096 utf8 characters. The default value is 4096.
  (#3206)

• example-message-generator : add support for values(name1 => value1, name2 => value2,..) syntax.

  Example

  @version: 3.27
  log {
    source { example-msg-generator(template("message parameter")
                                   num(10)
                                   values("PROGRAM" => "program-name"
                                          "current-second" => "$C_SEC"
                                  ));
           };
    destination { file(/dev/stdout template("$(format-json --scope all-nv-pairs)\n")); };
  };
  

  (#3237)

• example-msg-generator: support freq(0) for fast message generation

  log {
     source { example-msg-generator(freq(0) num(100)); };
     destination { file("/dev/stdout"); };
  };
  

  (#3245)

Bugfixes

• file: changed time-reap() timer's schedule to respect the documentation (expires after last message)
  (#3133)

• dbld: fix building problems

  • fix rpm package build on centos-7
  • fix devshell image build
  • fix ubuntu-trusty image build
  • fix deb package build on ubuntu-trusty
  • fix rpm package build on fedora-30
    (#3143)

• tls (network): Properly log an error message, when key-file() or cert-file() is missing.
  (#3145)

• loggen: fix crash with invalid parameterization
  (#3146)

• format-json: fix printing of embedded zeros

  Prior to 2.64.1, g_utf8_get_char_validated() in glib falsely identified embedded zeros as valid utf8 characters. As a result, format json printed the embedded zeroes as \u0000 instead of \x00. This change fixes this problem.
  (#3175)

• configure: fix --with-net-snmp configure option
  (#3180)

• python: fix Py_None reference counting in logger methods (trace, debug, info, warning, error)
  (#3187)

• afmongodb: do not build module when ENABLE_MONGODB=OFF
  (#3188)

• telegram: automatically truncate messages larger than 4096 utf8 characters to avoid telegram destination to get stuck
  (#3206)

• compat/glib: fix recursive call issue on CentOS-6/RHEL-6/platforms
  (#3212)

• timeutils: fix crash in %f conversion when non-numeric character is in usec field (e.g. ".asd123")
  (#3270)

Packaging

• macOS: add example startup configuration.
  (#3172)

• rpm: fix --without maxminddb option

  If maxminddb development package was installed on the build system: rpmbuild fails if --without maxminddb was used.
  (#3208)

Notes to developers

• light: Support to relocate reports dir other than current base dir

  For example

  python -m pytest -lvs functional_tests/source_drivers/file_source/test_acceptance.py --installdir=/install --reports /tmp/
  

  (#3157)

• CONTRIBUTING.md: contribution guide updated
  (#3174)

• libtest: Now we install config_parse_lib.h, fake-time.h, mock-cfg-parser.h and queue_utils_lib.h
  which help unit testing outside of core.
  (#3179)

• tests: Wait until snmptrapd process able to write traps into output file
  (#3185)

• mongodb: Replaced the deprecated get_server_status() API with command_simple().

  This means, that syslog-ng can now be built with -Werror on systems with 1.15 libmongoc.
  (#3199)

• stats: add external stats counters

  There are situations when someone wants to expose internal variables through stats-api.
  Without this changeset, we need two distinct variables: one is for the internal state, other is for the
  stats registration (internal state cannot depends on the life cycle of the StatsCounterGroup).
  (#3225)

Other changes

• afsnmp: merge two existing SNMP modules (trapd-parser and destination) into one.

  Motivation: keep closely related modules together and decrease the number of small packages.

  Packaging related changes:

  libsnmptrapd-parser.so has been removed, both the snmp destination and the trapd parser are part of afsnmp.so .

  • deb: we already had mod-snmp which shipped snmp-dest. From now, this packages installs the snmptrapd-parser syslog-ng module. The syslog-ng-mod-snmptrapd-parser package has been removed.
  • rpm: snmpdest renamed to afsnmp and the snmptrapd-parser is installed by this package from now
    (#3142)

• dbld: remove ubuntu-cosmic as it has reached EOL
  (#3143)

• afsocket-source: present the number of connections in stats

  It helps in the debug process if we can see the number of source connections counted by syslog-ng internally.
  (#3193)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Airbus Commercial Aircraft, Andras Mitzki, Antal Nemes, Attila Szakacs, Balazs Scheidler, Gabor Nagy, Kokan, Laszlo Budai, Laszlo Szemere, László Várady, Mehul Prajapati, Roberto Meléndez, Stephan Marwedel, Steven Haigh, Peter Czanik, Thomas De Schampheleire, Vatsal Sisodiya, Vivin Peris

3.26.1

Highlights

• file source: Added a new option to multi-line file sources: multi-line-timeout()
  After waiting multi-line-timeout() seconds without reading new data from the file, the last (potentially partial)
  message will be flushed and sent through the pipeline as a LogMessage.
  Since the multi-line file source detects the end of a message after finding the beginning of the subsequent message
  (indented or no-garbage/suffix mode), this option can be used to flush the last multi-line message
  in the file after a multi-line-timeout()-second timeout.
  There is no default value, i.e. this timeout needs to be explicitly configured.
  Example config:

  file("/some/folder/events"
      multi-line-mode("prefix-garbage")
      multi-line-prefix('^EVENT: ')
      multi-line-timeout(10)
      flags("no-parse")
  );
  

  (#2963)

• python-http-header: Added this new plugin, which makes it possible for users to implement HTTP header plugins in Python language.
  It is built on top of signal-slot mechanism: currently HTTP module defines only one signal, that is signal_http_header_request and python-http-header plugin implements a python binding for this signal. This means that when the signal_http_header_request signal is emitted then the connected slot executes the Python code.
  The Python interface is:

  def get_headers(self, body, headers):
  

  It should return string List. The headers that will be appended to the request's header.
  When the plugin fails, http module won't try to send the http request without the header items by default.
  If you want http module to trying to send the request without these headers, just disable mark-errors-as-critical() function.
  Original code was written by Ferenc Sipos.

  @version: 3.26
  python {
  from syslogng import Logger
  logger = Logger()
  class TestCounter():
      def __init__(self, options):
          self.header = options["header"]
          self.counter = int(options["counter"])
          logger.debug(f"TestCounter class instantiated; options={options}")
      def get_headers(self, body, headers):
          logger.debug(f"get_headers() called, received body={body}, headers={headers}")
         
          response = ["{}: {}".format(self.header, self.counter)]
          self.counter += 1
          return response
      def __del__(self):
          logger.debug("Deleting TestCounter class instance")
  };
  source s_network {
    network(port(5555));
  };
  destination d_http {
      http(
          python_http_header(
              class("TestCounter")
              options("header", "X-Test-Python-Counter")
              options("counter", 11)
              # this means that syslog-ng will trying to send the http request even when this module fails
              mark-errors-as-critical(no)
          )
          url("http://127.0.0.1:8888")
      );
  };
  log {
      source(s_network);
      destination(d_http);
      flags(flow-control);
  };
  

• azure-auth-header: Added this new plugin, which generates authorization header for applications connecting to Azure.
  It can be used as a building block in higher level SCLs.
  Implemented as a signal-slot plugin.

  @version: 3.26
  @include "scl.conf"
  destination d_http {
    http(
      url("http://127.0.0.1:8888")
      method("PUT")
      user_agent("syslog-ng User Agent")
      body("${ISODATE} ${MESSAGE}")
      azure-auth-header(
        workspace-id("workspace-id")
        secret("aa1a")
        method("POST")
        path("/api/logs")
        content-type("application/json")
      )
    );
  };
  source s_gen {
    example-msg-generator(num(1) template("Test message\n"));
  };
  log {
    source(s_gen);
    destination(d_http);
  };
  

• python: From now on users can specify a persist name template from python code.

  @staticmethod
  def generate_persist_name(options):
      return options["file_name"]
  

  • Usage of this function is necessary, when one python destination is used multiple times in one config.
  • Persist name from config takes precedence over generate_persist_name.
  • Persist name is exposed through self.persist_name. (#3016)

Features

• set-severity(): Added this new rewrite rule for changing message severity.
  It receives a template and sets message severity by evaluating the template.
  Numerical and textual severity levels are both supported.
  Examples:

  rewrite {
    set-severity("info");
    set-severity("6");
    set-severity("${.json.severity}");
  };
  

  (#3115)
• $(list-search): Added a new template function, which returns the first index of a pattern in a list.
  Starts the search at start_index. 0 based. If not found, returns empty string.
  Usage: $(list-search --mode MODE <pattern> ${list})
  Where mode can be: literal (default), prefix, substring, glob, pcre.
  Add --start-index <index> to change the start index. (#2955)
• config version: Made the config version check of the configuration more liberal by accepting version numbers
  that had no changes relative to the current version. This means that if you are running 3.26 and the last
  semantic change in the configuration was 3.22, then anything between 3.22 and 3.26 (inclusive) is accepted
  by syslog-ng without a warning at startup. (#3074)
• $SEVERITY instead of $LEVEL: syslog-ng now follows the RFC3164 trend of using severity instead of level
  to refer to the severity of the message that is used in the template language ($SEVERITY),
  filter expressions (severity()) and so on. (#3128)
• http: Added ssl_version("tlsv1_3") and ssl_version("no-tlsv13") options to respectively force and disable TLSv1.3. (#3063)
• scl: Improved error message at init, when an scl is missing a dependency. (#3015)
• geoip2: Added template() option as an alias for the positional argument string, to match the grammar convention. (#3051)
• loggly: Added transport() option, so users can now use it with tls (or any network() supported transport). (#3149)
• config-option-database: Added support for parser, diskq and hook-commands blocks. (#3029)

Bugfixes

• configure.ac: Fixed gethostbyname() function location detection (#3135)

• http: Fixed a crash, when workers() was set to 0. We do not allow nonnegative values anymore. (#3116)

• snmp-dest: engine-id() option now handles 5 to 32 characters, instead of the strict 10 before. (#3058)

• http: Fixed handling of ssl-version() option, which was ignored before.
  Prior this fix, these values of ssl-version in http destination were ignored by syslog-ng:
  tlsv1_0, tlsv1_1, tlsv1_2, tlsv1_3. (#3083)

• network sources: Added workaround for a TLS 1.3 bug to prevent data loss.
  Due to a bug in the OpenSSL TLS 1.3 implementation (openssl/openssl#10880),
  it is possible to lose messages when one-way communication protocols are used, -
  such as the syslog protocol over TLS (RFC 5425,
  RFC 6587) - and the connection is closed by the client right after sending data.
  The bug is in the TLS 1.3 session ticket handling logic of OpenSSL.

  To prevent such data loss, we've disabled TLS 1.3 session tickets in all syslog-ng network sources.
  Tickets are used for session resumption, which is currently not supported by syslog-ng.

  The loggen testing tool also received some bugfixes (#3064), which reduce the
  likelihood of data loss if the target of loggen has not turned off session tickets.

  If you're sending logs to third-party OpenSSL-based TLS 1.3 collectors, we recommend turning session
  tickets off in those applications as well until the OpenSSL bug is fixed. (#3082)

• cmake: Now we install loggen headers, as we do with autotools. (#3067)

• graylog2, format-gelf: Fixed sending empty message, when ${PID} is not set.
  Also added a default value "-" to empty short_message and host as they are mandatory fields. (#3112)

• loggen: fix dependency error with cmake + openssl from nonstandard location (#3062)

• config-option-database: Fixed reading 'grammar' and 'parser' files on 'POSIX' environment (#3125)

• file source: Fixed file source not able to process new message after log-msg-size() increase. (#3075)

• checkpoint parser: Fixed parsing ISO timestamp. (#3056)

• secret-storage: Fixed some cases, where diagnostical logs were truncated. (#3141)

• loggen, dqtool: Fixed a crash, when writing error/debug message or relocating qfile. (#3069)

• build: Fixed a compatibility related build error on Solaris 11. (#3070)

• loggen: Fixed address resolution when only loopback interface was configured. (#3048)

Packaging

• scl: Moved scl files to the core package. (#2979)
• RHEL: Now we include the packaging/rhel/ folder in our release tarball. (#3071)
• RHEL 8 / CentOS 8: Added RHEL 8 / CentOS 8 support to syslog-ng.spec (#3034)

Notes to developers

• signal-slot-connector: Introduced a generic event handler interface for syslog-ng modules.

  • The concept is simple:
    • There is a SignalSlotConnector which stores Signal - Slot connections
    • Signal : Slot = 1 : N, so multiple slots can be assigned to the same Signal.
    • When a Signal is emitted, the connected Slots are executed.
    • Signals are string literals and each module can define its own signals.
  • Interface/protocol between signals and slots:
    • A macro (SIGNAL) can be used for defining signals as string literals:

  SIGNAL(module_name, signal, signal_parameter_type)
  

  The parameter type is for expressing a kind of contract between signals and slots.

  • Usage:

     #define signal_cfg_reloaded SIGNAL(config, reloaded, GlobalConfig)
     the generated literal:
     "config::signal_reloaded(GlobalConfig *)"
  

  • emit passes the argument to the slots connected to the emitted signal. (#3043)

• http: Defined the Signal interface for HTTP - with one signal at this time.
  What's in the changeset?

  • List ADT (abstract data type for list implementations) added to lib.
    • Interface:
      • append
      • foreach
      • is_empty
      • remove_all
  • Implemented the List ADT in http module with struct curl_slist for storing the headers.
  • HTTP signal(s):
    • Currently only one signal is added, header_request.
      Note, that the license for http-signals.h is LGPL . (#3044)

• example-modules: Added example http slot plugin.
  This plugin is an example plugin that implements a slot for a HTTP signal (signal_http_header_request).
  When the plugin is attached, it CONNECT itself to the signal.
  When the signal is emitted by the http module, the slot is executed and append the header to the http headers.
  header is set in the config file.

  @version: 3.26
  @include "scl.conf"
  destination d_http {
    http(
      url("http://127.0.0.1:8888")
      method("PUT")
      user_agent("syslog-ng User Agent")
      http-test-slots(
        header("xxx:aaa") # this will be appended to the http headers
      )
      body("${ISODATE} ${MESSAGE}")
    );
  };
  source s_generator {
    example-msg-generator(num(1) template("test msg\n") );}
  ;
  source s_net {
    network(port(5555));
  };
  log {
    source(s_generator);
    destination(d_http);
  };
  

• NEWS.md: From now on, for every PR that we want to include in the newsfile,
  we must create the news entry with the PR itself. See news/README.md. (#3066)

• snmp test in Light: Added snmp destination tests in the Light test framework.
  These tests requires snmptrapd as an external dependency. If you don't want to run this test,
  you can use the pytest's marker discovery feature: python -m pytest ... -m 'not snmp'
  The tests are run by syslog-ng's Travis workflow. (#3126)

• cmake: Added add_module function to cmake to normalize CMakeLists.txt files for modules. (#3106)

• dbld: Introduced syslog-ng-kira as a new CI image (#3125)

• FunctionalTests: Functional tests are now Python3 compatible (#3144)

• dbld: Added Ubuntu 19.10 and 20.04 (#3091)

• dbld: Added option to customize shell command.
  With this change, it is possible to override the option with rules.conf, while keeping the default behaviour.
  The simplest example: use existing images, start a new one if there is none. (use docker rm manually if you want to update)

  DOCKER_SHELL=$(DOCKER) inspect $* > /dev/null 2>&1; \
    if [ $$? -eq 0 ]; then \
      $(DOCKER) start -ia $*; \
    else \
      $(DOCKER) run $(DOCKER_RUN_ARGS) -ti --name $* balabit/syslog-ng-$* /source/dbld/shell; \
    fi
  

  (#3038)

Other changes

• python: Added --with-python3-home configure option to use a hard-coded PYTHONHOME for Python-based plugins.
  This can be useful when a Python interpreter is bundled with syslog-ng.
  Relocation is supported, for example: --with-python3-home='${exec_prefix}' (#3134)
• afmongodb: Removed the support of deprecated legacy configurations (#3092)
• http: use-system-cert-store() now autodetects the system provided cert-store (#3086)
• doc: Added manual page for persist-tool. (#3072)

Credits

syslog-ng is developed as a community project, and as such it relies
on volunteers, to do the work necessarily to produce syslog-ng.

Reporting bugs, testing changes, writing code or simply providing
feedback are all important contributions, so please if you are a user
of syslog-ng, contribute.

We would like to thank the following people for their contribution:

Andras Mitzki, Antal Nemes, Attila Szakacs, Balazs Scheidler, Dylan Perry, Gabor Nagy, Laszlo Budai,
Laszlo Szemere, László Várady, Norbert Takacs, Peter Czanik, Péter Kókai, Romain Tartière, Tomáš Mózes.