Manual pages

• 1: The `syslog-ng.conf` manual page
• 2: The `syslog-ng` manual page
• 3: The dqtool tool manual page
• 4: The loggen manual page
• 5: The pdbtool manual page
• 6: The persist-tool manual page
• 7: The secure-logging manual page
• 8: The slogencrypt manual page
• 9: The slogkey manual page
• 10: The slogverify manual page
• 11: The syslog-debun manual page
• 12: The syslog-ng control tool manual page

1 - The `syslog-ng.conf` manual page

Name

syslog-ng.conf — configuration file

Synopsis

syslog-ng.conf

Description

The AxoSyslog application is a flexible and highly scalable system logging application. Typically, AxoSyslog is used to manage log messages and implement centralized logging, where the aim is to collect the log messages of several devices on a single, central log server. The different devices - called syslog-ng clients - all run AxoSyslog, and collect the log messages from the various applications, files, and other sources. The clients send all important log messages to the remote AxoSyslog server, where the server sorts and stores them.

Basic concepts of AxoSyslog

The AxoSyslog application reads incoming messages and forwards them to the selected destinations. The AxoSyslog application can receive messages from files, remote hosts, and other sources.

Log messages enter AxoSyslog in one of the defined sources, and are sent to one or more destinations.

Sources and destinations are independent objects, log paths define what AxoSyslog does with a message, connecting the sources to the destinations. A log path consists of one or more sources and one or more destinations: messages arriving from a source are sent to every destination listed in the log path. A log path defined in AxoSyslog is called a log statement.

Optionally, log paths can include filters. Filters are rules that select only certain messages, for example, selecting only messages sent by a specific application. If a log path includes filters, AxoSyslog sends only the messages satisfying the filter rules to the destinations set in the log path.

Other optional elements that can appear in log statements are parsers and rewriting rules. Parsers segment messages into different fields to help processing the messages, while rewrite rules modify the messages by adding, replacing, or removing parts of the messages.

Configuring AxoSyslog

• The main body of the configuration file consists of object definitions: sources, destinations, logpaths define which log message are received and where they are sent. All identifiers, option names and attributes, and any other strings used in the syslog-ng.conf configuration file are case sensitive. Object definitions (also called statements) have the following syntax:

      type-of-the-object identifier-of-the-object {<parameters>};
  

  • Type of the object: One of source, destination, log, filter, parser, rewrite rule, or template.

    Identifier of the object: A unique name identifying the object. When using a reserved word as an identifier, enclose the identifier in quotation marks ("").

    All identifiers, attributes, and any other strings used in the AxoSyslog configuration file are case sensitive.

    Note Use identifiers that refer to the type of the object they identify. For example, prefix source objects with s_, destinations with d_, and so on.

    Repeating a definition of an object (that is, defining the same object with the same id more than once) is not allowed, unless you use the @define allow-config-dups 1 definition in the configuration file.

  • Parameters: The parameters of the object, enclosed in braces {parameters}.

  • Semicolon: Object definitions end with a semicolon (;).

  For example, the following line defines a source and calls it s_internal.

      source s_internal { internal(); };
  

  The object can be later referenced in other statements using its ID, for example, the previous source is used as a parameter of the following log statement:

      log { source(s_internal); destination(d_file); };
  

• The parameters and options within a statement are similar to function calls of the C programming language: the name of the option followed by a list of its parameters enclosed within brackets and terminated with a semicolon.

      option(parameter1, parameter2); option2(parameter1, parameter2);
  

  For example, the file() driver in the following source statement has three options: the filename (/var/log/apache/access.log), follow-freq(), and flags(). The follow-freq() option also has a parameter, while the flags() option has two parameters.

      source s_tail { file("/var/log/apache/access.log"
      follow-freq(1) flags(no-parse, validate-utf8)); };
  

  Objects may have required and optional parameters. Required parameters are positional, meaning that they must be specified in a defined order. Optional parameters can be specified in any order using the option(value) format. If a parameter (optional or required) is not specified, its default value is used. The parameters and their default values are listed in the reference section of the particular object.

Example: Using required and optional parameters

The unix-stream() source driver has a single required argument: the name of the socket to listen on. Optional parameters follow the socket name in any order, so the following source definitions have the same effect:

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

• Some options are global options, or can be set globally, for example, whether AxoSyslog should use DNS resolution to resolve IP addresses.

      options { use-dns(no); };
  

  • Objects can be used before definition.

  • Objects can be defined inline as well. This is useful if you use the object only once (for example, a filter).

  • To add comments to the configuration file, start a line with # and write your comments. These lines are ignored by AxoSyslog.

    #Comment: This is a stream source
    source s_demo_stream {
    unix-stream("<path-to-socket>" max-connections(10) group(log)); };
    

The syntax of log statements is as follows:

   log {
        source(s1); source(s2); ...
    optional_element(filter1|parser1|rewrite1);
    optional_element(filter2|parser2|rewrite2);
                ...
    destination(d1); destination(d2); ...
    flags(flag1[, flag2...]);
            };

The following log statement sends all messages arriving to the localhost to a remote server.

source s_localhost { network(ip(127.0.0.1) port(1999)); };
destination d_tcp { network("10.1.2.3" port(1999) localport(999)); };
log { source(s_localhost); destination(d_tcp); };

The AxoSyslog application has a number of global options governing DNS usage, the timestamp format used, and other general points. Each option may have parameters, similarly to driver specifications. To set global options add an option statement to the AxoSyslog configuration file using the following syntax:

options { option1(params); option2(params); ... };

Example: Using global options

To disable domain name resolving, add the following line to the AxoSyslog configuration file:

options { use-dns(no); };

The sources, destinations, and filters available in AxoSyslog are listed below. For details, see the AxoSyslog documentation.

Table: Available source drivers

Table 2. Available destination drivers

Table 3. Filter functions

Files

/opt/syslog-ng/

/opt/syslog-ng/etc/syslog-ng.conf

See also

syslog-ng.8

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

2 - The `syslog-ng` manual page

Name

syslog-ng — syslog-ng system logger application

Synopsis

syslog-ng [options]

Description

The AxoSyslog application is a flexible and highly scalable system logging application. Typically, AxoSyslog is used to manage log messages and implement centralized logging, where the aim is to collect the log messages of several devices on a single, central log server. The different devices - called clients - all run AxoSyslog, and collect the log messages from the various applications, files, and other sources. The clients send all important log messages to the remote AxoSyslog server, where the server sorts and stores them.

Options

• --caps

  Run AxoSyslog process with the specified POSIX capability flags.

  • If the --no-caps option is not set, AxoSyslog has been compiled with the --enable-linux-caps compile option, and the host supports CAP_SYSLOG, AxoSyslog uses the following capabilities: cap_net_bind_service, cap_net_broadcast, cap_net_raw, cap_dac_read_search, cap_dac_override, cap_chown, cap_fowner=p cap_syslog=ep

  • If the --no-caps option is not set, and the host does not support CAP_SYSLOG, AxoSyslog uses the following capabilities: cap_net_bind_service, cap_net_broadcast, cap_net_raw, cap_dac_read_search, cap_dac_override, cap_chown, cap_fowner=p cap_sys_admin=ep

  For example:

  /opt/syslog-ng/sbin/syslog-ng -Fv --caps cap_sys_admin,cap_chown,cap_dac_override,cap_net_bind_service,cap_fowner=pi
  

  Note that the capabilities are not case sensitive, the following command is also good: /opt/syslog-ng/sbin/syslog-ng -Fv --caps CAP_SYS_ADMIN,CAP_CHOWN,CAP_DAC_OVERRIDE,CAP_NET_BIND_SERVICE,CAP_FOWNER=pi

  For details on the capability flags, see the following man pages: cap_from_text(3) and capabilities(7)

• --cfgfile <file> or -f <file>

  Use the specified configuration file.

• --chroot <dir> or -C <dir>

  Change root to the specified directory. The configuration file is read after chrooting so, the configuration file must be available within the chroot. That way it is also possible to reload the syslog-ng configuration after chrooting. However, note that the --user and --groupoptions are resolved before chrooting.

• --check-startup: Use this option to perform a complete configuration initialization with syslog-ng, then exit with exit code indicating the result. You can use this option to check if the configuration is semantically valid and that syslog-ng can actually start. (The --syntax-only option catches only syntactical errors.)

  You can also use syslog-ng --check-startup in a Kubernetes environment, to run it as a dedicated configuration check container.

  Available only in AxoSyslog version 4.5 and later.

  Using this option initializes things like network listeners, so it will probably not work if another syslog-ng instance running in the background (because in that case the network address is already in use).

