Installation guide for the AAFID2 prototype


There is no automatic installation procedure for now. That will come
at some later time.

SYSTEM REQUIREMENTS
===================

- A Unix system. The current AAFID release has been tested on Solaris
  2.5.1 and a little on Linux (RedHat 5.2 and 6.0), but it will
  probably run without a lot of problems on other versions of Unix, as
  long as you can run Perl on them.

  Sorry, it does not run on Windows NT yet. We are working on porting
  it, but it is not ready yet.

  We are very interested in your experiences if you run AAFID(tm)
  under Linux or any other non-Solaris version of Unix. Please email
  aafid-feedback@cs.purdue.edu with your comments!

- Perl 5.004 or later.

- Make sure your Perl installation has the following extensions
  installed (they come with the distribution, but may not be
  installed):

  IO (which includes IO::File, IO::Handle, IO::Socket, etc.)

  Socket (which includes Socket.pm)

  Opcode (which includes Safe.pm. Notice that this version of Safe.pm
      does not seem to be the same as the Safe package available from
      CPAN. You should use the version included in the Opcode
      extension)

  --------------------------------------------------------------------
  NOTE: To see if a package is present in your Perl installation,
        execute the following command:
	perl -e 'use PackageName'
	replacing "PackageName" with the full name of the package you
	are looking for. For example: perl -e 'use Data::Dumper'.
	If you get no output, the package is present. If you get an
	error message, the package is not installed, or could not
	be located in the standard paths.
  --------------------------------------------------------------------

- The following non-standard packages, which you can get from
  http://www.perl.com/CPAN/ (some of them may be already present in
  your Perl installation):

  Data::Dumper. Newer versions of Perl (after 5.004_71) include
      Data::Dumper as a standard package, you may want to check first
      to see if you already have it.

      URL: http://www.perl.com/CPAN/modules/by-module/Data/

  Log::Topics. The Log::Topics package is included in the AAFID
      distribution, under the classes/Log/ subdirectory. This
      directory contains the Log::Topics package as found in CPAN, but
      with a patch that fixes a spurious warning and some incorrect
      behavior.

      You do not need to install Log::Topics, it is included with
      AAFID.

      In case you are curious, the patch applied to the Topics.pm file
      can be found in misc/Topics.patch.

      The Log::Topics package is included with explicit permission
      from its author, John Williams (J.A.R.Williams@aston.ac.uk).

      URL: http://www.perl.com/CPAN/modules/by-module/Log/

  Resources. The Resources package is included in the AAFID
      distribution under the classes/ subdirectory. It is the
      Resources package as found in CPAN, but with a couple of patches
      to make it work better with AAFID.

      You do not need to install Resources, it is include with AAFID.

      In case you are curious, the patch applied to the Resources.pm
      file can be found in misc/Resources.patch.

      The Resources package is included with explicit permission from
      its author, Franco Callari (FrancoC@GeometrixInc.com).

      URL: http://www.perl.com/CPAN/modules/by-module/Resources/

  MD5

      The MD5 package implementes the computation of MD5 hashes.

      URL: http://www.perl.com/CPAN/modules/by-module/MD5/

  Tk (Perl/Tk) for the GUI. Make sure you have the is the Perl/Tk
      package, not the TkPerl module. Get the latest version of Tk402*
      or Tk800*, depending on your version of Tk (4.2 or 8.0).
  
      URL: http://www.perl.com/CPAN/modules/by-module/Tk/

INSTALLATION
============

Please read the following steps carefully.

- To be able to use the AAFID system at this point in its development,
  you are expected to be fluent with Perl, because many of the
  internals of the system are still visible.

- Choose an account under which the system will run. It may be a
  regular user account, or a dedicated one. Do _not_ use root.

- In the current version of AAFID2, the Monitor needs to be able to
  execute remote commands in the hosts where Transceivers are to be
  started. Thus, the account under which the system will run has to be
  able to execute remote commands among all the machines where the
  system will run. The remote execution of commands can be done using
  rsh, ssh, or any other mechanism you have available, as long as it
  can be accessed from a command line. Decide on which mechanism you
  want to use, and see below for instructions on how to configure it.

- Choose a directory under which you will install the
  distribution. For example, /usr/local.

- Unpack the distribution under that directory:
	 cd /usr/local
	 gunzip -c /some/directory/aafid2.tar.gz | tar xvf -
  The last command will create a directory aafid2 with the structure
  described in the file aafid2/doc/notes/Directory_hierarchy.txt.

- Take some time to read the documentation under aafid2/doc. It will
  make it easier for you to use the programs.  The suggested reading
  order is:

  To get started:

  doc/papers/architecture_report.ps
      General introduction and design of the architecture. Read at
      least Section 2.
  doc/notes/Filters.txt
      Description of the filters mechanism, which is absent from the
      architecture paper.
  doc/notes/Directory_hierarchy.txt
      Description of the directory structure of the AAFID2
      distribution.
  doc/papers/implementation_report_draft.ps
      Description of the AAFID2 implementation (somewhat outdated)
  
- Put the directory aafid2/classes of the distribution in the PERLLIB
  environment variable of the account that will run the programs, so
  that the variable is set whenever the account logs in, and also
  whenever a command is executed remotely using the mechanism you
  decided in the first step. For example, if the account is using
  C-shell, you may put the following in its .cshrc file:
     setenv PERLLIB /usr/local/aafid2/classes
  
  NOTE: Make sure that the variable is assigned even for
	non-interactive sessions. For example, many .cshrc files have
	the following (or something similar) at some point:
	    if ( ! $?prompt ) exit
	Make sure you assign to PERLLIB before that point in the
	file.

- Make sure that the PERLLIB variable also contains the paths needed 
  to find all the non-standard packages mentioned under 
  "System requirements".

- Repeat the previous 3 steps for all the machines where you want the
  system to run. You may want to install it in a directory that is
  NFS-mounted to all the machines so that you do not have to install
  it multiple times. Just make sure that the PERLLIB variable is set
  correctly in all the hosts for the account that will run the
  system.

- To configure the system, read the following documentation:

  doc/notes/Config.txt
      Description of the configuration mechanism.

  The above document also describes the standard configuration
  parameters. The two that you may want to specify in config/Monitor
  are RemoteExecCmd and StarterExecCmd, to suit your remote-execution
  mechanism. In the config/ subdirectory you will find sample
  configuration files (with commented sample parameters) and some more
  information. But read Config.txt first. Really.

- Edit the files under the bin/ directory and change their first lines to 
  reflect the location of the perl executable in your system.

- Read the following documentation:

  To run the program:

  doc/notes/How_to_run.txt
      General description of how to run entities.
  doc/notes/How_to_use_GUI.txt
      How to use the Graphical User Interface.

  To develop new agents:

  doc/papers/users_guide_draft.ps
     Contains extensive information and a tutorial on how to write
     agents.
  doc/notes/How_to_use_filters.txt

  To develop new filters:

  doc/papers/users_guide_draft.ps
  doc/notes/How_to_write_filters.txt

This documentation will keep improving as the distribution matures,
but we need your feedback. Please feel free to send comments, bug
reports, questions or any other kind of feedback to
aafid-feedback@cs.purdue.edu. Also, see the MAILLIST file for
information on joining the AAFID users discussion list.

Enjoy,
--The CERIAS AAFID team (see the file CREDITS for details)

AAFID is a trademark of the Purdue Research Foundation.  All rights
reserved.
