diff options
Diffstat (limited to 'source/installation/install_from_source.rst')
| -rw-r--r-- | source/installation/install_from_source.rst | 238 |
1 files changed, 238 insertions, 0 deletions
diff --git a/source/installation/install_from_source.rst b/source/installation/install_from_source.rst new file mode 100644 index 0000000..282e3b2 --- /dev/null +++ b/source/installation/install_from_source.rst @@ -0,0 +1,238 @@ +Installing rsyslog from Source +============================== + +*Written by* `Rainer Gerhards <https://rainer.gerhards.net>`_ + +**In this paper, I describe how to install** +`rsyslog <http://www.rsyslog.com/>`_. 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 +:doc:`manual set <../index>`. + +How to make your life easier... +------------------------------- + +In addition to building from source, you can also install |PRODUCT| +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 :doc:`packages` 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 :doc:`build_from_repo` instead. + +Load the most recent build from +`http://www.rsyslog.com/downloads <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. + + +Build Requirements +~~~~~~~~~~~~~~~~~~ + +.. include:: /includes/container_dev_env.inc.rst + +At a minimum, the following development tools must be present on the +system: + +* C compiler (usually gcc) +* make +* libtool +* 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) +* libfastjson +* libestr + +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:: + + ./configure --enable-mysql + +Please note that MySQL support by default is NOT disabled. + +To learn which ./configure options are available and what their +default values are, use + +``./configure --help`` + + +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. + +.. seealso:: + + :doc:`/compatibility/v3compatibility` + +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 +:doc:`/tutorials/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 <http://www.debian.org/>`_ 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. + +Done +~~~~ + +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 <http://www.rsyslog.com>`_ and check the forum or +mailing list for help with your issue. |