.. This document is formatted using the ReST syntax.

===============================================
Aegir -- FreeBSD installation instructions hints
===============================================

This is a helper file to the canonical INSTALL.txt. It is aimed at
helping you install Aegir on FreeBSD. It simply lists commands that
diverge from the base INSTALL.txt in a concise document that will be
easy to maintain in the long term.

It is recommended that the INSTALL.txt document is consulted before
going ahead with this install.

We reuse the same process describe in that document:

 1. Install requirements
 2. Configure system requirements, which include:
    * create a Aegir user
    * configure Apache, MySQL, DNS, etc
 3. Install the Aegir files
 4. Follow the install wizard


1. Install software requirements
================================

You should use portsnap to install and maintain dependancies

Shell commands::
 $ portsnap fetch
 $ portsnap extract
 
You can now update the portsnap tree using:
 $ portsnap fetch update
 
In order to update all outdated ports be sure to install portupgrade:
 $ cd /usr/ports/ports-mgmt/portupgrade; make install clean

You can use the default options when asked, now that portupgrade is
installed you can update all outdated ports by using:
 $ /usr/local/sbin/portupgrade -a
 
If portupgrade complains about stale dependancies clean with pkgdb:
 $ /usr/local/sbin/pkgdb -F

Install apache22:
 $ cd /usr/ports/www/apache22; make all install clean
 
When prompted what options to choose for Apache configuration choose:
 * THREADS
 * GDBM
 * BDB
 * MYSQL
 
Install MYSQL:
 $ cd /usr/ports/databases/mysql50-server; make install clean
 
Install PHP5:
 $ cd /usr/ports/lang/php5
 $ make config
**BE SURE TO ENABLE SUHOSIN FOR SECURITY REASONS**
 $ make install clean

Install PHP extensions:
 $ cd /usr/ports/lang/php5-extensions; make install clean

Install PHP JSON:
 $ cd /usr/ports/devel/php5-json; make install clean
 
Install PDO MYSQL for PHP:
 $ cd /usr/ports/databases/php5-pdo_mysql; make install clean
 
Install git:
 $ cd /usr/ports/devel/git; make install clean
 
Install unzip:
 $ cd /usr/ports/archivers/unzip; make install clean

Install CURL library:
 $ cd /usr/ports/ftp/fpc-curl; make install clean
**GO AHEAD AND ENABLE CARES AS WELL WHEN ASKED**

Install libidn (DNS):
 $ cd /usr/ports/dns/libidn; make install clean


2. Configure system requirements
================================

There have been issues with FreeBSD and Apache, when starting it may
throw the error:

[warn] (2)No such file or directory: Failed to enable the ‘httpready’ Accept Filter
 
This is because  by default Apache does not buffer incoming connections
so we have to load accf_http which serves this exact purpose into the
FreeBSD kernel, do so by doing the following:
 $ kldload accf_http
 
To make this setting permanent edit /boot/loader.conf and add the line:
accf_http_load="YES"

Check the default settings accf_http located in /boot/defaults/loader.conf
 $ grep accf /boot/defaults/loader.conf

Which should return:
accf_data_load=”NO” # Wait for data accept filter
accf_http_load=”NO” # Wait for full HTTP request accept filter

To start apache use the script /usr/local/etc/rc.d/apache22:
 $ /usr/local/etc/rc.d/apache22 start

By default Apache is not aware of PHP5, in order to make Apache
aware you must add the following lines to /usr/local/etc/apache22/httpd.conf
AddType application/x-httpd-php .php
AddType application/x-httpd-php-source .phps

Not all PHP extensions are created equal, some will cause segmentation faults,
others require additional libraries, though I will not detail each and every
library required for each extension most can be found in portsnap using
locate and grep, For example:
 $ locate missinglibrary | grep /usr/ports

Additionally, the order in which the extensions are loade will make the difference
between working and not, here is what my /usr/local/etc/php/extensions.ini looks like:

extension=bcmath.so
extension=bz2.so
extension=ctype.so
extension=curl.so
extension=dom.so
extension=filter.so
extension=gd.so
extension=hash.so
extension=iconv.so
extension=mbstring.so
extension=mcrypt.so
extension=ncurses.so
extension=pcntl.so
extension=pcre.so
extension=pdf.so
extension=pdo.so
extension=pdo_sqlite.so
extension=posix.so
extension=readline.so
extension=simplexml.so
extension=spl.so
extension=session.so
extension=sockets.so
extension=mysql.so
extension=mysqli.so
extension=tokenizer.so
extension=xml.so
extension=xmlreader.so
extension=xmlwriter.so
extension=zlib.so
extension=json.so

**NOTE: you may not need all but this works for me

Add user
================
 $ adduser

Home directory permissions (Leave empty for default):
Use password-based authentication? [yes]: 
Use an empty password? (yes/no) [no]: 
Use a random password? (yes/no) [no]: 
Enter password:
Enter password again:
Lock out the account after creation? [no]: no
Username   : aegir
Password   : ****
Full Name  : aegir
Uid        : 
Class      :
Groups     : aegir www-data
Home       : /www/aegir
Home Mode  :
Shell      : /bin/sh
Locked     : no


By default the mysql root user has no password, be sure to set with:
 $ mysqladmin -u root password "new_password"
 
Also, two anonymus users come without passwords, it is generally a
good idea to delete these accounts. To do so you must log into mysql
database:
 $ mysql -uroot -proot_password

At mysql prompt execute the following:
 mysql> delete from mysql.user where user = '';
 mysql> flush privileges;
 mysql> \q

Install sudo so aegir can restart apache
 $ cd /usr/ports/security/sudo; make install clean
 
You can add/remove sudo users by editing /usr/local/etc/sudoers and adding:
aegir   ALL=NOPASSWD: /usr/local/etc/rc.d/apache22
aegir   ALL=NOPASSWD: /usr/sbin/cron


3. Install the Aegir files
==========================

Edit install.sh.txt and change
#! /bin/sh
to
#! /bin/bash

Shell commands::
 $ cd /www/aegir
 $ su aegir -c "bash install.sh.txt"
 $ sudo /usr/local/etc/rc.d/apache22 restart

**CHECK IF CRON STARTED**
 $ ps axu | grep cron
 
**IF NOT START IT**
 $ /usr/sbin/cron -s


4. Follow the install wizard
============================

You should now be in the installation wizard. The wizard is usually
self-documenting so you should just be able to follow the instructions
in the wizard to configure Aegir to properly use the webserver and
database server.

5. Common issues
==================
*INCOMPLETE*
I'm still determining what is a bsd issue and what is isolated to my
environment - will update soon