Version 95 (modified by vjo, 6 years ago)

--

Using Flukes

Overview

Flukes is a Java-based GUI that allows an experimenter to graphically inspect the state of ORCA substrates, create request topologies, submit requests to ORCA and inspect the returned substrate information (called 'manifest'). Several key features of Flukes:

  • Graphical intuitive interface
  • Uses native ORCA interfaces and resource descriptions (NDL-OWL) for maximum flexibility, unlike other interfaces to ORCA which use GENI RSpecs and GENI AM API and rely on conversions between these resource formats.
  • Allows the user to submit requests and inspect the output manifest in a graphical environment
  • Allows the user to login to provisioned resources

To launch Flukes, be sure that a Java 6 JRE is installed and double-click on this link. Flukes is a Java Webstart application, which means it will update itself every time it is launched. It also requires Internet access to operate (off-line mode is not supported). If Flukes fails to launch automatically from your browser, execute the following command from commandline:

$ curl http://geni-images.renci.org/webstart/flukes.jnlp > ~/Downloads/flukes.jnlp
$ javaws ~/Downloads/flukes.jnlp

The 'javaws' executable is included in both JRE or JDK 1.6.

Flukes will ask for permission to access the filesystem, which you should grant. Flukes code is digitally signed by a certificate issued to IliaBaldine from BEN@RENCI with a certificate that has the following fingerprints:

SHA1: 3D 24 35 3E 57 72 C0 0C 40 B9 C6 4F B2 ED 62 C2 87 91 0C A8
MD5: 83 08 1C D4 C8 75 DB C4 36 21 B9 B2 92 98 D6 E0

FLUKES Screenshot

Advantages of using Flukes

Flukes uses ORCA native interfaces and resource descriptions. ORCA natively allows the user to specify a few things not available in RSpecs

  • Various node groupings (individual nodes, node groups)
  • Permits group properties common to all nodes in a group
  • Permits ORCA-driven splitting of groups between provider domains without user input
  • Powerful stitching - requests submitted to Fluke can span multiple geographic domains and ORCA will determine and create the proper stitching between slice components at Layer 2 across multiple national and regional research networks.
  • Allows the user to specify custom boot images (filesystem, kernel, ramdisk) to be installed into provisioned resources
  • Allows post-boot script templates (see section below)
  • Allows the user to specify functional dependencies between nodes (node A depends on node B == node B must boot before node A).

Using Flukes

Workflow

Flukes follows a simple workflow:

  • Create or load existing request file in the request pane
  • Type in a name of the slice (must be unique)
  • Click submit button
  • Verify the return status has no errors
  • Switch to Manifest pane
  • Click 'My Slices', select your slice and click OK to display the slice manifest
  • Continue querying for manifest until slice is ready (all reservations are up)
  • Right click on elements of the slice. Nodes offer a login option.

NOTE: the time it takes to create a slice is highly variable. It depends on a large number of factors. The dominant delays are associated with downloading and installing custom images at selected sites. If an image is new, it must be downloaded and registered at a site and then copied to a worker node on which a VM is being stood up. If the image has been used in the past, the delays are much shorter because images are cached in a number of places. Obviously, the larger the image, the longer the delays. It is not uncommon for slices to take 10 minutes to be stood up.

User preferences

Flukes relies on a $HOME/.flukes.properties file to customize its behavior. Properties that are not specified in this file use default values. To inspect the current values of preference properties, click on the 'Help' menu and select 'Preference Settings'. The popup window will display the current settings.

If you wish to overwrite any of the values:

  • create $HOME/.flukes.properties file if it doesn't exist
  • copy/paste the content of the preferences window into a text editor
  • modify the values of properties you need to change
  • save the file
  • restart Flukes.

Basic configuration

At a minimum you need to customize the following properties:

  • The URL of the SM(s) to which you will be sending slice requests (orca.xmlrpc.url - can be a comma-separated list of several)
  • Locations of ssh private and public keys (ssh.key and ssh.pubkey)
  • Location of the JKS file with user credentials (user.keystore), or locations of certificate (user.certfile) and private key (user.certkeyfile) files.

