Forward Analytics Events to Syslog

Overview

Follow the steps in this guide to set up a NGINX Controller Integration that forwards events to a syslog server.

Before You Begin

This guide assumes that you already have a working instance of any syslog server.

If you haven’t already done so, you can use an open-source version of Syslog-NG.

Requirements for syslog Server

Network protocol

The syslog server should be able to receive data via one of the following protocols:

  • TCP - for unencrypted connections.
  • TLS - for encrypted connections. Validation of the Certificate Authority (CA) and mutual TLS are currently not supported.

Syslog Format

  • The forwarder produces RFC-5424-compliant messages.

  • For delimiting, the octet count is added to every syslog message. See RFC-5425 for details.

Example of a message sent by the forwarder in syslog format:

<6>1 2019-09-10T06:40:15+02:00 controller.fqdn.svc nginx_controller 1 ngxctrl [dimensions alias="my_system" category="agent event" counter="1" instance="" instance.tags="tag1,tag2" level="INFO" local_id="d23c85484ee760ee5f4619c0434e1968b5290964487541da0889964eb783613c" location="" message="nginx stub_status detected, https://127.0.0.1:443/basic_status" parent_hostname="d0784771a503" root_uuid="49946669ca315d45bae1d6c05de9bd7e"] nginx stub_status detected, https://127.0.0.1:443/basic_status

Example configuration for Syslog-NG

The example of syslog-ng.conf that receives messages over TLS:

@version: 3.29
@include "scl.conf"

source s_network {
    default-network-drivers(
    tls(key-file("/key.pem") cert-file("/cert.pem") peer-verify(optional-trusted))

    # the optional flag that enables the access to $RAWSMSG
    flags(store-raw-message)
    );
};

destination d_remote  {
    file("/var/log/controller.events.log");

    # if you want to see the raw message with all dimensions:
    file("/var/log/controller.events.raw.log" template("${RAWMSG}\n"));
};

log {
    source(s_network);
    destination(d_remote);
};

Create an Integration

Take the following steps to create an Integration for syslog:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select GENERIC_INTEGRATION.
  10. In the Endpoint URI box, add the TCP endpoint for your syslog. Syslog’s URL can be provided in two formats:
    • tcp://hostname[:port] for unencrypted TCP connections (example: tcp://192.168.0.1:601).
    • tcp+tls://hostname[:port] for encrypted TCP connections with TLS (example: tcp+tls://192.168.0.1:6514)
  11. In the Credential Type list, select UNAUTHENTICATED.
  12. Select Submit.

Create a Forwarder

Use the NGINX Controller REST API to create a forwarder.

To create a forwarder, send a POST request to the analytics/forwarders endpoint with a request similar to the following example.

Important:
You can create a forwarder with syslog output format only for input data type EVENTS. We don’t support syslog for METRICS.
Important:
You must reference the integration in the JSON request body. Requests that do not contain a valid integration reference will return an error message.
{
  "metadata": {
    "name": "syslog-forwarder",
    "displayName": "Syslog - Events",
    "description": "Events forwarder for syslog"
  },
  "desiredState": {
    "collectorType": "SYSLOG",
    "integrationRef": {
      "ref": "/platform/integrations/<name-of-syslog-integration>"
    },
    "streams": [
      {
        "inputDataType": "EVENTS",
        "outputFormat": "SYSLOG",
        "selector": ""
      }
    ]
  }
}

Parameters

metadata

  • name: The resource name to use for the forwarder.
  • displayName (Optional): The friendly name to show for the forwarder.
  • description (Optional): A brief description of the forwarder.

desiredState

  • integrationRef.ref: The integration reference for the forwarder. Use the format /platform/integrations/<name-of-syslog-integration>. Use the name for the Integration that you created in the Create an Integration procedure.
  • collectorType: The type of collector. For syslog collector use SYSLOG.

streams

  • inputDataType: The type of data to forward. NGINX Controller can forward only EVENTS data to syslog.

  • outputFormat: The format for the output. For syslog-formatted output, use SYSLOG. +- selector: Consists of the following query parameters (optional):

    • filter: The conditions to use to refine events data. If not given, all events will be forwarded.
    • Example usage: "filter=type='security violation' AND app='my-app'".

What’s Next


This documentation applies to the following versions of NGINX Controller Documentation: 3.16 and 3.16.