A Sumo syslog source operates like a syslog server listening on the designated port to receive syslog messages. You set your hosts or syslog-enabled devices to send syslog data to the same port you specify when you configure the syslog source.
For multiple syslog collections, set up a separate source for each and set a separate port number for each.
If you are editing a source, metadata changes are reflected going forward. Metadata for previously collected log data will not be retroactively changed.
Step 1: Configure a syslog source
In the Sumo web app select Manage Data > Collection > Collection (Manage > Collection in the classic UI).
- Find the installed collector to which you'd like to add the syslog source. Click Add and then choose Add Source from the pop-up menu.
- Select Syslog for the source type.
- Set the following:
- Name. Enter the name you'd like to display for the new source. Description is optional. Source name metadata is stored in a searchable field called _sourceName.
- Protocol. Select the option that your syslog-enabled devices are currently using to send syslog data (UDP or TCP). For more information, see Choosing TCP or UDP.
- Port. Enter the port number for the source to listen to. If the collector runs as root (default), use 514. Otherwise, consider 1514 or 5140. Make sure the devices are sending to the same port.
- Source Category. Enter any string to tag the output collected from this source with searchable metadata. For example, enter firewall to tag all entries from this source in a field called _sourceCategory. Type _sourceCategory=firewall in the Search field to return results from this source. For more information, see Metadata Naming Conventions.
- Set any of the following under Advanced:
- Enable Timestamp Parsing. This option is selected by default. If it's deselected, no timestamp information is parsed at all.
- Time Zone. There are two options for Time Zone. You can use the time zone present in your log files, and then choose an option in case time zone information is missing from a log message. Or, you can have Sumo Logic completely disregard any time zone information present in logs by forcing a time zone. It's very important to have the proper time zone set, no matter which option you choose. If the time zone of logs can't be determined, Sumo assigns logs UTC; if the rest of your logs are from another time zone your search results will be affected.
- Timestamp Format. By default, Sumo will automatically detect the timestamp format of your logs. However, you can manually specify a timestamp format for a source. See Timestamps, Time Zones, Time Ranges, and Date Formats for more information.
- Create any processing rules you'd like for the new source.
- When you are finished configuring the source click Save.
You can return to this dialog and edit the settings for the source at any time.
Step 2: Configure syslog to forward to Sumo source
In addition to configuring the syslog source on an installed collector to receive syslog data from hosts in your environment, you must also configure those hosts to send the syslog data to the source. The process for doing so depends on the syslog agent on your operating system. MacOS and Linux each have a built-in syslog agent. Windows does not include a syslog agent, but a number of third-party syslog agents for Windows are available.
You configure a syslog agent by editing its configuration file. For the built-in syslog agent on LInux and MacOS, the configuration file is typically /etc/syslog.conf. If you use a different syslog implementation, the name of the configuration file may be different.
Each line in the configuration file contains two items: the selector, which specifies the messages to be sent and the action which specifies what to do with matching messages. For example:
- facility.level is the selector.
- facility is the syslog message facility, which identifies the type of software that generated the message. Default syslog message facilities are – auth, authpriv, daemon, cron, ftp, lpr, kern, mail, news, syslog, user, and local0 – local7.
- level indicates message severity: emerg, alert, crit, err, warn, notice, info, or debug. The syslog agent will send messages with the specified severity level and higher. For example, if you specified auth.crit, you would get messages from the authorization system whose severity is emerg, alert, and crit. If you want to get messages of certain severity only, prefix the severity with an equals sign, for example auth.=crit
- action specifies what to do with the messages. There are a variety of types of actions you can specify. For the purpose of this procedure, you’ll use action to specify the address of the collector where you configured the syslog source. To send messages via UDP, use this format: @IP_address. To send messages via TCP, use this format: @@IP_address. If you have configured the Sumo source to list on a port other than 514, specify the port as well, like this: @IP_address:port.
The following line causes messages from all facilities whose severity is crit or higher to be sent via UDP to port 514 on the host whose IP address is 220.127.116.11. (Because port is not specified messages will be sent to the default syslog port, which is 514.)
The following line causes messages whose severity is crit or higher from all facilities to be sent via UDP to port 515 on the host whose IP address is 18.104.22.168.
The following line causes messages whose severity is crit or higher from the auth facility to be sent via UDP to port 514 on the host whose IP address is 22.214.171.124.
The following line causes messages whose severity is crit or higher from the auth facility, and messages of all severity levels from the ftp facility to be sent via TCP to port 514 on the host whose IP address is 126.96.36.199.
Choosing TCP or UDP
When you configure a syslog source, you choose a transfer protocol, either TCP or UDP. If your syslog-enabled hosts or devices have already been configured using TCP or UDP, choose the same protocol. If you are just setting up your devices, your first choice should probably be TCP.
TCP includes a guaranteed delivery mechanism, meaning that the network layer provides that all of your logs arrive at the Sumo collector in order and without any dropped log messages. The downside of this protocol is that it creates more network and CPU overhead than the alternative UDP protocol. However, due to its reliability guarantee, TCP is the recommended protocol unless you have network and CPU utilization concerns that you need to work around due to an extremely high volume of log messages.
The collector supports single-line TCP messages up to 65,535 bytes.
UDP is a streaming protocol that makes no guarantees of delivery, and as such, log messages may be dropped or arrive out of order. However, in return for this lack of guarantee, UDP does not create the same kind of network and CPU overhead that is created by the TCP protocol. In reality, in most networks, UDP is reliable enough for mission-critical use, however, there may be situations where network traffic storms might cause messages to be dropped or arrive out of order. If this is an unacceptable risk for you, then choose TCP.
Per RFC 5426, the collector by default supports UDP messages up to 2048 bytes. To increase the UDP message length limit to the maximum datagram size (65k), you can add the following configuration to collector/config/collector.properties and restart the collector:
collector.syslog.udp.readBufferSize = 65535
Specifying the network interface for a syslog source
When configuring a syslog source in a computer that has more than one network interface you can specify which network interface the collector should bind to. This option is set in the collector.properties file.
To specify the network interface:
- Configure the syslog source.
- Navigate to collector/config/collector.properties. Open the file in a text editor.
- Add syslog.hostname=your_host_name where your_host_name identifies the network interface you'd like to use.
- Save and close the file.
Troubleshooting syslog sources
If data is not being ingested into your syslog source, you may need to add firewall rules to allow inbound traffic on the port the collector is listening on.
For more information, see How to test a Syslog Source in case messages are not ingested.