phpDocumentor Configuration
[ class tree: Configuration ] [ index: Configuration ] [ all elements ]

Installing and configuring eduroam CAT on your server

Here, you will learn everything you need to know!

Table of Contents

Introduction

eduroam Configuration Assistant Tool (CAT) is a user-oriented system helping to configure various wireless devices for eduroam.

The CAT database contains information provided by local eduroam admins, i.e. items like supperted EAP methods, trusted RADIUS server names, trusted server certificates, etc.

CAT configurators are device dependant entities (Windows installers, XML profiles, etc.), which carry all institution-depenent information. Such a configurator is created when a user selects his/her instition, possibly also user group and one of supported devices.

See Glossary for a more detailed description of terms used in this text.

Packages required prior to installing CAT

The CAT generates installers for numerous operating systems. Consequently, many console tools need to be installed for all the profile generators to work correctly. The prerequisites are:

  • Apache2 Web Server
  • MySQL Server
  • PHP 5.3
  • PHP extensions: "gettext", "openssl", "PECL:IMagick", "GeoIP" and "MySQL"
  • simpleSAMLphp
  • NSIS 2.46 or higher - either as a native Linux binary or on Wine
  • qrencode
  • zip
  • wpa_supplicant (eapol_test utility)
  • rad_eap_test - correctly configured to find eapol_test in the system
  • OpenSSL

Configuring the required prerequisite packages

Here are some extra configuration hints for these packages:

  • Operating System
    • make sure the base system can send emails to the outside world via PHP's mail() function
    • language display needs the corresponding locales to be installed (check config/config-template.php for the exact list of locales that CAT can support right now)
  • Apache
    • the Directory for installer downloads (configurable, defaults to web/downloads/ ) needs to have "AllowOverrides FileInfo" set
    • the directories under web/ need to be accessible from DocumentRoot
    • the CAT log dir (configurable, defaults to /var/log/CAT/ ) needs to be accessible for writing
    • if you want to use client certificates for administrative user authentication, be sure set a sufficiently large SSL Renegotiation Buffer size (e.g. SSLRenegBufferSize 10486000 for 10 MB max. upload size)
  • simpleSAMLphp
    • configure it as a service provider, authenticating towards an IdP of your choice. Attribute mapping is defined in config.php
  • NSIS
    • needs to have the plug-ins "NSISArray", "GetVersion", "ZipDLL" available
    • "makensis" needs to be in your $PATH and executable
  • rad_eap_test
    • needs to be in your $PATH and executable.
    • The >1500 Bytes packet inflation currently needs a slight patch, which is available on request.
  • GeoIP
    • best install as a system package or use instructions from http://dev.maxmind.com/geoip/downloadable#PHP-7 or http://php.net/manual/en/geoip.installation.php
    • download GeoLiteCity and GeoLiteCityv6 databases from http://geolite.maxmind.com/download/geoip/database/GeoLiteCity.dat.gz and http://geolite.maxmind.com/download/geoip/database/GeoLiteCityv6.dat.gz
    • unzip them and copy into GeoIP directory changing names to GeoCity.dat and GeoCityv6.dat (the directory is /usr/share/GeoIP or something similar, GeoIP will display an error message if the database is missing and you will be able to guess the required location).
    • arrange for downloads each month (databases are udated on the first Thursday of each month)

Installing CAT

  • unpack the distribution
  • create the config/config.php file from the supplied template config-template.php
  • create the devices/devices.php file from the supplied template
  • on a MySQL server, create the databases as per the schema definition in schema/schema.sql
  • make sure that you can connect to that database
  • make sure that the web/downloads directory exists and is writeable to the Apache web server user
  • make sure that simplesamlphp is installed
  • make sure that simplesamlphp openid module is enabled and google (or any IdP of your choice) is uncommented in authsources
  • using your browser, check if the main interface is running (web subdirectory)
  • if so, go to the master management page to have your system prerequisites checked (web/admin/112365365321.php)

Configuring CAT

After creating config.php as above, adapt it to your needs and the realities on your server. A full description of the config options in this file can be read by clicking on "Classes: Config" on the left-hand side. In particular, pay attention to the following:

  • reference the autoloader of your simpleSAMLphp installation correctly in config.php
  • enter the connection details to the database(s)

The device configuration file is in devices/devices.php. There is a template file devices-template.php - you can simply copy it to have a devices.php. Unless you want to disable specific device modules, or have custom ways to digitally sign installers, it is not necessary to change this file.

Customisation / Look and Feel

CAT ships with a default look-and-feel for the eduroam consortium. You can adapt most of its appearance to your local needs by changing colours and images. The sources for the images are scattered around the source tree. Here is a list of LOGOs to edit:

  • web/resources/images/consortium_logo.png (website main logo)
  • web/resources/images/gradient-bg.png (gradient top-down for the adverising 'film roll'
  • web/resources/images/screenshots/* (sample installers on 'film roll' - supplied ones carry digital sig from TERENA and eduroam logo; might not be appropriate for your use
  • web/favicon.ico (website favicon)
  • devices/ms/Files/eduroam_150.bmp (logo to embed in Microsoft installers)
  • devices/ms/Files/eduroam32.ico (window icon for Microsoft installers)
  • devices/ms/Files/cat_bg.bmp (background for front page on windows installers)

The colours are all configured in the web/resources/css/ directory.

  • The default eduroam colour number 1 is #BCD7E8 (light blue). Change it to your own colours as needed.
  • The default eduroam colour number 2 is #0A698E (dark blue). Change it to your own colours as needed.

Glossary

Device:
  • An operating system instance which covers a group of wireless client devices; it may be just a group of oerating systems like "Microsoft Windows Vista and newer" or "Android smartphones" or "iOS devices"
  • Profile:
  • A group of users which share the same network configuration parameters (except for user credentials), thus a profile shares the same supported EAP methiods, the same trusted servers etc. Even if the entire institution needs only one profile it will always be created; configurators are prepared per (profile, device) tuple.

  • Documentation generated on Wed, 08 Apr 2015 07:12:46 +0000 by phpDocumentor 1.4.4