Flukes GUI

Flukes GUI opens with several tabs:

  • Resources pane - for inspecting available resources
  • Request pane - for creating the request graph for a slice and submitting the request to ORCA
  • Manifest pane - for inspecting the manifest of a slice (either previously saved or queried from ORCA)

The slice request can be created in the Request pane and either submitted to ORCA or saved for future use. Once the slice request is submitted, the user can switch to the Manifest pane and query ORCA for slice status. Once the valid manifest is received, the user can inspect the elements of the slice and login to the provisioned nodes.

Left click places the nodes or node groups (in request mode). Clicking on one node and dragging (while holding the mouse button) to another node creates a link. Right click displays a context menu for either

  • A node (when clicked on a node)
  • A link (when clicked on a link)
  • A mouse mode (when clicked on empty space)

All panes support some subset of the following 3 mouse modes:

  • Edit - for creating nodes and edges [Request only]
  • Pick - for picking one or more nodes (holding the left mouse button while dragging selects multiple nodes) [Request only]
  • Pan - panning the graph image within the pane [All modes]

In pick mode the user can select multiple nodes (by clicking on a node or clicking and dragging to create a select area) and edit their common properties (e.g. image, domain binding etc) by right clicking anywhere except node or link and selecting 'Edit Selected Nodes'.

Nodes

Nodes are a main element of the topology. A node group is a special kind of a node that represents some number of nodes sharing common properties. Node and node groups can

  • Have IP addresses/IP address ranges within the dataplane assigned by the user
  • Have functional dependencies on other nodes (node A depending on node B will not boot until node B boots)
  • Nodes can have post boot scripts or post boot script templates.

Nodes are accessed by users over the management IP network which has access to the public Internet. In addition nodes may have other interfaces connecting them to other nodes, which are created by ORCA from Layer 2 circuits either within one domain or between domains, depending on the requested topology. IP address assignment on the primary/management interfaces is the responsibility of the hosting domain and these IP addresses are reported as part of the manifest (they cannot be set or determined at request time by the user). IP addresses for all other interfaces can be specified by the user. When IP addresses are left unspecified, the interfaces in the hosts are created, but remain unconfigured.

Two node types are possible - plain node (a VM with either a default image or an image specified by the user) or a node group. A node group is a set of nodes with common attributes (e.g. size, boot image, post boot script, binding). A node group can be connected to other node groups or individual nodes over a Layer 2 connection (e.g. a VLAN). Nodes within a node group that has a connection to another node or node group will be put on the same vlan.

Similar parameters can be specified for nodes and node groups. For node groups, the number of nodes should be specified. The IP address specified for the node group is the address to be assigned to the first node in the node group, with other addresses incrementally selected from the same address set limited by the netmask. E.g. if there are 3 nodes in a cluster and a user specifies 172.16.1.10/16 then the first node will have 172.16.1.10/16, second 172.16.1.11/16 and so on.

Flukes includes the functionality to automatically assign IP addresses to interfaces in a slice. There is an 'Auto-IP' button in the request view that accomplishes this. It works across single nodes and groups, point-to-point and broadcast links. IP addresses can also be specified manually in the 'Properties' window of individual nodes.

Logging into nodes

Flukes offers a convenient option to login to the provisioned slivers. By default it tries to use ~/.ssh/id_dsa private key and ~/.ssh/id_dsa.pub public key if the user has them. These settings can be overridden by setting ssh.key and ssh.pubkey properties in ~/.flukes.properties. Also the experimenter can override the application used to provide terminal capabilities (xterm, by default) and the options passed to SSH client. Again, the default settings can be seen in 'Help | Preferences' window and can be overridden in ~/.flukes.properties.

Post Boot Scripts and templates

Flukes allows a post boot script to be associated with each node or node group. Post boot scripts are the preferred way to create customized instances from a shared image. Specifically, a post boot script can contain an arbitrary script that is a executed immediately after the instance has booted.

Simple example:

echo "Hello from post boot script"
apt-get install my-favorite-app
echo node1 > /etc/hostname

