diff options
| author | Rainer Gerhards <rgerhards@adiscon.com> | 2007-07-13 13:03:19 +0000 |
|---|---|---|
| committer | Rainer Gerhards <rgerhards@adiscon.com> | 2007-07-13 13:03:19 +0000 |
| commit | 421cbcfe164e609e8bc58e23bf6bd2f9c32eb8f6 (patch) | |
| tree | b7d6ea944daa52e664195242400d17399745356c | |
| parent | 949ef40a44faedc0f4c62051c1b478719d1a4558 (diff) | |
| download | rsyslog-421cbcfe164e609e8bc58e23bf6bd2f9c32eb8f6.tar.gz rsyslog-421cbcfe164e609e8bc58e23bf6bd2f9c32eb8f6.tar.xz rsyslog-421cbcfe164e609e8bc58e23bf6bd2f9c32eb8f6.zip | |
updated doc to reflect new build system
| -rw-r--r-- | doc/install.html | 335 | ||||
| -rw-r--r-- | doc/manual.html | 8 |
2 files changed, 159 insertions, 184 deletions
diff --git a/doc/install.html b/doc/install.html index ac19f8bb..fb9e8933 100644 --- a/doc/install.html +++ b/doc/install.html @@ -1,181 +1,156 @@ -<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>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 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>.
-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 - Change into correct Subdirectory</h3>
-<p>Rsyslog contains subdirectories for all platforms it has been compiled on so
-far. If your platform is missing, that does not mean it won't run - it simply
-means either nobody tried before or did not let us know. Please note that there
-is a generic subdirectory "linux", which should cover allmost all linux variants.
-If you run Linux but your distro has no specific directory, use the linux
-directory instead. For example, at the time of this writing there wasn't even a
-redhat directory, because it would have been no different from the linux
-directory. So the absence of a distro-specific directory does not (necessarily)
-mean rsyslog has never been compiled on that distro.</p>
-<p><b>CD into the distribution-specific directory that best matches your
-platform.</b> All further steps assume that you are inside this directory and
-NOT the rsyslog home directory.</p>
-<h3>Step 3 - 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 4 - 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 5 - 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 6 - 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 7 - 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 8 - 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 9 - 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 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>
- <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>
-</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><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></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. 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 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>" +(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 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>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 neccesary 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> + <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> +</ul> +<h3>Copyright</h3> +<p>Copyright (c) 2005, 2007 +<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 b4735d57..1abbeb1b 100644 --- a/doc/manual.html +++ b/doc/manual.html @@ -31,13 +31,13 @@ helps. Learn <a href="how2help.html">how to help the rsyslog project</a>.</p> </ul>
<p>Also, there is an article from Dennis Olvany on
<a href="rsyslog084-freebsd5.4.txt">Syslog-to-SQL with rsyslog-0.8.4 on FreeBSD 5.4</a>
-(which unfortunately is a bit outdated now). Thanks to Ozgur Karatas, we also
have a
<a href="http://www.rsyslog.com/index.php?module=Static_Docs&func=view&f=/turkish-install-1.0.1.pdf">turkish install howto</a> (online-only, based on the 1.0.1 release).</p>
+(which unfortunately is a bit outdated now).</p>
<p>Our <a href="history.html">rsyslog history</a> page is for you if you would like to learn a little more
on why there is an rsyslog at all.</p>
-<p>Documentation is added continously. Please note that the documentation here
+<p>Documentation is added continuously. Please note that the documentation here
matches only the current version of rsyslog. If you use an older version, be sure
to use the doc that came with it.</p>
-<p><b>You can also browse the following online ressources:</b></p>
+<p><b>You can also browse the following online resources:</b></p>
<ul>
<li><a href="http://www.rsyslog.com/module-Static_Docs-view-f-manual.html.phtml">rsyslog online documentation</a></li>
<li><a href="http://www.rsyslog.com/Topic3.phtml">rsyslog FAQ</a></li>
@@ -48,6 +48,6 @@ to use the doc that came with it.</p> <p>And don't forget about the <a href="http://lists.adiscon.net/mailman/listinfo/rsyslog">rsyslog mailing list</a>.
If you are interested in the "backstage", you may find
<a href="http://www.adiscon.com/en/people/rainer-gerhards.php">Rainer</a>'s
-<a href="http://rgerhards.blogspot.com/">syslog blog</a> an interesting read.</p>
+<a href="http://rgerhards.blogspot.com/">blog</a> an interesting read (filter on
syslog and rsyslog tags).</p>
</body>
</html>
|