Skip to content. | Skip to navigation

Personal tools

Navigation

You are here: Home / Wiki / Flackmanual

Flackmanual

Flack Manual

Flack Manual

This document describes Flack, the visual 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 issues them a certificate and gives them the credentials they need to present when allocating 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 slivers. Slivers contain addressable resources assigned to a user's slice from a manager. If a user asks for resources from more than one manager then they would have one slice and multiple slivers from different managers. 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 certificate and private key. Emulab sites, such as emulab.net, serve as GENI authorities and provide you with a compatible certificate and private key. 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

Important: Currently there is a large difference in what Flack supports for ProtoGENI and non-ProtoGENI users. If you are a ProtoGENI user, you will get a fairly streamlined log in experience and have full capabilities to view existing slices and create new ones. For non-ProtoGENI users you will have to manually input your cert/key as well as provide a slice or user credential after which you won't have the ability to view any existing slices and can only edit a slice if you gave a slice credential (meaning you can only work on that one slice).

When logging in, you should see the following window:

login.png

Certificate(s) and Private Key

First, you need to select your authority and import your certificate(s) and private key. You will find all of the controls you need in the red boxed area in the login window image above. Select your authority's hostname from the top right menu and click Download to the left. 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 should 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. If you sign into your authority and Flack continues to prompt you to log in, it's possible that you haven't generated your SSL certificate. In your authority's site, click 'Generate SSL Cert' on the left (in the case of Emulab) and follow the directions. Once your SSL certificate has been created, try clicking 'Download' again in Flack.

An alternative to automatically downloading your private key and certificate automatically is to manually enter them (open from file or paste). These controls are at the top left.

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, check Remember to the right.

Credential(s)

Last, you need to confirm how Flack will retrieve your credential(s). This is specified in the blue boxed area in the above image of the login window. Most likely, you can leave the default which will automatically retrieve your user and slice credentials from the selected authority. If you need to access a slice which is not registered with your authority, you will need to provide the credential yourself. You can click the open file icon and select the credential for the slice you need to access.

Continuing

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.
  • arrow_out.png View the client in full-screen mode.
  • help.png View the about window (view system info, acknowledgements, delete cache, and view/edit the trust bundle).

Left pane

  • building.png Resources (main)
    • user.png View and edit your user information, including public keys added onto allocated resources.
    • Slices
      • arrow_refresh.png Clear and reload all user data including slices.
      • wand.png Create a new slice.
      • 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
      • arrow_refresh.png Clear and reload all managers.
      • add.png 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 loading, or a checkbox to select whether to view resources from that manager on them map.
        • Click on the manager name to view its properties (advertisements, version info, resources, etc.).
  • magnifier.png Search
    • Toggle 'Map' to view only the search results on the map.
    • Type part of a name or select any of the other attributes to limit search results. Hover over an attribute to get more details.
    • Click on a node name to view its properties or drag the node name to a slice canvas to add the node to the slice.
  • system_monitor.png Tasks
    • Click 'Tasks & Logs' to view all tasks and related logs.
    • Any running group of tasks are shown, you can click the x button to cancel a task or click on the name to get more information.

Map area

  • Shown by default, hidden when new areas are pushed on top. Go back to older areas, like the Map, by clicking on the vertical bar on the left (displayed for each hidden area).
  • Inspect resources geographically.
  • Markers will be colored according to their manager (as listed in the left pane) 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 from a certain area (available in the slice area).
  • Links will be drawn and clustered according to the markers that they connect.
  • Limit mapped resources to:
    1. User-allocated resources from all slices or a particular slice (toggle Show in the Slices section in Resources on the left pane).
    2. All or certain managers (check/uncheck managers in Resources on the left pane).
    3. Search results (toggle 'Map' in Search on the left pane).

Inspecting Resources

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 using the Add button in the Managers section of Resources in the left pane. 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 based on the node markers.

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. You can also search for resources using magnifier.png Search in the left pane.

Managers and Nodes

If you are more interested in inspecting the managers which are loaded and what types of resources they have available you can do that easily as well. If you are interested in a specific manager, you can click on its name in the Managers section from building.png Resource in the left pane. The manager properties area will load and you can perform many functions like see what APIs the manager supports, view the advertisement RSPEC, see a list of sliver types the manager has, or click on and inspect the nodes or links deeper. Each of the node/link lists will allow you to filter based on various properties.

If you are more interested in inspecting nodes (like finding all pcs that you know are >= 2 GHz) then I would suggest using magnifier.png Search from the left pane. You can drill down the list of nodes based on attributes like sliver types, speeds, etc.

Troubleshooting

If you are having trouble, send an email to the protogeni-users group after doing the following:

  • Copy and paste any text from error messages that pop up.
    • Take a screenshot if selectable text isn't available or if the problem is visual.
  • If you click the copy button for log messages, your system information will be pasted as well. If you don't see system information in the text pasted into the email, please at least include the operating system, browser, and flash version. You can find that information in the help.png About window by clicking on the button at the top right in Flack.
  • Please try to describe how the error occurred and everything which led up to it. Bugs are often linked to a very specific action you may have performed like creating a link directly from node to node instead of dragging a LAN onto the canvas.

