Flack Manual

This document describes Flack, the map client for ProtoGENI and federated GENI managers. For the older manual for Flack 1 (deprecated), see the Flack 1 manual.

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 continue to the next step: logging in. If you aren't already set up at an Emulab site, first follow these directions to get an account. Once you have your account set up, come back to this page and continue on with the next section.

Logging In

Select your authority from the top right menu and click Download. If your authority is not listed, click Add next to the list and fill out the information for your authority. 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 downloading your private key and certificate automatically is to manually enter them (open from file or paste).

Once your private key and certificate have been added, Flack will detect and display your username and authority under the private key/certificate area.

If your private key is encrypted, you will be prompted at the bottom of the log in window for the passphrase. If you don't want to type it in every time, click Remember.

Once you hit enter (or click the OK button), Flack will load all of the 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

• Near the left, you will see a spinner and some status text if any task is being performed
• View the client in full-screen mode
• View the about window (view credits, delete cache, and view/edit the SSL certificate bundle)

Left Pane

• Main
  • Slices
    • View and edit your user information, including public keys added onto allocated resources
    • Clear and reload all user data including slices
    • Create a slice with the given name and authority/sub-authority selected above it
    • Toggle 'Show' to view user resources on the map instead of all advertised resources
      • Select 'All' or individual slices to limit what is mapped
    • Click on a slice name to view/edit the slice
  • Managers
    • Clear and reload all managers
    • Add a new manager not listed (select 'cache' so it shows up next time Flack is opened)
    • Toggle 'Show/Hide' to select all or none of the managers
    • For each manager,
      • there is either a spinner if it is loading, retry button if there were errors, or a checkbox to select whether to view resources from that manager on them map.
      • click on the button to inspect the manager (view advertisements, version info, etc.)
• Search
  • Toggle 'Map' to view only the search results
  • Type part of a name or select any of the other attributes to limit search results
  • Click on a node name to view or drag the node name to a slice canvas to allocate the node
• Tasks
  • Any running group of tasks are shown and can be clicked on to see more details
  • Click 'Tasks & Logs' to view all tasks and related logs

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.
  • Drag markers into the slice pane to allocate nodes in a certain area (available in the slice area)
• Limit mapped resources to
  1. user-allocated resources from all slices or a particular slice (available in the user section of the main pane)
  2. all or certain managers (in the managers section of the main pane)
  3. search results (in the search pane)

Interacting With the Map

You may easily view GENI resources available through the map or by clicking on individual managers in the left pane. By default, only ProtoGENI-federated resources are shown but you can manually add any manager that implements the GENI AM API. By default, all managers are shown on the map. Select the checkboxes in the left pane in the managers section to show or hide all or certain managers.

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 nodes. You can also click on any visible links which are also grouped together.

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 the middle of the Atlantic Ocean.

Debugging

If you experience any problems, chances are that you can find out more information by looking at the tasks and logs (top button in the left tasks pane). Everything that happens in Flack is implemented as a task. In the tasks and logs area, you will see a list of tasks on the left organized by when tasks were added and placed in their hierarchical structure. On the right is a list of logs (by default, all logs) organized from oldest to newest. If you click on a task, the logs will only show you the logs related to that task. You can click on 'Tasker' at the top of the list of tasks to view all logs again. You can view more details about any log by clicking on the title in the log list. Many useful logs help like determining the XML-RPC values sent or received by Flack (all are logged).

Typically an error log window 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 Slices section of the main left pane. If you don't have any slices listed, you will need to create a slice.

Above where your list of slices, 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. If the slice name is invalid (like if another user is using the same name), you will be prompted for a different name.

Slice Area

The slice area is partitioned into two zones:

1. Dashboard (on the left)
   1. (at the bottom) Submit will perform all actions to allocate the resources for the slice and reload will clear all data
   2. Resources
      • 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
        • Firewall node
      • Manager/Nodes View
        • Drag bound nodes from the list.
        • Filter nodes using the available options
   3. Slice Details and Actions
      1. Top options
         • Get Status refreshes the status of all the resources
         • The home icon will let you view login information for your allocated resources
         • Save the slice credential to file
         • View logs related to the slice
         • View the manifest RSPECs
      2. Slivers, view the current status of each sliver in the slice
         • Manager name is shown along with a spinner if any task related to the sliver is being run
         • Perform operations on the sliver though the menu button, like view logs or the manifest, stop/start/restart, and delete
      3. Actions
         • Delete all of the known slivers or run delete everywhere for a more thorough cleanup
         • Start the slivers
         • Stop the slivers
         • View the amount of time remaining before the soonest resource expires and extend if needed
   4. Plugins
      • Select any plugin from the menu to see its interface
        • INSTOOLS
          • Instrumentize a slice with INSTOOLS
          • Visit the INSTOOLS portal
2. Canvas (on the right)
   1. Top bar
      • Select a list or graph view
      • Clear all resources and history
      • Import a RSPEC (save RSPECs by previewing and saving the previews or save the manifests)
      • Undo or redo actions
      • Clone a selected node
      • Select an output RSPEC version
      • Preview the output RSPEC
      • Pop out
   2. 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
      • To create a link, bring the mouse near a node and start dragging to another node

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.