Downloading and Installing fedd

This section describes how to get a copy of fedd for your testbed and install it.

Fedd is released under the GENI Public License

Downloading and Installing the tar file

The easiest way to get a copy of fedd installed on your machine is to download the python distutils tar file and install it. The current version is fedd-4.10.tar.gz​. Older sources are attached to this page.

You will need to have the following python packages installed as well.

• ZSI (version ​2.0)
  • Either version 2.1a or 2.0 work.
  • 2.0 does not work on recent Linux installs because of an incompatibility with recent XML libraries - use 2.1a on Linux
  • 2.0 Continues to work on FreeBSD installs, which is what we run on in DETER
• M2Crypto (requires ​swig. Most package systems will fetch and install swig as well)
• MySQLdb
• ​libabac and its dependencies.

Versions of M2Crypto before 0.20 will require

• pyasn1

Emulabs generally have MySQLdb installed already. All of the components above also have FreeBSD packages and ports, which can simplify installation. We strongly recommend using the FreeBSD ports system or a packaging system like apt-get or rpms to do these installations when possible. Many of the packages have dependencies that differ slightly on different systems (primarily because different OSes and distros have different software in the base installation).

Finally, if you are creating federated experiments, the graphviz package needs to be installed to generate legacy visualization information. Boss already will have this installed on most Emulab installs. This requirement will disappear in a future release.

Once those packages are installed, the following commands will install fedd:

$ tar xzf -C /tmp fedd-4.10.tar.gz
$ cd /tmp/fedd-4.10
$ sudo python ./setup.py install
$ cd 
$ sudo rm -rf /tmp/fedd-4.10

Your install will include the python package called federation and the following scripts:

/usr/local/bin/access_exp_access_db.py

application to simplify creating access controller databases

/usr/local/bin/access_to_abac.py

converts access controller authorization databases to ABAC.

/usr/local/bin/cert_to_fedid.py

create a self-signed certificate from an existing hierarchical X.509 certificate and key.

/usr/local/bin/creddy_split.py

Split a combination X.509 certificate and key file into two separate files, useful for working with the ​libabac ​creddy utility

/usr/local/bin/db_to_certs.py

utility to simplify setting up a DETER access controller

/usr/local/bin/dump_abac_authorizer.py

Debugging tool to display the contents of an ABAC authorizer directory in human-readable format.

/usr/local/bin/exp_access_db.py

application to simplify creating experiment creation databases

/usr/local/bin/fedd.py

fedd itself

/usr/local/bin/fedd_client.py

legacy fedd command line access

/usr/local/bin/fedd_create.py

creates federated experiments

/usr/local/bin/fedd_ftopo.py

returns a general logical to physical mapping

/usr/local/bin/fedd_image.py

generates images of federated topologies

/usr/local/bin/fedd_info.py

provides general information about federated experiments

/usr/local/bin/fedd_multiinfo.py

provides general information about multiple experiments

/usr/local/bin/fedd_multistatus.py

provides summary information of the status of experiments accessible by this user

/usr/local/bin/fedd_new.py

gets a new federated experiment reservation without attaching resources to it

/usr/local/bin/fedd_ns2topdl.py

converts an ns2 representation of an experiment to a topdl one

/usr/local/bin/fedd_operation.py

accesses the operations interface

/usr/local/bin/fedd_spewlog.py

monitor the process of creating an experiment

/usr/local/bin/fedd_terminate.py

ends an experiment

/usr/local/bin/fedd_to_abac.py

converts existing experiment controller DBs to ABAC.

/usr/local/bin/fedid.py

command line tool for getting fedids from X509 certificates

/usr/local/bin/import_abac_creds.py

adds an X.509 ABAC credential directly to a fedd authorizer.

These scripts are documented in more detail on the commands page.

DRAGON install

If you are installing a DRAGON access controller, you must also download and install the ​OSCARS configuration software. The DRAGON project provides ​detailed instructions for doing that.

The Federation Kit (fedkit)

