source: trunk/README@ 558

Last change on this file since 558 was 546, checked in by katerina, 6 years ago

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