• --control <file> or -c <file>

  Set the location of the syslog-ng control socket. Default value: /var/run/syslog-ng.ctl

• --debug or -d

  Start syslog-ng in debug mode.

• --default-modules

  A comma-separated list of the modules that are loaded automatically. Modules not loaded automatically can be loaded by including the @module <modulename> statement in the AxoSyslog configuration file. Available only in AxoSyslog version 4.1 and later.

• --enable-core

  Enable AxoSyslog to write core files in case of a crash to help support and debugging.

• --fd-limit <number>

  Set the minimal number of required file descriptors (fd-s). This sets how many files syslog-ng can keep open simultaneously. Default value: 4096. Note that this does not override the global ulimit setting of the host.

• --foreground or -F

  Do not daemonize, run in the foreground. When running in the foreground, AxoSyslog starts from the current directory ($CWD) so it can create core files (normally, AxoSyslog starts from /$PREFIX/var).

• --group <group> or -g <group>

  Switch to the specified group after initializing the configuration file.

• --help or -h

  Display a brief help message.

• --log-level <level>

  Set the internal log level of AxoSyslog to default, verbose, debug, or trace. Available in AxoSyslog 4.0 and later.

• --module-registry

  Display the list and description of the available modules. Note that not all of these modules are loaded automatically, only the ones specified in the --default-modules option.

• --no-caps

  Run AxoSyslog as root, without capability-support. This is the default behavior. On Linux, it is possible to run AxoSyslog as non-root with capability-support if AxoSyslog was compiled with the --enable-linux-caps option enabled. (Run syslog-ng --version to display the list of enabled build parameters.)

  To run AxoSyslog with specific capabilities, use the --caps option.

• --persist-file <persist-file> or -R <persist-file>

  Set the path and name of the syslog-ng.persist file where the persistent options and data are stored.

• --pidfile <pidfile> or -p <pidfile>

  Set path to the PID file where the pid of the main process is stored.

• --preprocess-into <output-file>

  After processing the configuration file and resolving included files and variables, write the resulting configuration into the specified output file. Available only in AxoSyslog 4 F1 and later.

• --process-mode <mode>

  Sets how to run AxoSyslog: in the foreground (mainly used for debugging), in the background as a daemon, or in safe-background mode. By default, syslog-ng runs in safe-background mode. This mode creates a supervisor process called supervising syslog-ng, that restarts AxoSyslog if it crashes.

• --stderr or -e

  Log internal messages of AxoSyslog to stderr. Mainly used for debugging purposes in conjunction with the --foreground option. If not specified, syslog-ng logs such messages to its internal source.

• --syntax-only or -s

  Verify that the configuration file is syntactically correct and exit.

• --user <user> or -u <user>

  Switch to the specified user after initializing the configuration file (and optionally chrooting). Note that it is not possible to reload the syslog-ng configuration if the specified user has no privilege to create the /dev/log file.

• --verbose or -v

  Enable verbose logging used to troubleshoot AxoSyslog.

• --version or -V

  Display version number and compilation information, and also the list and short description of the available modules. For detailed description of the available modules, see the --module-registry option. Note that not all of these modules are loaded automatically, only the ones specified in the --default-modulesoption.

• --worker-threads

  Sets the number of worker threads AxoSyslog can use, including the main AxoSyslog thread. Note that certain operations in AxoSyslog can use threads that are not limited by this option. This setting has effect only when AxoSyslog is running in multithreaded mode. Available only in AxoSyslog 4 F1 and later. See The AxoSyslog 7 Administrator Guide for details.

Files

/opt/syslog-ng/

/opt/syslog-ng/etc/syslog-ng.conf

See also

syslog-ng.conf.5

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

3 - The dqtool tool manual page

Name

dqtool — Display the contents of a disk-buffer file created with AxoSyslog.

Synopsis

dqtool [command] [options]

Description

The dqtool application is a utility that can be used to display and format the messages stored in a disk-buffer file.

The cat command

cat [options] [file]

Use the cat command to display the log messages stored in the disk-buffer (also called disk-queue) file, and also information from the header of the disk queue file. The messages are printed to the standard output (stdout), so it is possible to use grep and other tools to find particular log messages, for example, dqtool cat /var/log/messages.lgs |grep 192.168.1.1.

The cat command has the following options:

• --debug or -d

  Print diagnostic and debugging messages to stderr.

• --help or -h

  Display a brief help message.

• --template=<template> or -t

  Format the messages using the specified template.

• --verbose or -v

  Print verbose messages to stderr.

• --version or -V

  Display version information.

Example: The cat command

./dqtool cat ../var/syslog-ng-00000.qf

The output looks like:

Disk-buffer state loaded;
filename='../var/syslog-ng-00000.qf', qout_length='65', qbacklog_length='0', qoverflow_length='9205', qdisk_length='0'
Mar  3 10:52:05 tristram localprg[1234]: seq: 0000011630, runid: 1267609923, stamp: 2010-03-03T10:52:05 PADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADD
Mar  3 10:52:05 tristram localprg[1234]: seq: 0000011631, runid: 1267609923, stamp: 2010-03-03T10:52:05 PADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADD

The info command

info [DISK-BUFFER_FILE]

Shows status information about the specified disk-buffer file. For example:

• Empty, normal disk-buffer file

  /opt/syslog-ng/bin/dqtool info /opt/syslog-ng/var/syslog-ng-00000.qf/var/lib/syslog-ng/syslog-ng-00000.qf
  

  Example output:

  Disk-buffer state loaded; filename='/opt/syslog-ng/var/syslog-ng-00000.qf/var/lib/syslog-ng/syslog-ng-00000.qf', number_of_messages='0'
  

• Non-empty, reliable disk-buffer queue file

  /opt/syslog-ng/bin/dqtool info /opt/syslog-ng/var/syslog-ng-00000.rqf
  

  Reliable disk-buffer state loaded; filename='/opt/syslog-ng/var/syslog-ng-00000.rqf', number_of_messages='10'
  

The relocate command

relocate [options] [files]

Use the relocate command to move or rename disk-buffer (also called disk-queue) files. Note that this option modifies the persist file. Stop AxoSyslog before using this command.

The relocate command has the following options:

• --all or -a

  Relocate every disk-buffer file that is listed in the AxoSyslog persist file.

• --new_path or -n

  The directory where you want to move the disk-bufffer files. For example: /var/disk-buffers

• --persist or -p

  The path to the AxoSyslog persist file. The relocate command automatically updates the entries of the disk-buffer files in the persist file.

Examples

Relocate a single queue file:

bin/dqtool relocate --new_path /tmp/dq --persist var/syslog-ng.persist /tmp/syslog-ng-00000.rqf

Relocate multiple queue files:

bin/dqtool relocate --new_path /tmp/dq --persist var/syslog-ng.persist /tmp/syslog-ng-00000.rqf /tmp/syslog-ng-00001.rqf

Relocate every queue file:

bin/dqtool relocate --new_path /tmp/dq --persist var/syslog-ng.persist --all

Files

/opt/syslog-ng/bin/dqtool

See also

syslog-ng.conf.5

syslog-ng.8

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

4 - The loggen manual page

Name

loggen — Generate syslog messages at a specified rate

Synopsis

loggen [options]

target [port]

Description

The loggen application is a tool to test and stress-test your syslog server and the connection to the server. It can send syslog messages to the server at a specified rate using a number of connection types and protocols, including TCP, UDP, and unix domain sockets. The messages can be generated automatically (repeating the PADDstring over and over), or read from a file or the standard input.

When loggen finishes sending the messages, it displays the following statistics:

• average rate: The average rate of the sent messages in messages/second.

• count: The total number of messages sent.

• time: The time required to send the messages in seconds.

• average message size: The average size of the sent messages in bytes.

• bandwidth: The average bandwidth used for sending the messages in kilobytes/second.

Options

• --active-connections <number-of-connections>

  Number of connections loggen will use to send messages to the destination. This option is usable only when using TCP or TLS connections to the destination. Default value: 1

  The loggen utility waits until every connection is established before starting to send messages. See also the --idle-connections option.

• --csv or -C

  Send the statistics of the sent messages to stdout as CSV. This can be used for plotting the message rate.

• --dgram or -D

  Use datagram socket (UDP or unix-dgram) to send the messages to the target. Requires the --inet option as well.

• dont-parse or -d

  Do not parse the lines read from the input files, send them as received.

• --help or -h

  Display a brief help message.

• --idle-connection <number-of-connections>

  Number of idle connections loggen will establish to the destination. Note that loggen will not send any messages on idle connections, but the connection is kept open using keep-alive messages. This option is usable only when using TCP or TLS connections to the destination. See also the --active-connections option. Default value: 0

