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

1
Invalid 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: Product Brief

Adminlog: Product Brief

Copyright  1994 JoS-Ware Comp Tech

Document Number	al-pb1


