




INSTALL - An Installation System For UNIX
Version 1.0

Stuart Herbert, S.Herbert@Sheffield.ac.uk









ABSTRACT

The UNIX operating system, more than any other, has long enjoyed a tradition
of developers creating software which is freely available to anyone who cares
to download it.  The Free Software Foundation is an organisation which is
dedicated to furthering this tradition.

However, installing such software is often a process done by hand.  This
paper introduces INSTALL, a software solution which can be distributed with
software to provide an automated means of installing software.  This solution
has been placed under the GNU General Public License.

Copyright (c) 1994 Stuart Herbert

Permission is granted to copy and distribute verbatim copies of this
paper provided the copyright and this permission notice are preserved
on all copies.

Anyone seeking to distribute material derived from this paper should contact
the author for permission to do so.




All trademarks are the property of their owners.

Conventions In This Paper

References to sections are contained inside parenthesis, and are referenced
by number; e.g. (1.2) references section 1.2 of this paper.

References to the annotated bibliography are contained in square brackets,
and are referenced by number; e.g. [1] references reference number 1 of the
annotated bibliography.

Brief Glossary

  o  distribution
	A collection of files which are released as a single entity;
	normally as some form of tape archive (.tar file).
  
  o  file hierarchy
  	All files and sub-directories contained within a directory.

  o  image
  	Any file which can be executed by the user; normally resulting from a
	compilation of source code.
	
  o  manifest
	A list of the contents of a distribution.

Introduction


Status Of This Paper

This is the first draft of this paper, which includes an implementation of
INSTALL.  This paper will be distributed initially with The System Manager,
and to certain USENET news groups and ftp sites, in an effort to gauge public
reaction, and future revisions are expected to follow.


Organisation Of This Paper

  o  1. Background
		An outline of the problems which currently exist, and the
		objectives which the solution aims to address.
		
  o  2. Architecture
  		An detailed explaination of the architecture of the solution.

  o  3. Defined Functions
		The functions supplied to a manifest file are explained, and
		the differences of behaviour between the functions supplied
		by INSTALL and by INFO are noted.
		
  o  4. Annotated Bibliography
  		A (limited) list of sources for further information.

Content List


1.      Background.

1.1     General Issues.
1.2     Specific Problems.
1.3     Criteria.
1.4     History.
1.5     Proof-Of-Concept.


2.      Architecture.

2.1     Overview.
2.2     Manifest Files
2.3     INSTALL
2.4     INFO
2.5     REMOVE
2.6     Other Considerations
2.6.1   Inherant Flaws
2.6.2   Strategy For Success

3       Defined Functions.

3.1     Overview
3.2     Function List.
3.2.1   author()
3.2.2   comment()
3.2.3   depend()
3.2.4   dir()
3.2.5   endinfo()
3.2.6   file()
3.2.7   link()
3.2.8   log()
3.2.9   pause()
3.2.10  require()
3.2.11  root()
3.2.12  target()
3.2.13  title()
3.3     Error Codes.

4       Annotated Bibliography

4.1     Overview
4.2     [1]  : Bourne Again SHell (/bin/bash) Manual Page
4.3     [2]  : The GNU General Public License
  		
1.	Background.


1.1	General Issues.

This paper documents INSTALL, a freely distributable software solution which
aims to provide an automated way for users and system administrators alike to
install third-party software onto a UNIX system, and to remove it afterwards.

INSTALL is aimed squarely for adoption by software developers.  It provides
tools for creating an installation manifest, for actually installing the
software, and for removing the software at a later date.

The motivation behind INSTALL comes from a number of areas

  o  The availability of free implementations of UNIX means that the number of
     system administrators who have only a rudimentary knowledge of
     maintaining a UNIX system is very much on the increase.

     This cross-section of the UNIX population is in need of assistance.
     USENET newsgroups which offer that assistance, such as
     comp.os.linux.help, often fail to deliver simply because of the sheer
     number of people seeking such help.

  o  Experienced system administrators often spend a significant proportion of
     their time either installing or removing software.

     This process can be protracted, tedious, and prone to error, especially
     removal; software which has long enjoyed a place on a file store may
     consist of files which are not obviously connected with the software,
     and which may escape the attention of whoever is removing the software.

  o  Users often download and use software which meets their specific needs;
     the local system administration may not desire to install the software
     for all users.

     On large systems, if the system administrators were to install every
     piece of software their users wanted, they would have little time for
     anything else.  By providing a means for users to install software in
     their own filestore, and for the system administration to be aware of
     software so installed, a good working compromise can be achieved.

