Page tree
Skip to end of metadata
Go to start of metadata

On this page you will find instructions on how to set up a Trust Router on RedHat, CentOS, or Scientific Linux.


1. System Preparation

1.1. Install CentOS

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

  1. Install the operating system via usual mechanism (e.g., net boot CD, ISO in VMware/VirtualBox or the DVD image).
  2. Choose the following server install options: "Basic server”.
  3. Create/choose a secure root password and an initial system user account.
  4. Once installed, make sure you run a yum makecache and yum update to ensure your system is fully up to date.


We would recommend using LVM when disk partitioning to allow easier partition/disk expansion on a live system.


After install, you will want to secure/lockdown the server as best practice dictates - for both the server and any extra software installed. This is beyond the remit of this guide but there are many guides available that provide information on how to secure your CentOS servers and applications.

1.2. Configure CentOS

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

1.2.1. Networking configuration

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

For CentOS networking information please refer to the official Red Hat guide:

CentOS 6
CentOS 7

1.2.2. 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)

Here are sample firewall rules that establish incoming and outgoing rules to both the Test and Live (Jisc Assent) Moonshot trust router infrastructures. If you connect to another Trust Router, adjust these rules to suit:

IP Tables sample firewall rules (Jisc Assent)

-A INPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s 0/0 --dst <IdP/RP Proxy IP address> --dport 2083 -j ACCEPT
-A OUTPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s <IdP/RP Proxy IP address> --dst 0/0 --dport 2083 -j ACCEPT
 -A INPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s,,, --dst <IdP/RP Proxy IP address> --dport 12309 -j ACCEPT
-A OUTPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s <IdP/RP Proxy IP address> --dst,,, --dport 12309 -j ACCEPT

IP Tables sample firewall rules (Test Network)

-A INPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s 0/0 --dst <IdP/RP Proxy IP address> --dport 2083 -j ACCEPT
-A OUTPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s <IdP/RP Proxy IP address> --dst 0/0 --dport 2083 -j ACCEPT
-A INPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s,, --dst <IdP/RP Proxy IP address> --dport 12309 -j ACCEPT
-A OUTPUT -m state --state NEW,ESTABLISHED,RELATED -m tcp -p tcp -s <IdP/RP Proxy IP address> --dst,, --dport 12309 -j ACCEPT

1.3. Add the Required Repositories

Supported versions

At the moment, CentOS/RHEL/SL 7 and 8 are supported.

Moonshot requires three yum repositories to be added to the system - EPEL and the Shibboleth repositories (home of some required dependencies), and the Moonshot repository itself.

  1. Install EPEL by running the following command:

    yum install epel-release

    Depending on your platform, the epel-release package is part of one of the optional repositories.

    On CentOS, it is part of the Extras repository. On RHEL, you must enable both the Optional and Extras repositories. For more information, visit the EPEL homepage.

    On newer releases of Scientific Linux 7, the epel-release package does not exist. Use yum install yum-conf-epel instead. For more information, see the Scientific Linux 7.2 release notes.

  2. Install the Moonshot repository information running one of the the following commands depending on your CentOS version:

    CentOS 7
    yum install -y
    CentOS 8
    yum install -y

    This installs the Yum repository, the current Moonshot GPG key, and a package that can update both. This is the preferred method of deploying repository information.

    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. (Optional - Not required if you install the noshib versions) Install the official Shibboleth repository using one of the following commands, according to your CentOS version:

    CentOS 7
    curl -o /etc/yum.repos.d/shibboleth.repo
    CentOS 8
    curl -o /etc/yum.repos.d/shibboleth.repo

2. Install Trust Router

We’re now ready to install the Trust Router software and its required dependencies. Install the software by running the following command:

yum install trust_router moonshot-noshib

ABRT (Automatic Bug Reporting Tool) issues

The trust_router binaries intentionally terminate child processes by sending the SIGABRT signal. This is interpreted by the Automatic Bug Reporting Tool (ABRT) as an error, generating a report and notifying the user when enabled. As a work around, we recommend editing the /etc/abrt/abrt-action-save-package-data.conf file and adding trust_router to the list of blacklisted modules. The resulting file would look similar to the following:

OpenGPGCheck = yes

# Blacklisted packages
BlackList = nspluginwrapper, valgrind, strace, mono-core, trust_router

# Process crashes in executables which do not belong to any package?
ProcessUnpackaged = no

3. Configure Trust Router

