------------------------------------
INSTALL - ISPutil installation notes
------------------------------------

-------------
REQUIREMENTS:
-------------

	SAVVY	You probably currently need to have a bunch of assorted
		Sysadmin and/or script-language experience to use this
		stuff, it is not plug and play for end-user types yet.
		The new-user routine for example actually has to be
		compiled from C sources which will need to have some
		constants tailored for your environment.

	BASH	You need a bash-compatible shell to execute the various
		shell-scripts. I am not sure if any bash-isms are used
		in them which might preclude using other sh-type shells.

	MAKE	You need to have the "make" command installed.
		Available at e.g. sunsite.unc.edu.

	GCC	You need a C compiler to compile at least the new user
		routine, since it needs some system-specific information
		compiled into it.

	DIALOG	You need the "dialog" command (if you are using
		Slackware you should have it, as Slackware's install
		system uses it). Available at e.g. sunsite.unc.edu.

	SUPER	You need the "super" command, available at
		e.g. sunsite.unc.edu. This is used to grant users
		various needed privileges to write logs, change their
		shell and so on, in a controlled manner.

	QDDB	You need the Quick and Dirty Data Base system,
		available at e.g. ftp.ms.uky.edu.

		You need at least the textmode utilities and qtclsh.
		The GUI (nxqddb) based on Tk and extensions is not
		technically necessary in order to run the package but
		is probably going to be useful to have.

	Groups	You need certain groups to exist in your /etc/group file.
		These are:
			users 	-	Normal users
			guest	-	New/Unvalidated users.
			slipin	-	SLIP/PPP dialin customers.
			staff	-	Staff, not necessarily sales/sysop.
			sales	-	Persons who can create NEW users.
			sysop	-	Administrative staff

		I use the dslip package for slip usually, so the group
		slipin is the group which a user needs to be in order
		to execute the dslip incoming-slip routines.

		The group "users" is not intended for customers, it is
		the Slackware default that oneself and one's friends,
		and the staff, sales, and sysop people, all belong to.
		The only people whose actual login group is not "users"
		in this system are the dialin SLIP/PPP users, because
		they need to be group slipin to run the dslip routines
		that establish their SLIP connection if they have chosen
		SLIP as their protocol.

	BBSutil This is now known as Dial-Up_Utils, but the version used by
		ISPutil still needs one additional routine not included in
		the standard distribution. I have a version packaged up
		ready for ISPutil to use at
		http://www.kayhay.com/pub/linux/distrib/kip1/bbsutil.tgz
		which is already compiled to the directories and such that
		ISPutil and WWWutil expect.

-----------
TO INSTALL:
-----------

NOTE that although this package has a start toward being moveable to
different directories via the config.sh script invoked by "make install",
in fact that really only works for shell scripts; all the tcl/qtcl scripts
would still need manual editting if the package were not placed into
/var/lib/ISPutil as expected.

super.tab:	There is a sample super.tab file in the util directory,
		showing what you need to add to your super.tab file.

/shells:	Create a directory /shells as a symbolic link pointing
		to the $ISPUTIL/shells directory. (ie the shells directory
		in this package, wherever you have placed this package).
		The scripts therein are the login shells for the various
		types of users. NOTE there are now shells.mainhost and
		shells.modemhost directories, since the requirements for
		what the shells do are different on each host. If you do
		not have separate hosts you may have to fiddle some to
		put together a shells.both which hopefully a future version
		will include.

edit Makefile:	Edit the Makefile - at the top of the file are a whole
		bunch of defines for paths and such. Check that they are
		correct for your system.

make install:	In the main directory of the package, do a "make install".
		This will create a paths.dat file containing various paths
		used to find things; and will run a script that processes
		all the scripts substituting in these paths where needed.

Database initialisation:

	ISPutil uses a QDDB relation named Clients in which to store user 
information. This relation is derived from the Clients relation in the 
Qba (QDDB Business Application) package found at
ftp://ftp.ms.uky.edu/pub/unix/qddb/ among the example apps.

Included in the ISPutils package is what amounts to a hacked version of 
the Qba package, hacked primarily to support new fields in the Clients 
relation. So you don't need to actually go out and get Qba, I am just 
telling you this to acknowledge the derivation of the accounting apps.

The hacked Qba basically still works as Qba used to work, it just has a 
lot more fields in the Clients schema and a few of them supported in the 
custom GUI interface for that relation.

As I write, the Clients relation is currently not used by much of the 
package, however new users get added to it and eventually the plan is to 
drive the entire administration of the system from the databases. Where 
currently new users are added using a 'C' program which also posts them 
to the database, one day the plan is to do the reverse: enter them into 
the database and create their Operating System user accounts from the 
database information. The Clients database does however contain the 
accounting information which drives user timelimits.

There are various scripts for bulk processing of the Clients database in 
$ISPUTIL/util/import, look these over before using them to check what
they do. Paths in .qtcl scripts are not presently (as of version 0.2) 
substituted in by the "make install" routines, and some of the scripts 
are oneshots that happened to be of use on some occassion or another or 
which were never gotten into working state.

----------
MODEMHOST:
----------

If your MODEMHOST is not your MAINHOST, the MODEMHOST needs only a small 
part of this package:

	$ISPUTIL/bin/doas
	$ISPUTIL/bin/pwdoas

However it does need the Dial-Up_Utils package. Versions before 1.20 
needed sessreg to be SUID root and use pwdoas.uid; 1.20 recognises EUID
properly so pwdoas.euid can be used and sessreg need not be SUID.~

The webserver user (the UID used for rsh from mainhost to modemhost for 
setting user timelimits etc) must have ability to run some of the 
Dial-Up_Utils programs as SUID root programs. We do that by having the 
webserver user be group daemon and give group daemon execute permission 
to these programs. The script modemhost.permissions.sh in ./root shows 
the permission settings we use.

--------------------- 
HTTPD rsh capability:
---------------------

Because ISPutil was put together largely in conjunction with WWWutil, the 
Dial-Up_Utils and such were set up on the MODEMHOST in such a way that 
the user "httpd.daemon" (our webserver) on the MAINHOST could rsh to the 
MODEMHOST to assign user timelimits, give users more time, obtain 
information about user time remaining and so on. For simplicity the menus 
for groups sales, staff and sysop also use the httpd UID to accomplish 
these tasks.


-------------------
Credit Limit stuff:
-------------------

Credit Limits were not used for a while; and a Pending field was used 
pending posting to real balances. Version 0.5 now posts via the invoices 
to actual balances but the options for users to purchase stuff themselves 
still has not been updated so continues to use the Pending thing. Hope to 
fix that soon since inconsistency is a real drag.

Here is older text from versions prior to 0.5 ...

The routines for buying/selling blocks of online time check the user's 
credit limit from the database, but currently do not post transactions so 
they do not affect the credit limit. As an interrim fix while I check out 
the whole accounting and transaction system, I am going to simply post 
the cost of the sold time to the (new) "Pending" field and check that as 
well as the credit limit when deciding whether to sell them more time.
In the Qba system until an invoice is actually "processed" it does not 
get posted to the user's record in the Clients relation, so to correctly 
update the user's balance would involve not only writing to an invoice 
but closing the invoice. The "pending" field should allow us to instead 
post time sales to an open invoice which will not be processed until the 
end of the billing period. It will basically be the balance of open 
invoices.
