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 (the Oracle version, not OpenJDK) 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.7 (the recommended version)

Flukes will ask for permission to access the filesystem, which you should grant. Flukes code is digitally signed by a certificate issued to 'Renaissance Computing Institute' with a certificate that has the following fingerprints:

	 MD5:  68:D6:62:8F:0A:A3:5F:E1:7B:C8:4A:4A:D3:79:BB:CA
	 SHA1: 8E:73:D9:79:71:92:01:04:0F:1E:5C:95:38:D7:AF:C8:5A:00:AB:CD
	 SHA256: D0:F3:19:1C:4D:3D:07:74:C3:0B:9D:9D:07:23:A2:19:19:5E:FD:6B:54:C2:BC:E4:9A:AF:BE:EE:45:B7:0B:CC

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.

By default Flukes instructs ORCA to enable root logins into nodes using user's public SSH key. It is possible to have Flukes create an additional account on each node that will be associated with a separate SSH public key, to, for example, provide someone else access to slivers in your slice. To do that you must modify the following properties in ~/.flukes.properties file:

# Secondary login (works with ssh.other.pubkey). It can be set to 'root', which will give both you and the other user access to root login
ssh.other.login=username
# Secondary public SSH key (perhaps belonging to other users) that should be installed in the slice.
ssh.other.pubkey=~/Desktop/id_rsa.pub
# Should the secondary account have sudo privileges
ssh.other.sudo=yes

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.

Storage

Some ExoGENI sites allow adding slivers of storage to your slice. These are iSCSI volumes allocated from the rack-local storage appliance, formatted to experimenter specifications and attached to one or more nodes in the topology. Simply select 'Storage' node type, add it to the topology, right-click and fill in the necessary properties. Connect the storage to one or more nodes in the topology. The necessary properties will be passed into the node to initialize, format (if needed), attach and mount the volume. Note that while it is possible to attach more than one node to a volume, it is an advanced usage. In this case the volume will be attached, but not mounted, as the experimenter must decide which nodes will be readers, which will be writers and how they will be deconflicted. iSCSI protocol allows for this, but not every filesystem type supports it.

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 'ExoGENI Info | Compute Images ...' menu item.

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 'New' dialog.

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 'Compute 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 'Compute 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 ExoGENI ExoBlog .

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
    • 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 select 'Submit Changes' from Slice Operations menu . 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
    • 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 select 'Submit Changes' button from Slice Operations menu. 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.
  • Delete or add any node or link
    • Right-click on node or link and select 'Delete Node ....' or 'Delete Link ....' option. Similarly, 'Submit Changes' must be selected from the Slice Operations menu
  • Add any node or link
    • Query for slice manifest, then click to add new nodes or links as if you were drawing a slice. Use 'Submit Changes' menu item to enact the changes. You can use query for manifest or use polling to wait until the changes are realized.

Slice-to-slice stitching

Two slices that have reservations on the same rack/aggregate can be stitched together. The supported scenario is connecting a link or a broadcast link in one slice to a compute node in another slice. In order to enable it insert the following property into your .flukes.properties file:

enable.slice.stitching=true

The following operations are possible

  • Permit stitching to a node or a link. A password must be set that is then shared with owners of slices who wish to stitch to this slice
  • Revoke stitching permission. Disallows new stitching operations, however does not undo existing slice-to-slice stitches
  • Perform a slice-to-slice stitching operation using the password established in the first step. The user must indicate the name of the slice and the ID of the reservation (node or link) in the other slice to which the stitching is being done. It is possible to set IP address and netmask for the new interface that will appear on the node that connects to the link.
  • Undo stitching. This operation does not require a password and is symmetrical - can be performed by owner of either slice.
  • Inspect stitching-related properties. Lists existing and past stitches to the particular node or link

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.

Colored property graphs

Flukes supports adding 'coloring' annotation to the slice requests that is passed unaffected through the resource provisioning engine in ORCA and becomes visible in the slice manifest, where provisioned resources can be correlated to the assigned colors and their properties. A color label (a string) can be assigned to any resource in the request (a node or a link) and also to a special kind of colored edge between any two resources, that may represent a directed labeled dependency between resources. Each color label can be associated with a dictionary of key-value pairs or a blob of text or XML. The purpose of this work is to allow higher level (e.g. application) annotation of the request graphs. An application can assign color labels of its choosing to different resources, associate properties (dictionaries or text blobs) with them and inspect the manifest graph that represents the combination of this annotation and the description of the provisioned resources. This may help the application consuming the manifest to make deployment decisions of its components in the slice using e.g. extracted properties in the form of dictionaries or text blobs, readable by the application.

