hospitality_help.txt

Scripts and JARs from hospitality project
-------------------------------------

$Id: hospitality_help.txt,v 1.1.1.1 2001/10/30 10:11:04 andyc Exp $


Introduction
------------

The JARs and scripts described here use the word "hospitality" a lot.
This hides the fact that control (ie admin) warrants for a hospitality are
actually control (ie admin) warrants for a hosting service. The
hosting service is provided by the hospitality JARs and scripts.  The
words "hospitality" and "hosting" are therefore fairly interchangable
here.


hospitality_control.jar
-------------------

Usage: java -jar hospitality_control.jar <dir> <name>

Generates a netlet descriptor so a cluster of Nodality nodes can
provide a hosting service.  The netlet is a bootstrap netlet and
creates a warrant gives netlets access to administer the hosting
service.

When the boot netlet descriptor is run in a Nodality node at boot time
it can be given arguments as in this example with the jnode script:

    jnode <jtrix_params> <name>-boot.xml [sas-in=<sas_warrant>]
           [hosting-out=<hosting_warrant>]

where <jtrix_params> are whatever parameters jtrix usually accepts.

For example, here is how to start a new node with a hosting service,
telnet and SAS.  Hospitalities admin warrant is written to a file,
clust01-admin.xml, then read by each of the next bootstrap netlets
(telnet and SAS) in sequence:

    hospitality_init clust01
    telnet_init 2000
    sas2_init niksas
    jnode 100 clust01-boot.xml hosting-out=clust01-admin.xml \
        telnet-2000.xml hosting-in=clust01-admin.xml \
        niksas-boot.xml hosting-in=clust01-admin.xml \
            hosting-out=clust01-real-admin.xml sas-out=niksas-warrant.xml \
            sas-desc=niksas-real-desc.xml

Arguments:

    <dir>
           Base directory in which warrants and descriptors are to be
           written.
    <name>
           An arbitrary string to identify hospitality. Must be
           unique within this LAN.
    <sas_warrant>
           Optional warrant to a SAS which hospitality can use.
    <hosting_warrant>
           Tells the boot netlet it should write a hosting administration
           warrant to the named file. If both sas-in and hosting-out
           are used, this written warrant will be the warrant from the
           SAS. If sas-in isn't supplied, then the warrant will be a
           boot warrant with no bind servers.

Files:

    <name>-boot.xml
           Generated boot descriptor to run a hosting controller netlet,
           which creates and manages hospitality.
    <sas_warrant>
           The input SAS warrant.
    <hosting_warrant>
           The output hosting administration warrant.


hospitality_facet.jar
-----------------

Usage: No command line usage.

JAR file of all the hosting facets. Used, for example, by
hospitality_telnet.jar.


hospitality_init
------------

Usage: hospitality_init <name> <hospitality_options>

Generates warrants for a hospitality hosting service of a given name. This
name should be unique within its LAN. Expects a public/private key
pair, but will generate them if either one is not found.

Arguments:

    <name>              Name of the cluster.
    <hospitality_options>   Passed directly to hospitality_control.jar.

Files:

    <name>.prv
                Expected/generated private key.
    <name>.pub
                Expected/generated public key.
    <name>-boot.xml
                Generated boot descriptor to run a hosting controller netlet,
                which creates and manages the hosting service.


hospitality_keygen
--------------

Usage: hospitality_keygen <name>

Runs hospitality_keygen.jar.


hospitality_keygen.jar
------------------

Usage: java -jar hospitality_keygen.jar <name>

Generates a public/private key pair. This can be used for any application,
not just hospitality

Files:

    <name>.prv  The private key of the pair.
    <name>.pub  The public key of the pair.


hospitality_telnet.jar
------------------

Usage: java -jar hospitality_telnet.jar <dir> <port> [<outfile>]

Used by script telnet_init. See that for more details.

Arguments:

    <dir>
           Base directory in which warrants and descriptors are to be
           written.
    <port>
           Port which the telnet server should listen on.
    <outfile>
           Filename of XML netlet descriptor generated.

Files:

    <outfile>
           Descriptor generated.


telnet_init
-----------

Usage: telnet_init <port>

Generates a bootstrap descriptor for a telnet server which provides
telnet access to the hosting service. This is for use by the hosting
administrator only.

This telnet server will expect an input parameter ("hosting-in") on
boot which is the hosting admin warrant to expose using telnet.  The
telnet server will run on port <port>.

Here is an example of how to create a descriptor for a telnet server on
port 2000, then start a new node (with ID 100) in a new cluster "fred"
with this server. The hosting admin warrant will be in a file called
"fred-boot-admin.xml":

    hospitality_init fred
    telnet_init 2000
    jtrixd 100 telnet-2000.xml hosting-in=fred-admin.xml

Arguments:
    <port>
        Port which the telnet server should listen on.

Files:
        telnet-<port>.xml
            Generated descriptor.

(ends)