One can also look to non-UNIX platforms, such as Microsoft Windows, where
limited installation systems are supplied with distributions, for further
evidence to support the proposal of an automated installation solution. 

This paper, and the proposed solution, arose out of development work on an
administration tool aimed at users of Linux, a free UNIX implementation.  It
represents several months of work by several local administrators, each with
several years worth of experience, on examining issues related to the
administration of systems supporting up to several thousand users.

As proof-of-concept, the solution has been integrated into the aforementioned
administration tool to provide a means for third party developers to release
'drop in modules' for that tool.  It is expected that feedback from that
project will form the bulk of evidence used in the evolution of the solution.


1.2	Specific Problems.

The following points were considered of primary urgency, and are listed in no
particular order.

  o  On systems catering for the diverse needs of a large number of users,
     centrally installed software adds to the number of files contained on
     the /usr file hierarchy.  It is currently left to administrators to
     provide local methods of keeping track of any software added to the /usr
     file hierarchy.
     
     One strategy to minimise the impact of adding software is to ensure that
     such software is placed inside the /usr/local file hierarchy.  However, 
     considerable amounts of software require files to be placed outside of
     this hierarchy, in /etc, or elsewhere.
     
  o  When adding files to the /usr hierarchy, one is very much dependant on
     being supplied with sufficient documentation to make sure that one knows
     when specific files must be placed in specific locations.  Documentation
     (perhaps rightly) often assumes an understanding of where certain types
     of file naturally belong; those whose background knowledge is not as
     thorough as anticipated are at a disadvantage here.
     
     One can indignantly claim that this is a problem which should be solved
     by training, rather than by software.  However, the availability of free
     implementations of UNIX, sold on CD-ROM at low cost and high volume,
     means that there is a whole new generation of system administrators who
     do not have access to experienced personnel from who they can learn.
     
  o  It can often arise that a distribution will rely on prior installation
     of other, unrelated distributions.  In these cases, one is dependant on
     being supplied with sufficient documentation to indicate that this so.
     
  o  When preparing a distribution for release, writing documentation
     (especially documentation which provides a measure of 'hand holding') is
     a tedious task which one is often tempted to leave out.
     
In addition, the following problems arise when considering any implementation
of a software solution.

  o  Any solution will only be a success if it is adopted by a large number
     of third-party developers.  (History shows that the technical merit of a
     solution is very much a secondary requirement for success.)

  o  The solution must prove portable between different flavours of UNIX.  A
     large amount of new software is targetted at several UNIX implementations,
     with one distribution including support for all target UNIX flavours.
     
  o  The solution must prove highly flexible, being able to provide batch
     automation and interactive use.

  o  It should be practical to include the solution with distributions.
  
These issues play a significant role in the design of the final solution.


1.3	Criteria.

From the above problems and considerations, the following criteria was
decided upon.

  o  Provide a solution to all of the problems in (1.2) which does not place
     undue burdens upon software developers.
     
  o  Provide a proof-of-concept release, which will permit validation of the
     suitability of the solution.


1.4	History.

The adoption of the World Wide Web by the University Of Sheffield as the
means to implement a Campus Wide Information Service brought about the
reality that, to remain effective, the local user group was required to
branch out from Novell Netware into the world of UNIX.

Due to the nature of the sources of funding, the user group was put into the
position whereby it could only secure suitable hardware to be a UNIX server
at a date after the group was due to lose its experienced administration
team.  In addition, the group was forced to chose a free implementation of
UNIX, which meant that the incoming administration team would be almost
completely without local help.

In response, the outgoing administration team sought to develop a framework
which would allow for the development of user-friendly software which could
walk an inexperienced user through many tasks.  The framework allows for
'modules' to be added and removed easily, and it was this 'drop in' concept
which lead to the requirement for a proper installation system.

In addition, there was concern at the ability of the incoming administration
team to maintain a UNIX system while they accumulated sufficient knowledge
and experience.  While this concern cannot be met in the short term, by
developing a solution for the long term, we can help ease the pressures
faced in future years during the learning period.


1.5	Proof-Of-Concept.

As mentioned in (1.1), the current emphasis is upon proving the concept.  The
System Manager was chosen as a suitable test, becase

  o  The System Manager requires the ability to install and remove
     distributions in an easy and efficient manner.

  o  The System Manager is targeted at software developers for a popular
     implementation of UNIX (Linux).
     
  o  The System Manager is targeted at a large user base which is more used
     to DOS than to UNIX, thus allowing a test of how useful the solution
     actually is to the very users who need it most.

