summaryrefslogtreecommitdiffstats
path: root/doc/install.html
blob: 3fa534033f4d505808d7e429044b1d38e52331c6 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
<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>. 
Extract the software with &quot;tar xzf -nameOfDownloadSet-&quot;. 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 &quot;mysql-dev&quot;). 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 &quot;linux&quot;, 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 &quot;FEATURE_DB&quot; 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 
&quot;make clean&quot; 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 &quot;make&quot; 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 &quot;make install&quot;. 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 &quot;<a href="rsyslog_mysql.html">Writing syslog Data to MySQL</a>&quot;.</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 &quot;ln -s ../init.d/rsyslogd S10rsyslogd&quot;. 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 &quot;Restart syslogd&quot; (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>