TLS options
The syslog-ng application can encrypt incoming and outgoing syslog message flows using TLS if you use the network() or syslog() drivers.
|
|
NOTE:
The format of the TLS connections used by syslog-ng is similar to using syslog-ng and stunnel, but the source IP information is not lost. |
To encrypt connections, use the transport("tls") and tls() options in the source and destination statements.
The tls() option can include the following settings:
| Accepted values: | yes | no |
| Default: | no |
Description: Enable on-the-wire compression in TLS communication. Note that this option must be enabled both on the server and the client side to have any effect. Enabling compression can significantly reduce the bandwidth required to transport the messages, but can slightly decrease the performance of syslog-ng PE, reducing the number of transferred messages during a given period.
| Accepted values: | Directory name |
| Default: | none |
Description: 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.
| Accepted values: | sha1-based |
| Default: | sha1-based |
Description: The type of the hash used for the CA certificates. NOTE: This option is deprecated.
|
|
Caution:
If you are upgrading to syslog-ng PE version 6.x from a version earlier than 5.0, you must rehash the trusted CA certificates. |
| Accepted values: | Filename |
| Default: | none |
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. 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.
cipher-suite()
| Accepted values: | Name of a cipher, or a colon-separated list |
| Default: | 1.1.1 |
Description: Specifies the cipher, hash, and key-exchange algorithms used for the encryption, for example, ECDHE-ECDSA-AES256-SHA384. The list of available algorithms depends on the version of OpenSSL used to compile syslog-ng PE. To specify multiple ciphers, separate the cipher names with a colon, and enclose the list between double-quotes, for example:
cipher-suite("ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384")| Accepted values: | Directory name |
| Default: | none |
Description: Name of a directory that contains the Certificate Revocation Lists for trusted CAs. Similarly to ca-dir() files, use the 32-bit hash of the name of the issuing CAs as filenames. The extension of the files must be .r0.
If the crl-dir() is set, and the peer certificate has been revoked, syslog-ng PE rejects the connection. If the peer certificate has not been revoked, or syslog-ng PE cannot access the CRL, syslog-ng PE accepts the connection.
| Accepted values: | string (colon-separated list) |
| Default: | none |
Description: A colon-separated list that specifies the curves that are permitted in the connection when using Elliptic Curve Cryptography (ECC). The syslog-ng PE application uses automatically the highest preference curve that both peers support. If not specified, the list includes every supported curve. For example:
curve-list('prime256v1:secp521r1')
The syslog-ng Premium Edition application currently supports the following curves: sect163k1, sect163r1, sect163r2, sect193r1, sect193r2,, sect233k1, sect233r1, sect239k1, sect283k1, sect283r1,, sect409k1, sect409r1, sect571k1, sect571r1, secp160k1,, secp160r1, secp160r2, secp192k1, prime192v1, secp224k1,, secp224r1, secp256k1, prime256v1, secp384r1, secp521r1,, brainpoolP256r1, brainpoolP384r1, brainpoolP512r1.
| Accepted values: | string (filename) |
| Default: | none |
Description: Specifies a file containing Diffie-Hellman parameters, generated using the openssl dhparam utility. Note that syslog-ng PE supports only DH parameter files in the PEM format. If you do not set this parameter, syslog-ng PE uses the 2048-bit MODP Group, as described in RFC 3526.
| Accepted values: | Filename |
| Default: | none |
Description: Name of a file, that contains an unencrypted private key in PEM format, suitable as a TLS key.
| Accepted values: | optional-trusted | optional-untrusted | required-trusted | required-untrusted |
| Default: | required-trusted |
Description: Verification method of the peer, the four possible values is a combination of two properties of validation:
-
whether the peer is required to provide a certificate (required or optional prefix), and
-
whether the certificate provided needs to be valid or not.
The following table summarizes the possible options and their results depending on the certificate of the peer.
| The remote peer has: | ||||
|---|---|---|---|---|
| no certificate | invalid certificate | valid certificate | ||
| Local peer-verify() setting | optional-untrusted | TLS-encryption | TLS-encryption | TLS-encryption |
| optional-trusted | TLS-encryption | rejected connection | TLS-encryption | |
| required-untrusted | rejected connection | TLS-encryption | TLS-encryption | |
| required-trusted | rejected connection | rejected connection | TLS-encryption | |
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.
|
|
Caution:
When validating a certificate, the entire certificate chain must be valid, including the CA certificate. If any certificate of the chain is invalid, syslog-ng PE will reject the connection. |
| Accepted values: | list of accepted distinguished names |
| Default: | none |
Description: To accept connections only from hosts using certain certificates signed by the trusted CAs, list the distinguished names of the accepted certificates in this parameter. For example using trusted-dn("*, O=Example Inc, ST=Some-State, C=*") will accept only certificates issued for the Example Inc organization in Some-State state.
| Accepted values: | list of accepted SHA-1 fingerprints |
| Default: | none |
Description: To accept connections only from hosts using certain certificates having specific SHA-1 fingerprints, list the fingerprints of the accepted certificates in this parameter. For example trusted-keys("SHA1:00:EF:ED:A4:CE:00:D1:14:A4:AB:43:00:EF:00:91:85:FF:89:28:8F", "SHA1:0C:42:00:3E:B2:60:36:64:00:E2:83:F0:80:46:AD:00:A8:9D:00:15").
To find the fingerprint of a certificate, you can use the following command: openssl x509 -in <certificate-filename> -sha1 -noout -fingerprint
|
|
NOTE:
When using the
|
Chapter 12. Reliable Log Transfer Protocol™
The syslog-ng PE application can send and receive log messages in a reliable way over the TCP transport layer using the Reliable Log Transfer Protocol™ (RLTP™). RLTP™ is a proprietary transport protocol that prevents message loss during connection breaks. The transport is used between syslog-ng PE hosts (for example, a client and a server, or a client-relay-server), and interoperates with the flow-control and reliable disk-buffer mechanisms of syslog-ng PE, thus providing the best way to prevent message loss. The sender detects which messages has the receiver successfully received. If messages are lost during the transfer, the sender resends the missing messages, starting from the last successfully received message. Therefore, messages are not duplicated at the receiving end in case of a connection break (however, in failover mode this is not completely ensured). RLTP™ also allows to receive encrypted and non-encrypted connections on the same port, using a single source driver.
|
|
NOTE:
Because of the communication overhead, the RLTP™ protocol is slower than other transport protocols, which might be a problem if you need to collect a high amount (over 200000 messages per second) of log messages on your log server. For performance details of syslog-ng PE see the syslog-ng Premium Edition Performance Guideline at the syslog-ng Documentation page. |
|
|
Caution:
In the following cases, it is possible to lose log messages even if you use RLTP™:
|
The RLTP™ protocol works on top of TCP, and can use STARTTLS for encryption. RLTP™ supports IPv4 and IPv6 addresses. Inside the RLTP™ message, the message can use any format, for example, RFC3164 (BSD-syslog) or RFC5424 (IETF-syslog). The default port of RLTP™ is 35514.
RLTP™ can be added to the configuration like a transport protocol within the syslog() driver and the network() driver.
Procedure 12.1. How RLTP™ connections work
Purpose:
This procedure summarizes how two syslog-ng PE hosts (a sender and a receiver) communicate using the Reliable Log Transfer Protocol™ (RLTP™).
Prerequisites:
The sender (also called the client) is the host that has RLTP™ configured in its destination driver. The receiver (also called the server) is the host that has RLTP™ configured in its source driver.
Steps:
-
The sender initiates the connection to the receiver.
-
The sender and the receiver negotiate whether to encrypt the connection and to use compression or not.
-
If the connection should be encrypted, the sender and the receiver perform authentication (as configured in the
tls()options of their configuration). -
If the sender and the receiver have communicated earlier using RLTP™, the receiver indicates which was the last message received from the sender.
-
The sender starts sending messages in batches. Batch size depends on the
flush-lines()parameter of the sender.For optimal performance when sending messages to an syslog-ng PE server, make sure that the
flush-lines()is smaller than the window size set using thelog-iw-size()option in the source of your server. -
When the receiver has successfully processed the messages in the batch, it sends an acknowledgement of the processed messages to the sender.
What "successfully processed" means depends on the configuration of the receiver, for example, written to disk in a destination, forwarded to a remote destination using notRLTP™, dropped because of filter settings, or written to the disk-buffer. (If the messages are forwarded using RLTP™, see the section called “Using RLTP™ in a client-relay-server scenario”.)
-
After receiving the acknowledgement, the sender sends another batch of messages.
You can use RLTP™ between multiple syslog-ng PE hosts, for example, in a client-relay-server scenario. In such case, the communication described in Procedure 12.1, “How RLTP™ connections work” applies both between the client and the relay, and the relay and the server. However, note the following points:
-
Unless you use disk-buffer on the relay, the relay waits for acknowledgement from the server before acknowledging the messages to the client. If you send the messages in large batches, and the server can process the messages slowly (or the network connection is slow), you might have to adjust the
message-acknowledgement-timeout()on the client. -
If you use reliable disk-buffer on the relay, the relay will acknowledge the messages when the messages are written to the disk-buffer. That way, the client does not have to wait while the server acknowledges the messages.
RLTP™ options
The following options are specific to the RLTP™ protocol. Note that when using RLTP™ in a source or a destination, the options of the syslog() or the network() driver can be used as well.
| Accepted values: | yes | no |
| Default: | no |
Description: Enable on-the-wire compression in the RLTP communication. Note that this option must be enabled both on the server and the client side to have any effect. Enabling compression can significantly reduce the bandwidth required to transport the messages, but can slightly decrease the performance of syslog-ng PE, reducing the number of transferred messages. The allow-compress() option can be used in source and destination drivers as well. Available in syslog-ng PE 5.0 and later.
| Type: | number (seconds) |
| Default: | 900 |
Description: When the receiver (syslog-ng PE server) receives and successfully processes a message, it sends an acknowledgement to the sender (the syslog-ng PE client). If the receiver does not acknowledge receiving the messages within this period, the sender terminates the connection with the receiver. Use this option only in destination drivers.
| Type: | number (seconds) |
| Default: | 60 |
Description: If syslog-ng PE does not receive any protocol-related message in the given timeframe (except for message acknowledgement, which is governed by the message-acknowledgement-timeout() option), syslog-ng PE terminates the connection with the peer, and the "Connection broken" message appears in the logs of the sender (the syslog-ng PE client). This is normal, and happens when the sender does not send any new message to the receiver.
Under normal circumstances, you should not change the value of this option. The response-timeout() option can be used in source and destination drivers as well.
| Type: | yes, optional, no |
| Default: | optional |
Description: Determines whether STARTTLS is to be used during communication. If the option is set to yes, you must also configure the tls() option to specify other parameters of the TLS connection (for example, the authentication of the server and the client).
The tls-required() option can be used in source and destination drivers as well.
For example, if you configure tls-required(yes) on server side and tls-required(no) on client side, the connection is dropped. If one of them is set to optional, the configuration of the other side will decide if TLS is used or not. If both sides are set to optional, and the tls() option is properly configured, TLS encryption will be used. The following table summarizes the possible options and their results.
Note that the various parameters of the tls() option are considered in the connection only if the tls-required() settings of the peers result in TLS-encryption in the following table. In other words: the tls-required() option of RLTP™ determines if TLS should be used at all, while the peer-verify() option of the tls()setting determines if the TLS connection can be actually established.
Setting tls-required(optional) on your server allows you to receive both encrypted and unencrypted connections on the same port.
Examples for using RLTP™
Example 12.1. Simple RLTP™ connection
The sender and the receiver use RLTP™ over the network() protocol. Since the tls() option is not configured neither on the sender nor on the receiver, the communication will be unencrypted.
Receiver configuration (syslog-ng PE server):
source s_network_rltp {
network(
ip("127.0.0.1")
port("5555")
transport(rltp)
ip-protocol(4)
);
};
Sender configuration (syslog-ng PE client):
destination d_network_rltp {
network(
"127.0.0.1"
port("5555")
transport(rltp)
ip-protocol(4)
);
};Example 12.2. RLTP™ with TLS encryption
The following example configure a sender and a receiver to communicate using RLTP™. Since the tls-required() option is set to optional on the receiver and yes on the sender, and the tls() option is configured, the communication will be TLS-encrypted. For the sender (syslog-ng PE client), reliable disk-buffering is enabled to prevent data loss.
Receiver configuration (syslog-ng PE server):
source s_syslog_rltp {
syslog(
ip("127.0.0.1")
port("4444")
transport(rltp(tls-required(optional)))
ip-protocol(4)
tls(
peer-verify(required-trusted)
ca-dir("/var/tmp/client/")
key-file("/var/tmp/server/server_priv.key")
cert-file("/var/tmp/server/server.crt")
)
);
};
Sender configuration (syslog-ng PE client):
destination d_syslog_rltp {
syslog(
"127.0.0.1"
port("4444")
transport(rltp(tls-required(yes)))
ip-protocol(4)
disk-buffer( mem-buf-size(200000) disk-buf-size(2000000) reliable(yes) )
tls(
peer-verify(required-trusted)
ca-dir("/var/tmp/server/")
key-file("/var/tmp/client/client_priv.key")
cert-file("/var/tmp/client/client.crt")
)
);
};