Feedback from The System Manager will form the first body of evidence which
will be used in the evolution of the solution.  If this test proves
satisfactory, the solution will be positioned in the UNIX community as a
stand-alone, viable proposition.

2.	Architecture.


2.1	Overview.

The solution consists of the following.

  o  A manifest
  
     This is a list of what files require installing where.  To provide as
     much flexibility as possible, the manifest is a script for the /bin/bash
     shell, which makes use of supplied functions to perform the installation.
     
     The manifest is supplied by the author of the distribution.
     
  o  INSTALL
  
     This is a script for the /bin/bash shell, which defines the functions
     used within a manifest.  It is also responsible for creating the list of
     installed files, which is used by the REMOVE script.
     
  o  INFO
  
     This is a script for the /bin/bash shell, which defines the functions
     used within a manifest.  Because many functions are defined to do
     nothing, INFO is suitable for examining a manifest file without having
     to perform an installation.
     
  o  REMOVE
  
     This is a script for the /bin/bash shell, which uses the information
     created by INSTALL to reverse an installation at a later date.

This architecture was inspired by the way Makefiles have been extended to
become Imakefiles, and particularly the Linux kernel configuration script by
raymondc@microsoft.com.

Imakefiles provide a set of variables and functions which are used to perform
the conditional compilation; the C preprocessor is drawn upon to provide part
of the conditional execution.

In contrast, the Linux configuration script simply exports a set of defined
functions, and calls a second script to perform the actual configuration.
This approach has greater simplicity than using the C preprocessor, and can
be adapted to provide greater flexibility.

That flexibility comes from the ability to redefine the behaviour of the
functions in (3) depending upon the task at hand.  The approach taken has
been to define at most two different behaviours, where one is always a
no-operation.  This means that programmers are not subjected to having the
functions proving useless because their behaviour cannot be relied upon.

As explained in (2.2), the special function `endinfo` has been provided to
allow the programmer to assume what is actually happening.


2.2	Manifest Files

A manifest file is a shell script for the /bin/bash shell, which is called
from within INSTALL, INFO or any other such utility.  Because the file is
called using the `.` command, the file need not have its permissions set as
executable.

When called with no parameters, a manifest file should attempt to use the
functions definied in (3) to install a distribution.  The behaviour of a
manifest file when called with command line parameters is undefined.

A manifest file will generally follow the following structure.

  o  Call `title` and `author` to identify the distribution.

  o  Make repeated calls to `comment` to display some information about the
     distribution.

  o  Call `endinfo` to tell INFO to stop parsing the manifest.  All code
     after a call to `endinfo` can assume that an installation is to take
     place.
  
  o  Test for any other distributions which are required, using `depend` and
     `require`.  If these tests fail, then add a message to the log file, and
     perhaps exit.
  
  o  Compile any source code, format any documentation or execute any other
     processes required to create the files to be installed.

  o  Call `target` to determine where to install any files.
  
  o  Create any directories which are required.
  
  o  Install files and symbolic links.


2.3	INSTALL

INSTALL is a script for the shell /bin/bash, which defines and exports the
functions defined in (3), and then uses the `.` command to call the specified
manifest files.  When called with no parameters, INSTALL displays a list of
manifest files available for installation, and then exits.

INSTALL looks for manifest files in the directory './.MANIFEST'.  By changing
directory, one can therefore obtain different lists of manifest files.  This
strategy was chosen to allow each distribution to supply an independant set
of manifest lists.

One should include INSTALL in a distribution, and place it in the top
directory created by extracting files from the distribution.  For example, if

      `tar zxf INSTALL.tar.gz`
      
creates

      INSTALL/
      
and places all files inside 'INSTALL/', then the following should be included
in a distribution.

      INSTALL/INSTALL			(a)
      INSTALL/.MANIFEST/		(b)
      
where (a) is the INSTALL script definied as part of this solution, and (b)
contains the manifest files used to install the distribution.  The user can
then

      `cd INSTALL`
      `INSTALL`
      
to obtain a list of manifests to choose from, and then

      `INSTALL [-f] <manifest> [ [-f] <manifest> ...]`
      
to actually install, where the switch '-f' ensures that any existing files
are overwritten (default behaviour is to skip files which already exist).

Once the installation process is complete, a list of installed files is saved
in the user's home directory '~/.INSTALLed/' for use by REMOVE at a later date.
The contents of this directory can also be examined by system administrators
to build a list of software installed by users; popular packages can then be
considered for installation centrally.


2.4	INFO

