DSMT User's Guide DSMTGuide.php docs.css DSMTGuide
Overview overview Access to the Distributed Service Management Toolkit (DSMT) is provided by the dsmtc command line interface. In order to create a managed slice, your application must be packaged as an RPM
Quick Start quickstart

To create a managed slice from scratch:

$ dsmtc create --slice slicename

To start managing an existing slice:

$ dsmtc manage --slice slicename

To set a node (distribution) plan for a slice

$ dsmtc setplan --slice slicename --plan planname [key=value]*

To set an agent (management) plan for a slice

$ dsmt setagent --slice slicename --agent agentname [key=value]*
Authentication authentication

PlanetLab uses two methods of authentication:

  • Password authentication - for operations on the PlanetLab Central database
  • SSH authentication - for logging into a slice

The toolkit uses your PlanetLab account Id (email address) to authenticate with PLC, whilst authentication with the management service utilizes your ssh key.

Slice Creation slicecreation Slice creation can only be performed by users with the PlanetLab role of 'pi' or 'admin'. The toolkit provides support for creation of managed or un-managed slices.
Managed Slice Creation managedslicecreation

The dsmtc create command will perform all necessary steps to create a create a slice with PlanetLab and establish management on that slice.

$ dsmtc create --slice slicename \
            [ --agent agentname [key=value]* ] \
            [ --plan planname [key=value]* ] \
            [ --user user.name@some.domain ] \
            [ --node planetlab.node.name ]
Unmanaged Slice Creation unmanagedslicecreation

First create the node with PlanetLab central

$ dsmtc plc create --slice idsl_test1

Then add any users (including yourself)

$ dsmtc plc addusers --user paul.brett@intel.com --slice idsl_test1

Now add the nodes you wish to use

$ dsmtc plc addnodes --node planetlab1.nbgisp.com --node planetlab3.nbgisp.com --slice idsl_test1

Set the instantiation method

$ dsmtc plc setInstantiationMethod --method plc --slice idsl_test1

And finally start the slice

$ dsmtc plc start --slice idsl_test1
Package Management packagemanagement

Package management is currently in development. Currently developers must login to alpha and upload rpms into the correct yum repository. In the near future, a 'depot' interface will be provided with the following commands:

To copy a file from your desktop to the depot:

$ dsmtc depot put filename

To copy a file from the depot to your desktop:

$ dsmtc depot get filename

To list the files in the depot:

$ dsmtc depot ls

To remove a file from the depot:

$ dsmtc depot rm filename

To create any required indexes on the directory (e.g. run yum-arch):

$ dsmtc depot index
Node Management nodemanagement

Node assignment for managed slices can either be performed manually by the user or by using a deploymment plan.

Manual deployment manualdeployment

When no deployment plan has been specified with the --plan option, the management service will maintain your application on all nodes currently assigned to the slice. This list of nodes can be maintained by using the PlanetLab web interface or the dsmtc plc sub-commands:

To list the currently assigned nodes:

$ dsmtc plc listnodes --slice idsl_jpet1
planetlab2.pop-mg.rnp.br
planetlab1.pop-ce.rnp.br
planetlab2.pop-rj.rnp.br
planetlab2.pop-rs.rnp.br

To add nodes

$ dsmtc plc addnodes --node planetlab1.nbgisp.com --node planetlab3.nbgisp.com

To delete nodes

$ dsmtc plc delnodes --node planetlab1.pop-ce.rnp.br --node planetlab2.pop-rj.rnp.br
Built-in Deployment plans builtindeploymentplans

Deployment plans provide a managed set of nodes upon which to install your application. In general, deployment plans attempt to find sets of nodes which match your requirements whilst minimizing the number of changes to the node set during the evaluation of each step of the plan.

You can query for a list of deployment plans for your slice using:

$ dsmtc plan ls
# name                        attributes
all_nodes
failed                        penalty=86400 running=14400 request=900 install=14400
geographical_filter   maxlat=90.0 minlat=-90.0 parent= maxlng=180.0 minlng=-180.0
hostname_filter       parent= prefix= suffix=
intersection                  right= left=
limit                         parent= count=0
manual
minus                         right= left=
n_per_site                    parent= count=0
no_nodes
plc
sword                         refresh=0 query=
union                         right= left=

