Defining a relay rule
- Juan Tomás Alonso Nieto (Unlicensed)
A relay rule evaluates an inbound event by the port it was received on and any other source criteria defined in the rule. When the criteria is met, the rule dictates how the event should be processed. Usually, this means applying a specific Devo tag or filtering out events that don't need to be sent to Devo.
To handle a few common inbound event types, all in-house relays have four predefined rules. Three of these are designed to receive events from specific sources incapable of applying tags, and the fourth rule simply acts as a forwarder for events that are already tagged. These predefined rules use ports 12999-13002. This means you cannot use these ports to set up custom rules.
This article describes how to:
Set up a custom relay rule
- Go to Administration → Relays and click the relay name to open the relay details window to the Relay Input (Rules) tab.
- To set up a new rule, click the Add Rule button.
The Rule Definition window opens. A Rule name and Source port are required. You can set any other criteria for the source data that are necessary for the rule. Use the target fields and checkbox options to determine how to handle the processing.
Rule name Enter a brief name for the rule. Description Optionally, add a description of what the rule does. Source port The rule will be applied to events received at this port on the relay. This is a required field. IP The rule will be applied to data originating from this IP address. Hostname The rule will be applied to data originating from this hostname. Source message, Source data, Source tag These fields are for specifying criteria based on the data contained in the inbound event's syslog header or message. It's important to note that Devo supports the widely-used "BSD syslog protocol" defined in RFC 3164 which describes the tag part of a syslog packet as directly preceding the message part, often separated by a colon, bracket, or space. The Source tag and Source message refer to $syslogtag$ and $msg$ information contained in the source event. Source data is a field that represents the combination of $syslogtag$ and $msg$ information.These fields are often expressed in regex using capturing groups. By using capturing groups in these fields, we can use Devo backreference syntax in the Target tag and Target message fields to reuse content from the original event.
Note that if your regex includes quotes, you must escape them using a \ before each quote to make it work properly.
Sent without syslog tag Select this checkbox if the data source will send events to the relay without a syslog tag component. It's important to specify this so that the relay can correctly parse and identify the component parts of the inbound event. If this option is not set correctly, the messages may be truncated. Target tag This is the Devo tag to be applied to events that meet the conditions of this rule. In this example, the tag is using Devo backreferences \\d1 and \\d2 that refer to capturing groups defined in regular expression set in the Source message or Source data field.
- Example: level1.level2.\\d1.\\d2
Keep in mind:
- Tags may contain hyphens and dots but no other special characters.
- The maximum length of the tag is 50 characters.
Is prefix Select this checkbox if you want to retain the original syslog (source) tag received and append it to the target tag for sending to the Devo Cloud. In other words, you want to treat the target tag as a prefix to the syslog tag as originally received by the relay.
For example, if the syslog tag is "hostd" and the target tag is "box.vmware.esx", the event will be sent to the Devo Cloud with the tag "box.vmware.esx.hostd".
Target message This defines the content of the syslog $msg$ component that the relay will forward to Devo.
This is usually expressed using Devo backreferences that refer to capturing groups defined in regular expression set in the Source message or Source data field. The backreference \\d0 refers to the complete, original syslog $msg$ component.
Stop processing Select this checkbox if you want events that match this rule to undergo no further processing. That is, no subsequent rules should be applied after this rule. Events that do not match the rule will continue to be processed by subsequent rules.
For example, when you set up a rule designed to filter out specific events, you can select Stop processing to indicate that no subsequent rules need to be applied to the events that you filter out.
Drop event Select this checkbox if you want to drop events that meet the conditions of this rule.
This is how you filter events and prevent them from being forwarded to Devo. If you select Drop event, it's advisable to also select the Stop processing option. This will ensure that any events that meet this rule and are dropped, are not subjected to any further processing.
The Source definition (advanced params) fields are used to customize the performance of the TCP/UDP settings on the port specified in the rule:
Source level The rule will only be applied to the events that are received with the syslog level you indicate here. Source facility The rule will only be applied to the events that are received with the syslog facility you indicate here. UDP threads Number of threads used by the UDP port. UDP receive buffer (bytes) The OS receiving buffer size of the socket for this rule/port. Note that 0 means the default OS value. To learn more about this, check this article. Max packet size (bytes) Maximum packet size for transmission over UDP. TCP threads Number of threads used by the TCP port. TCP receive buffer (bytes) The receiving OS buffer size of the socket for this rule/port. Note that 0 means the default OS value. Click Add rule to save the new relay rule.
Edit an existing relay rule
- Go to Administration → Relays and click the relay name to open the relay details window to the Relay Input (Rules) tab.
- Locate the rule you want to edit, then open its ellipsis menu and select Edit Rule.
- Make the necessary changes to the rule and click Save.