The Desktop Access Controller (plugin)

The desktop controller allows experimenters to create experiments that incorporate standalone computers running FreeBSD or Linux. These computers act as though they are a direct part of the experiment. The traffic from the desktop computer is tunnelled via SSH to and from the DETER experiment at layer 2. Unlike federated testbeds, the desktop plugin currently does not import or export filesystem service or DETER accounts. The desktop owner continues to manage most of the computer.

The SSH tunnel can use a dedicated link or be multiplexed with other traffic on on a given network interface. The traffic is routed using the internet routing established by the user.

This page will explain how to configure and use the desktop controller.

Download

Follow the directions for downloading and installing fedd. Download and install from the git repository as the desktop controller is new functionality.

Configuration

Once the fedd is downloaded, the desktop plugin will need to be configured and started. Generally people running a desktop controller will not need to run an experiment controller as well. Most experimenters will use DETER's experiment controller (at ​https://users.isi.deterlab.net:23235 )

While it is worth reading the general configuration instructions, only a subset of them are directly applicable to the desktop controller.

Permissions On The Desktop

The desktop controller will need to run some commands as root in order to connect the desktop to DETER. Specifically, it will need to run ssh as root, create tap interfaces (through ssh), configure network routing, and append to the /etc/hosts file. You can either do this by running the controller as root, or by giving the user that runs the controller the right to run commands through sudo.

Unless you are willing to type the password into a window in which the controller is running, it should be able to sudo without using a password. The two commands that the controller runs are shell scripts called connect and disconnect. The user configuring the desktop controller controls the rest of the pathname of those scripts. You can configure sudo to allow those scripts to be run without a password. See the sudo manual for details.

The controller will also create tap interfaces, and the kernel code to do this must be loaded. On linux this is done by:

# modprobe tun

and on FreeBSD

# kldload if_tap

Be sure to run these commands as root before attempting to create experiments using the desktop plugin.

sshd must be configured to allow layer 2 tunneling. In /etc/ssh/sshd_config or similar, set:

PermitTunnel yes

And restart sshd.

Also follow the instructions for creating a fedid for this controller. Save that identity in the configuration directory we create below. Conventionally, that ID is stored in fedd.pem.

Configuring the Desktop Controller

Create a directory for the data and configuration of the desktop controller. It does not need to be on a very large file system - a few megs at *most* - but should not be in a temporary directory. DETER uses /usr/local/etc/fedd for this. In the configuration directory, create a file similar to this one​ called desktop.conf:

[DEFAULT]

# The directory containing this file
base: /vim/fedd_desktop

[access]

log_level: debug
# Saved controller state
access_state: %(base)s/desktop_access.state
# saved access info (generated by access_to_abac.py)
accessdb: %(base)s/desktop_access_map
# The ABAC database (generated by access_to_abac.py)
certdir: %(base)s/certs
# Location of generated scripts and temp data
localdir: %(base)s/local

auth_type: abac
auth_dir: %(base)s/abac

# The hostname of the machine we run on
hostname: vim.isi.edu

# If set the first hop router to DETER (DNS name or IP address)
# gateway: first_hop.your.domain

# If set the IP address of the interface to use in accessing DETER (Linux only)
# interface_address 192.168.1.1

[globals]
# The controllers self-signed identity (X.509 cert)
cert_file: %(base)s/fedd.pem
# Port on which to listen
services: 23235
# This is a desktop access controller
access_type: desktop

You will want to change base to point to the configuration file, and hostname to be the DNS name of the machine the controller runs on. If you want to route the experimental traffic through a particular interface, you can use the gateway or interface_address parameters to select the interface to use. If gateway is set, the interface that routes to that gateway will be used. If interface_address is set, the interface that has that address assigned will be used. Currently interface_address only works on Linux machines.

The rest of the defaults are probably acceptable, but they are described in the comments and this documentation.

In addition, in the configuration directory create 3 subdirectories:

• certs - used to hold allocation fedids (if you prefer another name, change the certdir parameter in desktop.conf to point at it)
• local - used to hold controller data and the startup and shutdown scripts (if you prefer another name, change the localdir parameter in desktop.conf to point at it)
• abac - used to hold ABAC data (if you prefer another name, change the auth_ir parameter in desktop.conf to point at it)

Configuring ABAC

The simplest configuration of the desktop controller allows a specific DETER user to access it. To set that up, create a file called desktop_access with a line similar to the following:

(fedid:e630047380b1060ce03d19e373b8047bb785031a,<any>,faber)-> access, (access)

Change faber to the username of the DETER user you wish to grant access. If you want multiple users to be able to federate this machine, add additional lines with the same format. The fedid at the beginning of the line is the fedid of the DETER experiment controller. This line allows the named DETER users (as validated by the experiment controller) to federate this machine.

To make that operative, use the access_to_abac.py command to create the ABAC database:

$ access_to_abac.py --cert=fedd.pem --dir=/usr/local/etc/fedd/abac --type=skel --mapfile=desktop_access_map ./desktop_access

That command must be run from the configuration directory. The argument to --dir must be an absolute pathname.

At this point you should be able to start the controller:

$ fedd.py --config /usr/local/etc/fedd/desktop.conf

A test experiment

This file​ contains a two node experiment, one node on DETER and the other on your desktop:

# simple DETER topology federated to a desktop
#
# SERVICE: project_export:deter::project=SAFER
#

set ns [new Simulator]
source tb_compat.tcl

set a [$ns node]
set b [$ns node]
tb-set-node-testbed $a "deter"

tb-set-node-testbed $b "desktop"

set link0 [ $ns duplex-link $a $b 100Mb 0ms DropTail]

$ns rtproto Static
$ns run

To swap that experiment in, use the ​fedd_create.py command on users.isi.deterlab.net as follows:

$ fedd_create.py --map desktop:https://your.machine:23235 --file two.tcl --experiment_name test-name

That will initiate the experiment. You can monitor it using the ​fedd_spew.py or ​fedd_multistatus.py commands. When those commands report the experiment as active the components will have been created on DETER and your desktop. It may still take a few minutes to establish connectivity to the experiment. You can check the /tmp/connect.log on your desktop for updates.

Once the connectivity has been established, your desktop should be able to ping the a node on DETER.

Manually Connecting and Disconnecting

You can run the connect and disconnect scripts in /usr/local/etc/fedd/local directly (as root) to connect or disconnect the desktop from the federated experiment while the experiment still exists.

Terminating the experiment

The ​fedd_terminate.py command will release the resources of a federated experiment.