INFO is a script for /bin/bash, which defines and exports the functions
defined in (3), and then uses the `.` command to call the specified manifest
files.  When called with no parameters, INFO displays a list of manifest
files available for examination.

INFO defines most of the functions in (3) as no-operations, and provides the
function `endinfo` to allow a manifest file to indicate that it has finished
providing the user with information about itself.

Like INSTALL, INFO looks in the '.MANIFEST/' directory for any available
manifest files.

While INSTALL should be included in a distribution, INFO, because of its more
limited application, is only recommended for inclusion where the distribution
supplies many manifest files.


2.5	REMOVE

REMOVE is a shell script for the /bin/bash shell which attempts to remove an
INSTALLed package.  During the installation process, INSTALL creates a file
inside '~/.INSTALLed' which is a list of all files and directories which
REMOVE should attempt to remove for each distribution.

REMOVE parses each specified file twice.

  o  The first pass identifies files to be removed.  Files are only removed
     if they are not listed in any of the other files inside '~/.INSTALLed'.
     
  o  The second pass identifies directories to be removed.  Directories are
     only removed if they are found to contain no files.

If the superuser wishes to REMOVE distributions installed by other users, he
or she should use the `su` command to become that user, and then use REMOVE.

As with INSTALL, it is recommended that REMOVE is included with all
distributions.


2.6	Other Considerations

2.6.1	Inherant Flaws

The danger of using automated installation is that the procedure is open to
abuse, and this is a serious problem for the superuser.  However, consider
the following.

  o  There currently exists numerious ways in which any malicious intent
     could be realised; a trojan horse could be placed within a distribution,
     the 'install' target of a Makefile could cause damage, etc. etc.
     
     INSTALL is by no means unique in having this flaw.
     
  o  The supplied INSTALL script could itself be modified to act maliciously.
     
     This can be prevented by having centrally installed the INSTALL, INFO
     and REMOVE scripts.  As the current working directory should NEVER be
     placed anywhere but last within the PATH, this prevents the problem.
     
  o  System administration normally includes the requirement of writing shell
     scripts, and /bin/sh compatible shells are generally considered the most
     suitable for the job.
     
     This means that it can be considered reasonable for most administrators
     to read manifest files before using INSTALL.  It is general recommended
     practice that the superuser NEVER executes anything from a non-trusted
     source unless they have examined it first.


2.6.2	Strategy For Success

In (1.2), it was noted that work is required to ensure the success of INSTALL.

  o  The shell /bin/bash was chosen because it is available across many
     platforms, helping to ensure compatability (as opposed to /bin/sh, which
     can differ in capability depending upon the vendor).
     
  o  The solution has been placed under the GNU General Public License [2],
     to ensure that the solution is freely available and has unrestricted
     distribution.

  o  The initial release of the solution has been targeted at users of a free
     implementation of UNIX.  The users of Linux are normally willing to
     examine any new software presented to them (this is perhaps due to their
     nature; most run Linux as a pastime, and they therefore have more time
     to spend examining new software than would otherwise be the case).

  o  If the solution proves popular, an attempt should be made to freely
     transfer the copyright to the Free Software Foundation.
     
     It cannot be denied that software distributed by the Free Software
     Foundation enjoys success on many UNIX platforms, and this may prove to
     be the key in securing the long term use of INSTALL et. al.
     
3	Defined Functions.


3.1	Overview

The solution provides a series of shell functions which can be used to
perform specific tasks.  The functions below are definied for INSTALL and
INFO.


3.2	Function List.

The following functions are available inside MANIFEST files.

  o  author
  o  comment
  o  depend
  o  dir
  o  endinfo
  o  file
  o  link
  o  log
  o  pause
  o  require
  o  root
  o  target
  o  title


3.2.1	author()

This function takes two parameters.

  o  Author's name
  o  Author's address
  
A copyright message, crediting the author, is displayed.


3.2.2	comment()

This function takes two parameters.

  o  A text string
  o  'y' if output to be logged
  
The text string is echoed to the screen, and is also added to the log file if
the second parameter is a 'y' or a 'Y'.


3.2.3	depend()

This function takes two parameters.

  o  A switch to a `test` [1] statement
  o  A file or directory name
  
The specified test is performed upon the specified file or directory, and a
value of 254 is returned if the test fails.

NOTE: This function does nothing inside INFO.


3.2.4	dir()

This function takes three parameters.

  o  The name of a directory
  o  The permissions for the directory
  o  'y' if the directory should be considered for REMOVEing
  
