= 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 [FeddDownload downloading and installing fedd].  Download and install from [FeddDownload#Gitaccess 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 [FeddGettingStarted 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, but these lines worked for me:

{{{
## Let members of group fedd run the connect/disconnect commands without a password
%fedd ALL=NOPASSWD: /bin/sh /vim/fedd_desktop/local/connect, NOPASSWD: /bin/sh /
vim/fedd_desktop/local/disconnect
}}}

(That assumes that base: is set to /vim/fedd_desktop, which you will probably change.)

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 [FeddConfig#MakingaFedidCertificate 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 [attachment:desktop.conf 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 [FeddConfig#MainConfigurationFilefedd.conf 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 [wiki:FeddABAC#access_to_abac.py 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 [attachment:two.tcl file] contains a two node experiment, one node on DETER and the other on your desktop:

{{{
# simple DETER topology federated to a desktop
#


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 [http://fedd.deterlab.net/wiki/FeddCommands#fedd_create.py 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 [http://fedd.deterlab.net/wiki/FeddCommands#fedd_spew.py fedd_spew.py] or [http://fedd.deterlab.net/wiki/FeddCommands#fedd_multistatus.py 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 [http://fedd.deterlab.net/wiki/FeddCommands#fedd_terminate.py fedd_terminate.py] command will release the resources of a federated experiment.