This section provides information about enabling Proxy Protocol support in your network() source options, and an example configuration and output to illustrate how the Proxy Protocol method works in syslog-ng Open Source Edition (syslog-ng OSE).
For more information about the working mechanism of the Proxy Protocol, see The working mechanism behind the Proxy Protocol.
Enabling Proxy Protocol support for your network() source options
Unless you enable Proxy Protocol support for your network() source, syslog-ng OSE identifies every connection that is connected to the load balancers identically by default, regardless of the source IP or the source protocol.
To enable Proxy Protocol for your network() source, set the transport() parameter of your network() source to proxied-tcp or proxied-tls-passthrough, depending on your preference and configuration.
proxied-tls can be used in complex MITM (man in the middle) configurations, where the proxy header is sent encrypted within the same TLS session as the proxied messages.
When you enable Proxy Protocol support for your network() source, you can use the following configuration example with your syslog-ng OSE application.
Configuration
The following code sample illustrates how you can use the Proxy Protocol in your syslog-ng OSE configuration (using the transport() parameter set to proxied-tls-passthrough).
@version: 3.35
source s_tcp_pp {
network (
port(6666)
transport("proxied-tls-passthrough")
tls(
key-file("/certs/certs/server/server.rsa")
cert-file("/certs/certs/server/server.crt")
ca-dir("/certs/certs/CA")
peer-verify("required-trusted")
)
);
};
destination d_file {
file("/var/log/proxy-proto.log" template("$(format-json --scope nv-pairs)\n"));
};
log {
source(s_tcp_pp);
destination(d_file);
};
With this configuration, the Proxy Protocol method will perform injecting the information of the original connection into the forwarded TCP session, based on the working mechanism described in The working mechanism behind the Proxy Protocol.
The following example illustrates how the parsed macros will appear in the output.
Example: Output for the PROXY TCP4 192.168.1.1 10.10.0.1 1111 2222 input header
With the PROXY TCP4 192.168.1.1 10.10.0.1 1111 2222 input header, the output looks like this:
{"SOURCE":"s_tcp_pp","PROXIED_SRCPORT":"1111","PROXIED_SRCIP":"192.168.1.1","PROXIED_IP_VERSION":"4","PROXIED_DSTPORT":"2222","PROXIED_DSTIP":"10.10.0.1","PROGRAM":"TestMsg","MESSAGE":"","LEGACY_MSGHDR":"TestMsg","HOST_FROM":"localhost","HOST":"localhost"}
Note that the macros that syslog-ng OSE adds to the message appear in the output.
Using the nodejs() driver, syslog-ng OSE can receive application logs directly from nodejs applications that use the widespread Winston logging API. The syslog-ng OSE application automatically adds the .nodejs.winston. prefix to the name of the fields the extracted from the message.
To use the nodejs() driver, the scl.conf file must be included in your syslog-ng OSE configuration:
@include "scl.conf"
The nodejs() driver is actually a reusable configuration snippet configured to receive log messages using the network() driver, and process its JSON contents. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of the nodejs configuration snippet on GitHub.
Example: Using the nodejs() driver
The following example uses the default settings of the driver, listening for messages on port 9003 of every IP address of the syslog-ng OSE host.
@include "scl.conf"
source apps { nodejs(); };
The following example listens only on IP address 192.168.1.1, port 9999.
@include "scl.conf"
source apps {
nodejs(
localip(192.168.1.1)
port(9999)
)
};
The nodejs() driver has the following options.
hook-commands()
Description: This option makes it possible to execute external programs when the relevant driver is initialized or torn down. The hook-commands() can be used with all source and destination drivers with the exception of the usertty() and internal() drivers.
NOTE: The syslog-ng OSE application must be able to start and restart the external program, and have the necessary permissions to do so. For example, if your host is running AppArmor or SELinux, you might have to modify your AppArmor or SELinux configuration to enable syslog-ng OSE to execute external applications.
Using the hook-commands() when syslog-ng OSE starts or stops
To execute an external program when syslog-ng OSE starts or stops, use the following options:
| startup() |
| Type: |
string |
| Default: |
N/A |
|
Description: Defines the external program that is executed as syslog-ng OSE starts. |
| shutdown() |
| Type: |
string |
| Default: |
N/A |
|
Description: Defines the external program that is executed as syslog-ng OSE stops. |
Using the hook-commands() when syslog-ng OSE reloads
To execute an external program when the syslog-ng OSE configuration is initiated or torn down, for example, on startup/shutdown or during a syslog-ng OSE reload, use the following options:
| setup() |
| Type: |
string |
| Default: |
N/A |
|
Description: Defines an external program that is executed when the syslog-ng OSE configuration is initiated, for example, on startup or during a syslog-ng OSE reload. |
| teardown() |
| Type: |
string |
| Default: |
N/A |
|
Description: Defines an external program that is executed when the syslog-ng OSE configuration is stopped or torn down, for example, on shutdown or during a syslog-ng OSE reload. |
Example: Using the hook-commands() with a network source
In the following example, the hook-commands() is used with the network() driver and it opens an iptables port automatically as syslog-ng OSE is started/stopped.
The assumption in this example is that the LOGCHAIN chain is part of a larger ruleset that routes traffic to it. Whenever the syslog-ng OSE created rule is there, packets can flow, otherwise the port is closed.
source {
network(transport(udp)
hook-commands(
startup("iptables -I LOGCHAIN 1 -p udp --dport 514 -j ACCEPT")
shutdown("iptables -D LOGCHAIN 1")
)
);
};
ip() or localip()
| Type: |
string |
| Default: |
0.0.0.0 |
Description: The IP address to bind to. By default, syslog-ng OSE listens on every available interface. Note that this is not the address where messages are accepted from.
If you specify a multicast bind address and use the udp transport, syslog-ng OSE automatically joins the necessary multicast group. TCP does not support multicasting.
port() or localport()
| Type: |
number |
| Default: |
9003 |
Description: The port number to bind to.
Using the mbox() driver, syslog-ng OSE can read email messages from local mbox files, and convert them to multiline log messages.
This driver has only one required option, the filename of the mbox file. To use the mbox() driver, the scl.conf file must be included in your syslog-ng OSE configuration:
@include "scl.conf"
The mbox() driver is actually a reusable configuration snippet configured to read log messages using the file() driver. For details on using or writing such configuration snippets, see Reusing configuration blocks. You can find the source of the configuration snippet on GitHub.
Example: Using the mbox() driver
The following example reads the emails of the root user on the syslog-ng OSE host.
@include "scl.conf"
source root-mbox {
mbox("/var/spool/mail/root");
};
