diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2005-08-08 16:12:14 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2005-08-08 16:12:14 +0000 |
| commit | 6d8ebae225ad55a175b2266f531e0ddba50da706 (patch) | |
| tree | e145afaa36e2aa838ebd3959b17b51ca7b057914 | |
| parent | 563f86b26914a72ef68be1a1f5569119af681573 (diff) | |
| download | rsyslog-6d8ebae225ad55a175b2266f531e0ddba50da706.tar.gz rsyslog-6d8ebae225ad55a175b2266f531e0ddba50da706.tar.xz rsyslog-6d8ebae225ad55a175b2266f531e0ddba50da706.zip | |
added first revision of install document
| -rw-r--r-- | doc/install.html | 136 | ||||
| -rw-r--r-- | doc/manual.html | 1 |
2 files changed, 137 insertions, 0 deletions
diff --git a/doc/install.html b/doc/install.html new file mode 100644 index 00000000..4b0e5a21 --- /dev/null +++ b/doc/install.html @@ -0,0 +1,136 @@ +<html><head>
+<title>SSL Encrypting syslog with stunnel</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> (2005-08-08)</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>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 focusses 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. Load the most recent build
+from <a href="http://www.rsyslog.com/downloads">http://www.rsyslog.com/downloads</a>.</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). 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 - Check Makefile</h3>
+<p>The Makefile that comes with rsyslog contains all common options, instead of
+support for MySQL. By default, it is compiled without it, because most folks do
+not need it. If you need MySQL, you need to activate it. It's straightforward:</p>
+<ul>
+ <li>load Makefile in your preferred text editor</li>
+ <li>search for the "FEATURE_DB" definition close to the top of the file:
+ <blockquote><code># Enable database support (off by default, must be turned<br>
+ # on when support for MySQL is desired).<br>
+ <b>FEATURE_DB=<font color="#FF0000">0</font></b></code></blockquote>
+ </li>
+ <li>change FEATURE_DB to 1, that enables MySQL support. The line should now
+ look as follows:<blockquote>
+ <p><code># Enable database support (off by default, must be turned<br>
+ # on when support for MySQL is desired).<br>
+ <b>FEATURE_DB=<font color="#FF0000">1</font></b></code></p>
+ </blockquote>
+ </li>
+ <li>write the updated Makefile to disk</li>
+</ul>
+<p><b>Important:</b> If you modify the Makefile more than once, be sure to call
+"make clean" before going further.</p>
+<p>Now you are ready for the next step, the compilation.</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 vew
+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 relavant 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. Then, edit rsyslog.conf for any
+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>".</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 mus be
+done as follows: The default runlevel is 2. We modify the init scripts for
+runlevel 2 - in parctice, 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>Done</h3>
+<p>This concludes the steps necesary to install rsyslogd. Of course, it is
+always a good idea to test everything thouroughly. 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>
+</ul>
+<h3>Copyright</h3>
+<p>Copyright (c) 2005
+<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>
+
+</body>
+</html>
\ No newline at end of file diff --git a/doc/manual.html b/doc/manual.html index dd263cf7..29c72e4f 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -22,6 +22,7 @@ version information and ports.</p> <li><a href="bugs.html">rsyslog bug list</a></ul>
<p><b>We have some in-depth papers on</b></p>
<ul>
+ <li><a href="install.html">installing rsyslog</a></li>
<li><a href="rsyslog_stunnel.html">ssl-encrypting syslog with stunnel</a></li>
<li><a href="rsyslog_mysql.html">writing syslog messages to MySQL</a></li>
<li><a href="rsyslog_php_syslog_ng.html">using php-syslog-ng with rsyslog</a></li>
|