If you're a power user or feeling adventurous, you could attempt to help debug the problem on your own.

Debugging

If you experience any problems, chances are that you can find out more information by looking at system_monitor.png Tasks in the left pane. Only active tasks are listed in the left pane, so click on 'Tasks & Logs' to see all tasks. Everything that happens in Flack is implemented as a task. In Tasks & Logs, 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. You can limit the logs shown by toggling the options above the logs (like unchecking Info to see only the warnings and errors). If you click on a task, the logs list will only display logs from that (and any child) task. You can click on 'View all' at the top of the logs list to view logs from all tasks again. You can view more details about any log by clicking on the title. Many useful logs help to find errors like determining the XML-RPC values sent or received by Flack (all are logged). For example, you may want to know the exact request RSPEC that was sent in a request.

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.

Examples

I'll go through a few short examples of finding problems using the logging mechanisms built into Flack. Many issues can be solved if you look at the logs in Flack. That may mean determining a problem with an outside entity (like bad output from a manager) or bad behavior in Flack (not parsing values).

XML-RPC Error

Sometimes you may notice a problem when Flack tries to make a XML-RPC call. A valid question you must answer is whether the problem lies in bad XML-RPC output (given to or generated by Flack) or whether Flack took valid XML-RPC output and did something wrong with it. The easiest way to inspect the raw XML-RPC values passed to and from Flack is to open up the Logs & Tasks in system_monitor.png Tasks from the left pane. Once you've opened up Tasks & Logs, you can click on the task you are interested in (like a Create sliver task) which will load only the log messages for that task. If XML-RPC calls were made, you should see messages that say 'Sent request' or 'Received response.' If you click on those logs then you will see exactly what was sent to and from Flack. If you inspect those values and determine nothing is wrong, then you have to find out why Flack is misbehaving which may involve looking at more logs. Sometimes Flack will log warnings and errors indicating that something may be wrong.

One example of a problem I recently solved regarding XML-RPC values was determining that a manager was returning the correct value. After looking in the logs at the XML-RPC returned from the manager I determined that it was sending a response that wasn't formatted correctly (the returned value was an integer whereas the standard said it should be a boolean value). That was one case where Flack simply silently failed without any indication what the problem was.

Advertisement Error

Sometimes you may notice a problem when Flack parses and tries to list resources from a manager. Perhaps nodes aren't drawn at the right locations, nodes are missing, or certain values from the advertisement seem to be missing when inspecting them after they've been parsed. The easiest way to inspect advertisements from a certain manager is to click on the manager name from Managers in building.png Resources on the left pane and click on system_monitor.png Logs in the top right of the manager area. This will show you all of the logs relating only to this manager. Like the above example, you can inspect the XML-RPC received by looking for 'Sent request' or 'Received response' logs. If the XML-RPC values sent and recieved look correct, then you need to look for any logs Flack spits out when parsing. You may see yellow or red text describing possible errors encountered so clicking on those logs is a good place to start. There are some common warnings, like 'interface not found' which has been fairly common and is not a problem so warnings may not be related to problems you are having. If there aren't any warnings or errors then it's possible that Flack just simply skipped over values it didn't know about.

Common Tasks

Creating and Opening Slices

Your list of slices will be near the top of the Slices section in building.png Resources on the left pane. If you don't have any slices listed, you will need to create a wand.png New slice. You will be prompted for a slice name and re-prompted if a slice name isn't available. Once the slice canvas is opened, your slice is ready to have resources added to it.

Slice Area

The slice area is partitioned into the following:

Dashboard (left)

  • The slice name is displayed at the top.
  • View menu to:
    • Preview the request RSPEC that would be sent to managers according to what is drawn on the canvas.
    • View the request RSPEC according what it may have looked when originally sent.
      • The best example of why you would want the original RSPEC is if you originally drew a slice with unbound nodes that are bound after creation. This function will show you an RSPEC even after creation with unbound nodes. Note that this is only available when the RSPEC was generated from Flack which adds values into RSPECs describing how the slice was drawn before being created.
    • View the manifest RSPECs for allocated resources.
    • View and edit SSH public keys which will be installed on allocated resources.
    • system_monitor.png View logs related to the slice.
    • View login information like usernames and hostnames/ports for allocated resources.
    • View the slice credential.
  • resources.png Resources tab
    • drive.png LAN, click or drag to the canvas to add a LAN.
    • Drop-down list to show only managers which support certain sliver types.
    • List of managers with loaded resources.
      • Click name to get options available for adding resources from that manager similar to magnifier.png Search on the main left pane.
      • Click or drag a PC or VM or a resource of another sliver type if an arrow is shown onto the canvas.
    • The bottom options are available on the other tabs as well:
      • wand.png Submit will perform all actions to allocate/delete/update resources according to the canvas.
      • arrow_refresh.png Reload will clear all slice data and reload the slice checking every valid manager for allocated resources.
  • gear_in.png Slice tab
    • resources.png Add Resources button to easily get back to the Resources tab.
    • Get Status button to reload the status of all of the slivers.
    • Slivers, view the current status at aggregates in the slice
      • Manager name is shown along with a spinner if any task related to the sliver is being run along with either what is currently running or the status of what ran last.
      • Perform operations on the sliver though the menu button, like view logs or the manifest, stop/start/restart, and delete.
    • Slice-wide actions
      • delete.png Delete all of the known slivers or run delete everywhere for a more thorough cleanup
      • control_play_blue.png Start, control_stop_blue.png Stop or control_repeat_blue.png Restart the slivers if supported.
      • View the amount of time remaining before the soonest resource expires and extend if needed.
    • Submit and reload options available as described above.
  • resources.png Plugins tab
    • Select a slice plugin from the top menu.
    • Currently available:
    • Submit and reload options available as described above.

