The darwin-oslog() source is based on the native OSLog Framework to read logs from the local store of the unified logging system on Darwin OSes. The syslog-ng OSE system() source automatically uses this new source on Darwin platforms if the `darwinosl` plugin is available. This plugin is available only on macOS 10.15 Catalina and later versions. The 10.15 version is the first to support the OSLog API.

NOTE: The persistent OSLog store keeps about 7 days of logs on the disk.

The darwin-oslog() source has the following options.

chain-hostname()

Type: yes, no
Default: no

Description: This option can be used to enable or disable the chained hostname format. For more information, see the chain-hostnames() global option.

default-facility()

Type: facility string
Default: kern

Description: This parameter assigns a facility value to the messages received from the file source if the message does not specify one.

default-level()

This is just an alias of default-priority().

default-priority()

Type: priority string
Default:  

Description: This option defines the default level value if the PRIORITY entry does not exist in the msg received from the file source. For example, default-priority(warning).

default-severity()

This is just an alias of default-priority().

disable-bookmarks()

Type: boolean
Default: no

Description: This option prevents syslog-ng OSE from storing a bookmark (such as position or offset) in its persist file for the last processed message.

NOTE: This will not prevent usage of an already presented bookmark entry, for ignoring those bookmark entries specify ignore-saved-bookmarks(yes) as well.

dns-cache()

Type: yes, no
Default: no

Description: This option enables or disables the DNS cache usage.

filter-predicate()

Type: string
Default: (eventType == 'logEvent' || eventType == 'lossEvent' || eventType == 'stateEvent' || eventType == 'userActionEvent') && (logType != 'debug')

Description: String for native macOS log message filtering using predicates. For example, the following predicate selects AirDrop logs: subsystem=="com.apple.sharing" and category=="AirDrop"

go-reverse()

Type: boolean
Default: no

Description: If set to yes, the logs are processed in reverse order (latest to oldest).

hook-commands()

Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.

NOTE: The syslog-ng OSE application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable syslog-ng OSE to execute external applications.

Using the hook-commands() when syslog-ng OSE starts or stops

To execute an external program when syslog-ng OSE starts or stops, use the following options:

startup()

Type: string
Default: N/A

Description: Defines the external program that is executed as syslog-ng OSE starts.

shutdown()

Type: string
Default: N/A

Description: Defines the external program that is executed as syslog-ng OSE stops.

Using the hook-commands() when syslog-ng OSE reloads

To execute an external program when the syslog-ng OSE configuration is initiated or torn down, for example, on startup/shutdown or during a syslog-ng OSE reload, use the following options:

setup()

Type: string
Default: N/A

Description: Defines an external program that is executed when the syslog-ng OSE configuration is initiated, for example, on startup or during a syslog-ng OSE reload.

teardown()

Type: string
Default: N/A

Description: Defines an external program that is executed when the syslog-ng OSE configuration is stopped or torn down, for example, on shutdown or during a syslog-ng OSE reload.

Example: Using the hook-commands() with a network source

In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as syslog-ng OSE is started/stopped.

The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the syslog-ng OSE created rule is there, packets can flow, otherwise the port is closed.

source {
    network(transport(udp)
        hook-commands(
          startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
          shutdown("iptables -D LOGCHAIN 1")
        )
      );
};

host-override()

Type: string
Default:  

Description: Replaces the HOST part of the message with the parameter string.

hook-commands()

Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.

NOTE: The syslog-ng OSE application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable syslog-ng OSE to execute external applications.

Using the hook-commands() when syslog-ng OSE starts or stops

To execute an external program when syslog-ng OSE starts or stops, use the following options:

startup()

Type: string
Default: N/A

Description: Defines the external program that is executed as syslog-ng OSE starts.

shutdown()

Type: string
Default: N/A

Description: Defines the external program that is executed as syslog-ng OSE stops.

Using the hook-commands() when syslog-ng OSE reloads

To execute an external program when the syslog-ng OSE configuration is initiated or torn down, for example, on startup/shutdown or during a syslog-ng OSE reload, use the following options:

setup()

Type: string
Default: N/A

Description: Defines an external program that is executed when the syslog-ng OSE configuration is initiated, for example, on startup or during a syslog-ng OSE reload.

teardown()

Type: string
Default: N/A

Description: Defines an external program that is executed when the syslog-ng OSE configuration is stopped or torn down, for example, on shutdown or during a syslog-ng OSE reload.

Example: Using the hook-commands() with a network source

In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as syslog-ng OSE is started/stopped.

The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the syslog-ng OSE created rule is there, packets can flow, otherwise the port is closed.

source {
    network(transport(udp)
        hook-commands(
          startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
          shutdown("iptables -D LOGCHAIN 1")
        )
      );
};

ignore-saved-bookmarks()

Type: boolean
Default: no