The federation kit is the software used by fedd to connect testbeds and tunnel services from the master to the other testbeds. Currently we have a single fedkit​ that provides SSH tunnels to connect experimental testbeds at the ethernet layer, tunnels the DETER/Emulab event system and provides shared file service via ​SMB. That fedkit runs on any FreeBSD or Linux image that provides the SMB file system.

By splitting this function out, we intend to allow different installations of fedd to provide different interconnection and service tunneling function. Currently the DETER fedkit is the only federation kit in use, and fedd defaults its startcmd options for use with it.

To install fedd, the administrator must download a copy and put it where fedd can read it, usually /usr/local/etc/fedd and set the fedkit parameter in the [experiment_control] section of the config file to be the pathname of the tar file.

Fedkit Functions and Configuration

In standard operation, the fedkit is configured and invoked by fedd. This section provides some details on the inner workings of the kit that may be helpful in debugging.

The federation kit has 2 roles

• Configuring experiment nodes to use services, such as shared file systems.
• Configuring portal nodes to connect experiments

Fedkit on Experiment Nodes

On experiment nodes, the fedkit starts dynamic routing, and optionally configures user accounts and samba filesystems if they are in use. The system expects the following software to be available:

• quagga routing system (an old gated installation will also work)
• samba-client
• smbfs

Those are the linux package names; equivalent FreeBSD packages will also work. For software to be available is for it to be either installed or accessible using yum or apt-get. DETER nodes have a local repository for that purpose.

The fedkit is installed in /usr/local/federation and when run places a log in /tmp/federate.

Services are initialized based on the contents of /usr/local/federation/etc/client.conf. Possible values include:

ControlGateway

The DNS name (or IP address) of the node that will forward services Hide: Do nat add this node to the node's view of the experiment. Used for multi-party experiments.

PortalAlias

A name that will be mapped to the same IP address as the control gateway. SEER in particular expects nodes with certain functions to have certain names.

ProjectUser

The local user under which to mount shared project directories

ProjectName

Project name to derive shared project directories from

Service

a string naming the services to initialize.

SMBShare

The name of the share to mount

Fedkit on Portal Nodes

On portal nodes the fedkit uses ssh to interconnect the segments and bridges traffic at layer 2. If the portal node is a Linux image it needs to have the bridge-tools package available. Like the fedkit on experiment nodes, it will attempt to load that software from repositories if it is not present.

The fedkit configures the portal based on the contents of a configuration file containing the following parameters:

active

a boolean. If true this portal will initiate ssh connections to its peer.

nat_partner

a boolean. If true the fedkit's peer is behind a network address translator. Not used yet.

tunnelip

a boolean. If true use the DETER system for binding external addresses.

peer

a string. A list of DNS names or IP addresses. Usually this is one value, the DNS name of the peer, but passive ends of NATted portals may use a list of addresses to establish routing.

ssh_pubkey

a string. A file in which the access controller has placed the ssh key shared by this portal and its peer. These are nonce keys discarded after the experiment ends.

ssh_privkey

a string. A file in which the access controller has placed the ssh key shared by this portal and its peer. These are nonce keys discarded after the experiment ends.

The passive portal node establishes routing connectivity to the active end, reconfigures the local sshd to allow link layer forwarding and to allow the active end to remotely configure it, and waits. The active end connects through ssh, establishes a link layer forwarding tunnel and bridges that to the experimental interface. It also forwards ports to connect experiment services.

Installing from git

If you prefer to live more dangerously, you can download a recent tree from the git repository on this site and install it. The same packages must be installed as for the tar file version. The commands to check out a local copy from the git repository and install from it are:

$ git clone git://fedd.deterlab.net/fedd
$ cd fedd/fedd
$ make dist
$ cd dist

And from there, install from the fedd-xxx.tar.gz file from the dist directory, as above. The build scripts expect the wsdl interface descriptions to be in ../wsdl relative to the fedd source directory. SOAP/Web Services interface code is generated from those files. When the tarfile is used, the generated files are included, so the wsdl directory is not delivered.

You can also browse the source on the web.