• --inet or -i

  Use the TCP (by default) or UDP (when used together with the --dgram option) protocol to send the messages to the target.

• --interval <seconds> or -I <seconds>

  The number of seconds loggen will run. Default value: 10

  Note When --interval and --number are used together, loggen will send messages until the period set in --interval expires or the amount of messages set in --number is reached, whichever happens first.

• --ipv6 or -6

  Specify the destination using its IPv6 address. Note that the destination must have a real IPv6 address.

• --loop-reading or -l

  Read the file specified in --read-file option in loop: loggen will start reading from the beginning of the file when it reaches the end of the file.

• --number <number-of-messages> or -n <number-of-messages>

  Number of messages to generate.

  Note When --interval and --number are used together, loggen will send messages until the period set in --interval expires or the amount of messages set in --number is reached, whichever happens first.

• --no-framing or -F

  Do not use the framing of the IETF-syslog protocol style, even if the --syslog-proto option is set.

• --quiet or -Q

  Display statistics only when loggen is finished. If not set, the statistics are displayed every second.

• --permanent or -T

  Keep sending logs indefinitely, without time limit.

• --rate <message/second> or -r <message/second>

  The number of messages generated per second for every active connection. Default value: 1000

  If you want to change the message rate while loggen is running, send SIGUSR1 to double the message rate, or SIGUSR2 to halve it:

  kill -USR1 <loggen-pid>``kill -USR2 <loggen-pid>

• --read-file <filename> or -R <filename>

  Read the messages from a file and send them to the target. See also the --skip-tokens option.

  Specify - as the input file to read messages from the standard input (stdio). Note that when reading messages from the standard input, loggen can only use a single thread. The -R -parameters must be placed at end of command, like: loggen 127.0.0.1 1061 --read-file -

• --sdata <data-to-send> or -p <data-to-send>

  Send the argument of the --sdata option as the SDATA part of IETF-syslog (RFC5424 formatted) messages. Use it together with the --syslog-proto option. For example: --sdata "[test name=\\"value\\"]

• --size <message-size> or -s <message-size>

  The size of a syslog message in bytes. Default value: 256. Minimum value: 127 bytes, maximum value: 8192 bytes.

• --skip-tokens <number>

  Skip the specified number of space-separated tokens (words) at the beginning of every line. For example, if the messages in the file look like foo bar message, --skip-tokens 2 skips the foo bar part of the line, and sends only the message part. Works only when used together with the --read-file parameter. Default value: 0

• --stream or -S

  Use a stream socket (TCP or unix-stream) to send the messages to the target.

• --syslog-proto or -P

  Use the new IETF-syslog message format as specified in RFC5424. By default, loggen uses the legacy BSD-syslog message format (as described in RFC3164). See also the --no-framing option.

• --unix </path/to/socket> or -x </path/to/socket>

  Use a UNIX domain socket to send the messages to the target.

• --use-ssl or -U

  Use an SSL-encrypted channel to send the messages to the target. Note that it is not possible to check the certificate of the target, or to perform mutual authentication.

• --version or -V

  Display version number of syslog-ng.

Examples

The following command generates 100 messages per second for ten minutes, and sends them to port 2010 of the localhost via TCP. Each message is 300 bytes long.

loggen --size 300 --rate 100 --interval 600 127.0.0.1 2010

The following command is similar to the one above, but uses the UDP protocol.

loggen --inet --dgram --size 300 --rate 100 --interval 600 127.0.0.1 2010

Send a single message on TCP6 to the ::1 IPv6 address, port 1061:

loggen --ipv6 --number 1 ::1 1061

Send a single message on UDP6 to the ::1 IPv6 address, port 1061:

loggen --ipv6 --dgram --number 1 ::1 1061

Send a single message using a unix domain-socket:

loggen --unix --stream --number 1 </path/to/socket>

Read messages from the standard input (stdio) and send them to the localhost:

loggen 127.0.0.1 1061 --read-file -

Files

/opt/syslog-ng/bin/loggen

See also

syslog-ng.conf.5

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

5 - The pdbtool manual page

Name

pdbtool — An application to test and convert pattern database rules

Synopsis

pdbtool [command] [options]

Description

The AxoSyslog application can match the contents of the log messages to a database of predefined message patterns (also called patterndb). By comparing the messages to the known patterns, AxoSyslog is able to identify the exact type of the messages, tag the messages, and sort them into message classes. The message classes can be used to classify the type of the event described in the log message. The functionality of the pattern database is similar to that of the logcheck project, but the syslog-ng approach is faster, scales better, and is much easier to maintain compared to the regular expressions of logcheck.

The pdbtool application is a utility that can be used to:

• test messages, or specific rules

• convert an older pattern database to the latest database format

• merge pattern databases into a single file

• automatically create pattern databases from a large amount of log messages

• dump the RADIX tree built from the pattern database (or a part of it) to explore how the pattern matching works.

The dictionary command

dictionary [options]

Lists every name-value pair that can be set by the rules of the pattern database.

• --dump-tag or -T

  List the tags instead of the names of the name-value pairs.

• --pdb <path-to-file> or -p <path-to-file>

  Name of the pattern database file to use.

• --program <programname> or -P <programname>

  List only the name-value pairs that can be set for the messages of the specified ${PROGRAM} application.

The dump command

dump [options]

Display the RADIX tree built from the patterns. This shows how are the patterns represented in AxoSyslog and it might also help to track down pattern-matching problems. The dump utility can dump the tree used for matching the PROGRAM or the MSG parts.

• --debug or -d

  Enable debug/diagnostic messages on stderr.

• --pdb or -p

  Name of the pattern database file to use.

• --program or -P

  Displays the RADIX tree built from the patterns belonging to the ${PROGRAM} application.

• --program-tree or -T

  Display the ${PROGRAM} tree.

• --verbose or -v

  Enable verbose messages on stderr.

Example and sample output:

pdbtool dump -p patterndb.xml  -P 'sshd'

'p'
     'assword for'
    @QSTRING:@
      'from'
        @QSTRING:@
          'port '
        @NUMBER:@ rule_id='fc49054e-75fd-11dd-9bba-001e6806451b'
          ' ssh' rule_id='fc55cf86-75fd-11dd-9bba-001e6806451b'
             '2' rule_id='fc4b7982-75fd-11dd-9bba-001e6806451b'
     'ublickey for'
    @QSTRING:@
      'from'
        @QSTRING:@
          'port '
        @NUMBER:@ rule_id='fc4d377c-75fd-11dd-9bba-001e6806451b'
          ' ssh' rule_id='fc5441ac-75fd-11dd-9bba-001e6806451b'
             '2' rule_id='fc44a9fe-75fd-11dd-9bba-001e6806451b'
                

The match command

match [options]

Use the match command to test the rules in a pattern database. The command tries to match the specified message against the patterns of the database, evaluates the parsers of the pattern, and also displays which part of the message was parsed successfully. The command returns with a 0 (success) or 1 (no match) return code and displays the following information:

• the class assigned to the message (that is, system, violation, and so on),

• the ID of the rule that matched the message, and

• the values of the parsers (if there were parsers in the matching pattern).

The match command has the following options:

• --color-out or -c

  Color the terminal output to highlight the part of the message that was successfully parsed.

• --debug or -d

  Enable debug/diagnostic messages on stderr.

• --debug-csv or -C

  Print the debugging information returned by the --debug-pattern option as comma-separated values.

• --debug-pattern or -D

  Print debugging information about the pattern matching. See also the --debug-csv option.

• --file=<filename-with-path> or -f

  Process the messages of the specified log file with the pattern database. This option allows to classify messages offline, and to apply the pattern database to already existing logfiles. To read the messages from the standard input (stdin), specify a hyphen (-) character instead of a filename.

• --filter=<filter-expression> or -F

  Print only messages matching the specified AxoSyslog filter expression.

• --message or -M

  The text of the log message to match (only the ${MESSAGE} part without the syslog headers).

• --pdb or -p

  Name of the pattern database file to use.

• --program or -P

  Name of the program to use, as contained in the ${PROGRAM} part of the syslog message.

• --template=<template-expression> or -T

  An AxoSyslog template expression that is used to format the output messages.

• --verbose or -v

  Enable verbose messages on stderr.

Example

The following command checks if the patterndb.xml file recognizes the Accepted publickey for myuser from 127.0.0.1 port 59357 ssh6 message:

pdbtool match -p patterndb.xml -P sshd -M "Accepted publickey for myuser from 127.0.0.1 port 59357 ssh6"