Canvas (right)

  • Top bar
    • Select a graph.png Graph or legend.png List view
    • draw_eraser.png Clear all resources and history
    • Import a RSPEC (save RSPECs for later importing using the View menu in the dashboard).
    • arrow_undo.png Undo or arrow_redo.png Redo actions.
    • stamp_pattern.png Clone a selected node.
    • Select an output RSPEC version supported at all managers.
    • title_window.png Pop out into a window.
  • Canvas
    • Nodes are colored based on what manager they are from and links are colored based on what type of a link they are. Their color may be changed or augmented based on status for allocated resources.
    • cross.png Delete the node/link.
    • information.png View and edit.
    • To create a link, bring the mouse near a node and start dragging to another node or an existing link.

Editing Slice Resources

Adding nodes

To add nodes you may do any of the following (for any node button, you can drag it or click if you don't care where it goes on the canvas):

  • Drag an unbound node with a certain sliver type by using the buttons next to the managers in the resources.png Resources tab in the dashboard. Click the down arrow on the right to see more sliver types.
  • Click on a manager in the resources.png Resources tab in the dashboard and drag a node onto the canvas as a bound node.
  • Drag a node marker from the map into the resources.png Resources tab in the dashboard to pick from the nodes from that geographical area.
  • Drag nodes from magnifier.png Search in the resources.png Resources tab in the main left pane.

To add links, you may do any of the following:

  • Place the mouse near a node. When you see a line being drawn from the node you can hold down the mouse key and drag the mouse and release it over a node. If the connection cannot be made, you should see red when the mouse is hovering over the destination node.
  • Drag or click the drive.png LAN button from Resources in the dashboard. You can then drag connections like the previous directions from nodes to the LAN. This can be done for existing links as well.

Editing nodes

Click on the information.png Information button for any node to view/edit it's properties or the cross.png Delete button to remove it. Here is a description of what you can find in the properties area:

  • Client ID at the top.
    • View the manifest RSPEC (if allocated).
    • Status (if allocated).
    • Login info (if allocated).
  • Basic tab.
    • Manager where the node is or should be allocated at.
    • Binding.
      • Unbound, you don't care what specific node so long as you get a certain sliver type.
      • Bound, the node is tied to a specified physical node.
    • Sliver Type.
      • Some sliver types allow you to select Exclusive or not (Shared). Exclusive means no other user will be taking up resources on any node you have and shared means you may be sharing a resources, like a PC, with other users when dealing with VMs.
    • Disk Image.
      • Based on the sliver type, you may be able to select a predefined disk image.
      • If you have a name for a disk image you know you can use, you can just paste that in as well.
      • Create image (Emulab only).
    • Install services.
    • Execute services.
    • Sliver Type specific interface.
      • For example, you can select an init script for planetlab nodes.
  • Interfaces and Links tab.
    • Table of interfaces.
    • Request a public IP for the control interface (Emulab only).
    • List of connected nodes and links used.
  • Extensions tab.
    • Any XML here will be pasted into the RSPEC in requests or was in the manifest if already allocated.

Click on the information.png Information button for any link to view/edit it's properties or the cross.png Delete button to remove the entire link or the single connection of a node to a LAN. Here is a description of what you can find in the properties area:

  • Client ID at the top.
    • View the manifest RSPEC (if allocated).
    • Status (if allocated).
  • Type (LAN, Tunnel, ION, etc.).
  • Shared VLAN.
  • Interfaces tab.
  • Properties tab.
    • Edit the capacity, latency, and packet loss for all of the properties.
    • Edit them in the individual properties for finer control.

Accessing RSPECs

You can view any RSPEC, including preview request RSPECs which would be sent if you clicked Submit or manifest RSPECs if you've already submitted the slice, by clicking View at the top left of the slice area to the right of the slice name and selecting the appropriate option.

Submitting changes

Once you are ready to allocate the resources from the canvas, click wand.png Submit at the bottom of the dashboard. The gear_in.png Slice tab will be automatically selected in the dashboard so you can watch the submission status at each of the aggregates. If all goes well, you should see the canvas change colors and hopefully end up all green. If any errors occur during submission, you will be notified and given options for what you can do. If you want to look through the logs to see what XML-RPC calls Flack made out of curiosity or if you're interested in looking for errors, select system_monitor.png Logs from the View menu at the top of the dashboard.

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

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.