source: trunk/README

Last change on this file was 546, checked in by katerina, 3 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.