Example

The following example applies the sshd.pdb pattern database file to the log messages stored in the /var/log/messages file, and displays only the messages that received a useracct tag.

   pdbtool match -p sshd.pdb \
                        –file /var/log/messages \
                    –filter ‘tags(“usracct”);’ 

The merge command

merge [options]

Use the merge command to combine separate pattern database files into a single file (pattern databases are usually stored in separate files per applications to simplify maintenance). If a file uses an older database format, it is automatically updated to the latest format (V3). See the AxoSyslog documentation for details on the different pattern database versions.

• --debug or -d

  Enable debug/diagnostic messages on stderr.

• --directory or -D

  The directory that contains the pattern database XML files to be merged.

• --glob or -G

  Specify filenames to be merged using a glob pattern, for example, using wildcards. For details on glob patterns, see man glob. This pattern is applied only to the filenames, and not on directory names.

• --pdb or -p

  Name of the output pattern database file.

• --recursive or -r

  Merge files from subdirectories as well.

• --sort or -s

  Sort files into alphabetic order during the merge (first sort by filename, then by directory name).

• --verbose or -v

  Enable verbose messages on stderr.

Example

pdbtool merge --recursive --directory /home/me/mypatterns/  --pdb /var/lib/syslog-ng/patterndb.xml

Currently it is not possible to convert a file without merging, so if you only want to convert an older pattern database file to the latest format, you have to copy it into an empty directory.

The patternize command

patternize [options]

Automatically create a pattern database from a log file containing a large number of log messages. The resulting pattern database is printed to the standard output (stdout). The pdbtool patternize command uses a data clustering technique to find similar log messages and replacing the differing parts with @ESTRING:: @ parsers. For details on pattern databases and message parsers, see the AxoSyslog documentation. The patternize command is available only in version 3.2 and later.

• --debug or -d

  Enable debug/diagnostic messages on stderr.

• --file=<path> or -f

  The logfile containing the log messages to create patterns from. To receive the log messages from the standard input (stdin), use -.

• --iterate-outliers or -o

  Recursively iterate on the log lines to cover as many log messages with patterns as possible.

• --named-parsers or -n

  The number of example log messages to include in the pattern database for every pattern. Default value: 1

• --no-parse or -p

  Do not parse the input file, treat every line as the message part of a log message.

• --samples=<number-of-samples>

  Include a generated name in the parsers, for example, .dict.string1, .dict.string2, and so on.

• --support=<number> or -S

  A pattern is added to the output pattern database if at least the specified percentage of log messages from the input logfile match the pattern. For example, if the input logfile contains 1000 log messages and the --support=3.0 option is used, a pattern is created only if the pattern matches at least 3 percent of the log messages (that is, 30 log messages). If patternize does not create enough patterns, try to decrease the support value.

  Default value: 4.0

• --verbose or -v

  Enable verbose messages on stderr.

Example

pdbtool patternize --support=2.5 --file=/var/log/messages

The test command

test [options]

Use the test command to validate a pattern database XML file. Note that you must have the xmllint application installed. The test command is available only in AxoSyslog version 3.2 and later.

• --color-out or -c

  Enable coloring in terminal output.

• --debug or -d

  Enable debug/diagnostic messages on stderr.

• --debug or -D

  Print debugging information on non-matching patterns.

• --rule-id or -r

  Test only the patterndb rule (specified by its rule id) against its example.

• --validate

  Validate a pattern database XML file.

• --verbose or -v

  Enable verbose messages on stderr.

Example

pdbtool test --validate /home/me/mypatterndb.pdb

Files

/opt/syslog-ng/

/opt/syslog-ng/etc/syslog-ng.conf

See also

syslog-ng.conf.5

syslog-ng.8

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

6 - The persist-tool manual page

Name

persist-tool — Display the content of the persist file

Synopsis

persist-tool [command] [options]

Description

The persist-tool application is a utility that can be used to dump the content of the persist file, and manipulate its content.

WARNING: Persist-tool is a special tool for AxoSyslog experts. Do not use the tool unless you know exactly what you are doing. Misconfiguring it will result in irrecoverable damage to the persist file, without any warning.

Limitations

Wildcard characters are not supported in file/directory names.

The dump command

Use the dump command to print the current content of the persist file in JSON format to the console.

dump <options;gt; <persist_file>

Example: persist-tool dump /opt/syslog-ng/var/syslog-ng.persist

The output looks like:

run_id = { "value": "00 00 00 00 0C 00 00 00 " }
host_id = { "value": "00 00 00 00 5F 49 2F 01 " }

The dump command has the following options:

• --help or -?

  Display a brief help message.

The add command

add <options> <input_file>

Use the add command to add or modify a specified state-entry in the persist file. The state-entry should be in the same format as the dump command displays it. If the given state-entry already exists, it will be updated. Otherwise, a new value will be added. If the given persist state is invalid, it will be skipped.

To use the add command: use persist-tool dump to print the content of the current persist file, and redirect it to a file. Edit the content of this file. Use persist-tool add with this file to modify the persist. The add command has the following options:

• --help or -?

  Display a brief help message.

• --output-dir=<directory> or -o

  Required parameter. The directory where the persist file is located at. The name of the persist file stored in this directory must be syslog-ng.persist.

Example: /opt/syslog-ng/bin/persist-tool add dump_persist -o .

The valid output looks like:

log_reader_curpos(Application)      OK
affile_sd_curpos(/var/aaa.txt)        OK

The invalid output looks like:

log_reader_curpos(Application)      OK
wrong
FAILED (error: Invalid entry syntax)
affile_sd_curpos(/var/aaa.txt)        OK

Files

/opt/syslog-ng/bin/persist-tool

See also

syslog-ng.conf.5

syslog-ng.8

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

7 - The secure-logging manual page

Name

secure-logging — Forward integrity and confidentiality for system logs.

Synopsis

$(slog --key-file <host key file> --mac-file <MAC file> $RAWMSG)

Description

Secure logging is an extension to AxoSyslog providing forward integrity and confidentiality of system logs. It is implemented in form of a module and is configured as a template in the AxoSyslog configuration file.

The main objective of the secure logging module is to provide tamper evident logging, i.e. to adequately protect log records of an information system and to provide a sensor indicating attack attempts. The secure logging module achieves this by authentically encrypting each log record with an individual cryptographic key used only once and protecting the integrity of the whole log archive by a cryptographic authentication code. Each attempt to tamper with either an individual log record or the log archive itself will be immediately detected during log archive verification. Therefore, an attacker can no longer tamper with log records without being detected.

In order to use the log file created by the secure logging module for analysis, the log file must first be decrypted and its integrity verified. This is achieved with a command line utility that is part of the secure logging module and is installed as part of the AxoSyslog package. This utility can easily be integrated into the import module of existing analysis environments.

The secure logging environment uses a cryptographic key for encrypting log entries. Each individual log entry is encrypted with its own key which is immediately discarded after successful encryption in order to provide forward integrity. An efficient algorithm generates the key for the next log entry based the key used for encrypting the previous log entry. The resulting chain of keys preserves forward integrity, i.e. a potential attacker cannot deduce the previous key from the current key.

In order to ease log verification and analysis, a sequence number is added to each log entry. This sequence number is also added to the encryption key creating a one-to-one correspondence of the encryption key with the log entry. In order to prevent truncation attacks or deletion of individual log entries, a message authentication code (MAC) is iteratively applied to the complete log archive and stored in a separate file. It is used upon verification to check the integrity of the whole log archive.

Here is an example of three short original log messages that will be sent to a destination with secure logging enabled:

This is a log message
And here comes another log message
This is a log message with a longer text that is processed without any problems

In order to inspect the status of the secure logging environment, one can check the sequence counter by querying the key file with the slogkey utility like this:

user@host:~> slogkey --counter /etc/syslog-ng/host.key 
counter=3

Counting starts at zero. This is why the counter is set to three after processing three messages.

The output of the secure logging template for the three example messages is shown below. One clearly sees the sequence number that was prepended to each message. The colon indicates the end of the sequence number and the start of the original message. As three message were processed, the sequence counter of the key will be three.

AAAAAAAAAAA=:k3/dYpLsgO2tUJKSauo6dycIBzW6OTC3pyA9TP+7AnqFgEojBzgC2rcK4OPfRtr8yg==
AQAAAAAAAAA=:smw0ATISVgN+BYEu5d7OLBE7aQhHpK9Ro4MndmNgSVrqhcmRCBCj6DUnD6ku0Z29CKJ0N6LAJUgByX4Ev+g=
AgAAAAAAAAA=:5UVybnKL1EAbgC4CLfd8HpgurjREf4LEN61/yWHSD2hbXjRD4QmQdtbwguT1chzdItKSQASps9QRIvR5Jd4AHzHfqxI4aRgdUBcNbAq26nwUCg5vPWygjmbtQaxZgCJYkry8slxCigmbTVs=

