# ----------------------------------------------------------------------------
#  $RCSfile: xbone-app-deployment.txt,v $
#
# $Revision: 1.4 $
#   $Author: pingali $
#     $Date: 2005/03/31 07:03:47 $
#    $State: Exp $
# ----------------------------------------------------------------------------
# Primary Author: Yu-Shun Wang
# ----------------------------------------------------------------------------

                Application Depolyment in X-Bone Overlays
                              Yu-Shun Wang

0.  Introduction

    This document describes the X-Bone application deployment support, what
    it is, and how to use it. A simple script is provided as an example and
    starting point for more sophisticated applications.

    X-Bone provides a mechanism to support application deployment on top of
    virtual networks (overlays). The basic idea is to utilize the X-Bone node
    daemon on each node to execute user-provided commands that will setup,
    configure, and start the user applications *after* the overlay is
    established. The X-Bone control system will also monitor the status
    of the application upon user requests. When the overlay is torn down,
    all applications running within the overlay will also be terminated.

    This document will focus on the usage part of this mechanism. Please refer
    to the paper [xxx] for the detailed description and in-depth discussion
    of the mechanism in the X-Bone system.

    The following is a brief note on the terminology used in this document.

      o overlay & virtual network: these two terms are used interchangably.
        An overlay consists of a set of nodes connected by virtual links or
        tunnels.

      o base (physical) addresses: these are the IP addresses each node has
        for communication to the Internet. The base or physical addresses
        are static with respect to X-Bone operation, and will not be
        affectetd or changed by the overlay creations and deletions.

      o virtual addresses: these are addresses assigned and delegated from
        the X-Bone system to each node to be used as the addresses inside
        an overlay. Virtual addresses are dynamic and have the same lifetime
        as the overlays they belong to.

1.  Assumption

    X-Bone creates *closed* overlays, which means each overlay is a confined
    network connecting all participating nodes. Nodes inside an overlay could
    not communication with nodes outside through the virtual network.

    Overlay nodes have both base and virtual addresses. These addresses exist
    in each node in the form of addresses associated to network interfaces.
    X-Bone overlays are constructed in such a way that packets sent to the
    virtual addreseses of an overlay will go through the virtual links, while
    packets addresses to the base addresses will go through the base network
    (usually the Internet) instead of the virtual network.

    An application *uses* an overlay by exchanging packets among nodes via
    the overlay. Practically, this means sending and receiving packets to
    and from virtual addresses of the overlay. How this is achieved varies
    by applications. Most requires explict binding to the virtual addresses
    when starting with options in the command line, configuration files, etc.

2.  X-Bone Application Deployment Scripts

    Rather than hard-coding application commands into the system, the X-Bone
    utilizes customized user scripts to control each application. Users
    would write different commands for different applications in the
    scripts, grouped under sevearl external, "macro" targets: configure,
    start, status/monitor, stop, and cleanup. Each macro command is called
    in stages during the overaly create, monitor, and delete operations.

    This additional level of abstraction releaves X-Bone from the burden of
    hardcoding commands for all the different appliations, allows users
    fine-grain controls over how each application would be configured and
    started. There is no constraint on the type of scripts. They could be
    shell scripts, Perl, or binary executables. The only constraint is the
    format of command line options for the scripts. It is necessary for the
    script to recognize the options in order to specify different stages of
    application deployment, to obtain the network parameters (virtual
    addresses, list of virtual nodes, etc.) applications need.

2.1 Options and Arguments for the Scripts

    This section list the command line arguments for the X-Bone application
    deployment. At the end of this section, a simple example in UNIX shell
    script is provided to show how these options are obtained and parsed.
    Unless indicated otherwise, options could appear only once in each
    command line call. Note that these options and values are generated
    automatically by the X-Bone system before calling the application
    scripts. The scripts must either recognize and extract values from
    these options, or ignore the unnecessary options.

    -t ${target}

      ${target} specifies the stage of application deployment: verify,
      install, conf, run, pid, kill, cleanup, deinstall.

        - verify:
            verifies whether an application is available
        - install/desintall:
            install/deinstall an application
        - conf:
            sets up the environment for an application (configuration files,
            application paths, log files, etc.)
        - run/kill:
            starts/terminate the application
        - cleanup: 
            restore the environment back to the original state (remove the
            application files, undo the configuration applied to the system,
            etc.)

    -i ${virtual_ip_address}

      ${virtual_ip_address} is the virtual IP address for the current node.
      There could be multiple "-i" options.

    -I ${base_ip_address}

      ${base_ip_address} is the base IP address of the current node.

    -h ${virtual_hostname}

      ${virtual_hostname} is the virtual DNS hostname of the current node.

    -H ${base_hostname}

      ${base_hostname} is the base DNS hostname of the current node.

    -f ${interface}

      ${interface} is the virtual interface to the virtual link (tunnel).
      There could be multiple "-f" options one for each virtual interface.

    -a ${overlay_virtual_ip}

      ${overlay_virtual_ip} is the virtual IP addresses for the *whole*
      overlay, not just the current node. There are multiple "-a" options,
      one per virtual IP address.

    -A ${overlay_base_ip}

      ${overlay_base_ip} is the base IP addresses for the *whole* overlay.
      There are multiple "-A" options, one per base IP address.

    -n ${overlay_virtual_hostname}

      ${overlay_virtual_hostname} is the virtual DNS hostname for all nodes
      in the overlay. There are multiple "-n" options, one per virtual DNS
      hostname.

    -N ${overlay_base_hostname}

      ${overlay_base_hostname} is the base DNS hostname for all nodes in the
      overlay. There are multiple "-N" options, one per overlay base hostname.

    -d ${overlay_domain_suffix}

      ${overlay_domain_suffix} is the virtual DNS domain suffix for the
      overlay.

    -p ${overlay_prefix}

      ${overlay_prefix} is the network address prefix (virtual) of the
      overlay.

    -O ${om_ip}

      ${om_ip} is the base IP address of the overlay manager which controls
      and manages the overlay.

    -P ${om_api}

      ${om_api} is the TCP port on the overlay manager, ${om_ip}, that
      accepts the X-Bone API commands.

