This is the README file for the program usrchk 1.06a
I threw it together pretty quick, so if you feel I'm missing anything or
see a discrepency (spelling?) email me.

ATTENTION!!!!
IF YOU'RE GOING TO RUN THIS ON A WIN32 SYSTEM, I.E.
WINDOWS 95/98/NT/ME/2000, YOU ARE URGED TO DOWNLOAD THE WIN32 BINARY
DISTRIBUTION AT http://www.asteroid-b612.org/software


Relevent unix files included in this package:

usrchk.c - The main port checking program. Compile on Linux, SunOS, and
	   Solaris machines with: gcc -o usrchk usrchk.c
	   For other systems, see source code comments.

usrchk.cfg - Default config file that the program reads to get its options
	    and dialup server info. Program reads it from /etc/usrchk.cfg
	    by default.

READ-ME-UNIX      - Readme file for unix based systems
CHANGES           - Changelog/History of the program
TODO              - Things to program yet


INSTALLATION
------------
1. Copy usrchk.cfg to /etc or wherever you want it installed. Preferably
   OUTSIDE a web-accessible directory.
2. Copy usrchk.c to wherever you want it installed. If you installed
   usrchk.cfg into somewhere other than /etc, either edit the CONF #define in
   usrchk.c to specify where, or use the "-f /path/to/config" switch when 
   running the program, to tell it where your config file is.
3. Compile usrchk.c. Usually "gcc -o usrchk usrchk.c"
4. Give usrchk execute permissions by the web server. Usually
   "chmod 755 usrchk"
5. Configure usrchk.cfg for your hosts as per instructions below.
6. Copy usrwho.sh to a web-accessible directory. Edit usrwho.sh to
   specifiy the FULL path where the usrchk program is installed and which
   hosts or groups (which you configure in usrchk.cfg) you want to check
   with it.
7. Make usrwho.sh executable by the web server. Usually "chmod
   755 usrwho.sh" Make sure the web server can execute .sh scripts
8. See USAGE section for running the program


SETTING UP THE CONFIG FILE
--------------------------
The config file (defined by #define CONF in usrchk.c, or -f on the command 
line) is used so the program doesn't have to be recompiled when a change 
to frequently changed variables is made. By default it looks for it in 
/etc/usrchk.cfg.
Since this file contains your dialup server passwords, make sure it's only
readable by the usrchk program, if you have other users on the server
you're running this off.
Variable settings in this file are preceeded with a "VARIABLE_NAME: "
reference. NOTE no spaces before the : and a space after the colon and
before the value.
Comments in the file explains what each variable does.
The last set of variables if the chassis information.
The syntax of each line is as follows:

BOX: <hostname> <username> <password> <linestotal> <beforekill> <startport>
<lastport> <sortTime> <type> <group> <name>

the syntax above may wrap in your editor, please be aware that all
variables go on a SINGLE LINE.

Hostname is the ip and location designation letter. If 1 chassis
is used for serveral cities, the letter breaks the city into a seperate
table and makes the identifier unique. This is like the opposite of the
group concept. See sample config file for examples.

Groups are made by linking like servers to the same group name.
This is usually done is there are multiple dialup server to 1
location/POP. The group allows:
 1) the program to determine the correct number of ports for auto-killing
    on a POP. We need to tranverse all servers in a group to find the
    highest session user to disconnect.
 2) To more easily specify hosts on the command line or in the web script.
Even if you only have one server for a location/POP, give it a group name
as in the example config file.


USAGE
-----
You can run the program 4 ways.

1) From the command line

From the command line you can use the program to output text only
information or do manual port/auto-killing. Type the program name,
followed by any number of options (found by "usrchk -h") and a list of
space-seperated hosts or groups.
Examples:
to get host information for the host 192.168.1.1
Type: usrchk 192.168.1.1
to get host information for all hosts in the group "Hazleton"
Type: usrchk Hazleton
to get host information and all summary info for all hosts in the group
"Hazleton"
Type: usrchk -S -T Hazleton
to perform a manual auto-kill on the group "Hazleton"
Type: usrchk -k Hazleton

and so forth..


2) From a web page directly

First, for one-time-only, you need to make a symbolic link called 
usrchk.cgi and point it to the usrchk program.

From the directory usrchk is installed in:
ln -s usrchk usrchk.cgi

This is so the web server knows you're calling a cgi. If you call the
usrchk program directly, it wont know you're running a program.

Now..

Go to the url:
http://www.yourdomain.com/yourcgibin/usrchk.cgi?<options>

where <options> is a query string to tell it what to do.
It's the same as the command line options, jsut in web format

example: to view normal info for the group "Hazleton" the last part
would be:
        /usrchk.cgi?-H&Hazleton