The output of a successful verification run is shown below.

0000000000000000: This is a log message
0000000000000001: And here comes another log message
0000000000000002: This is a log message with a longer text that is processed without any problems

The original log messages have been successfully restored. Additionally, the sequence counter is also prepended to the clear text messages. This helps when in analyzing problems with a particular log entry. As real log files will contain thousands of entries. the sequence counter eases identification of erroneous entries.

Before the secure logging module can be used as part of an existing AxoSyslog installation, several preparatory activities need to be performed.

Key generation

In order to bootstrap the system, an initial key k0 must be created and installed on the log host before secure logging environment is started for the first time.

The newly created host key k0 has its counter set to 0 indicating that it represents the initial host key k0. This host key k0 must be kept secret and not be disclosed to third parties. It will be required to successfully decrypt and verify log archives processed by the secure logging environment. As each log entry will be encrypted with its own key, a new host key will be created after successful processing of a log entry and will replace the previous key. Therefore, the initial host key needs to be stored in a safe place before starting the secure logging environment, as it will be deleted from the log host after processing of the first log entry. The following steps must be done before starting the secure logging environment. Steps 1 and 2 are performed with the slogkey utility. See the slogkey.1 manual page for details on how to generate a master key and to derive a host key from it. Step 3 and 4 depend on the actual deployment in a target environment.

1. Create a master key
2. Derive an initial host key k0 from a previously created master key1. Store the initial host key k0 in a safe location outside of the log host
3. Deploy the key k0 on the log host where the secure logging module will be used

Configuration

Secure logging is configured by adding the corresponding statements to the syslog-ng.conf file.

Secure logging is implemented as a template and is configured accordingly. Apart from the actual template configuration, no other settings are required in order to activate secure logging. The secure logging is activated by placing the following statement in the configuration file.

template("$(slog --key-file  <host key file> --mac-file <MAC file> $RAWMSG)\n");

where:

• slog

  The name of the secure logging template function. This name can be also be found by calling syslog-ng with the --module-registry arguments and checking the template-func property of the secure logging module in the corresponding output.

• --key-file or -k

  The host key. <host key file> is the full path of the file storing the host key on the log host. If this arguments is not supplied or does not point to a valid regular key file, syslog-ng will not start and a display a corresponding error message.

• --mac-file or -m

  The MAC file. <MAC file> is the full path of the MAC file on the log host. The file does not need to exist, as it will be automatically created upon the initial start. If the path is not correct, syslog-ng will not start and a display a corresponding error message.

• $RAWMSG

  $RAWMSG provides access to the original log message received at the source. This macro is only available if the store-raw-message flag was set for the source. Otherwise, an empty string will be passed to the secure logging template. If access to the original message is not available, for example, if the source does not support the store-raw-message flag, then the $MSG macro can also be used. In this case, however, the integrity guarantee provided by secure logging is limited to the content that this macro provides and does not protect the complete original message.

• \n

  \n is the line separator. This is important, as the secure logging template expects log entries to be separated by a line separator. When detecting a line separator, the log entry is regarded as complete and is encrypted with the current host key. Therefore, only a single line separator is allowed.

The secure logging template can be combined with any source or destination within the following limitations:

• Sources must be line-oriented. Secure logging uses a line separator in order to distinguish between individual log entries. Sources which provide data in a different format, for example, in the form of raw data obtained directly from a database system, cannot currently be used with the secure logging template, as the separation of log entries is not clearly defined for this type of data.

• Only sources for which the store-raw-message flag is implemented and set do benefit from the integrity guarantee provided by the secure logging template. Secure logging aims at protecting the integrity of complete log messages including all associated meta-data, such as timestamps and host names. syslog-ng parses the log message into its internal format and provide easy access to parts of a message through macros. While this is convenient when rewriting log messages, it is not helpful for secure logging. syslog-ng provides the store-raw-message flag which provides access to a copy of the original log message after parsing. This is the log message processed and protected by the secure logging template. If the source does not support the store-raw-message flag, then the $MSG macro can also be used. However, in this case the integrity guarantee provided by secure logging is limited to the content that this macro provides.

• Log rotation of any kind cannot be used with destinations using secure logging. The reason is that log rotate will overwrite, i.e. delete previous log files. This destroys the cryptographic chain of trust of the log entries making recovery impossible. In order to allow for a an efficient handling of log files, the secure logging environment features iterative verification. Using iterative verification, a log file can be verified in steps. For this to work, the log file must first be downloaded from the log host, together with the corresponding host key and MAC file to a verification host. After this download the log file can be safely deleted from the log host. Verification is then performed on the verification host using the iterative mode of the slogverify utility.

The following example configuration shows the use of the secure logging template on a file destination.

#############################################
# Minimal syslog-ng.conf file with secure logging enabled. Encrypted log
# entries will be logged to a single file called /var/log/messages.slog
#

@version: 4.4
@include "scl.conf"

source s_local {
    system();
    internal();
};

source s_network {
    network(
        transport("udp")
        port(514)
        flags(store-raw-message)
    );
};

# Secure logging template definition
template secure_logging { 
    template("$(slog --key-file /etc/syslog-ng/host.key --mac-file /etc/syslog-ng/mac.dat $RAWMSG)\n");
};

# This configures a secure logging destination
destination d_local {
    file("/var/log/messages.slog" template(secure_logging));
};

log {
    source(s_local);

    # This source has the raw message flag set
    source(s_network);

    # This statement activates secure logging for this destination
    destination(d_local);
};

Log Verification

In order to analyze the log file created in a secure logging environment, the log files must be decrypted and their integrity be verified. Verification requires both the initial host key k0 and the corresponding MAC file and is performed with the slogverify utility. It is not normally performed on the log host where the secure logging environment is producing log data. In a typical deployment, log files would be retrieved from the log host and transferred to a central log collector where verification it performed. As verification requires the use of the initial host key k0, it should only be performed in a trusted environment.

Normal mode

In normal mode, a complete log archive is verified at once. In a typical environment, this would mean retrieving a log file together with is MAC file from a log host and retrieving the corresponding initial key k0 form a safe location and supplying them to the slogverify utility. A typical call sequence for verification in normal mode would look like this:

slogverify --key-file host0.key --mac-file mac.dat /var/log/messages.slog /var/log/verified/messages

where:

• host0.key

  The initial host key k0. Supplying the initial key k0 is enough for decrypting all log entries, as the key derivation algorithm is able to generate the necessary keys for all subsequent log entries based on the initial key k0.

• mac.dat

  The MAC file from the log host.

• /var/log/messages.slog

  The file containing the encrypted log entries as retrieved from a log host.

• /var/log/verified/messages

  The file receiving the plain text log after decryption.

Log files may become large and not fit into system memory. Verification is therefore performed in chunks. Each part of the log file is transferred to an internal buffer on which verification is performed. After the buffer has been processed, the next chunk is fetched. An optional buffer argument can be supplied to the slogverify utility in order to change the default buffer size of 1000 log entries to a number suitable for the system on which the verification is performed, for example:

slogverify --key-file host.key --mac-file mac.dat /var/log/messages.slog /var/log/verified/messages 8000

See slogverify for details on verification in normal mode.

Iterative mode

Verification in normal mode may not be suitable for some application scenarios. Many log hosts use log rotation in order to preserve storage space. In log rotation, a threshold for the maximum amount of storage space and the number of generations is defined for different type of log files. When either storage space is exhausted or the number of generations is reached, the oldest log file will be overwritten by new incoming log data. This procedure is not possible in secure logging environment, as overwriting, i.e. deleting a log file would break the cryptographic chain that is established between the log entries. This comes as no surprise, as one of the main objectives of secure logging is to protect against deletion of log entries by a potential attacker.

In order allow for a procedure similar to log rotation, the secure logging environment features an iterative mode. In iterative mode, log files can be split into different files and each of these files can be verified separately. Care must be taken when performing verification in iterative mode, as each of the different log files needs to be accompanied by a copy of the host key and the MAC files present on the system at the time of retrieval. A typical usage scenario for the iterative mode would look like this:

1. Define a storage threshold for the secure logging file destination. In this example we assume 500MB.
2. Let the secure logging environment produce log data that is written to the destination until 500MB are reached.
3. Stop the secure logging environment and retrieve the log file, the host key and the MAC files from the log host.
4. Delete the log file on the log host but leave host key and MAC file untouched.
5. Restart the secure logging environment.
6. Perform verification in iterative mode with the log file, the host key and the MAC just retrieved.