A detailed description for each deployment plan, including the nodeset to which it would currently evaluate is available utilizing the get command, e.g. 

$ dsmtc plan get --plan all_nodes

New plans can be established based on existing plans using the set command.

$ dsmtc plan set --plan newplan --base existingplan key1=value1 key2=value2 ...

Unused user defined plans can be removed from a slice using the rm command.

$ dsmtc plan rm --plan oldplan
All Nodes all_nodes

The all nodes deployment plan provides a set of all the live nodes in the PlanetLab database (i.e. all nodes listed in sites.xml

$ dsmtc plan get --plan all_nodes
# name                        attributes  description
all_nodes                              All bootable nodes according to the PLC database
# nodelist
[planet1.cs.ucsb.edu, planet1.scs.cs.nyu.edu, planet2.scs.cs.nyu.edu, planetlab-1.stanford
.edu, ricepl-1.cs.rice.edu, planet1.cc.gt.atl.ga.us, planetlab1.arizona-gigapop.net, plane
tlab2.arizona-gigapop.net, pl1.cs.utk.edu, pl2.cs.utk.edu, planetlab1.diku.dk, ... ]
Failed Nodes failed

The failed nodes deployment plan provides a set of nodes upon which the installation of this slice has been recently attempted, but has failed. This plan is usually combined with the 'minus' plan to remove failed nodes from a compond deployment plan. 

$ dsmtc plan get --plan failed
# name                        attributes  description
failed                        penalty=86400 running=14400 request=900 install=14400  Set
of nodes which have failed to install
# nodelist
[planetlab3.nbgisp.com, planet2.ottawa.canet4.nodes.planet-lab.org, planetlab8.nbgisp.com,
planetlab7.nbgisp.com, planetlab2.nbgisp.com, mycroft.nbgisp.com]

The failed nodes deployment plan can be tuned in order to establish the timeouts required for each of the states. All timeout parameters are specified in seconds.

  • request
    • timeout is the period of time between the node being selected into the deployment set, and the node being assigned by PLC
  • install
    • timeout is the period between the sliver being requested with PLC, and the sliver completing installation
  • running
    • timeout is the period between successive heartbeats being recieved by the container manager
  • penalty
    • is the period of time this node will remain in the failed node set

Example:

$ dsmtc plan set --plan good_nodes --base minus left=all_nodes right=failed
$ dsmtc plan set --plan 10_good_nodes --base limit count=10 parent=good_nodes
$ dsmtc plan get --plan 10_good_nodes
# name                        attributes  description
10_good_nodes                 parent=good_nodes count=10  At most 'count' nodes
# nodelist
[planet1.cs.ucsb.edu, planet1.scs.cs.nyu.edu, planet2.scs.cs.nyu.edu, planetlab-1.stanford
.edu, ricepl-1.cs.rice.edu, planet1.cc.gt.atl.ga.us, planetlab1.arizona-gigapop.net, plane
tlab2.arizona-gigapop.net, pl1.cs.utk.edu, pl2.cs.utk.edu]
Geographical filtering of nodes geographical_filter

The geographical filtered nodes plan allows nodes to be filtered based on site latitude/longitude from the PlanetLab database. Sites in the database without valid lat/long data will be ommitted. 

$ dsmtc plan get --plan geographical_filter
# name                        attributes  description
geographical_filter   maxlat=90.0 minlat=-90.0 parent= maxlng=180.0 minlng=-180.0
All nodes within the bounding box set with min/max lat/lng
# nodelist
[]

Examples:

$ dsmtc plan set --base geographical_filter --plan north_american_nodes \
                 minlat=0 maxlat=90 minlng=-150 maxlng=-55 parent=all_nodes
$ dsmtc plan set --base geographical_filter --plan european_nodes \
                 minlat=40 maxlat=90 minlng=-10 maxlng=60 parent=all_nodes
$ dsmtc plan set --base geographical_filter --plan south_american_nodes \
                 minlat=-90 maxlat=0 minlng=-90 maxlng=-30 parent=all_nodes
$ dsmtc plan set --base geographical_filter --plan australian_nodes \
                 minlat=-90 maxlat=0 minlng=105 maxlng=160 parent=all_nodes
Hostname filtering of nodes hostname_filter

The hostname filtered plan allows filters nodes based on the prefix and/or suffix of the hostname 

$ dsmtc plan get --plan hostname_filter
# name                        attributes  description
hostname_filter       parent= prefix= suffix=  All nodes starting with 'prefix' an
d ending with 'suffix'
# nodelist
[]

Examples:

$ dsmtc plan set --plan internet2_nodes suffix=internet2.planet-lab.org \
                 --base hostname_filter parent=all_nodes
$ dsmtc plan set --plan canet4_nodes suffix=canet4.nodes.planet-lab.org \
                 --base hostname_filter parent=all_nodes
Set intersection intersection

The intersection operation provides the ability to specify the overlap between two different node plans. 

$ dsmtc plan get --plan intersection
# name                        attributes  description
intersection                  right= left=  All nodes in both the 'left' and 'right' plans
# nodelist
[]

Example:

$ dsmtc plan set --plan com_nodes --base hostname_filter suffix=.com
plan set --plan european_com_nodes --base intersection left=com_nodes right=european_nodes
plan get --plan european_com_nodes
# name                        attributes  description                           
european_com_nodes            right=european_nodes left=com_nodes  All nodes in both the '
left' and 'right' plans 
# nodelist                                                                      
[pli1-br-2.hpl.hp.com, pli1-br-3.hpl.hp.com, pli1-br-1.hpl.hp.com, pli2-br-2.hpl.hp.com, p
li2-br-1.hpl.hp.com, pli1-tlnx.hpl.hp.com, planetlab1.rdfrancetelecom.com, planetlab2.rdfr
ancetelecom.com]
Limiting node set limit

Providing an upper bound on the number of nodes in a set can be accomplised with the limit operation. 

$ dsmtc plan get --plan limit
# name                        attributes  description
limit                         parent= count=0  At most 'count' nodes
# nodelist
[]

Example:

$ dsmtc plan set --plan good_nodes --base minus left=all_nodes right=failed
$ dsmtc plan set --plan 10_good_nodes --base limit count=10 parent=good_nodes
$ dsmtc plan get --plan 10_good_nodes
# name                        attributes  description
10_good_nodes                 parent=good_nodes count=10  At most 'count' nodes
# nodelist
[planet1.cs.ucsb.edu, planet1.scs.cs.nyu.edu, planet2.scs.cs.nyu.edu, planetlab-1.stanford
.edu, ricepl-1.cs.rice.edu, planet1.cc.gt.atl.ga.us, planetlab1.arizona-gigapop.net, plane
tlab2.arizona-gigapop.net, pl1.cs.utk.edu, pl2.cs.utk.edu]

Important : Limit should almost always be used at the outermost level of your node plan. The following plan is not equivalent: 

$ dsmtc plan set --plan 10_nodes --base limit count=10 parent=all_nodes
$ dsmtc plan set --plan good_10_nodes --base minus left=10_nodes right=failed
Manual control of nodes manual

The manual control plan allows for user selection of the node set. 

$ # name                        attributes  description
manual                        nodes=      Manual control - provide a white space separated
list of nodes
# nodelist
[]

Example:

$ dsmtc plan set --plan mynodes --base manual nodes=@nodes.txt
$ dsmtc plan get mynodes
Error: Unrecognized command line option mynodes
dsmtc paul.brett@intel.com [pi] idsl_pfb_test_1> plan get --plan mynodes
# name                        attributes  description                           
mynodes                       nodes=planetlab3.nbgisp.complanetlab1.nbgisp.com  Manual con
trol - provide a white space separated list of nodes 
# nodelist                                                                      
[planetlab3.nbgisp.com, planetlab1.nbgisp.com]
Set minus minus

The minus plan allows nodes from one plan to be excluded from another plan. 

$ dsmtc plan get --plan minus
# name                        attributes  description
minus                         right= left=  All nodes in the 'left' plan, but not in the '
right' plan
# nodelist
[]

Example:

$ dsmtc plan set --plan internet2_nodes suffix=internet2.planet-lab.org \
                 --base hostname_filter parent=all_nodes
$ dsmtc plan set --plan not_i2_nodes --base minus left=all_nodes right=internet2_nodes
$ dsmtc plan set --plan canet4_nodes suffix=canet4.nodes.planet-lab.org \
                 --base hostname_filter parent=all_nodes
$ dsmtc plan set --plan i1_nodes --base minus left=not_i2_nodes right=canet4_nodes
$ dsmtc plan get --plan i1_nodes
# name                        attributes  description                           
i1_nodes                      right=canet4_nodes left=not_i2_nodes  All nodes in the 'left
' plan, but not in the 'right' plan 
# nodelist                                                                      
[planet1.cs.ucsb.edu, planet1.scs.cs.nyu.edu, planet2.scs.cs.nyu.edu, planetlab-1.stanford
.edu, ricepl-1.cs.rice.edu, planet1.cc.gt.atl.ga.us, planetlab1.arizona-gigapop.net, ... ]
Selecting every site n_per_site

A common requirement on PlanetLab is to run an experiment or service at a group of sites, which requires a single instance to be assigned once per site. This can be achieved with the n_per_site plan. 

$ dsmtc plan get --plan n_per_site
# name                        attributes  description
n_per_site                    parent= count=0  At most 'count' nodes per site
# nodelist
[]

Example:

$ dsmtc plan set --plan i2_1_per_site --base n_per_site count=1 parent=internet2_nodes
$ dsmtc plan get --plan i2_1_per_site
# name                        attributes  description                           
i2_1_per_site                 parent=internet2_nodes count=1  At most 'count' nodes per site        
# nodelist                                                                      
[planetlab1.nycm.internet2.planet-lab.org, planetlab1.ipls.internet2.planet-lab.org, plane
tlab2.sttl.internet2.planet-lab.org, planetlab1.chin.internet2.planet-lab.org, ... ]
Empty nodeset no_nodes

The empty node set provides a mechanism for a slice to be removed from all nodes without deleting the slice from PlanetLab. 

$ dsmtc plan get --plan no_nodes
# name                        attributes  description
no_nodes                                  No nodes
# nodelist
[]
PLC Controlled plc

The PLC controlled site plan disables node management within DSMT. The nodelist of current nodes in the slice will be downloaded from PLC, and any changes made at PLC (via either the web interface, or dsmtc's plc sub-menu will be honored. 

$ dsmtc plan get --plan plc
# name                        attributes  description
plc                                       PLC Controlled - use plc add/del nodes
# nodelist
[planetlab3.nbgisp.com, planetlab1.nbgisp.com, planet1.ottawa.canet4.nodes.planet-lab.org,
planetlab8.nbgisp.com, planetlab7.nbgisp.com, planetlab4.nbgisp.com, ... ]
Sword selected sword

The Sword plan generates queries to David Oppenheimer 's Scalable Wide-Area Resource Discovery tool to perform node selection. 

$ dsmtc plan get --plan sword
# name                        attributes  description                           
sword                         refresh=0 query=  Query using Scalable Wide-Area Resource Di
scovery (http://www.swordrd.org/ 
# nodelist                                                                      
[]

Example:

$ dsmtc plan set --plan sword_20 --base sword query=@sword.txt refresh=3600
$ dsmtc plan get --plan sword_20
# name                        attributes  description                           
sword_20                      refresh=3600 query=<request>
   <group>
      <name>LowLoad</name>
      <numhosts>20</numhosts>
      <num_machines>all</num_machines>
      <load_one>0.0,0.0,5.0,5.0,0.0</load_one>
   </group>
</request>  Query using Scalable Wide-Area Resource Discovery (http://www.swordrd.org/ 
# nodelist                                                                      
[planet3.pittsburgh.intel-research.net, planetlab3.xeno.cl.cam.ac.uk, ... ]
Set union union

The union operation provides the ability to specify the combination of two different node plans. 

$ plan get --plan union 
# name                        attributes  description                           
union                         right= left=  All nodes in either the 'left' or 'right' plan 
# nodelist                                                                      
[]

Example:

$ plan set --plan berkeley_edu_nodes --base hostname_filter \
         suffix=berkeley.edu
$ dsmtc plan set --plan berkeley_intel_nodes --base hostname_filter \
         suffix=berkeley.intel-research.net
$ dsmtc plan set --plan berkeley_nodes --base union left=berkeley_edu_nodes \
         right=berkeley_intel_nodes
$ dsmtc plan get --plan berkeley_nodes
# name                        attributes  description                           
berkeley_nodes                right=berkeley_intel_nodes left=berkeley_edu_nodes  All node
s in either the 'left' or 'right' plan 
# nodelist                                                                      
[planetlab4.millennium.berkeley.edu, planetlab12.millennium.berkeley.edu, planetlab5.mille
nnium.berkeley.edu, ... planet1.berkeley.intel-research.net]

A deployment plan can be established on your managed slice using the setplan command 

$ dsmtc setplan --plan internet2_nodes --slice idsl_jpet1
Custom deployment plans customplans

The built-in deployment plans can be composed together to provide fine grained control over the placement of an application. To illustrate plan composition, we will construct a deployment plan for a distributed service with the following requirements:

  • The service requires a presence in europe, north america, south america and australia
  • In each geography, four working nodes are required. For redundancy, none of the node in a geography may be at the same site.
  • The nodes must not be hosted by Internet2 or Canarie.
  • If the node is down for more than one hour, it should be replaced with another node. Installation time for any node should be limited to a maximum of 4 hours.

Create a list of nodes which meet the installation and service uptime requirements. 

$ dsmtc plan set --plan badnodes --base failed running=3600 install=14400

And exclude these nodes from the available node list

$ dsmtc plan set --plan nobadnodes --base minus left=all_nodes right=badnodes

Create a list of internet2 and canarie nodes, and exclude them from the available nodes

$ dsmtc plan set --plan internet2_nodes \
                 --base hostname_filter suffix=internet2.planet-lab.org parent=all_nodes
$ dsmtc plan set --plan canet4_nodes \
                 --base hostname_filter parent=all_nodes suffix=canet4.nodes.planet-lab.org 
$ dsmtc plan set --plan nobad_noi2_nodes --base minus left=nobadnodes right=internet2_nodes
$ dsmtc plan set --plan good_nodes --base minus left=nobad_noi2_nodes right=canet4_nodes

Create node groups for each of the geographies

$ dsmtc plan set --base geographical_filter --plan north_american_nodes \
                 minlat=0 maxlat=90 minlng=-150 maxlng=-55 parent=good_nodes
$ dsmtc plan set --base geographical_filter --plan european_nodes \
                 minlat=40 maxlat=90 minlng=-10 maxlng=60 parent=good_nodes
$ dsmts plan set --base geographical_filter --plan south_american_nodes \
                 minlat=-90 maxlat=0 minlng=-90 maxlng=-30 parent=good_nodes
$ dsmtc plan set --base geographical_filter --plan australian_nodes \
                 minlat=-90 maxlat=0 minlng=105 maxlng=160 parent=good_nodes

Limit each geography to four nodes

$ dsmtc plan set --plan north_american_four --base limit parent=north_american_nodes count=4
$ dsmtc plan set --plan european_four --base limit parent=european_nodes count=4
$ dsmtc plan set --plan south_american_four --base limit parent=south_american_nodes count=4
$ dsmtc plan set --plan australian_four --base limit parent=australian_nodes count=4

Join the regions together

$ dsmtc plan set --plan american_eight --base union left=north_american_four right=south_american_four
$ dsmtc plan set --plan nonamerican_eight --base union left=european_four right=australian_four 
$ dsmtc plan set --plan appnodes --base union left=american_eight right=nonamerican_eight

And finally, activate the plan

$dsmtc setplan --plan appnodes
Files Files
.slices slices

The $HOME/.slices file contains configuration information required to authenticate the the PlanetLab central API. This configuration file can be shared with the plslice command (part of the pldeploy package), and has the following format: 

slice: slicename
account: email address
password: plain text password
server: url to PLC API
role: PLC role name
All items are optional, and can alternativly be specified on the command line.
ssh identity ssh Authentication with DSMT currently uses the ssh key uploaded into PlanetLab. Your key will be searched for in the following locations 
$HOME/.ssh/id_rsa
$HOME/.ssh/id_dsa
$HOME/.ssh/identity
The dsmtc client includes an inbuilt ssh client, and does not currently recognize options in the $HOME/.ssh/config file. Proxies are also currently not supported.