Mimic Version 1.4.2 : README

Contents
********

Overview
Terminology
How it works
Setting up Mimic
Options
Known bugs
Changes
Copyleft

Overview
********

Mimic is an installation tool for automated installation of pre-packaged
programs and patches on IRIX-systems. Mimic uses the installation tools 
provided with the OS in order to keep the installation database consistent.
Using Mimic in conjuction with a distributed filesystem a large number of 
computers can use a single software repository to automatically install new 
software. The only thing the system administrator has to do is upload the 
software distributions to the repository and register the software 
components to be installed in a global selection file.

Mimic was written for use with AFS (Andrew File System), but also works well 
with NFS.

Terminology
***********

The terminology used in this document tries to follow the terminology used 
in the SGI documentation. A software package supplied in the format used by 
the SGI installation tools is referred to as a product. A product is made 
up of one or more subsystems, a subsystem is the smallest piece of software 
that can be installed. A software group is one or more subsystems grouped 
together in the Mimic selection files. A label is a name for a group, an 
active label means that the label has been defined and the group is 
eligible for installation.

How it works
************

A global selection file specifies the software subsystems to be installed 
on the machines using it. Subsystems can be grouped together in the global
selection file using labels and the machines that uses that file can 
selectively install such groups by defining the labels that apply. The 
global selection file also specifies in which directories the actual 
software product files reside. 

Mimic is intended to be run as a cron job with a suitable interval. Each 
time Mimic is run it reads a local configuration file (default is 
/etc/mimic.local.conf). The local configuration file contains the path to 
the global selection file as well as the active software group labels. The 
global selection file pointed to by the local configuration file is scanned 
and the software subsystems in the active groups are tentatively selected 
for installation. The versions(1M) program is then called to determine which 
subsystems are already installed, those subsystems are then removed from the 
tentative selection. An inst(1M)-readable selection file containing 
installation directives for the remaining subsystems is then created. 
Finally inst(1M) is run with the created selection file as input. Each run 
produces a log file (default /tmp/mimic.log) with the output from the 
inst-program. 

Setting up Mimic
****************

Setting up Mimic entails creating the software repository, a global 
selection file and a local configuration file.

The global selection file
-------------------------

The default name of the global selection file is mimic.global.conf and its 
path is specified either directly to Mimic or in the local configuration file.
The global selection file can contain the following directives:

%ifdef <label>		- Declares the beginning of a software group
%ifndef <label>		- As above only if <label> is undefined
%endif			- Declares the end of a software group
%inst_root <path>	- Specifies the root path to the software repository 
			  tree
%inst_path <path>	- Specifies the current path from which to get the 
			  software packages. This path can be absolute 
			  (starting with /) or relative to the root path 
			  (starting without /).
%include <filename>	- Reads the contents of file <filename> as a part 
			  of the global selection file.
i <subsystem>		- Select <subsystem> for installation
r <subsystem>		- Select <subsystem for removal
f <subsystem>		- Force selection of <subsystem> for installation, 
			  ie <subsystem> will not be pruned from the final 
			  selection even if it is already installed. This is 
			  useful for installing new versions of old software.

The minimal useful global selection file contains a %inst_root statement and 
a %ifdef-%endif pair surrounding a selection statement.

Probably the easiest way to set up a global selection file is to use 
inst(1M). Copy the software product files into a suitable directory to 
create the repository. Use the inst program to make a selection of 
subsystems and save them to a file using the admin:save command. Create a 
new file with a %ifdef-%endif pair and a %inst_root statement and copy the 
selection lines from the saved selection into this file.

The version information in an inst-generated selection file is utilized by
Mimic. Only new products or upgrades are selected for installation. If the
version number is missing it is assumed to be zero, this means that an upgrade
product will only be installed if it has its version number specified in the
Mimic selection file. Downgrades of products could occur anyway, for instance
when a previously uninstalled product is selected for installation and
it is a downgrade of another, already installed, product. This is because
Mimic has no way of figuring out these dependencies. Because of this, the
default is to disallow all downgrades, this an be overridden by using the -d
switch.

The local configuration file
----------------------------

The default name and location of the local configuration file is 
/etc/mimic.local.conf. The local configuration file can contain 
the following directives:

%dbdir <path>		- Specifies the path to the global selection file
%define <label>		- Activates a label
%exclude <path>		- Excludes a file or directory from the installation

The local configuration file needs to have at least one valid %define 
statement if anything is to be installed. Unless Mimic is always invoked 
with the path to the global selection file explicitly given a %dbdir is also 
needed.

The directory exclusion file
----------------------------

The directory exclusions file exists because of a bug in inst(1M). If 
filesystems are mounted read-only inst will die if it tries to write files 
in these filesystems. The only way that this can be prevented is by 
explicitly excluding all write-only directories from the installation. This 
is done by listing them in the directory exclusion file (default 
/etc/mimic.afsdirs.conf), one line per directory.

Options
*******

Mimic understands the following options

-version	  Prints version info.
-f		  Fakes an installation; this will create a selection file
		  (/tmp/mimic.inst) without calling inst on it.
-a		  Appends the log-info to the logfile without clobbering it.
-d		  Enables version downgrades; products that are selected for
		  installation but is a downgrade of some installed product
		  is allowed to be installed.
-r		  Enable removes; those products that are installed but not 
		  selected by the global configuration file are removed.
-ne		  No directory exclusions; the contents of the directory 
		  exclusion file will be ignored.
-rc <filename>	  Reads the directories to exclude from the installation 
		  from file <filename> instead of from the default file.
-F		  Force selection of all products; even already installed 
		  products will be selected for installation.
-il		  Inverse link skip; only install files in those directories 
		  listed in the directory exclusion file.
-re		  Forces install of all files; write all files to disk even 
		  if the product is already installed.
-c <filename>	  Reads the file <filename> as the global selection filename 
		  instead of the default name.
-R <path>	  Installs with <path> as root path.
-V		  Verbose mode, prints various diagnostic and debugging 
		  messages.
-VV		  Very verbose mode, print LOTS of diagnostic and debugging 
		  messages.


Known bugs
**********

The path used to read products when inst is invoked by mimic is static, ie
it is not pruned between runs. A sideeffect of this is that inst may
encounter several different versions of a product when looking in the
directories specified by this path. Unfortunately, inst can not be relied
upon to select the latest version of the product, rather it selects the
first one it finds for installation. This means that even if you have
version numbers in your selection file you might end up with an old
version of a product, or Mimic might try but fail to install the latest
version every time it is run. This can only be fixed by making sure that
there's only one version of a given product in the software repository at
any given time.

The code is pretty far from beautiful and understandable.

Changes
*******
Version 1.01 - 1.3
- Added support for version upgrades

Version 1.3 - 1.4
- Removed the verify and file check functionality, this simplified the code
  immensely and overlays now work since the package file names are now ignored.
- Added the %exclude directive to the local config file.
- Added the %ifndef directive to the global config file.

Copyleft
********

Mimic is written in Perl and may be changed to suit your needs
provided you follow the GPL (see below), although the code is 
admittedly rather disgusting. If you make any useful changes
please let me know so the original program may be improved.
If you want any useful changes made you can always ask for
them although there are no guarantees that I have the time
to make them.

Mimic was written by Per Ekman (pek@pdc.kth.se) at the Center for 
Parallel Computers at the Royal Institute of Technology in Sweden.

---

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

---