Steps 2-6 have to repeated each time the log file reaches a size of 50 MB. Assuming that the log file parts will be named after the iteration, e.g. log.1, log.2, log.3, etc. and a similar convention is applied to the host keys and MAC files, a typical call sequence for the validation of a log file part in iterative mode after three iterations will look like this:

slogverify --iterative --prev-key-file host.key.2 --prev-mac-file mac.dat.2 --mac-file mac.dat /var/log/messages.slog.3 /var/log/verified/messages.3

where:

• host.key.2

  The host key from the previous iteration. In this example, this is the second iteration.

• mac.dat.2

  The MAC file from the previous iteration. In the example, verification is performed during the third iteration, so the MAC file from the second iteration is required.

• mac.dat

  The current MAC file from the log host.

• /var/log/messages.slog.3

  The file part containing the encrypted log entries as retrieved from the log host during the third iteration.

• /var/log/verified/messages.3

  The file receiving the plain text log after decryption during the third iteration.

In a real deployment, the above steps would typically be automated using a scripting engine. See slogverify(1) for details on verification in iterative mode.

Files

/usr/bin/slogkey

/usr/bin/slogencrypt

/usr/bin/slogverify

/etc/syslog-ng.conf

See also

syslog-ng.conf.5

slogkey.1

slogencrypt.1

slogverify.1

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

8 - The slogencrypt manual page

Name

slogencrypt — Encrypt existing plain text log files using the AxoSyslog secure logging environment.

Synopsis

slogencrypt [options] [arguments]

Description

The slogencrypt utility is used to encrypt plain text log file using an existing secure logging environment. Using this utility, log files obtained from a previous installation of syslog-ng or another logging system can be transferred to a secure logging environment. The order of the log entries is preserved. Encrypting plain text log files using an existing secure logging environment, requires the current encryption key to be supplied in order to preserve consistency.

General call sequence: slogencrypt -k <key file> -m <MAC file> <new key file> <new MAC file> <plain text log> <output file> [counter]

Arguments

• <new key file>

  The file that will contain the new current encryption key after successful encryption.

• <new MAC file>

  The file receiving the new current message authentication code (MAC) of the secure encrypted destination after encryption. In case an existing file is supplied, new entries will be appended.

• <input log file>

  The plain text log file that will be encrypted using the secure logging environment.

• <output log file>

  The file that will contain the encrypted log entries from the supplied plain text log file after encryption.

• counter

  The current log entry counter of the secure encrypted destination after encryption. This is required if the log entries to be encrypted will be appended to an existing secure encrypted destination.

Options

• --key-file or -k

  The current host key from the system where the encryption will be performed.

• --mac-file or -m

  The current MAC file from the system where the encryption will be performed.

• --help or -h

  Display a help message.

Files

/usr/bin/slogencrypt

/etc/syslog-ng.conf

See also

syslog-ng.conf.5

syslog-ng.8

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

9 - The slogkey manual page

Name

slogkey — Manage cryptographic keys for use with the AxoSyslog secure logging environment.

Synopsis

slogkey [options] [arguments]

Description

The slogkey utility is used to manage cryptographic keys for use with the secure logging module of AxoSyslog. Use this utility to create a master key, derive a host key to be used by a secure logging configuration and to display the current sequence counter of a key. The options determine the operating mode and are mutually exclusive.

Arguments

The arguments depend on the operating mode.

• Master key generation

  Call sequence: slogkey --master-ḱey <filename>

  <filename>: The name of the file to which the master key will be written.

• Host key derivation

  Call sequence: slogkey --derive-key <master key file> <host MAC address> <host serial number> <host key file>

  • <master key file>: The master key from which the host key will be derived.
  • <host MAC address>: The MAC address of the host on which the key will be used. Instead of the MAC address, any other string that uniquely identifies a host can be supplied, e.g. the company inventory number.
  • <host serial number>: The serial number of the host on which the key will be used. Instead of the serial number, any other string that uniquely identifies a host can be supplied, for example, the company inventory number.
  • <host key file>: The name of the file to which the host key will be written.

  NOTE: The newly created host key has its counter set to 0 indicating that it represents the initial host key k0. This host key must be kept secret and not be disclosed to third parties. It will be required to successfully decrypt and verify log archives processed by the secure logging environment. As each log entry will be encrypted with its own key, a new host key will be created after successful processing of a log entry and will replace the previous key. Therefore, the initial host key needs to be stored in a safe place before starting the secure logging environment, as it will be deleted from the log host after processing of the first log entry.

• Sequence counter display

  Call sequence: slogkey --counter <host key file>

  • <host key file>: The host key file from which the sequence will be read.

Options

• --master-key or -m

  Generates a mew master key. <filename> is the name of the file storing the newly generated master key.

• --derive-key or -d

  Derive a host key using a previously generated master key.

• --counter or -c

  Display the current log sequence counter of a key.

• --help or -h

  Display a help message.

Files

/usr/bin/slogkey

/etc/syslog-ng.conf

See also

syslog-ng.conf.5

secure-logging.7

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

10 - The slogverify manual page

Name

slogverify — Verify cryptographically secured logs.

Synopsis

slogverify [options] [arguments]

Description

The slogverify utility is used to verify the integrity of cryptographically secured logs and to decrypt log entries produced in a AxoSyslog secure logging environment.

• Normal mode: slogverify -k <host key file> -m <input MAC file> <input file> <output file> [buffers]
• Iterative mode: slogverify -i -p <previous host key> -r <previous MAC> -m <current MAC> <input file> <output file> [buffers]

Arguments

• input file

  An encrypted log file from the syslog-ng secure logging environment that will be verified.

• output file

  The file that will contain the plain text log entries after decryption and verification.

• buffers

  Optional number of input buffers. The number of buffers can be used for performance adjustments in case the log file to be verified is very large and cannot be processed at once. It is a positive number of log entries that can be held in memory during verification. The minimum number if 10 and the maximum number is 4294967295. If this argument is not supplied the default of 1000 is used.

Options

• --iterative or -i

  Iterative mode. This is useful in case the log files are periodically copied from the system on which they where generated to central collector. As log rotation, i.e. overwriting log files in order to preserve space cannot be done in a secure logging environment, the iterative mode can be used instead. This works as follows: If a certain storage limit is reached the log file together with the host key and the MAC file is copied to new destination and the old file is deleted. The verification is then performed in iterations, i.e. separately for each file that was retrieved from the log host. For this to work, it is important to always retrieve the corresponding host key and MAC files. The process can be automated, e.g. by calling slogverify in iterative mode from a script.<

• --key-file or -k

  The initial host key (k0). This option is used in normal mode only.

• --mac-file or -m

  The current MAC file used.

• --prev-key-file or -p

  The host key corresponding to the previous log file. This option can be used in iterative mode only. In theory, this can be initial host key (k0) but using this key might generate warnings, as the gap between the first log entry ever (log entry 0) and the first log entry of the current log file might be large.

• --prev-mac-file or -r

  The MAC file from the previous log file. This option can only be used in iterative mode.

• --help or -h

  Display a help message.

Files

/usr/bin/slogverify

/etc/syslog-ng.conf

See also

syslog-ng.conf.5

secure-logging.7

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

11 - The syslog-debun manual page

Name

syslog-debun — syslog-ng DEBUg buNdle generator

Synopsis

syslog-debun [options]

Description

The syslog-debun tool collects and saves information about your AxoSyslog installation, making troubleshooting easier, especially if you ask help about your AxoSyslog related problem.

General Options

• -r

  Run syslog-ng-debun. Using this option is required to actually execute the data collection with syslog-ng-debun. It is needed to prevent accidentally running syslog-ng-debun.

• -h

  Display the help page.

• -l

  Do not collect privacy-sensitive data, for example, process tree, fstab, and so on. If you use with -d, then the following parameters will be used for debug mode:-Fev

• -R <directory>

  The directory where AxoSyslog is installed instead of /opt/syslog-ng.

• -W <directory>

  Set the working directory, where the debug bundle will be saved. Default value: /tmp. The name of the created file is syslog.debun.${host}.${date}.${3-random-characters-or-pid}.tgz

Debug mode options

• -d

  Start AxoSyslog in debug mode, using the -Fedv --enable-core options.

  Warning Using this option under high message load may increase disk I/O during the debug, and the resulting debug bundle can be huge. To exit debug mode, press Enter.