Next, we need to configure the Trust Router.

3.1. RadSec

3.1.1. APC TLS

First, you will need a copy of a client key and certificate (and appropriate CA) from the APC(s) that your Trust Router serves. Copy them onto the filesystem.

You can put these files anywhere on the file system, but this guide assumes you put them in /etc/pki/certs and /etc/pki/private. If you place them in a different location you will need to change the locations below as appropriate.

3.1.2. Connection to APC

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

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

Then check the file and the certificates can be read by the Trust Router user:

sudo -u trustrouter cat /etc/radsec.conf  /etc/pki/certs/tr-*.* /etc/pki/private/tr-*.*

3.2. Trust Router

3.2.1. Daemon Configuration

Your Trust Router will need to have a few core configuration items set. To do this:

  1. Open the default instance's main configuration file at /etc/trust_router/conf.d/default/main.cfg for editing.
    1. Change the hostname to the (fully qualified) hostname of your Trust Router.
  2. Open the /etc/sysconfig/trust_router file for editing. Make sure the configuration items are correct. Items you will most likely have to change are:
    • TR_DEFAULT_TEST_ACCEPTOR - this will need to be set to the (fully qualified) hostname of your Trust Router.

    • TR_DEFAULT_TEST_RPREALM - this will need to be set to the (fully qualified) hostname for your APC.

    • TR_DEFAULT_TEST_COMMUNITY - this will need to be set to the (fully qualified) hostname for your APC.

    • TR_DEFAULT_TEST_REALM - this will need to be set to the (fully qualified) hostname for your APC.

If the /etc/trust_router directory does not exist, you may need to create it yourself, along with the subdirectories mentioned.

3.2.2. Moonshot Configuration

Moonshot, you say? Yes, Trust Router uses Moonshot to authenticate and secure all communications between Trust Router clients and servers. So, you will need to configure the trust router user to make use of the Moonshot flatstore (i.e. telling Moonshot that this is a special system account, not a regular user account), and you will need to import a set of credentials for your Trust Router to use.

  1. Import it using the moonshot-webp command (as the trustrouter user):

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

    The credentials file will be given to you by the administrator of the APC.

3.2.3. Shibboleth

This step is only required if you use the default Moonshot packages. Using the moonshot-noshib packages will not require this step.

Shibboleth, you say? Yes, Shibboleth is used by the Moonshot components to be able to deal with incoming SAML. However, this feature typically isn't used in Trust Router, but its logging will appear in your Trust Router's log files. So, to simplify your log files, it is recommended that you silence the Shibboleth logging. To do this:

  1. Open /etc/shibboleth/console.logger for editing.
  2. Change WARN to NONE on the first line, i.e.

    log4j.rootCategory=NONE, console

3.2.4. Default Peer

If your Trust Router is going to run in its own, standalone, trust network, then skip this step.

If your Trust Router is going to run in a wider trust network, then you can configure your Trust Router's default peer - i.e. the Trust Router it sends its clients to when they ask it to locate a Moonshot entity that your Trust Router doesn't know about. To do this:

  1. Open /etc/trust_router/conf.d/default/peering.cfg for editing. Change the content as follows:

    "default_servers": [
     "[hostname of trust router]"


    If you were configuring your default Trust Router peer to be Janet's Trust Router at, its peering.cfg file would look like this:

    "default_servers": [

3.2.5. Configure your Trust Router

A trust router requires a trust configuration to function correctly. See the trust configuration file for more information.

Place an appropriate trusts.cfg file info the /etc/trust_router directory and symbolically link it into the default configuration directory:

cd /etc/trust_router/conf.d/default
ln -s ../../trusts.cfg

You can find a Trust Router configuration suitable for a Trust Router connecting to at sample Trust Router Client configuration

3.2.6. Start your Trust Router

You are now ready to restart your Trust Router and test it. To do this:

  1. As root, start the Trust Router daemon:

    service trust_router start

4. Testing

To test your trust router, you should attempt a TIDC request on a Moonshot service connected to your trust router. If you have defined a default peer, the TIDC request may take a little longer, but it should succeed.

If it fails, please contact us.

5. Next Steps

At this point, you now have a Trust Router.

5.1. Automatically start the software

5.1.1. Trust Router

To automatically start Trust Router, issue the following command (as root):

chkconfig trust_router on
service trust_router restart 

If this is working correctly, you should see trust_router running as a daemon process.