3.  Application Deployment Procedure

    This section describes the application deployment procedures in the
    X-Bone system.

    o Preparation of the script:

      The user will need to compose the application deployment scripts based
      on each individual application. These script must accept or ignore the
      options described above. Thses scripts must be copied to the locations
      accessible in the form of URLs (http, file, ftp, etc.)

    o Provide the URL of the script to the X-Bone system:

      The user provides the URL (uniform resource locator) of the script to
      the X-Bone system either through X-Bone GUI or directly embedded inside
      the X-Bone API create command.

    After this step, the X-Bone system takes over the operations of creating
    the overlay and fetching and executing the appliation script through the
    given URL. The user will not need to concern about the operations listed
    below.

    o Resource Discovery:

      The X-Bone system, in the process of discovering available nodes,
      will execute the script with the "verify" target to detect whether
      the application is available on the node. If not, it'll be necessary
      to call the "install" target in the later stage.

    o Overlay Construction:

      After selecting and committing the nodes for an overlay, the X-Bone
      will construct and issue commands to each node, including the options
      and values to execute the appliation scripts. After the overlay is
      constructed, the X-Bone node daemon will then call the application
      deployment script with the options specified previously, and the 
      targets in the following order: install (when necessary), conf,
      and run. The last step (run) starts the application on the overlay.

    o Overlay Deletion:

      When the user decided to tear down the overlay, the applications
      deployed on top of the overlay will also be terminated, and the
      environment will be restored to the state before the deployment.
      Upon receiving the delete command, the X-Bone node daemon will
      first terminate all applications and perform environmental cleanup
      before moving on to tear down the overlay. The application script
      will be called with the targets in the following order: kill,
      cleanup, and deinstall (if necessary).

    This is a complete life cycle of an overlay and the appliations deployed
    within the overlay.

    
    NOTES: 

    When doing app deployment, the first step RD will do is to run the
    script with "-t verify" option which should verify whether the
    node could run this app or not.  The application is run as user
    "nobody". The return value of this script should be as follows:

	   0 => the app is installed and could run
	   1 => the app is NOT installed
	   2 => could not run for any reasons 
	     (such as version mismatch, etc.)

    Currently, "install" is not recommended although it is used in the
    example code. If the application script does not support
    "install", then it should just return anything >= 2 and the node
    daemon will die and not reply to invitation message (assuming it
    could not detect the existance of the apps).

4.  X-Bone Application Deployment Script Example

    The following is a simple application deployment script that parses
    and prints the corresponding option names and values. It's a UNIX
    shell script utilize the getopt(1) command for most Unix systems.

#!/bin/sh

