source: trunk/docs/README@ 555

Last change on this file since 555 was 553, checked in by katerina, 6 years ago

Fix for ticket #443 (Incompatibility with older gpg versions).
File size: 15.3 KB
Line 
1
2CONTENT OF THIS DOCUMENT
3------------------------
4
5 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
6 +++ +++
7 +++ NOTE: The distribution package contains a much more detailed MANUAL +++
8 +++ +++
9 +++ ---- See the docs/ subdirectory ---- +++
10 +++ +++
11 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
12
13 - INSTALL basic install procedure
14
15 - PGP SIGNATURES signing database and config file
16
17 - CLIENT/SERVER how to install and use with client/server mode
18 for distributed host monitoring
19
20 - STEALTH how to install and use with stealth mode enabled
21
22 - USAGE some usage examples
23
24 - CAVEATS what the name says
25
26 - START AT BOOT TIME how to start the daemon during the boot sequence
27
28 - CONFIGURE OPTIONS overview of supported options, and defaults
29
30 - TESTING test suite (also useful to see EXAMPLES)
31
32
33
34
35INSTALL:
36-------
37
38 Unpack the source with:
39
40 gunzip -c samhain-current.tar.gz | tar xvf -
41
42 This will drop two files in your current directory:
43
44 samhain-{version}.tar.gz
45 samhain-{version}.tar.gz.asc
46
47 To check authenticity and integrity of the source code, verify
48 the PGP signature on samhain-{version}.tar.gz
49 (public PGP key for Rainer Wichmann at http://wwwkeys.pgp.net/):
50
51 gpg --verify samhain-{version}.tar.gz.asc samhain-{version}.tar.gz
52
53 Then unpack samhain-{version}.tar.gz:
54
55 gunzip -c samhain-{version}.tar.gz | tar xvf -
56 cd samhain-{version}
57
58 If you have an incarnation of 'dialog' (xdialog, dialog, lxdialog)
59 installed, you can use the GUI install tool:
60
61 ./Install.sh
62
63 Otherwise use the commands:
64
65 ./configure [options]
66 make
67 su root
68 make install
69
70 At least the following executable will be built:
71
72 +++ samhain +++ the monitoring agent, without any
73 client/server support (i.e. local use only)
74
75 Additional executables will be built if you compile in client/server
76 and/or stealth mode (see below).
77
78 The 'make install' target will strip the executable(s), i.e.
79 discard symbols.
80
81 PATHS:
82 -----
83 For configuring the install paths/locations,
84 see the MANUAL.
85
86
87 WARNING:
88 -------
89 Some versions of gcc have a bug that generates incorrect
90 code if strength reducing is enabled.
91 If you modify the compiler flags, always use the -fno-strength-reduce
92 option with gcc, unless you are sure that your compiler does not
93 suffer from the problem (see README.gcc_bug).
94 Also, some gcc versions generate incorrect code unless the
95 -fno-omit-frame-pointer option is used.
96 The -fno-strength-reduce and the -fno-omit-frame-pointer options are
97 enabled by default by the 'configure' script.
98
99PGP SIGNATURES:
100--------------
101 By default, samhain will report on the checksums of the database
102 and configuration files on startup.
103
104 You can always (clear)sign the database (once initialized)
105 with GnuPG, as well as the configuration file
106 (recommended: gpg -a --clearsign --not-dash-escaped FILE).
107
108 However, to have samhain check these signatures, rather than ignoring
109 them, you need GnuPG and you must compile samhain with the option
110
111 ./configure --with-gpg=PATH
112
113 where PATH is the path to the gpg/pgp binary.
114
115 Samhain will invoke gpg only after checking that
116 only trusted users (by default: root and the effective user)
117 have write access to any element in the path.
118
119 The public key for verification must be in the keyring of the
120 effective user (usually root)
121
122 For more security, it is possible to compile in the checksum
123 of the GnuPG executable, and/or the key fingerprint. See
124 the MANUAL for more details.
125
126 The public key will be searched in the gpg home directory
127 (~/.gnupg/) of the effective user (usually root).
128 The key identification and fingerprint will be reported.
129
130CLIENT/SERVER:
131-------------
132
133 samhain supports logging to a central server via TCP/IP.
134 To enable this option, use the ./configure option
135
136 ./configure --enable-network=client|server [more options]
137
138 NOTE: client and server are __distict__ applications, and must be
139 built separately. By default, installation names and paths are
140 different. Do not blame us if you abuse './configure' options to
141 cause name clashes, if you install both on the same host.
142
143 The following executables are built:
144
145 +++ samhain (client) +++ the monitoring agent,
146 with client code included
147 if --enable-network=client
148
149 +++ yule (server) +++ the log server (no monitoring, just report
150 collecting !!!)
151 if --enable-network=server
152
153 +++ samhain_setpwd +++ a utility program to set the password of
154 a monitoring agent (see man page samhain.8).
155 Use it without options to get help.
156
157
158 To set up a monitoring agent, do the following:
159
160 -- select a (16-digit hexadecimal) password. To generate
161 a random password, you can use:
162
163 ./yule -G
164
165 -- use 'samhain_setpwd samhain <suffix> <password>'
166 to generate an agent 'samhain.suffix' with the selected password
167 (you can rename the agent afterwards, of course)
168
169 -- use 'yule -P password' to compute an entry to register the agent
170
171 -- in the servers's configuration file, insert the computed entry
172 (replace HOSTNAME with the host, on which the agent will run)
173 in the section called [Clients]
174
175 By default, client/server authentication
176 is done with the SRP (Secure Remote Password) protocol.
177
178 It is also possible to store configuration and database files
179 on the server. See the manual for details.
180
181STEALTH:
182-------
183
184 samhain supports a 'stealth' mode of operation, meaning that
185 the program can be run without any obvious trace of its presence
186 on disk. The supplied facilities are more sophisticated than
187 just running the program under a different name,
188 and might thwart efforts using 'standard' Unix commands,
189 but they will not resist a search using dedicated utilities.
190 To enable this mode, use the ./configure option
191
192 ./configure --enable-stealth=XOR_VAL [more options]
193
194 XOR_VAL must be a decimal number in the range 0, 128..255
195 (using 0 will have no effect).
196
197 The runtime executable will contain no printable strings revealing
198 its nature or purpose (strings are xor'ed with XOR_VAL at compile
199 time, and decoded at runtime).
200
201 The configuration file is expected to be
202 a postscript file with _uncompressed_ image data, wherein
203 the configuration data are hidden by steganography.
204 To create a suitable image file from an existing image,
205 you may use e.g. the ImageMagick program 'convert', such as:
206
207 convert +compress ima.jpg ima.ps
208
209 The following additional executable will be built:
210
211 +++ samhain_stealth +++ steganography utility program to hide/extract
212 the configuration file data in/from a
213 postscript file with
214 _uncompressed_ image data.
215 Use it without options to get help.
216
217 Database and log file entries are xor'ed with XOR_VAL to 'mask'
218 printable strings as binary data. No steganography is supported
219 for them, as this would require image files of unreasonable large
220 size.
221 However, if the database/log file is an existing image (say, a .jpg
222 file), the data will be appended to the end of the image data.
223 The image will display normally, and on examination of the file,
224 the add-on data will look like binary (image) data at first sight.
225 The built-in utility to verify and print log file entries
226 will handle this situation transparently.
227
228 To re-name samhain to something unsuspicious, use the configure option
229
230 ./configure --enable-install-name=NAME
231
232 'make install' will then re-name samhain upon installation. Also,
233 database, log file, and pid file will have 'samhain' replaced by
234 NAME.
235
236
237USAGE EXAMPLES:
238--------------
239
240 Review the default configuration file that comes with the
241 source distribution. Read the man page (samhain.8).
242
243 initialize database: samhain -t init
244
245 check files: samhain -t check
246
247 run as daemon: samhain -t check -D
248
249 report to log server: samhain -t check -D -e warn
250
251 start the log server: yule -S
252
253
254CAVEATS:
255-------
256 Permissions:
257 -----------
258 samhain needs root permissions to check some system files.
259 The log server does not require root permissions, unless
260 you use a privileged port (port number below 1024).
261 If you use --enable-udp to listen on the syslog socket, you need
262 to start the log server with root permissions (it will drop them
263 after binding to the port).
264
265 Trust:
266 -----
267 samhain checks the path to critical files (database, configuration)
268 for write access by untrusted users. By default, only root and
269 the effective user are trusted. More UIDs can be added as a
270 compile options (some systems habe 'bin' as owner of the root
271 directory).
272
273 Integrity:
274 ---------
275 On startup, samhain will report on signatures or checksums of
276 database and configuration files. You better check these reports.
277
278 Both startup and exit will be reported. If you are using samhain
279 as daemon and start it at boot time, you may want to check that
280 startup/exit corresponds with scheduled reboots.
281
282 If the path to the samhain binary is defined in the configuration
283 file, samhain will checksum the binary at startup and compare
284 at program termination. This will minimize the time available
285 for an intruder to modify the binary.
286
287 Mail address:
288 ------------
289 For offsite mail, you may have to set a mail relay host
290 in the configuration file.
291
292START AT BOOT TIME:
293------------------
294 the easy way (supported on Linux, FreeBSD, HP-UX, AIX):
295
296 su root
297 make install-boot
298
299
300
301CONFIGURE OPTIONS:
302-----------------
303
304 -------------------
305 -- basic options --
306 -------------------
307
308 --enable-network Compile with client/server support.
309
310 --enable-udp Enable the server to listen on
311 port 514/udp (syslog).
312
313 --enable-srp Use SRP protocol to authenticate to
314 log server.
315
316 --with-gpg=PATH Use GnuPG to verify database/config.
317 The public key of the effective
318 user (in ~/.gnupg/pubring.gpg)
319 will be used.
320
321 --enable-login-watch Watch for login/logout events.
322
323 --enable-stealth=XOR_VAL Enable stealth mode, and set XOR_VAL.
324 XOR_VAL must be decimal in
325 0..32 or 127..255
326 and will be used to 'mask' literal
327 strings as binary data.
328 (0 has no effect).
329
330 --enable-micro-stealth=XOR_VAL
331 As --with-stealth, but without
332 steganographic hidden configuration
333 file.
334
335 --enable-nocl=PW Enable command line parsing ONLY if
336 PW is the first argument on the command
337 line. If PW is "" (empty string),
338 command line parsing is completely
339 disabled.
340
341 --enable-base=BASE Set base for one-time pads. Must be
342 ONE string (no space) made of TWO
343 comma-separated integers in the range
344 -2147483648...2147483647.
345 (The default is compile time.)
346 Binaries compiled with different
347 values cannot verify the audit trail(s)
348 of each other.
349 THIS IS IMPORTANT IF YOU COMPILE
350 MULTIPLE TIMES, E.G. ON DIFFERENT
351 HOSTS.
352
353
354 -------------------
355 -- paths --
356 -------------------
357
358 ${install_name} is "samhain" by default
359 (see --with-install-name=NAME )
360
361 configuration: /etc/${install_name}rc
362 state data: /var/lib/${install_name}
363 log file: /var/log/${install_name}_log
364 lock/pid file: /var/run/${install_name}.pid
365
366 mandir: /usr/local/man
367 bindir: /usr/local/sbin/
368
369
370 --exec-prefix=EPREFIX Set sbindir prefix (default
371 is /usr/local, ie. binaries
372 go to /usr/local/sbin)
373
374 --prefix=PREFIX install directory
375 (default is NONE)
376
377 IF PREFIX = USR; then
378
379 configuration: /etc/${install_name}rc
380 state data: /var/lib/${install_name}
381 log file: /var/log/${install_name}_log
382 lock/pid file: /var/run/${install_name}.pid
383
384 mandir: /usr/share/man
385 bindir: /usr/sbin/
386
387 IF PREFIX = OPT; then
388
389 configuration: /etc/opt/${install_name}rc
390 state data: /var/opt/${install_name}/${install_name}
391 log file: /var/opt/${install_name}/${install_name}_log
392 lock/pid file: /var/opt/${install_name}/${install_name}.pid
393
394 mandir: /opt/${install_name}/man
395 bindir: /opt/${install_name}/bin/
396
397 IF PREFIX = (something else); then
398
399 If EPREFIX is not set, it will be set to PREFIX.
400 configuration: PREFIX/etc/${install_name}rc
401 state data: PREFIX/var/lib/${install_name}
402 log file: PREFIX/var/log/${install_name}_log
403 lock/pid file: PREFIX/var/run/${install_name}.pid
404
405 mandir: PREFIX/share/man
406 bindir: PREFIX/sbin/
407
408
409
410 --with-config-file=FILE Set path of configuration file
411 (default is PREFIX/etc/samhainrc)
412
413 --with-data-file=FILE Set path of data file
414 (PREFIX/var/lib/samhain/samhain_file)
415 --with-html-file=FILE Set path of server status html file
416 (PREFIX/var/lib/samhain/samhain.html)
417
418 --with-log-file=FILE Set path of log file
419 (PREFIX/var/log/samhain_log)
420 --with-pid-file=FILE Set path of lock file
421 (PREFIX/var/run/samhain.pid)
422
423 -------------------
424 -- other --
425 -------------------
426
427
428 --with-checksum=CHECKSUM Compile in TIGER checksum of the
429 gpg/pgp binary.
430 CHECKSUM must be the full
431 line output by samhain or GnuPG when
432 computing the checksum.
433
434 --with-fp=FINGERPRINT Compile in public key fingerprint.
435 FINGERPRINT must be without spaces.
436 Only useful in combination with
437 '--with-gpg'.
438 If used, samhain will check the
439 fingerprint, but still report on the
440 used public key.
441
442 --enable-identity=USER Set user when dropping root privileges
443 (default is the user "nobody").
444 Only needed if there is no user
445 'nobody' on your system
446 (check /etc/passwd)
447
448 --with-port=PORT Set port number for TCP/IP
449 (default is 49777).
450 Only needed if this port is already
451 used by some other application.
452
453 --with-logserver=HOST Set host address for log server
454 (default is NULL).
455 You can set this in the configuration
456 file as well.
457
458 --with-timeserver=HOST Set host address for time server
459 (default is NULL - use own clock).
460 You can set this in the configuration
461 file as well.
462
463 --with-sender=SENDER Set sender for e-mail
464 (default is daemon).
465
466 --enable-xml-log Use XML format for log file.
467
468 --enable-debug Enable extended debugging
469
470 --enable-ptrace Use anti-debugging code.
471
472 --with-trusted=UID Comma-separated list of UID's of
473 users that are always trusted
474 (default is 0 = root).
475 You will need this only if the
476 path to the config file has directories
477 owned neither by 'root' nor by the
478 (effective) user of the program.
479
480
481TESTING:
482-------
483 For testing compilation etc., you may use the test suite:
484
485 ./test/test.sh n [hostname]
486
487 The argument 'n' is the number of the test to run. Some tests require
488 that the (fully qualified) hostname be given as second argument.
489
490 Without options, you will get a short help/usage message, listing
491 each test, its purpose, and the name of the configuration file used.
492 You may want to review the respective configuration file before
493 running a test.
494
495 Also listed are the scripts used for each test. If you have problems
496 getting samhain to run, you may use these scripts as examples.
497
Note: See TracBrowser for help on using the repository browser.