To edit the list of authorized users of the factory service, add DNs to $GLOBUS_LOCATION/etc/workspace_service/workspace-grid-mapfile

Add a DN to the list in normal Globus fashion (if the DN has spaces in it, use quotes around it). The gridmap authorization module requires a username mapping, but it is irrelevant to this service, so using e.g. "fakeuser" for each DN entry is OK. We support grid-mapfiles instead of simple access control lists for maximum compatibility with predeployed installations.

Other (attribute based) authorization methods are now available via the plugin system.

After a workspace is created, only the creator may manage the WSRF resource. This is configured programmatically for each workspace, so no grid-mapfile for the workspace service is needed, just the factory.

There are currently two service implementations, xenlocal and xenSSH.

xenlocal does not handle the resource pool model, it is only for the cases where you want to run one workspace service on the same node as the (sole) hypervisor it manages.

xenSSH on the other hand will enable you to manage a pool of resources from one running service. The service keeps track of the what resource are available at the current time, adding and subtracting the resources used, keeping a view of what is available at the different hypervisor nodes. In this version of the service, the first introduction of the resource pool model, this only tracks the RAM available for VMs at the node. To configure the resource pools, see here.

To edit the path to the workspace backend program(s) that was (were) installed, edit $GLOBUS_LOCATION/etc/workspace_service/jndi-config.xml

In jndi-config.xml, find the backendPath entry under the WorkspaceService section. Use an absolute path to the program. The service is distributed with the proper configuration for when the backend program is installed with the workspace-control default configurations and installer.

Note: if you are using the resource pool setup and the XenSSH implementation, this backendPath entry refers to the program's location on the VMM nodes.

Currently, the factory can be configured with three simple policies concerning workspace deployment. Each value is listed in the WorkspaceFactoryService section of $GLOBUS_LOCATION/etc/workspace_service/jndi-config.xml

The defaultRunningTimeMinutes value is used if the DeploymentTime element of the deployment request is not specified.

The maxRunningTimeMinutes value can not be exceed by the value of the DeploymentTime element of the deployment request.

The WSRFResouceMinutesPastRunningTime value configures the default termination time of the WSRF resource representing the workspace. When a workspace is shutdown, its representation is not terminated (one reason being that it can be started again). This value is added on to the running time and is currently only configurable at this location.

The optional architecture value can be one of the JSDL ProcessorArchitectureEnumeration values such as "x86". If you are running Xen on other architectures, this should be changed appropriately.

The optional vmm value will currently be Xen.

The optional vmmVersions value can be a comma separated list of one-word strings (deciding on values to use is a deployment issue within VOs).

The optional associationFileLocation value is a directory location that specifies where to find the networking pool information for the Allocate networking method. If this is a relative path, it is evaluated with respect to $GLOBUS_LOCATION. For more information on configuring associations, see below.

The optional certificateFileLocation value is a directory location that specifies where to find the certificate and keyfiles that an association may optionally refer to.

The optional resourcepoolFileLocation value is a directory location that specifies where to find the resource pool information for the xenSSH implementation. If this is a relative path, it is evaluated with respect to $GLOBUS_LOCATION. For more information on configuring a resource pool, see below.

For more information about the deployment request, see the TP1.2.2 interfaces documentation.

This is optional because you may be using "local" mode where the service is being hosted on the only hypervisor. But in most cases, the resource pool mode of operation (where you deploy one grid service that manages many hypervisor nodes) is recommended. See Service Implementation.

As noted above, the resourcepoolFileLocation directory can contain files that represent resource pools. The file format is currently very simple: for each node in the pool, list the hostname and the amount of RAM it can spare for running guest VMs.

These configurations are currently under the same constraint as the association entries with respect to removing entries (see DB side note).

The workspace service can allocate IP addresses from pools of addresses (called associations) for the Allocate networking method. The name of the file is the association name, and the directory to find all such files must be configured in the workspace factory JNDI config (see above).

The service is packaged with two sample association files public and private. These files can be found in the example associations directory: $GLOBUS_LOCATION/etc/workspace_service/associations. The files contain the syntax explanation as comments. Currently there is no script to auto-generate such files from higher level logic, each entry must be specified manually or generated via script.

Side note: The service takes these files and inserts them into its database (uniqueness is judged by the combination of association name and IP address). This happens during the container boot process in the factory service initialization. The files themselves are therefore not the authoritative source of association information, but are for administrator convenience. Note that currently there is no support for assessing if an administrator has removed any entries between boots of the GT container. If you have added any entries, it will add them, but there is no support for removing database entries besides manually deleting them via SQL or resetting the entire database (and losing all persistent state) by using "ant resetDB" from the service source tree. To implement such a feature would require a longer container boot process as well as shutting all workspace down that used the removed address (if there is user demand for this convenience, we can take the time to add it).

For Xen3 control, editing the networking configurations, and for one feature where the image itself is modified (certificate staging), the sudo program must be installed on the same node as the backend program. For more information about the mentioned networking configuration, see below.

As root with the visudo command, add these lines to the /etc/sudoers file that reflects the user running the GT container (the first word) and the correct full paths to the dhcp-config.sh tool, the xm tool, and the xend daemon (needed in the case where the workspace-control program is permitted to reboot the daemon if it has fallen).

