Review comments and a few more macro-related corrections

mrgarris0n · mrgarris0n · commit 7be8fdfd43a4 · 2024-06-04T16:47:41.000+02:00
Signed-off-by: mrgarris0n &lt;gergely.karacsonyi@gmail.com&gt;
diff --git a/_includes/doc/admin-guide/options/flags.md b/_includes/doc/admin-guide/options/flags.md
@@ -31,7 +31,7 @@ The functionality of `no-header` is similar to the `no-parse` flag, but the `no-
 ```
 
 * `no-multi-line`: This flag disables line-breaking in the messages and converts the entire message into a single line. Note that this happens only if the underlying transport method supports multi-line messages. Currently only the `file()` and `pipe()` drivers support multi-line messages.
-* `no-parse`: By default, syslog-ng OSE parses incoming messages as syslog messages. The `no-parse` flag disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application generates a new syslog header (timestamp, host, and so on) automatically and puts the entire incoming message into the `MESSAGE` part of the syslog message (available using the `${MESSAGE}` macro). This flag is useful for parsing messages that do not complying to the syslog format.
+* `no-parse`: By default, syslog-ng OSE parses incoming messages as syslog messages. The `no-parse` flag disables syslog message parsing and processes the complete line as the message part of a syslog message. The syslog-ng OSE application generates a new syslog header (timestamp, host, and so on) automatically and puts the entire incoming message into the `MESSAGE` part of the syslog message (available using the ${MESSAGE} macro). This flag is useful for parsing messages that do not complying to the syslog format.
 * `dont-store-legacy-msghdr`: During default operation, syslog-ng OSE stores the original incoming header of the log message. This is useful if the original format of a non-syslog-compliant message must be retained. The syslog-ng OSE application automatically corrects minor header errors, for example, it adds a whitespace before "msg" in the following message: `Jan 22 10:06:11 host program:msg`. If storage of the original header of the message is not needed, enable the `dont-store-legacy-msghdr` flag.
 * `sanitize-utf8`: When this flag is used, syslog-ng OSE converts non-UTF-8 input to an escaped format, adhering to UTF-8.
 Prior to version 4.6, this only worked with parsing RFC3164 messages. In syslog-ng OSE 4.6 and later versions, RFC5424 and raw messages can also be parsed using this flag.
diff --git a/_includes/doc/admin-guide/options/keep-hostname.md b/_includes/doc/admin-guide/options/keep-hostname.md
@@ -6,10 +6,10 @@
 *Description:* Enable or disable hostname rewriting.
 
 - If enabled (**keep-hostname(yes)**), {{ site.product.short_name }} assumes that the
-    incoming log message was sent by the host specified in the HOST
+    incoming log message was sent by the host specified in the `HOST`
     field of the message.
 
