mirror of
https://github.com/rsyslog/rsyslog.git
synced 2025-12-19 20:50:42 +01:00
181 lines
11 KiB
HTML
181 lines
11 KiB
HTML
<html><head>
|
|
<title>A guide on HOWTO install rsyslog</title>
|
|
<meta name="KEYWORDS" content="syslog encryption, rsyslog, stunnel, secure syslog, tcp, reliable, howto, ssl">
|
|
</head>
|
|
<body>
|
|
<h1>HOWTO install rsyslog</h1>
|
|
<P><small><i>Written by
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer
|
|
Gerhards</a></i></small></P>
|
|
<h2>Abstract</h2>
|
|
<p><i><b>In this paper, I describe how to install
|
|
<a href="http://www.rsyslog.com/">rsyslog</a>.</b> 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
|
|
<a href="manual.html">manual set</a>.</i></p>
|
|
<h2>How to make your life easier...</h2>
|
|
<p>Some folks have thankfully created <a href="rsyslog_packages.html">
|
|
RPMs/packages for rsyslog</a>. 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.</p>
|
|
<h2>Steps To Do</h2>
|
|
<p>Rsyslog does currently only have very limited availability as a package (if
|
|
you volunteer to create one, <a href="mailto:rgerhards@adiscon.com">drop me a
|
|
line</a>). Thus, this guide focuses on installing from the source, which
|
|
thankfully is <b>quite easy</b>.</p>
|
|
<h3>Step 1 - Download Software</h3>
|
|
<p>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 <a href="build_from_repo.html">build rsyslog from repository</a>
|
|
instead.
|
|
<p>Load the most recent build
|
|
from <a href="http://www.rsyslog.com/downloads">http://www.rsyslog.com/downloads</a>.
|
|
Extract the software with "tar xzf -nameOfDownloadSet-". This will create a new
|
|
subdirectory rsyslog-version in the current working directory. CD into that. </p>
|
|
<p>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.</p>
|
|
<h3>Step 2 - Run ./configure</h3>
|
|
<p>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</p>
|
|
<p>./configure --enable-mysql</p>
|
|
<p>Please note that MySQL support by default is NOT disabled.</p>
|
|
<h3>Step 3 - Compile</h3>
|
|
<p>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. </p>
|
|
<h3>Step 4 - Install</h3>
|
|
<p>Again, that is quite easy. All it takes is a "make install". That will copy
|
|
the rsyslogd and the man pages to the relevant directories.</p>
|
|
<h3>Step 5 - Configure rsyslogd</h3>
|
|
<p>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 (more about
|
|
<a href="v3compatibility.html">compatibilty notes v3</a>). To load the most common plug-ins,
|
|
add the following to the top of rsyslog.conf:</p>
|
|
<p>
|
|
$ModLoad immark # provides --MARK-- message capability <br />
|
|
$ModLoad imudp # provides UDP syslog reception <br />
|
|
$ModLoad imtcp # provides TCP syslog reception and GSS-API (if compiled to support it) <br />
|
|
$ModLoad imuxsock # provides support for local system logging (e.g. via logger command) <br />
|
|
$ModLoad imklog # provides kernel logging support (previously done by rklogd) <br />
|
|
</p>
|
|
Change rsyslog.conf for any further
|
|
enhancements you would like to see. For example, you can add database writing as
|
|
outlined in the paper "<a href="rsyslog_mysql.html">Writing syslog Data to MySQL</a>"
|
|
(remember you need to enable MySQL support during step 2 if you want to do
|
|
that!).</p>
|
|
<h3>Step 6 - Disable stock syslogd</h3>
|
|
<p>In almost all cases, there already is stock syslogd installed. 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.</p>
|
|
<p>For example, under <a href="http://www.debian.org/">Debian</a> 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).</p>
|
|
<h3>Step 7 - Enable rsyslogd Autostart</h3>
|
|
<p>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).</p>
|
|
<p>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.</p>
|
|
<p><b>Important:</b> 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.</p>
|
|
<h3>Step 8 - Check daily cron scripts</h3>
|
|
<p>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, the default scripts do
|
|
not know about rsyslogd, so they manipulate syslogd. If that happens, in most
|
|
cases an additional instance of stock syslogd is started (in almost all cases,
|
|
this was not functional, but it is at least distracting). 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.</p>
|
|
<p>So you need to fix these scripts. See your distro-specific documentation how
|
|
they are located. Under most Linuxes, the primary script to modify is /etc/cron.daily/sysklogd.
|
|
Watch for a comment "Restart syslogd" (usually at the very end of the file). The
|
|
restart command must be changed to use rsyslogd's rc script.</p>
|
|
<p>Also, if you use klogd together with rsyslogd (under most Linuxes you will do
|
|
that), you need to make sure that klogd is restarted after rsyslogd is restarted.
|
|
So it might be a good idea to put a klogd reload-or-restart command right after
|
|
the rsyslogd command in your daily script. This can save you lots of troubles.</p>
|
|
<h3>Done</h3>
|
|
<p>This concludes the steps necessary to install rsyslogd. 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.</p>
|
|
<p>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 <a href="http://www.rsyslog.com">www.rsyslog.com</a> and check
|
|
the forum or mailing list for help with your issue.</p>
|
|
<h2>Housekeeping stuff</h2>
|
|
<p>This section and its subsections contain all these nice things that you
|
|
usually need to read only if you are really curios ;)</p>
|
|
<h3>Feedback requested</h3>
|
|
<P>I would appreciate feedback on this tutorial. It is still in its infancy, so additional ideas,
|
|
comments or bug sighting reports are very welcome. Please
|
|
<a href="mailto:rgerhards@adiscon.com">let me know</a> about them.</P>
|
|
<h3>Revision History</h3>
|
|
<ul>
|
|
<li>2005-08-08 *
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> * Initial
|
|
version created</li>
|
|
<li>2005-08-09 *
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
|
|
* updated to include distro-specific directories, which are now mandatory</li>
|
|
<li>2005-09-06 *
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
|
|
* added information on log rotation scripts</li>
|
|
<li>2007-07-13 *
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
|
|
* updated to new autotools-based build system</li>
|
|
<li>2008-10-01 *
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a>
|
|
* added info on building from source repository</li>
|
|
</ul>
|
|
<h3>Copyright</h3>
|
|
<p>Copyright © 2005-2008
|
|
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer Gerhards</a> and
|
|
<a href="http://www.adiscon.com/en/">Adiscon</a>.</p>
|
|
<p> Permission is granted to copy, distribute and/or modify this document
|
|
under the terms of the GNU Free Documentation License, Version 1.2
|
|
or any later version published by the Free Software Foundation;
|
|
with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
|
|
Texts. A copy of the license can be viewed at
|
|
<a href="http://www.gnu.org/copyleft/fdl.html">
|
|
http://www.gnu.org/copyleft/fdl.html</a>.</p>
|
|
<p>[<a href="manual.html">manual index</a>]
|
|
[<a href="http://www.rsyslog.com/">rsyslog site</a>]</p>
|
|
<p><font size="2">This documentation is part of the
|
|
<a href="http://www.rsyslog.com/">rsyslog</a> project.<br>
|
|
Copyright © 2008 by <a href="http://www.gerhards.net/rainer">Rainer Gerhards</a> and
|
|
<a href="http://www.adiscon.com/">Adiscon</a>. Released under the GNU GPL
|
|
version 1.2 or higher.</font></p>
|
|
</body>
|
|
</html>
|