
	SATOOLS, System Administrator Tools.
	Copyright (C) 1995,1996  Lars Berntzon, Cecilia Data AB

	This program is free software; you can redistribute it and/or modify
	it under the terms of the GNU General Public License as published by
	the Free Software Foundation; either version 1, or (at your option)
	any later version.

	This program is distributed in the hope that it will be useful,
	but WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.
	
	You should have received a copy of the GNU General Public License
	along with this program; if not, write to the Free Software
	Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

-------------------------------------------------------------------------------
	
1.	INTRODUCTION

1.1	PURPOSE

	This document describes how to install satools and sahostinfo.

1.2 	BACKGROUND

	Satools consist of two parts:

	The first part, satools itself, is a set of executable commands which
	can be installed anywhere at your wish. These commands include
	'machines' which is used for listing hosts according to certain
	search criteria or to show values for one or several hosts, and
	'sadist' to distribute data to hosts.

	The second part, sahostinfo, is a set of shell scripts that is used
	to get information about hosts. Information like connected subnets,
	IP addresses, physical memory etc. This is normally an automatic task
	started say every night by crontab. The command 'mkmachines' in the
	satools subdirectory will then start to loop through all hosts in the
	network, remote login to those hosts and run the sahostinfo scripts
	to get the data from the hosts. This data is then stored in the sadb
	database which in turn is used by be machines and sadist commands.
	To make this automatic examination work then all scripts belonging to
	sahostinfo must either be NFS-mounted on every host (I'd prefer this)
	or every host must have its own copy of the sahostinfo scripts. It is
	also recommended and sometimes necessary to create a pseudo user for
	the sahostinfo scripts. All scripts are then placed in the home
	directory for this pseudo user. The reason to create a pseudo user is
	that this user must be allowed to rlogin (rsh) from one host to all
	hosts in the network (or all hosts you administrate rather). This
	pseudo user could also have very short login files (like .login,
	.profile, .cshrc etc.) to make the rlogin fast.
	It probably necessary to define such pseudo user if you plan to have
	several disjoint domains in this database.


2.	INSTALLING SATOOLS

2.1.	DECIDING IN WHICH DIRECTORY TO INSTALL BINARIES

	All binaries, manual pages, X-default files and various library files
	needs to be installed beneath one UNIX directory. You must decide
	what directory you prefer. I usually use a directory like
	/usr/local/satools or something similar.

2.2.	CONFIGURE FOR COMPILATION

	When you unpacked the tar file or unshared the news files you will
	have a directory called satools-n.n, beneath this directory there are
	two subdirectories. One for sahostinfo and one for satools. In the
	satools subdirectory run the command configure with the argument
	--prefix=<install-dir> where <install-dir> is what you decided in
	section 2.1 above. Like this:

	    ./configure --prefix=/usr/local/satools

	Older versions of satools (1.1 and earlier) used ndbm or dbm as database
	by default. If you still want to use them you must supply the option
	-without-gdbm for configure like this:

	    ./configure -without-gdbm --prefix=/usr/local/satools

2.3.	COMPILE	SATOOLS

	Still in the satools directory start the compilation by running make.

2.4.	TESTING

	You can test that the database part seems OK by moving to the
	directory <unpack dir>/satools/sadblib/test and running make there.
	It should after about 10 minutes print a couple of lines with the
	text: "test_.... passed".

2.5.	INSTALL SATOOLS BINARIES

	Make sure that the target directory you decided in step 2.1 exist and
	that you have permission to create new files and directories in that
	target directory.
	Then run:

	    make install

	in the satools subdirectory.

3.	INSTALLING SAHOSTINFO

3.1.	CREATING A SPECIAL SAHOSTINFO USER

	Create a pseudo user account, i normally use a name like 'machines'.
	Make sure that this user does have short login files with minimal
	environment and paths, this is to make rlogin to be fast.

3.2.	DECIDE WHAT CENTRAL SERVER TO USE

	Normally there is one central server in the system that is used by
	sahostinfo to remote login to all hosts and get information about
	the hosts. Decide which server to use and then create a .rhosts file
	in the pseudo users home directory in which you write the name of
	this central server. If it has several names, like when a server is
	connected to several Ethernet segments each network connector has its
	own name. You probably need to write all those names in the .rhosts
	file.
	You also need to add the name 'localhost' to this .rhosts file.

	You can verify that the .rhosts file is proper setup by running
	the command:
		rsh <test host> date
	where <test host> is one host you are planning to examine by
	sahostinfo.

3.3.	COPY SAHOSTINFO FILES

	All scripts and directories in the sahostinfo subdirectory must be
	copied to the pseudo users home directory, this might be done as:

	    cd <unpack-directory>/satools-n.n/sahostinfo
	    cp -r * ~machines

	You might want to limit permissions to only allow the pseudo user
	itself to read and execute the files, this can be done by:

	    chmod 700 ~machines

3.4	DECIDE WHERE THE DATABASE SHALL BE

	You now need to decide where the database for sahostinfo shall be.
	I normally use a directory named sadb beneath a common system
	administrator account, for example /home/sysadm/sadb. It is a good
	choice to use sadb as a directory name because when satools is in
	operation the user does only need to define one environment variable
	called SAHOME and set it to this sysadm account (/home/sysadm in my
	example above). All commands in satools, like machines and sadist, 
	will use the SAHOME to find its databases. The machines command will
	default to use $SAHOME/sadb for its top database directory and sadist
	will by default use the database $SAHOME/sadist for its files.
	Create this directory and a directory below that called 'machines.db'.
	Make sure that the pseudo user has write permission to this latter
	directory.

3.5	CREATE CRONTAB JOB FOR PSEUDO USER

	To start the automatic examination of hosts create a crontab job for
	the pseudo user. In order to do this you need to know where the
	satools binaries are located (see step 2.1 above) and where the
	machines database is located.
	A good start for writing this crontab job is to modify the
	crontab.example in the sahostinfo subdirectory, remember to modify
	all occurrences of <edit-here> in this file.
	Also make sure that the pseudo user has write permissions to the
	database.
	A normal crontab job for mkmachines might look like this:

	0 2 * * * /usr/local/bin/mkmachines -sahome /home/adm -x -nis

	If you want to examine other hosts in other domains you must also
	supply the host names of those hosts in the script or by using for
	example the -rnis option as in:

	0 2 * * * /usr/local/bin/mkmachines -sahome /home/adm -x -nis -rnis thor

3.6	ADD EXTRA COLUMNS (optional)

	You can easy add extra columns in the database for automatic inventory. First you must
	create a script or program that prints the value you want. Say a script for printing 
	the uptime of the machine. The script should not be called as an existing UNIX command, lets
	give it the name uptm. It would probably look something like:

		#!/bin/sh
		uptime

	Quite simple, you should then create a own directory in the pseudo users home directory. Call
	it what you like, i prefer calling it after the site or network i'm on. Move the script into
	this directory (make sure it is executable) and create a file called columns.dat in that
	directory. This file list all columns and gives a description of the column. For above example
	this file should look like this:

		uptm	Uptime for host


3.7	MANUAL DATA FOR MACHINES (optional)
	
	It is possible to add manual data to machines, i.e. data that can not automatically be examined.
	You do this by creating the file /etc/satools.info with the information you like. I rekomend adding
	information like serial number, inventory number and owner. The file would look like:

		serial_number 123-5436
		inventory-number 238473-23
		owner Lars Berntzon
		room 324
		site V
		
3.8	CREATING OWN DATABASES (optional)

	To create your own database i rekomend using the GUI xsadb. Its a bit cruel but you can create new
	databases from in there. 
	A nother way is to feed the satools external data format into the command 'mkmachines -i -db <data-base>'.

4.	CONFIGURING SADIST FILES

	In order to use satools and sadist in particular you need of course
	to define how all distributions shall work, what should happen when
	the distribution motd is distributed for instance. All files for
	a distribution is located below $SAHOME/sadist (or below $SADISTDIR
	if that is set) and in a subdirectory with the same name as the
	distribution. In short a file named 'Control' needs to be created
	there and a file called 'default' but all this is described in the
	sadist man page in section 5 (man 5 sadist or man -s 5 sadist).

	In the distribution there is also a example file of sadist.cfg 
	called sadist.cfg.ex. This file is installed in the lib subdirectory
	of the installation directory. Copy the distribution example file
	to the real file if you have no sadist.cfg file already.

5.	SUMMARY

	These are the main steps in some kind of pseudo shell syntax to
	configure satools, in a very short form.
	The installation directory is represented as <install-dir>. The
	machines database directory is represented as <db-dir> and the
	sadist top directory for distributions is represented as
	<sadist-dir>. The top directory for the binaries to be installed is
	represented as <destination-dir>.  The central server is represented
	as <central-server>. The pseudo user is represented as <pseudo-user>.
	
	# mkdir <destination-dir>
	# cd <install-dir>/satools
	# ./configure --prefix=<destination-dir>
	# make
	# make install


	# add_user <pseudo-user>
	# mkdir <db-dir>/machines.db
	# chown <pseudo-user> <db-dir>/machines.db
	# su <pseudo-user>
	> cd ~<psuedo-user>
	> cp -r <install-dir>/sahostinfo/* .
	> echo <central-server> > .rhosts
	> cp croncript.example cronscript
	> vi cronscript
	[ set SAHOME to <db-dir> and append <destination-dir/bin to PATH]
	> crontab
	0 2 * * * ./cronscript
	^D
	> exit

	# mkdir <sadist-dir>/<distribution>
	# vi <sadist-dir>/<distribution>/Control
	# vi <sadist-dir>/<distribution>/default
	.
	.
	.

	And you are done, oh by the way you need to make sure the SAHOME
	environment is set correctly next time you log in. But that should
	be all, i think.

6.	NOTES

	If you are using Linux slackware-96 i had to create a symbolic link
	from /lib/libdl.so pointing to /lib/libdl.so.1 by running the command
	as root:

		ln -s /lib/libdl.so.1 /lib/libdl.so

	If you are using Linux slackware 3.0 you will have to change the
	-lg++ in all makefiles into /usr/lib/libg++.a, i.e. the statically
	linked library, since the dynamic version of libg++ seems to have
	many problems. You can also move the libg++.so* files away from
	/usr/lib.
	If that doesn't help, you might need to use a static version of the
	libc. This is easiest changed in the config.status. Find the line
	matching s%@LIBS.... add the text '/usr/lib/libc.a' before the
	last percent character in that line.
	The symptom in slackware 3.0 is that all binaries crashes with
	segmentation fault.
