source: tags/4.1.0/README

Last change on this file was 1, checked in by katerina, 15 years ago

Initial import

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 seperately. 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.