Description: By default, syslog-ng OSE continues reading logs from the last remembered position (or offset, etc.) stored in its persist file after a restart or reload. If this option is set to yes, it will always start reading from either the beginning or the end of the available log list (depending on the setting of the go-reverse() and the read-old-records() options.

NOTE: The deprecated do-not-use-bookmark() option is an alias for the ignore-saved-bookmarks() option, retained for compatibility with earlier syslog-ng OSE versions, but it may be removed at any time without further notice!

keep-hostname()

Type: yes or no
Default: no

Description: Enable or disable hostname rewriting.

NOTE: If the log message does not contain a hostname in its HOST field, syslog-ng OSE automatically adds a hostname to the message.

  • For messages received from the network, this hostname is the address of the host that sent the message (this means the address of the last hop if the message was transferred via a relay).

  • For messages received from the local host, syslog-ng OSE adds the name of the host.

This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

NOTE: When relaying messages, enable this option on the syslog-ng OSE server and also on every relay, otherwise syslog-ng OSE will treat incoming messages as if they were sent by the last relay.

keep-timestamp()

Accepted values: yes | no
Default: yes

Description: Specifies whether syslog-ng OSE should accept the timestamp received from the sending application or client. If disabled, the time of reception will be used instead. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

CAUTION: To use the S_ macros, the keep-timestamp() option must be enabled (this is the default behavior of syslog-ng OSE).

log-fetch-delay()

Type: integer [1 second / fetch_retry_delay * 1000000 milliseconds]
Default: 10000 (10 milliseconds)

Description: Sets the time syslog-ng OSE waits between reading and sending log messages. The unit of this parameter is a fraction of a second, where wait_time = 1 second / <defined value>. For example, setting it to 1 results in approximately one log being read/sent per second, while 1000000 means a delay of only 1 microsecond between read/write attempts. The maximum value of this parameter is 1000000.

NOTE: Increasing the value of this parameter (which reduces the delay time) can improve log feed performance, but it may also increase system load.

NOTE: The deprecated fetch-delay() option is an alias for the log-fetch-delay() option, retained for compatibility with earlier syslog-ng OSE versions, but it may be removed at any time without further notice!

log-fetch-retry-delay()

Type: integer in seconds
Default: 1

Description: Controls how many seconds syslog-ng OSE remains idle before checking for new logs, in case no new logs were read during the previous check.

NOTE: The deprecated fetch-retry-delay() option is an alias for the log-fetch-retry-delay() option, retained for compatibility with earlier syslog-ng OSE versions, but it may be removed at any time without further notice!

log-fetch-limit()

Type: number
Default: 100

Description: The maximum number of messages fetched from a source during a single poll loop. The destination queues might fill up before flow-control could stop reading if log-fetch-limit() is too high.

max-bookmark-distance()

Type: integer
Default: 0 (unlimited) in seconds

Description: The maximum distance in seconds that a bookmark can point backward. That is, if syslog-ng OSE is stopped for 10 minutes (600 seconds) and max-bookmark-distance() is set to 60, then syslog-ng OSE starts reading the logs from 60 seconds before the startup, missing 9 minutes (540 seconds) worth of logs.

program-override()

Type: string
Default:  

Description: Replaces the ${PROGRAM} part of the message with the parameter string. For example, to mark every message coming from the kernel, include the program-override("kernel") option in the source containing /proc/kmsg.

read-old-records()

Type: boolean
Default: no

Description: If read-old-record() is set to yes, syslog-ng OSE will start fetching from the oldest available message; otherwise, it will start from the newest one (if no bookmarks are present, or ignore-saved-bookmarks() is set to yes).

tags()

Type: string
Default:  

Description: Label the messages received from the source with custom tags. Tags must be unique, and enclosed between double quotes. When adding multiple tags, separate them with comma, for example, tags(“dmz”, “router”). This option is available only in syslog-ng OSE 3.1 and later.

time-zone()

Type: name of the timezone, or the timezone offset
Default:  

Description: The default timezone for messages read from the source. Applies only if no timezone is specified within the message itself.

The timezone can be specified by using the name, for example, time-zone(“Europe/Budapest”)), or as the timezone offset in +/-HH:MM format, for example, +01:00). On Linux and UNIX platforms, the valid timezone names are listed under the /usr/share/zoneinfo directory.

use-dns()

Accepted values: yes, no, persist_only
Default: yes

Description: Enable or disable DNS usage. The persist_only option attempts to resolve hostnames locally from file (for example, from /etc/hosts). The syslog-ng OSE application blocks on DNS queries, so enabling DNS may lead to a Denial of Service attack. To prevent DoS, protect your syslog-ng OSE network endpoint with firewall rules, and make sure that all hosts which may get to syslog-ng OSE are resolvable. This option can be specified globally, and per-source as well. The local setting of the source overrides the global option if available.

NOTE: This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

use-fqdn()

Accepted values: yes | no
Default: no

Description: Use this option to add a Fully Qualified Domain Name (FQDN) instead of a short hostname. You can specify this option either globally or per-source. The local setting of the source overrides the global option if available.

TIP: Set use-fqdn() to yes if you want to use the custom-domain() global option.

NOTE: This option has no effect if the keep-hostname() option is enabled (keep-hostname(yes)) and the message contains a hostname.

Updated: