**************************************************************
*      This is the README file for Digital-Phalanx 1.10       *
***************************************************************

Before proceeding please read the LICENSE file and DISCLAIMER.

You should find in the directory Digital-Phalanx-1.10 the 
following files present. 

 
823543      ----    License Key
DISCLAIMER  ----    A Disclaimer 
INSTALL     ----    An Installation Script
LICENSE     ----    A License Statement
dbm_add     ----    A Utility to add Authorised users and Domains
dbm_drop    ----    A Utility to 'Drop' Users who are no longer authorised
dbm_list    ----    A utility to 'list' the 'Authorisation' file
dbm_rem     ----    A Utility to 'remove' 'Un-Authorised' domains 
phalanx     ----    The Digital-Phalanx daemon 
phalanx.conf.dist   The phalanx's configuration file
phalanx.message     The message that is written to offending terminals.


***************************************************************
*      PRE-REQUESETES                                         *
***************************************************************

1) The installation should take place as the superuser.
2) /usr/bin/perl5 should point to the perl5 binary or..
   should be a link to it.
3) The following perl5 modules are required...
   Config;
   AnyDBM_File;
   Socket;
   If any of the above are missing they should be obtained from CPAN, and
installed
   before continuing.
4) The phalanx will install and reside in /usr/local/phalanx  
   this may be changed, but TRANS-EURO I.T LTD cannot be held responsible
for
   any issues that may arise by changing the location of phalanx.
5) You have read the LICENSE 
6) You accept the DISCLAIMER, Digital-Phalanx is an extremely powerful
tool, 
   and if mis-configured can cause mayhem.. proceed from this point only
   if you feel you have the suitable technical skills to (1) grasp what
the phalanx
   is doing and/or (2) you can restore order should mayhem strike..

If you cannot or are un-willing to accept points 1 - 6 then please refrain
from installing
the phalanx, and remove its components from your system. 


Only If you accept points 1-6 continue..


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

Run the installation script this will create the directory
/usr/local/phalanx,
copy the components of the system, and set the required file permissions,
These are basically only Superuser access to read/write or execute. 

./INSTALL 


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

Edit the configuration file phalanx.conf 

You should substitute the E-mail address of your support team in the 

variable              CONTACT=
for example           CONTACT=support@mydomain.com 

also the VARIABLES defining the paths  to the commands w, sendmail,
kill, ps
may need to be configured to point to the correct locations.

TTY_PREFIX 
This is the prefix required to make your terminal 
for example p1 a full device filename 
p1 == /dev/ttyp1 
so in this case TTY_PREFIX would be /dev/tty

PSFLAGS may also need to be altered, they are set to use BSDI -aux by
default, 
some system may use other options to retrieve a full list of users and
process numbers.

Whilst 'testing' and setting up keep the KLEVEL variable to 1 
                                         --------------------

Being constantly messaged is annoying if the phalanx is mis-configured,
but at least
you can still find the pid of the daemon and kill it. Higher levels will
result in
sessions being kill -9'ed.  As can be seen the scope for mayhem is great..
remember
the pre-requisit list!

A kill -HUP on the phalanx's pid will cause it to re-read its
configuration.

Question:
What do I do if there is no 'w' command on my system..??

Answer:
You can simulate the output of the w command by employing a combination
of who and sed and awk. Or a perl script.
The out put of your script should be in the format..

<dummy line1>
<dummy line2>
user   tty number  domain 

and your W= variable in phalanx.conf should point to your local script.


DO NOT START THE PHALANX UNTIL YOU HAVE READ THE NEXT SECTION!!!!!!


Administration of the authorised telnet database 
------------------------------------------------

There are four utilities to assist the sysadmin or security officer
to maintain the authorised telnet session database.

They should be invoked form with the /usr/local/phalanx directory 

These are...

dbm_add
-------  

dbm_add <authorised_username> <domain_pattern_to add>     

This will add a username of a 'cleared' telnet user into the database,
specifying
that they are cleared from a specific domain 'pattern' To find out what
this pattern 
is do a 'w' to find one of their sessions. Cut and paste or just copy this
pattern as
the second parameter to the command for instance..

dbm_add support ns1.mydomain.com 

the domain pattern will typically be only 16 characters long. And the
'truncated'
16 character domain name should be committed to the database.

The above command 'clears' support to login from ns1.mydomain.com 



dbm_drop
--------

usage dbm_drop <username_to drop>   

This command will 'drop' a particular username from the database.. ie they
will no longer
be cleared to telnet to your server from any machine.

dbm_drop badman 




dbm_list
--------

dbm_list results in output of the following format..

User support is authorised from :- ns1.mydomain.com;pop3.mydomain.com
User auser is authorised from :- ns1.mydomain.com;
User buser is authorised from :- ns1.mydomain.com;pop3.anotherdomai

NOTICE how the domain name for buser is truncated at 16 characters just as
it would
appear in 'w' listing.                                   



dbm_rem     
--------

usage dbm_rem <authorised_username> <domain_pattern_to remove> 

This command is the reverse of dbm_add and removes clearance from a
particular
domain pattern. 


All of the database manipulation commands will generate an E-mail to the
user specified
in CONTACT= in your phalanx.conf configuration file.




Starting the phalanx
--------------------

Once you have built up a list of cleared telnet users and cleared domain
patterns 
you may start the phalanx. With KLEVEL=1 you can refine your database
until your
sessions are recognised. 

The phalanx startup command can be placed in an appropriate system startup
file for  residence within your server, from startup. 

If you have any questions please E-mail 

                phalanx@lon1.dpe.net

Do not install the phalanx unless you have understood these instructions
100%.
It is Trans-Euro I.T Ltd's intention that this be an invaluable aid to
server security, 
and not a means of system wide mayhem. Hence do not activate the phalanx
if you are the 
least bit apprehensive. the decision is yours.. 

These instructions may also be found at http://www1.dpe.net/phalanx the
Digital-Phalanx homepage. 


