Flack1Manual

Flack 1 Manual

This document describes the deprecated version of Flack, the map client for ProtoGENI and federated GENI managers.

Terms

If you are new to the GENI world you may need to know what some of the terms mean. Users register at an authority which gives them the credentials they need to allocate resources which are advertised at various managers. To reserve resources (nodes, links, etc.), users must first create or be added to a slice. Slices are containers issued by authorities which allow users to ask managers for resources. Resources are issued by managers to users in the form of a sliver. A sliver contains all the resources assigned to a user's slice from one manager. If a user asks for resources from more than one manager then they would have one slice and multiple slivers. Resources are described using RSPECs, formally defined lists of resources. Advertisement RSPECs are listings of resources at a manager, request RSPECs are listings of resources a user wants and manifest RSPECs are listings of resources the user gets. Resources described in request RSPECs can be bound to a specific resource (ex. pc143) or unbound if the user simply desires any resource of a certain type (ex. any exclusive pc).

Setup

Becoming a User

In order to log in, you need to sign up with a ProtoGENI-federated GENI authority which issues you a SSL certificate. Emulab sites, such as emulab.net, serve as GENI authorities and provide you with a compatible SSL certificate. If you are already a user at one of the Emulab sites, you are ready to use Flack and can skip to logging in. If you aren't already set up at an Emulab site, follow these directions to get an account.

Logging In

Select your authority from the top right menu and click 'Download.' If you are already logged in to your authority's website your certificate will be automatically downloaded and added into the log in window. Otherwise you will be prompted to sign into your authority and return to Flack and hit Download again.

An alternative to this method is to manually insert your private key and certificate into the window.

Once you have your private key and certificate entered just type enter your passphrase in the bottom field. Check the Remember box if you don't want to enter the passphrase each time you start Flack. Once you hit enter, Flack will load all of the component managers and slices for you. Once everything loads then you are ready to create experiments.

For a brief overview of allocating resources, see the Flack tutorial.

Basics

Main Interface

The basic screen is split into three parts:

Top bar

Open the console to view information for sent, received and queued requests
Search in all resources
Clear and reload all data
View and edit your user data
You may see some text and a spinning icon in the middle, this will indicate status from the request queue
Reset the zoom
View the client in full-screen mode
View the about window

Map

Inspect resources geographically
Markers will be colored according to their manager and will indicate how many total nodes are at the location or in the cluster if multiple markers are combined.

Legend (right side of map)

User operations (if you are logged in)
- Create a slice with the given name
- Clear and reload all user data including slices
- Optionally draw only all or individual slice resources allocated to the user
- Click on a slice name to view
Managers
- Show/hide individual or all of the managers
- Click on a manager name to view
  - Color of the button is the same as the manager's markers on the map

Interacting With the Map

You may easily view ProtoGENI-federated resources available through the map or manager windows. Aggregate Managers like PlanetLab that have implemented the GENI AM API are also shown.

As managers report what resources they have, you will see resources constantly added to the map according to where they are located. Groups of nodes are clustered together and those clusters are also clustered together depending on the level of zoom. Click on the icons with the numbers (which specify the number of nodes at that site or area or the bandwidth of links) if you would like to see more information about the links or nodes.

By default the entire ProtoGENI federation is drawn on the map. You may also limit the view to one or all of your slice resources.

If you can't find a resource in a location you think you should, zoom out to make sure the location hasn't been changed to some extreme value. As of this writing, nodes without location information are placed in Antarctica.

Debugging

If you experience any problems, chances are that you can find out more information by looking at the console (left most in the top bar). If Flack makes any XML-RPC call, the request and response will both be logged. Errors encountered when making requests or anywhere else will be logged here as well.

When you open up the console, you will see previously sent requests and responses on the left (Log) and current or future requests on the right (Queue). Click on any request or error message to get more information. If you would like to stop or start the queue, click on the appropriate button at the top in the Queue section.

Typically the console will pop up if there is a major error and Flack cannot continue. If that occurs you should probably investigate further and perhaps send an error report.

Common Tasks

Creating and Opening Slices

Your list of slices will be near the top of the map legend. If you don't have any slices listed, you will need to create a slice.

Above where your slices are listed at the top of the map legend, you can type the name of a slice and hit enter. If a blank canvas appears with the name you typed in, that means your slice was created successfully and you are ready to add resources.