example: to view normal info and speeds for the group "Hazleton" the
last part would be:
        /usrchk.cgi?-H&-c&Hazleton
example: to view normal info, speeds, and do sorting by "port" for
the group "Hazleton" the last part would be:
        /usrchk.cgi?-H&-c&-s&port&Hazleton
example: to disconnect the user on port slot:1/mod:5 on host 1.2.3.4a would be
	/usrchk.cgi?-P&slot:1/mod:5&1.2.3.4a

each option corresponds to a command line option with & denoting a space.


3) From a web page through a form

First, for one-time-only, you need to make a symbolic link called
usrchk.cgi and point it to the usrchk program.

From the directory usrchk is installed in:
ln -s usrchk usrchk.cgi

This is so the web server knows you're calling a cgi. If you call the
usrchk program directly, it wont know you're running a program.

Now..

Here, the query string is formed by putting a the command line options
as input types to a form. Where the option name/switch is the name=""
part, and the desired feature for that option is the value="" part

Example:
<FORM METHOD=GET ACTION="http://www.yourdomain.com/yourcgibin/usrchk.cgi">
<input type=hidden name="-H" value="1">
Session Status
<select name="-c">
<option value="0">No speeds</option>
<option value="1" selected>w/ speeds</option>
</select>
<select name="-s">
<option value="port">sort by ports</option>
<option value="time" selected>sort by time</option>
<option value="speed">sort by speeds</option>
</select>
<select name="host">
<option value="Hazleton" selected>Hazleton</option>
<option value="Wilkes-Barre">Wilkes-Barre</option>
<option value="Bloomsburg">Bloomsburg</option>
<option value="Scranton">Scranton</option>
<option value="Tamaqua">Tamaqua</option>
<option value="Shenadoah">Shenadoah</option>
</select>
<input type=submit value="Get">
</FORM>

Example kill form:
<FORM METHOD=GET ACTION="http://www.yourdomain.com/yourcgibin/usrchk.cgi">
<input type=hidden name="-H" value="1">
Reset port 
<input type=text name="-P" size="15">
on host
<select name="host">
<option value="Hazleton" selected>Hazleton</option>
<option value="Wilkes-Barre">Wilkes-Barre</option>
<option value="Bloomsburg">Bloomsburg</option>
<option value="Scranton">Scranton</option>
<option value="Tamaqua">Tamaqua</option>
<option value="Shenadoah">Shenadoah</option>
</select>
<input type=submit value="Get">
</FORM>


4) From crontab to do timed autokilling or piping to email address/text
   files

* Set up your groups in the config file so that the LAST host in the
  group has the correct <beforekill> number of ports. For any other host
  in the group set the <beforekill> number to any number higher that the
  ports on that box.
  Example:
  Group Hazleton has 2 hyperarc dialup servers, Both with 46 ports. You
  want to autokill when both boxes fill up. So, max ports for the group is
  92. That's the number you will kill at. You're config lines will look
  something like this..
  BOX: 192.168.1.1a !root junk 46 47 slot:1  slot:3  1 1 Hazleton Hazleton POP1
  BOX: 192.168.1.2a !root junk 46 92 slot:1  slot:3  1 1 Hazleton Hazleton POP2

* Set up a crontab entry for the usrchk program. I run mine every minute
  like this:
	* * * * * /path/to/usrchk -k group1 group2 group3
* Be sure to restart the cron daemon
* When autokilling, kill only by group name, not hostname.



the structure variables are defined as follows (IN NO PARTICULAR ORDER):
  char groupname[32];   /* location group this chassis is in          */ 
  char hostname[32];    /* ip and location designation letter, if */  
                        /* 1 chassis is used for several cities       */  
                        /* the letter breaks the city into a seperate */  
                        /* table and makes the identifier unique      */
  char username[32];    /* username to log in to the chassis          */
  char password[32];    /* password for said username                 */
  char name[32];        /* Table header if output is in HTML          */
  int  linestotal;      /* how many total available lines on this box */
  int  beforekill;      /* how many lines should be active before we start
			   killing users past KILL_TOTAL */
  char startport[15];   /* for hiperarc, the slot we're in to search */
  char lastport[15];    /* up to what port/slot do we want to check? */   
                        /* for hiperarc this is the slot immediately */   
                        /* after the last slot we want to check  i.e. */  
                        /* to check up to including slot 15, set the */ 
                        /* lastport at slot:16                       */ 
  int  sortTime;        /* 0 - sort by port, ascending         */
                        /* 1 - sort by session time, ascending */
  int  type;            /* 0 - netserver        1 - hiperarc */


Please fire off some email to me if you find this program useful.

Anthony J. Biacco
thelittleprince@asteroid-b612.org