For added convenience, the post boot scripts can be templated for substitution of parameters like node, link names, ip addresses etc and processed by Orca's Velocity template engine. Read more here on how to create boot-script templates.

There are two types of links in Flukes - point-to-point and broadcast. Point-to-point links can connect nodes and nodegroups to each other. In the case of a nodegroup, a point-to-point link leading to another node or node group implies that all nodes in the nodegroup must have an interface on this link.

Broadcast links can be used to create isolated VLANs inside a nodegroup (replacing the now obsoleted 'private vlan' feature in flukes) or to connect multiple nodes together. Currently nodes or nodegroups connected to a broadcast link cannot be bound to different domains (however you can connect two nodegroups with a point-to-point link and bind those nodegroups to different domains).

Any link can be given an explicit label (VLAN tag). This tag must come from a specially defined pool of tags known to ORCA that lead to e.g. other substrates. For example, to put a node on a mesoscale VLAN 1750 at a particular site

  • create a node and a broadcast link
  • connect the two together
  • bind the node to a particular site (if submitting via ExoSM)
  • right-cick on the broadcast link and fill in the tag '1750' for it
  • submit this request.

Stitch Ports

A stitch port is a facility that provides a means for attaching your slice to an external network not controlled by ExoGENI. Stitch ports can be connected to nodes and require two pieces of information - a VLAN tag (one has to be known to you as a user prior to trying this; negotiation of these tags happens with campus network operators out of band) and a URL of the port - the name under which ORCA/ExoGENI knows this physical port on the switch in one of the racks or e.g. in BEN. Once both are specified a slice can be created that ends on a given physical port on a specified VLAN that can e.g. connect into a special-purpose campus network segment.

Node dependencies

ORCA performs its own dependency analysis on resources to determine the specific order in which they need to be configured/booted. In some cases additional functional dependencies can be introduced by the user to reflect e.g. the semantics of the application (for example an application may have a head node, which must be booted prior to worker nodes).

Node properties dialog allows for these additional dependencies to be specified. A dependency implies that the dependent node will not boot until its dependency target has booted. Dependencies may span multiple domains.

Domain binding

One of the powerful features of ORCA is automatic domain binding of nodes or node groups to specific provider domains based on resource availability. There are scenarios in which a user may explicitly indicate a binding of nodes within a request to specific domains. This can be done at either reservation level (within reservation properties), which makes all nodes within this request bound to a single domain, or it can be done on the individual node or node group level, where a binding of a specific node to a domain can be selected through node properties.

Nodes and node groups can be bound to resource provider domains by selecting one of the domains in the menu. Unbound nodes or domains in a bound reservation will be automatically bound to the selected domain.

An unbound node group may be split by the system among multiple domains depending on the availability of resources. A bound node group is never split and is allocated from a single domain. A user can indicate the splittability of the group by checking the appropriate box in node group properties.

Client disk images

ORCA allows experimenters to create their own filesystem, kernel and ramdisk images to be used for a slice. A number of standard images are available already. The images listed with this service are automatically visible in Flukes under 'images' button.

The user can add new images. Each image must have:

  • A unique short name
  • A URL of the ImageProxy metafile from which it can be downloaded
  • A SHA-1 hash of the metafile

Images can be specified for each node or nodegroup independently. New images must first be defined using the 'Images|New' dialog and then can be referenced from pull down menus in reservation and node properties. Users are required to specify an image for each node or nodegroup.

If the user has an image that should always be part of the Flukes environment, there are two approaches - request that the image is listed with the image service (this way the image becomes visible to all Flukes users) or privately define the image in .flukes.properties file. Flukes users can edit ~/.flukes.properties file to add their favorite images:

image1.name=regression-i386-debian
image1.url=http://geni-images.renci.org/images/regression/regression-deb5-i386.xml
image1.hash=ea80af6601a2a000ec5b050d7e7701f26db096fc

More images can be added by specifying image2.name, image2.url, image2.hash and so on. The images will be visible in the "Client Images' window and can be selected for individual nodes or the entire reservation. Note that they will not be visible in the preferences window.

