AMIE Installation and Configuration

This document describes how to install and configure AMIE. It assumes that you have access to the CVS repository at repo.teragrid.org[1]. It also assumes that you will be using the reference implementation interface to your local account management data. It is recommended to have at hand the companion documents The AMIE Model and Implementing AMIE.

Overview

The AMIE software has two major components. One is the core software. The core contains the functionality to read, write, and validate the xml files; to send and receive these xml files between two sites; to track the state of AMIE transactions; and to interface with the local account management database to retrieve and store the data required by the xml files.

The other is the local implementation. The local implementation is not provided with the core software. It must be written by the local site. However, the core specifies the interface that must be implemented and provides a reference implementation of that interface which moves data between AMIE and an intermediate database. If a site chooses to use the reference implementation[2], then it must implement the movement of data between its local account management database and the reference implementation intermediate database.

The current implementation uses ssh (with public/private key authentication) to transfer data between sites. From the perspective of a given site, the site itself is called the “local site” and remote site is called the “remote site.”

Sites need to create users as gateways to the local implementations and for ssh authentication and data transfer. These users are known respectively as the “local user” and the “remote user.”

A restriction is that any one user can only communicate with a single user on a remote system. It is not possible for a single user to communicate with more than one remote user. Thus if a site needs to send account management data to multiple sites it needs to create a user for each remote site[3] (and the remote site needs to create a corresponding user).

Required Software

Java 1.4

AMIE requires java 1.4. It has been tested under versions 1.4.1 and 1.4.2. Java 1.4.2 can be downloaded from

Perl 5

AMIE has been developed and tested under perl 5.6.0. It requires the following modules:

XML::Parser

XML::Writer

XML::XPath

Mail::Send

File::Basename

Data::Dumper

DBI (and related drivers, e.g. DBD::Sybase, DBD::Pg, etc)

SSH

The current AMIE transfer process uses ssh.

rbash

To secure the transfer process as much as possible, the restricted version of the bash shell is used. Make sure that the bash shell is installed and that a link from rbash to bash exists.

AMIE Installation

This document assumes that the AMIEcore software will be installed in /amie.[4]The installation basically exports the core software from the CVS repository at repo.teragrid.org.

cd /

umask 022

setenv CVSROOT :ext:[email protected]:/var/lib/cvs

setenv CVS_RSH ssh

cvs export r HEAD amie

This will create /amie with the following sub-directories: docs, lib, testbed, schema, scripts, and referenceimplementation.

Make sure that the scripts in the scripts sub-directory are executable.

cd /amie/scripts

chmod 755 amie.pl

chmod 755 validate-amie.pl

chmod 755 amie.sh

User creation and configuration

This section describes the creation and configuration of a single “local user”. It is assumed that the “remote site” will create a “remote user” that corresponds to this “local user.”

The “local site” and the “remote site” must agree on site names and user names. In this document, it is assumed that the “local site” is abcand that the“remote site” is tg; that the “local user” is amieuser and that the “remote user” is tg-abc; and that the home directory for amieuser is /home/amieuser.[5] Make sure that /home/amieuser is on a local file system.[6]

It is also assumed that the reference implementation described in Implementing AMIE will be used.

As root:

  • Create an entry in /etc/passwd for amieuser with home dir /home/amieuser and shell /bin/rbash (or wherever rbash lives). It is advisable to not allow login using a password.
  • umask 077
  • mkdir/home/amieuser
  • cd /home/amieusr
  • cp /amie/scripts/profile .profile
  • cp /amie/scripts/bashrc .bashrc
  • mkdir bin amielocal
  • cp /amie/scripts/amie.sh bin/amie
  • chmod +x bin/amie
  • cd amielocal
  • mkdir xfer logs conf
  • cp /amie/reference-implementation/conf/amie.config-template conf/amie.config
  • cp /amie/reference-implementation/conf/db.config-template conf/db.config
  • chown R amieuser/home/amieuser
  • ln s /amie/reference-implementation/lib /home/amieuser/amielocal/lib[7]

There are 3 files that need to be modified under /home/amieuser:

  • bin/amie

This script sets $PATH, $AMIE, and $AMIELOCAL and runs the AMIE transfer script

Follow the instructions in bin/amie.

PATH should be set to include java, perl, ssh, and a few other Unix commands.

AMIE should be set to /amie.

AMIELOCAL should be set to /home/amieuser/amielocal.

  • amielocal/conf/amie.config

This configuration file tells AMIE what the “local site” is, what the “remote site” is, how to send files, etc.

local-site.nameabc

remote-site.nametg

send.abc.tgssh tg-abc@remotehost amie –r

timeout.abc.tg1 # minutes[8] (default = 2)

admin.emaillocal-admin-user

response.timeout120 # minutes[9]

xml.validation[0|1] # 1 = validate each xml file, 0 = do not (default = 0)

  • amielocal/conf/db.config

This configuration file is used by the reference implementation to connect (via DBI) to the intermediate databases.

dsndbi:dbi-driver:driver-parameters

userdatabase-user

passworddatabase-user-password

Create a public/private key combination for the “local user” and exchange public keys with the “remote user.” It is beyond the scope of this document to provide instructions on how to generate the keys and how to install them[10].

Create a crontab entry for to run bin/amie for amieuser. This can be done either as an entry in root’s crontab file, or as an entry in the crontab file for amieuser.

To do this as a root entry:

crontab –e

0 * * * * su c amieuser amie

To do this as an entry in the crontab for amieuser:

crontab –e amieuser

0 * * * * /home/amieuser/bin/amie

NOTE: this will run AMIE every hour[11].

1 of 410/24/2018

[1] See instructions on how to access CVS at repo.teragrid.org.

[2] The reference implementation is described in the document Implementing AMIE.

[3] For TeraGrid sites, since each site will only communicate with the TeraGrid Central Database site, there will only be a single “local user” and a single “remote user.” At the TeraGrid Central Database site, there will be multiple users, one for each of the sites that will communicate with it.

[4] It is not required to install into /amie. If AMIE installed elsewhere, modify the instructions accordingly, or create /amie as a link to the installation location.

[5] None of these values are required. The site names, user names, home directories can be chosen by the site. Modify the instructions accordingly.

[6] It can not be on a remote file system, like NFS or AFS. AMIE uses flock (file locking) which requires a local file system.

[7] This mustfollow the chown command, not precede it.

[8] This timeout controls how long amie will expect the corresponding send command to take to complete. If that send command exceeds this number of minutes, it will be killed and no further attempts will be made to run that send command (until the next amie run).

[9] Reponses will be not generated by the remote site immediately upon receipt of a file, but rather when the cron job for AMIE is run. It is recommended that the timeout be twice as long as the cron job interval. If the remote site will run AMIE every hour, then the timeout should be set to 2 hours.

[10] The man pages for ssh and ssh-keygen should be referred to for key generation and installation.

[11] The cron job interval should be chosen to be half as long as the response.timeout8 for the remote site