# 
# -------------------------------------------------------------------
#                                   X-BONE
#
#                          http://www.isi.edu/xbone
#                USC Information Sciences Institute (USC/ISI)
#                   Marina del Rey, California 90292, USA
#                          Copyright (c) 1998-2005
# 
# -------------------------------------------------------------------
#
# Copyright (c) 1998-2005 by the University of Southern California.
# All rights reserved.
#
# Permission to use, copy, modify, and distribute this software and
# its documentation in source and binary forms for non-commercial
# purposes and without fee is hereby granted, provided that the above
# copyright notice appear in all copies and that both the copyright
# notice and this permission notice appear in supporting
# documentation, and that any documentation, advertising materials,
# and other materials related to such distribution and use acknowledge
# that the software was developed by the University of Southern
# California, Information Sciences Institute.  The name of the
# University may not be used to endorse or promote products derived
# from this software without specific prior written permission.
# 
# THE UNIVERSITY OF SOUTHERN CALIFORNIA MAKES NO REPRESENTATIONS ABOUT
# THE SUITABILITY OF THIS SOFTWARE FOR ANY PURPOSE.  THIS SOFTWARE IS
# PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES,
# INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
# MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
#
# Other copyrights might apply to parts of this software and are so
# noted when applicable.
#
# -------------------------------------------------------------------
#
# Effort partly sponsored by the Defense Advanced Research Projects
# Agency (DARPA) and Air Force Research Laboratory, Air Force Materiel
# Command, USAF, under agreement numbers F30602-98-1-0200 (X-Bone) and
# F30602-01-2-0529 (DynaBone). The views and conclusions contained
# herein are those of the authors and should not be interpreted as
# necessarily representing the official policies or endorsements,
# either expressed or implied, of the Defense Advanced Research
# Projects Agency (DARPA), the Air Force Research Laboratory, or the
# U.S. Government.
#
# This work was partly supported by the NSF STI-XTEND (ANI-0230789)
# and NETFS (ANI-0129689) projects. Any opinions, findings, and
# conclusions or recommendations expressed in this material are those
# of the authors and do not necessarily reflect the views of the
# National Science Foundation.
#
# -------------------------------------------------------------------

# ========================================================================
# XBone Application Deployment Script Example
# ========================================================================

# ========================================================================
# Standard Virtual Network (Overlay) Application Deployment Arguments
# ========================================================================
# - node parameters
#   i: virtual IP address(es)
#   I: base    IP address
#   h: virtual hostname
#   H: base    hostname
#   f: interface(s)
#
# - overlay parameters
#   a: all virtual IP addresses
#   A: all base    IP addresses
#   n: all virtual hostnames
#   N: all base    hostname
#   d: overlay DNS domain suffix
#   p: overlay network prerix
#   O: overlay manager IP address
#   P: overlay manager XBone API port
#

args=`getopt t:i:I:h:H:f:a:A:n:N:d:p:O:P: $*`

if [ $? != 0 ]
then
  echo 'Usage: ...'
  exit 2
fi
set -- $args

for i
do
  case "$i"
  in
    -t)
        echo target is "'"$2"'"; target="$2"; shift;
        shift;;
    -i)
        echo [i] Virtual IP       "'"$2"'"; iarg="$2"; shift;
        shift;;
    -I)
        echo [I] Base    IP       "'"$2"'"; Iarg="$2"; shift;
        shift;;
    -h)
        echo [h] Virtual hostname "'"$2"'"; harg="$2"; shift;
        shift;;
    -H)
        echo [H] Base    hostname "'"$2"'"; Harg="$2"; shift;
        shift;;
    -f)
        echo [f] Interface list   "'"$2"'"; farg="$2"; shift;
        shift;;
    -a)
        echo [a] All Virtual IP   "'"$2"'"; aarg="$2"; shift;
        shift;;
    -A)
        echo [A] All Base    IP  "'"$2"'"; Aarg="$2"; shift;
        shift;;
    -n)
        echo [n] All Virtual hostname "'"$2"'"; narg="$2"; shift;
        shift;;
    -N)
        echo [N] All Base    hostname "'"$2"'"; Narg="$2"; shift;
        shift;;
    -d)
        echo [d] Overlay Domain  "'"$2"'"; darg="$2"; shift;
        shift;;
    -p)
        echo [p] Overlay Prefix  "'"$2"'"; parg="$2"; shift;
        shift;;
    -O)
        echo [O] OM base IP      "'"$2"'"; Oarg="$2"; shift;
        shift;;
    -P)
        echo [P] OM API port     "'"$2"'"; Parg="$2"; shift;
        shift;;
    --)
        shift; break;;
  esac
done
echo target is "'"$target"'"

WHOAMI=/usr/bin/whoami

#- Script starts -------------------------------------------------------------

case "$target" in

  verify)
    echo ">>> [Test-App] Verify"
    $WHOAMI
    echo "<<< [Test-App] verified"
    exit 1
    ;;

  conf)
    echo ">>> [Test-App] Configuration"
    whoami
    echo "<<< [Test-App] configured"
    ;;

  run)
    echo ">>> [Test-App] Run"
    whoami
    echo "<<< [Test-App] started"
    ;;

  pid)
    ;;

  kill)
    echo ">>> [Test-App] Kill"
    whoami
    echo "<<< [Test-App] killed"
    ;;

  cleanup)
    echo ">>> [Test-App] Cleanup"
    whoami
    echo "<<< [Test-App] cleaned"
    ;;

  install)
    echo ">>> [Test-App] Install"
    whoami
    echo "<<< [Test-App] installed"
    ;;

  deinstall)
    echo ">>> [Test-App] Deinstall"
    echo "<<< [Test-App] deinstalled"
    ;;

esac

exit 0
