From d0a0305028bdacaf1a2b6899282d8652eaa524ee Mon Sep 17 00:00:00 2001 From: Rainer Gerhards Date: Mon, 18 Aug 2025 08:36:46 +0200 Subject: [PATCH] imptcp: split parameter docs into reference pages Signed-off-by: Rainer Gerhards --- doc/source/configuration/modules/imptcp.rst | 799 +++++------------- .../reference/parameters/imptcp-address.rst | 54 ++ .../parameters/imptcp-addtlframedelimiter.rst | 76 ++ .../parameters/imptcp-compression-mode.rst | 43 + .../reference/parameters/imptcp-defaulttz.rst | 42 + .../parameters/imptcp-discardtruncatedmsg.rst | 43 + .../parameters/imptcp-failonchownfailure.rst | 42 + .../parameters/imptcp-filecreatemode.rst | 45 + .../reference/parameters/imptcp-filegroup.rst | 43 + .../parameters/imptcp-filegroupnum.rst | 43 + .../reference/parameters/imptcp-fileowner.rst | 43 + .../parameters/imptcp-fileownernum.rst | 43 + .../parameters/imptcp-flowcontrol.rst | 42 + .../imptcp-framing-delimiter-regex.rst | 53 ++ .../imptcp-framingfix-cisco-asa.rst | 43 + .../parameters/imptcp-keepalive-interval.rst | 57 ++ .../parameters/imptcp-keepalive-probes.rst | 57 ++ .../parameters/imptcp-keepalive-time.rst | 58 ++ .../reference/parameters/imptcp-keepalive.rst | 54 ++ .../parameters/imptcp-listenportfilename.rst | 43 + .../parameters/imptcp-maxframesize.rst | 46 + .../parameters/imptcp-maxsessions.rst | 53 ++ .../reference/parameters/imptcp-multiline.rst | 42 + .../reference/parameters/imptcp-name.rst | 57 ++ .../imptcp-notifyonconnectionclose.rst | 54 ++ .../imptcp-notifyonconnectionopen.rst | 42 + .../reference/parameters/imptcp-path.rst | 42 + .../reference/parameters/imptcp-port.rst | 54 ++ .../parameters/imptcp-processonpoller.rst | 52 ++ .../parameters/imptcp-ratelimit-burst.rst | 41 + .../parameters/imptcp-ratelimit-interval.rst | 42 + .../reference/parameters/imptcp-ruleset.rst | 54 ++ .../parameters/imptcp-socketbacklog.rst | 55 ++ .../imptcp-supportoctetcountedframing.rst | 57 ++ .../reference/parameters/imptcp-threads.rst | 59 ++ .../reference/parameters/imptcp-unlink.rst | 42 + 36 files changed, 1910 insertions(+), 605 deletions(-) create mode 100644 doc/source/reference/parameters/imptcp-address.rst create mode 100644 doc/source/reference/parameters/imptcp-addtlframedelimiter.rst create mode 100644 doc/source/reference/parameters/imptcp-compression-mode.rst create mode 100644 doc/source/reference/parameters/imptcp-defaulttz.rst create mode 100644 doc/source/reference/parameters/imptcp-discardtruncatedmsg.rst create mode 100644 doc/source/reference/parameters/imptcp-failonchownfailure.rst create mode 100644 doc/source/reference/parameters/imptcp-filecreatemode.rst create mode 100644 doc/source/reference/parameters/imptcp-filegroup.rst create mode 100644 doc/source/reference/parameters/imptcp-filegroupnum.rst create mode 100644 doc/source/reference/parameters/imptcp-fileowner.rst create mode 100644 doc/source/reference/parameters/imptcp-fileownernum.rst create mode 100644 doc/source/reference/parameters/imptcp-flowcontrol.rst create mode 100644 doc/source/reference/parameters/imptcp-framing-delimiter-regex.rst create mode 100644 doc/source/reference/parameters/imptcp-framingfix-cisco-asa.rst create mode 100644 doc/source/reference/parameters/imptcp-keepalive-interval.rst create mode 100644 doc/source/reference/parameters/imptcp-keepalive-probes.rst create mode 100644 doc/source/reference/parameters/imptcp-keepalive-time.rst create mode 100644 doc/source/reference/parameters/imptcp-keepalive.rst create mode 100644 doc/source/reference/parameters/imptcp-listenportfilename.rst create mode 100644 doc/source/reference/parameters/imptcp-maxframesize.rst create mode 100644 doc/source/reference/parameters/imptcp-maxsessions.rst create mode 100644 doc/source/reference/parameters/imptcp-multiline.rst create mode 100644 doc/source/reference/parameters/imptcp-name.rst create mode 100644 doc/source/reference/parameters/imptcp-notifyonconnectionclose.rst create mode 100644 doc/source/reference/parameters/imptcp-notifyonconnectionopen.rst create mode 100644 doc/source/reference/parameters/imptcp-path.rst create mode 100644 doc/source/reference/parameters/imptcp-port.rst create mode 100644 doc/source/reference/parameters/imptcp-processonpoller.rst create mode 100644 doc/source/reference/parameters/imptcp-ratelimit-burst.rst create mode 100644 doc/source/reference/parameters/imptcp-ratelimit-interval.rst create mode 100644 doc/source/reference/parameters/imptcp-ruleset.rst create mode 100644 doc/source/reference/parameters/imptcp-socketbacklog.rst create mode 100644 doc/source/reference/parameters/imptcp-supportoctetcountedframing.rst create mode 100644 doc/source/reference/parameters/imptcp-threads.rst create mode 100644 doc/source/reference/parameters/imptcp-unlink.rst diff --git a/doc/source/configuration/modules/imptcp.rst b/doc/source/configuration/modules/imptcp.rst index 353ccdf75..c18ef9539 100644 --- a/doc/source/configuration/modules/imptcp.rst +++ b/doc/source/configuration/modules/imptcp.rst @@ -36,69 +36,30 @@ Configuration Parameters .. note:: - Parameter names are case-insensitive. + Parameter names are case-insensitive; camelCase is recommended for readability. Module Parameters ----------------- -Threads -^^^^^^^ +.. list-table:: + :widths: 30 70 + :header-rows: 1 -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "2", "no", "``$InputPTCPServerHelperThreads``" - -Number of helper worker threads to process incoming messages. These -threads are utilized to pull data off the network. On a busy system, -additional helper threads (but not more than there are CPUs/Cores) -can help improving performance. The default value is two, which means -there is a default thread count of three (the main input thread plus -two helpers). No more than 16 threads can be set (if tried to, -rsyslog always resorts to 16). - - -MaxSessions -^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "0", "no", "none" - -Maximum number of open sessions allowed. This is inherited to each -"input()" config, however it is not a global maximum, rather just -setting the default per input. - -A setting of zero or less than zero means no limit. - -ProcessOnPoller -^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "on", "no", "none" - -Instructs imptcp to process messages on poller thread opportunistically. -This leads to lower resource footprint(as poller thread doubles up as -message-processing thread too). "On" works best when imptcp is handling -low ingestion rates. - -At high throughput though, it causes polling delay(as poller spends time -processing messages, which keeps connections in read-ready state longer -than they need to be, filling socket-buffer, hence eventually applying -backpressure). - -It defaults to allowing messages to be processed on poller (for backward -compatibility). + * - Parameter + - Summary + * - :ref:`param-imptcp-threads` + - .. include:: ../../reference/parameters/imptcp-threads.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-maxsessions` + - .. include:: ../../reference/parameters/imptcp-maxsessions.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-processonpoller` + - .. include:: ../../reference/parameters/imptcp-processonpoller.rst + :start-after: .. summary-start + :end-before: .. summary-end Input Parameters @@ -107,554 +68,144 @@ Input Parameters These parameters can be used with the "input()" statement. They apply to the input they are specified with. - -Port -^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "none", "no", "``$InputPTCPServerRun``" - -Select a port to listen on. It is an error to specify -both `path` and `port`. - - -Path -^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "none", "no", "none" - -A path on the filesystem for a unix domain socket. It is an error to specify -both `path` and `port`. - - -DiscardTruncatedMsg -^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "none" - -When a message is split because it is to long the second part is normally -processed as the next message. This can cause Problems. When this parameter -is turned on the part of the message after the truncation will be discarded. - -FileOwner -^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "UID", "system default", "no", "none" - -Set the file owner for the domain socket. The -parameter is a user name, for which the userid is obtained by -rsyslogd during startup processing. Interim changes to the user -mapping are *not* detected. - - -FileOwnerNum -^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "system default", "no", "none" - -Set the file owner for the domain socket. The -parameter is a numerical ID, which is used regardless of -whether the user actually exists. This can be useful if the user -mapping is not available to rsyslog during startup. - - -FileGroup -^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "GID", "system default", "no", "none" - -Set the group for the domain socket. The parameter is -a group name, for which the groupid is obtained by rsyslogd during -startup processing. Interim changes to the user mapping are not -detected. - - -FileGroupNum -^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "system default", "no", "none" - -Set the group for the domain socket. The parameter is -a numerical ID, which is used regardless of whether the group -actually exists. This can be useful if the group mapping is not -available to rsyslog during startup. - - -FileCreateMode -^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "octalNumber", "0644", "no", "none" - -Set the access permissions for the domain socket. The value given must -always be a 4-digit octal number, with the initial digit being zero. -Please note that the actual permission depend on rsyslogd's process -umask. If in doubt, use "$umask 0000" right at the beginning of the -configuration file to remove any restrictions. - - -FailOnChOwnFailure -^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "on", "no", "none" - -Rsyslog will not start if this is on and changing the file owner, group, -or access permissions fails. Disable this to ignore these errors. - - -Unlink -^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "none" - -If a unix domain socket is being used this controls whether or not the socket -is unlinked before listening and after closing. - - -Name -^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "imptcp", "no", "``$InputPTCPServerInputName``" - -Sets a name for the inputname property. If no name is set "imptcp" -is used by default. Setting a name is not strictly necessary, but can -be useful to apply filtering based on which input the message was -received from. Note that the name also shows up in -:doc:`impstats ` logs. - - -Ruleset -^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "none", "no", "``$InputPTCPServerBindRuleset``" - -Binds specified ruleset to this input. If not set, the default -ruleset is bound. - - -MaxFrameSize -^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "200000", "no", "none" - -When in octet counted mode, the frame size is given at the beginning -of the message. With this parameter the max size this frame can have -is specified and when the frame gets to large the mode is switched to -octet stuffing. -The max value this parameter can have was specified because otherwise -the integer could become negative and this would result in a -Segmentation Fault. (Max Value: 200000000) - - -MaxSessions -^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "0", "no", "none" - -Maximum number of open sessions allowed. If more tcp connections -are created then rsyslog will drop those connections. Warning, -this defaults to 0 which means unlimited, so take care to set this -if you have limited memory and/or processing power. - -A setting of zero or negative integer means no limit. - -Address -^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "none", "no", "``$InputPTCPServerListenIP``" - -On multi-homed machines, specifies to which local address the -listener should be bound. - - -AddtlFrameDelimiter -^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "-1", "no", "``$InputPTCPServerAddtlFrameDelimiter``" - -This directive permits to specify an additional frame delimiter for -plain tcp syslog. The industry-standard specifies using the LF -character as frame delimiter. Some vendors, notable Juniper in their -NetScreen products, use an invalid frame delimiter, in Juniper's case -the NUL character. This directive permits to specify the ASCII value -of the delimiter in question. Please note that this does not -guarantee that all wrong implementations can be cured with this -directive. It is not even a sure fix with all versions of NetScreen, -as I suggest the NUL character is the effect of a (common) coding -error and thus will probably go away at some time in the future. But -for the time being, the value 0 can probably be used to make rsyslog -handle NetScreen's invalid syslog/tcp framing. For additional -information, see this `forum -thread `_. -**If this doesn't work for you, please do not blame the rsyslog team. -Instead file a bug report with Juniper!** - -Note that a similar, but worse, issue exists with Cisco's IOS -implementation. They do not use any framing at all. This is confirmed -from Cisco's side, but there seems to be very limited interest in -fixing this issue. This directive **can not** fix the Cisco bug. That -would require much more code changes, which I was unable to do so -far. Full details can be found at the `Cisco tcp syslog -anomaly `_ page. - - -SupportOctetCountedFraming -^^^^^^^^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "on", "no", "``$InputPTCPServerSupportOctetCountedFraming``" - -The legacy octed-counted framing (similar to RFC5425 -framing) is activated. This is the default and should be left -unchanged until you know very well what you do. It may be useful to -turn it off, if you know this framing is not used and some senders -emit multi-line messages into the message stream. - - -NotifyOnConnectionClose -^^^^^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "``$InputPTCPServerNotifyOnConnectionClose``" - -Instructs imptcp to emit a message if a remote peer closes the -connection. - - -NotifyOnConnectionOpen -^^^^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "none" - -Instructs imptcp to emit a message if a remote peer opens a -connection. Hostname of the remote peer is given in the message. - - -KeepAlive -^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "``$InputPTCPServerKeepAlive``" - -Enable of disable keep-alive packets at the tcp socket layer. The -default is to disable them. - - -KeepAlive.Probes -^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "0", "no", "``$InputPTCPServerKeepAlive_probes``" - -The number of unacknowledged probes to send before considering the -connection dead and notifying the application layer. The default, 0, -means that the operating system defaults are used. This has only -effect if keep-alive is enabled. The functionality may not be -available on all platforms. - - -KeepAlive.Interval -^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "0", "no", "``$InputPTCPServerKeepAlive_intvl``" - -The interval between subsequential keepalive probes, regardless of -what the connection has exchanged in the meantime. The default, 0, -means that the operating system defaults are used. This has only -effect if keep-alive is enabled. The functionality may not be -available on all platforms. - - -KeepAlive.Time -^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "0", "no", "``$InputPTCPServerKeepAlive_time``" - -The interval between the last data packet sent (simple ACKs are not -considered data) and the first keepalive probe; after the connection -is marked to need keepalive, this counter is not used any further. -The default, 0, means that the operating system defaults are used. -This has only effect if keep-alive is enabled. The functionality may -not be available on all platforms. - - -RateLimit.Interval -^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "0", "no", "none" - -Specifies the rate-limiting interval in seconds. Set it to a number -of seconds (5 recommended) to activate rate-limiting. - - -RateLimit.Burst -^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "10000", "no", "none" - -Specifies the rate-limiting burst in number of messages. - - -Compression.mode -^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "word", "none", "no", "none" - -This is the counterpart to the compression modes set in -:doc:`omfwd `. -Please see it's documentation for details. - - -flowControl -^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "on", "no", "none" - -Flow control is used to throttle the sender if the receiver queue is -near-full preserving some space for input that can not be throttled. - - -MultiLine -^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "none" - -Experimental parameter which causes rsyslog to recognize a new message -only if the line feed is followed by a '<' or if there are no more characters. - - -framing.delimiter.regex -^^^^^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "off", "no", "none" - -Experimental parameter. It is similar to "MultiLine", but provides greater -control of when a log message ends. You can specify a regular expression that -characterizes the header to expect at the start of the next message. As such, -it indicates the end of the current message. For example, one can use this -setting to use an RFC3164 header as frame delimiter:: - - framing.delimiter.regex="^<[0-9]{1,3}>(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)" - -Note that when oversize messages arrive this mode may have problems finding -the proper frame terminator. There are some provisions inside imptcp to make -these kinds of problems unlikely, but if the messages are very much over the -configured MaxMessageSize, imptcp emits an error messages. Chances are great -it will properly recover from such a situation. - - -SocketBacklog -^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "integer", "64", "no", "none" - -Specifies the backlog parameter passed to the `listen()` system call. This parameter -defines the maximum length of the queue for pending connections, which includes -partially established connections (those in the SYN-ACK handshake phase) and fully -established connections waiting to be accepted by the application. - -For more details, refer to the `listen(2)` man page. - -By default, the value is set to 64 to accommodate modern workloads. It can -be adjusted to suit specific requirements, such as: - -- **High rates of concurrent connection attempts**: Increasing this value helps handle bursts of incoming connections without dropping them. -- **Test environments with connection flooding**: Larger values are recommended to prevent SYN queue overflow. -- **Servers with low traffic**: Lower values may be used to reduce memory usage. - -The effective backlog size is influenced by system-wide kernel settings, particularly `net.core.somaxconn` and `net.ipv4.tcp_max_syn_backlog`. The smaller value between this parameter and the kernel limits is used as the actual backlog. - - -Defaulttz -^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "none", "no", "none" - -Set default time zone. At most seven chars are set, as we would otherwise -overrun our buffer. - - -Framingfix.cisco.asa -^^^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "binary", "off", "no", "none" - -Cisco very occasionally sends a space after a line feed, which thrashes framing -if not taken special care of. When this parameter is set to "on", we permit -space *in front of the next frame* and ignore it. - - -ListenPortFileName -^^^^^^^^^^^^^^^^^^ - -.. csv-table:: - :header: "type", "default", "mandatory", "|FmtObsoleteName| directive" - :widths: auto - :class: parameter-table - - "string", "none", "no", "none" - -.. versionadded:: 8.38.0 - -With this parameter you can specify the name for a file. In this file the -port, imptcp is connected to, will be written. -This parameter was introduced because the testbench works with dynamic ports. - - +.. list-table:: + :widths: 30 70 + :header-rows: 1 + + * - Parameter + - Summary + * - :ref:`param-imptcp-port` + - .. include:: ../../reference/parameters/imptcp-port.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-path` + - .. include:: ../../reference/parameters/imptcp-path.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-discardtruncatedmsg` + - .. include:: ../../reference/parameters/imptcp-discardtruncatedmsg.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-fileowner` + - .. include:: ../../reference/parameters/imptcp-fileowner.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-fileownernum` + - .. include:: ../../reference/parameters/imptcp-fileownernum.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-filegroup` + - .. include:: ../../reference/parameters/imptcp-filegroup.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-filegroupnum` + - .. include:: ../../reference/parameters/imptcp-filegroupnum.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-filecreatemode` + - .. include:: ../../reference/parameters/imptcp-filecreatemode.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-failonchownfailure` + - .. include:: ../../reference/parameters/imptcp-failonchownfailure.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-unlink` + - .. include:: ../../reference/parameters/imptcp-unlink.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-name` + - .. include:: ../../reference/parameters/imptcp-name.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-ruleset` + - .. include:: ../../reference/parameters/imptcp-ruleset.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-maxframesize` + - .. include:: ../../reference/parameters/imptcp-maxframesize.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-maxsessions` + - .. include:: ../../reference/parameters/imptcp-maxsessions.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-address` + - .. include:: ../../reference/parameters/imptcp-address.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-addtlframedelimiter` + - .. include:: ../../reference/parameters/imptcp-addtlframedelimiter.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-supportoctetcountedframing` + - .. include:: ../../reference/parameters/imptcp-supportoctetcountedframing.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-notifyonconnectionclose` + - .. include:: ../../reference/parameters/imptcp-notifyonconnectionclose.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-notifyonconnectionopen` + - .. include:: ../../reference/parameters/imptcp-notifyonconnectionopen.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-keepalive` + - .. include:: ../../reference/parameters/imptcp-keepalive.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-keepalive-probes` + - .. include:: ../../reference/parameters/imptcp-keepalive-probes.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-keepalive-interval` + - .. include:: ../../reference/parameters/imptcp-keepalive-interval.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-keepalive-time` + - .. include:: ../../reference/parameters/imptcp-keepalive-time.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-ratelimit-interval` + - .. include:: ../../reference/parameters/imptcp-ratelimit-interval.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-ratelimit-burst` + - .. include:: ../../reference/parameters/imptcp-ratelimit-burst.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-compression-mode` + - .. include:: ../../reference/parameters/imptcp-compression-mode.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-flowcontrol` + - .. include:: ../../reference/parameters/imptcp-flowcontrol.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-multiline` + - .. include:: ../../reference/parameters/imptcp-multiline.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-framing-delimiter-regex` + - .. include:: ../../reference/parameters/imptcp-framing-delimiter-regex.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-socketbacklog` + - .. include:: ../../reference/parameters/imptcp-socketbacklog.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-defaulttz` + - .. include:: ../../reference/parameters/imptcp-defaulttz.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-framingfix-cisco-asa` + - .. include:: ../../reference/parameters/imptcp-framingfix-cisco-asa.rst + :start-after: .. summary-start + :end-before: .. summary-end + * - :ref:`param-imptcp-listenportfilename` + - .. include:: ../../reference/parameters/imptcp-listenportfilename.rst + :start-after: .. summary-start + :end-before: .. summary-end .. _imptcp-statistic-counter: Statistic Counter @@ -722,3 +273,41 @@ Create a unix domain socket: input(type="imptcp" path="/tmp/unix.sock" unlink="on") +.. toctree:: + :hidden: + + ../../reference/parameters/imptcp-threads + ../../reference/parameters/imptcp-maxsessions + ../../reference/parameters/imptcp-processonpoller + ../../reference/parameters/imptcp-port + ../../reference/parameters/imptcp-path + ../../reference/parameters/imptcp-discardtruncatedmsg + ../../reference/parameters/imptcp-fileowner + ../../reference/parameters/imptcp-fileownernum + ../../reference/parameters/imptcp-filegroup + ../../reference/parameters/imptcp-filegroupnum + ../../reference/parameters/imptcp-filecreatemode + ../../reference/parameters/imptcp-failonchownfailure + ../../reference/parameters/imptcp-unlink + ../../reference/parameters/imptcp-name + ../../reference/parameters/imptcp-ruleset + ../../reference/parameters/imptcp-maxframesize + ../../reference/parameters/imptcp-address + ../../reference/parameters/imptcp-addtlframedelimiter + ../../reference/parameters/imptcp-supportoctetcountedframing + ../../reference/parameters/imptcp-notifyonconnectionclose + ../../reference/parameters/imptcp-notifyonconnectionopen + ../../reference/parameters/imptcp-keepalive + ../../reference/parameters/imptcp-keepalive-probes + ../../reference/parameters/imptcp-keepalive-interval + ../../reference/parameters/imptcp-keepalive-time + ../../reference/parameters/imptcp-ratelimit-interval + ../../reference/parameters/imptcp-ratelimit-burst + ../../reference/parameters/imptcp-compression-mode + ../../reference/parameters/imptcp-flowcontrol + ../../reference/parameters/imptcp-multiline + ../../reference/parameters/imptcp-framing-delimiter-regex + ../../reference/parameters/imptcp-socketbacklog + ../../reference/parameters/imptcp-defaulttz + ../../reference/parameters/imptcp-framingfix-cisco-asa + ../../reference/parameters/imptcp-listenportfilename diff --git a/doc/source/reference/parameters/imptcp-address.rst b/doc/source/reference/parameters/imptcp-address.rst new file mode 100644 index 000000000..563593352 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-address.rst @@ -0,0 +1,54 @@ +.. _param-imptcp-address: +.. _imptcp.parameter.input.address: + +Address +======= + +.. index:: + single: imptcp; Address + single: Address + +.. summary-start + +Specifies the local address to bind the listener to. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Address +:Scope: input +:Type: string +:Default: input=none +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +On multi-homed machines, specifies to which local address the +listener should be bound. + +Input usage +----------- +.. _param-imptcp-input-address: +.. _imptcp.parameter.input.address-usage: + +.. code-block:: rsyslog + + input(type="imptcp" address="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverlistenip: + +- $InputPTCPServerListenIP — maps to Address (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerListenIP + single: $InputPTCPServerListenIP + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-addtlframedelimiter.rst b/doc/source/reference/parameters/imptcp-addtlframedelimiter.rst new file mode 100644 index 000000000..62a38060e --- /dev/null +++ b/doc/source/reference/parameters/imptcp-addtlframedelimiter.rst @@ -0,0 +1,76 @@ +.. _param-imptcp-addtlframedelimiter: +.. _imptcp.parameter.input.addtlframedelimiter: + +AddtlFrameDelimiter +=================== + +.. index:: + single: imptcp; AddtlFrameDelimiter + single: AddtlFrameDelimiter + +.. summary-start + +Defines an additional ASCII frame delimiter for non-standard senders. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: AddtlFrameDelimiter +:Scope: input +:Type: integer +:Default: input=-1 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +This directive permits to specify an additional frame delimiter for +plain tcp syslog. The industry-standard specifies using the LF +character as frame delimiter. Some vendors, notable Juniper in their +NetScreen products, use an invalid frame delimiter, in Juniper's case +the NUL character. This directive permits to specify the ASCII value +of the delimiter in question. Please note that this does not +guarantee that all wrong implementations can be cured with this +directive. It is not even a sure fix with all versions of NetScreen, +as I suggest the NUL character is the effect of a (common) coding +error and thus will probably go away at some time in the future. But +for the time being, the value 0 can probably be used to make rsyslog +handle NetScreen's invalid syslog/tcp framing. For additional +information, see this `forum +thread `_. +**If this doesn't work for you, please do not blame the rsyslog team. +Instead file a bug report with Juniper!** + +Note that a similar, but worse, issue exists with Cisco's IOS +implementation. They do not use any framing at all. This is confirmed +from Cisco's side, but there seems to be very limited interest in +fixing this issue. This directive **can not** fix the Cisco bug. That +would require much more code changes, which I was unable to do so +far. Full details can be found at the `Cisco tcp syslog +anomaly `_ page. + +Input usage +----------- +.. _param-imptcp-input-addtlframedelimiter: +.. _imptcp.parameter.input.addtlframedelimiter-usage: + +.. code-block:: rsyslog + + input(type="imptcp" addtlFrameDelimiter="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserveraddtlframedelimiter: + +- $InputPTCPServerAddtlFrameDelimiter — maps to AddtlFrameDelimiter (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerAddtlFrameDelimiter + single: $InputPTCPServerAddtlFrameDelimiter + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-compression-mode.rst b/doc/source/reference/parameters/imptcp-compression-mode.rst new file mode 100644 index 000000000..0b3d02a0e --- /dev/null +++ b/doc/source/reference/parameters/imptcp-compression-mode.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-compression-mode: +.. _imptcp.parameter.input.compression-mode: + +Compression.mode +================ + +.. index:: + single: imptcp; Compression.mode + single: Compression.mode + +.. summary-start + +Selects decompression mode matching compression used by omfwd. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Compression.mode +:Scope: input +:Type: word +:Default: input=none +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +This is the counterpart to the compression modes set in +:doc:`omfwd <../../configuration/modules/omfwd>`. +Please see its documentation for details. + +Input usage +----------- +.. _param-imptcp-input-compression-mode: +.. _imptcp.parameter.input.compression-mode-usage: + +.. code-block:: rsyslog + + input(type="imptcp" compression.mode="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-defaulttz.rst b/doc/source/reference/parameters/imptcp-defaulttz.rst new file mode 100644 index 000000000..aaad2f4c2 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-defaulttz.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-defaulttz: +.. _imptcp.parameter.input.defaulttz: + +Defaulttz +========= + +.. index:: + single: imptcp; Defaulttz + single: Defaulttz + +.. summary-start + +Sets a default time zone string. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Defaulttz +:Scope: input +:Type: string +:Default: input=none +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Set default time zone. At most seven chars are set, as we would otherwise +overrun our buffer. + +Input usage +----------- +.. _param-imptcp-input-defaulttz: +.. _imptcp.parameter.input.defaulttz-usage: + +.. code-block:: rsyslog + + input(type="imptcp" defaulttz="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-discardtruncatedmsg.rst b/doc/source/reference/parameters/imptcp-discardtruncatedmsg.rst new file mode 100644 index 000000000..e80be8f3b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-discardtruncatedmsg.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-discardtruncatedmsg: +.. _imptcp.parameter.input.discardtruncatedmsg: + +DiscardTruncatedMsg +=================== + +.. index:: + single: imptcp; DiscardTruncatedMsg + single: DiscardTruncatedMsg + +.. summary-start + +Discards the remaining part of a message after truncation. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: DiscardTruncatedMsg +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +When a message is split because it is too long the second part is normally +processed as the next message. This can cause problems. When this parameter +is turned on the part of the message after the truncation will be discarded. + +Input usage +----------- +.. _param-imptcp-input-discardtruncatedmsg: +.. _imptcp.parameter.input.discardtruncatedmsg-usage: + +.. code-block:: rsyslog + + input(type="imptcp" discardTruncatedMsg="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-failonchownfailure.rst b/doc/source/reference/parameters/imptcp-failonchownfailure.rst new file mode 100644 index 000000000..b38d806f8 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-failonchownfailure.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-failonchownfailure: +.. _imptcp.parameter.input.failonchownfailure: + +FailOnChOwnFailure +================== + +.. index:: + single: imptcp; FailOnChOwnFailure + single: FailOnChOwnFailure + +.. summary-start + +Controls startup failure if changing socket owner, group, or mode fails. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: FailOnChOwnFailure +:Scope: input +:Type: boolean +:Default: input=on +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Rsyslog will not start if this is on and changing the file owner, group, +or access permissions fails. Disable this to ignore these errors. + +Input usage +----------- +.. _param-imptcp-input-failonchownfailure: +.. _imptcp.parameter.input.failonchownfailure-usage: + +.. code-block:: rsyslog + + input(type="imptcp" failOnChOwnFailure="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-filecreatemode.rst b/doc/source/reference/parameters/imptcp-filecreatemode.rst new file mode 100644 index 000000000..ff30f127b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-filecreatemode.rst @@ -0,0 +1,45 @@ +.. _param-imptcp-filecreatemode: +.. _imptcp.parameter.input.filecreatemode: + +FileCreateMode +============== + +.. index:: + single: imptcp; FileCreateMode + single: FileCreateMode + +.. summary-start + +Sets access permissions for the Unix-domain socket. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: FileCreateMode +:Scope: input +:Type: octalNumber +:Default: input=0644 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Set the access permissions for the domain socket. The value given must +always be a 4-digit octal number, with the initial digit being zero. +Please note that the actual permission depend on rsyslogd's process +umask. If in doubt, use "``$umask 0000``" right at the beginning of the +configuration file to remove any restrictions. + +Input usage +----------- +.. _param-imptcp-input-filecreatemode: +.. _imptcp.parameter.input.filecreatemode-usage: + +.. code-block:: rsyslog + + input(type="imptcp" fileCreateMode="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-filegroup.rst b/doc/source/reference/parameters/imptcp-filegroup.rst new file mode 100644 index 000000000..839390467 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-filegroup.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-filegroup: +.. _imptcp.parameter.input.filegroup: + +FileGroup +========= + +.. index:: + single: imptcp; FileGroup + single: FileGroup + +.. summary-start + +Sets the group of the Unix-domain socket by group name. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: FileGroup +:Scope: input +:Type: GID +:Default: input=system default +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Set the group for the domain socket. The parameter is a group name, for +which the groupid is obtained by rsyslogd during startup processing. +Interim changes to the user mapping are not detected. + +Input usage +----------- +.. _param-imptcp-input-filegroup: +.. _imptcp.parameter.input.filegroup-usage: + +.. code-block:: rsyslog + + input(type="imptcp" fileGroup="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-filegroupnum.rst b/doc/source/reference/parameters/imptcp-filegroupnum.rst new file mode 100644 index 000000000..93b43539b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-filegroupnum.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-filegroupnum: +.. _imptcp.parameter.input.filegroupnum: + +FileGroupNum +============ + +.. index:: + single: imptcp; FileGroupNum + single: FileGroupNum + +.. summary-start + +Sets the group of the Unix-domain socket by numeric GID. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: FileGroupNum +:Scope: input +:Type: integer +:Default: input=system default +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Set the group for the domain socket. The parameter is a numerical ID, +which is used regardless of whether the group actually exists. This can +be useful if the group mapping is not available to rsyslog during startup. + +Input usage +----------- +.. _param-imptcp-input-filegroupnum: +.. _imptcp.parameter.input.filegroupnum-usage: + +.. code-block:: rsyslog + + input(type="imptcp" fileGroupNum="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-fileowner.rst b/doc/source/reference/parameters/imptcp-fileowner.rst new file mode 100644 index 000000000..fef1901ce --- /dev/null +++ b/doc/source/reference/parameters/imptcp-fileowner.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-fileowner: +.. _imptcp.parameter.input.fileowner: + +FileOwner +========= + +.. index:: + single: imptcp; FileOwner + single: FileOwner + +.. summary-start + +Sets the owner of the Unix-domain socket by user name. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: FileOwner +:Scope: input +:Type: UID +:Default: input=system default +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Set the file owner for the domain socket. The parameter is a user name, +for which the userid is obtained by rsyslogd during startup processing. +Interim changes to the user mapping are *not* detected. + +Input usage +----------- +.. _param-imptcp-input-fileowner: +.. _imptcp.parameter.input.fileowner-usage: + +.. code-block:: rsyslog + + input(type="imptcp" fileOwner="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-fileownernum.rst b/doc/source/reference/parameters/imptcp-fileownernum.rst new file mode 100644 index 000000000..a6040de2f --- /dev/null +++ b/doc/source/reference/parameters/imptcp-fileownernum.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-fileownernum: +.. _imptcp.parameter.input.fileownernum: + +FileOwnerNum +============ + +.. index:: + single: imptcp; FileOwnerNum + single: FileOwnerNum + +.. summary-start + +Sets the owner of the Unix-domain socket by numeric UID. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: FileOwnerNum +:Scope: input +:Type: integer +:Default: input=system default +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Set the file owner for the domain socket. The parameter is a numerical ID, +which is used regardless of whether the user actually exists. This can be +useful if the user mapping is not available to rsyslog during startup. + +Input usage +----------- +.. _param-imptcp-input-fileownernum: +.. _imptcp.parameter.input.fileownernum-usage: + +.. code-block:: rsyslog + + input(type="imptcp" fileOwnerNum="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-flowcontrol.rst b/doc/source/reference/parameters/imptcp-flowcontrol.rst new file mode 100644 index 000000000..e3ce113a2 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-flowcontrol.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-flowcontrol: +.. _imptcp.parameter.input.flowcontrol: + +flowControl +=========== + +.. index:: + single: imptcp; flowControl + single: flowControl + +.. summary-start + +Throttles the sender when the receiver queue is nearly full. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: flowControl +:Scope: input +:Type: boolean +:Default: input=on +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Flow control is used to throttle the sender if the receiver queue is +near-full preserving some space for input that can not be throttled. + +Input usage +----------- +.. _param-imptcp-input-flowcontrol: +.. _imptcp.parameter.input.flowcontrol-usage: + +.. code-block:: rsyslog + + input(type="imptcp" flowControl="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-framing-delimiter-regex.rst b/doc/source/reference/parameters/imptcp-framing-delimiter-regex.rst new file mode 100644 index 000000000..d55a0369e --- /dev/null +++ b/doc/source/reference/parameters/imptcp-framing-delimiter-regex.rst @@ -0,0 +1,53 @@ +.. _param-imptcp-framing-delimiter-regex: +.. _imptcp.parameter.input.framing-delimiter-regex: + +framing.delimiter.regex +======================= + +.. index:: + single: imptcp; framing.delimiter.regex + single: framing.delimiter.regex + +.. summary-start + +Uses a regular expression to identify the start of the next message. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: framing.delimiter.regex +:Scope: input +:Type: string +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Experimental parameter. It is similar to "MultiLine", but provides greater +control of when a log message ends. You can specify a regular expression that +characterizes the header to expect at the start of the next message. As such, +it indicates the end of the current message. For example, one can use this +setting to use an RFC3164 header as frame delimiter:: + + framing.delimiter.regex="^<[0-9]{1,3}>(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)" + +Note that when oversize messages arrive this mode may have problems finding +the proper frame terminator. There are some provisions inside imptcp to make +these kinds of problems unlikely, but if the messages are very much over the +configured MaxMessageSize, imptcp emits an error messages. Chances are great +it will properly recover from such a situation. + +Input usage +----------- +.. _param-imptcp-input-framing-delimiter-regex: +.. _imptcp.parameter.input.framing-delimiter-regex-usage: + +.. code-block:: rsyslog + + input(type="imptcp" framing.delimiter.regex="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-framingfix-cisco-asa.rst b/doc/source/reference/parameters/imptcp-framingfix-cisco-asa.rst new file mode 100644 index 000000000..c861fb1cd --- /dev/null +++ b/doc/source/reference/parameters/imptcp-framingfix-cisco-asa.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-framingfix-cisco-asa: +.. _imptcp.parameter.input.framingfix-cisco-asa: + +Framingfix.cisco.asa +==================== + +.. index:: + single: imptcp; Framingfix.cisco.asa + single: Framingfix.cisco.asa + +.. summary-start + +Ignores a leading space after a line feed to work around Cisco ASA framing issues. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Framingfix.cisco.asa +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Cisco very occasionally sends a space after a line feed, which thrashes framing +if not taken special care of. When this parameter is set to "on", we permit +space *in front of the next frame* and ignore it. + +Input usage +----------- +.. _param-imptcp-input-framingfix-cisco-asa: +.. _imptcp.parameter.input.framingfix-cisco-asa-usage: + +.. code-block:: rsyslog + + input(type="imptcp" framingfix.cisco.asa="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-keepalive-interval.rst b/doc/source/reference/parameters/imptcp-keepalive-interval.rst new file mode 100644 index 000000000..dc8e2239f --- /dev/null +++ b/doc/source/reference/parameters/imptcp-keepalive-interval.rst @@ -0,0 +1,57 @@ +.. _param-imptcp-keepalive-interval: +.. _imptcp.parameter.input.keepalive-interval: + +KeepAlive.Interval +================== + +.. index:: + single: imptcp; KeepAlive.Interval + single: KeepAlive.Interval + +.. summary-start + +Sets the interval between keepalive probes. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: KeepAlive.Interval +:Scope: input +:Type: integer +:Default: input=0 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +The interval between subsequential keepalive probes, regardless of +what the connection has exchanged in the meantime. The default, 0, +means that the operating system defaults are used. This has only +effect if keep-alive is enabled. The functionality may not be +available on all platforms. + +Input usage +----------- +.. _param-imptcp-input-keepalive-interval: +.. _imptcp.parameter.input.keepalive-interval-usage: + +.. code-block:: rsyslog + + input(type="imptcp" keepAlive.interval="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverkeepalive_intvl: + +- $InputPTCPServerKeepAlive_intvl — maps to KeepAlive.Interval (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerKeepAlive_intvl + single: $InputPTCPServerKeepAlive_intvl + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-keepalive-probes.rst b/doc/source/reference/parameters/imptcp-keepalive-probes.rst new file mode 100644 index 000000000..461d38d0b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-keepalive-probes.rst @@ -0,0 +1,57 @@ +.. _param-imptcp-keepalive-probes: +.. _imptcp.parameter.input.keepalive-probes: + +KeepAlive.Probes +================ + +.. index:: + single: imptcp; KeepAlive.Probes + single: KeepAlive.Probes + +.. summary-start + +Sets the number of unacknowledged keepalive probes before the connection is considered dead. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: KeepAlive.Probes +:Scope: input +:Type: integer +:Default: input=0 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +The number of unacknowledged probes to send before considering the +connection dead and notifying the application layer. The default, 0, +means that the operating system defaults are used. This has only +effect if keep-alive is enabled. The functionality may not be +available on all platforms. + +Input usage +----------- +.. _param-imptcp-input-keepalive-probes: +.. _imptcp.parameter.input.keepalive-probes-usage: + +.. code-block:: rsyslog + + input(type="imptcp" keepAlive.probes="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverkeepalive_probes: + +- $InputPTCPServerKeepAlive_probes — maps to KeepAlive.Probes (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerKeepAlive_probes + single: $InputPTCPServerKeepAlive_probes + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-keepalive-time.rst b/doc/source/reference/parameters/imptcp-keepalive-time.rst new file mode 100644 index 000000000..238fc8715 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-keepalive-time.rst @@ -0,0 +1,58 @@ +.. _param-imptcp-keepalive-time: +.. _imptcp.parameter.input.keepalive-time: + +KeepAlive.Time +============== + +.. index:: + single: imptcp; KeepAlive.Time + single: KeepAlive.Time + +.. summary-start + +Sets idle time before the first keepalive probe is sent. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: KeepAlive.Time +:Scope: input +:Type: integer +:Default: input=0 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +The interval between the last data packet sent (simple ACKs are not +considered data) and the first keepalive probe; after the connection +is marked to need keepalive, this counter is not used any further. +The default, 0, means that the operating system defaults are used. +This has only effect if keep-alive is enabled. The functionality may +not be available on all platforms. + +Input usage +----------- +.. _param-imptcp-input-keepalive-time: +.. _imptcp.parameter.input.keepalive-time-usage: + +.. code-block:: rsyslog + + input(type="imptcp" keepAlive.time="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverkeepalive_time: + +- $InputPTCPServerKeepAlive_time — maps to KeepAlive.Time (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerKeepAlive_time + single: $InputPTCPServerKeepAlive_time + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-keepalive.rst b/doc/source/reference/parameters/imptcp-keepalive.rst new file mode 100644 index 000000000..66ff8d95b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-keepalive.rst @@ -0,0 +1,54 @@ +.. _param-imptcp-keepalive: +.. _imptcp.parameter.input.keepalive: + +KeepAlive +========= + +.. index:: + single: imptcp; KeepAlive + single: KeepAlive + +.. summary-start + +Enables TCP keep-alive packets on the socket. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: KeepAlive +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Enable or disable keep-alive packets at the tcp socket layer. The +default is to disable them. + +Input usage +----------- +.. _param-imptcp-input-keepalive: +.. _imptcp.parameter.input.keepalive-usage: + +.. code-block:: rsyslog + + input(type="imptcp" keepAlive="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverkeepalive: + +- $InputPTCPServerKeepAlive — maps to KeepAlive (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerKeepAlive + single: $InputPTCPServerKeepAlive + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-listenportfilename.rst b/doc/source/reference/parameters/imptcp-listenportfilename.rst new file mode 100644 index 000000000..d7aa40a87 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-listenportfilename.rst @@ -0,0 +1,43 @@ +.. _param-imptcp-listenportfilename: +.. _imptcp.parameter.input.listenportfilename: + +ListenPortFileName +================== + +.. index:: + single: imptcp; ListenPortFileName + single: ListenPortFileName + +.. summary-start + +Writes the port number being listened on into the specified file. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: ListenPortFileName +:Scope: input +:Type: string +:Default: input=none +:Required?: no +:Introduced: 8.38.0 + +Description +----------- +With this parameter you can specify the name for a file. In this file the +port, imptcp is connected to, will be written. +This parameter was introduced because the testbench works with dynamic ports. + +Input usage +----------- +.. _param-imptcp-input-listenportfilename: +.. _imptcp.parameter.input.listenportfilename-usage: + +.. code-block:: rsyslog + + input(type="imptcp" listenPortFileName="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-maxframesize.rst b/doc/source/reference/parameters/imptcp-maxframesize.rst new file mode 100644 index 000000000..7bbf00588 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-maxframesize.rst @@ -0,0 +1,46 @@ +.. _param-imptcp-maxframesize: +.. _imptcp.parameter.input.maxframesize: + +MaxFrameSize +============ + +.. index:: + single: imptcp; MaxFrameSize + single: MaxFrameSize + +.. summary-start + +Sets the maximum frame size when using octet counted mode. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: MaxFrameSize +:Scope: input +:Type: integer +:Default: input=200000 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +When in octet counted mode, the frame size is given at the beginning +of the message. With this parameter the max size this frame can have +is specified and when the frame gets too large the mode is switched to +octet stuffing. The max value this parameter can have was specified +because otherwise the integer could become negative and this would +result in a Segmentation Fault. (Max Value: 200000000) + +Input usage +----------- +.. _param-imptcp-input-maxframesize: +.. _imptcp.parameter.input.maxframesize-usage: + +.. code-block:: rsyslog + + input(type="imptcp" maxFrameSize="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-maxsessions.rst b/doc/source/reference/parameters/imptcp-maxsessions.rst new file mode 100644 index 000000000..067662b7e --- /dev/null +++ b/doc/source/reference/parameters/imptcp-maxsessions.rst @@ -0,0 +1,53 @@ +.. _param-imptcp-maxsessions: +.. _imptcp.parameter.module.maxsessions: +.. _imptcp.parameter.input.maxsessions: + +MaxSessions +=========== + +.. index:: + single: imptcp; MaxSessions + single: MaxSessions + +.. summary-start + +Limits the number of open sessions. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: MaxSessions +:Scope: module, input +:Type: integer +:Default: module=0; input=0 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Maximum number of open sessions allowed. When used as a module parameter +this value becomes the default inherited by each ``input()`` instance but +is not a global maximum. When set inside an input, it applies to that +listener. A setting of zero or less than zero means no limit. + +Module usage +------------ +.. _param-imptcp-module-maxsessions: +.. _imptcp.parameter.module.maxsessions-usage: + +.. code-block:: rsyslog + + module(load="imptcp" maxSessions="...") + +Input usage +----------- +.. _param-imptcp-input-maxsessions: +.. _imptcp.parameter.input.maxsessions-usage: +.. code-block:: rsyslog + + input(type="imptcp" maxSessions="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-multiline.rst b/doc/source/reference/parameters/imptcp-multiline.rst new file mode 100644 index 000000000..9eac947eb --- /dev/null +++ b/doc/source/reference/parameters/imptcp-multiline.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-multiline: +.. _imptcp.parameter.input.multiline: + +MultiLine +========= + +.. index:: + single: imptcp; MultiLine + single: MultiLine + +.. summary-start + +Detects a new message only when LF is followed by '<' or end of input. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: MultiLine +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Experimental parameter which causes rsyslog to recognize a new message +only if the line feed is followed by a '<' or if there are no more characters. + +Input usage +----------- +.. _param-imptcp-input-multiline: +.. _imptcp.parameter.input.multiline-usage: + +.. code-block:: rsyslog + + input(type="imptcp" multiLine="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-name.rst b/doc/source/reference/parameters/imptcp-name.rst new file mode 100644 index 000000000..6eff4c62f --- /dev/null +++ b/doc/source/reference/parameters/imptcp-name.rst @@ -0,0 +1,57 @@ +.. _param-imptcp-name: +.. _imptcp.parameter.input.name: + +Name +==== + +.. index:: + single: imptcp; Name + single: Name + +.. summary-start + +Sets the inputname property used for tagging messages and statistics. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Name +:Scope: input +:Type: string +:Default: input=imptcp +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Sets a name for the inputname property. If no name is set "imptcp" is +used by default. Setting a name is not strictly necessary, but can +be useful to apply filtering based on which input the message was +received from. Note that the name also shows up in +:doc:`impstats <../../configuration/modules/impstats>` logs. + +Input usage +----------- +.. _param-imptcp-input-name: +.. _imptcp.parameter.input.name-usage: + +.. code-block:: rsyslog + + input(type="imptcp" name="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverinputname: + +- $InputPTCPServerInputName — maps to Name (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerInputName + single: $InputPTCPServerInputName + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-notifyonconnectionclose.rst b/doc/source/reference/parameters/imptcp-notifyonconnectionclose.rst new file mode 100644 index 000000000..8fb985011 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-notifyonconnectionclose.rst @@ -0,0 +1,54 @@ +.. _param-imptcp-notifyonconnectionclose: +.. _imptcp.parameter.input.notifyonconnectionclose: + +NotifyOnConnectionClose +======================= + +.. index:: + single: imptcp; NotifyOnConnectionClose + single: NotifyOnConnectionClose + +.. summary-start + +Emits a message when a remote peer closes the connection. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: NotifyOnConnectionClose +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Instructs imptcp to emit a message if a remote peer closes the +connection. + +Input usage +----------- +.. _param-imptcp-input-notifyonconnectionclose: +.. _imptcp.parameter.input.notifyonconnectionclose-usage: + +.. code-block:: rsyslog + + input(type="imptcp" notifyOnConnectionClose="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpservernotifyonconnectionclose: + +- $InputPTCPServerNotifyOnConnectionClose — maps to NotifyOnConnectionClose (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerNotifyOnConnectionClose + single: $InputPTCPServerNotifyOnConnectionClose + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-notifyonconnectionopen.rst b/doc/source/reference/parameters/imptcp-notifyonconnectionopen.rst new file mode 100644 index 000000000..491ea3e86 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-notifyonconnectionopen.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-notifyonconnectionopen: +.. _imptcp.parameter.input.notifyonconnectionopen: + +NotifyOnConnectionOpen +====================== + +.. index:: + single: imptcp; NotifyOnConnectionOpen + single: NotifyOnConnectionOpen + +.. summary-start + +Emits a message when a remote peer opens a connection. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: NotifyOnConnectionOpen +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Instructs imptcp to emit a message if a remote peer opens a +connection. Hostname of the remote peer is given in the message. + +Input usage +----------- +.. _param-imptcp-input-notifyonconnectionopen: +.. _imptcp.parameter.input.notifyonconnectionopen-usage: + +.. code-block:: rsyslog + + input(type="imptcp" notifyOnConnectionOpen="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-path.rst b/doc/source/reference/parameters/imptcp-path.rst new file mode 100644 index 000000000..dd4087a6d --- /dev/null +++ b/doc/source/reference/parameters/imptcp-path.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-path: +.. _imptcp.parameter.input.path: + +Path +==== + +.. index:: + single: imptcp; Path + single: Path + +.. summary-start + +Specifies a Unix-domain socket path for the listener. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Path +:Scope: input +:Type: string +:Default: input=none +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +A path on the filesystem for a unix domain socket. It is an error to specify +both ``path`` and ``port``. + +Input usage +----------- +.. _param-imptcp-input-path: +.. _imptcp.parameter.input.path-usage: + +.. code-block:: rsyslog + + input(type="imptcp" path="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-port.rst b/doc/source/reference/parameters/imptcp-port.rst new file mode 100644 index 000000000..93f998acb --- /dev/null +++ b/doc/source/reference/parameters/imptcp-port.rst @@ -0,0 +1,54 @@ +.. _param-imptcp-port: +.. _imptcp.parameter.input.port: + +Port +==== + +.. index:: + single: imptcp; Port + single: Port + +.. summary-start + +Selects the TCP port on which to listen. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Port +:Scope: input +:Type: string +:Default: input=none +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Select a port to listen on. It is an error to specify +both ``path`` and ``port``. + +Input usage +----------- +.. _param-imptcp-input-port: +.. _imptcp.parameter.input.port-usage: + +.. code-block:: rsyslog + + input(type="imptcp" port="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverrun: + +- $InputPTCPServerRun — maps to Port (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerRun + single: $InputPTCPServerRun + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-processonpoller.rst b/doc/source/reference/parameters/imptcp-processonpoller.rst new file mode 100644 index 000000000..b398a9b08 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-processonpoller.rst @@ -0,0 +1,52 @@ +.. _param-imptcp-processonpoller: +.. _imptcp.parameter.module.processonpoller: + +ProcessOnPoller +=============== + +.. index:: + single: imptcp; ProcessOnPoller + single: ProcessOnPoller + +.. summary-start + +Processes messages on the poller thread when feasible to reduce resource use. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: ProcessOnPoller +:Scope: module +:Type: boolean +:Default: module=on +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Instructs imptcp to process messages on poller thread opportunistically. +This leads to lower resource footprint (as poller thread doubles up as +message-processing thread too). "On" works best when imptcp is handling +low ingestion rates. + +At high throughput though, it causes polling delay (as poller spends time +processing messages, which keeps connections in read-ready state longer +than they need to be, filling socket-buffer, hence eventually applying +backpressure). + +It defaults to allowing messages to be processed on poller (for backward +compatibility). + +Module usage +------------ +.. _param-imptcp-module-processonpoller: +.. _imptcp.parameter.module.processonpoller-usage: + +.. code-block:: rsyslog + + module(load="imptcp" processOnPoller="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-ratelimit-burst.rst b/doc/source/reference/parameters/imptcp-ratelimit-burst.rst new file mode 100644 index 000000000..1b9b8c8c9 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-ratelimit-burst.rst @@ -0,0 +1,41 @@ +.. _param-imptcp-ratelimit-burst: +.. _imptcp.parameter.input.ratelimit-burst: + +RateLimit.Burst +=============== + +.. index:: + single: imptcp; RateLimit.Burst + single: RateLimit.Burst + +.. summary-start + +Sets the rate-limiting burst size in number of messages. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: RateLimit.Burst +:Scope: input +:Type: integer +:Default: input=10000 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Specifies the rate-limiting burst in number of messages. + +Input usage +----------- +.. _param-imptcp-input-ratelimit-burst: +.. _imptcp.parameter.input.ratelimit-burst-usage: + +.. code-block:: rsyslog + + input(type="imptcp" rateLimit.burst="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-ratelimit-interval.rst b/doc/source/reference/parameters/imptcp-ratelimit-interval.rst new file mode 100644 index 000000000..e43c03f7b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-ratelimit-interval.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-ratelimit-interval: +.. _imptcp.parameter.input.ratelimit-interval: + +RateLimit.Interval +================== + +.. index:: + single: imptcp; RateLimit.Interval + single: RateLimit.Interval + +.. summary-start + +Specifies the rate-limiting interval in seconds. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: RateLimit.Interval +:Scope: input +:Type: integer +:Default: input=0 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Specifies the rate-limiting interval in seconds. Set it to a number +of seconds (5 recommended) to activate rate-limiting. + +Input usage +----------- +.. _param-imptcp-input-ratelimit-interval: +.. _imptcp.parameter.input.ratelimit-interval-usage: + +.. code-block:: rsyslog + + input(type="imptcp" rateLimit.interval="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-ruleset.rst b/doc/source/reference/parameters/imptcp-ruleset.rst new file mode 100644 index 000000000..2995a5133 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-ruleset.rst @@ -0,0 +1,54 @@ +.. _param-imptcp-ruleset: +.. _imptcp.parameter.input.ruleset: + +Ruleset +======= + +.. index:: + single: imptcp; Ruleset + single: Ruleset + +.. summary-start + +Binds the specified ruleset to this input. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Ruleset +:Scope: input +:Type: string +:Default: input=none +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Binds specified ruleset to this input. If not set, the default +ruleset is bound. + +Input usage +----------- +.. _param-imptcp-input-ruleset: +.. _imptcp.parameter.input.ruleset-usage: + +.. code-block:: rsyslog + + input(type="imptcp" ruleset="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverbindruleset: + +- $InputPTCPServerBindRuleset — maps to Ruleset (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerBindRuleset + single: $InputPTCPServerBindRuleset + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-socketbacklog.rst b/doc/source/reference/parameters/imptcp-socketbacklog.rst new file mode 100644 index 000000000..c72221a21 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-socketbacklog.rst @@ -0,0 +1,55 @@ +.. _param-imptcp-socketbacklog: +.. _imptcp.parameter.input.socketbacklog: + +SocketBacklog +============= + +.. index:: + single: imptcp; SocketBacklog + single: SocketBacklog + +.. summary-start + +Sets the listen() backlog for pending TCP connections. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: SocketBacklog +:Scope: input +:Type: integer +:Default: input=64 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Specifies the backlog parameter passed to the ``listen()`` system call. This parameter +defines the maximum length of the queue for pending connections, which includes +partially established connections (those in the SYN-ACK handshake phase) and fully +established connections waiting to be accepted by the application. + +For more details, refer to the ``listen(2)`` man page. + +By default, the value is set to 64 to accommodate modern workloads. It can +be adjusted to suit specific requirements, such as: + +- **High rates of concurrent connection attempts**: Increasing this value helps handle bursts of incoming connections without dropping them. +- **Test environments with connection flooding**: Larger values are recommended to prevent SYN queue overflow. +- **Servers with low traffic**: Lower values may be used to reduce memory usage. + +The effective backlog size is influenced by system-wide kernel settings, particularly ``net.core.somaxconn`` and ``net.ipv4.tcp_max_syn_backlog``. The smaller value between this parameter and the kernel limits is used as the actual backlog. + +Input usage +----------- +.. _param-imptcp-input-socketbacklog: +.. _imptcp.parameter.input.socketbacklog-usage: + +.. code-block:: rsyslog + + input(type="imptcp" socketBacklog="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-supportoctetcountedframing.rst b/doc/source/reference/parameters/imptcp-supportoctetcountedframing.rst new file mode 100644 index 000000000..f37d2b7d2 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-supportoctetcountedframing.rst @@ -0,0 +1,57 @@ +.. _param-imptcp-supportoctetcountedframing: +.. _imptcp.parameter.input.supportoctetcountedframing: + +SupportOctetCountedFraming +========================== + +.. index:: + single: imptcp; SupportOctetCountedFraming + single: SupportOctetCountedFraming + +.. summary-start + +Enables legacy octet-counted framing similar to RFC5425. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: SupportOctetCountedFraming +:Scope: input +:Type: boolean +:Default: input=on +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +The legacy octed-counted framing (similar to RFC5425 framing) is +activated. This is the default and should be left unchanged until you +know very well what you do. It may be useful to turn it off, if you know +this framing is not used and some senders emit multi-line messages into +the message stream. + +Input usage +----------- +.. _param-imptcp-input-supportoctetcountedframing: +.. _imptcp.parameter.input.supportoctetcountedframing-usage: + +.. code-block:: rsyslog + + input(type="imptcp" supportOctetCountedFraming="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserversupportoctetcountedframing: + +- $InputPTCPServerSupportOctetCountedFraming — maps to SupportOctetCountedFraming (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerSupportOctetCountedFraming + single: $InputPTCPServerSupportOctetCountedFraming + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-threads.rst b/doc/source/reference/parameters/imptcp-threads.rst new file mode 100644 index 000000000..495ecdea0 --- /dev/null +++ b/doc/source/reference/parameters/imptcp-threads.rst @@ -0,0 +1,59 @@ +.. _param-imptcp-threads: +.. _imptcp.parameter.module.threads: + +Threads +======= + +.. index:: + single: imptcp; Threads + single: Threads + +.. summary-start + +Sets the number of helper threads that pull data off the network. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Threads +:Scope: module +:Type: integer +:Default: module=2 +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +Number of helper worker threads to process incoming messages. These +threads are utilized to pull data off the network. On a busy system, +additional helper threads (but not more than there are CPUs/Cores) +can help improving performance. The default value is two, which means +there is a default thread count of three (the main input thread plus +two helpers). No more than 16 threads can be set (if tried to, +rsyslog always resorts to 16). + +Module usage +------------ +.. _param-imptcp-module-threads: +.. _imptcp.parameter.module.threads-usage: + +.. code-block:: rsyslog + + module(load="imptcp" threads="...") + +Legacy names (for reference) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Historic names/directives for compatibility. Do not use in new configs. + +.. _imptcp.parameter.legacy.inputptcpserverhelperthreads: + +- $InputPTCPServerHelperThreads — maps to Threads (status: legacy) + +.. index:: + single: imptcp; $InputPTCPServerHelperThreads + single: $InputPTCPServerHelperThreads + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`. diff --git a/doc/source/reference/parameters/imptcp-unlink.rst b/doc/source/reference/parameters/imptcp-unlink.rst new file mode 100644 index 000000000..f732e509b --- /dev/null +++ b/doc/source/reference/parameters/imptcp-unlink.rst @@ -0,0 +1,42 @@ +.. _param-imptcp-unlink: +.. _imptcp.parameter.input.unlink: + +Unlink +====== + +.. index:: + single: imptcp; Unlink + single: Unlink + +.. summary-start + +Unlinks a Unix-domain socket before listening and after closing. + +.. summary-end + +This parameter applies to :doc:`../../configuration/modules/imptcp`. + +:Name: Unlink +:Scope: input +:Type: boolean +:Default: input=off +:Required?: no +:Introduced: at least 5.x, possibly earlier + +Description +----------- +If a unix domain socket is being used this controls whether or not the socket +is unlinked before listening and after closing. + +Input usage +----------- +.. _param-imptcp-input-unlink: +.. _imptcp.parameter.input.unlink-usage: + +.. code-block:: rsyslog + + input(type="imptcp" unlink="...") + +See also +-------- +See also :doc:`../../configuration/modules/imptcp`.