# ---------------------------------------------------------------------------- # $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