1 Installation
1 Installation
1.1 Introducing
Ajanta
1.2 System
Requirements
1.3 Download
Ajanta
1.4 Setup
Ajanta Programming Environment
1.4.1 Policy
File Setup for Java 1.4 release version of Ajanta
1.5 Description
of the configuration files
1.6 Name-Registry
Administration
1.7 Change
configuration information
1.8 Running
the Demos
1.9 Trouble-shooting
Welcome to Ajanta. Ajanta is a Java based framework for programming mobile agent based applications on the Internet. You can use the Ajanta programming environment to develop agent-based applications. This section provides a brief overview of Ajanta's main components and walks you through the download and installation procedures. For a detailed discussion on Ajanta's programming environment please read the publications on Ajanta's web-site.
This chapter will walk you through the
basic installation procedure and a demo program "HelloWorld".
The steps are numbered Step1, Step2 etc.
in the following sub-sections. When going through the steps if you get
into trouble read the trouble-shooting
section at the bottom of the page.
Main Components
The main components of Ajanta are the
agent, the agent-server and the name-registry. A mobile agent is
a program, which represents a user in a network and is capable of migrating
autonomously from node to node, performing computations on behalf of that
user. A host in the Internet can provide services to mobile agents
by running an agent-server.
The name-registry provides the name service and can store any characteristics of an entity. Ajanta name-registry works as a repository of public-keys of all the entities. Any entity with a name, i.e. a URN, in Ajanta needs to register itself with a name-registry. For initial registration of an agent server, the location of the name-registry is provided to the server by the user. This bootstrap name-registry is called the local name registry. Before a user is able to run an agent-server, the local name-registry must be installed and running by an administrator.
Core Classes
Link
to Core Classes.
Sample Demos and Applications
This release provides the following demo and applications and their source codes to enable users efficiently implement applications and experiment with Ajanta framework.
Demos:
1. HelloWorld:
Agents migrates to given destination servers and prints "Hello" on the
console.
2. HelloJoin:
Same as HelloWorld, except the agent uses split-join as migration pattern.
3. RMIHello:
Shows how to access resources through proxy.
4. RecallDemo:
Shows how to use agent primitive recall/retract/terminate.
Applications:
1. A Calendar
Application
2. A File Sharing Middleware
This version of Ajanta is tested only on UNIX platforms. As Ajanta is written in Java, it is platform independent. But we have not tested it on other platforms supported by Java, like Windows NT.
To run Ajanta, following software components
are required.
1. JDK 1.1.X
2. Perl
Before you download
When going through the steps if you get into trouble read the trouble-shooting section at the bottom of the page.
Step 1: Download
Link to download page.
Step 2: Store Ajanta classes
Untar the ajanta_beta.tar.z file
under the user specific path, say in a directory whose path is some_path.
Define the environment variable AJANTA_HOME in your .cshrc
or .profile as shown below.
For example, it can be done on the command line as:
ajanta/
setup/
NOTE: Please set the permissions for the ajanta classes as "755".
Add the path "{$AJANTA_HOME}" to the CLASSPATH. It can be done using the following command.
% setenv CLASSPATH {$AJANTA_HOME}:{$CLASSPATH}
1.4 Setup Ajanta Programming Environment
Before you setup
Your environment variable should contain the CLASSPATH and AJANTA_HOME. If not, please refer to the previous section.
For installing Ajanta, in Step 4 below, you can choose either to install the package as an administrator or install it as a typical user.
The administrative installation includes all the modules including setting up the name-registry configuration. It will allow the administrator to run a name-registry and register other users in the name-registry.
The option "user installation" will skip the setup process of name-registry. Typically there is a single name-registry in a domain. A user is responsible to know its location (DNS host name) and ask the name-registry administrator to register himself/herself.
Step 4: Run installation script "userSetup"
Please run the perl script "userSetup" to install Ajanta in your user environment.
% perl $AJANTA_HOME/setup/userSetup
This script will ask you to choose between two installation options: (1) Administrator and (2) User. If another user is serving as an administrator, you may choose the option (2) User. In that case you have to ask the name-registry administrator to register yourself in the local name-registry.
This script will create a directory ".ajanta" in your home directory. This directory keeps all the configuration information needed by different entities like user, name-registry, agent-servers in Ajanta
1.4.1 Policy File Setup for Ajanta 2.0 with Java2 Security Framework
Ajanta 2.0 release is based on Java2 security framework. In Ajanta 2.0, access policy for file and network resources is expressed using a java policy file. If you are using older version of Ajanta, version 1.0 or 1.1, please refer to Chapter 3.
There are three distinct entities for which policies are set. These are (1) agent-servers or applications extending agent servers (2) agents, and (3) name-registry. There are two types of subject for policy specification in Java 2: codebase and principal.
** IMPORTANT: In Ajanta 2.0, only agent permissions should be specified based on principal. Permissions provided to agent-server and name-registry should be based on codebase.
** IMPORTANT: Please make sure the "startup_path" in serverConfig file is correct. For example:
startup_path=/dev/ajanta2/ajanta/server/StartUp.class
In the above line, AJANTA_HOME is /dev/janta2.
/* all privileges to
any code running from AJANTA core classes */
grant codeBase "file:AJANTA_HOME"
{
permission java.security.AllPermission;
};
/* permissions given
to remote agent based on agent's owner
grant principal com.sun.security.auth.UnixPrincipal
"AGENT_OWNER_URN" {
/* add the privileges here */
};
/* permissions given
to local application specific server */
grant codeBase "file:CODE_BASE"
{
/* add the privileges here */
};
/* all privileges to
any code running from ajanta demo */
grant codeBase "file:DEMO_HOME"
{
permission java.security.AllPermission;
};
Each entry within the policy file associates privileges with a codebase and/or ajanta principal. A sample policy file is provided with the ajanta release. Please follow the guidelines given below for setting up this policy file:
grant principal com.sun.security.auth.UnixPrincipal
"OWNER_URN" {
/* specific permissions go here */
/* refer to Java Security Documentation on how to grant privileges */
};
OWNER_URN must be replaced with the urn
of the agent's owner.
grant codebase "CODE_BASE"
{
/* specific permissions go here */
/* refer to Java Security Documentation on how to grant privileges */
};
CODE_BASE must be replaced with the codebase of the application classes. (NOTE: The codebase for a class is the location from where the package hierarchy begins.) As these are local classes they could be given all privileges. If not all privileges need to be granted, this codebase must be different from the codebase for the ajanta core classes.
Replace DEMO_HOME with the absolute path name of the directory in which the demo classes are present. This should be the path upto and including the directory examples.
Sample Policy File: A sample policy file for an agent with
owner "URN:ans:newton.cs.umn.edu/user1" is shown below. In this example
an agent is sent to a generic AgentServer to read the "/testFiles/file".
The codebase for the AgentServer is provided with all permissions;
however, only agents owned by the specified principal "user1"
has read permission on the file "/testFiles/file"
grant
codeBase "file:/dev/ajanta2/-" {
permission java.security.AllPermission;
};
grant principal com.sun.security.auth.UnixPrincipal
"URN:ans:newton.cs.umn.edu/user1" {
permission java.io.FilePermission "/testFiles/file", "read";
};
1.5 Description of the configuration files
The installation script will create the following directory structure under the user's HOME directory
$HOME/.ajanta/
user/
urn
nr/
keys
/* Only Administrative installation */
pubkeys
/* Only Administrative installation */
servers/
serverConfig
Debug
helloserver1/
config
keys
pubkeys
helloserver2/
config
keys
pubkeys
helloworld/
config
keys
pubkeys
helloJoin/
config
keys
ubkeys
RMIHello/
config
keys
pubkeys
RecallDemo/
config
keys
pubkeys
afsClient/
config
keys
pubkeys
afsServer/
config
keys
pubkeys
calendarClient/
config
keys
pubkeys
calendarServer/
config
keys
pubkeys
scripts/
tmp/
The "user" directory contains the URN of the user. An example of this URN is
"urn:ans:NameRegistry'sDNSHostName/UserName"
In Ajanta all the entities need Private/Public Key Pairs for authentication and encryption. Here we need pairs of keys for the name-registry, the user and the agent-servers.
The ".ajanta/servers/serverConfig" file contains the URL of the name-registry, startup-path which is the location of the class StartUP and URLs for the rmi port used by servers. These URLs are the user specific host name and port number where a user is running a rmi registry.
Each of the directories under "server", which represent various demos and applications systems such as helloserver1, afsServer, afsClient etc, contains a config file which stores all the configuration information needed by the demo programs or the applications.
The "scripts" directory contains different scripts needed by agent-servers. The scripts currently in this directory are used by the afsServer.
The "tmp" directory is used by afsServer for temporary storage of query results.
1.6 Name-Registry Administration
If you have done a user installation please ask your local name-registry administrator to register you and skip the following step. In case you are the administrator you will be automatically registered in the name-registry.
NOTE: you need to run the name-registry on the machine you mentioned during the installation. If you decided to run the name-registry on a different machine, please see the following section on how to change the name-registry location.
Step 5: Running Name-Registry
Login to the machine where you want to
run your name-registry. Then type the following to start the name registry:
% cd $HOME/.ajanta/nr
% perl {$AJANTA_HOME}/setup/startNameRegistry
Currently the name-registry serializes
its database to a file with extension ".rdmp" in the directory where it
is executed. In the above command line, we have moved to the "nr" directory
so that the dump file will be created there.
How to add a User in the name-registry
The administrator can run the "AddUser" utility to register a user to the name-registry. A user needs to be registered in a name-registry before he/she is able to run any agent-server. To register a user, the administrator will need two things (1) User's login name and (2) Users public keys. It is the responsibility of the user and the name-registry administrator to find a feasible and secure way to transfer the user's public keys (located at "$HOME/.ajanta/user/pubkeys") to the administrator.
A simple workable solution could be, the user copies his/her public key in a /tmp directory and gives the administrator the read permission.
The name-registry administrator runs the following utility to add a user.
% java ajanta.naming.AddUser "DNS host name of the name-registry"
The program will prompt for user-name as shown below. Please provide the user's login name (e.g tahmed).
Signature Verified
Enter the Username
to be added
tahmed
Then it will ask for the location of the public keys of the user. If you have a copy of the pubkeys in /tmp directory and you have read permission for the keys, you can provide the full path of the pubkeys.
Enter the full path for the user's DSA/ElGamal
pubkeys file:
/tmp/pubkeys
How to clean start a Name-Registry
The name-registry serializes its database
to a file named "DNSHostName.rdmp" (e.g. ajata.cs.umn.edu.rdmp). The first
part of the file name represents the DNS hostname of the machine it is
running on. This naming convention will allow a user to run multiple name-registries
in different hosts. This serialized file is created in the directory where
the name-registry is running.
Name-registry updates this file every
time a modification is made to the name-registry's entries.
If a clean start is needed, the name-registry
administrator can delete this file and restart the name-registry by running
the script "startNameRegistry". In this case, the administrator has to
register the users again by running "ajanta.naming.AddUser."
NOTE: Your environment variables
CLASSPATH and AJANTA_HOME should be properly set as described above.
1.7 Change configuration information
How to change Name-Registry location Or Changes that need to be done when you choose a different Name-Registry
1. If you change your name-registry where you are registered as a user, your URN needs to be changed. This needs to be done manually in file "$HOME/.ajanta/user/urn" as the current release supports only single name-registry.
2. Also you need to modify the file "$HOME/.ajanta/servers/serverConfig"
to reflect the change of the name-registry.
Changes need to be done when you update AJANTA_HOME
If you have moved your Ajanta classes to a different location, it needs to be reflected on all the server config files. The script "userSetup" and "serverSetup" uses the environment variable "AJANTA_HOME" to setup different configuration values. These values are "startup_path" in file "~/.ajanta/servers" and "cs_filepath" in each server's config file.
1.8 Running Demos and Applications
In this section we will walk you through the running of the demo programs. There are README files provided in all application and demo directories. Please refer to them when needed.
The helloworld demo consists of two generic agent-servers called helloserver1, helloserver2 and starts a client "helloworld", which sends an agent to these two agent-servers. Please follow the following steps to run this demo. It is assumed that you have run "userSetup" script to setup the configuration files needed by this demo. If you have not, please run the "userSetup" script.
Note:
The code for all the demos listed here is located in the following directory:
$AJANTA_HOME/demo
Step 6: Start Rmi Registry
To start agent-servers, the user needs to run a RMI Registry in a user-defined port. We provided the script "startRmi" for this.
On each machine where a user wants to run agent servers, the user should run one RMI registry process.
For example if you decided to run agent-servers on machine "Machine1", "Machine2" and "Machine3", you need to run the script "startRmi" on each of these machines, as shown below:
Machine1 % perl
{$AJANTA_HOME}/setup/startRmi
Machine2 % perl
{$AJANTA_HOME}/setup/startRmi
Machine3 % perl
{$AJANTA_HOME}/setup/startRmi
The script will start an RMI Registry on the machine where it is executed. It will also keep the port information in the configuration file "$HOME/.ajanta/servers/serverConfig". Any consequent run of this script will kill the previous RMI Registry process and run a new one.
Demo HelloWorld
Step 7:1:a: Run helloserver1, helloserver2
Login to two different windows (these windows
could be on the same or different machines) and run agent-servers.
For example,
Machine1 % java
ajanta.server.AgentServer helloserver1
Machine2 % java
ajanta.server.AgentServer helloserver2
This agent-servers will print their URNs
on the screen. The URN will look like
"urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1"
"urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver2".
We will need these URNs to send an agent to them.
Step 7:1:b: Run helloworld
First, the file "$HOME/.ajanta/servers/helloworld/itinerary" needs to be created which contains the URNs of the agent-servers to which agents will be sent. Please create this file and write the URNs of the agent-servers -- helloserver1 and helloserver2.
For example after creation the file will look as below:
urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1
urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver2
Then run the helloworld. It will send an agent to the agent-servers in the itinerary.
Machine3 % cd
$HOME/.ajanta/servers/helloworld/
Machine3 % java ajanta.demo.helloworld.HelloWorld
helloworld
The agent will move to the agent-servers
mentioned in itinerary, and print a message on each of the agent server's
window.
We have provided the contents of three
different windows below. The important messages are highlighted.
Window 1: Helloserver1
******************************************************************************************************************************************
(~) % java ajanta.server.AgentServer helloserver1
My URN = URN:ans:fourier.cs.umn.edu/tahmed/helloserver1
FileAcl: WARNING /home/grad03/tahmed/.ajanta/servers/helloserver1/.acl
not found
Agent server ready
ATPListener: create ATPHandler
Agent URN:ans:fourier.cs.umn.edu/tahmed/helloworld/helloagent
says Hello to URN:ans:fourier.cs.umn.edu/tahmed/helloserver1
AgentEnv: launch: destURN:ans:fourier.cs.umn.edu/tahmed/helloserver2
AgentEnv: Creating ATP request
AgentThread: java.lang.ThreadDeath
java.lang.reflect.InvocationTargetException
at ajanta.server.AgentThread.run(AgentThread.java:83)
***********************************************************************************************************************************************
Window 2: Helloserver2
***********************************************************************************************************************************************
% java ajanta.server.AgentServer helloserver2
My URN = URN:ans:fourier.cs.umn.edu/tahmed/helloserver2
FileAcl: WARNING /home/grad03/tahmed/.ajanta/servers/helloserver2/.acl
not found
Agent server ready
ATPListener: create ATPHandler
Agent URN:ans:fourier.cs.umn.edu/tahmed/helloworld/helloagent
says Hello to URN:ans:fourier.cs.umn.edu/tahmed/helloserver2
***********************************************************************************************************************************************
Window 3: HellWorld
***********************************************************************************************************************************************
(~/.ajanta/servers/helloworld) % java
ajanta.demo.helloworld.HelloWorld helloworld
My URN = URN:ans:fourier.cs.umn.edu/tahmed/helloworld
FileAcl: WARNING /home/grad03/tahmed/.ajanta/servers/helloworld/.acl
not found
Agent server ready
hop class name ajanta.pattern.Sequence
hop class name ajanta.pattern.ItinEntry
AgentEnv: launch: destURN:ans:fourier.cs.umn.edu/tahmed/helloserver1
AgentEnv: Creating ATP request
*************************************************************************************************************************************************
Demo helloJoin
This demo starts two generic agent-servers called helloserver1, helloserver2 and starts a client helloworld, which sends an agent to the agent-servers. The difference between this and the previous demo HelloWorld is that the agent for this demo uses the splitJoin pattern for migration and sends individual child agents to each of the servers, instead of a single agent visiting all of the servers.
Please follow the following steps to run this demo. It is assumed that you have run "userSetup" and "startRmi" scripts to setup the configuration files needed by this demo. If you have not, please run "userSetup" and "startRmi"
Step 7:2:a: Run helloserver1, helloserver2:
Login to two different windows (these windows
could be on the same or different machines) and run agent-servers.
For example,
Machine1 %
java ajanta.server.AgentServer helloserver1
Machine2 % java
ajanta.server.AgentServer helloserver2
These agent-servers will print their URNs on the screen. The URN's will look like
Step 7:2:b: Run helloworld:
The file "$HOME/.ajanta/servers/helloworld/itinerary"
needs to be created which will contain the URNs of the agent-servers to
which agents will be sent. Please create this file and write the URNs of
the agent-servers -- helloserver1 and helloserver2.
For example, after creation the file
will look as below:
urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1
urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver2
Then run helloworld as shown below. It will send agents to the agent-servers in the itinerary.
Machine3 % cd
$HOME/.ajanta/servers/helloJoin/
Machine3 % java ajanta.demo.helloJoin.HelloWorld
helloJoin
NOTE: Please make sure that you have created
the file "itinerary" in the directory helloJoin.
Demo RMIHello
This demo starts a generic agent-server called helloserver1 and starts a client RMIHello, which sends an agent to the agent-server. After successful migration of the agent to the destination server, the agent will create a Proxy. The client waits for a while and then requests a service from that Proxy.
Please follow the following steps to run this demo. It is assumed that you have run "userSetup" and "startRmi" scripts to setup the configuration files needed by this demo. If you have not already done so, please run the scripts "userSetup" and "startRmi".
Step 7:3:a: Run helloserver1:
Login to a window and run the agent-server. For example,
Machine1 % java ajanta.server.AgentServer helloserver1
This agent-server will print its URNs on
the screen. The URN will look like:
"urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1"
Step 7:3:b: Run RMIHello
The HelloClient program is executed to
launch an agent. The first argument, RMIHello, is the name of the client
agent-server that launches an agent. The second argument for the HelloClient
program is the URN of the destination server, as shown below:
Machine3 % java ajanta.demo.RMIHello.HelloClient RMIHello urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1
The HelloClient will send an agent to the
destination agent-server helloserver1. Upon arriving, the agent will
create a Proxy for the class "ajanta.demo.RMIHello.Hello" and register
itself with agent-server's RMI registry. Then the agent will wait
in a loop printing "HelloAgent in loop". On client side, the client agent-server
will wait for a while for the completion of agent migration.
Then it will obtain a reference to the
proxy , created by the agent, from the destination agent server and request
the service "sayHello".
Demo RecallDemo
This demo starts a generic agent-server called helloserver1 and starts a client RecallDemo which sends an agent to the agent-server helloserver1. After successful migration to the destination server, the agent will create a Proxy. The client will wait for a while and then recall/retract/terminate the agent. Any agent-server other than the client RecallDemo ( who is not an owner or guardian of the agent sent by RecallDemo) is not permitted to recall/retract/terminate the agent.
Please follow the following steps to run this demo. It is assumed that you have run "userSetup" and "startRmi" scripts to setup the configuration files needed by this demo. If you have not already done so, please run the scripts "userSetup" and "startRmi".
Step 7:4:a: Run helloserver1:
Login to a window and run the agent-server. For example,
Machine1 % java ajanta.server.AgentServer helloserver1
This agent-server will print their URNs on the screen. The URN will look like
"urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1".
Step 2b: Run RecallDemo
RecallDemo is the name of the client agent-server and is the first argument for HelloClient. We need to provide the destination agent-server as second argument.
Machine3 % java ajanta.demo.RecallDemo.HelloClient RecallDemo urn:ans:"NameRegistry's_DNS_Name"/"UserID"/helloserver1
The HelloClient will send an agent to the destination agent-server helloworld. Upon arriving, the agent will create a Proxy for the class "ajanta.demo.RMIHello.Hello" and register itself with agent-server's RMI registry. Then the agent will wait in a loop printing "HelloAgent in loop". On client side, the client agent-server will wait for a while for the completion of agent migration. Then it will obtain the proxy created by the agent from the destination agent server and request the service "sayHello".
After that the client will execute recall/retract/terminate.
In the demo code the "recall" is executed. The "retract" and "terminate"
is commented out. You can un-comment one of them to test the functionality.
This section is updated whenever we encounter a bug. Please check this section whenever you encounter a problem.
Configuration
Problems:
1. The config file may not substitute
the environment variables $AJANTA_HOME and $HOME.
Solution: Substitute the environment
variables with appropriate value.
2. Currently the key-files location
is in each server 's config file.
Solution: If you get an error message
saying key not found, please modify the value for "key-file"
in the config file of the appropriate server. (???)
3. You may get a message class not found
if Ajanta class permissions are not properly set.
Solution: Please set the permissions
for the ajanta classes as "755" as follows: % chmod -R 755 $AJANTA_HOME/ajanta
4. Script "startNameRegistry": this
script kills the rmi registry running on port 1099 and starts a new RMI
registry on port 1099. If another user is running a RMI registry on port
1099, the script "startNameRegistry" will fail to kill the process.
Solution: In this case, either
you have to move to a different machine or ask that user to kill his/her
RMI registry on port 1099.
If you
get a message saying something like "port busy", you can take care of that
as follows:
6. Any problems related
to the name registry (eg: user is not registered with the name registry,
user changed his/her public keys etc.) will cause a NullPointerException.
Solution:
Ask your Ajanta Administrator to register you (your URN and public keys)
at the name registry using the "AddUser" script.
7. Script "startRmi"
may cause a problem, such as in the Ajanta File Server session shown below.
The script uses the system command "uname -n" to get the complete DNS name
of the machine on which it is starting the RMI registry. In some cases,
however, the command returns an incomplete name, as shown below in red.
Solution:To
correct this, modify the file .ajanta/servers/serverConfig
by completing
the host name as plato.cs.umn.edu
pathak@plato
(~) % perl {$AJANTA_HOME}/setup/startRmi
previous port : 22600
12999 1 /bin/sh /soft/java/JDK-1.1.6/bin/../bin/sparc/green_threads/rmiregistry
22600
13019 13018 grep 22600
Killing rmiregistry running on port 22600
pathak@plato (~)
% more .ajanta/servers/serverConfig
#Please provide
your local name registry DNS host name in place of
#fourier.cs.umn.edu
nameregURL=//plato.cs.umn.edu/AjantaNameRegistry
startup_path=/project/research01/nexus/ajanta/dev.jdk1.1x//ajanta/server/StartUp
.class
serverURL=//plato:22700
This line should
read: serverURL=//plato.cs.umn.edu:22700
pathak@plato (~)
% java ajanta.apps.afs.FileServer $HOME/root
My URN = URN:ans:plato.cs.umn.edu/pathak/afsServer
FileAcl: WARNING
/home/ugrad00/pathak/.ajanta/servers/afsServer/.acl not found
Error no rmi port
found for hostplato.cs.umn.edu in file .ajanta/servers/serverConfig
Execute startRMI
to run rmiregistry and register the port in config file
2. Demo helloworld, hellojoin: Please make sure that you have created the "itinerary" file as shown in the instructions above. Also, blank lines in the itinerary will cause an exception. Please remove any blank lines from the itinerary.
GO TO- Top of this page Next Chapter Table of Contents of this Guide