
CONTENT OF THIS DOCUMENT
------------------------

	- INSTALL             basic install procedure

	- PGP SIGNATURES      signing database and config file

	- CLIENT/SERVER       how to install and use with client/server mode
                              for distributed host monitoring

	- STEALTH             how to install and use with stealth mode enabled

	- USAGE               some usage examples 

	- CAVEATS             what the name says 

	- START AT BOOT TIME  how to start the daemon during the boot sequence

	- CONFIGURE OPTIONS   overview of supported options, and defaults

	- TESTING             test suite (also useful to see EXAMPLES)


	NOTE: The distribution package contains a much more detailed manual.


INSTALL:
-------
	To check authenticity and integrity of the source code, first verify
	the PGP signature on the file MANIFEST.asc
	(public PGP key for Rainer Wichmann at http://wwwkeys.pgp.net/),
	then use GNU md5sum or GnuPG 
	to check the MD5 checksums in that file:

		md5sum `ls *` > MANIFEST 
		diff MANIFEST MANIFEST.asc

		or:

		gpg --print-md MD5 `ls *` > MANIFEST_GPG
		diff MANIFEST_GPG MANIFEST_GPG.asc

	The only differences should be the pgp signature in MANIFEST.asc,
	and the checksums for MANIFEST, MANIFEST.asc in MANIFEST.

	CAVEAT: Using '*' instead of '`ls *`' may result in a different 
	sorting order, and thus a quite different result with 'diff'. 
	GNU ls automatically sorts in alphabetic order. If your systems 'ls'
	doesn't, you can sort like:
		
		md5sum `ls * | sort +1` > MANIFEST
 

	AFTER verifying the integrity of the source code, run the commands:

		./configure [options]
		make
		su root
		make install

	At least the following executable will be built:

	  +++ samhain +++ the monitoring agent, without any
                          client/server support (i.e. local use only)

	Additional executables will be built for client/server and/or
	stealth mode (see below).

	The 'make install' target will strip the executable(s), i.e.
	discard symbols.

	WARNING:
	------- 
	Some versions of gcc (including some versions of 2.95.2, 
	i.e. fairly recent) have a bug that generates incorrect 
	code if strength reducing is enabled. 
	If you modify the compiler flags, always use the -fno-strength-reduce 
	option with gcc, unless you are sure that your compiler does not
	suffer from the problem (see README.gcc_bug). 
	The -fno-strength-reduce option is enabled by default 
	by the 'configure' script.

PGP SIGNATURES:
--------------
	By default, samhain will report on the checksums of the database
	and configuration files on startup.

	You can always (clear)sign the database (once initialized) 
        with PGP/GnuPG, as well as the configuration file.

	However, to have samhain check these signatures, rather than ignoring
	them, you need GnuPG/PGP and you must compile samhain with the option

		./configure --with-gpg=PATH

	where PATH is the path to the gpg/pgp binary. If using PGP rather than
	GnuPG, you must use

		./configure --with-pgp=PATH 

	Samhain will invoke gpg/pgp only after checking that 
	only trusted users (by default: root and the effective user) 
	have write access to any element in the path.

	The public key for verification must be in the keyring of the
	effective user (usually root)

	For more security, it is possible to compile in the checksum
	of the GnuPG/PGP executable, and/or the key fingerprint. See
	the manual for more details.

	The public key will be searched in the gpg/pgp home directory 
	(~/.gnupg/ or ~/.pgp/, respectively) of the effective user.
	The key identification and fingerprint will be reported.

CLIENT/SERVER:
-------------

	samhain supports logging to a central server via TCP/IP.
	To enable this option, use the ./configure option

		./configure --enable-network [more options]

	At least, the following executables are built:
	
	  +++ samhain        +++ the monitoring agent, 
				 with client code included

	  +++ yule           +++ the log server  (no monitoring, just report
				 collecting !!!)

	  +++ samhain_setpwd +++ a utility program to set the password of
                                 a monitoring agent (see man page samhain.8).
				 Use it without options to get help. 
                                 

	To set up a monitoring agent, do the following:

 	  -- select a (16-digit hexadecimal) password

	  -- use 'samhain_setpwd samhain <suffix> <password>'
	     to generate an agent 'samhain.suffix' with the selected password
	     (you can rename the agent afterwards, of course) 

	  -- use 'yule -P password' to compute an entry to register the agent

	  -- in the servers's configuration file, insert the computed entry
	     (replace HOSTNAME with the host, on which the agent will run)

	By default, client/server authentication 
	is done with a challenge/response protocol.

	For improved security, it is possible to use the SRP 
	(Secure Remote Password) algorithm instead, which is enabled by
 
		./configure --enable-srp [more options]


	It is also possible to store configuration and database files
	on the server. See the manual for details.

STEALTH:
-------

	samhain supports a 'stealth' mode of operation, meaning that
	the program can be run without any obvious trace of its presence
	on disk. The supplied facilities are more sophisticated than 
	just running the program under a different name,
	and might thwart efforts using 'standard' Unix commands,
	but they will not resist a search using dedicated utilities. 
	To enable this mode, use the ./configure option

		./configure --with-stealth=XOR_VAL [more options]

	XOR_VAL must be a decimal number in the range 0, 128..255
	(using 0 will have no effect).

	The runtime executable will contain no printable strings revealing
	its nature or purpose (strings are xor'ed with XOR_VAL at compile 
	time, and decoded at runtime). 

	The configuration file is expected to be
	a postscript file with _uncompressed_ image data, wherein 
	the configuration data are hidden by steganography.
	To create a suitable image file from an existing image, 
	you may use e.g. the ImageMagick program 'convert', such as:

		convert +compress ima.jpg ima.ps

	The following additional executable will be built:
 
	  +++ samhain_stealth +++ steganography utility program to hide/extract
				  the configuration file data in/from a 
				  postscript file with
				  _uncompressed_ image data.
				  Use it without options to get help. 

	Database and log file entries are xor'ed with XOR_VAL to 'mask' 
	printable strings as binary data. No steganography is supported 
	for them, as this would require image files of unreasonable large
	size.
	However, if the database/log file is an existing image (say, a .jpg
	file), the data will be appended to the end of the image data.
	The image will display normally, and on examination of the file,
	the add-on data will look like binary (image) data at first sight.
	The built-in utility to verify and print log file entries 
	will handle this situation transparently.

	NOTE: You are responsible by yourself for re-naming the compiled
	executable(s) to unsuspicious names, and choosing likewise
	unsuspicious names for configuration file, database, and log (+lock) 
	file (AND you need to specify these names at compile time, using 
	the appropriate options for 'configure' -- see below -- )


USAGE EXAMPLES:
--------------

	Review the default configuration file that comes with the
	source distribution. Read the man page (samhain.8).

	initialize database:  samhain -t init

	check files:          samhain -t check

	run as daemon:        samhain -t check -D

	report to log server: samhain -t check -D -e 3

	start the log server: yule -S 


CAVEATS:
-------
	Permissions:
	-----------
	samhain needs root permissions to check some system files. It 
	can be set SUID root, although there is no real reason to do
	so. If SUID, root privileges will be dropped at startup, and only
	regained when necessary. 
	The log server does not require root permissions, unless
	you use a privileged port (port number below 1024).

	Trust:
	-----
	samhain checks the path to critical files (database, configuration)
	for write access by untrusted users. By default, only root and
	the effective user are trusted. More UIDs can be added as a
	compile options (some systems habe 'bin' as owner of the root
	directory).

	Integrity:
	---------
	On startup, samhain will report on signatures or checksums of
	database and configuration files. You better check these reports.

	Both startup and exit will be reported. If you are using samhain
	as daemon and start it at boot time, you may want to check that
	startup/exit corresponds with scheduled reboots.

	If the path to the samhain binary is defined in the configuration
	file, samhain will checksum the binary at startup and compare 
	at program termination. This will minimize the time available
	for an intruder to modify the binary. 

	Mail address:
	------------
	Not every host will accept mail, and samhain does no DNS lookup 
	for the proper mail exchanger. Take care with the mail address.
 
	For offsite mail, you may have to set a mail relay host 
	in the configuration file.

START AT BOOT TIME:
------------------
	the easy way (probably works on Linux only): 

		su root
		make install-boot

	the nasty details:

	The following explanation assumes a System V-like boot concept. 
	More information can be found in the init(8) man
	page, or in /etc/init.d/README (/sbin/init.d/README for SuSE Linux).

	First review the supplied script 'samhain.start' (there are
	some paths you might need to change), and then copy it
	to '/etc/init.d/samhain' (on SuSE Linux, this should rather
	be '/sbin/init.d/samhain'; on RedHat, '/etc/rc.d/init.d/samhain'). 

	The script  /etc/init.d/samhain starts or stops the samhain
	daemon, according to the flag used:

	       /etc/init.d/samhain start
	and
	       /etc/init.d/samhain stop

	Your system will boot into some 'run level' (usually run level 2 or 3).
	To start a program when booting in (e.g.) run level 2, the startup
	script should be linked into /etc/rc2.d/ with symbolic links:

	       /etc/rc2.d/S99samhain -> ../init.d/samhain
	and
	       /etc/rc2.d/K10samhain -> ../init.d/samhain


	NOTE: on SuSE Linux, these should be 

	       /sbin/init.d/rc2.d/S99samhain  -> ../samhain
	and
	       /sbin/init.d/rc2.d/K10samhain  -> ../samhain

	NOTE: on RedHat Linux, these should be 

	       /etc/rc.d/rc2.d/S99samhain  -> ../init.d/samhain
	and
	       /etc/rc.d/rc2.d/K10samhain  -> ../init.d/samhain

	The corresponding link with the letter S is used to  start
	a service. The number after S determines the order, in which
	services are started. For samhain, this number should
	be greater than the number of the  start link of the 
	network service, if you make use of it (e.g. report forwarding
	by e-mail). However, if the network is not immediately available,
	samhain will retry.

	The corresponding link with the letter K is used to stop a
	service. The number of the stop link for samhain should be
	less than that of the stop link for the network service so
	that samhain is stopped before shutting down the network service
	(again, if you make use of it). 

	Run levels (may be different for your system - consult the
	init(8) man page):
		2  	This run level is for stations not 
			automatically running X windows.
		3	This run level is with network and X.
 

CONFIGURE OPTIONS:
-----------------

    -------------------
    -- basic options --
    -------------------

		--enable-network        Compile with client/server support.

		--enable-srp            Use SRP protocol to authenticate to 
					log server.

		--with-gpg=PATH         Use GnuPG to verify database/config.
					The public key of the effective
					user (in ~/.gnupg/pubring.gpg) 
					will be used.

		--with-pgp=PATH         Use PPG to verify database/config.
					The public key of the effective
					user (in ~/.pgp/pubring.pgp) 
					will be used.

		--enable-login-watch    Watch for login/logout events.

		--with-stealth=XOR_VAL  Enable stealth mode, and set XOR_VAL.
					XOR_VAL must be decimal in 
					0..32 or 127..255
					and will be used to 'mask' literal 
					strings as binary data.
					(0 has no effect).

		--with-micro-stealth=XOR_VAL  
					As --with-stealth, but without
					steganographic hidden configuration
					file.

		--with-nocl=PW          Enable command line parsing ONLY if
					PW is the first argument on the command
					line. If PW is "" (empty string),
					command line parsing is completely
					disabled.

		--with-base=BASE        Set base for one-time pads. Must be
					ONE string (no space) made of TWO
					comma-separated integers in the range
					-2147483648...2147483647.
					(The default is compile time.)
					Binaries compiled with different
					values cannot verify the audit trail(s)
					of each other.
					THIS IS IMPORTANT IF YOU COMPILE
					MULTIPLE TIMES, E.G. ON DIFFERENT 
					HOSTS.


    -------------------
    --   paths       --
    -------------------

		--prefix=PREFIX		root install directory
					(default is /usr/local)		

		--with-config-file=FILE	Set path of configuration file
					(default is /usr/local/etc/.samhainrc)

		--with-dataroot-prefix=PFX	
					Set directory for data
					(default is /usr/local/var/log),
					OR set individually:
		--with-data-file=FILE	   Set path of data file
					   (/usr/local/var/log/.samhain_file)
		--with-log-file=FILE	   Set path of log file
					   (/usr/local/var/log/.samhain_log)
		--with-lock-file=FILE	   Set path of lock file
					   (/usr/local/var/log/.samhain_lock)

    -------------------
    --  other        --
    -------------------


		--with-checksum=CHECKSUM   Compile in TIGER checksum of the
					gpg/pgp binary.
					CHECKSUM must be the full
					line output by samhain or GnuPG when
					computing the checksum.

		--with-fp=FINGERPRINT   Compile in public key fingerprint.
					FINGERPRINT must be without spaces.
					Only useful in combination with
					'--with-gpg'. 
					If used, samhain will check the 
					fingerprint, but still report on the 
					used public key.

		--with-identity=USER	Set user when dropping root privileges
					(default is the user "nobody").
					Only needed if there is no user
					'nobody' on your system 
					(check /etc/passwd)

		--with-port=PORT	Set port number for TCP/IP
					(default is 49777).
					Only needed if this port is already 
					used by some other application.

		--with-logserver=HOST	Set host address for log server
					(default is NULL).
					You can set this in the configuration
					file as well.

		--with-timeserver=HOST	Set host address for time server
					(default is NULL - use own clock).
					You can set this in the configuration
					file as well.

		--with-sender=SENDER	Set sender for e-mail
					(default is daemon).

		--enable-debug		Enable extended debugging

		--enable-ptrace		Call ptrace() for anti-debugging.

		--with-trusted=UID	Comma-separated list of UID's of
					users that are always trusted
					(default is 0 = root).
					You will need this only if the
					path to the config file has directories
					owned neither by 'root' nor by the
					(effective) user of the program. 


TESTING:
-------
	For testing compilation etc., you may use the test suite:

		./test.sh n [hostname]

	The argument 'n' is the number of the test to run. Some tests require
        that the (fully qualified) hostname be given as second argument.

	Without options, you will get a short help/usage message, listing
	each test, its purpose, and the name of the configuration file used.
	You may want to review the respective configuration file before
        running a test.

	Also listed are the scripts used for each test. If you have problems
	getting samhain to run, you may use these scripts as examples.

