GrpAdmin Software Installation and Operations Manual
ABSTRACT
This document describes the overall organization of
the GrpAdmin software suite. It includes procedures
for initial installation and continuing maintenance.
1. Introduction
GrpAdmin is software suite that allows unprivileged users to man-
age Unix group ownerships and memberships. It is basically orga-
nized into four major components:
1. An SQL database that contains various types of group informa-
tion.
2. A library of routines that access the DB in a secure manner.
3. User interfaces (command line, X-Windows and Web) built on
top of the access library.
4. A set of utility procedures for (re-)creating the GrpAdmin
database and extracting DB content into the flat-file format
used by Unix programs.
Each of these components will be discussed in some detail. Con-
stant reference will be made to various elements of the source
code, which is organized as given in Table 1.
+---------------------------------------+
| Table 1 |
+--------------+------------------------+
| Directory | Content |
+--------------+------------------------+
|build | compiled code |
+--------------+------------------------+
|config | main configuration |
| | file |
+--------------+------------------------+
|doc | documentation source |
| | files |
+--------------+------------------------+
|src/bin | user interfaces, |
| | including Web CGI |
| | script |
+--------------+------------------------+
|src/lib | DB access library, |
| | authentication rou- |
| | tines |
+--------------+------------------------+
|src/utils | DB initialization and |
| | maintenance scripts |
+--------------+------------------------+
|src/wish | X-Windows GUI library |
+--------------+------------------------+
|src/wish/help | on-line help files for |
| | GUI. |
+--------------+------------------------+
Now is a good time to explain a particularly important file: con-
fig/config.sed. GrpAdmin is written in three programming lan-
guages, C, Tcl/Tk8.0 and Perl5.0. Symbolic pathnames, contants,
etc. within the code are maintain by using sed(1) as a prepro-
cessor for all source files. Config.sed contains such configura-
tion definitions in the form of substitutions for strings of the
form @@some_name@@. Relevant "@@" variable names will be men-
tioned in appropriate contexts below. You may want to edit con-
fig.sed as we go along.
2. Basic Requirements and Preliminary Database Setup
GrpAdmin uses Kerberos for authentication. You must have a work-
ing Kerberos KDC to use GrpAdmin. It is assumed that you are
familiar with creating Kerberos principals and dealing with
keytab files.
It is also assumed that you have a working knowledge of managing
PostGres databases and that you have a DB configured to use Ker-
beros authentication installed and working. You need the FQDN of
the machine hosting the database server to define the
@@GRPDB_HOST@@ string in the config file. Also need the PostGres
programming libraries libpq and libpgtcl installed wherever
GrpAdmin software will run.
Determine the name of the database that will hold the tables used
by GrpAdmin. It if does not exist then create it now. Use the
database name to define the @@GRPDB_NAME@@ config string.
Create the Kerberos principal used by GrpAdmin to authenticate
itself to the DB. The name of this principal (default is
grpadmfe) defines the @@GRPFE_ID@@ config string. Create a Post-
Gres account for that name using the PGSQL createuser utility.
Create a PostGres-DB group called unixgroup_owners containing the
GrpAdmin principal and any real users who will have complete
read/write access to the tables comprising the group DB. Extract
the GrpAdmin principal keytab and make in readable only by a sin-
gle Unix user; this user name (default is postgres) should be
used to define the @@GRPADMIN_SUID@@ config string.
Much of the above paragraph is related to how GrpAdmin does
authentication and authorization, so it is worth delving into
that topic in greater detail. GrpAdmin requires that all users
present Kerberos credentials. It uses those credentials to
acquire a ticket for the database service and opens a connection
to the server. The server attempts to validate the ticket as a
form of mutual authentication. If it cannot do so it returns an
error and GrpAdmin exits. Even if the ticket is good, the server
will still (in general) reject the connection since the user will
not have a DB account entry. If this error is returned, GrpAdmin
knows that the user has presented valid credentials and opens a
separate connection to the DB server using the @@GRPFE_ID@@ iden-
tity and associated keytab. From that point on, GrpAdmin acts as
a proxy for the user, enforcing authorization restrictions which
are resident in the group DB information. The ability to make
changes to DB content are a function of the @@GRPFE_ID@@ iden-
tity. Thus the keytab used to generate credentials for that
identity must be protected. That is why the extracted keytab
file is readable only by @@GRPADMIN_SUID@@; all user interfaces
run as suid programs to that user.
2.1. Finalize Configuration of GrpAdmin
There are several other parameters that must be defined before
the GrpAdmin software can be compiled:
@@INST_DIR@@
Where the programs, help files, etc. are to be installed. The
default is /usr/local/.contrib/GrpAdmin.
@@LINK_DIR@@
Where to put symbolic links to user interface executables.
Default: /usr/local/bin.
@@DUMP_DIR@@
The directory where GrpAdmin periodically creates "flat file"
versions the group database. These files are intended for use
by standard Unix text utilities. Default: @@INST_DIR@@/Files.
@@GRPFE_KT@@
The full pathname to the keytab file for the GrpAdmin princi-
pal. Default: @@INST_DIR@@/data/grpadmfe.kt.
@@PGSQL_PATH@@
Base path where PostGres is installed. Default:
/usr/local/pgsql.
@@MAX_LOGGRP@@
Maximum number of login groups allowed per user. This number
does not include the group associated with the user in the
/etc/passwd file. Default: 13.
@@MIN_GID@@
Minimum numeric group id to allocate; group ids less than this
number will not be given to new groups. Existing groups can
have group ids less than this number. Default: 1024.
@@MAX_GID@@
Maxmimum numeric group id. Default: 65535.
@@WEB_SERVER@@
FQDN of the machine which will host the Web interface CGI
scripts. Default: none.
@@HTDOC_ROOT@@
Base URL of the directory where the CGI scripts will live.
Default: none.
Once all configuration parameters have been determined, simply cd
to the src directory, type "make" and then, if no errors, "make
install".
2.2. Seeding The Database
Note: This section is applicable only during the initial instal-
lation of GrpAdmin. If you have been using GrpAdmin and are
attempting some sort of DB disaster recovery, see Section X.Y.
Initial content of the GrpAdmin database is provided by existing
/etc/group file(s). However, the DB maintains additional seman-
tic content (such as group ownerships and expiration dates). You
may wish to provide that content when initially seeding the DB.
1. You must be sure that one of the initial group files contain
a group called "GrpAdmin". Members of this group are consid-
ered GrpAdmin administrators and have the ability to create
new groups, delete existing groups and users, change the own-
ership of any group, etc.
2. You can establish initial groups ownerships. This is done by
inserting a comma-separated list of user names in the second
(password) field of the group definition. E.g.,
agroup:owner1,owner2,owner3:666:member1,member2,member3...
3. You can establish initial group expiration dates and primary-
secondary group relationships by creating a separate group con-
trol file with this information. The format of the file is:
groupname groupid expiration-date primary-group-name
Expiration dates use the syntax 'mm-dd-yy[yy]'. Use the
string '{}' to specify a null value for an expiration date or
primary group. E.g.:
junk2 1064 04-01-2003 {}
junk2_1 1048 {} junk2
blah 666 12-31-01 blahprimary
After making any adjustments to the /etc/group file informa-
tion copy the group file, the group control file (if any),
and the shell script build/initgrpdb.csh to the PostGres
server machine. You must initialize the DB from the server
since the installation procedures use the SQL 'copy' command
for data entry.
To run the initialization procedure on the server, make sure that
you have to ability to create tables within the @@GRPDB_NAME@@
database. Then set a shell environment variable DBTMPDIR to a
directory where you have write access. Finally, invoke the init-
grpdb.csh as:
initgrpdb.csh <initial-group-file> <initial-group-file> \
[<group-control-file>]
At this point you should be able to run one of the GrpAdmin user
interfaces to confirm that the DB has been populated.
3. Maintenance Operations
GrpAdmin requires period maintenance commands to be run, usually
under the aupices of the cron(8) daemon.
3.1. Unix Group File Creation
As mentioned, GrpAdmin periodically converts the group DB content
to flat files for use by standard Unix utilities. This is accom-
plished by the script updateugfiles.tcl. It is meant to be run
as a cron(8) job on a single primary machine from which all other
nodes retrieve copies of the updated group information. Upda-
teugfiles checks for changes in the group DB and creates new
files if necessary, leaving them in the @@DUMP_DIR@@ directory
defined in the configuration file. The entire GrpAdmin suite must
be installed on the machine where updateugfiles runs, but that
machine need not be database server itself. The resulting Unix-
format files are assumed to migrate from the update server to
other machines by locally defined means.
The frequency with updateugfiles is runs depends on how rapidly
group information should be propagated to participating machines,
which in turn is a function of how often those machines poll for
changes. Under normal circumstances, new files will be created
only if DB changes are detected. However, the -force option can
be used to create new files even if no modifications are appar-
ent. Updateugfiles must be run with a real and effective root
uid; you cannot run the program from a {k}su shell.
GrpAdmin creates standard /etc/group files for distribution to
Unix machines. It also creates files that can be used to recre-
ate the database content in case of disastrous failure. These
files are:
group_updatelog
Contains the raw SQL commands used for DB updates, the identity
of the person who did the update and time it was done.
group_control
Expiration dates and primary-secondary group relationships.
group_member
User name, group name and login group indication for all group
members.
group_owner
Group ownership information.
group
Unix format group file; does not include group memberships for
non-login groups.
group.all
Unix format group file containing login and nonlogin group mem-
berships.
All of the files are maintained using the rcs(1) revision control
system so that DB content can be reconstructed from any point in
the past.
3.2. Group Expiration
The script bin/expire.con is intended to be run once a day. It
checks the group DB for expired groups and deletes them. These
deletions appear as normal GrpAdmin commands in the update log.
Thus updateugfiles will construct new Unix group files the next
time it is run.
4. Web Interface Installation
To Be Supplied.
5. Appendix -- Further Reading
Further details regarding the GrpAdmin design and terminology can
be found at:
http://www.cs.washington.edu/lab/GrpAdmin/facguide.html
GrpAdmin User's Manual
http://www.cs.washington.edu/lab/GrpAdmin/grpframe.html
GrpAdmin Design Description
http://www.cs.washington.edu/lab/GrpAdmin/index.html
Further links to GrpAdmin user interface manual pages, etc.