Installing HAiku

TOC | Administrating your Home Agent with HAiku

This chapter describes how to install the HAiku software on top of your Home Agent and documents its basic configuration.

1.  Requirements

• A functional Home Agent
• IPv6 connectivity: for the moment HAiku supports only IPv6 Mobility
• Ruby on Rails and dependencies
• HTTP server: apache, or lighthttpd, ...
• Database server: any relational database management system working with Rails (for instance MySQL version 5 or later)
• Mail server: sendmail or exim
• IPsec tools
• sudo
• ssh (if you chose to provide Live CDs)

2.  Getting the software

Get the latest version of HAiku at http://software.nautilus6.org/HAiku/.

The latest image of Homeguy, the MIPv6 Live CD to use with the service can be downloaded here. You should download the the master ISO used to build custom Live CDs for Mobile Nodes. HAiku also now comes with the sources of Homeguy.

3.  Install Home Agent

HAiku runs on top of a Home Agent and thus requires that your Home Agent is fully functional, i.e. you can register Mobile Nodes using IPsec.

We do not describe here how to setup a Home Agent. Please read the following documentations:

• Mobile IPv6 Howto for MIPL (GNU/Linux box)
• SHISA Howto (*BSD box)
• NEPL Howto
• How to configure IPsec for Mobile IPv6

However, here are some advices:

• we are providing packages for Debian and Ubuntu, with kernel and MIPL daemon with all the needed patches applied. Check the FAQ about our package repository for more information.
• the "extra" directory in HAiku contains sample configuration files, startup scripts and patches to be applied.
• you should force the use of IPsec to authenticate your users and reject others. Check the "extra" directory for MIPL configuration sample. With SHISA, this can be achieved by putting the following parameter in your startup configuration file:

 ipv6_mobile_security_enable="YES"

4.  Install required softwares (MySQL, Apache, Rails, ...)

We do not provide support on how to install required softwares. You should directly find documentation on their project page:

• MySQL installation;
• Apache documentation;
• Ruby on Rails wiki.

However, here are some advices:

• it is a good idea if your web server listens at both IPv4 and IPv6 so users can manage their MNs and create Live CDs even if they don't have IPv6 connectivity.
• your web server needs to serve for https as well. You can create your own certificate or get a free one.

5.  Install HAiku

5.1  Create the user_environment.rb file

The first step in the HAiku installation process is to create a valid config/environments/user_environment.rb. Copy the example file and edit it to match your needs:

 $ cp config/environments/user_environment.rb.example \
           config/environments/user_environment.rb
 $ # Now edit the config/environments/user_environment.rb file 

5.2  Create the database

We will now create the database that will be used by HAiku. We will detail the steps for the MySQL database server.

First you need to create the empty database and the special user under which HAiku will access the database. You really should avoid to connect to the database with the root user. Supposing you are at the root of HAiku directory, you can proceed as follow:

 $ cp db/create_user.sql.example db/create_user.sql
 $ # Edit the create_user.sql file to set the password for the haiku user
 $ cat db/create_user.sql | mysql -u root -p
 $ rm db/create_user.sql

You will be asked for the root password.

Then, you have to create a valid config/database.yml file in order to be able to connect to the database from HAiku:

 $ cp config/database.yml.example config/database.yml
 $ # Edit the database.yml file to set the password for the haiku user
 $ # Make sure the file is readable by the web server daemon user

Finally you need to import the database structure into your DB server thanks to rails migrations.

When you made backups of your DB you can execute the following command at the root of HAiku directory:

 $ rake db\:migrate RAILS_ENV="production"

5.3  Add the web daemon to the sudoers

HAiku will have to execute commands that are usually reserved to the root user. We will explicitly authorize the web daemon to run the setkey command (from the IPsec tools package) and reload MIPL daemon (with Linux Home Agents) without the need to enter a password thanks to the sudo utility. Following is an example of configuration of sudo when the web daemon is run by the www user. Adapt it to your needs:

 # User alias specification
 User_Alias  WWW = www

 # Cmnd alias specification
 Cmnd_Alias SETKEY = /sbin/setkey
 # Line below is only necessary for Home Agents running Linux
 Cmnd_Alias RELOAD_MIP6D = /usr/bin/killall -HUP mip6d
 Cmnd_Alias RELOAD_RACOON2 = /usr/bin/killall -HUP iked, \
                             /usr/bin/killall -HUP spmd
 Cmnd_Alias CREATE_CERT = /usr/bin/make -C /etc/openssl-ca *
 Cmnd_Alias CHOWN_RACOON2 = /bin/chown root\:root \
                            /usr/local/v6/etc/mobileip6/[0-9]*/racoon2.conf
 # Defaults specification
 Defaults    env_reset

 # User privilege specification
 root    ALL=(ALL) ALL
 WWW     ALL = NOPASSWD: SETKEY, RELOAD_MIP6D, \
               RELOAD_RACOON2, CREATE_CERT, CHOWN_RACOON2

5.4  Create a directory for HAiku files and fix the permissions

HAiku will need to store some persistent files on the Home Agent for the configuration of IPsec associations (and policies on BSD hosts) with the Mobile Nodes. You have to create a directory where the web server daemon has the sufficient permissions to read and write. Following is an example for the HAiku persistent files directory located in /usr/local/v6/etc/mobileip6 and www as the web server daemon user. As root user do:

 # mkdir /usr/local/v6/etc/mobileip6
 # chgrp www /usr/local/v6/etc/mobileip6
 # chmod 770 /usr/local/v6/etc/mobileip6

