System Preparation

Install Debian 8

The first thing that is required is a Debian 8 machine - this can be physical or virtual.

1. Install Debian 8 (Jessie) via usual mechanism (e.g., netboot CD, ISO in VMware/VirtualBox or the DVD image.
2. Choose the following server install options: "Debian desktop, SSH server, Standard system utilities”.
3. Create/choose a secure root password and an initial system user account.
4. Once installed, make sure you run an apt-get update and apt-get upgrade to ensure your system is fully up to date.

Configure Debian 8

Next, there are a few Debian configuration options that need to be set in advance.

Networking configuration

For production deployments, it is recommended that the machine be assigned a static IP address.

Firewall configuration

The following ports are required to be accessible from the outside world, both in the local firewall and in any external firewalls:

• 2083/tcp (for RadSec connections to other Moonshot entities)
• 12309/tcp (for Trust Router client connections - if using the Trust Router to broker trust relationships between entities)

Add the Moonshot Repository

1. Add the Moonshot Debian Jessie repository to your system. To do this, run the following command (as root, or using sudo):

   $ echo "deb http://repository.project-moonshot.org/debian-moonshot jessie main" > /etc/apt/sources.list.d/moonshot.list

2. Install the Moonshot GPG key:

   $ wget -O - http://repository.project-moonshot.org/key.gpg | apt-key add -

   Verifying the Moonshot GPG key

   If you wish to verify the Moonshot GPG key's validity and integrity, please see the Packaging GPG Key for further details.

3. Update the apt cache with the new repository information:

   $ apt-get update

Certificates

We need to get FreeRADIUS to create some private and public keys to use for its RadSec connections. Create and install the certificates by doing the following (as root).

1. Change into the /etc/freeradius/certs directory

   cd /etc/freeradius/certs

2. Edit the certificate generation properties in client.cnf, server.cnf, and ca.cnf as follows:

   1. In the ca.cnf file:
      1. In the [ req ] section, add encrypt_key = no

      2. In the [CA_default] section, change the default_days from 60 to a higher number (this is how long the certificates you create will be valid for). When the certificates expire, you will have to recreate them.

      3. in the [ certificate_authority ] section, change all of the parameters to match those of your organisation. e.g.

         [certificate_authority]
         countryName             = GB
         stateOrProvinceName     = England
         localityName            = Camford
         organizationName        = Camford University
         emailAddress            = support@camford.ac.uk
         commonName              = "Camford University FR Certificate Authority"

   2. In the server.cnf file:

      1. In the [ req ] section, add encrypt_key = no
      2. In the [CA_default] section, change the default_days from 60 to a higher number (this is how long the certificates you create will be valid for). When the certificates expire, you will have to recreate them.

      3. in the [ server ] section, change all of the parameters to match those of your organisation. e.g.

         [server]
         countryName             = GB
         stateOrProvinceName     = England
         localityName            = Camford
         organizationName        = Camford University
         emailAddress            = support@camford.ac.uk
         commonName              = "Camford University FR Server Certificate"

         When changing passwords in the [ req ] section of the server.cnf file, you must also update the private_key_password option in the FreeRADIUS mods-available/eap file with the same password.

         We recommend that you do not change these defaults.

   3. In the client.cnf file:

      1. In the [ req ] section, add encrypt_key = no
      2. In the [CA_default] section, change the default_days from 60 to a higher number (this is how long the certificates you create will be valid for). When the certificates expire, you will have to recreate them.

      3. in the [ client ] section, change all of the parameters to match those of your organisation. e.g.

         [client]
         countryName             = GB
         stateOrProvinceName     = England
         localityName            = Camford
         organizationName        = Camford University
         emailAddress            = support@camford.ac.uk
         commonName              = "Camford University FR Client Certificate"

         All of the organisation parameters (countryName, localityName, etc) need to match in the three .cnf files but the commonName must be unique in each file)

3. Clear out any old certificates in the directory:

   make destroycerts

4. Run the bootstrap script to generate the certificates

   ./bootstrap

5. Create a file that is the concatenation of the certificate and private key of the client.

   openssl x509 -in client.crt > client.pem ; cat client.key >> client.pem

6. Because the above command was run as root, the keys and certificates created will not be readable by the FreeRADIUS user by default, and FreeRADIUS will not be able to start. To fix this, reset the group for the files:

   chgrp freerad {client,server,ca,dh}*

RadSec

Next we need to configure RadSec. We do this by creating a file at /etc/radsec.conf with the following:

realm gss-eap {
	type = "TLS"
	cacertfile = "/etc/freeradius/certs/ca.pem"
	certfile = "/etc/freeradius/certs/client.pem"
	certkeyfile = "/etc/freeradius/certs/client.key"
	disable_hostname_check = yes
	server {
		hostname = "127.0.0.1"
		service = "2083"
		secret = "radsec"
	}
}

Dynamic Realm support

We need to tell your FreeRADIUS server to support dynamic lookup of realms.

1. Open /etc/freeradius/proxy.conf for editing:
   1. Towards the top of the file is a stanza beginning "proxy server {". Find this.

   2. Below this, add dynamic = yes, like so:

      proxy server {
              dynamic = yes

      
      

Configure FreeRADIUS to use Trust Router

Configuring FreeRADIUS realm lookup

We need to configure the community and rp_realm appropriate for your Moonshot service, and the Trust Router that it will connect to.

1. Open the /etc/freeradius/mods-enabled/realm for editing.
2. Find the "realm suffix {" configuration directive, and fill out the fields as appropriate.
3. Repeat this for the "realm bangpath {" configuration directive.

4. For the default Jisc Assent Trust Router this will look like the following:

   realm suffix {
     format = suffix
     delimiter = "@"
     default_community = "ov-apc.moonshot.ja.net"
     rp_realm = "Your service realm as registered in the Jisc Assent Portal"
     trust_router = "tr.moonshot.ja.net"
     rekey_enabled = yes
   }
   
   realm bangpath {
     format = prefix
     delimiter = "!"
     default_community = "ov-apc.moonshot.ja.net"
     rp_realm = "Your service realm as registered in the Jisc Assent Portal"
     trust_router = "tr.moonshot.ja.net"
     rekey_enabled = yes
   }

   Example

   Camford University has a Moonshot service registered in the Jisc Assent Portal using the service realm of moonshot.camford.ac.uk, so its realm file would look like this:

   realm suffix {
     format = suffix
     delimiter = "@"
     default_community = "ov-apc.moonshot.ja.net"
     rp_realm = "moonshot.camford.ac.uk"
     trust_router = "tr.moonshot.ja.net"
     rekey_enabled = yes
   }
    
   realm bangpath {
     format = prefix
     delimiter = "!"
     default_community = "ov-apc.moonshot.ja.net"
     rp_realm = "moonshot.camford.ac.uk"
     trust_router = "tr.moonshot.ja.net"
     rekey_enabled = yes
   }

Register your Trust Router client with a Trust Router

At this point, the Moonshot service needs to be associated with a Trust Router. To do this, you need to contact the operator of a Trust Router you wish to join for their specific instructions on how to do this.

Once you have joined the Trust Router service, you will be issued with a Trust Router credential file in XML file format.

1. You must import the issued credential file using the moonshot-webp command as the freerad user:

   su - --shell /bin/bash freerad
   moonshot-webp -f [path to credential file]

2. Check that the credential has been correctly imported, by starting the UI and checking the credential has been correctly imported:

   moonshot

3. If the file exists, the credential file's contents should be present in the file.