Slice Window

The slice window is partitioned into four zones:

Top (General Info)
- Documents Recieved
  - Save the slice credential to file
  - View the manifest RSPECs
  - If there is a flag showing, click it to see the slice's status
- Name
- Canvas
  - Clear
- Import
  - Import by pasting an RSPEC
  - Import an RSPEC from file
  - Import an RSPEC from a URL
- Select what RSPEC version to use (leave as is unless you know you need a different version)
- Preview
  - See what the RSPEC looks like for the current canvas
  - Save the preview RSPEC to file
- Clear and reload all data about this slice

Left (Resources)
- Default View (Managers)
  - Drag unbound nodes onto the canvas (Unavailable options mean a manager doesn't support it)
    - View bound nodes for this manager (Manager View)
    - Exclusive node
    - Shared node
    - Delay node
- Manager/Nodes View
  - Drag bound nodes from the list. For managers, unbound nodes will also be listed at the top.
    - Filter nodes by availability or type
    - Available node | Unavailable
- Dashboard View
  - View the current status of each sliver in the slice.
    - A spinner indicates that operations are happening or waiting for this manager
    - View the manifest
    - View logs for only this manager

Right (Canvas)
- Nodes are colored based on what manager they are from and links are colored based on what type of a link they are
- Delete the node/link
- View and edit
- Start dragging a link

Bottom: Actions.
- Create or update the slice
- Start the slivers
- Stop the slivers
- Delete the slivers
- View the amount of time before the slice/slivers expire
- Extend the slice/slivers for a period of time beyond the expires time
- INSTOOLS options
  - Instrumentize a slice with INSTOOLS
  - Visit the INSTOOLS portal

Editing Slice Resources

To create your desired configuration, you may drag nodes from various places throughout the interface and drag links from one node to another. To add nodes, you may drag nodes from their component manager by finding them in the list next to the slice canvas, markers from the map, or nodes from any other list throughout the interface (like after clicking on a marker and seeing the list of nodes).

To edit properties, click on the information button () located on the node or link, edit what you need and apply the changes.

Node Window

General
- Manifest
- Status
- Preview
Remote Access
- Hostname
- SSH
- Web
Basic
- Binding
- Disk Image
- Install
- Execute
Extensions
- Extensions from the RSPEC. You can paste your own in, but they must have their namespaces declared.
Links to
- List of nodes and the interfaces used which are connected

Link Window

General
- Manifest
- Status
- Preview
Type
- LAN, Tunnel, ION, etc.
Bandwidth
Connects
- List of interfaces and properties

Submitting Changes

Once you are ready to allocate the resources from the canvas, click the Create button () and wait until the slice and slivers are created to confirm the experiment was successfully created. By default, the status of the slice is refreshed automatically until the slice is ready or failed (though you can turn it off and manually refresh). If there is a failure, you will see red and the console might pop up. Look at the most recent failure in the console for details regarding the error. If the error is related to an individual node, you will see the node name change to red and you may mouse over the node (or click on the information button ) to read the specific error message.

Troubleshooting

If you are having trouble, email user mstrum on the domain flux dot utah dot edu. I will try to help you and improve these instructions to suit.

Nothing seems to be happening no matter what I do!
- Make sure you've followed the above directions.

Non-users

Manager Admins

If your manager is not listed in Flack, that means it is either not federated or is currently disabled from being shown due to previously not working.

If your manager is listed in Flack but is not loading successfully, you may not have added the Flash socket security policy server to your manager. In order to communicate with each manager, Flack asks for a Flash security policy on port 843. If the policy is returned and allows Flack to communicate with the server then everything should work. If no policy is being delivered on that port, the manager will not work in Flack.

To test whether your manager is running a Flash socket security policy, telnet to port 843. If you see a XML document returned that means the policy server is installed but the problem may be in the policy itself or somewhere else. If you do not see anything returned, you need to add the Flash socket security policy.

Here is an example of what a policy should look like (this example is Planet-Lab's policy):

<?xml version="1.0"?>
<!DOCTYPE cross-domain-policy SYSTEM "/xml/dtds/cross-domain-policy.dtd">

<cross-domain-policy>
 <site-control permitted-cross-domain-policies="master-only"/>
 <allow-access-from domain="*" to-ports="80,443,12345,12346,12347" />
</cross-domain-policy>

Here is the policy run at emulab.net

<cross-domain-policy>
 <site-control permitted-cross-domain-policies="master-only"/>
 <allow-access-from domain="*" to-ports="80,443"/>
</cross-domain-policy>

Basically any port that Flack will be communicating with needs to be listed.

Adding a Flash Socket Security Policy Server

You have multiple options to select from.

(1) inetd Configuration

Add the following line to your /etc/inetd.conf file:

flashpolicy stream tcp nowait root /bin/echo /bin/echo '<cross-domain-policy> <site-control permitted-cross-domain-policies="master-only"/> <allow-access-from domain="*" to-ports="443"/> </cross-domain-policy>'

And the following line to your /etc/services file:

flashpolicy     843/tcp

Make sure to restart the inetd service afterwards. Also, make sure your firewall rules permit a server running on port 843.

(2) Python/Perl Server

Download the sample files from the following article: http://www.adobe.com/devnet/flashplayer/articles/socket_policy_files.html

Make sure that port 443 is included in the ports which are allowed access.

Embedding Flack

To embed Flack into your website, simply include the following on the page you would like Flack to run on:

<iframe style="height: 600px; width: 100%;" src="https://www.emulab.net/protogeni/flack.html"></iframe>

Hosting Flack

You are recommended to embed Flack rather than host it yourself. That will allow you to always have the most current version. If you still wish to host your own copy of Flack, follow the directions below.

When embedding Flack into your website, there is one required Flash parameter (if running on a different server than ours) and various optional parameters to allow some customization. Flash parameters should be added to the end of the path to the SWF. In the example below of what the HTML should look like when embedding the flash client, you will notice that there is a variable of 'mode' with a value of 'publiconly' in two places (object.param[movie].value and embed.@src). For each additional parameter, simple add an ampersand (&) and another variable=value.

Variables

mode - Set the mode to Public (public), Public-only (publiconly) or Authenticated (authenticate)
mapkey - Set the Google Maps API key for the domain where the map client is located. Google Maps requires this value to be set for each domain, which means this parameter is required if you want to run the flash client on your own server. Visit http://code.google.com/apis/maps/signup.html to get an API key for your domain.
saurl - Force the client to use a certain Slice Authority. Give the url, like https://www.emulab.net/protogeni/xmlrpc for the Utah SA, to set.
debug (1=on) - Enables any debug output (currently just opens the console on start).
usejs (1=on) - Required to use JavaScript support
pgonly (1=on) - Only deal with ProtoGENI resources
publicurl - URL of the public RSPEC

Example embed code:

<object classid="clsid:D27CDB6E-AE6D-11cf-96B8-444553540000"
	id="pgmap" width="900" height="600" align="middle"
	codebase="http://fpdownload.macromedia.com/get/flashplayer/current/swflash.cab">
		<param name="movie" value="https://www.emulab.net/protogeni/flack.swf?mode=public" />
		<param name="quality" value="high" />
		<param name="bgcolor" value="#d2e1f0" />
		<param name="allowScriptAccess" value="sameDomain" />
            	<param name="allowFullScreen" value="true" /> 
		<embed src="https://www.emulab.net/protogeni/flack.swf?mode=public" bgcolor="#d2e1f0"	
			width="900" height="600" align="middle"
			name="pgmap"
			play="true"
			loop="false"
			quality="high"
			allowScriptAccess="sameDomain"
                	allowFullScreen="true"
			type="application/x-shockwave-flash"
			pluginspage="http://www.adobe.com/go/getflashplayer">
		</embed>
</object>

Compiling and Running Flack

Anonymous GIT repository: git://git-public.flux.utah.edu/emulab-devel.git
- Flack may be found in emulab-devel/protogeni/flack

In order to compile Flack, you will need either the freely available Flex 4.5+ SDK to build from the command line or the commercial Flash Builder to automate the process. Flash Builder is offered free for academic use (https://freeriatools.adobe.com).

If you are compiling Flack using the Flex SDK on a command line, you need to hand the mxml compiler the config.xml file located in the Flack directory.

Once you are able to compile flack, put flack.swf into the js/ folder and copy that folder's contents where you would like to run Flack. You can run it on your local machine, but be aware that due to the differences in Flash's security policy you may see different behavior when you upload the files and run them through the internet.