Contents
Introduction
syslog-ng is an enhanced log daemon, supporting a wide range of input and output methods: syslog, unstructured text, message queues, databases (SQL and NoSQL alike) and more.
It is available as a rolling release, and there is a new release roughly every second month, containing both new features and fixes for bugs reported for the previous version(s).
Ports History
For a while we provided versioned FreeBSD syslog-ng ports, but it turned out the vast majority of users kept using the sysutils/syslog-ng metaport. So, recently we switched back to a single syslog-ng port in ports.
The default settings of the syslog-ng port cover all the most common use cases without much extra dependencies. If you need some of the extra features, be prepared to compile from ports yourself.
When it comes to default options, we tried to reach a balance. While we tried to avoid any options requiring extra dependencies (so syslog-ng does not pull in Java & friends automatically), some of the most popular features are still enabled to cover as many use cases as possible.
Default Configuration
The default syslog-ng configuration tries to match syslogd behaviour as provided by FreeBSD base. It can work as a replacement, or, with minor configuration editing, can be run alongside syslogd.
The default configuration has JSON and HTTP support enabled. This way you can parse and create JSON payload and send logs to Splunk, Elasticsearch and different cloud services, like Slack or Telegram. These two options cover the needs for the vast majority of the syslog-ng user base.
Installation
Installing using pkg
The FreeBSD project builds ready to install binary packages from ports regularly. This means that you can use binary packages and do not have to compile software yourself unless the default options do not fit your needs.
Installation is as easy as:
# pkg install syslog-ng
Installing from Ports
If you want to use syslog-ng features that require additional dependencies, you can build syslog-ng yourself from FreeBSD Ports. Some examples are Java and Python language bindings, GeoIP, Kafka, MongoDB support and quite a few more.
The syslog-ng port is available under the /usr/ports/sysutils/syslog-ng directory.
The following command brings up a configuration menu:
# make config
Make the necessary changes and save the configuration.
Now you can build and install syslog-ng. Depending on the OPTIONS selected, you may need to configure additional ports in the same way.
# make install clean
This command builds and installs syslog-ng, and cleans up afterwards.
Post Installation
As mentioned earlier, the default syslog-ng configuration in ports enables JSON and HTTP. While you can disable these and save a few kilobytes of memory, it is not recommended. They are used by many of the configuration snippets included in the syslog-ng configuration library (SCL), enabled in the default syslog-ng configuration. If you really need to disable these for some reason, make sure that you create your own syslog-ng.conf without including SCL.
Replacing syslogd
The default configuration of the syslog-ng package is designed to replace syslogd from the base system. The following commands stop and disable syslogd and start and enable syslog-ng on the system:
# service syslogd stop # service syslogd disable # service syslog-ng enable # service syslog-ng start
The default configuration listens on UDP port 514, just as syslogd. Edit /usr/local/etc/syslog-ng.conf and remove udp(); from the source called src.
Using syslog-ng in parallel with syslogd
Another frequent use case is, when all you want is running syslog-ng as your central syslog server, log aggregator, but keep syslogd from the base system. In this case you need to edit /usr/local/etc/syslog-ng.conf before enabling and starting syslog-ng. Make sure that you do not collect logs from the system(); source, as it conflicts with syslogd. Once ready, you can enable and start syslog-ng:
# service syslog-ng enable # service syslog-ng start
Central Log Aggregation
One of the most typical use of syslog-ng is central log aggregation. The following simple configuration just achieves that. It collects log messages on TCP port 514 and saves them to directories and files based on sender host name and current date. You can either append it to your syslog-ng.conf, so it will extend your original configuration, or replace it (make sure, that you include the version declaration at the beginning of the file).
source s_remote {
tcp(port(514));
};
destination d_remote {
file(
"/var/log/remote/${HOST}/${YEAR}_${MONTH}_${DAY}.log"
create-dirs(yes)
);
};
log {
source(s_remote);
destination(d_remote);
};The source enables syslog-ng to listen on TCP port 514 using the legacy (but still a lot more popular) RFC 3164.
The destination writes log messages to files based on the originating host name and the current date. You can read about many more macros you can use in the syslog-ng documentation.
Finally the log statement connects the source and destination together.
Once you restarted syslog-ng you can test remote log collection by using the loggen utility installed with syslog-ng (logger does not support sending TCP logs).
loggen -i -S -n 1 localhost 514
Now you should see a new file on your file system. For example:
root@fb130:~ # cat /var/log/remote/localhost/2021_05_05.log May 5 14:44:34 localhost prg00000[1234]: seq: 0000000000, thread: 0000, runid: 1620218674, stamp: 2021-05-05T14:44:34 PADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADDPADD root@fb130:~ #
Additional Resources
Of course this wiki page could only cover a FreeBSD specific introduction. Here a few more pointers where you can find help:
website: https://www.syslog-ng.com/products/open-source-log-management/
documentation: https://www.syslog-ng.com/technical-documents/list/syslog-ng-open-source-edition/
mailing list: https://lists.balabit.hu/mailman/listinfo/syslog-ng
source code and issue tracker: https://github.com/syslog-ng/syslog-ng/