source: trunk/docs/HOWTO-client+server.html@ 559

Last change on this file since 559 was 553, checked in by katerina, 5 years ago

Fix for ticket #443 (Incompatibility with older gpg versions).

File size: 12.1 KB
Line 
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<title>HOWTO client+server</title>
5<style type="text/css">
6<!--
7
8html { background: #eee; color: #000; }
9
10body { background: #eee; color: #000; margin: 0; padding: 0;}
11
12div.body {
13 background: #fff; color: #000;
14 margin: 0 1em 0 1em; padding: 1em;
15 font-family: serif;
16 font-size: 1em; line-height: 1.2em;
17 border-width: 0 1px 0 1px;
18 border-style: solid;
19 border-color: #aaa;
20}
21
22div.block {
23 background: #b6c5f2; color: #000;
24 margin: 1em; padding: 0 1em 0 1em;
25 border-width: 1px;
26 border-style: solid;
27 border-color: #2d4488;
28}
29
30div.warnblock {
31 background: #b6c5f2; color: #000;
32 margin: 1em; padding: 0 1em 0 1em;
33 border-width: 1px;
34 border-style: solid;
35 border-color: #FF9900;
36}
37
38table {
39 background: #F8F8F8; color: #000;
40 margin: 1em;
41 border-width: 0 0 0 1px;
42 border-style: solid;
43 border-color: #C0C0C0;
44}
45
46td {
47 border-width: 0 1px 1px 0;
48 border-style: solid;
49 border-color: #C0C0C0;
50}
51
52th {
53 background: #F8F8FF;
54 border-width: 1px 1px 2px 0;
55 border-style: solid;
56 border-color: #C0C0C0;
57}
58
59
60/* body text, headings, and rules */
61
62p { margin: 0; text-indent: 0em; margin: 0 0 0.5em 0 }
63
64h1, h2, h3, h4, h5, h6 {
65 color: #206020; background: transparent;
66 font-family: Optima, Arial, Helvetica, sans-serif;
67 font-weight: normal;
68}
69
70h1 { font-size: 1.69em; margin: 1.4em 0 0.4em 0; }
71h2 { font-size: 1.44em; margin: 1.4em 0 0.4em 0; }
72h3 { font-size: 1.21em; margin: 1.4em 0 0.4em 0; }
73h4 { font-size: 1.00em; margin: 1.4em 0 0.4em 0; }
74h5 { font-size: 0.81em; margin: 1.4em 0 0.4em 0; }
75h6 { font-size: 0.64em; margin: 1.4em 0 0.4em 0; }
76
77hr {
78 color: transparent; background: transparent;
79 height: 0px; margin: 0.6em 0;
80 border-width: 1px ;
81 border-style: solid;
82 border-color: #999;
83}
84
85/* bulleted lists and definition lists */
86
87ul { margin: 0 1em 0.6em 2em; padding: 0; }
88li { margin: 0.4em 0 0 0; }
89
90dl { margin: 0.6em 1em 0.6em 2em; }
91dt { color: #285577; }
92
93tt { color: #602020; }
94
95/* links */
96
97a.link {
98 color: #33c; background: transparent;
99 text-decoration: none;
100}
101
102a:hover {
103 color: #000; background: transparent;
104}
105
106body > a {
107 font-family: Optima, Arial, Helvetica, sans-serif;
108 font-size: 0.81em;
109}
110
111h1, h2, h3, h4, h5, h6 {
112 color: #2d5588; background: transparent;
113 font-family: Optima, Arial, Helvetica, sans-serif;
114 font-weight: normal;
115}
116
117 -->
118</style></head>
119
120<body>
121<div class="body">
122<p style="text-align: center; background: #ccc; border: 1px solid #2d5588;"><a
123 style="text-decoration: none;"
124 href="http://www.la-samhna.de/samhain/">samhain file integrity
125 scanner</a>&nbsp;|&nbsp;<a style="text-decoration: none;"
126 href="http://www.la-samhna.de/samhain/s_documentation.html">online
127 documentation</a></p>
128<br><center>
129<h1>Setting up a client/server samhain system</h1>
130</center>
131<br>
132<hr>
133<p>
134This document aims to explain how to set up a client/server
135samhain system, where the client (samhain) runs on one machine to be
136monitored, and sends reports via TCP/IP to a remote server (yule).
137</p>
138<p>
139<b>Please note:</b> the server (yule) does not perform any filesystem and/or
140kernel checks. If you want to perform such checks on the log server host,
141you need to run a samhain client on this host as well.
142</p>
143<p>
144Client and server are
145<b>distict applications</b>, and must be
146built separately. By default, installation names and paths (e.g.
147the configuration file) are
148different. Do not blame us if you abuse './configure' options to
149cause name clashes, if you install both on the same host.
150</p>
151
152<h2>Introduction</h2>
153<p>
154Samhain can be compiled for remote logging to a central server via a
155secure (AES-encrypted, signed, and authenticated) TCP/IP connection.
156</p><p>
157In addition, both the client configuration file and the file signature
158database can be stored on the server. The client will then pull them from
159the server upon startup.
160</p><p>
161This requires three basic steps:
162</p>
163<ol>
164<li>
165compile and install server and client,
166</li>
167<li>
168establish trust between client and server, and
169</li>
170<li>
171enable remote logging in the client's configuration file.
172</li>
173</ol>
174
175
176<h2>Compiling</h2>
177
178<h3>The server - yule</h3>
179
180<p>
181<b>Note: </b> the server can be started with root privileges (e.g. to use
182a privileged port &lt; 1024), but it will always
183drop root privileges irrevocably
184before accepting any connections, and run as a non-root user. This user
185can be specified explicitely with the <i>configure</i>
186option <tt>--enable-identity=USER</tt>. The default is
187the first existing user
188out of the list <i>yule, daemon, nobody</i>.
189</p>
190
191<pre>
192
193bash$ ./configure --enable-network=server
194bash$ make
195bash$ make install
196
197</pre>
198
199<h3>The client - samhain</h3>
200
201
202<ul>
203<li>
204 <p>
205 If you just want remote logging:
206 </p><p>
207 <tt>&nbsp; &nbsp;./configure --enable-network=client
208 --with-logserver=server.example.com</tt>
209 </p>
210</li>
211<li>
212 <p>
213 If you want configuration and database files on the server:
214 </p><p>
215 <tt>&nbsp; &nbsp;./configure --enable-network=client
216 --with-logserver=server.example.com \<br />
217 &nbsp; &nbsp; &nbsp; &nbsp; --with-config-file=REQ_FROM_SERVER/etc/samhainrc \<br />
218 &nbsp; &nbsp; &nbsp; &nbsp; --with-data-file=REQ_FROM_SERVER/var/lib/samhain/samhain_file</tt>
219 </p>
220</li>
221</ul>
222<p>
223The path after the keyword <tt>REQ_FROM_SERVER</tt> has the following meaning:
224<ul>
225<li>for the configuration file:
226 <ul>
227 <li> if <i>initializing</i>, and the connection to the server
228 fails, samhain will fall back on the local file (if given);
229 </li>
230 <li> if in <i>check mode</i>, it is <i>ignored</i>. Samhain will
231 abort if the connection to the server fails.
232 </li>
233 </ul>
234 Thus, the local path allows you to initialize the database from a local
235 configuration file before the client is known to the server.
236</li>
237<li>for the database file:
238 <ul>
239 <li> if <i>initializing</i>, the database is written to the local file;
240 </li>
241 <li> if in <i>check mode</i>, the local path is <i>ignored</i>. Samhain will
242 abort if the connection to the server fails.
243 </li>
244 </ul>
245 Thus, <i>init</i> (or <i>update</i>) always requires a local file that
246 must be uploaded to the server thereafter. <b>Note</b> that if you
247 use the <b>Beltane</b> web-based frontend, database updates can be performed
248 on the server without ever running an <i>update</i> on the client.
249</li>
250</ul>
251
252<h2>Establishing trust between client and server</h2>
253
254<p>
255By default, samhain uses the SRP (Secure Remote Password) protocol,
256with a password that is <i>embedded in the client binary</i>, and a
257corresponding verifier that is in the <i>server configuration file</i>.
258</p>
259
260<h3>Embedding the password in the client, and register it with the server</h3>
261
262<p>
263To embed the password in the binary, there is a dummy password compiled
264in as placeholder, and a utility <i>samhain_setpwd</i> is provided that
265</p>
266
267<ol>
268<li>
269 takes a password as input,
270</li>
271<li>
272 searches the original binary for the
273 correct place (i.e. the placeholder), and
274</li>
275<li>
276 writes a copy of the original binary, with the placeholder replaced
277 by the password. The original is left untouched. The copy cannot
278 be changed to another password anymore.
279</li>
280</ol>
281
282
283<p>
284For convenience, the server has functions to
285</p>
286
287<ul>
288<li>
289<p>
290generate a random password in the correct format:
291</p><p>
292<tt>&nbsp; &nbsp;sh$ yule -G</tt>
293</p>
294</li>
295<li>
296<p>
297and generate a corresponding entry for the
298server configuration file:
299</p><p>
300 <tt>&nbsp; &nbsp;sh$ yule -P PASSWORD</tt>.
301<p>
302</li>
303<li>
304The generated entry has a string <tt>'HOSTNAME'</tt> that you should
305replace with the fully qualified name of the client. This entry must
306then be placed in the <tt>[Clients]</tt> section of the yule configuration
307file (e.g. <tt>/etc/yulerc</tt>).
308</li>
309<li>
310Finally, you need to tell yule to reload the configuration (send SIGHUP,
311or use <tt>/etc/init.d/yule reload</tt>).
312</li>
313</ul>
314
315
316<h3>Example</h3>
317
318<pre style="background-color:#DDDDDD; color:#000000">
319
320rainer$ ./samhain_setpwd
321
322Usage: samhain_setpwd &lt;filename&gt; &lt;suffix&gt; &lt;new_password&gt;
323
324 This program is a utility that will:
325 - search in the binary executable &lt;filename&gt; for samhain's
326 compiled-in default password,
327 - change it to &lt;new_password&gt;,
328 - and output the modified binary to &lt;filename&gt;.&lt;suffix&gt;
329
330 To allow for non-printable chars, &lt;new_password&gt; must be
331 a 16-digit hexadecimal number (only 0-9,A-F allowed in input),
332 thus corresponding to an 8-byte password.
333
334 Example: 'samhain_setpwd samhain new 4142434445464748'
335 takes the file 'samhain', sets the password to 'ABCDEFGH'
336 ('A' = 41 hex, 'B' = 42 hex, ...) and outputs the result
337 to 'samhain.new'.
338
339rainer$ yule -G
3405B5CDF18CE8D66A3
341
342rainer$ ./samhain_setpwd samhain new 5B5CDF18CE8D66A3
343INFO old password found
344INFO replaced: f7c312aaaa12c3f7 by: 5b5cdf18ce8d66a3
345INFO finished
346
347rainer$ scp ./samhain.new root@client.example.com:/usr/local/sbin/samhain
348samhain 100% |********************************| 592 KB 00:00
349
350rainer$ yule -P 5B5CDF18CE8D66A3
351Client=HOSTNAME@8A542F99C3514499@744C3A3EE8323470D9DAD42E2485BD0B138F6B4116E964\
352A9991A0B0D221E1AADE5800968804B99B494C39E7B9DD5710D18F1E6703D1DB6D6393295E05DF6A\
3536AA8D10BB4A21D7D9DC4901D444500D4EA358C1B44A3E3D44ACEC645F938F790A11AB0D03586143\
354977E2BCE3A2D689445AC89134B409E68F34B0DE8BD8242ADD7C0
355
356rainer$ yule -P 5B5CDF18CE8D66A3 | sed s%HOSTNAME%client.example.com% &gt;&gt; /etc/yulerc
357
358rainer$ tail -2 /etc/yulerc
359[Clients]
360Client=client.example.com@8A542F99C3514499@744C3A3EE8323470D9DAD42E2485BD0B138F
3616B4116E964A9991A0B0D221E1AADE5800968804B99B494C39E7B9DD5710D18F1E6703D1DB6D6393
362295E05DF6A6AA8D10BB4A21D7D9DC4901D444500D4EA358C1B44A3E3D44ACEC645F938F790A11AB
3630D03586143977E2BCE3A2D689445AC89134B409E68F34B0DE8BD8242ADD7C0
364
365rainer$ /etc/init.d/yule reload
366
367</pre>
368
369<p>
370<b>Note 1:</b> the verifier <tt>Client=client.example.com@.....</tt> must be
371in the <b>[Clients]</b> section of the server configuration file. It is
372convenient if this is the last section in the config file, because then
373you can just concatenate the output of <tt>yule -P PASSWORD</tt> to the
374configuration file. This allows for better automatisation with a simple
375script.
376</p>
377<p>
378<b>Note 2:</b> samhain comes with a <b>deploy system</b> that handles
379the deployment of clients, including password embedding and server
380configuration, in a semi-automatic way.
381This deploy system is tested and used in a production system
382of more than 50 machines, and described in detail in Chapt. 10 of the MANUAL.
383</p>
384
385<h2>Enabling remote logging</h2>
386<p>
387Samhain has multiple independent logging facilities (such as a local logfile,
388syslog, e-mail, TCP/IP, etc.) that can be used
389in parallel. You therefore have to specify in the client's configuration
390file, <b>which logging facility</b> you want to use.
391</p>
392<p>
393Selecting logging facilities is done by setting appropriate <b>thresholds</b>
394in the <b>[Log]</b> section of the configuration file: each
395message with a <b>priority</b> exceeding
396the threshold will be logged via the respective facility. Setting
397the threshold to <i>none</i> will disable a facility. For details,
398refer to Chapt. 4 in the MANUAL.
399</p>
400<h3>Example</h3>
401<p>
402To enable remote logging to the server for all messages of
403priority <i>error</i> or higher, use the following directive in the
404client configuration file:
405</p>
406<pre style="background-color:#DDDDDD; color:#000000">
407
408[Log]
409ExportSeverity=err
410
411</pre>
412
413
414<h2>Databases and config files on the server</h2>
415
416<p>
417The client does <i>not</i> tell the server the path to the requested
418file - it just requests a config or a database file. It's entirely the
419responsibility of the server to locate the correct file and send it.
420</p>
421<p>
422The server has a <i>data directory</i>, which by default would be
423<tt>/var/lib/yule</tt>, but depends on your compile options.
424</p>
425<p>
426Config files and baseline databases for clients must be located
427in this directory, and they must be named as follows:
428</p>
429<p>
430Configuration files: <tt>rc.</tt><i>client.mydomain.tld</i> or
431simply <tt>rc</tt>
432(this can be used as a catchall file).
433</p>
434<p>
435Database files: <tt>file.</tt><i>client.mydomain.tld</i> or
436simply <tt>file</tt>
437(this can be used as a catchall file).
438</p>
439</div>
440</body>
441</html>
Note: See TracBrowser for help on using the repository browser.