-- If disabled (**keep-hostname(no)**), {{ site.product.short_name }} rewrites the HOST
+- If disabled (**keep-hostname(no)**), {{ site.product.short_name }} rewrites the `HOST`
     field of the message, either to the IP address (if the use-dns()
     parameter is set to **no**), or to the hostname (if the use-dns()
     parameter is set to **yes** and the IP address can be resolved to a
diff --git a/_includes/doc/admin-guide/options/source-flags.md b/_includes/doc/admin-guide/options/source-flags.md
@@ -55,8 +55,8 @@
 
 - *no-hostname*: Enable the no-hostname flag if the log message does
     not include the hostname of the sender host. That way {{ site.product.short_name }}
-    assumes that the first part of the message header is PROGRAM
-    instead of HOST. For example:
+    assumes that the first part of the message header is `PROGRAM`
+    instead of `HOST`. For example:
 
     ```config
     source s_dell {
diff --git a/_includes/doc/admin-guide/options/value-pairs.md b/_includes/doc/admin-guide/options/value-pairs.md
@@ -12,8 +12,8 @@ formatted to JSON format, or directly used in a mongodb() destination.
 
 The following example selects every available information about the log
 message, except for the date-related macros (R\_\* and S\_\*), selects
-the .SDATA.meta.sequenceId macro, and defines a new value-pair called
-MSGHDR that contains the program name and `PID` of the application that
+the ${.SDATA.meta.sequenceId} macro, and defines a new value-pair called
+`MSGHDR` that contains the program name and `PID` of the application that
 sent the log message.
 
 ```config
diff --git a/doc/_admin-guide/020_The_concepts_of_syslog-ng/007_The_structure_of_a_log_message/000_BSD_syslog_messages.md b/doc/_admin-guide/020_The_concepts_of_syslog-ng/007_The_structure_of_a_log_message/000_BSD_syslog_messages.md
@@ -34,10 +34,10 @@ size when using UDP destinations.
 
 ## The PRI message part
 
-This section describes the PRI message part of a syslog message, according to the
+This section describes the `PRI` message part of a syslog message, according to the
 legacy syslog (BSD-syslog) protocol.
 
-The PRI part of the syslog message (known as Priority value) represents
+The `PRI` part of the syslog message (known as Priority value) represents
 the Facility and Severity of the message. Facility represents the part
 of the system sending the message, while Severity marks its importance.
 
@@ -57,7 +57,7 @@ PRI field (that is, Priority value):
 
 >\<133\> Feb 25 14:09:07 webserver syslogd: restart
 
-In this example, \<133\> represents the PRI field (Priority value). The
+In this example, \<133\> represents the `PRI` field (Priority value). The
 syslog message\'s Facility value is 16, and the Severity value is 5.
 
 Substituting the numerical values into the \<PRI\> = ( \<facility\> \*
diff --git a/doc/_admin-guide/020_The_concepts_of_syslog-ng/009_Structuring_macros/000_Specifying_data_types.md b/doc/_admin-guide/020_The_concepts_of_syslog-ng/009_Structuring_macros/000_Specifying_data_types.md
@@ -33,7 +33,7 @@ function supports data types.
 
 ## Example: Using type-hinting
 
-The following example stores the MESSAGE, PID, DATE, and `PROGRAM` fields
+The following example stores the `MESSAGE`, `PID`, `DATE`, and `PROGRAM` fields
 of a log message in a MongoDB database. The `DATE` and `PID` parts are
 stored as numbers instead of strings.  
 
diff --git a/doc/_admin-guide/040_Quick-start_guide/002_Configuring_syslog-ng_relays/001_How_relaying_works.md b/doc/_admin-guide/040_Quick-start_guide/002_Configuring_syslog-ng_relays/001_How_relaying_works.md
@@ -41,7 +41,7 @@ Depending on the settings of syslog-ng-relay, the following can happen.
     (syslog-ng-server) as well, so if syslog-ng-relay is configured
     properly, use the **keep-hostname(yes)** option on syslog-ng-server
     to retain the proper `HOST` field. Setting **keep-hostname(no)** on
-    syslog-ng-server would result in {{ site.product.short_name }} rewriting the HOST
+    syslog-ng-server would result in {{ site.product.short_name }} rewriting the `HOST`
     field to the address of the host that sent the message to
     syslog-ng-server, which is syslog-ng-relay in this case.
 
diff --git a/doc/_admin-guide/060_Sources/150_snmptrap/000_snmptrap_options.md b/doc/_admin-guide/060_Sources/150_snmptrap/000_snmptrap_options.md
@@ -30,7 +30,7 @@ Default value: .snmp. option.
 *Description:* The snmptrap() source automatically parses the traps into
 name-value pairs, so you can handle the content of the trap as a
 structured message. Consequently, you might not even need the
-MESSAGE part of the log message. If set-message-macro() is set to
+`MESSAGE` part of the log message. If set-message-macro() is set to
 **no**, {{ site.product.short_name }} leaves the `MESSAGE` part empty. If
 set-message-macro() is set to **yes**, {{ site.product.short_name }} generates a regular
 log message from the trap.
diff --git a/doc/_admin-guide/070_Destinations/240_SMTP/000_SMTP_options.md b/doc/_admin-guide/070_Destinations/240_SMTP/000_SMTP_options.md
@@ -103,7 +103,7 @@ When using the header option, note the following points:
 - If you set the same custom header multiple times, only the first
     will be added to the email, other occurrences will be ignored.
 
-- It is not possible to set the DATE, Return-Path, Original-Recipient,
+- It is not possible to set the `DATE`, Return-Path, Original-Recipient,
     Content-\*, MIME-\*, Resent-\*, Received headers.
 
 {% include doc/admin-guide/options/hook.md %}
diff --git a/doc/_admin-guide/080_Log/030_Filters/002_Comparing_macro_values.md b/doc/_admin-guide/080_Log/030_Filters/002_Comparing_macro_values.md
@@ -68,7 +68,7 @@ ${PID} macro is not empty):
 filter f_pid {"${PID}" !=""};
 ```
 
-The following expression selects log messages that do not contain a PID.
+The following expression selects log messages that do not contain a `PID`.
 Also, it uses a template as the left argument of the operator and
 compares the values as strings:
 
diff --git a/doc/_admin-guide/080_Log/030_Filters/004_Tagging_messages.md b/doc/_admin-guide/080_Log/030_Filters/004_Tagging_messages.md
@@ -31,7 +31,7 @@ Currently {{ site.product.short_name }} can tag a message at two different place
 
 - To include the tags in the message, use the **${TAGS}** macro in a
     template. Alternatively, if you are using the IETF-syslog message
-    format, you can include the ${TAGS} macro in the .SDATA.meta part
+    format, you can include the ${TAGS} macro in the `.SDATA.meta` part
     of the message. Note that the ${TAGS} macro is available only in
     {{ site.product.short_name }} 3.1.1 and later.
 
diff --git a/doc/_admin-guide/080_Log/030_Filters/005_Filter_functions/003_inlist.md b/doc/_admin-guide/080_Log/030_Filters/005_Filter_functions/003_inlist.md
@@ -9,7 +9,7 @@ id: adm-log-filters-inlist
 in a file, allowing you to do simple, file-based black- and
 whitelisting. The file must be a plain-text file, containing one entry
 per line. The {{ site.product.short_name }} application loads the entire file, and
-compares the value of the specified field (for example, PROGRAM) to
+compares the value of the specified field (for example, `PROGRAM`) to
 entries in the file. When you use the in-list() filter, note the
 following points:
 
@@ -25,7 +25,7 @@ Available in {{ site.product.short_name }} 3.5 and later.
 
 ## Example: Selecting messages using the in-list() filter
 
-Create a text file that contains the programs (as in the PROGRAM
+Create a text file that contains the programs (as in the `PROGRAM`
 field of their log messages) you want to select. For example, you want
 to forward only the logs of a few applications from a host: kernel,
 sshd, and sudo. Create the /etc/syslog-ng/programlist.list file with the
diff --git a/doc/_admin-guide/090_Global_options/000_Global_options.md b/doc/_admin-guide/090_Global_options/000_Global_options.md
@@ -311,7 +311,7 @@ configured to do so.
 |Default:|           yes|
 
 *Description:* Enable {{ site.product.short_name }} to collect UNIX credential
-information (that is, the PID, user ID, and group of the sender process)
+information (that is, the `PID`, user ID, and group of the sender process)
 for messages received using UNIX domain sockets. Available only in
 {{ site.product.name }} 3.7 and later. Note that collecting UNIX
 credential information from sockets in high-traffic environments can be
@@ -431,7 +431,7 @@ The following sub-options are available within the stats() option:
 
 Available in {{ site.product.short_name }} 4.1 and later versions.
 
-*Description:* Configures the behavior of counting messages based on different syslog fields, like SEVERITY, FACILITY, HOST.
+*Description:* Configures the behavior of counting messages based on different syslog fields, like SEVERITY, `FACILITY`, `HOST`.
 
 Possible values:
 
@@ -512,7 +512,7 @@ HOSTID@RCPTID. It has a fixed length: 16+@+8 characters. You can
 include the unique ID in the message by using the macro. For details,
 see ${UNIQID}.
 
-Enabling this option automatically generates the HOSTID. The `HOSTID` is a
+Enabling this option automatically generates the `HOSTID`. The `HOSTID` is a
 persistent, 32-bits-long cryptographically secure pseudo random number,
 that belongs to the host that the {{ site.product.short_name }} is running on. If the
 persist file is damaged, the `HOSTID` might change.
diff --git a/doc/_admin-guide/110_Template_and_rewrite/000_Customize_message_format/004_Macros_of_syslog-ng.md b/doc/_admin-guide/110_Template_and_rewrite/000_Customize_message_format/004_Macros_of_syslog-ng.md
@@ -222,7 +222,7 @@ Available in {{ site.product.short_name }} version 3.4 and later.
 
 The ${MSG} macro is an alias of the ${MESSAGE} macro, using ${MSG} in
 {{ site.product.short_name }} is equivalent to ${MESSAGE}. For details on this macro,
-see MESSAGE.
+see ${MESSAGE}.
 
 ## ${MSGHDR}
 
@@ -246,7 +246,7 @@ relayed without modification.
 Message contents without the program name or pid.
 Starting with {{ site.product.short_name }} 3.0, the following macros are equivalent:
 ${MSGONLY}, ${MSG}, ${MESSAGE}. For consistency, use the ${MESSAGE}
-macro. For details, see MESSAGE.
+macro. For details, see ${MESSAGE}.
 
 ## ${PID}
 
@@ -346,7 +346,7 @@ one of the following:
     timestamp format, then {{ site.product.short_name }} stores the sequence number from
     the message in this macro. If you forward this message the
     IETF-syslog protocol, {{ site.product.short_name }} includes the sequence number
-    received from the Cisco device in the ${.SDATA.meta.sequenceId}
+    received from the Cisco device in the `.SDATA.meta.sequenceId`
     part of the message.
 
     **NOTE:** To enable sequence numbering of log messages on Cisco devices,
@@ -459,9 +459,8 @@ following macros are available in {{ site.product.short_name }} version 3.9 and
 ## ${UNIQID}
 
 A globally unique ID generated from the `HOSTID` and the
-RCPTID in the format of HOSTID@RCPTID. For details, see
-use-uniqid() and
-RCPTID.
+`RCPTID` in the format of HOSTID@RCPTID. For details, see
+use-uniqid() and ${RCPTID}.
 
 Available in {{ site.product.short_name }} version 3.7 and later.
 
diff --git a/doc/_admin-guide/110_Template_and_rewrite/000_Customize_message_format/007_Template_functions_of_syslog-ng.md b/doc/_admin-guide/110_Template_and_rewrite/000_Customize_message_format/007_Template_functions_of_syslog-ng.md
@@ -105,8 +105,8 @@ prerequisites:
 
 The following example selects every available information about the log
 message, except for the date-related macros (R\_\* and S\_\*), selects
-the .SDATA.meta.sequenceId macro, and defines a new value-pair called
-MSGHDR that contains the program name and `PID` of the application that
+the ${.SDATA.meta.sequenceId macro}, and defines a new value-pair called
+`MSGHDR` that contains the program name and `PID` of the application that
 sent the log message (since you will use the template-function in a
 template, you must escape the double-quotes).
 
@@ -246,8 +246,8 @@ value-pairs(): format-json uses a syntax similar to command lines.
 
 The following example selects every available information about the log
 message, except for the date-related macros (R\_\* and S\_\*), selects
-the .SDATA.meta.sequenceId macro, and defines a new value-pair called
-MSGHDR that contains the program name and `PID` of the application that
+the ${.SDATA.meta.sequenceId} macro, and defines a new value-pair called
+`MSGHDR` that contains the program name and `PID` of the application that
 sent the log message (since you will use the template-function in a
 template, you must escape the double-quotes).
 
@@ -302,8 +302,8 @@ value-pairs().
 
 The following example selects every available information about the log
 message, except for the date-related macros (R\_\* and S\_\*), selects
-the .SDATA.meta.sequenceId macro, and defines a new value-pair called
-MSGHDR that contains the program name and `PID` of the application that
+the ${.SDATA.meta.sequenceId} macro, and defines a new value-pair called
+`MSGHDR` that contains the program name and `PID` of the application that
 sent the log message (since you will use the template-function in a
 template, you must escape the double-quotes).
 
@@ -815,7 +815,7 @@ template <template-name> {
 ### Example: Writing template functions in Python
 
 The following example creates a Python template function called
-return\_message that returns the `MESSAGE` part of the log message.
+`return_message` that returns the `MESSAGE` part of the log message.
 
 ```config
 @version: 3.38
@@ -831,7 +831,7 @@ destination d_local {
 ```
 
 The following example creates a Python template function called
-resolve\_host that receives an IP address as an argument, and attempts
+`resolve_host` that receives an IP address as an argument, and attempts
 to resolve it into a hostname.
 
 ```config
diff --git a/doc/_admin-guide/110_Template_and_rewrite/001_Modifying_messages/001_Setting_fields.md b/doc/_admin-guide/110_Template_and_rewrite/001_Modifying_messages/001_Setting_fields.md
@@ -9,10 +9,10 @@ To set a field of the message to a specific value, you have to:
 
 - select the field where it should be included.
 
-You can set the value of available macros, for example, HOST, MESSAGE,
-PROGRAM, or any user-defined macros created using parsers (for details,
+You can set the value of available macros, for example, ${HOST}, ${MESSAGE},
+${PROGRAM}, or any user-defined macros created using parsers (for details,
 see [[parser: Parse and segment structured messages]] and
-[[db-parser: Process message content with a pattern database (patterndb)]].
+[[db-parser: Process message content with a pattern database (patterndb)]]).
 Note that the rewrite operation completely replaces any previous value of that field.
 
 {% include doc/admin-guide/notes/hard-macros.md %}
@@ -37,7 +37,7 @@ rewrite r_rewrite_set{
 };
 ```
 
-The following example appends the \"suffix\" string to the MESSAGE
+The following example appends the \"suffix\" string to the `MESSAGE`
 field:
 
 ```config
diff --git a/doc/_admin-guide/110_Template_and_rewrite/001_Modifying_messages/008_Custom_SDATA_fields.md b/doc/_admin-guide/110_Template_and_rewrite/001_Modifying_messages/008_Custom_SDATA_fields.md
@@ -3,12 +3,12 @@ title: Creating custom SDATA fields
 id: adm-temp-sdata
 description: >-
     If you use RFC-5424 formatted (IETF-syslog) messages, you can also create
-    custom fields in the SDATA part of the message (For details on the SDATA
+    custom fields in the `SDATA` part of the message (For details on the `SDATA`
     message part, see The STRUCTURED-DATA message part).
 ---
 
 According to RFC-5424, the name of the field (its SD-ID) must not contain
-the @ character for reserved SD-IDs. Custom SDATA fields must be in the
+the @ character for reserved SD-IDs. Custom `SDATA` fields must be in the
 following format: .SDATA.group-name@\<private enterprise
 number\>.field-name, for example,
 .SDATA.mySDATA-field-group@18372.4.mySDATA-field. (18372.4 is the
@@ -19,7 +19,7 @@ private enterprise number of One Identity LLC, the developer of
 
 The following example sets the sequence ID field of the
 RFC-5424 formatted (IETF-syslog) messages to a fixed value. This field is
-a predefined SDATA field with a reserved SD-ID, therefore its name does
+a predefined `SDATA` field with a reserved SD-ID, therefore its name does
 not contain the @ character.
 
 ```config
@@ -36,7 +36,7 @@ use the **${.SDATA.groupID.fieldID@18372.4}** macro in a template or
 SQL table, its value will be yes for every message that was processed
 with this rewrite rule, and empty for every other message.
 
-The next example creates a new SDATA field-group and field called custom
+The next example creates a new `SDATA` field-group and field called custom
 and sourceip, respectively:
 
 ```config
@@ -47,12 +47,12 @@ rewrite r_rewrite_set {
 
 If you use the **${.SDATA.custom@18372.4.sourceip}** macro in a
 template or SQL table, its value will be that of the ${SOURCEIP} macro (as
-seen on the machine where the SDATA field was created) for every message
+seen on the machine where the `SDATA` field was created) for every message
 that was processed with this rewrite rule, and empty for every other
 message.
 
 You can verify whether or not the format is correct by looking at the
-actual network traffic. The SDATA field-group will be called
+actual network traffic. The `SDATA` field-group will be called
 custom@18372.4, and sourceip will become a field within that group. If
 you decide to set up several fields, they will be listed in consecutive
-order within the field-group\'s SDATA block.
+order within the field-group\'s `SDATA` block.
diff --git a/doc/_admin-guide/120_Parser/000_Parsing_syslog_messages/000_Syslog_parser_options.md b/doc/_admin-guide/120_Parser/000_Parsing_syslog_messages/000_Syslog_parser_options.md
@@ -24,7 +24,7 @@ If you set drop-invalid() to **no**, the parsing error triggers
 syslog-parser() to rewrite and extend the original log message with the
 following additional information:
 
-- It prepends the following message to the contents of the MESSAGE
+- It prepends the following message to the contents of the `MESSAGE`
     field: Error processing log message.
 
 - It sets the contents of the `PROGRAM` field to syslog-ng.
diff --git a/doc/_admin-guide/120_Parser/023_db_parser/004_The_syslog-ng_patterndb_format/000_patterndb/000_ruleset/001_rules/000_rule/README.md b/doc/_admin-guide/120_Parser/023_db_parser/004_The_syslog-ng_patterndb_format/000_patterndb/000_ruleset/001_rules/000_rule/README.md
@@ -69,7 +69,7 @@ The *\<rules\>* element may contain any number of *\<rule\>* elements.
 
   - *process*: Only messages that are generated by the same process
         of a client belong to the same context, that is, messages that
-        have identical HOST, `PROGRAM` and `PID` values. This is
+        have identical `HOST`, `PROGRAM` and `PID` values. This is
         the default behavior of {{ site.product.short_name }} if context-scope is not
         specified.
 
diff --git a/doc/_admin-guide/120_Parser/023_db_parser/004_The_syslog-ng_patterndb_format/000_patterndb/000_ruleset/002_actions/000_action/000_create_context/README.md b/doc/_admin-guide/120_Parser/023_db_parser/004_The_syslog-ng_patterndb_format/000_patterndb/000_ruleset/002_actions/000_action/000_create_context/README.md
@@ -50,7 +50,7 @@ Available in {{ site.product.short_name }} version 3.8 and later.
 
   - *process*: Only messages that are generated by the same process
         of a client belong to the same context, that is, messages that
-        have identical HOST, `PROGRAM` and `PID` values. This is
+        have identical `HOST`, `PROGRAM` and `PID` values. This is
         the default behavior of {{ site.product.short_name }} if context-scope is not
         specified.
 
diff --git a/doc/_admin-guide/120_Parser/023_db_parser/004_The_syslog-ng_patterndb_format/000_patterndb/000_ruleset/002_actions/000_action/README.md b/doc/_admin-guide/120_Parser/023_db_parser/004_The_syslog-ng_patterndb_format/000_patterndb/000_ruleset/002_actions/000_action/README.md
@@ -113,13 +113,13 @@ when a message matching the rule is received.
     <value name="MESSAGE">A log message matched rule number $.classifier.rule_id</value>
     ```
 
-    Note that currently it is not possible to add DATE, FACILITY, or
+    Note that currently it is not possible to add `DATE`, `FACILITY`, or
     SEVERITY fields to the message.
 
     When the action is used together with message correlation, the
     {{ site.product.short_name }} application automatically adds fields to the
     message based on the context-scope parameter. For example, using
-    context-scope=\"process\" automatically fills the HOST, PROGRAM,
+    context-scope=\"process\" automatically fills the `HOST`, `PROGRAM`,
     and `PID` fields of the generated message.
 
   - *name*: Name of the message field set by the value element.
diff --git a/doc/_admin-guide/130_Correlating_log_messages/001_Referencing_previous_messages_grouping-by.md b/doc/_admin-guide/130_Correlating_log_messages/001_Referencing_previous_messages_grouping-by.md
diff --git a/doc/_admin-guide/130_Correlating_log_messages/002_grouping-by_options.md b/doc/_admin-guide/130_Correlating_log_messages/002_grouping-by_options.md