If an experimenter loads a request file that references an image with the same name as one of the images defined in flukes properties, but with a different hash or url, this image will be added to the list of images under 'Client Images' with its usual name and a string '-req' appended to it.

If you wish to know more about how to build your own image, visit this page.

Slice modifications

After the user creates a slice, it can be modified. Slice modification is an experimental feature that is diabled in Flukes by default. In order to enable it insert the following property into your .flukes.properties file:

enable.modify=true

Currently the following slice modifications are possible:

  • Increase the size of a previously created node group
    • In Manifest View, right-click on the node that is part of a node group and select 'Increase size' option. In a new window type in the integer value indicating the number of nodes you want to create. Then click 'Commit Modify Actions' button, followed by 'OK'. You will see some debugging output. Refreshing the manifest (by clicking 'Query for Manifest') should display the new slice.
  • Delete nodes from a previously created node group
    • In Manifest View, right-click on the node that is part of a node group and select 'Delete Node ....' option. The node will disappear from view however it is not yet deleted. You must click on 'Commit Modify Actions' button, followed by 'OK'. You will see some debugging output. Refreshing the manifest (by clicking 'Query for Manifest') should display the new slice. Multiple nodes can be deleted as part of the same operation.

OpenFlow

You can create simple slices that attach to your OpenFlow controller. The easiest type of slice is a NodeGroup? with broadcast link (you can assign IP addresses to nodes on this VLAN). At reservation level (click on 'Reservation' button) be sure to bind the request to one of the XO racks (other racks will not support OpenFlow).

  • Start your openflow controller on some internet-reachable host
  • Click on 'OpenFlow Reservation'
  • In new fields fill out your email, your slice password and the url of your controller (you have to start it outside the slice). The url of the controller typically looks like 'tcp:<hostname>:<port number>'. When starting a controller on some host be sure the port on which the controller runs is not blocked by a firewall. Remember that it is the slice that connects to your controller, not the other way around.
  • Submit your request

Once the slice is created you will have a switch with some number of nodes attached to it, with the switch controlled by your controller.

Graph Layouts

There are several graph layouts available from a pull-down menu in Flukes. When a graph is saved in NDL-OWL, its layout is not preserved, so this feature is provided as a convenience. After loading a graph a user can experiment with different layouts to find the most convenient one.

iRods support

Flukes support Loading/Saving slice requests and manifests in iRods datagrids. This feature relies on the installation of iRods 'iCommands' executables on the same host that is running Flukes. The commands must be properly configured and runnable before the Flukes iRods features can be used. There are several Flukes properties that govern how the requests and manifests are saved in iRods. Note that by default iRods support is disabled.

enable.irods=true  
irods.format=ndl   
irods.icommands.path=/usr/bin    
irods.manifest.template=experiment/${slice.name}/manifest-${date}.${irods.format}
irods.request.template=experiment/${slice.name}/request-${date}.${irods.format}

User must set 'enable.irods' to true to enable the iRods support in Flukes. The remainder of the properties determines what format is used to save requests and manifests ('ndl' or 'rspec'; note that it is not possible to load 'rspec' into Flukes, as conversion from native NDL to GENI RSpec is one way). The location of iCommands is determined by 'irods.icommands.path' and the naming templates for requests and manifests are determined by 'irods.request.template' and 'irods.manifest.template' properties, respectively. The fields like 'slice.name', 'date' and 'irods.format' can be substituted.

User authorization

When using Flukes, the experimenter can use one of the following credentials:

  • A private key generated by you and a certificate file generated through GENI Portal (a .key and a .pem file)
  • A private key/certificate pem file provided by the GENI Project Office or Emulab - both generated through portal (single .pem file)
  • A private key and a certificate provided by BEN (a .key and a .crt file)

This section explains how to use these credentials with Flukes. It presumes you have one of the credentials described above.

There are two ways in which these credentials can be used. The first is simpler, and the second is more flexible.

