User Tools

Site Tools


admin:controller-installation

Controller installation

Requirements

Before you set up a CONFINE testbed you need a complete IPv6 /48 prefix to be used exclusively for the testbed (see The management network and Addressing in CONFINE). You may use a public prefix (even a 6to4 would suffice), but the easiest, most durable, resilient, and recommended approach is to generate a new random ULA prefix. For that you may use:

  • Web-based generators like SixXS' or Simple DNS Plus', or
  • The following Unix command, which should yield an output similar to the one shown below (hexadecimal digits after fd shall differ):
    $ random5B=$(hexdump -n5 -e '/1 "%02x "' /dev/urandom)
    $ printf 'fd%s:%s%s:%s%s::/48\n' $random5B; unset random5B
    fdc0:7246:b03f::/48

You also need an identifier-like name for your testbed. For instance, for My Testbed, mytestbed shall be used.

It is also advisable that you have a contact email address for support and other administrative matters. Here we use the sample address mytestbed@example.com.

For installing the Controller software it is recommended the use of a dedicated server. The Controller needs a running Debian Wheezy or Jessie installation, the cleaner the better. It is however highly important that the server is already able to send email to arbitrary addresses for notifications (the configuration of the mail server falls outside of the scope of this guide, though). The server should be reachable by nodes and users at the IP level; at the very least ports 80/tcp or 443/tcp should be available for the web interface, and ports 655/udp and 655/tcp for the tinc overlay supporting the management network.

A virtual machine or container should be enough to host the controller server. In the later case, the server should be allowed to use the devices tun (for tinc interfaces) and fuse, and to mount its own filesystems (for node firmware generation).

Deployment

We will be using the deploy-controller.sh script included in Controller sources to automate the installation steps. In case of errors, or if the installation stops prematurely, please take note of the first unsuccessful command (in bold letters). Then refer to Installation in order to proceed to step-by-step installation commands starting from the failing one. If you still cannot fix the issue, please look at the Controller documentation or ask for help in the confine-devel mailing list.

Please note that some errors are inocuous or expected; they will be pointed out below. Also note that the script installs NginX, which is recommended as the web server for the Controller over Apache (which is still currently used by Virtual CONFINE Testbed (VCT)). Thus, web server configuration examples from this point on will be specific for NginX unless noted otherwise.

To begin with the installation of the Controller software after preparing your dedicated server, upload the latest version of deploy-controller.sh to the server. Log into the server (e.g. via SSH) as root and define the following shell variables for the testbed name and management network prefix of your choosing, for example (please use different values!):

# TESTBED=mytestbed
# MGMT_PFX=fdc0:7246:b03f::/48

Now run the installation script using the Bash shell (standard sh will not work):

# bash /path/to/deploy-controller.sh -t local -j "$TESTBED" -m "$MGMT_PFX"

After downloading and installing software dependencies for the Controller, you will be asked to create an initial superuser account. In this example we create a generic account with the testbed contact address, but accounts belonging to normal personal users may act as superusers as well (if granted permission by another superuser). Please take the time to choose and provide proper values to the following questions asked by the installation process (example answers are shown):

Username: super  # identifier-like, no spaces or punctuation
Email Address: mytestbed@example.com  # testbed contact/support address
Name: Super User  # free form, spaces and punctuation allowed
Password:   # some secure password
Password (again):   # same secure password
Superuser created successfully.

The installation script proceeds to configure the tinc daemon for the management network overlay. The script may fail to reload the daemon, but this is expected since tinc may not be running yet.

A certificate for controller APIs is created next. The installation process will ask for the usual items for certificate request creation, except for the common name, which is preconfigured to the server's address in the management network as shown below (along with example answers):

Country Name (2 letter code) []: ES
State or Province Name (full name) []: CT
Locality Name (eg, city) []: Barcelona
Organization Name (eg, company) []: My Organization
Organizational Unit Name (eg, section) []: My Testbed
Email Address []:  mytestbed@example.com  # testbed contact/support address
Common Name: fdc0:7246:b03f::2  # automatically set
writing new certificate to '/home/confine/mytestbed/pki/cert'

You may see some diff errors about missing files when the script is configuring NginX; this is normal since there is no previous configuration. Stopping celerybeat may also fail since it may not be runnnig yet, and Apache restart may fail as well since NginX is being used instead; these errors are inocuous as well.

 ... seems that everything went better than expected :)

This line marks the end of the installation. After this point you should be able to access the controller web UI via HTTP and log in with the superuser you just created above. Otherwise, review the output from the installation commands to spot possible errors.

The installation should have created a new system user (a Unix account named confine by default) and a Controller deployment directory for the testbed inside of the user's home directory (e.g. ~confine/mytestbed). The system user is not related with the Controller superuser account created above, and besides owning the Controller data and configuration files under its home directory, it is meant to manage the Controller by executing the manage.py script, which is also part of the deployment.

The system user is not given a password though, so to allow it to log into the controller server a new password should be set (e.g. running passwd confine) or SSH authorized keys be added (e.g. to ~confine/.ssh/authorized_keys). Now you should be able to run a command like ssh confine@controller.example.com, where controller.example.com is the DNS name of the server where the Controller is installed.

Management address

A final step is needed to ensure the presence of the management network address early on boot. Otherwise, testbed services may start before tinc and they would fail to listen on the management address (see Nginx failed to start. Cannot assign requested address? for an example case). Run ip -6 addr show dev confine and note down the ADDRESS/PREFIX after inet6. Edit /etc/network/interfaces and add the following lines at the end of the stanza of the main network interface (usually eth0):

# Ensure that the management address is present early on boot.
up ip addr add ADDRESS dev $IFACE  # leave the "/PREFIX" out
up while [ "$(ip -6 addr show tentative)" ]; do sleep 1; done

HTTPS

We recommend that you customize your NginX configuration to serve the web interface over HTTPS instead of HTTP. Just take care not to override the configuration and certificate used to listen on the management network address. Using wildcard addresses on the HTTPS-protected web interface should be fine, though. For an HTTPS-only setup, you may add this server entry to /etc/nginx/conf.d/$TESTBED.conf:

server {
    listen 80;
    listen [::]:80 ipv6only=on;
    return 301 https://$host$request_uri;
}

Then in the existing plain HTTP server entry, change the listen options to:

listen 443 ssl;
listen [::]:443 ipv6only=on ssl;

Add the ssl_certificate and ssl_certificate_key options pointing to your own files, and restart NginX with service nginx restart.

admin/controller-installation.txt · Last modified: 2015/09/03 12:16 by ivilata