Installing rsyslog from Source¶
Written by Rainer Gerhards
In this paper, I describe how to install rsyslog. It is intentionally a brief step-by-step guide, targeted to those who want to quickly get it up and running. For more elaborate information, please consult the rest of the manual set.
How to make your life easier…¶
In addition to building from source, you can also install
using packages. If you use them, you can spare yourself many of the steps
below. This is highly recommended if there is a package for your
distribution available. See Installing rsyslog from Package for instructions.
Steps To Do¶
Step 1 - Download Software¶
For obvious reasons, you need to download rsyslog. Here, I assume that you use a distribution tarball. If you would like to use a version directly from the repository, see Installing rsyslog from the source repository instead.
Load the most recent build from http://www.rsyslog.com/downloads. Extract the software with “tar xzf -nameOfDownloadSet-“. This will create a new subdirectory rsyslog-version in the current working directory. cd into that.
Depending on your system configuration, you also need to install some build tools, most importantly make, the gcc compiler and the MySQL development system (if you intend to use MySQL - the package is often named “mysql-dev”). On many systems, these things should already be present. If you don’t know exactly, simply skip this step for now and see if nice error messages pop up during the compile process. If they do, you can still install the missing build environment tools. So this is nothing that you need to look at very carefully.
The rsyslog project maintains multiple rsyslog docker development
environment images. These
images have been configured specifically for use with rsyslog and are
recommended over your own build environment. Rsyslog docker development
images are named with the
rsyslog_dev_ prefix, followed by the
If you plan to copy the binary for use outside of the container you need to make sure to use an image of the same distro/version when building rsyslog.
At a minimum, the following development tools must be present on the system:
- C compiler (usually gcc)
- rst2man (part of Python docutils) if you want to generate the man files
- Bison and Flex (preferably, otherwise yacc and lex)
- zlib development package (usually libz-dev)
- json-c (usually named libjson0-dev or similar)
- libuuid (usually uuid-dev, if not present use –disable-uuid)
- libgcrypt (usually libgcrypt-dev)
Also, development versions of the following supporting libraries that the rsyslog project provides are necessary:
- liblogging (only stdlog component is hard requirement)
In contrast to the other dependencies, recent versions of rsyslog may require recent versions of these libraries as well, so there is a chance that they must be built from source, too.
Depending on which plugins are enabled, additional dependencies exist. These are reported during the ./configure run.
Important: you need the development version of the packages in question. That is the version which is used by developers to build software that uses the respective package. Usually, they are separate from the regular user package. So if you just install the regular package but not the development one, ./configure will fail.
As a concrete example, you may want to build ommysql. It obviously requires a package like mysql-client, but that is just the regular package and not sufficient to build rsyslog successfully. To do so, you need to also install something named like mysql-client-dev.
Usually, the regular package is automatically installed, when you select the development package, but not vice versa. The exact behaviour and names depend on the distribution you use. It is quite common to name development packages something along the line of pkgname-dev or pkgname-devel where pkgname is the regular package name (like mysql-client in the above example).
Step 2 - Run ./configure¶
Run ./configure to adopt rsyslog to your environment. While doing so, you can also enable options. Configure will display selected options when it is finished. For example, to enable MySQL support, run:
Please note that MySQL support by default is NOT disabled.
To learn which ./configure options are available and what their default values are, use
Step 3 - Compile¶
That is easy. Just type “make” and let the compiler work. On any recent system, that should be a very quick task, on many systems just a matter of a few seconds. If an error message comes up, most probably a part of your build environment is not installed. Check with step 1 in those cases.
Step 4 - Install¶
Again, that is quite easy. All it takes is a “sudo make install”. That will copy the rsyslogd and the man pages to the relevant directories.
Step 5 - Configure rsyslogd¶
In this step, you tell rsyslogd what to do with received messages. If you are upgrading from stock syslogd, /etc/syslog.conf is probably a good starting point. Rsyslogd understands stock syslogd syntax, so you can simply copy over /etc/syslog.conf to /etc/rsyslog.conf. Note since version 3 rsyslog requires to load plug-in modules to perform useful work.
To load the most common plug-ins, add the following to the top of rsyslog.conf:
$ModLoad immark # provides --MARK-- message capability $ModLoad imudp # provides UDP syslog reception $ModLoad imtcp # provides TCP syslog reception $ModLoad imuxsock # provides support for local system logging $ModLoad imklog # provides kernel logging support
Change rsyslog.conf for any further enhancements you would like to see. For example, you can add database writing as outlined in the paper Writing syslog messages to MySQL, PostgreSQL or any other supported Database (remember you need to enable MySQL support during step 2 if you want to do that!).
Step 6 - Disable stock syslogd¶
You can skip this and the following steps if rsyslog was already installed as the stock syslogd on your system (e.g. via a distribution default or package). In this case, you are finished.
If another syslogd is installed, it must be disabled and rsyslog set to become the default. This is because both it and rsyslogd listen to the same sockets, they can NOT be run concurrently. So you need to disable the stock syslogd. To do this, you typically must change your rc.d startup scripts.
For example, under Debian this must be done as follows: The default runlevel is 2. We modify the init scripts for runlevel 2 - in practice, you need to do this for all run levels you will ever use (which probably means all). Under /etc/rc2.d there is a S10sysklogd script (actually a symlink). Change the name to _S10sysklogd (this keeps the symlink in place, but will prevent further execution - effectively disabling it).
Step 7 - Enable rsyslogd Autostart¶
This step is very close to step 3. Now, we want to enable rsyslogd to start automatically. The rsyslog package contains a (currently small) number of startup scripts. They are inside the distro-specific directory (e.g. debian). If there is nothing for your operating system, you can simply copy the stock syslogd startup script and make the minor modifications to run rsyslogd (the samples should be of help if you intend to do this).
In our Debian example, the actual scripts are stored in /etc/init.d. Copy the standard script to that location. Then, you need to add a symlink to it in the respective rc.d directory. In our sample, we modify rc2.d, and can do this via the command “ln -s ../init.d/rsyslogd S10rsyslogd”. Please note that the S10 prefix tells the system to start rsyslogd at the same time stock sysklogd was started.
Important: if you use the database functionality, you should make sure that MySQL starts before rsyslogd. If it starts later, you will receive an error message during each restart (this might be acceptable to you). To do so, either move MySQL’s start order before rsyslogd or rsyslogd’s after MySQL.
Step 8 - Check daily cron scripts¶
Most distributions come pre-configured with some daily scripts for log rotation. As long as you use the same log file names, the log rotation scripts will probably work quite well. There is one caveat, though. The scripts need to tell syslogd that the files have been rotated. To do this, they typically have a part using syslogd’s init script to do that. Obviously, scripts for other default daemons do not know about rsyslogd, so they manipulate the other one. If that happens, in most cases an additional instance of that daemon is started. It also means that rsyslogd is not properly told about the log rotation, which will lead it to continue to write to the now-rotated files.
So you need to fix these scripts. See your distro-specific documentation how they are located.
This concludes the steps necessary to install rsyslog. Of course, it is always a good idea to test everything thoroughly. At a minimalist level, you should do a reboot and after that check if everything has come up correctly. Pay attention not only to running processes, but also check if the log files (or the database) are correctly being populated.
If rsyslogd encounters any serious errors during startup, you should be able to see them at least on the system console. They might not be in log file, as errors might occur before the log file rules are in place. So it is always a good idea to check system console output when things don’t go smooth. In some rare cases, enabling debug logging (-d option) in rsyslogd can be helpful. If all fails, go to www.rsyslog.com and check the forum or mailing list for help with your issue.
Help with configuring/using