= Installing HAiku This file describes how to install the HAiku software on top of your Home Agent and documents its basic configuration. == 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 choose to provide Live CDs) == Getting the software Get the latest version of HAiku at [1]. The latest image of Homeguy, the MIPv6 Live CD to use with the service, can be downloaded at [2]. You should download the master ISO used for building custom Live CDs for Mobile Nodes. HAiku also now comes with the sources of Homeguy. == 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, however we would like to redirect you to the following documentations: * Mobile IPv6 Howto for MIPL (GNU/Linux box) [3] * SHISA Howto (*BSD box) [4] * NEPL Howto [5] * How to configure IPsec for Mobile IPv6 [6] 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 at [7] 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" == 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 [8]; * Apache documentation [9]; * Ruby on Rails wiki [10]. However, here are some advice: * 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 [11] or get a free one [12]. == Install HAiku === 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 Finally you need to import the database structure into your DB server thanks to rails migrations. /!\ Before upgrading to a newer version of HAiku, always backup your database. This is mandatory when upgrading from version prior to 0.3 to not lose your data. 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" === 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 Do notice that on GNU/Linux box, these parameters may change. For example, www-data could replace www and the setkey command may be located at /usr/sbin/setkey. === 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 and write the tmp directory of the application. Let's do the same. Supposing you are in HAiku root directory, type the following commands as root: # chgrp -R www tmp # chmod -R 770 tmp === 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. === 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. You now need to create a config/environments/user_environment.rb file and specify the parameters for the mails sent to the users. 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 === 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 at [10] 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. == 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. === 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. This is generally a good idea to create a new user dedicated to this task on the server. 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 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: Redirection

Redirection

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/" AllowOverride all Order allow,deny Allow from all 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) === 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 == 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. If you have not defined a source address for user emails in the user_environment.rb file then you may notice that the source address of the emails sent by HAiku is the one of the user under which the web server is running. This is because HAiku is not yet aware of the contact address for the service. Let's configure it later from the HAiku interface. 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. File 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. == References [1] http://software.nautilus6.org/HAiku/ [2] http://software.nautilus6.org/homeguy/ [3] http://gnist.org/~lars/doc/Mobile-IPv6-HOWTO/Mobile-IPv6-HOWTO.html [4] http://www.kame.net/newsletter/20050707/ [5] http://www.nautilus6.org/doc/nepl-howto/ [6] http://member.wide.ad.jp/tr/wide-tr-nautilus6-configuring-ipsec-for-shisa-mipl-00.pdf [7] http://op-ha.nautilus6.org/documentation/FAQ/N6PackageRepository [8] http://mysql.org/doc/ [9] http://httpd.apache.org/docs/ [10] http://wiki.rubyonrails.com/rails/ [11] http://www.gtlib.cc.gatech.edu/pub/linux/docs/HOWTO/other-formats/html_single/SSL-Certificates-HOWTO.html [12] http://cert.startcom.org/