diff options
Diffstat (limited to 'source/configuration/modules/omrelp.rst')
| -rw-r--r-- | source/configuration/modules/omrelp.rst | 482 |
1 files changed, 482 insertions, 0 deletions
diff --git a/source/configuration/modules/omrelp.rst b/source/configuration/modules/omrelp.rst new file mode 100644 index 0000000..11a3fd9 --- /dev/null +++ b/source/configuration/modules/omrelp.rst @@ -0,0 +1,482 @@ +************************** +omrelp: RELP Output Module +************************** + +=========================== =========================================================================== +**Module Name:** **omrelp** +**Author:** `Rainer Gerhards <https://rainer.gerhards.net/>`_ <rgerhards@adiscon.com> +=========================== =========================================================================== + + +Purpose +======= + +This module supports sending syslog messages over the reliable RELP +protocol. For RELP's advantages over plain tcp syslog, please see the +documentation for :doc:`imrelp <imrelp>` (the server counterpart). + +Setup + +Please note that `librelp <http://www.librelp.com>`__ is required for +imrelp (it provides the core relp protocol implementation). + + +Configuration Parameters +======================== + +.. note:: + + Parameter names are case-insensitive. + +Module Parameters +----------------- + +tls.tlslib +^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "none", "no", "none" + +.. versionadded:: 8.1903.0 + +Permits to specify the TLS library used by librelp. +All relp protocol operations or actually performed by librelp and +not rsyslog itself. This value specified is directly passed down to +librelp. Depending on librelp version and build parameters, supported +tls libraries differ (or TLS may not be supported at all). In this case +rsyslog emits an error message. + +Usually, the following options should be available: "openssl", "gnutls". + +Note that "gnutls" is the current default for historic reasons. We actually +recommend to use "openssl". It provides better error messages and accepts +a wider range of certificate types. + +If you have problems with the default setting, we recommend to switch to +"openssl". + + +Action Parameters +----------------- + +Target +^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "none", "yes", "none" + +The target server to connect to. + + +Port +^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "514", "no", "none" + +Name or numerical value of TCP port to use when connecting to target. + + +Template +^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "RSYSLOG_ForwardFormat", "no", "none" + +Defines the template to be used for the output. + + +Timeout +^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "int", "90", "no", "none" + +Timeout for relp sessions. If set too low, valid sessions may be +considered dead and tried to recover. + + +Conn.Timeout +^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "int", "10", "no", "none" + +Timeout for the socket connection. + + +RebindInterval +^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "int", "0", "no", "none" + +Permits to specify an interval at which the current connection is +broken and re-established. This setting is primarily an aid to load +balancers. After the configured number of messages has been +transmitted, the current connection is terminated and a new one +started. This usually is perceived as a \`\`new connection'' by load +balancers, which in turn forward messages to another physical target +system. + + +WindowSize +^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "int", "0", "no", "none" + +This is an **expert parameter**. It permits to override the RELP +window size being used by the client. Changing the window size has +both an effect on performance as well as potential message +duplication in failure case. A larger window size means more +performance, but also potentially more duplicated messages - and vice +versa. The default 0 means that librelp's default window size is +being used, which is considered a compromise between goals reached. +For your information: at the time of this writing, the librelp +default window size is 128 messages, but this may change at any time. +Note that there is no equivalent server parameter, as the client +proposes and manages the window size in RELP protocol. + + +TLS +^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +If set to "on", the RELP connection will be encrypted by TLS, so +that the data is protected against observers. Please note that both +the client and the server must have set TLS to either "on" or "off". +Other combinations lead to unpredictable results. + +*Attention when using GnuTLS 2.10.x or older* + +Versions older than GnuTLS 2.10.x may cause a crash (Segfault) under +certain circumstances. Most likely when an imrelp inputs and an +omrelp output is configured. The crash may happen when you are +receiving/sending messages at the same time. Upgrade to a newer +version like GnuTLS 2.12.21 to solve the problem. + + +TLS.Compression +^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "binary", "off", "no", "none" + +The controls if the TLS stream should be compressed (zipped). While +this increases CPU use, the network bandwidth should be reduced. Note +that typical text-based log records usually compress rather well. + + +TLS.PermittedPeer +^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "array", "none", "no", "none" + +Note: this parameter is mandatory depending on the value of +`TLS.AuthMode` but the code does currently not check this. + +Peer Places access restrictions on this forwarder. Only peers which +have been listed in this parameter may be connected to. This guards +against rouge servers and man-in-the-middle attacks. The validation +bases on the certificate the remote peer presents. + +This contains either remote system names or fingerprints, depending +on the value of parameter `TLS.AuthMode`. One or more values may be +entered. + +When a non-permitted peer is connected to, the refusal is logged +together with the given remote peer identify. This is especially +useful in *fingerprint* authentication mode: if the +administrator knows this was a valid request, he can simply add the +fingerprint by copy and paste from the logfile to rsyslog.conf. It +must be noted, though, that this situation should usually not happen +after initial client setup and administrators should be alert in this +case. + +Note that usually a single remote peer should be all that is ever +needed. Support for multiple peers is primarily included in support +of load balancing scenarios. If the connection goes to a specific +server, only one specific certificate is ever expected (just like +when connecting to a specific ssh server). +To specify multiple fingerprints, just enclose them in braces like +this: + +.. code-block:: none + + tls.permittedPeer=["SHA1:...1", "SHA1:....2"] + +To specify just a single peer, you can either specify the string +directly or enclose it in braces. + +Note that in *name* authentication mode wildcards are supported. +This can be done as follows: + +.. code-block:: none + + tls.permittedPeer="*.example.com" + +Of course, there can also be multiple names used, some with and +some without wildcards: + +.. code-block:: none + + tls.permittedPeer=["*.example.com", "srv1.example.net", "srv2.example.net"] + + +TLS.AuthMode +^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "none" + +Sets the mode used for mutual authentication. Supported values are +either "*fingerprint*" or "*name*". Fingerprint mode basically is +what SSH does. It does not require a full PKI to be present, instead +self-signed certs can be used on all peers. Even if a CA certificate +is given, the validity of the peer cert is NOT verified against it. +Only the certificate fingerprint counts. + +In "name" mode, certificate validation happens. Here, the matching is +done against the certificate's subjectAltName and, as a fallback, the +subject common name. If the certificate contains multiple names, a +match on any one of these names is considered good and permits the +peer to talk to rsyslog. + +The permitted names or fingerprints are configured via +`TLS.PermittedPeer`. + + +About Chained Certificates +-------------------------- + +.. versionadded:: 8.2008.0 + +With librelp 1.7.0, you can use chained certificates. +If using "openssl" as tls.tlslib, we recommend at least OpenSSL Version 1.1 +or higher. Chained certificates will also work with OpenSSL Version 1.0.2, but +they will be loaded into the main OpenSSL context object making them available +to all librelp instances (omrelp/imrelp) within the same process. + +If this is not desired, you will require to run rsyslog in multiple instances +with different omrelp configurations and certificates. + + +TLS.CaCert +^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "none" + +The CA certificate that can verify the machine certs. + + +TLS.MyCert +^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "none" + +The machine public certificate. + + +TLS.MyPrivKey +^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "none" + +The machine private key. + + +TLS.PriorityString +^^^^^^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "none" + +This parameter permits to specify the so-called "priority string" to +GnuTLS. This string gives complete control over all crypto +parameters, including compression setting. For this reason, when the +prioritystring is specified, the "tls.compression" parameter has no +effect and is ignored. +Full information about how to construct a priority string can be +found in the GnuTLS manual. At the time of this writing, this +information was contained in `section 6.10 of the GnuTLS +manual <http://gnutls.org/manual/html_node/Priority-Strings.html>`__. +**Note: this is an expert parameter.** Do not use if you do not +exactly know what you are doing. + +tls.tlscfgcmd +^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "string", "none", "no", "none" + +.. versionadded:: 8.2001.0 + +The setting can be used if tls.tlslib is set to "openssl" to pass configuration commands to +the openssl libray. +OpenSSL Version 1.0.2 or higher is required for this feature. +A list of possible commands and their valid values can be found in the documentation: +https://www.openssl.org/docs/man1.0.2/man3/SSL_CONF_cmd.html + +The setting can be single or multiline, each configuration command is separated by linefeed (\n). +Command and value are separated by equal sign (=). Here are a few samples: + +Example 1 +--------- + +This will allow all protocols except for SSLv2 and SSLv3: + +.. code-block:: none + + tls.tlscfgcmd="Protocol=ALL,-SSLv2,-SSLv3" + + +Example 2 +--------- + +This will allow all protocols except for SSLv2, SSLv3 and TLSv1. +It will also set the minimum protocol to TLSv1.2 + +.. code-block:: none + + tls.tlscfgcmd="Protocol=ALL,-SSLv2,-SSLv3,-TLSv1 + MinProtocol=TLSv1.2" + +LocalClientIp +^^^^^^^^^^^^^ + +.. csv-table:: + :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" + :widths: auto + :class: parameter-table + + "word", "none", "no", "none" + +Omrelp uses ip_address as local client address while connecting +to remote logserver. + + +Examples +======== + +Sending msgs with omrelp +------------------------ + +The following sample sends all messages to the central server +"centralserv" at port 2514 (note that that server must run imrelp on +port 2514). + +.. code-block:: none + + module(load="omrelp") + action(type="omrelp" target="centralserv" port="2514") + + +Sending msgs with omrelp via TLS +------------------------------------ + +This is the same as the previous example but uses TLS (via OpenSSL) for +operations. + +Certificate files must exist at configured locations. Note that authmode +"certvalid" is not very strong - you may want to use a different one for +actual deployments. For details, see parameter descriptions. + +.. code-block:: none + + module(load="omrelp" tls.tlslib="openssl") + action(type="omrelp" + target="centralserv" port="2514" tls="on" + tls.cacert="tls-certs/ca.pem" + tls.mycert="tls-certs/cert.pem" + tls.myprivkey="tls-certs/key.pem" + tls.authmode="certvalid" + tls.permittedpeer="rsyslog") + + +|FmtObsoleteName| directives +============================ + +This module uses old-style action configuration to keep consistent with +the forwarding rule. So far, no additional configuration directives can +be specified. To send a message via RELP, use + +.. code-block:: none + + *.* :omrelp:<server>:<port>;<template> + + |