How to get started with syslog-ng? There are two main resources: the syslog-ng documentation and the syslog-ng blogs. You should learn the concepts and basics from the documentation. The blogs document use cases and you can use the docs as a reference.
Before you begin
As a first step, you should install syslog-ng. Of course, your studies can also be purely theoretic, but I strongly recommend testing what you are learning. Depending on company policies or the feature you need, you might install the version coming with your operating system, or the latest version from third party repositories. You can find information about where to find latest packages at: https://www.syslog-ng.com/products/open-source-log-management/3rd-party-binaries.aspx
Once you installed syslog-ng, check the version number. You need the version number for two reasons:
-
Each new syslog-ng release receives its own documentation, so make sure that you browse or download the right documentation version.
-
Features are added continuously. Blogs usually list the minimal syslog-ng version needed for a given use case.
Blogs
Most of the syslog-ng blogs document new features and use cases: how to send logs to Elasticsearch, how to process Suricata log messages, and so on. Many users first install syslog-ng after reading one of the blogs. Some of them try to use configuration snippets from blogs as if it was Stack Overflow: install syslog-ng and then copy & paste some configuration snippets without trying to understand what they are doing. Of course, it might even work in most cases :-)
Blogs start with information about the minimal syslog-ng version required. This might even set you back one step, if the installed syslog-ng version is too old. Then, they describe how to use syslog-ng in a given situation or how to use a new feature. Blogs do not replace the documentation, rather complement them.
Most syslog-ng features have many parameters. Blogs describe the mandatory parameters and some of the trickier optional ones. However, for a detailed description, you should check the documentation.
The syslog-ng blogs are available at https://www.syslog-ng.com/community/b/blog
Documentation
From the features’ point of view there are no huge differences between various syslog implementations. On the other hand, there are considerable differences when it comes to documentation. For many of our power users, the availability of good documentation was the decisive factor to start using syslog-ng from the many choices.
Sometimes with a bit of a delay, but each syslog-ng version comes with its own version of the documentation. This way you do not have to guess which version implemented a given feature: if it is there, then it works, in the way it is documented.
The syslog-ng administration guide is a reference guide. It does not have much information on use cases – those are covered by the blogs. It has a few introductory chapters, which I highly recommend reading. The bulk of the documentation is a reference guide, describing even the smallest optional parameters of various configuration settings in detail.
The syslog-ng documentation is available at https://www.syslog-ng.com/technical-documents/list/syslog-ng-open-source-edition/
How to get started with learning syslog-ng?
By now, you already know the two main resources to learn from. Learning only from the blogs is not possible as not everything is included. Learning from the documentation is possible, but difficult due to the overwhelming amount of information. So, what do I recommend?
Start with the first few chapters of the documentation:
-
“Introduction to syslog-ng” gives you a good, high-level overview of syslog-ng.
-
“The concepts of syslog-ng” describes how syslog-ng works: the various concepts you need to understand for configuring syslog-ng.
-
“The syslog-ng OSE quick-start guide” gives you a quick overview of the syslog-ng configuration file.
Of course, you can keep reading the syslog-ng administration guide, it is a fantastic source of information. However, the more you keep reading, the better chance you have at reading something that you will not only not use in the short run, but most likely not even in the long run.
Once you finished reading the introductory chapters of the documentation, you should head over to the blogs. There is a good chance that your use case has already been covered by one of the blogs. Search the blogs, read the articles you need and try to implement it in your environment. The blogs try to contain all the information needed to get started with logging the given use case. However, usually there are a lot more configuration parameters available than listed in the blogs. Checking the documentation helps you to better understand the given feature and to fine tune syslog-ng to your environment.
If you do not have a specific use case in mind, and just want to get better known with syslog-ng, there are a couple of longer blogs with a bit more complex configurations that are explained step-by-step. These help you to see the previously learned concepts and configuration basics in action and show you many new possibilities.
The first one is an old blog about working with Suricata logs: https://www.syslog-ng.com/community/b/blog/posts/analyze-your-suricata-logs-in-real-time-using-syslog-ng.
Here is something similar for Apache access log messages: https://www.syslog-ng.com/community/b/blog/posts/analyzing-apache-httpd-logs-in-syslog-ng.
This one explains how to work with JSON formatted log messages from sudo: https://www.syslog-ng.com/community/b/blog/posts/working-with-json-logs-from-sudo-in-syslog-ng.
What is next?
If you are stuck, you can contact syslog-ng users and developers in many ways:
-
Gitter (chat): https://gitter.im/syslog-ng/syslog-ng
-
Mailing list: https://lists.balabit.hu/mailman/listinfo/syslog-ng
-
If you have questions or comments related to syslog-ng, do not hesitate to contact us. You can reach us by email or even chat with us. For a list of possibilities, check our GitHub page under the “Community” section at https://github.com/syslog-ng/syslog-ng. On Twitter, I am available as @PCzanik.