Adminlog
Installation Notes


This document is all you need in order to get your Adminlog system up and
running. You will get some valuable examples dealing with customization of the
software at your site. If you are an experienced user you may prefer to read 
the section "Quick Setup". If you want some more information you just continue
reading after the "Quick Setup".


Quick Setup
===========
1.	Make a new directory for the Adminlog system (PROG-PATH).
2.	Make a new directory for the data-files (LOG-PATH).
3.	Unpack the software into the directory PROG-PATH.
4.	Update the files 'adminlog.ini' and 'users.ini' to match your site's
	specifications.
5.	Create a new user-group that will use the system.
6.	Add the Adminlog-users to the new group.
7.	Change the file-permissions on directory LOG-PATH, so the Adminlog
	group and its members only will have read- and write permissions to it.
8.	Create scripts (.bat-files in DOS) that will start the Adminlog system
	in read- and writemode.
9.	Change the file-permissions on the scripts, so the new group only will
	have permissions to read and execute them.
10.	Test the system (use the flag '-v' to run in verbose mode).
11.	If you encounter any problems - please read below!


Creating directories
====================
We will need to create two directories - one for the program files (PROG-PATH)
and one for the database files (LOG-PATH). On many unix systems, there is a
default directory to add new applications, for example /usr/lpp, /usr/local or
/opt. Find a suitable location and create a new directory there by the command:

mkdir Adminlog

The other directory will contain the database files you and your fellow-
administrators will read and add. If you don't have any better suggestions,
you can create the directory in the PROG-PATH:

mkdir logs

Now you'll have a directory-structure similar to this:

/usr/local/Adminlog		(PROG-PATH)
/usr/local/Adminlog/logs	(LOG-PATH

If you run a DOS-based filesystem with drive letters, you must use paths that
are common to all Adminlog users, for example:

r:\system\adminlog
r:\system\adminlog\logs


Creating an Adminlog Group
==========================
In order to keep the system hidden for unauthorized users, we will need to 
create a new user-group, we can name it 'al', but check that 'al' isn't used
already! Consult the documentation for your system how to create a new group.
A group doesn't make much sense without any members. Add all users that will
use the Adminlog system by consulting the documentation for your system. 
Solaris systems may use 'admintool', AIX systems 'smit', Windows NT systems
'User Manager' and Novell NetWare 'syscon', for example.


Installing the Adminlog Files
=============================
You may have received Adminlog in a couple of different ways and medias -
diskette, tape or electronically by ftp or modem. Please refer to the section
below that meet your case.


From Diskette or Tape
---------------------
If you've got a unix system the software is put on the media by the 'tar' 
(Tape ARchive) command. To extract it to your filesystem do the following:

1.	Change directory to PROG-PATH.
2.	Consult your system documentation to find the path to the device that
	holds the media (diskettes are often /dev/fd0 and tape may be
	/dev/nrmt0, /dev/rmt/0n or /dev/rmt0.1).
3.	Insert the diskette or tape.
4.	Extract the archive by the following command: 'tar xvf <device>', 
	where <device> is the path to the device that holds the media.
5.	Eject the diskette or tape.
6.	Now, go to section "Configuring the Software".

The DOS version of Adminlog is only distributed on tape in very rare occasions
so the following will do in most cases:

1.	Change directory to PROG-PATH.
2.	Insert the diskette into a suitable diskette-drive (usually A:).
3.	Extract the archive by the following command: 'A:install'.
4.	Eject the diskette.


From another directory
----------------------
If you received the Adminlog system electronically you are probably quite 
familiar with system commands, but check that you've copied the following files
into PROG-PATH:

adminlog.<version>	Adminlog binary file (executable)
adminlog.ini		Program configuration file
arch.txt		Info about <version>s
users.ini		Authorization file

The <version> applies to unix binaries and the DOS binary is named 
adminlog.exe.


Configuring the Software
========================
The first step is to find out which binary-file that matches your architecture
if you run a unix system. If you run the DOS-version you just skip this step.
The information is stored in the file arch.txt. Write the file on your screen:

cat arch.txt

On the screen you will see the name of a binary file and a description of the
architecture it was compiled on. There may be one or more lines in this file.
If you're not sure which to use you may check your architecture by these
commands:

uname -a
arch

Some binaries are shipped in two versions for the same operating system and 
computer architecture. One is called 'adminlog.<version>.static' and the other
one 'adminlog.<version>.dynamic'. The first works in all cases and the size is
noteably larger because program libraries are statically linked into the binary
itself. The latter (dynamic) uses external libraries that usually are installed
on a unix system and these libraries are linked at run-time. That's why the
binary file is very compact. Try the dynamically linked version first and if it
complains over missing libraries switch to the statically linked version.
You'll probably find a matching binary, otherwise you may try them one by one.
When you know which one to use you may rename the binary file by this command:

mv adminlog.<version>[.static | .dynamic] adminlog


Editing adminlog.ini
--------------------
You must edit your adminlog.ini to match your site's needs. There are comments
in the distributed adminlog.ini that may give you more clues. Each line that
isn't a comment or a blank line consists of a PARAMETER and a VALUE. Below
follows parameter by parameter.


LICENSEE
This is the owner of the software license and it's typed on the media. If
you've got a demo-copy, it'll by 'DEMO<date>', where <date> is the expiration
date of the demo. If you run in demo-mode, Adminlog will halt a couple of
seconds and beep. Also, there may be a maximum of ten (10) log-entries in the
database. If you want to try the demo-version a little more than ten writes you
just remove the existing entries. Example:

LICENSEE	DEMO940331


LIC-KEY
There is only one key that matches the LICENSEE and the version of Adminlog 
you've got. The LIC-KEY is printed on the shipped media. If you've got a demo-
copy the LIC-KEY will follow the distribution-files. Example:

LIC-KEY		0013-0139-3867


PROG-PATH
This is the path, where your Adminlog binary and the users.ini file must
reside. Unix example:

PROG-PATH	/usr/local/Adminlog

DOS example:

PROG-PATH	r:\system\Adminlog


TMP-PATH
TMP-PATH is a path to a writable directory, which is private to each user.
However, TMP-PATH is not used directly by Adminlog in this version. Unix
example:

TMP-PATH	$HOME/

DOS example:

TMP-PATH	f:\temp


LOG-PATH
This is the path to the database directory. Unix example:

LOG-PATH	/usr/local/Adminlog/logs

DOS example:

LOG-PATH	r:\system\Adminlog\logs


USER-VAR
In order for Adminlog to function, you must set an environment variable to the
user's login-name. In unix systems it may be 'LOGNAME' or 'USER' and in DOS you
must set this either in all workstations or in the network operating system's
login-script. In some modern (unix) systems the login-name may be retrieved
internally by Adminlog. This is stated as a note in the file 'arch.txt' and in
these cases the USER-VAR parameter isn't used. Example:

USER-VAR	LOGNAME


EDITOR
When a user writes a new entry to the database, this parameter will be used to
start a text-editor. Note that you can't write switches or parameters to the
editor here. If you want to supply arguments to your editor, you must make an
alias or script (.bat-file in DOS) that does this for you. The editor must take
a filename as an argument. Unix example:

EDITOR		emacs

DOS example:

EDITOR		edit


PAGER
This is the command that envokes a pager for browsing entries in read-mode and
your newly created entry in write-mode. DOS supplies a pager by name 'more',
but if you find a better one, you may wish to alter this value. In many unix
systems, there is a program called 'less', which many people prefer. Example:

PAGER	more


Editing users.ini
-----------------
This file must reside in the same directory as the Adminlog binary, i.e. PROG-
PATH. Adminlog will use this file to map a login-name (pointed to by 'USER-
VAR', see the "Editing adminlog.ini" section above) to a full-name. This is
very useful if one physical person, say James Mason, logs in as 'root' and
'jamesm' interchangably. The other members are not interested in the login-name
just who actually wrote the message. James Mason isn't interested in logging in
as 'jamesm' just to write a log when he did something as 'root'. Each line
consists of a login-name followed by one to three strings that make up the
corresponding "full-name". For James Mason we may want to write these entries:

#login-name	full-name
root		James Mason
jamesm		James Mason

In users.ini, you may write as many comments (preceded by "#") or blank (empty)
lines as you wish, which is quite useful if you have a large number of members
in the Adminlog group to keep track of. Example:

#login-name	full-name

#super-user:
root		James Mason

#administrators:
pradm1		Liza Min Elly
pradm2		Frank IE Boy
backer1		James Mason
backer2		James 007 Bond
backer3		James 007 Bond

#users:
jamesm		James Mason
lizame		Liza Min Elly
jamesb		James 007 Bond
frankieb	Frank IE Boy

If all the login-names to the left are members of the 'al' group, Frank IE Boy
may use the Adminlog system regardless of if he has logged in as 'pradm1'
(Administrator of Printer 1?) or 'frankieb'.


Examples on Site Tailoring
==========================
There are a couple of additional files in the distribution and they will be
extracted in a subdirectory called 'examples'. If you extracted the files into
/usr/local/Adminlog, you'll find these files in /usr/local/Adminlog/examples.
All unix distributions share the same examples, but the DOS distribution is a
somewhat different.


Unix Distribution
-----------------
The example-files are a collection of "shell-scripts" (/bin/sh), but if there
is a "hacker" in you, you might want to translate them to a more fancy script-
language.


readlog
#!/bin/sh
# readlog - read log-entries from an Adminlog database

# Assuming HOME points to the user's home-directory
if [ -f $HOME/.adminlog ]
then
	/usr/local/Adminlog/adminlog $HOME/.adminlog -r $1
else
	/usr/local/Adminlog/adminlog /usr/local/Adminlog/adminlog.ini -r $1
fi

# end of readlog


writelog
#!/bin/sh
# writelog - write a log-entry to an Adminlog database

# Assuming HOME points to the user's home-directory
if [ -f $HOME/.adminlog ]
then
	err=`/usr/local/Adminlog/adminlog $HOME/.adminlog -w $1`
else
	err=`/usr/local/Adminlog/adminlog /usr/local/Adminlog/adminlog.ini \
	-w $1`
fi

# Send a mail to the users that are listed in file \
  '/usr/local/Adminlog/.alusers.
# The file .alusers may look like this (one line!):
#
# jamesm, lizame, frankieb
#
# This implies that 'jamesb' doesn't want notification.
#
# The file '/usr/local/Adminlog/.al.message' is a file with a suitable \
  message in
# it, for example (may contain one or more lines):
#
# I wrote a new Adminlog-entry!
#
# NOTE:
# You may think of a better way to notify users on your site!
#
# If you don't want to send any mail to anybody, just comment out the following
# lines with "#":

# Notification:
if [ err -eq 0 ]
then
	mail -s "New entry to Adminlog" < /usr/local/Adminlog/.al.message \
	< /usr/local/Adminlog/.alusers
fi

# end of writelog


DOS Distribution
----------------
The example-files are a collection of "batch-programs" and some of the
functions are Novell NetWare specific.


readlog.bat
rem # readlog.bat - read log-entries from an Adminlog database

rem # Assuming HOME points to the user's home-directory
if exist %HOME%\adminlog.my goto LOCAL

:GLOBAL
r:\system\adminlog\adminlog r:\system\adminlog\adminlog.ini -r %1
goto NEXT

:LOCAL
r:\system\adminlog\adminlog %HOME%\adminlog.my -r %1
goto NEXT

:NEXT
rem # insert own stuff here:

rem # end of readlog.bat


writelog.bat
rem # writelog.bat - write a log-entry to an Adminlog database

rem # Assuming HOME points to the user's home-directory
if exist %HOME%\adminlog.my goto LOCAL

:GLOBAL
r:\system\adminlog\adminlog r:\system\adminlog\adminlog.ini -w %1
if not errorlevel 0 goto FAIL
goto NEXT

:LOCAL
r:\system\adminlog\adminlog %HOME%\adminlog.my -w %1
if not errorlevel 0 goto FAIL
goto NEXT

:NEXT
rem # insert own stuff here:

:NOTIFY
rem # This is Novell NetWare specific, please remove if you don't run NetWare \
or
rem # if you don't want to notify others.
rem #

rem # Notification:
rem # We are sending the quoted message to all members of group 'al'.
SEND "A new Adminlog-entry" TO GROUP al


:FAIL
rem # end of writelog.bat


Error Tracing
=============
If you for some reason don't get the Adminlog program to work, we will try to
guide you in tracing the problem in this section.


Unix Specific Errors
--------------------
This section refers to unix-problems only when you try to run the program.


Permission denied
If you get the message 'Permission denied' or something similar, there may be
two reasons for this; you simply haven't got the right permissions to the file,
because it's owned by other user or group or (the second reason) the binary
file is not set to be executable. If you are the super-user (root) you can set
the right permissions on the binary file like this:

chown root <binary>	set user 'root' to be the owner
chgrp al <binary>	set group 'al'
chmod ug+rx <binary>	allow owner and group to read and execute
chmod o-rwx <binary>	deny all other users access, not mandatory

The parameter <binary> refers to the Adminlog binary (usually 'adminlog').


Exec Format Error
If you get a message similar to 'zsh: exec format error: <binary>' or
'<binary>: cannot execute binary file', you most likely chose the wrong
binary file for your system architecture - try another one! The text of the
message is shell-specific and the two examples above comes from 'zsh' and 'sh',
respectively.


Exit Codes from the Adminlog Program
====================================
The Adminlog program returns different return-values (or errorlevels in DOS),
that you may wish to catch. In a unix shell-script you may store the value in a
variable like this:

err=`adminlog adminlog.ini -r`

In DOS, you can't store the value directly, but you may make a test on the
errorlevel (virtually the same thing) and set a variable accordingly like this:

adminlog adminlog.ini -r
if errorlevel 9 set err=9
if errorlevel 5 set err=5
if errorlevel 3 set err=3
if errorlevel 2 set err=2
if errorlevel 1 set err=1
if errorlevel 0 set err=0


Then you can use the variable to track a problem. The meaning of the exit codes
are listed below:

Exit Code
Meaning (one of the following)

0 Program executed normally

1Invalid DEMO date

1 DEMO copy has expired (by date)

1 Cannot find ini-file (the first argument)

1 Cannot find users.ini (must reside in PROG-PATH)

1 Cannot open a log-file (the one you tried to add)

1 Error starting an external editor

1 Error writing an entry on the screen

1 Invalid LIC-KEY

2 Wrong arguments passed to the Adminlog program

3 Corrupt ini-file (one or more of the lines aren't recognized)

5 Authorization failed (the value of USER-VAR doesn't match any of the 
  entries in users.ini)

9 There are already ten (10) entries in the database (when running in demo 
  mode)



Running in Verbose Mode
-----------------------
If you want to debug an installation that doesn't work, you may add the switch
"-v" at the end of the command-line like this (this is the only optional
switch):

adminlog adminlog.ini -r -v

This will make the Adminlog program to run in "verbose mode", where the program
prints out messages on the screen what it's doing.


Evaluation Copy
===============
In order to get the feel of what Adminlog may give you and your corporation,
there are evaluation copies available for all platforms. If you get an
Evaluation Copy it'll expire on a certain date and you are only admitted to put
ten entries into the database, but on the other hand you get the chance to
evaluate the program "at home". If you later decide to get a "real" licence you
only have to change two lines in the configuration file and off you go! You
don't have to re-install the product. The Evaluation Copies are free of charge
(a small fee for covering the distribution costs may occur) and will be
available at various ftp-sites, bbs'es and dealers.


More Information
================
If you have any questions or just want more information you may contact
JoS-Ware by mail or fax (stated below).

JoS-Ware Comp Tech
Box 739
220 07 LUND
SWEDEN
Fax: +46-46-188445


Document Date	94-02-16
Adminlog: Installation Notes
Copyright  1994 JoS-Ware Comp Tech
Document Number	al-in1
