$Header: /cvsroot/sid/sid/docs/users_guide.txt,v 1.5 2005/01/08 19:37:49 deppeler Exp $

This file describes the configuration and how to run SID. 

A more detailed description of how SID works is given in the file docs/README.

Contents
--------
- Quickstart
- Installation
- Configuration
- Running
- Caveat


Quickstart
----------

1) Install kernel and user part (see INSTALL).

2) Load kernel part:
- Solaris: via '/etc/init.d/tswk start' for package installs
           via 'modload tsw' for manual builds
- Linux 2.4: via '/etc/init.d/sidk start' for package installs
             via 'insmod tsw.o'
- Linux 2.6: via "insmod sidkl26x86.ko t_sys_call_table=0x`awk '/sys_call_table/ { print $1 }' /boot/System.map-\`uname -r\``"

3) Adapt user part configuration file
   Solaris package installs: cp /etc/tsw.conf.example /etc/tsw.conf
   Debian Linux package installs: /etc/sid/sid.conf

   basic configuration file adaptions:

   specify logfile location 
            logfile: /var/log/messages (Linux)
                     /var/adm/messages (Solaris)

   set maintenance mode password       
            admin: interactive         (read in upon startup)
	 or admin: sha1 hash	       (hash is hased password)
   the hash can be generated by running 'tsw -s'

   adapt the hostnames, add new sections, etc.

4) Run the user part:
   - package installs: Solaris: /etc/init.d/tswu start
                  Debian Linux: /etc/inid.d/sidu start

   or
   - manually run the user part './tsw -c test.in'

5) [Optional] Reload the user part with a new configuration
   - check whether the configuration parses ok ('tsw -c new.config -t')
   
   - send a HUP signal to the tsw process to load the new config.


Installation
------------

The installation and removal the kernel and user part of sid for Solaris
and Linux is described in the file INSTALL.


Configuration
-------------

Linux: as soon as the kernel module is loaded, the kernel part should
start to log for any ptys on the system.

Solaris: as soon as the STREAMS module is loaded and the module has
been configured to be automatically pushed onto STREAMS via autopush,
the kernel part should start to log for newly opened ptys.
(which Solaris ptys have sid inserted in their stream can be configured
via the file /etc/iu.ap.tsw)

Check your kernel facility logfile to verify that logging takes place
for newly opened ptys. If not, adapt /etc/syslog.conf and restart syslogd
(on Linux: also klogd, if available).


The user part can be configured via its configuration file. A sample
configuration file is given below.

Global options are:


- Logfile specification. Syntax:

  logfile: /path/filename

           /path/filename specifies which logfile should be watched

- Maintenance mode for PTYs.
  Upon opening, the sysadmin may enter a password (the way she enters
  a command on the shell) in order to turn off alerting for this pty.
  Syntax:

  admin: (interactive|sha1 hash)

          'interactive' will ask for the password on startup of the user 
	  part
	  'sha1 hash' specifies the sha1 hash of the password.
	  the sha1 hash of a password can be created by running './tsw -s'

[TODO: complete the syntax spec]

#------start-of-configuration-file-------
#
# global options
#
# where are the kern.* messages logged?
logfile: "/var/log/messages"

# if any (or all) of the hosts specifiy 'global' as their way to enter
# administrative mode:
# how is the password for global administrative access entered?
# currently, only 'interactive' and 'none' is implemented.
#admin: interactive
admin: sha1 "ebfdec64 1529d4b5 9a54e18f 8b0e9730 f85939fb"

# sample host definition
host: "solaris8x86"
	# how is the password for this specific host entered?
	# currently, only 'interactive' and 'global' is implemented.
	admin: global 
	admin_attempts: 3 # how many attempts for the admin mode?
	
	# when will the specified automated action be carried out upon
	# unexpected pty lines?
	automated_time: Mo-Th 19:00 +12h
			Fr 17:00 +2d13h

	#automated_action: "/usr/sbin/ifconfig pcn0 down"
	automated_action: "echo 'Intruder Alert!' | wall"

	# when an unexpected pty lines are encounted, what is logged and
	# how is it logged?
	syslog: message: "unexpected command"
		facility: "user"
		priority: "error"
		tag: "HOST_IDS"

host: "blade"
	admin: global
	admin_attempts: 0 # no administrative mode for this host

	automated_time: Fr 15:00 +2d19h
			Thursday 11:00 +7h

	automated_action: "echo 'Intruder Alert!' | wall"

	syslog: message: "Intrusion detected"
		facility: "user"
		priority: "error"
		tag: "HOST_IDS"
#------end-of-configuration-file-------

Running
-------

Run the user part as follows:

in packaged distributions:
# /etc/init.d/tswu start 	(Solaris)
# /etc/init.d/sidu start	(Linux)

manually:
% ./tsw -c test.in

(test.in is the filename of the configuration file)


Caveat
------

When entering the administration password on the shell prompt (in order
to disarm the alarm system), your password will be saved in the shell's
history if your default shell provides such a mechanism.

To work around this, use the Bourne shell as your default shell on
Solaris. On Linux, you have several options to work around this:

- use the bash's HISTCONTROL variable to stop the shell from logging
  your password in the shell's history file:
  o e.g. choose password that starts with a space
  o set 
    export HISTCONTROL=ignorespace
    in bash's startup configuration file ~/.bashrc
- unset the history file in the shell's startup configuration file, e.g.
  export HISTFILE=/dev/null
  in ~/.bashrc
  you can always turn history on after having entered your password.

- use a default shell without history, e.g. /bin/sh
  ('bash' called as 'sh' will act more like the Bourne shell and will not
  provide a command history).
