This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

graylog2: Send logs to Graylog

graylog2(): Sending logs to Graylog

You can use the graylog2() destination and a Graylog Extended Log Format (GELF) template to send syslog messages to Graylog.

You can forward simple name-value pairs where the name starts with a dot or underscore. If names of your name-value pairs include dots other than the first character, you should use JSON formatting directly instead of the GELF template and send logs to a raw TCP port in Graylog, which can then extract fields from nested JSON. Version 3.21 and later also supports TLS-encrypted connection to the Graylog server.

Declaration:

   graylog2();

Example: Using the graylog2() driver

You can send syslog messages to Graylog using the graylog2() destination. The graylog2() destination uses the GELF template, the native data format of Graylog.

  1. On the Graylog side, configure a GELF TCP input. For more information, see the relevant Graylog documentation.

  2. On the AxoSyslog side, configure the name or IP address of the host running Graylog.

        destination d_graylog {
      graylog2(
        host("172.16.146.142")
        transport(tcp)
      );
    };

    If you parsed your messages using syslog-ng, the template also forwards any name-value pairs where the name starts with a dot or underscore.

Sending nested JSON to Graylog

While sending nested JSON inside GELF is possible, it is not convenient. If you use parsing and normalization and dot notation in field names, use pure JSON instead of GELF to forward your messages.

  1. On the Graylog side, create a new raw TCP input.

  2. Still in Graylog, once the raw TCP input is ready, add a JSON extractor to it.

  3. On the AxoSyslog side, use a network destination combined with a template utilizing format-json as shown in the example below:

        destination d_jsontcp {
      network(
        "172.16.146.142"
        port("5555")
        transport(tcp)
        template("$(format-json --scope all-nv-pairs)\n")
      );
    };

1 - graylog2() destination options

The graylog2() destination has the following options:

ca-dir()
Accepted values:Directory name
Default:none

Description: The name of a directory that contains a set of trusted CA certificates in PEM format. The CA certificate files have to be named after the 32-bit hash of the subject’s name. This naming can be created using the c_rehash utility in openssl. For an example, see Configuring TLS on the AxoSyslog clients. The AxoSyslog application uses the CA certificates in this directory to validate the certificate of the peer.

This option can be used together with the optional ca-file() option.

ca-file()
Accepted values:File name
Default:empty

Description: Optional. The name of a file that contains a set of trusted CA certificates in PEM format. The AxoSyslog application uses the CA certificates in this file to validate the certificate of the peer.

Example format in configuration:

   ca-file("/etc/pki/tls/certs/ca-bundle.crt")

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 hook-commands() when AxoSyslog starts or stops

To execute an external program when AxoSyslog starts or stops, use the following options:

startup()

Type:string
Default:N/A

Description: Defines the external program that is executed as AxoSyslog starts.

shutdown()

Type:string
Default:N/A

Description: Defines the external program that is executed as AxoSyslog stops.

Using the hook-commands() when AxoSyslog reloads

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

setup()

Type:string
Default:N/A

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

teardown()

Type:string
Default:N/A

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

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

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

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

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

tls()
Type:tls options
Default:n/a

Description: This option sets various options related to TLS encryption, for example, key/certificate files and trusted CA locations. TLS can be used only with tcp-based transport protocols. For details, see TLS options.

transport()
Type:udp, tcp, or tls
Default:tcp

Description: Specifies the protocol used to send messages to the destination server.

If you use the udp transport, AxoSyslog automatically sends multicast packets if a multicast destination address is specified. The tcp transport does not support multicasting.