This document contains a brief overview of how to run Twine, the new version of INS. It may be helpful to read the documentation for the original version of INS, as most of the functionality has been carried over to Twine.
It is also very useful to take a look at the
ins/scripts
directory. It contains several scripts
useful to understand how to use INS/Twine.
CVS
repository. It works on Redhat 7.1
and Mandrake 8.0. If you have another platform, you must install SFS
and Chord on your machine as per instructions on the PDOS page.
A Chord node is started through a C++ application located in
ins/keyrouters/chordkeyrouter/
. It is called
ckr
(for "Chord Key-Router"). The binary included in the
repository is compiled for RedHat 7.1 or Mandrake 8.0. For other
platforms ckr
must be recompiled. This requires
installing SFS and Chord as described above. The binary is included
to avoid these installations if possible.
ckr is used as follows:
Usage: ckr -j hostname:port -p myPort [-v nvnode]
hostname:port | are the contact information of a Chord node that is already part of the overlay network being formed. This information allows the new node to join the network. The first node to be started should indicate its own contact information. |
myPort | is the port on which this ckr instance should be listening |
The optional parameter vnode | enables a node to represent several virtual nodes. This affects load distribution. For a uniform load distribution it is best to start all nodes with the same number of virtual nodes, and it is best to choose this number rather high (20 for example). |
Example: starting a network of three nodes, with the first node
running on nutmeg.lcs.mit.edu
. The other nodes may
be started on the same or on different hosts.
ckr -j nutmeg.lcs.mit.edu:10005 -p 10005 -v 20
ckr -j nutmeg.lcs.mit.edu:10005 -p 10006 -v 20
ckr -j nutmeg.lcs.mit.edu:10005 -p 10007 -v 20
Usage: java ins.inr.TwineResolver [vspace1,vspace2,...] -rpc myport -keyrouter port
[-udp udpport] [-d dsr] [-l] [-qt timeout] [-ad nbresolvers] [-qd nbresolvers]
[-pingstations pspath]
[--display] [--no-values] [--cap capacity]
-rpc | Use this port for communication between resolvers |
-keyrouter | Connect to this ckr process (running on the same host) |
In a network, offsets between ports of each {resolver,keyrouter} pair MUST be the same | |
-udp | Use this port to listen for client messages |
-d | Use dsr as the DSR |
-l | Turn on packet-logging mode |
-qt | Use this timeout for queries (ms) |
-ad | Replicate each key that many times |
-qd | Submit each query to this many resolvers at once. |
The value specified should be less than the value specified for the -ad option. | |
-pingstations | Use pspath to specify a ping.stations file. |
This is a late-binding option. If not using this option the resolver will use 0 ping stations and set an infinite distance between resolvers. | |
--display | Start a graphical window displaying the name tree. Useful for debugging. |
--no-values | Make the resolver use only attributes of resource descriptions when routing queries and advertisements (instead of both attributes and values). |
--cap | Network capacity in bits/second (default: 10485760) |
Example: starting resolvers associated with the three ckr started above
java ins.inr.TwineResolver -udp 20005 -rpc 15005 -keyrouter 10005
java ins.inr.TwineResolver -udp 20006 -rpc 15006 -keyrouter 10006
java ins.inr.TwineResolver -udp 20007 -rpc 15007 -keyrouter 10007
java ins.inr.TwineResolver -udp 20007 -rpc 15007 -pingstations ./ping.stations -keyrouter 10007
A sample ping.stations file looks like this:
first.ping.station.net | 20001 |
second.ping.station.net | 20001 |
third.ping.station.net | 20001 |
... |
ins.apps
.
Most of them are described here.
ins.apps.tests.TwineTester is the main test application for
Twine resolvers. It is almost identical to ins.api.AppTests
, but it uses
some features particular to Twine. For example it doesn't use vspaces. This application is
intented for experimentation.
java tests.TwineTester -host:portnumber name-specifier
host:portnumber | Is the resolver to which the application should connect to. |
name-specifier | Is the description
of an advertised resource. It should be of the form:
[attribute=value[a11=v11][a12=v12]][a2=v2] etc |
discoverNames [a2=v2] |
getHostByiName [attribute=value[a11=*]] all |
getHostByiName [attribute=value[a11=*]] any |
ins.apps.tests.SearchCFS is an application developed for searching in CFS. In fact it's a very useful application to run experiments. It has an interface very similar to TwineTester, but it takes very different commands on the interactive prompt.
java tests.SearchCFS -host:portnumber name-specifier
host:portnumber | Is the resolver to which the application should connect to. |
name-specifier | Is the description
of an advertised resource. It should be of the form:
[attribute=value[a11=v11][a12=v12]][a2=v2] etc |
insertDir /tmp/mp3dirkey /tmp/mp3
Reads directory /tmp/mp3 and creates a
{name-specifier,host-record} pair for each mp3 file found. Name-specifiers are
generated from mp3 headers. Host-records contain the directory key (found
in file /tmp/mp3dirkey ) and the relative path to the file. When a directory
is exported in CFS, a unique identifier is created for it. In CFS, this identifier is
later used to mount the directory. Therefore both the directory key and a
path inside the directory are required to retrieve a file.
|
insertFiles /tmp/mp3_inserted_files.txt
Reads a file containing a list of file names and unique identifiers. When files are inserted into CFS, a root block identifier is computed and constitutes the file's unique identifier. Similarly to insertDir
a {name-specifier,host-record} pair is thus generated for each file. In this case however,
the host-record contains the unique file-key. The file /tmp/mp3_inserted_files.txt
must contain each file name and key on a separate line as file names may contain spaces.
|
insertNameSpecs numericalkey ins/scripts/sampleNameSpecifiers/mp3/vol1
Exists mostly for the purpose of running experiments. It reads a file containing arbitrary name-specifiers. It creates {name-specifier,host-record} pairs where each host-record contains the numericalkey given in parameter |
setFrequency value
Allows to modify the frequency of advertisements of all name-specifiers. The default value is quite high so by default resource descriptions are inserted only once into the network. |
findAll name-specifier
Finds host-records of all resources whose description matches the given name-specifier |
findAny name-specifier
Finds the host-records of the resource whose description matches the given name-specifier and whose application level metric is lowest |
findInfo name-specifier
Finds complete name-specifiers of all resources whose description matches the given name-specifier |
quit
Terminates the application |
In INS, the uniqueness of a resource/document is determined by the {name-specifier,announcing-app} pair. Hence if one instance of SearchCFS advertises many documents under the SAME name-specifier, they will be considered as the same document by the Twine network
The input buffers of resolvers may only hold around 200 packets. As advertisements are sent in bursts, it is preferable to make each client application advertise no more than 200 name-specifiers.
ins.api.TwineApp
.
ins.api.TwineMultiApp
.
ins.apps.tests
as examples.