• -D <options>

  Start AxoSyslog in debug mode, using the specified command-line options. To exit debug mode, press Enter.

  • -t <seconds>

    Run AxoSyslog in non-interactive debug mode for <seconds>, and automatically exit debug mode after the specified number of seconds.

• -w <seconds>

  Wait <seconds> seconds before starting debug mode.

System call tracing

• -s

  Enable syscall tracing (strace -f or truss -f). Note that using -s itself does not enable debug mode, only traces the system calls of an already running AxoSyslog process. To trace system calls in debug mode, use both the -s and -d options.

Packet capture options

Capturing packets requires a packet capture tool on the host. The syslog-debun tool attempts to use tcpdump on most platforms, except for Solaris, where it uses snoop.

• -i <interface>

  Capture packets only on the specified interface, for example, eth0.

• -p

  Capture incoming packets using the following filter: port 514 or port 601 or port 53

• -P <options>

  Capture incoming packets using the specified filter.

• -t <seconds>

  Run AxoSyslog in non-interactive debug mode for <seconds>, and automatically exit debug mode after the specified number of seconds.

Examples

syslog-ng-debun -r

Create a simple debug bundle, collecting information about your environment, for example, list packages containing the word: syslog, ldd of your syslog-binary, and so on.

syslog-ng-debun -r -l

Similar to syslog-ng-debun -r, but without privacy-sensitive information. For example, the following is NOT collected: fstab, df output, mount info, ip / network interface configuration, DNS resolve info, and process tree.

syslog-ng-debun -r -d

Similar to syslog-ng-debun -r, but it also stops AxoSyslog, then restarts it in debug mode (-Fedv --enable-core). To stop debug mode, press Enter. The output of the debug mode collected into a separate file, and also added to the debug bundle.

syslog-ng-debun -r -s

Trace the system calls (using strace or truss) of an already running AxoSyslog process.

syslog-ng-debun -r -d -s

Restart AxoSyslog in debug mode, and also trace the system calls (using strace or truss) of the AxoSyslog process.

syslog-ng-debun -r -p

Run packet capture (pcap) with the filter: port 514 or port 601 or port 53 Also waits for pressing Enter, like debug mode.

syslog-ng-debun -r -p -t 10

Noninteractive debug mode: Similar to syslog-ng-debun -r -p, but automatically exit after 10 seconds.

syslog-ng-debun -r -P "host 1.2.3.4"  -D "-Fev --enable-core"

Change the packet-capturing filter from the default to host 1.2.3.4. Also change debugging parameters from the default to -Fev --enable-core. Since a timeout (-t) is not given, waits for pressing Enter.

syslog-ng-debun -r -p -d -w 5 -t 10

Collect pcap and debug mode output following this scenario:

• Start packet capture with default parameters (-p)
• Wait 5 seconds (-w 5)
• Stop AxoSyslog
• Start AxoSyslog in debug mode with default parameters (-d)
• Wait 10 seconds (-t 10)
• Stop AxoSyslog debugging
• Start AxoSyslog
• Stop packet capturing

Files

/opt/syslog-ng/bin/loggen

See also

syslog-ng.conf.5

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow

12 - The syslog-ng control tool manual page

Name

syslog-ng-ctl — Display message statistics and enable verbose, debug and trace modes

Synopsis

syslog-ng-ctl [command] [options]

Description

The syslog-ng-ctl application is a utility that can be used to:

• enable/disable various AxoSyslog messages for troubleshooting

• display statistics about the processed messages

• handling password-protected private keys

• display the currently running configuration of AxoSyslog

• reload the configuration of AxoSyslog.

Enabling troubleshooting messages

syslog-ng-ctl log-level <level>

Available in AxoSyslog 4.0 and later.

Use the syslog-ng-ctl log-level <level> command to display verbose, trace, or debug messages. If you are trying to solve configuration problems, the verbose (and occasionally debug) messages are usually sufficient. Trace messages are needed mostly for finding software errors. After solving the problem, do not forget to return the log level to the default using the syslog-ng-ctl log-level default command.

Use syslog-ng-ctl log-level without any parameters to display the current log level.

If AxoSyslog was started with the --stderr or -e option, the messages will be sent to stderr. If not specified, AxoSyslog will log such messages to its internal source.

If you need to use a non-standard control socket to access syslog-ng, use the syslog-ng-ctl <command> --control=<socket> command to specify the socket to use.

Higher log-levels automatically include messages from lower log-levels:

• default: Just normal log messages.
• verbose: Normal and verbose log messages.
• debug: Include debug messages of AxoSyslog.
• trace: Include trace messages of how messages are processed.

Example

syslog-ng-ctl log-level verbose

To temporarily change the log levels and access the logs of syslog-ng, see also the attach command.

syslog-ng-ctl query

The AxoSyslog application stores various data, metrics, and statistics in a hash table. Every property has a name and a value. For example:

[syslog-ng]
  |       
  |_[destinations]-[network]-[tcp]->[stats]->{received=12;dropped=2}
  |
  |_[sources]-[sql]-[stats]->{received=501;dropped=0}

You can query the nodes of this tree, and also use filters to select the information you need. A query is actually a path in the tree. You can also use the ? and * wildcards. For example:

• Select every property: *

• Select all dropped value from every stats node: *.stats.dropped

The nodes and properties available in the tree depend on your AxoSyslog configuration (that is, the sources, destinations, and other objects you have configured), and also on your stats-level() settings.

The list command

syslog-ng-ctl query list

Use the syslog-ng-ctl query list command to display the list of metrics that AxoSyslog collects about the processed messages.

An example output:

  center.received.stats.processed
  center.queued.stats.processed
  destination.java.d_elastic#0.java_dst(ElasticSearch,elasticsearch-syslog-ng-test,t7cde889529c034aea9ec_micek).stats.dropped
  destination.java.d_elastic#0.java_dst(ElasticSearch,elasticsearch-syslog-ng-test,t7cde889529c034aea9ec_micek).stats.processed
  destination.java.d_elastic#0.java_dst(ElasticSearch,elasticsearch-syslog-ng-test,t7cde889529c034aea9ec_micek).stats.queued
  destination.d_elastic.stats.processed
  source.s_tcp.stats.processed
  source.severity.7.stats.processed
  source.severity.0.stats.processed
  source.severity.1.stats.processed
  source.severity.2.stats.processed
  source.severity.3.stats.processed
  source.severity.4.stats.processed
  source.severity.5.stats.processed
  source.severity.6.stats.processed
  source.facility.7.stats.processed
  source.facility.16.stats.processed
  source.facility.8.stats.processed
  source.facility.17.stats.processed
  source.facility.9.stats.processed
  source.facility.18.stats.processed
  source.facility.19.stats.processed
  source.facility.20.stats.processed
  source.facility.0.stats.processed
  source.facility.21.stats.processed
  source.facility.1.stats.processed
  source.facility.10.stats.processed
  source.facility.22.stats.processed
  source.facility.2.stats.processed
  source.facility.11.stats.processed
  source.facility.23.stats.processed
  source.facility.3.stats.processed
  source.facility.12.stats.processed
  source.facility.4.stats.processed
  source.facility.13.stats.processed
  source.facility.5.stats.processed
  source.facility.14.stats.processed
  source.facility.6.stats.processed
  source.facility.15.stats.processed
  source.facility.other.stats.processed
  global.payload_reallocs.stats.processed
  global.msg_clones.stats.processed
  global.sdata_updates.stats.processed
  tag..source.s_tcp.stats.processed

The syslog-ng-ctl query list command has the following options:

• --reset

  Use --reset to set the selected counters to 0 after executing the query, except for the queued and the memory_usage counters. (The queued counters show the number of messages in the message queue of the destination driver, waiting to be sent to the destination. The memory_usage counters show the amount of memory used by the messages in the different queue types (in bytes). This includes every queue used by the object, including memory buffers (log-fifo) and disk-based buffers (both reliable and non-reliable))

Displaying metrics and statistics

syslog-ng-ctl query get [options]

The syslog-ng-ctl query get <query> command lists the nodes that match the query, and their values.

For example, the destination query lists the configured destinations, and the metrics related to each destination. An example output:

destination.java.d_elastic#0.java_dst(ElasticSearch,elasticsearch-syslog-ng-test,t7cde889529c034aea9ec_micek).stats.dropped=0
destination.java.d_elastic#0.java_dst(ElasticSearch,elasticsearch-syslog-ng-test,t7cde889529c034aea9ec_micek).stats.processed=0
destination.java.d_elastic#0.java_dst(ElasticSearch,elasticsearch-syslog-ng-test,t7cde889529c034aea9ec_micek).stats.queued=0
destination.d_elastic.stats.processed=0