HAiku will also need to have the permission to read read and write the log and tmp directories of the application. Let's do the same. Supposing you are in HAiku root directory, type the following commands as root:

 # chgrp -R www log tmp
 # chmod -R 770 log tmp

5.5  Automatic Home Agent startup

We will setup a script that will launch automatically the Home Agent daemon and load the SAs (and SPs under BSD) for registered Mobile Nodes at boot time. You will find such scripts in the "extra" directory. Read the enclosed README file for further instructions.

5.6  Configure HAiku

Now you will have to configure HAiku for your service. Open the config/environment.rb file and edit it to match your needs/setup.

Also, make sure that the settings in config/environments/user_environment.rb file are right.

5.7  Configure the web server

The last step to see your installation of HAiku alive is to configure your web server to serve the HAiku web pages. This configuration will be done just as any other rails application. Again, you may want to check the Ruby on Rails wiki for hints on how to do that.

We suggest however that you use fastcgi to speed up the processing of the pages by the web server.

Also be especially careful with the shebang line of the dispatch.(f)cgi file, that should be pointing to your ruby interpreter.

6.  Install Live CD

The Live CD is not mandatory and you may skip this section if you don't plan to provide custom Live CDs to your users.

6.1  On the Live CD server

We will separate the Home Agent and the server that creates the Live CDs. Choose a server with enough bandwidth and disk space to host your Live CDs.

Then, generate the structure that you will use to create and serve the Live CDs:

 $ ssh your_user@your_live_cd_server
 $ mkdir ~/bin
 $ mkdir ~/public_html
 $ mkdir ~/config
 $ mkdir ~/live-cd

Retrieve the latest image of Homeguy and uncompress in ~/live-cd/:

 $ cd ~/live-cd/
 $ wget http://software.nautilus6.org/packages/homeguy/homeguy-latest.tar.gz
 $ tar xvfz homeguy-latest.tar.gz

The iso file must be mounted and its content copied in ~/live-cd/master/:

 # mount -o loop homeguy-master-XXX.iso /mnt/
 $ cd ~/live-cd
 $ mkdir master
 $ cp -a /mnt/* master/
 # umount /mnt

Check that the file "boot/isolinux/isolinux.bin" has the write flag for the user that will generate the Live CDs.

We will then create an empty HTML file to protect the content of the stored Live CD directory against curious people. You will have to create an 'index.html' file in '~/public_html' with the following content. Adapt this to your needs, especially don't forget to specify the URL of your service:

 <?xml version="1.0" encoding="ISO-8859-1"?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>

 <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1" />
 <meta http-equiv="refresh" content="0; url=<url_to_HAiku>" />
    <title>Redirection</title>
 <meta name="robots" content="noindex,follow" />
 </head>
 <body>
     <p><a href="url_of_your_service">Redirection</a></p>
 </body>
 </html>

At last, configure a web server on this machine to permit to access from the web to the Live CD generated ISO files. For instance, you could add the following to an Apache configuration file:

 Alias /live-cd/ "/home/your_user/public_html/"
  <Directory /home/your_user/public_html/>
   AllowOverride all
   Order allow,deny
   Allow from all
 </Directory>

If everything went fine, you should now have something like the following:

 + home directory
     + bin
     |   + create_n6_iso.sh (will be copied here later)
     + config
     + live-cd
     |   + master
     + public_html (containing the generated Live CDs)
         + index.html (that redirects to the service home page)

6.2  On the Home Agent

We will set up some ssh authentication between your Home Agent and this server, for the user running the order_cd.sh script so it can connect on the remote host without the need to ask a password. This can be done via the ssh-keygen command:

 $ ssh-keygen -t rsa
     -> For the passphrase, simply type enter
 $ cat .ssh/id_rsa.pub | ssh your_user@your_live_cd_server \
        "cat - >>.ssh/authorized_keys"

We will now copy the extra/live-cd/create_n6_iso.sh file to the 'bin' directory on your Live CD server:

 $ scp extra/live-cd/create_n6_iso.sh \
        your_user@your_live_cd_server:~/bin

Modify the file extra/live-cd/order_cd.sh, to set the following parameters:

 USER="your_user"
 SERVER="your_live_cd_server"
 HAIKU_TMP="path/to/your/haiku/tmp/" 

Last but not least, add a cron job running periodically the script extra/live-cd/order_cd.sh. Here is how the crontab looks like to run the script every 10 minutes:

 # Order Live CD every 10 minutes
 */10 * * * *  path/to/haiku/extra/live-cd/order_cd.sh > /dev/null 2>&1

7.  Create first user and initial setup

Once the installation is complete, go to the base URL of your service. You should see the login page of HAiku. You can now register for an account. The first account registered will have the administrative right over the application so be sure to be the first one to register for an account.

You should receive a confirmation email containing the account validation link. If for some reason your configured SMTP server was not configured or running, the production.log file contains a copy of the confirmation email. You will however need to fix your SMTP server to work properly.

When you have successfully registered and logged in the web interface, you will directly have the possibility to make the initial setup of your Home Agent.

Fill in the name, description, IPv6 address of your Home Agent and the contact address of your service and you are ready to open the service to users.

TOC | Administrating your Home Agent with HAiku