Since this ORCA feature is really meant for automated processing by applications generating and consuming slice requests, the support in Flukes is meant primarily for testing and debugging.

Additional features

Information about ExoGENI

The majority of ORCA installations are part of the ExoGENI testbed. Using Flukes users can do the following things:

  • Find out the quantities and types of resources available from the selected ORCA controller: Under 'ExoGENI Info' menu select the 'Available Resources ...' option and you will be shown a table with resources known to this controller.
  • Find out about the maintenance events and other operational announcements. ExoGENI uses Twitter to make brief timely announcements and a google group for detailed information. Under 'ExoGENI info' there is a 'Twitter' option that lets you see the last few announcements and a 'More Information' button which takes you to the google group website to find out more.

Reporting problems

Flukes can help you draft an email to the users list reporting a problem with your slice. Under 'ExoGENI Info' menu, select 'Report slice problem ...' item and you should your email client window launched with the information about your slice. Fill in the rest of the details and click 'Send'.

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.

Support for GENI Portal

Flukes is capable of interacting with the GENI portal for the following purposes:

  • Registering created slices with a Slice Authority (SA). The most common use for it is to have user slices show up in the GENI portal.
    enable.genisa=true (enable SA support)
    genisa.url=https://ch.geni.net/SA (specify the URL of the SA; safe to leave the default)
    genisa.project.urn=urn:publicid:IDN+ch.geni.net+project+SomeProject (the URN of the project in the SA the slices should be registered to; usually enough to replace the 'SomeProject' string with project name)
    
  • Retrieving user SSH keys from the Member Authority (MA) and using them for logging into slivers. The public SSH key available to the portal will be installed in user's slivers. If the private key is also stored on the portal, it will be used for logins; if it is not stored on the portal, it will be loaded from a file named in ssh.key property.
    enable.genima=true (enable MA support)
    genima.url=https://ch.geni.net/MA (specify the URL of the MA; safe to leave the default)
    ssh.key.source=portal (enable getting SSH keys from the portal)
    

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 as a single .pem file
    • If you are using the GENI portal, go to Profile | SSL to download your .pem file containing the private key and the signed certificate.

GENI Portal snapshot

  • 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. The first way is most familiar to users coming from Emulab/Planetlab/InstaGENI Flack environment, and involves using a single identity credential supplied in the form of a combination of .key and .pem/.crt files. Flukes accepts these types of credentials, but if multiple identities need to be used, Flukes must be stopped, reconfigured and restarted. The second way relies on constructing a Java Key Store (JKS) out of one or more credentials issued to the experimenter (multiple identity credentials). Flukes can then use this keystore and the experimenter can choose which identity to use at run time.

Note that to preserve original behavior, Flukes favors the second way, that is if you already have your identity specified in a JKS, using the .pem/.key files will have no effect until you comment out the JKS setting.

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 your 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).

Flukes on Windows

Flukes is written in Java to present the most consistent cross-platform to its users. However there are some differences in default behavior available on different operating systems that must be accounted for. These differences are described in this page.

Troubleshooting

  1. If flukes fails to start on your platform using a double-click, try running from the command line to see the error output:
    $ javaws /path/to/flukes.jnlp
    
  2. Try flushing the webstart cache by running 'javaws -viewer' - this should display a GUI with a list of all Java Webstart applications cached by the system. Remove all applications from the cache and try again.

Gotchas

While Flukes tries very hard to work well on all platforms, there are some "gotchas" that can be encountered by its users. We have attempted to enumerate them below.

1. Exception containing the text "Illegal key size"

  • Due to the continued export restrictions on crypto in the US, Oracle's implementation of Java is unable to make use of credentials that exceed a certain degree of strength, without the installation of so-called "Unlimited Strength" policy files.
  • In order to resolve the issue, you will need to go to http://www.oracle.com/technetwork/java/javase/downloads/index.html and download the "Unlimited Strength" policy files for your version of the JRE or JDK. Please follow the instructions for installing them, then restart Flukes.

2. Unable to find xterm on OS X, version 10.8 (Mountain Lion) or above

  • Beginning with version 10.8 of OS X, Apple has chosen to no longer include X11 in the base OS, as noted here: http://support.apple.com/kb/HT5293?viewlocale=en_US&locale=en_US
  • In order to resolve this issue, please download and install XQuartz from: http://xquartz.macosforge.org/landing/
  • Once you have installed XQuartz, you will need to ensure that the "xterm.path" property in your .flukes.properties looks like this: xterm.path=/opt/X11/bin/xterm
  • After upgrading to OS X Yosemite, xterm has moved. As the following to .flukes.properties: xterm.path=/opt/X11/bin/xterm

Attachments