Note: the installer will print out the exact sudo policy you need that matches the configurations it read in from the workspace-control conf file. e.g.:

You must manually add these policies to your sudo config (use visudo):

globus ALL=(root) NOPASSWD: /opt/workspace/bin/dhcp-config.sh
globus ALL=(root) NOPASSWD: /usr/sbin/xm
globus ALL=(root) NOPASSWD: /usr/sbin/xend

This version of the workspace service does not support unauthorized client kernels. As such, the guestkernels configuration under the [images] section lists the kernels workspaces are allowed to be instantiated with. A client can choose from these kernels in the metadata, but they must already exist at the hypervisor node and must be in the guestkernels list.

With Xen, for each NIC on the hypervisor node, it is typical to create a corresponding bridge such that guest virtual machines may be bridged to each NIC. This allows workspaces to be on different networks or allows spreading out of the networking load (in the case where the hypervisor's multiple NICs are on the same network).

Support for multiple physical and virtual NICs is present in this version, mapped in the grid context in terms of a networking association string. A client will specify the required association in the metadata, assuming the deployment nodes support that association (otherwise, a creation fault will be thrown). An association is created by configuring an entry for it in the workspace-control configuration file. This should match the service association configurations.

For example, the node could have two physical NICs, one bound to a private LAN and one bound to the Internet. To accomodate virtual networking cards being bound to both NICs, a site admin could create two bridges, xenbr0 and xenbr1. Then an association would be configured for each bridge, e.g., one called "public" and one called "private" for example (a typical configuration).

In the sample workspace-control configuration file, find the association_ settings in the [networking] section. If xenbr0 is the 'public' interface, add this line:

association_0: private; xenbr0; vif0.0 ; AA:01; 192.168.0.0/24

This specifies that there will be an association called 'private' with bridge 'xenbr0' with MAC address prefixes of 'AA:01' given to virtual NICs bound to this bridge and with an authorized IP range of 192.168.0.0 to 192.168.0.255.

The third field lists the interface of the NIC that is listening for DHCP requests. This is the interface that DHCP requests originating from workspaces should be allowed to broadcast to. Directing the request to a specific interface prevents DHCP requests from being broadcast to other workspaces as well as to the real network. You can doublecheck what vif is on what bridge by running "brctl show". Normally you'd run the DHCP server in dom0 and the defaults are like so:

xenbr0 - vif0.0
xenbr1 - vif0.1
xenbr2 - vif0.2

You are not required to run the DHCP server in dom0 as the workspaces' DHCP request broadcast can be directed to any interface, but currently to run it in another domain would require altering the dhcp-config.sh callout to work remotely (this would not be hard for you to do, grep for "dhcpconfigpath" in the xen_v2.py module and prepend ssh parameters, for example).

When choosing MAC addresses to use, ensure you choose a unicast address.
That is, one with the low bit of the first octet set to zero. For example, an
address starting aa: is OK but ab: is not. It is best to keep to the range of
addresses declared to be "locally assigned" (rather than allocated globally to
hardware vendors). These have the second lowest bit set to one in the first
octet. For example, aa: is OK, a8: isn't.

In summary, an address of the following form should be OK:

XY:XX:XX:XX:XX:XX

where X is any hexadecimal digit, and Y is one of 2, 6, A or E

Note: if you only have one bridge for virtual network cards, a simple configuration would be to list one association like so:

association_0: default; AA; 1.0.0.0/16

Note that no bridge name is given, the default bridge as determined by Xen will be used. Note the IP range is fake; if you want to not keep track of workspace IP assignments (to prevent conflicts) or to not check if a requested IP setting is valid for the bridge, set the check_ip_ranges, track_MAC_assignments, and track_IP_assignments settings to 'false'.

To actually enact networking changes (using the Allocate networking method for example), the VM must set its own L3 networking information (IP address, default gateway, etc) from inside the VM. Currently we only support delivery of the information via DHCP. Booting into DHCP client mode is well supported in virtually every operating system in existence. Previously we passed information via kernel parameters which required a special understanding inside the VM. The result of using DHCP is that workspace images are easier to create and easier to maintain.

A DHCP server is required to run on each hypervisor node. The purpose of this server is to respond to broadcast requests from workspace's that are booting locally. Before starting a VM, if any of its NICs need to be configured via DHCP, workspace-control will call out to "dhcp-config.sh" via sudo, passing it a specific MAC address to IP mapping (as well as other information to be passed to the VM such as hostname, dns servers, broadcast address, default gateway, etc).

In addition to a DHCP server, we also insert custom ebtables rules when the workspace is deployed. These rules accomplish three things:

A draft of the workspace DHCP design document is available here.

Configuring the DHCP server consists of copying the example DHCP file "dhcp.conf.example" to "/etc/dhcp/dhcpd.conf" and editing it to include the proper subnet lines (see the contents of the example file). The subnet lines are necessary to get the DHCP server to listen on the interface in the first place. No lease configurations, available ranges, etc. should be added: these are added dynamically to the file after the token at the bottom.

In most cases it is unecessary, but if you have a non-standard DHCP configuration you may need to look at the "dhcp-config.sh" script in the protected workspace bin directory and look at the "adjust as necessary" section. The assumptions made are as follows: