GASH 1.0 INSTALLATION
18 September 1994
ARL:UT Computer Science Division
Dean Kennedy & Jonathan Abbey
---------------------------------

GASH is easy to compile, but difficult to get set up for real use.  Proper
use of GASH requires that several databases and control files be configured
for your environment.  See the DATABASES file for a description of these
databases, and CONTROL_FILES for a description of the control files.

Essentially, the control files control how GASH behaves, and the databases
hold the actual data that GASH manipulates, and that gets distributed to
the network environment through NIS and DNS.

Two important compilation parameters to be set in the source Makefile
are GASHDIR and LOCKFILE.  GASHDIR will control where GASH looks for
its datafiles.  On our master server, we have set GASHDIR to
/var/yp/gash/files, LOCKFILE to /var/yp/gash/gash_lock.  We place the
GASH sources in /var/yp/gash/sources.

         /var/yp/gash ----------
        /     |      \           \
     files  gash_lock sources  scripts

In addition to the files mentioned in DATABASES and CONTROL_FILES,
GASH has a database Makefile and a set of perl scripts which are run
after each GASH editing session in which changes are made.  The
database Makefile is placed in GASHDIR. While the perl scripts can be
placed anywhere, it is recommended to place them in a scripts
directory alongside GASHDIR and the source files directory. The
locations for these directories must be set in the top section of the
each Makefile with SRC being the same as GASHDIR and the location of
the perl scripts being YPDBSRC.

We place our log subdirectory under GASHDIR, as GASHDIR/logs.  Defs.h
contain definitions that specify the placing of the log, and of the GASH
autologs, which are generated each night during nightly processing.


Compiling Gash
--------------

The first step in compiling gash is to decide where you want all
related files to go.  As mentioned, you need to place 2 or 3 directies
to hold the gash source code files, gash databases, and NIS/DNS
generation scripts.  The sample structure distributed uses 3
directories, but at ARL we place the database files and the scripts in
the same directory.  Move and name the sample directories where you
want them to be.  We run GASH directly out of our source directory
(/var/yp/gash/sources).

Once the directories are placed where you want them to stay, you will
need to edit some files to reflect these choices.  First, edit the
gash compilation makefile.  Set GASHDIR and LOCKFILE.  Also, choose
the appropriate CC and CFLAGS options for your site.  If you want to
run GASH for initial setup, you don't need to worry about running GASH
setuid, and you can leave the chmod 4755 line commented.  If you want
GASH to run setuid (which you do if you are to have non-root
administrators), uncomment the comment line after the gash build
instructions in the source Makefile.  Run makedepend on the gash
sources makefile.  Set all of the variables in defs.h.  This file contains
a bunch of define's which you must edit to set up GASH for your
environment.  Run the make.  GASH should be built with a few warnings
in the checkpasswd, pwck, and libmain source files.  There obviously
should not be any errors.


Control File Setup/Starting Gash
--------------------------------

Before gash can run, a number of files must be in place.  Edit the
following control files in your GASHDIR, based on the sample files
that we provide:

shell_paths
networks_by_room
motd
mail_control
internet_assignment

The networks_by_room file contains a map of your facility or
facilities.  GASH uses the networks_by_room control file to assign
internet addresses to systems based on the network or networks that
are physically connected to the room the system is to be placed in.

The internet_assignment control file contains a list of system types,
and a desired subrange of a class C network in which you wish such systems
to be assigned IP addresses.  For example, our internet_assignment
file looks like this:

Servers:1:149
Workstation:11:149
PC:11:149
Macintosh:150:249
Slip:1:249
Terminal Server:149:1
Gator Box:249:150
Router:254:250

Whenever a system is created or modified, the GASH administrator will
have be asked which kind of system it is.  An internet assignment will
be assigned out of the free IP addresses on the network or networks
that the system is connected to, and on the range specified in the
internet_assignment file.  For instance, a new Macintosh on subnet
116.224.176 will be given the first free internet address between
116.224.176.150 and 116.224.176.249.

The following empty files should already be in your GASHDIR

user_info
aliases_info
group_info
netgroup
auto.vol
auto.home.default
hosts_info
pending_actions

You need to create an admin_info file in your GASHDIR.  This
will contain a definition for the priviliged supergash account, and
the root account, which has no special privileges, but which shares
the supergash password.  You must have entries for both supergash
(you'll really need supergash's su capabilities) and for root (which
must be defined for autogash processing).  Note that there are two
example admin_info files: admin_info.groupmask and
admin_info.nogroupmask.  If you are using the ARL_SPECIFIC option,
which uses group name masking to control group access, then copy
over admin_info.groupmask to GASHDIR with the name admin_info.  Most
sites will not be using group name masks, however, in which case you
should use the file admin_info.nogroupmask instead.

Read over the README.scripts and all of the associated scripts in the
scripts directory.  You will have to configure things so that these
scripts interact properly with your NIS and DNS master servers.

If you get all this done, you should be able to log in as root, using
the password "GashWorld".  At this point, it would be a good idea to
assign a better password for root using the gash passwd command.  su
to the supergash account (su by itself), and run passwd to set the
GASH password for supergash.  The supergash password defined in the
sample admin_info file is also "GashWorld".  You'll definitely want to
change that.

Of course, there isn't much data in the gash files yet, so there is
not much to do while running gash.  Never fear...


Database Initialization
-----------------------

You won't be able to immediately start using GASH.  It took us a few months
to get all the data from our various divisions reconciled and put into the
GASH databases.  We did much of the database generation by hand, and you
will likely need to as well.  It will be somewhat easier for you,
because we have eased some of the particular restrictions and
conventions that we have adopted.  In particular, if you do not build
GASH with USE_SOCIAL_SECURITY and USE_EXPANDED_GROUPS, the user_info
and group_info databases will be strictly identical to the standard
passwd and group files.

Even though you can use your vanilla passwd and group files with GASH,
you will need to do a number of things to prep the other databases.

1) You must make sure that your user and group population are
separable according to numeric id.  That is, all users that you want
to be under the control of a particular GASH administrator must fall
within a specific uid range.  Likewise with your groups.  At ARL:UT,
our various subdivisions needed to shuffle uid's and gid's around so
that each research group and administrative division had all their
UNIX users and groups within contiguous blocks.

2) Each user in the user_info database must
have a corresponding entry in the aliases_info database, of the
following form:

broccol:jonabbey, broccol:broccol@arlut.utexas.edu

where the first field is the GASH user name, the second is a comma
separated list of names by which the user will receive e-mail (with
the first entry being the outgoing name for the user's e-mail), and
the third field being the complete e-mail address where the user's
email should be ultimately delivered.

3) Assuming you are starting with your own group and passwd files for
group_info and user_info, then next step is to define some gash
admininstrators.  To do this, start gash as root, using the password
"GashWorld", or whatever you have set the password to.  su to the
supergash account (su by itself), and run passwd to set the GASH
password for supergash.  The supergash password defined in the sample
admin_info file is also "GashWorld".  You'll definitely want to change
that.  If the user_info file has users in it, you can now use cadm to
create some gash administrators.  Be sure to make an administrator
account for yourself.

4) Gash files tend to be rather interdependent.  To completely finish
users, first you will need to define the volumes which contain their
home directories.  To define volumes, systems must be defined for the
volumes to exist on.  So the next step is to define all of the UNIX
systems which are to contain disks with home directories.  Use gash
and csys to define these systems.  As mentioned ealier, to put systems
in the hosts_info database you have to have the networks_by_room and
internet_assignment control files set up.

Note that GASH will assign its own notion of IP addresses to systems
and interfaces that you create through csys.  You will need to be able
to go into the hosts_info file and correct the IP address for the
systems or interfaces that you have created with csys.  For help with
this, check out our web server (the URL is in the INTRODUCTION file),
or send e-mail to pug@arlut.utexas.edu or jonabbey@arlut.utexas.edu.  The
hosts_info is the most complex, gnarly file in the GASH system, and it
is very easy to goof things up.  Just changing IP numbers is not too
difficult, though you have to be careful not to duplicate IP addresses.

5) Next you will have to define volumes in the auto.vol database.  Use
cvm to generate these volumes.

6) Each user in the user_info database must have a corresponding entry
in the auto.home.default database, defining the volume that the user's
home directory should be placed on.  Now that you have volumes
defined, you can use mam to put all of the user entries into the
auto.home.default database.


Autogash
--------

Once you get things reasonably up and humming, you need to create a root
cron job that will run autogash nightly.  We do this every night at 1:30a.m.;
note that autogash processing can easily take 30 minutes or more.


The End
-------

Sorry, this is really messy, but we haven't had the time or resources
to spend a lot of effort on the bootstrap stuff once we got past that
point ourselves.

