syslog-ng Open Source Edition 3.16 - Administration Guide

amqp: Publishing messages using AMQP

The amqp() driver publishes messages using the AMQP (Advanced Message Queuing Protocol). syslog-ng OSE supports AMQP versions 0.9.1 and 1.0. The syslog-ng OSE amqp() driver supports persistence, and every available exchange types.

The name-value pairs selected with the value-pairs() option will be sent as AMQP headers, while the body of the AMQP message is empty by default (but you can add custom content using the body() option). Publishing the name-value pairs as headers makes it possible to use the Headers exchange-type and subscribe only to interesting log streams. This solution is more flexible than using the routing-key() option.

For the list of available parameters, see amqp() destination options.

amqp( host("<amqp-server-address>") );

destination d_amqp {
    amqp(
        vhost("/")
        host("127.0.0.1")
        port(5672)
        exchange("syslog")
        exchange-type("fanout")
        routing-key("")
        body("")
        persistent(yes)
        value-pairs(
            scope("selected-macros" "nv-pairs" "sdata")
        )
    );
};

amqp() destination options

The amqp() driver publishes messages using the AMQP (Advanced Message Queuing Protocol).

The amqp() destination has the following options:

An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.

Declaration:

destination  d_ampqp {
    amqp(
        host("127.0.0.1")
        port(5672)
        username("test")
        password("test")
        tls(
            ca-file("ca")
            cert-file("cert") 
            key-file("key")
            peer-verify(yes|no)
        )
    );
};

Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.

cert-file()

Description: Name of a file, that contains an X.509 certificate (or a certificate chain) in PEM format, suitable as a TLS certificate, matching the private key set in the key-file() option. The syslog-ng OSE application uses this certificate to authenticate the syslog-ng OSE client on the destination server. If the file contains a certificate chain, the file must begin with the certificate of the host, followed by the CA certificate that signed the certificate of the host, and any other signing CAs in order.

An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.

Declaration:

destination  d_ampqp {
    amqp(
        host("127.0.0.1")
        port(5672)
        username("test")
        password("test")
        tls(
            ca-file("ca")
            cert-file("cert") 
            key-file("key")
            peer-verify(yes|no)
        )
    );
};

Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.

disk-buffer()

Description: This option enables putting outgoing messages into the disk buffer of the destination to avoid message loss in case of a system failure on the destination side. It has the following options:

Options reliable() and disk-buf-size() are required options.

destination d_demo {
    network(
        "127.0.0.1"
        port(3333)
        disk-buffer(
            mem-buf-size(10000)
            disk-buf-size(2000000)
            reliable(yes)
            dir("/tmp/disk-buffer")
        )
    );
};

destination d_demo {
    network(
        "127.0.0.1"
        port(3333)
           disk-buffer(
            mem-buf-length(10000)
            disk-buf-size(2000000)
            reliable(no)
            dir("/tmp/disk-buffer")
        )
    );
};

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.

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:

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:

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

key-file()

Description: The name of a file that contains an unencrypted private key in PEM format, suitable as a TLS key. If properly configured, the syslog-ng OSE application uses this private key and the matching certificate (set in the cert-file() option) to authenticate the syslog-ng OSE client on the destination server.

An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.

Declaration:

destination  d_ampqp {
    amqp(
        host("127.0.0.1")
        port(5672)
        username("test")
        password("test")
        tls(
            ca-file("ca")
            cert-file("cert") 
            key-file("key")
            peer-verify(yes|no)
        )
    );
};

Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.

peer-verify()

Description: Verification method of the peer. The following table summarizes the possible options and their results depending on the certificate of the peer.

For untrusted certificates only the existence of the certificate is checked, but it does not have to be valid — syslog-ng accepts the certificate even if it is expired, signed by an unknown CA, or its CN and the name of the machine mismatches.

An alternative way to specify this option is to put into a tls() block and specify it there, together with any other TLS options. This allows you to separate these options and ensure better readability.

Declaration:

destination  d_ampqp {
    amqp(
        host("127.0.0.1")
        port(5672)
        username("test")
        password("test")
        tls(
            ca-file("ca")
            cert-file("cert") 
            key-file("key")
            peer-verify(yes|no)
        )
    );
};

Make sure that you specify TLS options either using their own dedicated option (ca-file(), cert-file(), key-file(), and peer-verify()), or using the tls() block and inserting the relevant options within tls(). Avoid mixing the two methods. In case you do specify TLS options in both ways, the one that comes later in the configuration file will take effect.

retries()

Description: The number of times syslog-ng OSE attempts to send a message to this destination. If syslog-ng OSE could not send a message, it will try again until the number of attempts reaches retries, then drops the message.

throttle()

Description: Sets the maximum number of messages sent to the destination per second. Use this output-rate-limiting functionality only when using disk-buffer as well to avoid the risk of losing messages. Specifying 0 or a lower value sets the output limit to unlimited.

value-pairs()

scope("selected-macros" "nv-pairs")

Description: The value-pairs() option creates structured name-value pairs from the data and metadata of the log message. For details on using value-pairs(), see Structuring macros, metadata, and other value-pairs.

elasticsearch: Sending messages directly to Elasticsearch version 1.x

Starting with version 3.7 of syslog-ng OSE can directly send log messages to Elasticsearch, allowing you to search and analyze your data in real time, and visualize it with Kibana.

Note the following limitations when using the syslog-ng OSE elasticsearch destination:

• This destination is only supported on the Linux platform.

• Since syslog-ng OSE uses the official Java Elasticsearch libraries, the elasticsearch destination has significant memory usage.

• Sending messages over the HTTP REST API is supported only using the elastic2() destination. Note that in HTTP mode, the elasticsearch2 destination can send log messages to Elasticsearch version 1.x and newer. For details, see elasticsearch2: Sending logs directly to Elasticsearch and Kibana 2.0 or higher.

• The log messages of the underlying client libraries are available in the internal() source of syslog-ng OSE.

@module mod-java
@include "scl.conf"

elasticsearch(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
);

@module mod-java
@include "scl.conf"

destination d_elastic {
  elasticsearch(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
  );
};

@module mod-java
@include "scl.conf"

options {
  threaded(yes);
  use-uniqid(yes);
};

source s_syslog {
  syslog();
};

destination d_elastic {
  elasticsearch(
    index("syslog-ng_${YEAR}.${MONTH}.${DAY}")
    type("test")
    cluster("syslog-ng")
    client-mode("transport")
    custom-id("${UNIQID}")
    flush-limit("10000")
  );
};

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

• To install the software required for the elasticsearch destination, see Prerequisites.

• For details on how the elasticsearch destination works, see How syslog-ng OSE interacts with Elasticsearch.

• For the list of options, see Elasticsearch destination options.

The elasticsearch() driver is actually a reusable configuration snippet configured to receive log messages using the Java language-binding of syslog-ng OSE. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of the elasticsearch configuration snippet on GitHub. For details on extending syslog-ng OSE in Java, see the Getting started with syslog-ng development guide.

Prerequisites

To send messages from syslog-ng OSE to Elasticsearch, complete the following steps.