The specified directory is created (and any leading directories if they do
not exist) and its permissions are set to those specified.  If the specified
directory already exists, the operation is aborted, and a value of 255 is
returned.

If the third parameter is 'y' or 'Y', the directory is added to the list of
files which REMOVE will attempt to remove.  REMOVE will only remove a
specified directory if it has managed to empty the directory first.

NOTE: This function does nothing inside INFO.


3.2.5	endinfo()

This function requires no arguements.

This function exits the shell script.

NOTE: This function does nothing inside INSTALL.


3.2.6	file()

This function takes three arguements.

  o  A file to copy.
  o  The destination name of the file.
  o  The permissions of the destination file.

The named file is copied as the destination file, and its permissions are set
as specified.  If the destination file exists, the operation is aborted, and
the value 255 is returned.

NOTE: This function does nothing inside INFO.


3.2.7	link()

This function takes two parameters.

   o  A file or directory which is to be linked.
   o  The destination of the link.
   
The symbolic link is created.  If the specified destination exists, the
operation is aborted, and the value 255 is returned.

NOTE: This function does nothing inside INFO.


3.2.8	log()

This function takes two parameters.

  o  A text string.
  o  'y' if the output is to be echoed to the screen.

The text string is added to the log file, and if the second parameter is 'Y'
or 'y', the string is echoed to the screen.

NOTE: This function does nothing inside INFO.


3.2.9	pause()

This function takes no parameters.

The user is prompted to press ENTER or RETURN to continue, or to press ctrl-c
to abort.  If the user presses ctrl-c, this function does not return.

NOTE: This function does nothing inside INFO.


3.2.10	require()

This function takes one parameter.

  o  A utility which is required by the distribution.
  
The existance of the utility is tested for, first by seeing if the file
exists, and then by seeing whether the utility can be found within the PATH.
If both tests fail, the value 254 is returned.


3.2.11	root()

This function takes no parameters.

If the user is not root, or equivalent, the function does not return.

NOTE: This function does nothing inside INFO.


3.2.12	target()

This function takes two parameters.

  o  The recommended hierarchy where the distribution should install to.
  o  The sub-directory inside the recommended hierarchy where the
     distribution should install to.

This function sets no less than four variables.

  o  TARGETBIN is the directory where any images should go; this directory
     will normally be within the user's PATH.
     (Default is /usr/local/bin if root, or ~/bin otherwise)
  o  TARGETDIR is the directory where the distribution should go; this may or
     may not be the directory recommended by the call to this function.
     (Default is $1/$2 if root, or ~/$2 otherwise)
  o  TARGETLIB is the directory where library files should go.
     (Default is /usr/local/lib if root, or ~/lib otherwise)
  o  TARGETMAN is the directory where manual pages should go.
     (Default is /usr/local/man if root, or ~/man otherwise)

This function may be altered by local system administrators to suite local
conditions, and during this function the user may or may not be prompted to
recommend any target directory.

NOTE: It is currently left to the MANIFEST script to ensure that these
directories exist.

NOTE: This function does nothing inside INFO.


3.2.13	title()

This function takes one parameter.

  o  A text string.
  
The text string is prominently displayed on the screen.


3.3	Error Codes.

Several functions return error codes, the meaning of which is always the
following.

  o  255
  	The function discovered that a specified file or directory already
	exists, and that the operation was therefore aborted.
	
	The user is informed that the specified file or directory has been
	'skipped', and an entry to that effect is also added to the
	installation log file.
	
  o  254
  	The function discovered that a specified file or directory does not
	exist, and that the operation was therefore aborted.
	
	The user is informed that a 'warning' has been generated, and an
	entry to that effect is also added to the installation log file.
	
  o  1
  	The function discovered that a specified test succeeded.
	
	The user is informed that the specified file or directory has been
	'found', but no entry is added to the installation log file.
	
  o  0
  	The function completed its specified action successfully.
	
	When creating files, directories, and symbolic links, the user is
	informed that such entities have been 'added', but no entry is added
	to the installation log file.
  
4	Annotated Bibliography


4.1	Overview

The references mentioned here should be consulted as extra sources of
information.

4.2	[1]  : Bourne Again SHell (/bin/bash) Manual Page

The shell /bin/bash is an sh-compatible shell which has been chosen as most
suitable for use in the solution.  If one wishes to adopt the solution and
include INSTALL and manifests with distributions, one must be familiar with
programming for /bin/bash.

4.3	[2]  : The GNU General Public License

This license, which at the time of writing stands at version 2, grants
certain rights to users of software, and also ensures that those rights
cannot be curtailed in any manner.
