[[PageOutline]]

This page provides instructions for grabbing/configuring SFA from git, assuming a site which is already running a stable myplc and just needs to add SFA

We recommend sites use the tag `sfa-geni-gec9` from the PlanetLab GIT repository.

IF you were already running an older version of SFA, including RPM-based versions sfa-0.9-14 or earlier, you will need to remove all old sfi credentials to handle a credential format change.  NOTE: if those credentials were used to create any slivers which are still active, you may lose the ability to modify those slivers.  Please contact the GPO before upgrading if this is a concern for you.  If you were already running a more recent SFA, this upgrade should be harmless, though it's always good to proceed with caution around any upgrade.

= Variables =

You will need to configure SFA using some of the same variables which were configured for PLC.  Get these values by running `plc-config-tty` in read-only mode on your myplc host:
{{{
$ plc-config-tty
Enter command (u for usual changes, w to save, ? for help) s PLC_SLICE_PREFIX
PLC_SLICE_PREFIX = <plc_slice_prefix>

Enter command (u for usual changes, w to save, ? for help) s PLC_API_HOST
PLC_API_HOST = <plc_api_host>

Enter command (u for usual changes, w to save, ? for help) s PLC_DB_HOST
PLC_DB_HOST = <plc_db_host>

Enter command (u for usual changes, w to save, ? for help) s PLC_ROOT_USER
PLC_ROOT_USER = <plc_root_user>

Enter command (u for usual changes, w to save, ? for help) s PLC_ROOT_PASSWORD
PLC_ROOT_PASSWORD = <plc_root_password>

Enter command (u for usual changes, w to save, ? for help) s PLC_DB_PASSWORD
PLC_DB_PASSWORD = <plc_db_password>

Enter command (u for usual changes, w to save, ? for help) q
}}}

= Step 1: get a tarball of the `sfa-geni-gec9` tag of SFA =

On any machine with git installed:
{{{
git clone git://git.planet-lab.org/sfa.git
gittag=sfa-geni-gec9
cd sfa
git archive --format=tar --prefix=${gittag}/ ${gittag} | gzip > ${gittag}.tar.gz
}}}

This will produce a tarball named `sfa-geni-gec9.tar.gz`.  Copy the tar file to your myplc node.

= Step 2: install SFA prerequisites =

If this is the first time you are installing SFA on this myplc, you will need to install prerequisite packages, and you will need to make certain that particular packages are up-to-date:
{{{
sudo yum update fedora-release
sudo yum install m2crypto python-dateutil python-psycopg2 myplc-config pyOpenSSL python-ZSI libxslt-python xmlsec1-openssl-devel python-lxml
sudo yum upgrade pyOpenSSL python-lxml
}}}

= Step 3: Compile and install the SFA code =

Compile the source code in a working directory of your choice:
{{{
mkdir ~/src
cd ~/src
tar xvzf ~/sfa-geni-gec9.tar.gz
cd sfa-geni-gec9
make
}}}

Expect about 6 lines of output and no obvious errors.  Assuming that looks okay, install SFA:
{{{
sudo make install
}}}

= Step 4: Configure SFA =

== Step 4A: Clean old certificates if you were already running SFA ==

IF you were already running an older version of SFA, including RPM-based versions sfa-0.9-14 or earlier, you will need to remove all old sfi credentials to handle a credential format change.  NOTE: if those credentials were used to create any slivers which are still active, you may lose the ability to modify those slivers.

{{{
sudo /etc/init.d/sfa stop
sudo sfa-nuke-plc.py
sudo rm /etc/sfa/trusted_roots/*.gid
sudo rm -rf /var/lib/sfa/
rm ~/.sfi/*.gid
rm ~/.sfi/*.cert
rm ~/.sfi/*.cred
}}}

== Step 4B: Create new configuration if this is the first time SFA has run on this PLC ==

Note that many of these configuration options require variables taken from your myplc configuration itself.  See [#Variables] for details.

{{{
$ sudo sfa-config-tty
Enter command (u for usual changes, w to save, ? for help) u
 SFA_INTERFACE_HRN: plc.<plc_slice_prefix>
 SFA_REGISTRY_ROOT_AUTH: plc
 SFA_REGISTRY_HOST : <plc_api_host>
 SFA_AGGREGATE_HOST : <plc_api_host> 
 SFA_SM_HOST : <plc_api_host>
 SFA_PLC_DB_HOST : <plc_db_host> 
 SFA_PLC_DB_USER : postgres
 SFA_PLC_USER: <plc_root_user>
 SFA_PLC_PASSWORD: <plc_root_password>
 SFA_PLC_DB_PASSWORD: <plc_db_password>  
 SFA_PLC_URL : [https://localhost:443/PLCAPI/] 
Enter command (u for usual changes, w to save, ? for help) w
Enter command (u for usual changes, w to save, ? for help) q
}}}

= Step 5: Start SFA =

Start up SFA once, to create the initial /etc/sfa/sfa_config.py, and stop it again
{{{
sudo service sfa reload
}}}

Import the PLC database into SFA:
{{{
sudo sfa-import-plc.py 
}}}
 
Start up SFA again:
{{{
sudo service sfa restart
}}}

= Step 6: Create local sfi credentials if desired =

In order to use omni to reserve resources using the `pgeni.gpolab.bbn.com` slice authority, you do not need to test sfi or create local users with sfi certificates.  You should be able to install SFA and configure it to allow omni sliver creation for GEC9 demos without ever installing a local sfi user on your myplc.  So it is fine to skip this step.

However, you may want to create local users for other purposes, or to test functionality.  If you want to do that, [wiki:GeniApiInstallationMyPlc#InstallSFA] has instructions for creating an sfi client configuration and using it to test `getversion` in steps 6 and 7.

= Step 7: Install the `pgeni.gpolab.bbn.com` certificate =

Configure your SFA instance to allow slivers to slices created at the GEC9 demo slice authority, `pgeni.gpolab.bbn.com`.

Get a copy of the certificate:
{{{
wget http://www.pgeni.gpolab.bbn.com/ca-cert/pgeni.gpolab.bbn.com.pem
}}}

Copy that certificate into a `.crt` file under `/etc/sfa/trusted_roots`:
{{{
sudo cp pgeni.gpolab.bbn.com.pem /etc/sfa/trusted_roots/pgeni.gpolab.bbn.com.crt
}}}

Restart sfa:
{{{
sudo service sfa restart
}}}

= Step 8: Configure host firewall to allow SFA =

If your myplc is running iptables, you will need to add rules to allow inbound connections to the `sfa-server.py` daemon, which listens on three ports.  Add the following rules to `/etc/sysconfig/iptables`:
{{{
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 12345 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 12346 -j ACCEPT
-A RH-Firewall-1-INPUT -m state --state NEW -m tcp -p tcp --dport 12347 -j ACCEPT
}}}
placing them immediately ''before'' the default reject rule:
{{{
-A RH-Firewall-1-INPUT -j REJECT --reject-with icmp-host-prohibited
}}}

Then restart iptables:
{{{
sudo service iptables restart
}}}

= Outcome =

Assuming SFA comes up cleanly, it should now be possible for people to create slivers via omni at your myplc, using the instructions at OmniSetupGEC9Demos.  Of particular note, you will want to run:
{{{
./src/omni.py listresources -n -a http://<plc_www_host>:12346 
}}}
to obtain an rspec describing the planetlab nodes available at your myplc.  This will tell you what your planetlab hosts are called by omni, and thus how to reserve them.