The syslog-ng-ctl query get command has the following options:

• --sum

  Add up the result of each matching node and return only a single number.

  For example, the syslog-ng-ctl query get --sum "destination*.dropped" command displays the number of messages dropped by the AxoSyslog instance.

• --reset

  Use --reset to set the selected counters to 0 after executing the query, except for the queued and the memory_usage counters. (The queued counters show the number of messages in the message queue of the destination driver, waiting to be sent to the destination. The memory_usage counters show the amount of memory used by the messages in the different queue types (in bytes). This includes every queue used by the object, including memory buffers (log-fifo) and disk-based buffers (both reliable and non-reliable))

The stats command

stats [options]

Use the stats command to display statistics about the processed messages. For details about the displayed statistics, see The AxoSyslog documentation. The stats command has the following options:

• --control=<socket> or -c

  Specify the socket to use to access AxoSyslog. Only needed when using a non-standard socket.

• --reset=<socket> or -r

  Reset all statistics to zero, except for the queued and the memory_usage counters. (The queued counters show the number of messages in the message queue of the destination driver, waiting to be sent to the destination. The memory_usage counters show the amount of memory used by the messages in the different queue types (in bytes). This includes every queue used by the object, including memory buffers (log-fifo) and disk-based buffers (both reliable and non-reliable))

• --remove-orphans

  Safely removes all counters that are not referenced by any syslog-ng stat producer objects.

  The flag can be used to prune dynamic and static counters manually. This is useful, for example, when a templated file destination produces a lot of stats:

      dst.file;#anon-destination0#0;/tmp/2021-08-16.log;o;processed;253592
      dst.file;#anon-destination0#0;/tmp/2021-08-17.log;o;processed;156
      dst.file;#anon-destination0#0;/tmp/2021-08-18.log;a;processed;961
  

  Note The stats-lifetime() can be used to do the same automatically and periodically, but currently stats-lifetime() removes only dynamic counters that have a timestamp field set.

Example

syslog-ng-ctl stats

An example output:

src.internal;s_all#0;;a;processed;6445
src.internal;s_all#0;;a;stamp;1268989330
destination;df_auth;;a;processed;404
destination;df_news_dot_notice;;a;processed;0
destination;df_news_dot_err;;a;processed;0
destination;d_ssb;;a;processed;7128
destination;df_uucp;;a;processed;0
source;s_all;;a;processed;7128
destination;df_mail;;a;processed;0
destination;df_user;;a;processed;1
destination;df_daemon;;a;processed;1
destination;df_debug;;a;processed;15
destination;df_messages;;a;processed;54
destination;dp_xconsole;;a;processed;671
dst.tcp;d_network#0;10.50.0.111:514;a;dropped;5080
dst.tcp;d_network#0;10.50.0.111:514;a;processed;7128
dst.tcp;d_network#0;10.50.0.111:514;a;queued;2048
destination;df_syslog;;a;processed;6724
destination;df_facility_dot_warn;;a;processed;0
destination;df_news_dot_crit;;a;processed;0
destination;df_lpr;;a;processed;0
destination;du_all;;a;processed;0
destination;df_facility_dot_info;;a;processed;0
center;;received;a;processed;0
destination;df_kern;;a;processed;70
center;;queued;a;processed;0
destination;df_facility_dot_err;;a;processed;0

Handling password-protected private keys

syslog-ng-ctl credentials [options]

The syslog-ng-ctl credentials status command allows you to query the status of the private keys that AxoSyslog uses in the network() and syslog() drivers. You can also provide the passphrase for password-protected private keys using the syslog-ng-ctl credentials add command. For details on using password-protected keys, see The syslog-ng Administrator Guide.

Displaying the status of private keys

syslog-ng-ctl credentials status [options]

The syslog-ng-ctl credentials status command allows you to query the status of the private keys that AxoSyslog uses in the network() and syslog() drivers. The command returns the list of private keys used, and their status. For example:

  syslog-ng-ctl credentials status
  Secret store status:
  /home/user/ssl_test/client-1/client-encrypted.key SUCCESS

If the status of a key is PENDING, you must provide the passphrase for the key, otherwise AxoSyslog cannot use it. The sources and destinations that use these keys will not work until you provide the passwords. Other parts of the AxoSyslog configuration will be unaffected. You must provide the passphrase of the password-protected keys every time AxoSyslog is restarted.

The following log message also notifies you of PENDING passphrases:

Waiting for password; keyfile='private.key'

• --control=<socket> or -c

  Specify the socket to use to access AxoSyslog. Only needed when using a non-standard socket.

Opening password-protected private keys

syslog-ng-ctl credentials add [options]

You can add the passphrase to a password-protected private key file using the following command. AxoSyslog will display a prompt for you to enter the passphrase. We recommend that you use this method.

syslog-ng-ctl credentials add --id=<path-to-the-key>

Alternatively, you can include the passphrase in the --secret parameter:

syslog-ng-ctl credentials add --id=<path-to-the-key> --secret=<passphrase-of-the-key>

Or you can pipe the passphrase to the syslog-ng-ctl command, for example:

echo "<passphrase-of-the-key>" | syslog-ng-ctl credentials add --id=<path-to-the-key>

• --control=<socket> or -c

  Specify the socket to use to access AxoSyslog. Only needed when using a non-standard socket.

• --id=<path-to-the-key> or -i

  The path to the password-protected private key file. This is the same path that you use in the key-file() option of the AxoSyslog configuration file.

• --secret=<passphrase-of-the-key> or -s

  The password or passphrase of the private key.

Displaying the configuration

syslog-ng-ctl config [options]

Use the syslog-ng-ctl config command to display the configuration that AxoSyslog is currently running. By default, only the content of the main configuration file is displayed, included files are not resolved. To resolve included files and display the entire configuration, use the syslog-ng-ctl config --preprocessed command.

Starting with AxoSyslog version 4.2, you can display the configuration identifier (if set) and the SHA256 has of the output of the syslog-ng-ctl config --preprocessed command by running syslog-ng-ctl config --id. For details, see Configuration identifier.

List referenced files

You can use the syslog-ng-ctl list-files command to list files referenced in your configuration, for example, certificates or external configuration files. Available in AxoSyslog 3.23.1 and later.

Reloading the configuration

syslog-ng-ctl reload [options]

Use the syslog-ng-ctl reload command to reload the configuration file of AxoSyslog without having to restart the AxoSyslog application. The syslog-ng-ctl reload works like a SIGHUP.

The syslog-ng-ctl reload command returns 0 if the operation was successful, 1 otherwise.

The healthcheck command

Available in AxoSyslog 4.2 and later.

You can use the syslog-ng-ctl healthcheck command to query the healthcheck status of AxoSyslog. The following health values are reported:

• mainloop_io_worker_roundtrip_latency_nanoseconds: mainloop->io-worker-job->mainloop roundtrip - a basic latency measure for AxoSyslog.
• io_worker_latency_nanoseconds: io-worker-job start latency.
• syslogng_internal_events_queue_usage_ratio: If you are using the internal() source in your configuration, then this value shows the saturation of the internal source’s queue, ranging from 0 to 1. Non-zero values indicate some kind of disruption in the pipelines.

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

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

The attach command

Available in AxoSyslog 4.9 and later.

Connect to the standard IO (stdin, stdout, stderr) and display the results. Note that there can only be one attached process at a time.

syslog-ng-ctl attach [attach-mode] [options]

The syslog-ng-ctl attach command has the following parameters:

• Attach mode: logs or stdio.

  • Use logs to access the internal log messages of syslog-ng. For example, the following command changes the log level to trace and accesses the internal logs of syslog-ng:

    syslog-ng-ctl attach logs --seconds 10 --log-level trace
    

  • Use stdio to display the output of the syslog-ng process. For example:

    syslog-ng-ctl attach stdio --seconds 10
    

• Change log-level to the specified value:

  Higher log-levels automatically include messages from lower log-levels:

  • default: Just normal log messages.
  • verbose: Normal and verbose log messages.
  • debug: Include debug messages of AxoSyslog.
  • trace: Include trace messages of how messages are processed.

• How long to attach to the process: --seconds. For example:

  syslog-ng-ctl attach stdio --seconds 10
  

Files

/opt/syslog-ng/sbin/syslog-ng-ctl

See also

syslog-ng.conf.5

syslog-ng.8

Getting help

• The up-to-date documentation of AxoSyslog is available on the AxoSyslog documentation site.
• For news and notifications about AxoSyslog, visit the Axoflow blog.
• If you want to contact the developers directly to help with problems or report issues, contact us on Discord or GitHub.

This manual page is maintained by Axoflow