Before we describe either, a quick note regarding the storage of the various files (.key, .pem, .p12, .jks) referenced in these procedures: since these files represent secrets belonging to you, it is best to store them in a single directory (e.g. $HOME/.ssl) that only you are allowed to read and write.

Specifying a certificate and private key directly

The process for accomplishing this is:

  • Obtain a .pem (GENI, Emulab) or .crt (BEN) file. You may have generated your own .key file.
  • Check it using openssl:
    $ openssl x509 -text -in mycredential.pem
    
  • Enter the path to the file containing your certificate into the "user.certfile" property
  • Enter the path to the file containing your private key into the "user.certkeyfile" property; this may be the same file as is specified in the "user.certfile" property.

When you submit a request through Flukes, it will ask you for a key alias and password. The alias that you choose to use is immaterial (it is *not*, if you are using the second, more flexible, method for specifying user credentials, that is described below), but you should enter the password associated with you private key.

Creating a Java keystore, and adding credentials to it

Unlike a .pem file, a Java keystore can contain multiple private key entries under different aliases. A user can select the key alias to be used for submitting a specific request at the time of the submission.

In order to convert these credentials into a keystore usable by Flukes, a user must create the keystore, and then import at least one of the credentials into it. The easiest way to import a key/certificate is to download a tool like Portecle. Portecle is Java-based and works across multiple platforms. Importing a .pem file containing a key and a certificate issued by either Emulab or GPO is straightforward and shown in this screen capture.

The process is as follows:

  • Obtain a .pem (GENI, Emulab) or .crt (BEN) file. You may have generated your own .key file.
  • Check it using openssl:
    $ openssl x509 -text -in mycredential.pem
    
  • ONLY IF you have a separate file containing the private key (.key) and a separate certificate file (.crt or .pem) from GENI or BEN, combine them into a single PKCS12 store:
    $ openssl pkcs12 -export -in username.[crt|pem] -inkey username.key -out username.p12
    
  • Start Portecle
  • Create a new keystore of type JKS
  • Click on "Import Key Pair"
  • Locate the .pem or the .p12 (if you generated one) file
  • Enter the password protecting the .pem or the .p12 file
  • Import the key and certificate, but change the key alias to something simpler than a GUID (e.g. firstnamelastname-geni with no spaces). This is the key alias you will enter when prompted by Flukes.
  • Enter and confirm a new key password. This is the password you will enter when prompted by Flukes.
  • Click on "Save Keystore"
  • Enter and confirm the new keystore password (use same as the key password)
  • Enter the path to the keystore file into .flukes.properties "user.keystore" property

If you prefer to use a command-line, the process is:

  • Obtain a .pem (GENI, Emulab) or .crt (BEN) file. You may have generated your own .key file.
  • Check it using openssl:
    $ openssl x509 -text -in mycredential.pem
    
  • Convert your certificate and private key files (which may be a single PEM file) into a single PKCS12 store:
    $ openssl pkcs12 -export -in username.[crt|pem] -inkey username.[key|pem] -name username -out username.p12
    
  • You will be prompted for the password for the private key first, and then prompted for the password to be

used for the PKCS12 store. Enter your private key password at each of these prompts.

  • Convert the PKCS12 store into a Java keystore:
    $ keytool -importkeystore -srckeystore username.p12 -destkeystore username.jks -srcstoretype pkcs12
    
  • You will be prompted twice for a password to protect the new Java keystore, and once for the password protecting

the PKCS12 store. Enter your private key password at each of these prompts.

  • Enter the path to the Java keystore file into .flukes.properties "user.keystore" property

When using the command-line method, please note that the value you use for the "-name" parameter (while creating the PKCS12 store) will be the value used for the key alias.

A note about keystore passwords: a Java keystore always has a password protecting its integrity. Each key within a keystore can also have a password. Flukes currently assumes both the keystore and key passwords are the same.

When you submit a request through Flukes, it will ask you for the key alias and password. You should use the alias you assigned to this new key and the password used for keystore and keys. Note that you can have multiple key/certificate pairs under different aliases within the same keystore (e.g. one from GPO and one from BEN).

Attachments