This page is being moved to http://docs.aegirproject.org/en/latest/install/install/

Aegir requires some special permissions to your server in order to automate some configurations. For example, when a new site is installed, the web server will be automatically configured (vhost) and restarted. Therefore Aegir cannot be installed on a shared hosting environment. Consult the system requirements to ensure you meet the necessary requirements.

Automatic or manual install?

The automatic install process through Debian packages is the currently recommended install process on Debian and Ubuntu platforms. It should just be a matter of adding the right sources to your APT repositories and running apt-get install aegir.

The manual install process should take about 15 minutes for trained system administrators, between 30 to 60 minutes for others. The section contains detailed instructions on how to install Aegir manually on supported systems. It is aimed at system administrators and porters that want to control every step of the install process.

To decide which method is the right one, you may also want to review the operating system support page.

We also provide a troubleshooting guide to resolve common installation problems.

Note that, while installing Aegir does change some system configurations, it does only minor changes and keeps all its system configurations in one place so that it is easy to uninstall. It will not remove existing configurations. However, make sure you have backups before installing.

Automatic install and maintenance with Puppet

There is now a Aegir Puppet module that can further automate installation and maintenance of Aegir servers. It defaults to using the Debian packages, and is thus best-suited to Debian and it's derivatives (Ubuntu, Mepis, &.), but also supports (experimental) installation via the manual install process. This currently also only works on Debian, as it follows the documented installation procedure; however, it should be pretty straight-forward to adapt it to other OSes.

Development installs with Vagrant and Aegir-up

If you're installing Aegir for experimental or development purposes, you might be interested in Aegir-up, a Virtualbox/Vagrant-based local virtual machine automation system. It provides a simple method of building a complete Aegir system locally using the Puppet modules, and is, in fact, the primary development platform for them. In addition, you can build a dev version of Aegir from the git repos (with .git directories intact) to make debugging and writing patches and extensions easier.

Related documentation

• Upgrading Aegir
• Uninstalling Aegir
• Remote servers (multiserver)

Note that the following System Requirements are the same for Aegir automatic or manual install

A system capable of running Drupal

The Aegir system is entirely Drupal based, and has the same base requirements that Drupal does (with the exception that it won't run on Windows). See more notes on Unix and LAMP/LEMP requirements below.

Your own server

The low level of access required to be able to configure and run this system is very far beyond what is commonly available to users with shared hosting. A VPS from any popular provider such as Linode, Rackspace, Slicehost, Amazon EC, etc. will do fine. You will need root access to the server and the server needs to be dedicated to Aegir.

A Unix-based operating system

Aegir must run on some flavour of UNIX, because the majority of functionality in this system occurs in the back-end, through command line scripting. There are also several features (such as symlinks), that are not available to users on Windows. There are no plans currently to add Windows support. See the operating system support page for more information.

Web server

You will need at least one dedicated web server, running Apache. We generally work with Apache 2 but we should be compatible with the 1.x series. Aegir also supports the Nginx web server, but requires at least version 0.7.66 or newer. Since Nginx doesn't provide php-cgi or php-fpm (recommended) modules, you will need to install and run php-fpm server separately. You can find useful examples and tips in the third party Barracuda installer available at the barracuda project page.

N.B.: This third party installer is not supported by the core Aegir developers, but you can find helpful community support at the boa group.

PHP 5.2 and 5.3

Aegir depends on Drush 4.x, which requires PHP 5.2 or higher. Aegir 2.x depends on a minimun of Drush 5.10 (though Drush 6 is recommended), which requires PHP 5.3 or higher. You also need to have the command-line version of PHP to run Drush properly, and the MySQL extensions for PHP.

Given that PHP 5.2 has been deprecated since July 2010, we suggest using PHP 5.3 if possible. Note that while Drupal 6.x and above support PHP 5.3, some contributed third-party modules may still have problems with this version. Most often these cause warnings that can be safely ignored. Aegir and Drush themselves have no known outstanding PHP 5.3 compatibility issues, although you could have a lot of warnings in Drupal 6 due to ereg deprecation, see this issue for details. If you need to host Drupal 5.x sites, note that Drupal 5.x is not compatible with PHP 5.3 and above, and most likely never will be. See http://drupal.org/node/360605 (amongst other issues) for details. As such, Aegir has dropped support for Drupal 5 in versions 2.0+.

Database server

You will require a database server, obviously. Aegir currently only supports MySQL and MariaDB. It is preferable to use a dedicated (not shared-hosting) server since Aegir will create database users and will require the use of a MySQL root user.

Mail transfer agent

Aegir requires an MTA (Mail Transfer Agent) installed on your webserver in order to be able to install new sites to your new platform. If you don't have an MTA, the site installation will fail with message like "could not send email". Additional messages will show that site has been removed because of this problem. To remedy the situation simply install an MTA like sendmail, postfix, or exim and do the minimal configuration.

Other utilities: sudo, rsync, git and unzip

Aegir installs itself via a Drush Make makefile that downloads via git if you want the bleeding edge code, or via wget if you want the latest official release. If you want the latest development version, and don't have the git program you will need to install it on the server.

The jQueryUI library is used in the Aegir UI, unzip is required to extract it. Sudo is required to allow the aegir user the limited privilege to restart the webserver when required. Rsync is used to sync files to remote servers.

No conflicting Control Panels

Other popular control panels such as Plesk, cPanel etc, are designed to manage all aspects of Apache configuration and other areas that Aegir also is intended to be used for.

Running Aegir alongside such control panels is not supported and very likely may cause you problems or difficulties installing or running Aegir. Filing bug reports that are caused by interference by another control panel will likely be closed unless the problem can be fixed without causing problems for other Aegir users. Proceed at your own risk!

System requirements of popular Drupal distributions

Some Drupal distributions, such as OpenAtrium, are specialized products that may contain unique prerequisites for optimal performance. Such examples may include raising the php-cli program's memory_limit to something higher than 64M.

Please note that this is not a requirement of Aegir but of the distribution you are trying to install a site on. Thus the Aegir documentation may not officially 'require' such performance settings, but be aware that Aegir may report errors if the system was under-resourced to complete such a task.

These are the installation instructions that are recommended on Debian. Aegir dependencies (Apache, MySQL, PHP...) are also automatically installed. If you are managing the installation from a remote Windows computer, well-known open source tools for this task are for example PuTTY (a SSH client for command line), and WinSCP (a SFTP client with easy text file editing).

If you wish to install Debian packages over an existing manual install, it's possible. See the Debian upgrade procedures.

Debian packages are uploaded to http://debian.aegirproject.org/ shortly after a release. We eventually want to upload those packages to the official archives, but this will take some adaptation and time to sponsor the packages in.

1. Requirements for automatic install on Debian

Basic Linux system administration skills

Root access to your server

An up-to-date system and applications

Run the following command lines to update your system and applications.

  aptitude update
 

  aptitude safe-upgrade
 

A configured Fully Qualified Domain Name (FQDN)

Such as aegir.example.com

The hostname returned by the commands hostname -f and uname -a must resolve to the IP address of your server.

After setting up your FQDN you must restart your server with a reboot command so your changes take effect.

Note that newly created domain name usually take 24 to 48 hours to fully start working. This period, called propagation, is the projected length of time it takes for root name servers and cache records across the entire web to be updated with your website's DNS information.

Other System Requirements

Find http://community.aegirproject.org/content/installing/system-requirements

2. Adding the project repositories

Use this command to add the Aegir package "Software Source" repository to your system:

To install a customized Debian package, see the developer instructions for the debian package. Other distributions are available for courageous people that want to try development versions.

2.x note: to install the development version of Aegir, you can use the unstable or stable distribution above.

3. Adding the archive key to your keyring

This repository self-signs packages uploaded to it (and packages uploaded are verified against a whitelist of trusted uploaders) using OpenPGP (GnuPG, to be more precise).

Use these commands to download and add the repository's PGP key, then update the package list on your system:

4. Adding backports for or manually installing Drush

If you are running Debian wheezy or later, or Ubuntu Natty 11.04 or later, you don't need to do anything here. The Drush package you need is available from your distribution's repositories.

If not, you should also configure backports repositories for Drush. Version 4.4 of Drush is now in Debian unstable, wheezy, squeeze-backports and Ubuntu Natty.

1.x note: if you are running Debian Squeeze 6.0 or Debian Squeeze 7.0, add the following line to /etc/apt/sources.list :

You might also have to add a proper Pin-Priority before this works. Create a file called drush containing the following and drop it into /etc/apt/preferences.d:

Alternatively, you could download and install the squeeze-backports package for Drush 4.5 directly from: http://packages.debian.org/squeeze-backports/all/drush/download. Then you could install it with:

dpkg -i drush_4.5-2~bpo60+1_all.deb

2.x note: if you are running Debian Squeeze 6.0, to get drush-5.8.x and above, download php-console-table manually and install it

You do not need to edit /etc/apt/sources.list or create /etc/apt/preferences.d/drush

Then run:

If you are running Debian lenny 5.0 or Ubuntu Maverick 10.10 or Karmic Koala or earlier, we recommend downloading and installing the Drush package manually. The version of Drush in the Ubuntu Universe repository for these versions of Ubuntu is outdated. If you are using Ubuntu Lucid LTS 10.04, you can install the Drush package manually or instead use Brian Mercer's PPA (Personal Package Archive) using the following command:

Now run apt-get update again to refresh the apt database.

N.B. Since Aegir 2 requires Drush 5, which in turn requires PHP 5.3+, Drupal 5 sites are not supported in Aegir 2.

5. DNS configuration

Aegir requires a properly configured "FQDN" (Fully Qualified Domain Name) be assigned to the machine. In practice, this means that the hostname returned by the hostname -f and uname -n shell commands should resolve to the IP address for this server, and vice versa, with the resolveip command (included with the mysql-server package).

For Ubuntu, /etc/hosts should have entries that look like:

To set this up in a virtual machine (e.g. Virtualbox), here are the steps:

1. Create a new VM
2. Go to settings->network. Enable Adapter 2, and set to "host-only"
3. Install Ubuntu. Set hostname as FQDN during install
4. You may need to add the lines `auto eth1` and `iface eth1 inet dhcp` to /etc/network/interfaces

If you have a virtual machine already setup and want to change the FDQN:

1. change /etc/hostname using: `sudo hostname NEW_NAME`
2. change /etc/hosts using: `sudo nano /etc/hosts` and change name
3. reboot and test `hostname -f`, `uname -n`, `resolveip NEW_NAME`, `resolveip IP`
4. YMMV - Your Mileage May Vary

6. Manual sudo configuration

If you are running Debian squeeze or later, or Ubuntu Lucid 11.04 or later, you don't need to do anything here. The Aegir package configures sudoers automatically.

If not, you will need to manually modify your /etc/sudoers file to add the following line:

The line above assumes that you have created a user aegir as specified in the installation instructions.

7. Manual installation of MySQL (on Ubuntu 12.04 LTS)

Please note that Ubuntu 12.04 LTS installs, by default, an insecure MySQL installation that contains an anonymous user grant, allowing anyone to login without a password. This breaks Aegir functionality.

If you are running Ubuntu 12.04, you should install MySQL manually, and then ensure it is installed securely:

When running 'sudo mysql_secure_installation', answer 'Y' to 'Remove anonymous users?'

Now you can proceed with installing Aegir below.

8. Installing Aegir

To install Aegir version 2, frontend and backend, use the following command:

2.x note: Aegir version 2 is now stable. Read more at http://community.aegirproject.org/2.1

1.x note: to install Aegir version 1, use sudo apt-get install aegir instead.

If apt-get reports that the aegir packages have unmet dependencies, then make sure that you have installed Drush (as explained above). On a debian system, you can force the install of Drush from the squeeze-backports repository:

Then install aegir using the apt-get command above.

This will prompt you for the required information (MySQL password, Postfix configuration...) and go ahead with the install.

During the Postfix configuration, the following options appear: "No configuration, Internet site, Internet with smarthost, Satellite system, Local only". That first text screen only allows to use the tab key to select "OK", and then the enter key to display a second screen where you can select one of the choices. The default is "Internet site", useful in most cases to enable the server to send email messages, for example to the admin.

At the end of the installation, you will receive an email message or, if the user "aegir" has been assigned with a local email account during the installation, the file /var/mail/aegir will contain the message. It will include a one-time login to your new Aegir control panel, that is a URL to copy into your browser so that you can set the password for the "admin" user.

9. Custom Drupal distributions and make files

If you have your own Drupal make file, you can go ahead with the above process, but change the make file to the one you want:

echo debconf aegir/makefile string /var/aegir/makefiles/aegir/aegir-custom.make | debconf-set-selections
apt-get install aegir

This allows you to specify the makefile path for your custom distribution of Aegir. To maintain these customizations, you'll need to ensure you do the same when upgrading.

An example aegir-custom.make file could look like:

Note that for this to work, you may need the patch from this issue, allowing drush_make to reference absolute system paths. If drush make --version <= 2.2 you need this patch.

After installing Aegir, you can reinstall the front end (hostmaster), with following commands:

su -s /bin/sh aegir -c "some command" runs some command in the /bin/sh shell as user aegir. sudo runs the su command as root - prompting for your user's password instead su asking for aegir's password.

10. Troubleshooting the install

To make the install smoother, the install command is run without much debugging information, which can make diagnostics pretty hard. For this, there's a special environment variable you can set that will trigger debugging output. Install aegir with this*:

You can build your own Debian packages from our repositories using those instructions.

Note: Prior to 1.1-4. the command was env DEBUG=yes apt-get install aegir

Here are simplified instructions for installing Aegir on a server, quickly and easily.

The fastest way to install Aegir is on the latest Ubuntu Server LTS (Long Term Support). Currently 12.04.

Command Summary

Here is every command, ready to copy and paste.

It is highly recommended to read through the Installation Instructions step by step to give yourself the feel for how this is done. In addition, if you are not already familiar in Linux system administration, please read up on the subject. Standard linux security protocols should be followed.

Installation Instructions

Enter all commands in code boxes exactly as they are written.

ALL commands should be entered as root user until these instructions are complete. After that, you should never have to use the root user.

Self-installation of Ubuntu has you create an additional user in the admin group, which means they can sudo. If you are using a cloud hosting service, it likely just sent you root user credentials. Server security and user management is up to you. Don't give away access to root or the aegir user unless you know what you are doing. Follow standard web host best practices

For a summary of all needed commands, scroll to the bottom of the page.

1. Fire up a new server

   • Use Ubuntu 11.04 Server Edition for the smoothest and most reliable installation experience.
   • Make sure it has at least 1024MB, preferably 2048MB of memory. Depending on your host you will have to configure a hostname. It can be convenient to call this 'aegir'.
   • If you want the smoothest installation, create a brand new server. There will be the least chance of conflicts if you start with a brand new Ubuntu 11.04 server. If you use Ubuntu Desktop, you should be able follow these instructions without any problems.
   • Run all commands as root. If you are not root, enter
     sudo su

2. Add the project repositories and archive key

   Use this command to add the Aegir package "Software Source" repository to your system:

   echo "deb http://debian.aegirproject.org stable main" | tee -a /etc/apt/sources.list.d/aegir-stable.list
   Use this command to add the archive key to your keyring:
   wget -q http://debian.aegirproject.org/key.asc -O- | apt-key add -
   Then, finally, update your apt repositories:
   apt-get update

3. Install configure Aegir and dependencies

   Once you have added the repositories, you can now fire off the standard debian installation command. For Aegir 1.x, the command is:

   apt-get install aegir
   For Aegir 2.x, the command is:
   apt-get install aegir2
   This fires off the installation script for AEgir, along all dependencies including Apache, MySQ and PHP. You will be asked a number of questions about your server.
   • You will be asked to create a MySQL root user password. Make this long and random and type it down somewhere safe, you won't need it very often, but you will need it later on in the installation process.
   • In Postfix Configuration: Choose Internet Site, unless you have a reason otherwise. When asked for the System mail name, pick either the hostname (default) or the domain name you will be hosting this server on.
   • In Configure aegir-hostmaster, you will be asked to choose a "URL of the hostmaster frontend". This should be either the hostname (default) or the domain name the server will be hosting, with "aegir" as a subdomain. For example, "aegir.example.com". You may want to change this to whatever you prefer, just don't forget it as it will be where you use the Aegir front-end.
   • After entering your domain, Aegir Hostmaster installation will ask you for the MySQL root password you created earlier. You did write it down, didn't you?
     NOTE: The current DEB package requires you to enter the MySQL root password twice. When this script is done, if everything went ok, after a lot of other interesting information, you should see this:
     Aegir is now installed. You can visit it at http://test/user/reset/1/1329504351/eda205d9a27abde400a27cf160dff69a
***... frontend bootstrap correctly, operation was a success!
Setting up aegir (1.6-1) ...
Setting up libhtml-template-perl (2.9-2) ...
Setting up mysql-server (5.1.54-1ubuntu4) ...
Setting up php5 (5.3.5-1ubuntu7.7) ...
Processing triggers for libc-bin ...
ldconfig deferred processing now taking place
root@test:~#

   At this point, everything is installed. Visit the link the script provided you to check out the frontend. Switch to the aegir user to check out the backend:

   su - aegir

   Once you are the aegir user, check out the drush site aliases it gives you. @hostmaster is the alias for the new front-end you created. You will get new site aliases for every platform and site you create.

   drush site-aliases

4. Give yourself access to the server

   As the "Administrators Manual" can tell you, you should only manage the Aegir server from the backend as the aegir user.

   However, by default, the aegir user cannot sudo (except to restart apache). The aegir user also does not have a password. Therefor, the only way to become aegir is to sudo su - aegir from a user that can.

   So, to finish the server, you should give yourself a personal account that you can use to login to the server with a password in case all of your SSH keys get lost.

   To add yourself as a user:

   adduser yourname
   Then fill out the little wizard it gives you.

   //@TODO: Add some helpful notes about SSH keys and remote aliases.

   Install SSH on your server, generating your SSH keys and install them on your Ubuntu server. (Directions to generate your SSH keys are assuming your PC is Ubuntu as well, Windows users look below for SSH directions)

   • Tutorial: https://help.ubuntu.com/11.04/serverguide/C/openssh-server.html

   If using Windows, you must use Putty, PuttyGen, and PuttyPageant to generate and use your SSH keys.

   • Tutorial #1: http://the.earth.li/~sgtatham/putty/0.53b/htmldoc/Chapter8.html
   • Tutorial #2: http://www.howtoforge.com/ssh_key_based_logins_putty

   You will want to also be a part of the aegir and www-data groups so you can write to some of their files:

   addgroup yourname aegir
addgroup yourname www-data

5. Start Using!

   Now that aegir is installed, head to the User Manual page to get your first platform and site up and running.

Credits

This document was originally based on http://community.aegirproject.org/installing/debian but has been trimmed down to list only the steps you need to use on an Ubuntu server to get Aegir up and running as quickly and easily as possible.

This page describes to process you need to follow if Aegir doesn't have packages for your distribution. We currently provide Debian packages and others should be coming, if you help! This manual assumes you are fairly familiar with the UNIX commandline interface, but should be possible to follow through if you copy and paste faithfully all steps of the procedure.

A note on supported systems

These instructions provide example commands for a Debian-like distribution, but should be fairly easy to adapt to other environments. This document is meant as a canonical reference that should work on every supported platform. It can also be used for people porting Aegir to new platforms or installing on alien platform for which Aegir is not yet packaged.

It currently contains special recommendations for CentOS, RHEL 6, Arch Linux and Solaris. Users of those platforms are also strongly encouraged to review the common installation problems that occur on those platforms. Aegir is also known to be installable (and was developed partly on) Mac OS X, but that process is so obtuse that it has a separate page for the first part of the manual (up to Install Aegir components).

Installing Aegir may seem daunting at first (which is why we provide automated installs through packages), but once you get around it, it's fairly simple. It follows those steps:

Note that these instructions setup a complete Aegir system. If you want to only setup a new remote web/db server, it should be sufficient to install the system requirements (step 1), configure them (step 2) and follow the Remote server how-to.

1. Review System Requirements

Find http://community.aegirproject.org/content/installing/system-requirements

2. Install system requirements

To install the required components, run the following command as root:

apt-get install apache2 php5 php5-cli php5-gd php5-mysql php-pear postfix sudo rsync git-core unzip

Note: replace apache2 with nginx php5-fpm to install nginx on Ubuntu Precise or newer. Since Debian Squeeze doesn't provide php5-fpm, you will need to follow http://www.dotdeb.org/instructions/ before you will be able to install php5-fpm.

2.1. CentOS-specific configuration

yum install httpd php php-mysql php-cli php-gd php-process sudo rsync git postfix

For versions of CentOS previous to 6.0, you will need to upgrade to PHP 5.3 using those instructions.

Also for Centos minimal you should install cron (for queue and drupal cron) and unzip (for jquery.ui)

yum install cronie unzip

2.2. RHEL 6 specific configuration

RHEL 6 Server needs an additional PHP package to enable POSIX support. To find the package php-process you must enable the RHEL Server Optional channel. Once enabled, download and install the php-process-5.3.2-6.el6_0.1.i686.rpm.

You will also need to install the php-xml package if you are planning to use Aegir to manage Drupal 7 sites.

2.3. Solaris specific configuration

Solaris has this way of dealing with third party software that is... far from ideal. You will need to find the best way to install the following packages: apache2, git, sudo, mysql, PHP 5.2 and wget. unzip and sendmail should be part of the base Solaris install. The other applications should be available on the companion CDs or on sunfreeware.com.

In particular, git can be compiled easily by exporting the following environment::

export CFLAGS="-I/usr/sfw/include -I/opt/sfw/include"
export LD_LIBRARY_PATH="/usr/sfw/lib:/opt/sfw/lib:$LD_LIBRARY_PATH"

Then the compile instructions bundled with git should just be followed directly. I had trouble installing the binaries, as git expects ginstall to be available in the $PATH. I ended up adding the source directory in the $PATH, which works fine for most uses.

2.4. Arch Linux specific configuration

To install the required components, run the following command as root:

pacman -S apache php php-apache php-gd mysql postfix sudo rsync unzip git

Although all of the necessary apache modules and php extensions are installed at this stage, further configuration is required to enable and tweak certain features. Critically, virtual hosts are not enabled. It is worth examining the Arch Linux wiki page on LAMP server set up and verifying that more than one named virtual host functions properly.

If setting up for standalone development, see this useful wiki page to configuring postfix for local mail only.

To ensure Apache and mysql start when the machine boots, enable the httpd and mysqld daemons by adding them to the /etc/rc.conf file:

DAEMONS=(... mysqld httpd ...)

3. Configure system requirements

3.1. Create the Aegir user

The provision framework of Aegir requires that the scripts run as a non-root system account, to ensure that it can correctly set the file permissions on the hosted files.

Also to ensure that the file permissions of the hosted sites are always as safe as can be, and especially to make sure that the web server does not have the ability to modify the code of the site, the configured system account needs to be a member of the web server group, in order to be able to correctly set the file permissions.

While you can choose another username, most aegir documentation assumes the Aegir user is aegir, its home directory is /var/aegir and the webserver group is www-data.

Shell commands as root:

adduser --system --group --home /var/aegir aegir
adduser aegir www-data    #make aegir a user of group www-data

3.1.1. CentOS specific configuration

CentOS requires special commands to create the user, use those instead:

useradd --home-dir /var/aegir aegir
gpasswd -a aegir apache
chmod -R 755 /var/aegir

3.1.2. Solaris specific configuration

groupadd aegir
useradd -g aegir -G webservd -d /var/aegir -s /bin/bash -c "Aegir sandbox" aegir
chown aegir:aegir /var/aegir

3.1.3. Arch Linux specific configuration

useradd --system --groups http --home /var/aegir --create-home aegir
chmod -R 755 /var/aegir

3.2. Webserver configuration

Aegir supports two popular web servers, Apache and Nginx.

3.2.1. Apache configuration

Aegir assumes a few Apache modules are available on the server, and generates its own configuration files. The way we enable this is by symlinking a single file which contains all the configuration necessary. In Debian-based systems, you should symlink this file inside /etc/apache2/conf.d that will be parsed on startup or alternatively you can place include that file in your apache.conf/httpd.conf. We prefer the former. In other systems there are similar ways to accomplish this. Consult your OS's documentation if unsure.

If you are on a Debian-based system, you will also need to enable the mod_rewrite module manually.

Run the following shell commands as root. First, configure Apache to enable RewriteEngine:

a2enmod rewrite

Finally, create a symlink from an apache configuration file to a folder within the /var/aegir/:

ln -s /var/aegir/config/apache.conf /etc/apache2/conf.d/aegir.conf  

3.2.1.1. Ubuntu 14.04+ specific Apache configuration

Ubuntu 14.04 departs from Debian and previous Ubuntu Apache setup in that it doesn't use /etc/apache2/conf.d any more and better separates out sites-enabled from conf-enabled configurations. So:

ln -s /var/aegir/config/apache.conf /etc/apache2/conf-available/aegir.conf  
a2enconf aegir

Do not reload/restart Apache if prompted to after running these commands, it will fail.

3.2.1.2. CentOS specific Apache configuration

On CentOS, mod_rewrite is enabled by default and you can create the following symlink:

ln -s /var/aegir/config/apache.conf /etc/httpd/conf.d/aegir.conf

3.2.1.3. Arch Linux specific Apache configuration

On Arch Linux, mod_rewrite is also enabled by default. Add the aegir apache configuration include file to the httpd.conf file:

echo "Include /var/aegir/config/apache.conf" >> /etc/httpd/conf/httpd.conf

3.2.1.4. Other systems' Apache configuration

In other systems that do not have a conf.d directory, this could also work:

echo "Include /var/aegir/config/apache.conf" >> /etc/apache2/httpd.conf

N.B.:

• A standard umask of 022 is assumed. This is the default on most systems.
• For more information, see the common installation errors.
• For all OSes, the installer script creates the configuration file referenced by the newly created symlink/or file referenced in the Apache config file.

3.2.2. Nginx configuration

(If you just succeeded in installing Apache, please skip this section.)

Aegir assumes standard Nginx configuration is available on the server, and generates its own configuration files. The way we enable this is by symlinking a single file which contains all the configuration necessary. In Debian-based systems, you should symlink this file inside /etc/nginx/conf.d that will be parsed on startup.

Please make sure your nginx installation is up and running before continuing. On Ubuntu 12.04 Server, for instance, you must edit /etc/nginx/nginx.conf and uncomment the line "types_hash_max_size 2048;" in order for nginx to start successfully.

Shell command as root::

ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf

Do not reload/restart Nginx after running these commands, it will fail.

The installer script creates the configuration file referenced by the newly created symlink.

3.3. PHP configuration

Some complex installation profiles or distributions require a PHP memory limit that is higher than the default. To avoid common errors when installing sites on some distributions, the PHP command line tool should be configured to use 192Mb of RAM.

Change the memory_limit directive in /etc/php5/cli/php.ini to read:

memory_limit = 192M      ; Maximum amount of memory a script may consume (192MB)

Most modern Drupal sites require around 96M or even 128M of RAM for certain operations. This is far more than what is provided by the default PHP configuration.

Change the memory_limit directive in /etc/php5/apache2/php.ini to read:

memory_limit = 128M      ; Maximum amount of memory a script may consume (128MB)

If your distributions require more memory than these limits, then use some common sense and update it as appropriate to suit your individual needs.

For Aegir 3, make sure you've installed the required PHP extensions, particularly the image library (php-gd).

3.3.1. RHEL 6 specific configuration

The default php.ini configuration beyond the above changes also requires that the timezone be set for your location. Otherwise, you get fun errors and warnings during the host-master install step.

1. sudo vi /etc/php.ini
2. enter your password
3. /zone (this will bring you to the date specific timezone module area

4. Remove the semi colon in front of date.timezone and enter your specific timezone.

   [Date]
  ; Defines the default timezone used by the date functions
  ; http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone
  date.timezone = Your Time Zone Goes Here

5. Restart apache to compile these changes. sudo httpd -k graceful

3.3.2. Arch Linux specific configuration

Make the following changes to the php.ini file (/etc/php/php.ini):

Add :/var/aegir/ to the open_basedir directive:

open_basedir = /srv/http/:/home/:/tmp/:/usr/share/pear/:/var/aegir/

Add date.timezone value as per PHP's runtime configuration instructions - this is an example:

date.timezone = Europe/London

Modify the memory_limit directive:

memory_limit = 192M

Uncomment

extension=posix.so
extension=mysqli.so

3.4. Sudo configuration

Next, we need to give the aegir user permission to execute the Apache2 command to restart the web server without entering a password.

Create a file at /etc/sudoers.d/aegir and add the following:

Defaults:aegir  !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apache2ctl

After saving, change the permissions on the file:

chmod 0440 /etc/sudoers.d/aegir

Note - the path to your apache2ctl program may differ from this example. On some systems it may also be called 'apachectl' instead of apache2ctl. Adjust to suit your own requirements.

3.4.1. CentOS Linux specific sudo configuration

For CentOS apache2ctl is apachectl and you should use this instead, as root::

visudo

This command opens an editor to allow you to edit the /etc/sudoers file. Add the following to the end of the file (specific directions cannot be given since this depends on what editor you're using):

Defaults:aegir  !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apachectl

Note - the !requiretty bit is to make aegir able to run sudo even though it's not attached to a terminal. By default CentOS enforces requiretty so this exception is necessary.

3.4.2. Nginx specific configuration

For those using Nginx, set the sudoers line as follows

aegir ALL=NOPASSWD: /etc/init.d/nginx

3.5. DNS configuration

Aegir requires a properly configured "FQDN" (Fully Qualified Domain Name) be assigned to the machine. In practice, this means that the hostname returned by the hostname and uname -n shell commands should resolve to the IP address for this server, and vice versa.

If you only intend to use Aegir on a single server, it is acceptable for the resolved IP address to be the '127.0.0.1' loopback address.

If you intend to manage multiple servers using Aegir, you will need to make sure that the IP address is the public IP of this server.

You can add multiple entries to your /etc/hosts file for testing purposes, for example:

127.0.0.1 aegir.example.com example.com test1.example.com test2.example.com test3.example.com

Then you can use test1.example.com to create your first site.

3.6. Database configuration

Aegir supports MySQL right now. It is best to install the MySQL server using your Linux distribution's package manager.

Shell commands as root::

apt-get install mysql-server

To make sure that the Aegir backend, and all the possible web servers can reach your database server, you need to configure mysql to listen on all the public IP addresses available to it.

Again, as root, edit the MySQL configuration file /etc/mysql/my.cnf configuration line to comment out by placing a # at the beginning of the line as follow:

Before

bind-address        = 127.0.0.1

After

# bind-address      = 127.0.0.1

Without this line commented out, MySQL will listen only on localhost for database connection requests.

Now you need to restart mysql, to clear any caches.

Shell command as root:

/etc/init.d/mysql restart

The installer will prompt you for your MySQL root user password. The root user will be used to make administrative tasks such as creating new databases, and granting and revoking access to those databases for sites.

Even though MySQL is now listening on all IP's, it will not allow invalid users to connect to the databases, without the correct user accounts configured.

If you are concerned about MySQL being accessible in this way, you can also configure your firewall to only allow incoming connections from certain addresses. This is outside the scope of this document however.

Note that Aegir will ask you for your MySQL root password. If you do not want to use your regular root password for Aegir, you will need to create another root account for Aegir using a MySQL command like:

GRANT ALL PRIVILEGES ON *.* TO 'aegir_root'@'%' IDENTIFIED BY 'password' WITH GRANT OPTION;

Note: If you are running your Aegir databases on a remote DB server, you will want to create this aegir_root user. The install will often fail if you're trying to use the root user on a remote database. See this issue for details.

3.6.1. Ubuntu, RHEL, Arch linux specific configurations

NOTE: If you are running either Ubuntu 12.04 LTS, RHEL 6 or Arch Linux, you should still install MySQL in the same way as above. However, once done, you must now remove the anonymous, passwordless login that those platforms creates by default. To do this, run:

sudo mysql_secure_installation

Otherwise, Aegir will fail to install and work at all. See this FAQ entry.

3.6.2. RHEL 6 specific configuration

In Red Hat, you may need to move a default configuration file from /usr/share/mysql/ to /etc/my.cnf to view or modify any of the settings mentioned above.

4. Install Aegir components

Next step is to install the Aegir software components themselves, that is: drush, provision and hostmaster.

4.1. Install drush

Before installing Aegir proper, you first need to install Drush. This can be done through your operating system's package manager (Drush is shipped with Debian and Ubuntu currently) or by following the Drush README.txt file which has all the information for installing and using drush.

Note for 1.x users: you should use Drush version 4. Aegir 1.x does not support Drush 5. Also note there is a bug in Drush 4.0 and 4.1 so you should use a version of Drush between 4.1 and 5.

pear channel-discover pear.drush.org
pear install drush/drush-4.6.0

Note for 2.x users: you need to install a minimum of Drush version 5.10, though Drush 6.x is recommended. In this case, you may be able to install the regular release:

Note for 3.x users: you need to install a minimum of Drush version 6,some time you need apt-get install php-console-table before you become the Aegir user:

pear channel-discover pear.drush.org
pear install drush/drush

This should install Drush system-wide, but if you follow the manual install, you may end up with Drush in a non-standard location (traditionally /var/aegir/drush/drush.php), in which case you will need to add that directory to your path or use the following symlink:

ln -s /var/aegir/drush/drush /usr/local/bin/drush

4.1.1. Arch Linux specific configuration

It seems that Arch's PHP environment needs to be modified for Drush:

mkdir /var/aegir/.drush
cp /etc/php/php.ini /var/aegir/.drush/

Edit /var/aegir/.drush/php.ini to remove the values after open_basedir =, as this will any open_basedir values are likely to cause Drush to fail.

4.2. Stop! Now become the Aegir user!

The remaining of this manual assumes you are running as the Aegir user. Things will go very wrong if you do not change your shell credentials to become that user. You can do this by running the following command as root:

su -s /bin/bash - aegir

If this fails because /bin/bash doesn't exist, try using /bin/sh.

4.3. Install provision

Once Drush is installed you should be able to install the latest recommended Provision release using the following drush command:

Note for 1.x users:

drush dl --destination=/var/aegir/.drush provision-6.x

Note for 2.x users:

drush dl --destination=/var/aegir/.drush provision-6.x-2.0
drush cache-clear drush

Note for 3.x users: replace provison-6.x-2.0 to provison-7.x

4.4. Running hostmaster-install

Once you have downloaded drush and provision, you can just install provision in the commands directory of Drush (either ~aegir/.drush or /usr/share/drush/commands), if that's not already done. Once provision is properly installed, you can install all other aegir components using the hostmaster-install command:

drush hostmaster-install

You will be prompted for the required information if not provided on the commandline. See the inline help for the available options:

drush help hostmaster-install

For example, to install the frontend on Nginx, use:

drush hostmaster-install --http_service_type=nginx

Note for 2.x users: Drush 5 has a commandfile cache which you need to clear before installing Aegir:

drush cache-clear drush

It is imperative that you provide a valid FQDN to the installer. This is used for database GRANTs. Remote web servers depend on the FQDN being resolvable in order to connect back to your Aegir master server if it is used as your database server for managed sites.

Upon completion of the installation, the traditional Drupal 'Welcome' e-mail will be sent to the e-mail address specified by --client_email=(your e-mail) or if not provided as a command line switch, the address prompted by the installer process. This e-mail address will also be used as the default e-mail address of the first user and client in Aegir, but can be changed later.

There are other commandline switches available, documented in drush help hostmaster-install, as usual.

4.4.1. Arch Linux specific configuration

drush hostmaster-install --web_group=http

5. Install the Hosting Queue Daemon

For Aegir 2.x installs, using the Hosting Queued Daemon (hosting_queued) is highly recommended. For Aegir 1.x, check out http://drupal.org/project/hosting_queue_runner instead.

These instructions will install the daemon to run as a regular service in /etc/init.d/. Instructions will vary according to platforms, but the following should work in Debian, running as root.

1. Install the init script in place

   cp <hostmaster_platform_root>/profiles/hostmaster/modules/hosting/queued/init.d.example /etc/init.d/hosting-queued
   

2. Setup symlinks and runlevels

   update-rc.d hosting-queued defaults
   

3. Start the daemon

   /etc/init.d/hosting-queued
   

6. Checkpoint / Finished!

At this point, you have checked out all the code and setup your basic Drupal system (Drupal core, hosting, hostmaster and eldir) that will be the Aegir frontend and the backend system (provision and drush). Your filesystem layout should look something like this:

 /var/aegir/hostmaster-1.x/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/admin_menu/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/hosting/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/install_profile_api/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/jquery_ui/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/modules/modalframe/
 /var/aegir/hostmaster-1.x/profiles/hostmaster/themes/eldir/
 /var/aegir/hostmaster-1.x/sites/aegir.example.com/
 /var/aegir/config/server_master/apache.conf
 /var/aegir/config/server_master/apache/conf.d/
 /var/aegir/config/server_master/apache/vhost.d/
 /var/aegir/config/server_master/apache/platform.d/
 /var/aegir/backups/
 /var/aegir/drush/drush.php
 /var/aegir/.drush/drush_make/
 /var/aegir/.drush/provision/

Variations on this are acceptable (for example, the Drush Debian package works out of /usr/bin/drush and that's fine), but you are better to stick with the defaults if you really want to get through this.

The installation will provide you with a one-time login URL to stdout or via an e-mail. Use this link to login to your new Aegir site for the first time.

For troubleshooting this process and resulting install, see the common installation problems page.

You may also want to read on with what you can do with Aegir now that it is installed.

Apache

For Apache based installation hints see Apache / mySQL / PHP / Aegir

Nginx

Nginx is more performant than Apache, if you are interested in setting Aegir up using nginx Brian Gilbert from Realityloop has created a script to install everything that you need on a clean Mac (not already running anything on port 80), see OSX Aegir Installer on github.

This is a helper file to the canonical manual install process. It is aimed at helping you install Aegir on Mac OS X. Since PHP and MySQL support on OS X is fairly limited and complicated, a separate documentation page was created for that part of the documentation. You should follow this page all the way through and then proceed with the regular install, step 4: becoming the aegir user.

1. Special software requirements

While Mac OS X comes with Apache & PHP (and even MySQL on the Server version), the version of PHP shipped with 10.6 Snow Leopard is 5.3.x and thus may not work with Aegir (as of the 0.4alpha-era) and various other software. If you're running 10.5 Leopard, it may work out of the box, but I haven't tested it.

There are several different ways to get Apache, PHP 5.2, and MySQL 5 onto a Mac OS X machine. I give detailed instructions for MacPorts below, but if that's a bit more than you're ready to bite off right now, feel free to use an alternative approach.

One such alternative is MAMP. There is a good but outdated HOWTO for installing Aegir on Mac OS X 10.6 (Snow Leopard) using MAMP located here: http://groups.drupal.org/node/30270

MAMP stands for Mac, Apache, MySQL, and PHP and is the Mac equivalent of "LAMP". It is a self-contained package of all of these programs with a nice graphical installer and control panel. You can find it here: http://www.mamp.info/

MAMP is pretty straightforward, but it's also not very flexible (IMHO). While certainly not without its own headaches, MacPorts is a decently powerful way to sanely manage a healthy stack of open source UNIX software on your Mac. Since this is what I use, I'm going to assume MacPorts is in use for the rest of this HINTS file. I have also only tested this on Mac OS X 10.6 Snow Leopard.

If you don't yet have MacPorts installed, go here to get it: http://www.macports.org/install.php

Once it's installed, quit and re-launch your Terminal before continuing. Otherwise MacPorts won't yet be in your PATH.

The first two commands below are optional but recommended.

php5-apc is optional, but highly recommended as it will significantly increase PHP performance.

Watch the output of the last port command carefully, as there are usually some boring tasks for you to perform once the install is done. You'll be wishing you were running Ubuntu/Debian and apt-get by the time you're done.

2. Configure system requirements

Next we'll create the aegir user and add it to the _www group. This part is very different on Mac OS X than Linux or most other Unices. Must be a NeXTism. The command we will use he is "dscl", which is a short for Directory Service Command Line. In OSX 10.3 and earlier, that command is "nicl" (short for Net Info Command Line). It is also possible to create the user using the "Workgroup Manager" utility included with OS X Server. To obtain Workgroup Manager for the OS X Client, download the "Server Admin Tools" from Apple. For example, for Mac OS X 10.6, the admin tools can be found at:

http://support.apple.com/downloads/Server_Admin_Tools_10_6

Now you need to find the next spare UID to assign the user.

Here's how you find out on your system:

Then open the file users.out in a text editor, search for the highest 5xx user ID and add 1 to it (in your brain, not in the file). So if you find 506 but no 507, use 507. When you're done, delete users.out to be safe.

Now assign this UID to the aegir user, replacing "5xx" with the UID.

!! If you're running Mac OSX Lion, you also need to assign PrimaryGroupID to the aegir user.
   sudo dscl . -create /Users/aegir PrimaryGroupID XXX

Set a secure password for the aegir user, as it needs shell access.

Create the aegir home directory and set its permissions.

Add the aegir user to the _www group. This is the group Apache runs as.

Give the aegir user the ability to restart Apache.

Go to the last line of the file and add the following.

Save the file and exit your text editor.

Next configure Apache to include the Aegir config.

Configuring your MySQL database and user accounts is the same as in the INSTALL.txt file. But you probably want to add the path to its executables to your user's PATH and the aegir user's PATH.

The instructions that used to be here are now outdated, instead use the OSXAegirInstaller created by Brian Gilbert of Realityloop.

There are 2 methods of installing AEgir on CentOS both are the same but one is scripted and the other is manual and is documented below.

Scripted

The script can be found at https://github.com/marafa/aegir/tree/master/version2

NB. There is preliminary work to fix selinux at https://github.com/marafa/aegir/blob/master/aegir_selinux.sh. Feedback is quite welcome as well as git pulls.

Explanation

Connect to the server via ssh as root user.

ssh root@000.000.000.000

Install system requirements

yum install httpd php php-mysql php-cli php-gd php-process php-pear php-mbstring php-xml php-soap sudo rsync git postfix tree wget cronie unzip mysql-server mlocate nmap samba samba-client samba-common vim

Note: The following packages are not required but are very useful to include git wget mlocate nmap samba samba-client samba-common vim

SElinux

Make sure Security-Enhanced Linux is disabled as it creates install problems.

vim /etc/selinux/config Make sure SELINUX=disabled

If was SELINUX=enabled then we need to restart.

shutdown -r now

Note: I am not sure if it can be enabled at the end I have never tried.

Create the Aegir user

The provision framework of Aegir requires that the scripts run as a non-root system account, to ensure that it can correctly set the file permissions on the hosted files.

Also to ensure that the file permissions of the hosted sites are always as safe as can be, and especially to make sure that the web server does not have the ability to modify the code of the site, the configured system account needs to be a member of the web server group, in order to be able to correctly set the file permissions.

While you can choose another username, most aegir documentation assumes the Aegir user is aegir, its home directory is /var/aegir and the webserver group is www-data.

useradd --home-dir /var/aegir aegir

gpasswd -a aegir apache

chmod -R 755 /var/aegir

Apache configuration

Start Apache

service httpd start

Make apache start automatically after reboot.

chkconfig httpd on

We need to create a symbolic link between aegir and apache.

ln -s /var/aegir/config/apache.conf /etc/httpd/conf.d/aegir.conf

PHP configuration

vim /etc/php.ini

Increase the memory limit as complex installation profiles or distributions require a PHP memory limit that is higher than the default (128M)

memory_limit = 192M

Set Date Zone to your time zone see http://www.php.net/manual/en/datetime.configuration.php#ini.date.timezone

date.timezone = “”

Sudo configuration

Next, we need to give the aegir user permission to execute the Apache2 command to restart the web server without entering a password.

visudo

Add to end of file

Defaults:aegir !requiretty

aegir ALL=NOPASSWD: /usr/sbin/apachectl

DNS configuration

Aegir requires a properly configured "FQDN" (Fully Qualified Domain Name) be assigned to the machine. In practice, this means that the hostname returned by the hostname and uname -n shell commands should resolve to the IP address for this server, and vice versa.

If you only intend to use Aegir on a single server, it is acceptable for the resolved IP address to be the '127.0.0.1' loopback address.

If you intend to manage multiple servers using Aegir, you will need to make sure that the IP address is the public IP of this server.

You can add multiple entries to your /etc/hosts file for testing purposes, for example:#> >vim /etc/hosts Add your ip and hostname

000.000.000.000 hostname

Database configuration

Start mysql

service mysqld start

Make mysql start automatically after reboot.

chkconfig mysqld on

Configure Mysql

/usr/bin/mysql_secure_installation

Recommended:

Set root Password

Remove anonymous users? y

Disallow root login remotely? y

Remove test database and access to it? y

Reload privilege tables now? y

Install drush

pear channel-discover pear.drush.org

pear install drush/drush-4.5.0

Check if drush works If you get PHP Fatal error: Class 'Console_Table' not found then

pear install Console_Table

Stop! Now become the Aegir user!

The remaining of this manual assumes you are running as the Aegir user. Things will go very wrong if you do not change your shell credentials to become that user.

su -s /bin/bash - aegir

Install provision

drush dl --destination=/var/aegir/.drush provision-6.x

Clear the drush cache

drush cache-clear drush

Run hostmaster-install

drush hostmaster-install

These are some really rough notes on how to go about creating a 4 server aegir installation (aegir, mysql, web1, web2).

Adapted from reading through the BOA project and my own experimentation.

** Note -- regarding the wildcard SSL, your sites will need some configuration in your settings.php or local.settings.php to check for the X-Forwarded-Proto headers. I can't recall if the wildcard SSL config.

These notes also assume the last Ubuntu LTS -- 10.04/Lucid.

aegirmysql:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install vim mysql-server


_USER="aegir"
_DOMAIN="aegir.domain.com"
_AEGIR_HOST="aegir.server.hostname"
_AEGIR_HOST_IP="123.456.789.01"
_AEGIR_PASSWORD="password"

#AEGIR_DB_USER=aegir_root
#AEGIR_DB_PASS=`echo $RANDOM:\`date\`:$AEGIR_HOST | openssl md5`

echo "[client]
user=root
password=password" >> .my.cnf

mysql -uroot mysql<<EOFMYSQL
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_DOMAIN' IDENTIFIED BY 'password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_AEGIR_HOST' IDENTIFIED BY 'password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'$_AEGIR_HOST_IP' IDENTIFIED BY 'password' WITH GRANT OPTION;
GRANT ALL PRIVILEGES ON *.* TO '$_USER'@'localhost' IDENTIFIED BY 'password' WITH GRANT OPTION;
FLUSH PRIVILEGES;
EOFMYSQL


========================

# https://launchpad.net/~brianmercer/+archive/nginx
# https://launchpad.net/~nginx/+archive/php5

aegircontrol:

sudo apt-get update
sudo apt-get upgrade

sudo mkdir -p /var/www/nginx-default

#php5-suhosin
CATHOSTDEBDEPS="git-core git-doc mysql-client-5.1 vim nginx-custom drush postfix php5-cli php5-mysql php5-fpm php5-gd rsync unzip bzr patch curl"
sudo apt-get -V install $CATHOSTDEBDEPS

#postfix config already sorted

sudo adduser --system --group --home /var/aegir aegir
sudo adduser aegir www-data
sudo chsh -s /bin/bash aegir

#patch drush, re: ereg()

#as root:
echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers

ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf
#disable directives in nginx.conf:
#types_hash_max_size
#tcp_nopush
#error_log
invoke-rc.d nginx restart

#install SSL cert to:
/etc/ssl/private/domain.com.cert.pem
cd /etc/ssl/private/
ln -s domain.com.cert.pem nginx-wild-ssl.crt
ln -s domain.com.cert.pem nginx-wild-ssl.key

#install SSL config to:
/var/aegir/config/server_master/nginx/pre.d/nginx_wild_ssl.conf
#TODO: also install for /var/aegir/config/server_aegirweb{1,2}.host.name

#as aegir:
cd ~

mkdir .ssh
ssh-keygen -t rsa

ln -s /usr/share/drush /var/aegir/drush
mkdir ~/.drush
cd ~/.drush
wget -c http://ftp.drupal.org/files/projects/provision-6.x-1.3.tar.gz
tar -zxf provision-6.x-1.3.tar.gz

#htaccess password bit
mkdir ~/tmp
cd ~/tmp
git clone --branch develop git://github.com/computerminds/aegir_http_basic.git
#must be develop branch to use crypt() and for nginx support
cp -r aegir_http_basic/provision ~/.drush/provision/aegir_http_basic
cp -r aegir_http_basic/hosting ~/hostmaster-6.x-1.3/profiles/hostmaster/modules/hosting/http_basic_auth
#set directory permissions? -- patch aegir/http_basic module to do so?

_DOMAIN="aegir.domain.com"
_USER="aegir"
#_AEGIR_HOST=`uname -n`
_AEGIR_HOST="aegir.server.hostname"
_AEGIR_HOME="$HOME"
_AEGIR_DB_PASS="password"
_AEGIR_DB_HOST="mysql.server.fqdn"
_AEGIR_VERSION="1.3"
#_AEGIR_ROOT="$_AEGIR_HOME/hostmaster-$_AEGIR_VERSION"
_ADM_EMAIL="admin@domain.com""
_WEBG=www-data
_USRG=users

#going vanilla
echo "drush hostmaster-install $_DOMAIN --aegir_host=$_AEGIR_HOST --aegir_db_user=$_USER --aegir_db_pass=$_AEGIR_DB_PASS --http_service_type=nginx --db_service_type=mysql --db_port=3306 --aegir_db_host=$_AEGIR_DB_HOST --client_email=$_ADM_EMAIL --script_user=$_USER --web_group=$_WEBG --profile=hostmaster -d -v"

drush hostmaster-install $_DOMAIN --aegir_host=$_AEGIR_HOST --aegir_db_user=$_USER --aegir_db_pass=$_AEGIR_DB_PASS --http_service_type=nginx --db_service_type=mysql --db_port=3306 --aegir_db_host=$_AEGIR_DB_HOST --client_email=$_ADM_EMAIL --script_user=$_USER --web_group=$_WEBG --profile=hostmaster -d -v

cd hostmaster-6.x-1.3
echo "alive" >> healthcheck

#enable aegir modules
drush @hostmaster en hosting_web_cluster
drush @hostmaster en hosting_alias
drush @hostmaster en hosting_http_basic_auth
#*** enable hosting client in features -- disabling client module cause WSOD on site add page

# setup aegirweb{1,2}
# test ssh to aegirweb{1,2}
# add to known_hosts

# NOTE: Aegir web clusters need to share the files, and private directories between web servers (also cache directory, if using boost module)
# Setup provision hook for NFS links
# http://drupal.org/node/1283738

mkdir -p /var/lib/sitedata/aegir
chown -R aegir:www-data /var/lib/sitedata/aegir

mkdir -p /var/lib/sitedata/aegir/cache
chown -R aegir:www-data /var/lib/sitedata/aegir/cache


# add web servers
# add web cluster
#TODO: Add DR web servers to cluster
#TODO: Add WR, re: DR web servers & firewall

# set date/time settings in Aegir

#TODO: Logrotate webserver logs

#TODO: Add an alias for the aegir user:
#aegir: "admin@domain.com""

========================

aegirweb{1,2}:
#TODO: Check puppeted stuff, fix, etc

sudo apt-get update
sudo apt-get upgrade

sudo mkdir -p /var/www/nginx-default

CATWEBDEBDEPS="mysql-client-5.1 vim nginx-custom drush postfix php5-cli php5-mysql php5-fpm php5-gd rsync unzip patch"
sudo apt-get -V install $CATWEBDEBDEPS


sudo adduser --system --group --home /var/aegir aegir
sudo adduser aegir www-data
sudo chsh -s /bin/bash aegir

#install SSL cert to:
/etc/ssl/private/domain.com.cert.pem
cd /etc/ssl/private/
ln -s domain.com.cert.pem nginx-wild-ssl.crt
ln -s domain.com.cert.pem nginx-wild-ssl.key

#install SSL config to:
/var/aegir/config/server_master/nginx/pre.d/nginx_wild_ssl.conf
#TODO: also install for /var/aegir/config/server_aegirweb{1,2}.host.name

#as root:
echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers

#as aegir:
mkdir /var/aegir/.ssh
cat aegir.aegircontrol.id_rsa.pub >> /var/aegir/.ssh/authorized_keys2


#TODO: Logrotate webserver logs

==========================

Note: This installation process assumes that you're using a fresh install of Ubuntu 14.04 x64. If you use a lower version of Ubuntu, you may have trouble with this guide.

On most VPS providers, you'll be logged in as root initially. The installation process below assumes that you are logged in as root. Obviously, this is not a secure long-term solution, so once you're done with this guide, I suggest setting up public key authentication, turning off root login over SSH, and creating yourself a new unprivileged user. That's out of scope for this doc page, so you're probably on your own for that.

Finally, this document assumes that you're going to be installing aegir at aegir.example.com. Any time you see example.com, replace it with your domain.

1. Housekeeping

Make sure you're up to date:

apt-get update
apt-get upgrade

And that you have the the python-software-properties package (we'll need it later):

apt-get install python-software-properties

2. Install MariaDB

From mariadb.org:

MariaDB is a database server that offers drop-in replacement functionality for MySQL. 
MariaDB is built by some of the original authors of MySQL, with assistance from the
broader community of Free and open source software developers. In addition to the core
functionality of MySQL, MariaDB offers a rich set of feature enhancements including
alternate storage engines, server optimizations, and patches.

Install MariaDB:

apt-get install mariadb-server

You'll need to set your root password for the MariaDB server

3. Install Nginx

Next, install Nginx and PHP-FPM:

apt-get install nginx php5-cli php5-mysql php5-fpm php5-gd

Create the default docroot for Nginx as well:

mkdir -p /var/www/nginx-default

4. Install all the other stuff

apt-get install git-core git-doc vim drush postfix rsync unzip bzr patch curl

When prompted for Postfix configuration, select "Internet Site", then use "example.com" for the System mail name.

5. Create the Aegir user

Easy:

adduser --system --group --home /var/aegir aegir
adduser aegir www-data
chsh -s /bin/bash aegir

6. Misc Configuration

Make sure the Aegir user is allowed to restart Nginx:

echo "aegir ALL=NOPASSWD: /etc/init.d/nginx" >> /etc/sudoers

Symlink Aegir's nginx configuration into place:

ln -s /var/aegir/config/nginx.conf /etc/nginx/conf.d/aegir.conf

Disable duplicated directives in /etc/nginx/nginx.conf (the Aegir config specifies these values as well - if you do not disable them in the main nginx.conf, nginx will fail to restart). You can just remove (or comment them out with a "#") the lines that start with the following

types_hash_max_size
tcp_nopush
error_log

Then, restart Nginx:

service nginx restart

7. Install Aegir

IMPORTANT Switch to the Aegir user now: IMPORTANT

su - aegir
cd ~/

Download the latest Provision release:

mkdir ~/.drush
cd ~/.drush
wget -c http://ftp.drupal.org/files/projects/provision-6.x-2.1.tar.gz
tar -zxf provision-6.x-2.1.tar.gz
rm provision-6.x-2.1.tar.gz

Start the Aegir install process:

cd ~/
drush hostmaster-install aegir.example.com \
--aegir_host="aegir.example.com" \
--http_service_type="nginx" \
--aegir_db_user="root" \
--aegir_db_pass="[YOUR ROOT DATABASE PASSWORD]" \
--db_service_type="mysql" \
--db_port=3306 \
--aegir_db_host="localhost" \
--client_email="[YOUR EMAIL ADDRESS]" \
--script_user="aegir" \
--web_group="www-data" \
--profile=hostmaster

8. Optional Improvements

drupal.org/project/hosting_queue_runner

drupal.org/project/provision_boost

There are a few things that can go wrong in the install.

1. Verify and install run everything through SSH

Since Aegir has multi-server support, it is possible that you have a misconfigured "FQDN" and that aegir then tries to connect to the local server as a remote server. To check if you have a misconfigured server, run the following commands:

resolveip `uname -n`

If the command returns your IP address, you are all set. If it returns an error you will need to edit your /etc/hosts file.

First line of this file looks like:

127.0.0.1  localhost

Simply add all domains you want to this line. e.g:

127.0.0.1  localhost aegir.example.com example.com

2. NameVirtualHost *:80 has no VirtualHosts

It does not hurt anything, but it can be annoying in your logs. This may disappear as soon as you define your first virtual site using Aegir. If it does not, you most likely have a second NameVirtualHost statement in your configuration someplace other than in the Aegir configurations.

If you are on a Debian system, that is usually a configuration fragment in /etc/apache2/ports.conf or in a fragment symbolically linked in /etc/apache2/sites-enabled and it is safe to comment out any NameVirtualHost statements you find there as this really is a large part of the job you have asked Aegir to do for you.

Once those are commented out, the message should disappear.

3. Making sure it works

Your new Aegir server will be installed with a single site named the way you specified in your install script. That's great, but you may have more paths to that same server.

When you try to browse to your server for the first time from a non-localhost browser you may get an addressing issue. If you do, make sure that you actually have the server defined in DNS and that the DNS server was reloaded. If it was reloaded and you use slave servers, make sure that the serial number in the zone file was incremented so that the slaves automatically reload.

If you already have multiple URLs in your DNS which resolve to the same Aegir, you should check them. For instance: if your DNS resolves both aegir.example.com and sitecontrol.example.com to your new Aegir server's IP, you need to make sure that both are accommodated. If they will both get the same physical hostmaster site, one should be set up as an alias to the other. If they are indeed going to be separate sites you will have to create a new site node with the other name as a virtual site.

4. Access by the server's physical IP address

Another "gotcha" that you may run into is http access using the actual IP itself. Remember that the IP is not picked up by the site vhost and will not match a ServerName or ServerAlias - so it gets picked up by the default vhost. This is just standard apache stuff, nothing Aegir or Drupal specific here, but quite the annoyance and a potential problem.

You can easily work around it by simply adding the IP as a Site Alias in the site node in either the Aegir site (or another site that you may have defined which you would prefer the IP to address).

You can tell if you have the IP problem by simply pointing your browser to the server by IP as http://999.999.999.999/ and seeing what comes up. If you get an install screen, you have the problem. You certainly do not want that install screen getting executed!

The good news is that fixing it is easy.

Simply log into Aegir, click on Sites, click on the site name that you want the IP to address, click on Edit and scroll down to Domain Aliases. Put the IP into the box, click on the Redirect checkbox so that Aegir instructs Apache to do a rewrite to the real domain name, and finally click Save.

If you do not have the Domain Aliases entry box, you need to turn that feature on. In that case, go to your administration menu at the top of the page, point to Hosting and then click on Features. Click the checkbox for Site Aliasing and then Save Configuration. The Aliases box will now appear when you edit a site. There is excellent information about the site alias feature in this handbook at http://community.aegirproject.org/node/60 with much more detail.

After the Verify job completes you should test your server again. Now when you address the server by it's IP address the URL should automatically change to the site you selected and the install screen never appears.

5. CentOS firewall settings

You may need to adjust CentOS's firewall settings to allow HTTP traffic on port 80. If you installed CentOS with a UI, enable "Firewall settings -- WWW (HTTP)".

Alternatively, another solution may be to edit /etc/sysconfig/iptables and add a rule accepting traffic on the relevant interface on port 80.

Afterwards, you can restart the firewall with this command:

Shell commands::

6. CentOS cron requires restart?!

Also, in some configurations, it seems necessary to restart crond for the user crontab changes to take effect (very bizarre). For that, use:

Shell commands::

See http://drupal.org/node/632308 if you have more information about this issue.

7. CentOS aegir.conf permission denied

If you receive:

when trying to restart httpd, check your SELinux settings. If enabled, you can run the following command on the aegir.conf file in /var/aegir/config/server_master directory: Alternatively, you can disable SELinux completely if you desire. Both options will result in removing the permisson denied error.

You can see this comment: http://drupal.org/node/1286926#comment-5028062 for a little more info.

Try the following if nothing works:

setenforce permissive

See this doc to make the change permanent: http://wiki.centos.org/HowTos/SELinux

8. Solaris cron issues

I had numerous problems setting up a proper cron job, as Solaris' crond seems pretty anal about what it accepts. The only way I could get it to work was to create a wrapper shell script that would be called using the simplest cron tab.

Crontab entry:

Content of dispatch.sh:

9. Drush execution path issues

Solaris (and maybe others) suffers from the dreaded execution issues of drush:

• http://drupal.org/node/637574
• http://drupal.org/node/586466

Those can be worked around by hardcoding the --php executable on the commandline path. Adding the proper shebang (#!/usr/local/bin/php, for example) header and using a proper PATH that includes the PHP executable also helps.

10. APC issues

If you are having trouble running APC with Aegir, try downgrading to APC 3.1.4. This can be achieved by the following:

sudo pecl uninstall apc

sudo pecl install apc-3.1.4

As explained at http://community.aegirproject.org/installing/manual, the recommended version of PHP is 5.3, but some users may wish to use PHP 5.2 in order to host Drupal 5.x sites or to use modules which have PHP 5.3 compatibility issues. Should you choose to do so, the following documentation may be useful. What is explained here is specific to Ubuntu 10.04. It hasn't been tested on further versions, mostly because many sysadmins prefer to use the latest Long Term Support (LTS) version of Ubuntu, currently 10.04, on their production servers.

Follow this procedure :

sudo apt-get install python-software-properties

add-apt-repository ppa:txwikinger/php5.2

Create the file /etc/apt/preferences.d/php and input the following code in it :

Package: libapache2-mod-php5
Pin: version 5.2.10*
Pin-Priority: 991

Package: libapache2-mod-php5filter
Pin: version 5.2.10*
Pin-Priority: 991

Package: php-pear
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-cgi
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-cli
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-common
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-curl
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-dbg
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-dev
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-gd
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-gmp
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-ldap
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-mhash
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-mysql
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-odbc
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-pgsql
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-pspell
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-recode
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-snmp
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-sqlite
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-sybase
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-tidy
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-xmlrpc
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-xsl
Pin: version 5.2.10*
Pin-Priority: 991

Package: php5-mcrypt
Pin: version 5.2.6*
Pin-Priority: 991

Package: php5-imap
Pin: version 5.2.6*
Pin-Priority: 991

Then proceed Aegir install as explained at http://community.aegirproject.org/installing/debian

Alright, so you have installed Aegir, what else is there?

You have a lot of things you can do now:

• Get to know the interface
• Use drush make
• Work as the Aegir user
• Debugging Aegir
• Setup the hosting queue runner for lower waiting times

A lot more is available in the user manual.

It is possible to import existing sites into the Aegir hosting system, so that they can be managed by Aegir.

These instructions assume you've set up a new server with Aegir on it, and you want to import sites into Aegir from another server, or even from the same server, using backups.

There are basically three ways of importing sites in Aegir:

• from Aegir backups - simplest and fastest, scriptable
• from any single site, manually - most reliable, can import even non-aegir sites, hard to automate
• from a complete Drupal install - fairly reliable, can import non-aegir sites, could be automated but requires access to the database servers currently in use by the site

This section also regroups troubleshooting and other less orthodox techniques.

If you need to import a site from an existing Aegir system, this can be done from an Aegir site backup.

Requirements:

1. New Aegir version 0.4 alpha15 or later.
2. Access to Aegir backups from the old server.
3. A platform set up and verified that matches the platform on the old Aegir server.

1. Copy backups

First log into the new server via ssh - switch to the aegir user. Create a temporary directory somewhere, for example:

Run a command to syncronize the new directory with the backups directory of the old Aegir hosting system. This command does the entire directory, but you may want to modify this if you have a lot of unneeded backups on the old system.

This command also assumes that you can shell into the other server as the aegir user. Modify as required.

Now you can re-run the above command just before you are going to migrate a site. This is handy if you have a lot of sites to migrate and each site requires attention. Simply make a new backup of the site in the old system, and rerun the rsync command.

2. Create the site context and deploy the backup

For brevity, I assume that drush can be executed as drush. Replace with php /var/aegir/drush/drush.php if needed.

Pay attention to these two commands, they require modification to match the name of the site, the alias of the platform, and the name of the backup archive. These commands should each be on one line. You also need to know the platform alias. You can see all the platform aliases available by typing drush sa | grep platform.

First tell Aegir about the site, which creates a site alias.

Then run the provision-deploy:

Note: if you receive an error, you might also try adding the site to your new Aegir platform (using the same platform and site name, of course). Then run the provision-deploy again.

3. Verify the Platform

The final step is to import the site into Aegir. This is easily done by logging into the Aegir front-end and verifying the platform, which then will trigger an import task for the new site.

4. Caveats

The provision-save command will assume the database server is the same as the master server and that you are not using any install profile. So if your DB lives in another server or if you are using an install profile like openatrium you will probably need to edit the file created at /var/aegir/.drush/example.com.alias.drushrc.php

5. Setting a Non-Default Install Profile

If you are using a non-default install profile, you may want to specify your install profile by adding --profile=profilemachinename to the drush provision-save command above.

Using the example above but using an install profile for Open Atrium, the command would look like:

If you already have a platform setup on Aegir with EXACTLY the same codebase as your existing site, then you don't need to transfer the entire old codebase - you can just transfer the sites/example.com directory. However, you also need to make sure any dependencies on contrib modules that your site has, are covered on the codebase or Platform that you're importing it into.

In general it may be considered safer/less prone to confusing errors to transfer the entire old codebase into Aegir as a whole Platform, whereby the site will be imported automatically under that Platform. You can then migrate it in Aegir to one of your existing Platforms later. See importing from a complete Drupal platform for this method.

Also, it is much faster to just "deploy" an Aegir backup than go through the manual procedure here, so you should generally follow that procedure instead of the one defined here unless you have a very hairy setup.

To transer a site manually into Aegir, those are the steps you should follow:

1. Create the site database, user and directory

In order to import the site, you need to create a database and database user for the site, along with a directory in the platform.

The simplest way to do this is to create an empty site in the right platform and overwrite it. Through the commandline:

Through the UI, this can be done simply by creating a site in Create content.

If this is not working for some reason, you can create the mysql user and database manually using the following:

2. Transfer the files

You need to copy the sites/example.com directory from your old server to the new Aegir server.

To do this, first create a tarball of the site on the old server. Within the sites/example.com directory type:

Then, on the Aegir server, you can create a directory for it in the codebase (platform) you want to put it under:

Instead of using wget you could of course use SCP or FTP to transfer the tarball onto the Aegir server.

In the above we assume that you have created an empty site as directed above, if not, you will also need to extract the settings.php file, so that last command should instead be simply:

Then you will need to modify the settings.php file to follow the user and database created in the first step. Again, this is not necessary if you let Aegir create the site for you.

Once the file is unpacked, check the ownership and group of each file by using ls -al. It should be either 'aegir:aegir' or 'aegir:www-data'. Change it if necessary. In particular, files that may have been uploaded on your site via modules like imagecache, upload, Profile pics etc, may need to have their ownership changed:

3. Transfer the Database

Make a backup of the database on your old server (Backup and Migrate module is good for this, or you can use phpmyadmin or your favourite MySQL management tool. It's a good idea to truncate the cache, search and watchdog tables first to reduce the size of the database. The "Backup and Migrate" module does this for you.

If you are importing a site from a previous Aegir installation somewhere, such as from a backup tarball, the database.sql will already be within the tarball you unpacked. You can use this to import into a new database on your new server.

You can import the database with drush using the following command:

4. Verify In Aegir

In the Aegir web interface click on the name of the platform you have added your site to. You can access the list of platforms via the 'Platforms' tab in the primary links menu.

Execute a new Verify task on this platform via the 'Verify' button in the task list.

Aegir will now re-verify the platform. In the process of this, it will discover your new site and spawn a new 'Import' task for the site.

Once it's done this (it may take a couple of cron runs to dispatch these tasks in the queue) the tasks should turn green (if not, see 'Troubleshooting' below).

At this point, presuming you have updated DNS or are overriding DNS via an entry in your /etc/hosts file to access the site via the new Aegir server, you can visit the site in a browser and check around to see that it has worked. Pay particular attention to any links in node content that pointed to paths referencing /sites/community.aegirproject.org if your site was not part of a multisite setup. (Drupal has a habit of storing these paths in the database, or they may have been hard-coded into nodes by users).

Aegir will not go through all your database and update all URLs, so some images or links may be broken. This will need to be done manually. Aegir does attempt to update paths stored in tables such as 'files' though.

It's a good idea to clear the caches, and you may need to get imagecache to rebuild its thumbnails if you use it.

This way of importing sites is often considered the safest whereby you transfer across an entire codebase containing Drupal core, and define it as a Platform first. This makes sure you bring any dependencies, contrib modules etc, in exactly the same version and configuration that is referenced in the database for the site.

1. Transfer the codebase

Create a tarball of the codebase on the old server. Within the drupal root directory type: tar -zcvf example.com.tar.gz * .htaccess

Note that we have to specify including the .htaccess because it isn't picked up by the * wildcard due to being prefixed with a full stop. It is important to bring along the .htaccess for a platform so that Aegir can consider these settings when it generates Apache configuration for this platform.

Then, on the new server you can create a directory for it in the codebase you want to put it under:

Instead of using wget you could of course use SCP or FTP to transfer the tarball onto the Aegir server.

Once the file is unpacked, check the ownership and group of each file by using ls -al. It should be either 'aegir:aegir' or 'aegir:www-data'. Change it if necessary. We have to assume you have basic knowledge of Linux and POSIX permissions - we can't be responsible for teaching you sysadmin skills :)

In particular, files that may have been uploaded on your site via modules like imagecache, upload, Profile pics etc, may need to have their ownership changed: sudo chown -R aegir $platform/sites/*/files

If your site previously resided in sites/defau1t you need to move it because Aegir ignores the default directory (it has no way of understanding what URL this would be accessed by, so it is impossible to 'manage' it). Each site needs its own directory with the correct domain in typical Drupal multisite design:

If you do this, you may need to also update your filepath's stored in the files table by running the following query on your database:

There are many other places in the database that can suffer the same problem, the node_revisions table for example. If you have phpMyAdmin available you can easily search the entire database for 'sites/defau1t'. Select the database, then click the Search tab. Once you know which tables are affected you can run a variation of the above query to correct these records.

2. Transfer the Database

Note: This step is not necessary if you are moving your site from one directory on your server (e.g., /var/www/html) to a newly created Aegir directory on the same server (e.g., /var/aegir).

Make a backup of the database on your old server (Backup and Migrate module is good for this, or you can use phpmyadmin or your favourite MySQL management tool. It's a good idea to truncate the cache, search and watchdog tables first to reduce the size of the database (Backup and Migrate does this for you).

Aegir does not provide support for importing databases with prefixed tables so it is best to remove prefixes form the database. However, there is work to bring this support in (http://drupal.org/node/483346) and a solution if you want to keep prefixes on your tables (http://drupal.org/node/483346#comment-3113516)

Unlike traditional Drupal projects the database settings cannot be found in settings.php. The database credentials are stored in the Apache vhost config of the associated site. This is a security measure implemented by the Aegir project.

In the vhost directory on your old server, /var/aegir/config/server_master/apache/vhost.d/, is a vhost file for every site on your server. The contents of the file can be displayed in your terminal with the command cat thenameofthefile. At the top of the file you will find the credentials needed to create a database on the new server.

On your new server, manually create a new database and upload the .sql file from your backup.

Then create the mysql user that your site accesses the database as, and grant it all permissions on that database except 'GRANT'.

Connect to the database on the old server: mysql -u root -p

Create the new database: create database yourdatabasename

Add the user: CREATE USER 'yourdatabaseuser'@'localhost' identified by 'youruserpassword';

Give the necessary privileges: GRANT ALL PRIVILEGES ON yourdatabasename.* TO 'yourdatabaseuser'@'localhost';

Import the database: mysql -u yourdatabaseuser -p -h localhost yourdatabasename < thenameofthedatabase.sql

3. Setup Platform in Aegir

In the Aegir web interface click on 'Create Content' and 'Platform'. This step is often easiest when using the admin-menu on the top of your screen.

Enter the name you want to use for the platform (eg 'My Platform import'), and the path to the platform on the server (eg '/var/aegir/platforms/your-new-platform')

Click Save to submit the form, and Aegir will spawn a Verify task for this platform into the queue.

Once the task is complete this the task should turn green (click through to the homepage to refesh and check. If not, see 'Troubleshooting' below).

4. Import and Verify Sites In Aegir

Upon completion of the above Platform verification task, Aegir will discover your new site and spawn a new 'Import' task for the site.

Once it's done this (it may take a couple of cron runs to dispatch these tasks in the queue) the tasks should turn green (if not, see 'Troubleshooting' below).

At this point, presuming you have updated DNS or are overriding DNS via an entry in your /etc/hosts file to access the site via the new Aegir server, you can visit site in a browser and check around to see that it has worked. Pay particular attention to any links in node content that pointed to paths referencing /sites/community.aegirproject.org if your site was not part of a multisite setup. (Drupal has a habit of storing these paths in the database, or they may have been hard-coded into nodes by users).

It's a good idea to clear the caches, and you may need to get imagecache to rebuild its thumbnails if you use it.

5. Migrate To Another Platform

Now that you have your sites under Aegir's control you can take advantage of its power, and easily migrate them to another platform. In the event that your sites were on old versions of Drupal core and a new one is available and present as another Platform on your Aegir server, you can use the Migrate process to upgrade those sites onto the new core.

For details on how to Migrate sites, consult the Migrate documentation.

6. Troubleshooting

For those who are migrating existing sites that live with their files in the sites/community.aegirproject.org folder, things can get tricky. However, you can follow this tutorial and successfully get things moved over rather easily.

We have already seen how to import sites in an Aegir install, but what if we want to test the "hostmaster" site itself, ie. setup a development or staging environment of an Aegir install itself?

This page explains how. The basic steps are:

1. Installing aegir

The first step should be fairly simple and intuitive if you got that far: you have to install aegir itself on the staging server. You should install the specific version that is currently in production.

Maybe that also involves uninstalling the existing install.

2. Backup the production site

Run a backup on the production site, on the production server. This can be done in the frontend or in the backend using:

3. Deploy the production site in staging

Copy the resulting backup to the staging server. Then you should be able to deploy it with the following command:

In this case, we use deploy to also rename the site (--old_uri=aegir.koumbit.net).

4. Tweaking the install for the staging server

The environment on the staging server could be very different from the production server. The server name will be different, maybe there will not be a dedicated mysql server, platforms will not exist, etc.

It is recommended to review the "Servers" page to change the domain names to the staging environment. In Koumbit's case, this means:

1. editing the master server to change the hostname and IPs
2. renaming the DB server to "localhost" and changing the database credentials
3. renaming the main hostmaster site:
   drush @hostmaster sqlq "UPDATE node n JOIN hosting_context h ON h.nid = n.nid SET n.title='hostmaster.koumbit.net' WHERE name='hostmaster';"
drush @hostmaster sqlq "UPDATE node_revisions nr JOIN hosting_context h ON h.nid = nr.nid JOIN node n ON n.vid = nr.vid SET nr.title='hostmaster.koumbit.net' WHERE h.name='hostmaster';"
4. change the sites to point to the good web and db servers:
   UPDATE hosting_site SET db_server=3631 WHERE db_server <> 3631;
UPDATE hosting_platform SET web_server = 3 WHERE web_server <> 3;

Note that this will have the added benefit of reverifying all platforms and therefore create them if they are makefile-based.

5. Troubleshooting

I had weird issues with failing to run updatedb on the hostmaster site (while deploying to another alias would work). My workaround was to suspend the process right before it would run drush updatedb, then run updatedb manually, twice:

First things to check:

Does the aegir user have proper permissions?

sudo chown aegir -R PLATFORM/sites/yoursite

Is the database properly set up? Try drush sql-cli to see if the site db user has access and if there are tables (try SHOW TABLES).

If something goes wrong with importing a site you might end up with a node for a non-working site. In such a case it can be good to delete the node for this non-working site and verify the underlying platform again. Since there is no direct way to delete such a node from the user interface you have change the URL from node/NUMBER/edit into node/NUMBER/delete to do this.

Aegir supports multiple 'server' entities. These servers have 'services' such as 'Web' or 'Database', and 'service types' which are implementations of that service, such as 'Apache' or 'MySQL'.

Some previous experience in the configuration of Apache and MySQL will help if you want to use remote servers with Aegir. If you haven't had any experience in setting up and maintaining Apache or MySQL before you might want get familiar with the basic concepts first.

1. Remote web servers

1.1. System dependencies

On the remote server, install these packages

1.2. Aegir user

Any number of remote web servers may be configured. The remote server needs an aegir user created on the system.

1.3. Web server configuration

You'll also need to prepare the web server in the same way you did for the master Aegir server during installation:

Don't restart Apache even when it prompts you. This will be done by the Verify task you'll spawn for the server from the Aegir frontend later.

1.4. Sudoers

Add the aegir user to sudoers so it can restart Apache (e.g. sudo visudo -f /etc/sudoers.d/aegir):

1.5. Login shell

The remote aegir user will also need a login shell, which can be modified using the chsh command.

1.6. MySQL access

Aegir connects directly to the remote server's MySQL to create databases and users. Therefore, you need to log into MySQL in the remote server as root and create a user with the following command:

Where

• 'root' is the username on the Aegir server that will be connecting. Leave 'root';
• 'aegir_server_ip' is the IP address of your Aegir server. For example '123.123.123.123';
• 'password' is the password that will be used by your Aegir 'root' user to connect to the remote server's MySQL to create databases and users. It is suggested to store that password in a secure location. To increase security, it is recommended to choose a password with 6 to 16 alphanumeric and or punctuation characters.

If MySQL returns something like "Query OK", that means the command was successful. For example:

Query OK, 0 rows affected (0.00 sec)

Note the comment about "bind-address = 127.0.0.1" on http://community.aegirproject.org/installing/manual#Database_configuration

When the server is being verified, Aegir will attempt to create a database and grant privileges to a user for that database. If any of these two fails, verify that your MySQL configuration is correct and that there is no firewall blocking your MySQL port.

You can confirm that MySQL is configured correctly on the remote server by manually connecting from the command line on your Aegir machine:

If your MySql database is running on the same server as the Aegir master and is configured with the name "localhost", you may run an issue where the remote web server tries to access MySql via a local socket rather than the hostname. To resolve this, just change the server hostname for the MySql server in Aegir from "localhost" to the hostname of the server.

1.7. SSH keys

SSH public/private keys should be set up so the main Aegir server's aegir user can access remote web aegir users with no passwords required.

Example: on main Aegir server:

Do not use a passphrase when you create your key. Simply press Enter to leave the passphrase blank. Otherwise, SSH will insist that you enter the passphrase everytime you try to SSH using the key. We don't want SSH to present any prompts.

Put the public key's contents into /var/aegir/.ssh/authorized_keys on the remote web server. The easiest way to do this is to use the ssh-copy-id command.

You should manually login for the first time from your Aegir master server to your remote server as the aegir user, so that the remote web server is added to the known_hosts file in /var/aegir/.ssh on your Aegir master server. Verifying the remote webserver will fail until this has been done.

You can confirm that SSH is set up correctly by manually connecting from your aegirmaster server to your remote server as aegir@ user to aegir@ user:

This should directly log you into the remote shell command line without any additional keys pressed.

There are many, many tutorials online for setting up ssh keys, and various mistakes can be made by inexperienced users such as permissions etc. Aegir isn't a 'Linux beginner's practice tool', so setting these up is really out of the scope of this document and users are encouraged to research this on their own. (For Ubuntu, see this article).

If you have followed the instructions above, and your SSH connection gets closed immediately after you try to connect to the remote server as the aegir user, you may not have given the aegir user a shell correctly. Check the /etc/passwd file on the remote server to make sure that the aegir user has a shell.

1.8. Verify the server

Now you can add a new server node in Aegir, set the hostname and/or IP and set the service type to be 'Apache' (or Apache_SSL if this site is to handle SSL sites).

A verify task will be spawned and added to the Task queue ready for dispatching. During a server verification task, various configurations will be set on the Aegir master server and also synced to the remote web server, restarting Apache.

Now when you add a new Platform node in Aegir, you have the option of setting which web server to host it on. If you are not using a makefile but are downloading a platform manually, you must still do this on the main Aegir server. The contents will then be synced across to the web server.

You don't choose a web server when installing a new site. Because a site depends on a platform, its web server is implied by which platform has been chosen. In other words, all sites on a platform are hosted on the same server. You cannot host two sites on the same platform on different servers.

Any number of remote web servers may be configured. They need an aegir user and webserver configuration, with the same user name and directory paths. SSH public/private keys should be set up so hostmaster's Aegir user can access remote web Aegir users with no passwords. The above Apache configuration needs to be performed too.

Additionally, the remote web server needs the 'mysql' client binary installed so that Aegir can test that it can successfully connect to the database server. On (at least) Debian-based systems, this can be installed via the 'mysql-client' package.

They will also need a login shell, which can be modified using the chsh command.

Shell commands as root::

apt-get install mysql-client
adduser --system --group --home /var/aegir aegir
adduser aegir www-data    #make aegir a user of group www-data
chsh -s /bin/sh aegir
apt-get install rsync apache2 php5 php5-cli php5-mysql
mkdir /var/aegir/.ssh
cat > /var/aegir/.ssh/authorized_keys <<EOF
ssh-rsa AAAAB3NzaC1yc2EAAAADAQAB...UF aegir@filer01
EOF
chown aegir:aegir /var/aegir/.ssh -R
chmod 750 /var/aegir/.ssh
chmod 640 /var/aegir/.ssh/authorized_keys
a2enmod rewrite
ln -s /var/aegir/config/apache.conf /etc/apache2/conf.d/aegir.conf
cat > /etc/sudoers.d/aegir <<EOF
Defaults:aegir  !requiretty
aegir ALL=NOPASSWD: /usr/sbin/apache2ctl
EOF
chmod 440 /etc/sudoers.d/aegir

For clusters, use the aegir-cluster-slave package to operate the above and NFS mounts for you. See also web cluster configuration documentation.

Especially if you have been using Aegir for a while simply because it handles updates, moving to new releases, cloning, aliases and everything Drupal with such elegance on a single server - you might not be entirely clear on what changes when you make the move to multiple servers. Hopefully this will help.

Understanding the process

Multiple servers are great even if you do not have to manage a server farm. Having a server for development that you are free to break, one for testing that you hope will not break, one for approvals so your clients can go to see how their "real" website will look, and one for production that serves the daily grind of live sites is a wonderful thing. This DTAP (Development, Testing, Acceptance, and Production) structure works and it is surprisingly easy to accomplish under Aegir.

If you are managing a farm, creating massive numbers of servers is quick and easy with Aegir - especially if you use virtual machines like Xen where a server image can be cloned or generated using LVM disks that can be migrated (even while running) to other physical machines.

When it is time break out an Aegir master controller and remote slaves you have to remember that Aegir is the place that it (almost) all happens. Everything is stored in Aegir - including your remote platforms and your sites - and then distributed to the slave servers by Aegir in the Verify process.

Remember too that sites reside on platforms, and platforms reside on servers. You are turning your Aegir install into an Aegir Master as the hub, and the Aeger Remote Slaves as the spokes. To move into this "hub and spoke" architecture, you must build the remote server, tell the Aegir Master about that server and verify it, install a Drupal platform for that server on the Aegir Master and finally tell the Aegir Master about that Drupal install and verify that. You then create the sites on the platform you want based upon the install profile you select for that site. Need more? How about an example:

The mechanics

(1) Build a server image on your network to become your Aegir Slave. This can be anything from a separate headless server to a Virtual Machine image on physical machine with a dozen other Virtual Machines on it. As long as it has its own IP and is capable of running a Drupal image, it will work.

(2) Ensure that your new server image is resolved in your DNS by adding it to your zone files and incrementing the serial number in the zone file. Aegir can manage that for you now to some extent, but you might want to wait until that feature leaves the experimental status. Make sure the entries in /etc/hostname and /etc/hosts all match your zone files (including reverse DNS). Reload/restart the DNS server. Any DNS slaves should automatically get notified and the incremented serial number should make sure they reload automatically. Test the resolution and ping the new Aegir Slave server image from the Aegir Master to Ensure that the IPs all resolved properly.

(2) Follow the steps in the Aegir Handbook page at http://community.aegirproject.org/node/30 carefully. You should be able to use cut and paste if you are using Debian Stable or the like. In any case, you will need those packages. You do not need Aegir on the slave, but you do need the aegir user and that user must have a shell. I prefer the bash shell, but the sh shell in the instructions will do.

(3) You need to have the "passphraseless" ssh working and proven before you continue. A web search on the terms "passphraseless ssh" plus your operating system will generally get you great instructions, but putting those instructions here for every possible combination is beyond the scope of this example. In terms of helpful hints, however, you do not need to have a password for the aegir user on the Aegir Slave. Your access will be this certificate. By simply hitting enter when it asks for the passphrase, you make the certificate passphraseless. You should carefully set the permissions and back these certificates up to a secure location. You MUST log in manually from the Aegir Master to the Aegir Slave the first time or your verify will fail. This is because the system has to add the ssh keys to the known hosts and it will ask about about it before it will allow the connection. Aegir nows nothing about this and will not answer, so the verify will fail. To be absolutely sure it works, after exiting the initial login, you should retry the login to verify it does not ask for a password and then exit the login and try an rsync (which is the process by which the Aegir Master controls the Aegir Slaves). All of these commands should work from the Aegir Master to the new Aegir Slave while logged into the Aegir Master as the aegir user with no request for a password, proving that the systems are exchanging keys (do not proceed until you can do this flawlessly without having to enter a response):

(4) Go to Add Content/Server and put in the server name, leave the Database set as None (Your sites will use the Aegir Master database and none is required on the Remote Slave) and under Web select apache or apache ssl (to match the example) then click Save. After the process completes you should see that it found the IP address properly on its own, plugged it in all by itself and then Verify quite nicely. If you look on the Aegir Slave remote server you will see that you now have directories named config and platform.

(5) Now that hard decision for platform choice comes in play. My preference is a Drupal install that is the same release as the Aegir Master server or higher. Since sites are eventually destined to be Drupal 7 one day, and the Aegir system is not Drupal 7 ready as of this writing but heading that direction, making at least one Drupal 7 slave is a good idea so that you can migrate sites to that platform as they are ready. If you are migrating sites off of your existing Aegir and onto slaves, migrating to platforms of the same Drupal version makes that process much easier. In any case, firm up your decision about which Drupal version you want to install on your new Aegir Slave Platform.

(6) Time to create that platform. The big thing here is to do it right the first time and make certain that the name of the platform is unique to any platform on your Aegir Master server. If you look in your /var/aegir directory you will notice that Aegir has its own naming convention. For instance, you should see /var/aegir/hostmaster-0.4-rc1 as the platform for the Aegir 0.4 release candidate 1. You need to consider doing the same. For instance, name your platform something like: /var/aegir/slavename-drupal-version and you will make it easier to distinguish which server the platform resides upon and the drupal version so that you can manage updates and migrations more easily. Make certain that you are not destroying one platform when creating another. Be aware that at some point Aegir started organizing platforms into a separate directory: /var/aegir/platforms and you should change to that structure if you have an older original install. Again, be careful you are not overwriting an existing install when you create the new one. For instance, if you already have a Drupal install in /var/aegir/platforms/drupal-7.14 the code below will attempt to recreate it on top of the existing install. If you are using a Makefile, be sure that the same problem does not occur in that makefile. To create a Drupal 7 Aegir Remote Slave Platform, log into the Aegir Master as the aegir user and run this simple code (of course edit it to match the platform and name you want to create:

(7) The final step in creating this platform is to actually tell the Aegir Master about it so that it can distribute it (via rsync) to the new Aegir Remote Slave. Simple enough. Just go to Create Content/Platform and the Create Platform screen comes up. Under Name write something descriptive and unique. In the example so far, this will be something like 'slavename Drupal 7.14' or in some way adhere to your chosen naming convention. I use the directory name I created above since that serves two purposes. Under Publish Path you will put the path that holds this Drupal distribution. In the example above that will be /var/aegir/platforms/slavename-drupal-7.14 but the path will be reflected from the Aegir Master to the Aegir Slave and will be the same on both. If you are using a Makefile you need to enter the full path and name of that Makefile here as well, but the creation and use of the Makefile is beyond the scope of this example. Lastly choose the server that this platform will reside upon. When you are finished, double check the screen and then click on Save. The Verify step should execute flawlessly and when it does, your Aegir Remote Slave will be complete and ready to accept sites.

(8) Lather, rinse and repeat for each Aegir Remote Slave.

Creating sites on the remote

The only difference you will notice when creating a new site under Aegir will be the choice of platform. The Create Site screen is quite self explanatory, but the main thing is to select the Install Profile that you require and then the list of Platforms that support that install profile will be populated.

As usual, Aegir makes it all faster and easier than you expect.

Cluster module

The cluster module is a simplified solution for maintaining platforms across multiple web servers. A cluster server node does not require a physical machine to be present on the network. Simply create web servers as usual and create a server node that has "Cluster" selected under the web field set of the server node add form. Select the servers that should be part of the new web cluster by clicking the check box next to each web server in the "Servers" section.

The cluster module will rsync the platforms between each web server and keep them up to date.

Pack module

A Pack consists of a single server node that is specified as "pack" and any number of server nodes specified as "apache" or "nginx". The main difference between the Pack functionality and Web Cluster functionality is that Aegir rsync's configuration (Apache & Nginx) to "all" nodes in the Pack and rysnc's the platform and site code to only the "master" node in the Pack. All other "slave" nodes will see the platform and site code via NFS.

Configuring the Pack server node:

The "pack" server node will not be used by Aegir to physically deploy sites or platforms on, so consider it more of a 'virtual server group' for logistical purposes only. When creating the pack node, you do not need to supply a valid Server hostname or IP address, so choose a naming convention that makes sense in your environment.

Next, select the "pack" radio button option under the web configuration when creating or editing the server node, in order to designate this server node as the "pack" server.

Now select the "Master" server from the list of Master servers. The Master server will be the server node that Aegir rsync's the platform and site to. Typically, you would choose the Aegir server itself as the 'master'.

Finally, select the "Slave" servers from the list of Slave servers. The Slave servers will have the Apache or Nginx config rsync'd to them but not the platform or site code, since those will be available to all Slave servers via the NFS share.

Configuring the Web server nodes (Master and Slaves):

Configure all web server nodes using these instructions. Take care to ensure the 'aegir' user and group on your NFS client machines, have the same UID/GID as that of the NFS server, or else you may run into permissions issues with NFS.

Then mount the files on the remote server.

On the NFS server:

sudo apt-get install nfs-kernel-server
echo "/var/aegir/platforms    10.0.0.0/24(rw,no_subtree_check)" >> /etc/exports
sudo service nfs-kernel-server reload

(Replace the subnet here or add specific /32 hosts as necessary for your environment)

Then on the web servers (Master, if it wasn't also the NFS server, and the Slaves):

sudo apt-get install nfs-client
sudo mount 10.0.0.1:/var/aegir/platforms /var/aegir/platforms

(Replace the NFS server's IP here with that of your master server/Aegir server)

Add this to your fstab on the servers that mount the NFS share, so that the share is mounted on boot:

10.0.0.1:/var/aegir/platforms /var/aegir/platforms nfs rw 0 0

Creating a Platform on a Pack:

When configuring a Platform to be deployed on a Pack, choose the "Pack" server node from the Web server radio group during the Platform node creation. Then you choose this Platform as usual when adding a site, and that site will be served from any servers within the Pack.

Caveats

Relying on an NFS share to serve your entire /var/aegir/platforms can be a single point of failure if the NFS share becomes unavailable. You may want to look into providing some sort of failover for NFS (google for things like DRBD and Heartbeat), or using some other form of redundancy for your NFS (Netapp filer clusters etc)

There have also been reports of issues with MySQL GRANT statements not being provided to all webservers in the pack - especially where the master server is not the Aegir hostmaster server. This issue is ongoing - see the Talk page here or this ticket

Also attached is an example diagram of a Pack cluster known to be functioning in production (with an optional MySQL-MMM cluster out of scope for this documentation), which may help you visualise the Pack and how it can be put together.

I had the hardest time finding resources & documentation on how to get this configured properly so I am adding this to the documentation for those of you who may need it.

A couple of notes: I am using Ubuntu 10.04 LTS. I set my apache to port 8082 because there was a conflict on port 8080 on my system. You should make a copy of each file before editing it. Memcache settings are drupal 7.

Varnish

Setting up varnish isn't too hard but it could end up being kind of tedious if you configure something incorrectly & you have alot of sites.

First you install it sudo apt-get install varnish

Then you have to go to configure it. I use vim. sudo vim /etc/varnish/default.vcl

These are my settings.

backend default {
    .host = "127.0.0.1";
    .port = "8082";
    .connect_timeout = 600s;
    .first_byte_timeout = 600s;
    .between_bytes_timeout = 600s;
}
sub vcl_recv {
  // Remove has_js and Google Analytics __* cookies.
  set req.http.Cookie = regsuball(req.http.Cookie, "(^|;\s*)(__[a-z]+|has_js)=[^;]*", "");
  // Remove a ";" prefix, if present.
  set req.http.Cookie = regsub(req.http.Cookie, "^;\s*", "");
  // Remove empty cookies.
  if (req.http.Cookie ~ "^\s*$") {
    unset req.http.Cookie;
  }
 

// Skip the Varnish cache for install, update, and cron
  if (req.url ~ "install\.php|update\.php|cron\.php") {
    return (pass);
  }
 

// Cache all requests by default, overriding the
  // standard Varnish behavior.
  // if (req.request == "GET" || req.request == "HEAD") {
  //   return (lookup);
  // }
}
sub vcl_hash {
  if (req.http.Cookie) {
    set req.hash += req.http.Cookie;
  }
}

Now you have to edit /etc/default/varnish sudo vim /etc/default/varnish

Here are my settings

# Should we start varnishd at boot?  Set to "yes" to enable.
START=yes
# Maximum number of open files (for ulimit -n)
NFILES=$(ulimit -n)
#Malloc size depend on your memory server
DAEMON_OPTS="-a :80 \
             -T localhost:6082 \
             -f /etc/varnish/default.vcl \
             -S /etc/varnish/secret \
             -s malloc,512M \
             -u www-data \
             -g www-data"

Now we have to configure apache's listening ports

sudo vim /etc/apache2/ports.conf

change

NameVirtualHost *:80
Listen 80

So that it looks like this

NameVirtualHost *:8082
Listen 8082

Start varnish services varnish start

Now login to aegir Edit your server & change the port from 80 to 8082

Aegir will re-verify the server, as well as all platforms & sites on the server.

If that doesnt work, you need to go to /var/aegir/config/server_master/apache/vhost.d and edit all of your virtual hosts so that the port shows 8082 instead of 80 then do the same thing with /var/aegir/config/server_master/apache.conf Reverify your server.

Now add this to the local.settings.php of the sites that you want to leverage varnish

<?php
# Tell Drupal it's behind a proxy
$conf['reverse_proxy'] = TRUE;
# Tell Drupal what addresses the proxy server(s) use
$conf['reverse_proxy_addresses'] = array('127.0.0.1','your-ip-address-here');
# Bypass Drupal bootstrap for anonymous users so that Drupal sets max-age &gt; 0
$conf['page_cache_invoke_hooks'] = FALSE;
?>

Memcache

There is hardly any current documentation for setting up memcache on D7, especially not for aegir.

FIrst you install memcache & its dependencies Download & install memcache module into the platform of the site/sites in which you will be using memcache

Then you have to edit /etc/default/memcached sudo vim ./etc/init.d/memcached

Here are my settings

#! /bin/sh
#

PORT=11211
USER=nobody
MAXCONN=1024
OPTIONS=""
DAEMON=/usr/bin/memcached

RETVAL=0
prog="memcached"

start_instance() {
        echo -n $"Starting $prog ($1): "
        start-stop-daemon --start --quiet --pidfile /var/run/memcached/memcached.$1.pid --exec $DAEMON -- -d -p $PORT -u $USER  -m $2 -c $MAXCONN -P /var/run/memcached/memcached.$1.pid $OPTIONS
        RETVAL=$?
        echo
        [ $RETVAL -eq 0 ] && touch /var/lock/memcached.$1
        PORT=`expr $PORT + 1`
}

stop_instance() {
        echo -n $"Stopping $prog ($1): "
        start-stop-daemon --stop --quiet --oknodo --pidfile /var/run/memcached/memcached.$1.pid --exec $DAEMON 
        RETVAL=$?
        echo
        if [ $RETVAL -eq 0 ] ; then
            rm -f /var/lock/memcached.$1
            rm -f /var/run/memcached/memcached.$1.pid
        fi
}
start () {
        # insure that /var/run/memcached has proper permissions
        mkdir -p /var/run/memcached
        if [ "`stat -c %U /var/run/memcached`" != "$USER" ]; then
                chown $USER /var/run/memcached
        fi

        start_instance default 64;
        start_instance block 16;
        start_instance content 128;
        start_instance filter 128;
        start_instance form 32;
        start_instance menu 16;
        start_instance page 8;
        start_instance update 8;
        start_instance views 8;
        start_instance path 8;
        start_instance field 8;
        start_instance rules 8;
        start_instance token 8;
        start_instance image 8;
        start_instance apachesolr 16;
}
stop () {
        stop_instance default;
        stop_instance block;
        stop_instance content;
        stop_instance filter;
        stop_instance form;
        stop_instance menu;
        stop_instance page;
        stop_instance update;
        stop_instance views;
        stop_instance path;
        stop_instance field;
        stop_instance rules;
        stop_instance token;
        stop_instance image;
        stop_instance apachesolr;
}

restart () {
        stop
        start
}

# See how we were called.
case "$1" in
  start)
        start
        ;;
  stop)
        stop
        ;;
  status)
        status memcached
        ;;
  restart|reload|force-reload)
        restart
        ;;
  *)
        echo $"Usage: $0 {start|stop|status|restart|reload|force-reload}"
        exit 1
esac

exit $?

Start memcache sudo services memcached start If you see errors u may have an issue where a one line got split into two lines. Check and make sure that none of your lines got broken off.

Place this code in your local.settings.php file inside your site folder

// the path to the core cache file
  include_once('./includes/cache.inc');
  // the path to the memcache cache file
  include_once('./sites/all/modules/memcache/memcache.inc');
  // make MemCacheDrupal the default cache class
  $conf['cache_default_class'] = 'MemCacheDrupal';
  
  # Key Prefix: edit this for multisite use.
  $conf['memcache_key_prefix'] = "$_SERVER[db_user]";
  
  $conf['memcache_servers'] = array(
  '127.0.0.1:11211' => 'default',
  '127.0.0.1:11212' => 'menu',
  '127.0.0.1:11213' => 'filter',
  '127.0.0.1:11214' => 'form',
  '127.0.0.1:11215' => 'block',
  '127.0.0.1:11216' => 'update',
  '127.0.0.1:11217' => 'views',
  '127.0.0.1:11218' => 'content',
  '127.0.0.1:11219' => 'apachesolr',
  '127.0.0.1:11220' => 'path',
  '127.0.0.1:11221' => 'field',
  '127.0.0.1:11222' => 'rules',
  '127.0.0.1:11223' => 'token',
  '127.0.0.1:11224' => 'image',    
);
$conf['memcache_bins'] = array(
  'cache' => 'default',
  'cache_menu'   => 'menu',
  'cache_filter' => 'filter',
  'cache_form'   => 'form',
  'cache_block'  => 'block',
  'cache_update' => 'update',
  'cache_views'  => 'views',
  'cache_views_data'  => 'views',
  'cache_content'  => 'content',
  'cache_apachesolr'  => 'apachesolr',
  'cache_path'  => 'path',
  'cache_field'  => 'field',
  'cache_rules'  => 'rules',
  'cache_token'  => 'token',
  'cache_image'  => 'image',
);

And that should be basically it.

It can be convenient to do stuff as the aegir user. The default shell of the aegir user is /bin/false, so you have to make sure to use something more usable:

sudo su - aegir -s /bin/bash

GNU Screen is a super useful window manager for the console. When launching screen you will usually get errors like

Cannot open your terminal '/dev/pts/6' - please check.

You can get around this by running

script /dev/null

All in all this works nicely:

sudo su aegir -s /bin/bash -c "script -q /dev/null"

It can be convenient to put it in a little script as /usr/local/bin/suaegir

Allowing other users besides root on your system to run commands as aegir

If you wish to allow other users on your system to run commands as the aegir user using sudo, without allowing them to use sudo generally, you can add the following two lines to your /etc/sudoers file using visudo:

If you want to allow these users to use aegir without entering a password, simply change the second line to this:

If you connect to your Hostmaster server and look at ~aegir/config/server_examplecom/apache.conf, you can see that this file includes files from pre.d and post.d directories. The includes are done in the following order:

1. pre.d
2. vhost.d
3. platform.d
4. post.d

The earlier files take precendence over the later files for <VirtualHost> blocks. The latter files take precedence over earlier files for <Directory> blocks.

If we wanted to add a phpini directive that can only be set on a PHP_INI_PERDIR-for example, post_max_size-we could create a file called upload.conf and add it either to pre.d or post.d.

Here's a possible upload.conf:

If we put upload.conf in pre.d, our setting would always take precedence, because it occurs higher up the chain of include files.

If we put upload.conf in post.d, our setting would be applied only if the same setting is not defined higher up the chain by the aegir code. As Antoine states here post.d is mainly useful when migrating in sites. It would also be useful if you wanted to set a server-wide default which could be overridden on by a virtual host or platform config setting.

Related: http://community.aegirproject.org/node/73

Introduction

SSL support was significantly improved in Aegir 0.4 alpha9 and subsequent releases have further refined the SSL functionality. Here are the current steps to configure SSL support in Aegir and apply it to your web sites.

Prepare Your Server

1. Make sure port 443 is open for SSL traffic.
2. From the command line, install SSL software for your web server (e.g. on Debian/Ubuntu you can use sudo apt-get install openssl).
3. Enable SSL support (e.g. sudo a2enmod ssl). You will need to restart Apache at this point.

Enable SSL Support in Aegir

1. You have to enable SSL support in Aegir as it is off by default. Assuming the URL of your Aegir front end is aegir.example.com, browse to aegir.example.com/admin/hosting/features
2. Click on Experimental to reveal experimental features
3. Check SSL support
4. Click Save configuration

Configure Your Aegir Server

1. Click on the Servers tab
2. Click on the server that you wish to enable SSL support
3. Click Edit to change the server configuration
4. Click apache_ssl (this will reveal an additional field: SSL port, which should be already populated with 443).
5. You may also have to add an IP address to the IP addresses field. The field is used as an "IP pool" for SSL certificates: IPs are assigned to SSL sites when they are created on a first come, first served basis. (Note that there are known issues with this process, see issue #1126640 for details.)
6. Click Save - this will start various tasks beginning with a verify task on the server followed by verify tasks on all platforms that are associated with that server
7. If all goes well you will see the following changes in your Aegir file system structure: a new /var/aegir/config/ssl.d directory and a new /var/aegir/config/server_master/ssl.d directory.

The /var/aegir/config/ssl.d directory is where you will be able to manipulate SSL keys and certificates, for example by importing commercial SSL certificates or generating a new key. Do not manually edit the /var/aegir/config/server_master/ssl.d directory as changes to that directory will be overwritten when the server or site are verified.

Configure Your Aegir Site

1. You must enable SSL on your sites that are on those platforms associated with the server. Browse to aegir.example.com/hosting/c/example.com
2. Click Edit to change the site configuration
3. Choose the type of Encryption required and the Encryption key (see the explanatory notes below each option). NOTE:, Alternatively, you may specify a directory under /var/aegir/config/server_master/ssl.d where your own certificate and key is to be stored (see Apache notes below).
4. Click Save. Aegir will then generate a certificate and private key for your web site and insert these into a new VirtualHost directive in your vhost file. (This file is typically at /config/server_master/apache/vhost.d/example.com).
5. If all goes well the VirtualHost directive will now have these important elements:

Now, when you navigate to https://example.com you should see that your site is SSL enabled. It will, however, generate warnings in your browsers because it is a self-signed certificates. See below for how to use commercial certificates to remove this warning.

Notes for Apache users with Commercial Certificate File(s)

If you wish to use your own commercial certificate and key you will need to do the following:

1. Follow the directions above, using the "Generate new encryption key" option and using your site's domain name for the "New encryption key". This will create a site directory under /var/aegir/config/ssl.d/example.com. With this step, you have created a self-signed certificate, and your site is now configured to use it.
2. This generated a 2048 bit RSA key for you along with a CSR (Certificate Signing Request). If you prefer to generate your own RSA key, replace the files (openssl.key and openssl.csr) in the /var/aegir/config/ssl.d/example.com directory with your RSA key and associated CSR.
3. Copy and paste the .csr file into the form for the issuing Certificate Authority (CA) to create your certificate.
4. When your certificate has been generated, download the files from the issuing authority and place in your temporary folder on your PC. You may have more than one .crt files, in this case you have a "bundle" or what we call a "certificate chain" that you need to add in aegir (see below).
5. Transfer all the files to /var/aegir/config/ssl.d/example.com. Rename the site .crt file to openssl.crt. If you have a certificate chain, install it in openssl_chain.crt. You should have at least three files in the directory (openssl.crt, openssl.key, openssl.csr, and optionnally openssl_chain.crt).

Verify your site from aegir's frontend.

You should now be able to access your site via https:// using your commercial certificate.

Notes for Nginx users:

It is recommended to allow Aegir to create a default self-signed certificate and key first, and then replace the contents of both files (not the files itself) with your real key and certificate. Any chained certificates (bundles) should be included in the same file, directly below your own certificate - there is no need for extra files/lines like it is for Apache configuration.

Debian/Ubuntu

There is preliminary support for DNS in Aegir's backend that allows it to manage zonefiles dynamically when sites are created. There are still a few major bits missing (described in this meta-ticket) so we generally recommend people use the wildcard approach for now.

That said, while perhaps not yet ready for production use, Aegir's DNS functionality can be quite useful for local development environments. If you run Aegir locally, you're probably in the habit of hacking /etc/hosts regularly, or if you're more adventurous, you've set up a local DNS forwarder, such as dnsmasq. With Aegir's DNS feature, you can avoid this hassle, and let Aegir handle it transparently.

While Aegir supports both BIND and dnsmasq, this documentation will focus on the former. The first step is to install BIND. On Debian-based distros, this will look like:

Next we need to allow the aegir user to run rndc (the name server control utility). On recent Debian systems, this will involve editing /etc/sudoers.d/aegir, whereas on older releases this would be /etc/sudoers. Modify the aegir line to read:

Then we need to make sure the bind user has access to read Aegir's files, so we'll add bind to the aegir group:

We're now ready to activate the feature in Aegir's frontend. Go to Hosting >> Features (admin/hosting/features) and select "DNS Support" under the "Experimental" fieldset, and save the configuration.

Finally, we need to activate DNS on the Aegir server. Visit the server node (hosting/c/server_master) and click the edit tab (which should bring you to node/2/edit). Then under "DNS Service", select "Bind" and then save.

This should trigger a verify of the server (and then probably the platforms on it too), after which Aegir will be managing your local BIND server, and it's zonefile(s). If you have installed Aegir in /var/aegir, put this line in the file /etc/bind/named.conf.local:

Aegir is now a full-fledged DNS server that you can use to resolve addresses locally. This can be accomplished on Debian-like systems by editing /etc/resolv.conf to include "nameserver 127.0.0.1". If you're running Aegir in a VM, you can just point this to the address of the virtual machine.

CentOS/RHEL

You need to have a working DNS/bind/named server for AEgir to take control of. What follows is rough documentation to reach that stage. It is currently UNTESTED in a production environment.

Additional Notes

Additional documentation can be found in the Provision DNS module: http://drupalcode.org/project/provision.git/blob/HEAD:/dns/NOTES.

Why run a wildcard DNS server?

A wildcard DNS setup lets you automatically have subdomains for a given domain. For example, say you own the domain widgets.com and you want to setup an unlimited number of subdomains like dev.widgets.com, test.widgets.com, customers.widgets.com, etc.... Typically you would have to set these all up individually. A wildcard DNS can let you bypass a lot of configuration. In a development environment it can let you setup any number of test/development sites very quickly and easily. Drupal developers in particular can leverage Drupal's multisite installation feature to setup lots of sites for development or production very quickly.

Creating a DNS wildcard with hosted DNS

Many of the popular domain registration companies allow you to manage your DNS records through a web interface. If you have access to such a facility, adding a DNS wildcard is easy: you just create an A record called '*', pointing to your server's IP address.

For convenience, here are instructions for some popular hosting providers: GoDaddy, hosting.com (which uses the popular cPanel system) and 123-reg.co.uk. It is likely that your host will have a similar system to one of these.

How to configure DNS wildcards on your own server

Ubuntu/Debian

OS X Snow Leopard

Setting up a Wildcard DNS configuration on Ubuntu/Debian

Overview of Steps on Ubuntu/Debian

I. Install Bind 9 II. Add a zone to /etc/bind/named.conf.local. Check the syntax of named.conf.local with named-checkconf III. Add a zone file & Check the syntax of your zone files for errors with named-checkzone IV. Edit /etc/resolv.conf V. Start up Bind VI. Check setup with dig VII. Troubleshoot if needed

I. Install Bind 9

II. Edit /etc/bind/named.conf.local to add a zone.

We need to add a zone to /etc/bind/named.conf.local. A zone is a record for a domain. In this case we'll use a fake domain for development purposes. Our domain can be called anything. Let's call it mydev. (I was really tempted to call the domain bullshit - would have been great for screencasts). So at a shell prompt do:

Add this to the end of the file:

Save the file with Control - O and enter. Exit from nano with Control X.

Check the syntax of the file as follows:

If the file is syntactically correct the shell prompt will return nothing. If there is an error - make sure you did not miss a quote or semicolon and recheck the file.

III. Add a zone file & Check the syntax of your zone files for errors with named-checkzone

Add this to the file replacing 10.0.2.15 with your IP address

Save the file with Control - O and enter. Exit from nano with Control X. Check the syntax with the following:

If the syntax of the file is correct you should see something like:

If not review the file for errors. In particular whenever referring to a domain, it must end in a . , thus mydev.

IV. Edit /etc/resolv.conf

resolv.conf tells applications like browsers where to look for DNS info. By default it may have your ISPs info. We need to tell it to check our local DNS server first then the ISP.

Add/change the following

If you are receiving an IP address via DHCP then you need to edit /etc/dhcp3/dhclient.conf too.

Look for the lines send host-name, supersede domain-name, and prepend domain-name-servers and set them as follows (and make sure they are uncommented ) :

Whew! Almost there.

V. Start up Bind (or Restart)

VI. Check setup with ping and dig

If ping works then you should be good to go. If not try dig and part V. To stop the ping action press [Ctrl]+[c].

VII. Troubleshoot

I found the section on Troubleshooting Bind in O'Reilly's "Linux System Administration" helpful. Fortunately, this part of the book is viewable on Google books as of this writing (10/29/2009): http://books.google.com/books?id=-jYe2k1p5tIC&lpg=PP1&dq=Linux%20System%... . See page 66

Getting a Wildcard DNS running on OSX Snow Leopard

Note: it took me several tries to get this working. If you are new to DNS be patient with yourself - you'll get it, but may take a few tries.

In this example I will concentrate on setting a development environment with OSX using wildcard DNS

Overview of Steps

I. Edit /etc/named.conf to add a zone.
II. Add a zone file at /var/named/ III. Check the syntax of named.conf and your zone files for errors IV. Edit /etc/resolv.conf V. Set your computers network settings to use 127.0.0.1 as a name server VI. Start up Bind VII. Check setup with dig VIII. Reboot if needed

Before we start a few more notes.

I tend to use the nano text editor to edit Unix configuration files you could use Emacs, VI, Textmate, BBEdit or the editor of your choice.

Backup all these files we are editing so you can start over if you mess up. I didn't do this and it added more time to the project. For example to backup /etc/named.conf do:

Last, most of the files we need to edit are owned by root so you will need to use sudo to edit these files. If you get tired of typing sudo you can become root by doing this:

Be careful when working as root or using sudo. You can mess up your system so make sure to backup. All example here are run as root.

I. Edit /etc/named.conf to add a zone

We need to edit named.conf to add our zone.

I called my zone vmdev so I added this to named.conf

I added this right before the zone 0.0.127.inaddr.apra and saved the file. So we told Bind to look in /var/named/db.vmdev for this zone.

II. Add a zone file at /var/named/

You can just copy this but be sure to change 192.168.0.199 to you Mac's IP address

III. Check the syntax of named.conf and your zone files for errors

Run this to check your named.conf file:

If it returns nothing, your named.conf file is at least syntactically correct. If there is an error, then well you have to diagnose and fix the error.

Now run this to check your zone file:

It should return something like this:

If there are errors then diagnose and fix them.

IV. Edit /etc/resolv.conf

V. Set your computers network settings to use 127.0.0.1 as a name server

Do this at System Preferences -> Network. You may want to use your ISPs Name server as the second name server

VI. Start up Bind

The -w option tells OSX to enable Bind at startup

VII. Check setup with dig

Should return something like this:

The key here is status NOERROR; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 45640 If you get an error then check previous steps.

Now try:

should return:

but if it does not got to VIII.

VIII. Reboot if needed.

I needed to reboot to get everything to take. Whoila! Have a cookie or something.

Because Aegir is capable of installing, deploying and moving your sites around, it has to manage the various configuration files that keep your sites running.

These configurations include the standard Drupal settings.php for a site, .htaccess overrides for your HTTP server, as well as HTTP 'VirtualHost' or 'vhost' configuration files that tell your HTTP server where your site is.

A caveat of this system is that Aegir regularly re-generates these configuration files to apply new changes that have been made to the sites or platforms, as well as doing so as a safety mechanism to ensure these files are 'sane'.

For example, if you make a modification to a site vhost or settings.php and it breaks your site, running a 'Verify' task on the site should restore the file back to how it was.

However, sometimes it is necessary to add custom configuration or overrides to these files, and you can't do that if Aegir is regularly wiping your changes.

Fortunately, Aegir provides a series of hooks and inclusions for overriding or injecting customisations into these files safely and persistently.

This chapter shows you how each of these hooks or inclusions work.

Changing maximum filesize upload is common when setting up sites in Drupal. As described in Overriding site-specific PHP values you can change this value for each site created with Ægir by adding a .drush.inc file in /var/aegir/.drush directory. But wouldn´t it be nice to be able to do it side-wide?

Here below is the same code from ergonlogic demonstrating how to create a domainname.drush.inc file using the domain name as a condition before the code injection.

Apparently you can do this side-wide by omitting the IF statement and create a file with a .drush.inc extension.

For instance, you could create a file called global_settings.drush.inc and put in the following code:

* the closing ?> syntax should not be used

Make sure you Verify your site after you create the file. Then scroll through the log and find the message you added in the code:

Overriding PHP file size values. See .drush/global_settings.drush.inc

Using a .htaccess with an Allow Override all directive in Apache can be a major performance killer, because it requires Apache to stat each subdirectory of the codebase looking for overrides in .htaccess.

As a result, Aegir disables the reading of the Drupal .htaccess in the runtime environment.

This does not mean that the .htaccess is not needed. Instead, when you run the Verify task against a Platform, the .htaccess is studied by Aegir and its contents are copied into the platform-wide Apache vhost configuration, typically located in /var/aegir/config/server_master/apache/platform.d

Need to make a modification to the .htaccess? Simple: you can simply edit it in-place as you normally would, but you must re-Verify the platform in Aegir afterward, in order for those new or modified settings to be 'loaded in' to the platform vhost file.

The end result is improved performance for your sites, without losing any functionality, as you can still customise the .htaccess to your liking.

Aegir provides some hook functions in its API, one of which allows you to inject extra configuration snippets into your Apache vhost files for sites.

When would I want to do this?

A good example for this is when you may need to inject a custom Rewrite rule that goes beyond what the Aegir Aliases 'redirection' feature provides.

Or, perhaps you have to inject some htpasswd mod_auth password protection for your site, or perhaps a CustomLog definition. The http_basic_auth module uses this. (code)

Typically you'd just add what you need to the vhost file, but the problem is that Aegir manages these vhosts, and on every Verify task, will rewrite the config from a template, blowing away your changes in the process. Ouch!

Fortunately there is a very easy and elegant solution to this problem to save your configurations persistently across Verify tasks and the like, by means of invoking the Provision hook provision_apache_vhost_config(), or, if you are using Nginx, provision_nginx_vhost_config() (and just replace the below examples with 'nginx' instead of 'apache' where necessary). Below "mig5" is just an example, you can replace this with anything as drush looks for all *.drush.inc files in ~aegir/.drush

A simple example

In this example I'll inject a simple 'ErrorLog' apache definition into a vhost to save the site error logs to a file.

1. Create a file in ~aegir/.drush called mig5.drush.inc. (Choose <any> prefix for the file name <any>.drush.inc).
2. Add this snippet of PHP to the file:
   
<?php
  function mig5_provision_apache_vhost_config($uri, $data) {
    return "ErrorLog /var/aegir/" . $uri . ".error.log";
  }
?>
   (Choose <any> prefix for the function name <any>_provision_apache_vhost_config).
3. drush cache-clear drush
4. Install a site or verify an existing one

Check your site's vhost config file (in /var/aegir/config/server_master/apache/vhost.d/) and you'll see the line has been injected into the '#Extra configuration' area of the vhost

It's that simple! You can see that via the hook, we pass $uri and the drush data to the function, allowing me to abstract the site url so that each site will get its own error log. You could do extra PHP conditionals to ensure certain data only gets inserted into certain sites of a specific name.

To inject multiple lines instead of one, use an array, i.e

The key point of this is that the file ~aegir/.drush/mig5.drush.inc file will never be touched by Aegir, so you can rest assured your changes will be respected.

If you want to only inject code into a specific site, wrap your code with an if statement, i.e

A more advanced example

Managing multiple versions of a production site can be a tricky proposition, even in Aegir. This is particularly true when you want to use the same canonical domain name to allow users to access one such site of your choosing at any given moment. For instance, in Aegir I might have a site named www.example.com (with an alias of example.com,) and a couple of alternates with the site names of test1.example.com and test2.example.com. If I suddenly decide that I want my primary domain to access test1.example.com, Aegir forces me into a tedious process that ultimately results in site downtime – I have to delete or migrate the existing www.example.com site to a new unused site name (or clone it to an unused site name, and delete the original) and then I have to migrate test1.example.com to the vacated site name www.example.com. Alternatively, I could add the www.example.com and example.com aliases to test1.example.com but then my users would just be redirected to test1.example.com.

Given the way Aegir manages aliases, it would actually be easier to make this switch if the desired address was never used as a site name to begin with. Instead of having the site name www.example.com alongside of the two other test sites, we might have live.example.com, with in-use aliases of www.example.com and example.com, and a rewrite instruction in the vhost that rewrites live.example.com to www.example.com. If we could easily change the rewrite instructions in that vhost, all we would need to do is move the aliases from one site to the next in the GUI (with the requisite verify tasks executed on each site in question) in order to quickly change which site was being loaded at any given moment by www.example.com. For example, if I wanted to move to test2.example.com, I would remove the www.example.com and example.com aliases from live.example.com and verify, add those aliases to test2.example.com and verify, and change my vhost so that test2 .example.com is rewritten as www.example.com. Since as previously mentioned Aegir overwrites changes to the vhost during the verify process, the solution is to use the provision_apache_vhost_config hook in a drush.inc file to selectively add the rewrite information to the vhost when verifying the site that we want our canonical domain to refer to.

When we want to switch again, say to test1.example.com, We could update the code to look for the test1.example.com uri.

Sometimes it is useful to override certain PHP values on a per-site basis, but changes to php.ini are generally server-wide. Depending on the value you want to override, a couple of options present themselves.

First, let's consider where PHP values can be changed. http://www.php.net/manual/en/ini.list.php lists php.ini directives, and under the "Changeable" column, indicates where a configuration setting may be set. If your value shows either PHP_INI_USER or PHP_INI_ALL, then the easiest way to change this value would be using ini_set() in a local.settings.php:

On the other hand, if the changes mode is either PHP_INI_PERDIR or PHP_INI_SYSTEM, php_ini() won't work. In this case, the solution is to inject the value into the vhost. Since vhosts are managed by Aegir, manually adding an override to /var/aegir/config/server_master/apache/vhost.d/<uri> would get blown away the next time that the site is verified.

As described in Injecting into site vhosts, we can inject values into vhosts using a Drush hook. For example, to raise the file upload size limit on http://ergonlogic.com, I added the following code in /var/aegir/.drush/ergonlogiccom.drush.inc:

This results in the insertion of the following lines into /var/aegir/config/server_master/apache/vhost.d/ergonlogic.com:

Also, in the verify task log I get the following informative message:

One challenge this technique may present is inspecting the values of the parameters passed into this function. It appears that the Hostmaster site doesn't get bootstrapped, and so common debugging tools (such as devel.module's dd()) aren't available. However drush_log() is, and when called, will push arbitrary messages back into your Aegir site's verify task log.

So sticking the following into the function above can help:

Introduction

Every web site in an Aegir environment has a Drupal configuration file settings.php in /sites/example.com directory. Web administrators often need to make changes to this file; however, the Aegir system also manages this file and any manual customizations will be lost when a site is verified.

Fortunately, there are two mechanisms to ensure that your customizations can be preserved. If you look in the bottom of an Aegir settings.php file you will see references to two files local.settings.php and global.inc.

If these files exist they are loaded at run time by Drupal. As you can probably surmise from the paths to these files, local.settings.php is for site-specific customizations and global.inc is for Aegir-wide customization.

Let's look at these files in more detail. We'll use customization of user session cookies as an example. If you look at the settings.php file generated by Aegir you see that it sets more conservative php settings for cookies (@ini_set('session.cookie_lifetime',  0); i.e. cookies expire immediately) than are in the default.settings.php packaged with Drupal (@ini_set('session.cookie_lifetime',  2000000); i.e. 2 million seconds, which is just over 23 days).

Site-specific Customization

The local.settings.php file by default does not exist in a new Aegir site installation so you have to create it. Continuing with our example of user session cookies, let's override the Aegir default.

Note that because local.settings.php is included after the variables are set in the main settings.php it's customizations takes precedence.

Now, whenever you clone a site or migrate it between platforms, Aegir moves a copy of local.settings.php as well.

Using drush_hook_provision_drupal_config

You can also use the API to add module-specific site configurations with hook_provision_drupal_config

For example it could look like this

That is used to add the site settings added by the UI in the hosting backend implemented in https://github.com/EugenMayer/hosting_site_settings

Aegir-wide Customization

In some situations you may want to implement the same configuration settings on all your Aegir sites. This is where global.inc comes in. Note that global.inc is now included in settings.php before local.settings.php, so that Aegir system administrators no longer retain the ability to override configuration changes in local.settings.php, but instead it is possible to override global settings per site (read why this has been changed: http://drupal.org/node/1044938 - note: this change is available since 0.4-rc1 release).

For example, say the system administrator wanted to limit users' session lifetimes to a maximum of one day they could create a global.inc as follows:

You can even set more granular policy within global.inc (however it makes more sense to keep site-specific overrides in the local.settings.php):

If you are using Aegir to manage multiple remote webservers, you will need to run the Verify task on the webserver in order to push global.inc to the remote machine.

Note: on some Aegir installations (e.g. alpha14) the permissions on /var/aegir/config are insufficent for Apache to properly include the global.inc file. If you find that the configuration settings in global.inc are being ignored, change the permissions with chmod a+x /var/aegir/config. This only has to be applied to the config directory as the sub directory and file permissions should be correct.

If you have other configuration examples, create a wiki and reference it here.

The drushrc.php file can be changed in two ways:

1. by changing the templates used for the Drushrc context (see the hook_provision_config_load_templates() hook)
2. by creating a local.drushrc.php file in the site-specific folder (e.g. sites/example.com/local.drushrc.php

This is a stub. You can put more stuff here and it would be prettier.

1. Aegir 7.x-3.x

Contrib modules for the upcomming version are listed on a sub page

2. Extensions to Hostmaster (frontend)

2.1. Verified in Aegir 2.x

Aegir HTTP basic authentication (now included in hosting_tasks_extra)

This module allows you to protect sites with passwords.

Hosting server titles

This is a really simple module that allows you to change the names of servers that are displayed in lists in the Hosting frontend when choosing what server to use for something.

Hosting site Backup Manager

Add a backups tab to a site node. It extends the default backup functionality with the ability to download a backup over HTTP.

Now also includes the functionality from Hosting backup garbage collection and Hosting backup queue

Hosting site Git

This is a simple module for the Aegir project that adds a 'Git pull', 'Git checkout' and 'Git clone' task for sites.

Hosting platform Git

Provides integration with Aegir that allows provisioning a platform from a git repository (also allows specifying the branch or tag name)

Hosting tasks extra

This module extends Aegir hostmaster (and drush/provision) with some additional tasks. Such as: cache-clear and registry-rebuild.

Now also includes the functionality from Aegir HTTP basic authentication

Hosting database login

Provides a link to login into a PHPMyAdmin instance (or other db management web software) configured for the current site database server. Requires dblogin to be installed on the site.

Aegir Piwik integration

Makes it easy to connect an Aegir instance and a Piwik instance. When you create a site in Aegir, the site is registered in Piwik. When you verify the site in Aegir, new site aliases (if any) get added to Piwik. Also adds system variables to settings.php in order to integrate properly with the Piwik module.

Note: There's a good chance that other Aegir 1.x contrib modules also work on 2.x

2.2. Aegir 1.x

Aegir Ubercart Integration

This module allows you to sell an Ægir client, with quotas and access to specific platforms, through Ubercart . It automates a number of set-up tasks from the moment the order ...

Aegir HTTP basic authentication

This module allows you to protect sites with passwords.

Aegir HTTP basic LDAP authentication

A fork of the above to allow you to specify an LDAP server and Require (ldap filter) string for authentication of 'sites'.

Aegir feeds

This is a very basic module that provides feeds integration with Aegir . Features Provides mapping targets for Aegir site nodes, allowing you to create new sites from a feed or file upload.

Aegir Piwik integration

Makes it easy to connect an Aegir instance and a Piwik instance. When you create a site in Aegir, the site is registered in Piwik. When you verify the site in Aegir, new site aliases (if any) get added to Piwik. Also adds system variables to settings.php in order to integrate properly with the Piwik module.

Aegir Rules

Aegir Rules provides Rules integration for the Aegir.

Aegir Drush Make Platform working-copy

This feature allows you to specify 'working-copy' when adding a platform using a Drush makefile. Working-copy means your .git subdirectories are preserved in the platform, which may be useful for development purposes.

Aegir Subfolders

Support for 'example.com/subsite1' style sites in Aegir (experimental as of July 2012)

Hosting Platform Pathauto

This is an add-on module for the Aegir hosting system: http://aegirproject.org/ This module simply makes a little time-saving tweak when creating a new platform: ...

Hosting queue runner

This module allows the Hosting tasks queue for the Aegir project to be 'daemonized' so that tasks are run as soon as possible instead of waiting for a cron run. This makes Aegir appear much more responsive. This module was inspired by the Waiting queue project. Requirements You will need ...

Hosting Reinstall

The Hosting Reinstall module provides a frontend for the Provision Reinstall module so that you can reinstall any sites via Hostmaster (Aegir).

Hosting backup garbage collection

This is an add-on module for the Aegir hosting system: http://aegirproject.org Introduction This module allows you to specify how long Aegir should retain backups for. You can specify, ...

Hosting backup queue

This is a simple module for the Aegir project that allows scheduling of backups. E.g. backup sites every hour, day or month. The module allows for the general settings to be applied to all sites, ...

Hosting site Backup Manager

Add a backups tab to a site node. It extends the default backup functionality with the ability to download a backup over HTTP.

Hosting site Git

This is a simple module for the Aegir project that adds a 'Git pull', 'Git checkout' and 'Git clone' task for sites.

Hosting upload

This module allows administrators to add platforms to aegir and extend platforms and sites with modules, themes, libraries without the need of ssh access.

Hosting Profile Roles

Hosting Profile Roles extends Aegir to enable more control over what role(s) a client is assigned during site install. Since, by default, Aegir client's are given UID1 during site installs, this module also allows UID1 to be assigned to another user.

Hosting server titles

This is a really simple module that allows you to change the names of servers that are displayed in lists in the Hosting frontend when choosing what server to use for something.

Services API Support

Integrates the Services API framework into the Hostmaster suite of tools. It allows Aegir managers the ability to build Services API connections over any of the available servers for Services API.

Hosting Advanced Cron

This module allows an administrator to set the default cron interval globally and to override that interval for individual sites.

Hosting Features

This module provides a Task to Hostmaster that provides integration with a site's Features. (In beta as of June 1,2012)

Hosting Notifications

This is a module that integrates with the Notifications framework. This allows you to receive notifications about task execution in various formats.

Hosting Task Garbage Collection (merged into Aegir 7.x-3.x)

This module will delete rows in the {hosting_task} and {hosting_task_log} tables. (In alpha as of June 1,2012)

Hosting Remote Import

This Drupal module provides a UI for fetching sites from remote Aegir servers. (In development as of June 1, 2012)

Hosting Varnish

Allows the Varnish cache for Aegir-managed sites to be purged via the user interface. (In alpha as of June 1,2012)

Hosting CivicCRM Cron

This module provides the ability to trigger CiviCRM cron jobs on sites hosted on the Aegir Hosting System.

Hosting tasks extra

This module extends Aegir hostmaster (and drush/provision) with some additional tasks. Such as: cache-clear and registry-rebuild.

Hosting Filemanager

This module provides a web file browser for viewing files under sites and platforms. (In beta as of August 29,2012)

Hosting Signup Settings

This module is dependent on hosting_signup module in the hosting package of Aegir. It allows the Signup form at /hosting/signup to be configured. (Sandbox project, October 22, 2012)

Hosting Client Roles

Client Roles module integrates Aegir user roles into hosting_products as product feature. With this module you can assign Aegir user roles to Ubercart products, and sell them as hosting products. This module is part of the "Hosting & Ubercart Integration" package, and depends on uc_hosting and uc_hosting_products modules

Hosting Solr

Works with Provision Solr to give Aegir the ability to manage Solr servers and and gives sites a Solr database.

3. Extensions to Provision (backend)

Provision boost support

the Aegir project and therefore depends on the provision backend and expects the Aegir environment to be functional. Quickstart Download the provision_boost code into your /var/aegir/.drush/ Download ...

Provision ACL support

This drush command aims to provide preliminary ACL support for the Aegir backend . The objective here is to allow administrators to set more granular access policies on files managed by Aegir and resolve more hairy access permissions requirements than what is usually allowed by the Aegir core. ...

Project Status

Project status is an extension for drush which takes a list of drupal platforms as arguments and returns a list of modules which are not in use by any site within these platforms. It is also optionally able to list modules which are use, by platform and site.

Provision CiviCRM

A Drush module to automatically setup Drupal instances with the CiviCRM Constituent Relationship Management solution. It is specifically aimed towards the Aegir project.

Provision Backup Platform

This hooks into deleting a platform and creates a simple tar backup.

kPlatforms

Koumbit's "standard Drupal platforms", a set of makefiles to build and maintain development and production platforms easily.

Provision Git

Provision Git is a backend Drush module. It provides 4 drush commands. (In alpha as of June 1,2012)

Provision Merge Log

This Aegir extension allows you to automate fetching and merging logs from multiple servers part of the same cluster in a single logfile for later analysis with various analysis tools

Provision CDN

This is a simple module and drush script for that allows you to enable CDN support per site in Aegir. (In development as of June 1,2012)

Provision profile settings

Incredibly simple extension for provision that allows install profiles to easily inject settings into settings.php for provisioned sites.

Provision New Relic

This is a simple extension that exposes all sites in New Relic, so you can monitor each sites performance.

Provision Solr

Works with Hosting Solr to give Aegir the ability to manage Solr servers and and gives sites a Solr database.

4. Themes

• Koumbit has provided it's custom Aegir theme as a sample subtheme of Eldir.
• Saeven, a clone of the core theme Seven, based on Omega 4 or 5, clean, simple and responsive.

5. Puppet modules and Chef cookbooks

Those projects allow you to manage Aegir instance(s) through Puppet. Chef recipes also welcome, we don't discriminate.

• Aegir Puppet module
• Drush Puppet module
• Aegir Chef cookbook

6. Others

Aegir up

Aegir-up is a Drush extension that deploys a local instance of the Aegir Hosting System atop Vagrant and Virtualbox, for development and testing purposes.

DevShop

DevShop is a Drupal Development Environment Manager built on Aegir.

DevShop creates Aegir platforms and sites automatically from Git URLs. It tracks multiple Projects and allows multiple environments to be created for each Project, such as dev, test, and live. It provides tools to Pull Code, Sync Data, Commit Features, and Run Tests on these environments, and provides a dashboard with useful links and information for developers.

7. Your module here?

Developers: Please add your contributed module here, and feel free to put install instructions or other documentation in a child page. If you are looking for ways of extending Aegir or have already done so and want to document the internals of your module, head over to the extending Aegir page.

Aegir Services integrates the Services API framework into the Hostmaster suite of tools. It allows Aegir managers the ability to build Services API connections over any of the available servers for Services API.

Using Services 3.x we are aiming at full CRUD support for clients, tasks and sites, as well as read access to profiles, platforms, and eventually, packages.

The 2.x branch of Aegir Ubercart Integration will take advantage of this support to provide a remote storefront functionality.

Please report issues and request support via the issue queue on Drupal.org

Installation

1. Install Aegir
2. Install the dev version of services 3.x, including at least one server and, ideally, an authentication server.
3. Install this module.
4. Configure your endpoint, it's resources and authentication, normally.
5. Optionally, test your rest server using the included bash script, hosting_services.rest_test.sh

1. Extensions to Hostmaster (frontend)

Hosting Git

This is a simple module for the Aegir project that adds a 'Git pull', 'Git checkout' and 'Git clone' task for sites.

The successor of Hosting site Git & Hosting platform Git

Hosting Logs

This is a simple module for the Aegir project that adds a 'Logs' tab to sites and platforms. Showing Apache error, Git commit and watchdog logs.

Hosting Platform Pathauto

This is an add-on module for the Aegir hosting system: http://aegirproject.org/ This module simply makes a little time-saving tweak when creating a new platform: ...

Hosting site make

Allows a site to have its modules built from a makefile in the sites directory.

Hosting tasks extra

This module extends Aegir hostmaster (and drush/provision) with some additional tasks. Such as: cache-clear and registry-rebuild.

Now also includes the functionality from Aegir HTTP basic authentication

2. Extensions to Provision (backend)

Starting from Aegir 7.x-3.x the Drush component can be included in a 'drush' directory in the same git repository as the hosting module.

Therefore this list will be shorter then for previous versions.

Provision STS

Adds the Strict Transport Security header to hosts that require SSL.

3. Themes

• Saeven
• Eldir. (The default theme)

4. Puppet modules and Chef cookbooks

Those projects allow you to manage Aegir instance(s) through Puppet. Chef recipes also welcome, we don't discriminate.

• Aegir Puppet module
• Drush Puppet module
• Aegir3 Chef Cookbook

5. Others

Aegir up

Aegir-up is a Drush extension that deploys a local instance of the Aegir Hosting System atop Vagrant and Virtualbox, for development and testing purposes.

DevShop

DevShop is a Drupal Development Environment Manager built on Aegir.

DevShop creates Aegir platforms and sites automatically from Git URLs. It tracks multiple Projects and allows multiple environments to be created for each Project, such as dev, test, and live. It provides tools to Pull Code, Sync Data, Commit Features, and Run Tests on these environments, and provides a dashboard with useful links and information for developers.

Aegir Pathologic Files

A tiny Drupal Module to simplify file paths in content. This helps prevent broken images when the site directory name changes. Requires an apache rewrite rule to point /files to /sites/example.com/files, which Aegir provides by default.

This module is not for hostmaster, but for the sites hosted under Aegir.

6. Your module here?

Developers: Please add your contributed module here, and feel free to put install instructions or other documentation in a child page. If you are looking for ways of extending Aegir or have already done so and want to document the internals of your module, head over to the extending Aegir page.

Homepage: http://drupal.org/project/devshop

DevShop Provision

Drupal development infrastructure made easy.

This module provides the backend commands needed to deploy and manage sites using the DevShop git and features based development workflow.

About DevShop

The goals of DevShop are...

1. to simplify management of multiple environments for multiple Drupal projects.
2. to provide web-based tools that streamline the Drupal site building workflow.
3. to provide a common, open-source infrastructure for Drupal development shops.

Installation

To install devshop_provision, simply use drush:

$ drush dl devshop_provision

Or, you can download the source code to any available drush commands folder, such as /usr/share/drush or ~/.drush

Usage

DevShop Provision works by providing a new Provision class called "Project".

To start, you must have a Project drush alias. Using the DevShop+Hostmaster system will make this much easier, but if you wish to only use the backend, you can create a project alias with provision-save, for project NAME:

Commands

DevShop contains a set of features that make Drupal site building within a version-controlled code workflow quick and easy.

Currently you must create new platforms within a project in hostmaster. Once created, you can execute the following commands:

1. Pull Code

This task runs on the dev platform for this project. It runs git pull, and optionally runs new updates, reverts features, and clears caches. It is used to keep the dev server up to date on every commit via the devshop_pull module, and can be used as the deployment task.

• Git Pull the code for your site's platform.
• Then, all optionally:
  • Run update.php.
  • Revert all Features modules
  • Clear caches

2. Commit Features

This task integrates with Features.module to make it very easy to commit your changes to your features.

• Calls drush features-update-all
• Commits the result, with a part automated and part customized commit message.
• (Optionally) pushes the commits.
• (Optionally) force-reverts after a commit.

3. Sync Content

This task makes it easy to syncronize the database and files down from other environments within the project.

WARNING: This will DESTROY the destination site's database!

This task:

• (optionally) Pulls code
• Drops the @destination database.
• Creates an SQL dump from @source.
• Copies the SQL dump to the local system (if @source is a remote).
• Imports the SQL dump into @destination database.
• (optionally) Runs update.php.
• (optionally) Runs features-revert-all.
• (optionally) Clears all caches.

$ drush --filter=devshop_provision

$ drush provision-devshop-commit --help

$ drush provision-devshop-pull --help

$ drush provision-devshop-sync --help

$ drush provision-devshop-test --help

This page documents the Provision ACL extension to Aegir which allows more granular access control over your sites files and directories.

1. Install instructions

First, you'll need a running Aegir install (1.0-rc3 or later), see http://community.aegirproject.org/installing. Most (if not all) of these commands will have to be run as root (or using sudo, etc.)

1.1. Download and install provision

drush dl provisionacl-6.x

1.2. Enable ACLs on your filesystem

mount -o remount,acl /

Here we assume everything is under the root (/) filesystem here, otherwise run this command for every filesystem Aegir will work on (e.g. /srv, /var or /home).

You also need to edit your /etc/fstab for this configuration to survive reboots.

1.3. Install ACL support package

apt-get install acl

1.4. Create a UNIX group

In this case we choose a group called "devs" but you can choose another name.

groupadd devs

1.5. Add users to the group

Add one or more UNIX users that you want to give access to that group. For an existing user (socrates32), this would look like:

usermod -a -G devs socrates32

For a new user (ergonlogic), this would look like:

useradd -G devs ergonlogic

1.6. Create a client

Create a client (should be called "devs" for this example) in the frontend at /node/add/client.

1.7. Create a site

Create a site for the client in the frontend at /node/add/site.

2. What it does

When the site is installed, members of the "devs" group will be able to write to the sites' directories (e.g. upload files and modules) and run drush commands on the site (yes, including site aliases, although see caveats below).

This works also for existing sites; make sure you create a group matching the internal name of the existing client and reverify the site.

3. LDAP integration

Provisionacl supports LDAP groups as well. Ensure that an LDAP client is running and that the 'aegir' user can see the LDAP-provided groups:

getent groups

You may need to restart the Name Service Cache Daemon (nscd):

/etc/init.d/nscd restart

4. API - how to add ACL support to your Aegir extension

To change ACLs on files, you should use something like this:

if (function_exists('provisionacl_set_acl')) {
    provisionacl_files_acls(d()->site_path . '/mysettings.php');
}

You can optionnally pass a group as an argument, but it will guess that from the client name of the site. Also note that this will raise a drush error if setfacl fails, but just set a warning if the group doesn't exist.

5. Caveats (ie. what it does not)

Giving shell access to users in Aegir is still insecure, see this upstream issue: #762138.

We aim to refactor this into the Aegir core in 2.x, but in the meantime this should provide a good workaround for the limitations of the existing permission system.

This will only work in 1.0 and above, as it needs the "client_name" field to be populated.

You will need to change your $HOME variable for aliases to work, because of this bug in drush: #1104438. Example:

See also this post for context and design.

6. Debugging

If for some reason you have lost the ACLs on the directories and you need to restore them, use the following commands, which is basically what the module does:

7. Notes

This page is the reference documentation for the Provision ACL module page on Drupal.org - keep this in mind when editing please.

This module provides several features to ubercart products on an Aegir platform.

Requirements

• Hostmaster 6.x-1.0 or higher
• Ubercart 6.x-2.4 or higher
• Patience

Installation

1. Download the module and its dependencies into sites/all/modules on your hostmaster platform (drush @hostmaster dl uc_hosting ubercart should work)
2. Activate the clients feature for hostmaster (admin/hosting/features)
3. Enable the module uc_hosting_products. This should enable all dependencies (drush @hostmaster en uc_hosting_products)

Creating your first site product

N.B. A video introduction covering configuration is available from the DrupalCon London session Aegir-based Business Models (starting at 26:30).

1. Create a product. Make sure it is not shippable. (node/add/product)
2. Edit the product. Go to the features tab.
3. Choose the "Create a site and adjust quotas accordingly" feature. It should use the sku of your product automatically.
4. For single-site products, make sure, on the product feature form, to check off "Force clients to create their site on purchase" if you want to be sure people create their site.
5. Now all you need is a drupal platform that any user can create sites on and you are ready to go. (node/add/platform)

Creating more complex offerings using product kits

The method we recommend for creating complex offerings, including multiple site quotas and access to restricted platforms, is via Ubercart product kits.

1. Enable uc_product_kit.
2. Create one or more uc_hosting products.
3. Create a product kit with these products in them in the appropriate quantities.

Support

You can report bugs, request support and propose patches via our issue queue on Drupal.org.

Development

If you would like to use uc_hosting to develop your own Aegir dependant product features, be sure to read the relevant documentation.

Check out the roadmap.

Other Resources

• Aegir community site
• Ubercart Documentation
• #aegir IRC channel on freenode

provision_civicrm helps to manage the installation and upgrades of CiviCRM in Drupal sites managed with Aegir.

CiviCRM is not a typical Drupal module. It is a third-party system that integrates with Drupal, WordPress and Joomla for its front-end and permission system. CiviCRM has its own installer, upgrade system and cron. The "provision_civicrm" module helps to manage any CiviCRM+Drupal site as any other Drupal site managed in Aegir.

Requirements

• Aegir 2.x or 3.x
• hosting_civicrm must be installed in the hostmaster front-end (~/hostmaster-x-y/sites/example.org/modules).

Installation

Download the provision_civicrm module as the "aegir" user:

drush dl provision_civicrm-6.x-2.x

This should install the module in ~/.drush/provision_civicrm.

NB: provision_civicrm 6.x-2.x is a Drush module, and works with both Aegir 2 and Aegir 3. However, for Aegir 3, you must use the 7.x-3.x branch of the hosting_civicrm module.

Creating a CiviCRM platform

provision_civicrm assumes that if you have a CiviCRM installation in your sites/all/modules/civicrm, then this is a CiviCRM platform and CiviCRM should be installed automatically.

(A cleaner way, in theory, would be to have an install profile and let the user configure it through the front-end, patches welcome! -- however, you do not want any site to simply enable CiviCRM from the Drupal admin/build/modules, so having dedicated platforms for CiviCRM makes sense in any case.)

A sample drush makefile is provided with provision_civicrm.

Assuming you are running as the user 'aegir', whose $HOME is /var/aegir/, save this in a file such as ~/makefiles/drupal-6.22-civicrm-3.3.4.make

Then create the new platform:

mkdir ~/platforms/drupal-6.22-civicrm-3.3.4
cd ~/platforms/drupal-6.22-civicrm-3.3.4
drush make ~/makefiles/drupal-6.22-civicrm-3.3.4.make

You can now add your platform in the Aegir front-end and then create new sites.

Sometimes you will need to administer your server beyond what you can do as the Aegir user.

Examples include installing additional software or editing PHP configuration.

It's not recommended to use the root user for administering things as it can be easy to make mistakes that could break your system.

Instead of running as root, it is recommended to create a user for yourself that has sudo privileges.

Create a user with SUDO privileges

In ubuntu/debian systems, creating a user and giving them the ability to run commands with sudo is easy with the adduser command.

Think of a username and password for yourself, then run the following commands as root:

root@aegir:~# adduser bob
Adding user `bob' ...
Adding new group `bob' (1001) ...
Adding new user `bob' (1001) with group `bob' ...
Creating home directory `/home/bob' ...
Copying files from `/etc/skel' ...
Enter new UNIX password: 
Retype new UNIX password: 
passwd: password updated successfully
Changing the user information for bob
Enter the new value, or press ENTER for the default
    Full Name []: Bob
    Room Number []: 
    Work Phone []: 
    Home Phone []: 
    Other []: 
Is the information correct? [Y/n] y
root@aegir:~#

Then add them to the "sudo" user group:

root@aegir:~# adduser bob sudo
Adding user `bob' to group `sudo' ...
Adding user bob to group sudo
Done.
root@aegir:~# 

Then you can switch to the "bob" user using sudo su, or login via ssh with your password.

root@aegir:~# sudo su - bob
bob@aegir:~$

These notes describe a possible way of installing Apache with fastcgi using php5-fpm. The below configuration works but is experimental.

On a Ubuntu 12.04 box:

Install Aegir2 from Debian packages

Follow http://community.aegirproject.org/installing/debian. Below is a shortened form.

Add the Aegir package "Software Source" repository:

Install aegir2:

If the installation fails, it might be that your FQDN is not set or your postfix is not configured.

Verify your aegir site is working

Navigate your browser to the FQDN of your aegir server. You need to see the "Welcome to Aegir" page.

Modify the configuration to use fastcgi / php5-fpm

Edit /etc/apt/sources.list and enable the multiverse repository (it's needed for the libapache2-mod-fastcgi package).

Then install php5-fpm and make apache use it:

Modify /etc/php5/fpm/pool.d/www.conf Make it listen on socket, instead of IP:

Create /etc/apache2/conf.d/php-fpm.conf with this content:

Enable apache modules:

Restart php5-fpm and apache to load the new configs:

Verify that you can still reach your Aegir site

Navigate your browser to the FQDN of your aegir server. This time, you are using php5-fpm. Verify e.g. via phpinfo().

--
Page author: Marji Cermak marji@morpht.com, http://morpht.com

While building (and re-building) platforms using makefiles and the Aegir front-end (node/add/platform) is great, it has a number of minor annoyances. They're slow, and consume lots of bandwidth, but worse still, even a small hiccup in drupal.org (or other) infrastructure can break a platform build, which requires starting from scratch each time.

When you maintain platforms with upwards of 300 modules, themes and libraries, such as with kPlatforms, and you start to deploy these to multiple clients' Aegir servers, those minor annoyances can become significant challenges.

There is good documentation on setting this up for use with Drush Make already, such as this blog post. However, there are some gotchas when doing so in Aegir. Most of the suggested solutions involve something like setting environment variables in ~/.bashrc, which works fine if you're running 'drush make' yourself in a login shell. However, since the Aegir is running in a non-interactive shell, there isn't a opportunity to set environment variables.

Thankfully, Drush Make supports curl, and opts for it automatically if it's installed. Careful reading of curl's manpage indicates that:

[curl] always [...] checks for a default config file and uses it if found.

So, in the end, all that's required is a /var/aegir/.curlrc file containing:

proxy = "http://<proxy_host>[:port]"

Thus a basic configuration on Debian would involve installing a proxy, such as Squid:

# apt-get install squid3

Then add an acl in /etc/squid3/squid.conf allowing access from your local network, e.g.:

acl localnet src 192.168.0.0/16
http_access allow localnet

Restart Squid and you're good to go:

# /etc/init.d/squid3 restart

Testing that Aegir is actually using your new proxy cache, and that Squid is actually caching the makefile projects involves taking a quick look at the logs of the Squid server:

# tail -f /var/log/squid3

1. Introduction

Upgrading Aegir is designed to be as easy as it possibly can be, and regularly improves over time as the developers attempt to streamline the process for users.

Nonetheless, the upgrade process can seem a little daunting to users. This is mainly because some expectation arises that because Aegir is built on Drupal, and is made for managing Drupal sites, it seems reasonable to expect the upgrade process to be as straightforward as, say, upgrading a regular Drupal site.

Aegir is a powerful system that goes beyond a normal Drupal application by being split into two parts: a frontend (the browser-based control panel) and the backend (bits on the system in /var/aegir, such as Drush and Drush extensions), along with a system user on your server that runs command-line scripts and restarts services, and cronjobs.

Typically what this means is that when it comes time to upgrade Aegir, you not only have to upgrade the frontend site, but also update the components that reside in the 'backend'.

But don't panic! We have instructions and even a script to run, to take care of almost all of it for you, eliminating as much as possible the chance for human error.

2. Upgrade options

There are three options you can choose to upgrade your Aegir install when a new release comes up:

• Upgrades using Debian packages
• Upgrades using the upgrade.sh.txt script
• Manual upgrades

3. New release of Drupal core?

Just as you would use the Migrate task in Aegir to upgrade one of your sites to a new copy of Drupal core, you can follow the UPGRADE.txt to upgrade your actual Aegir frontend system to a new copy of Drupal core too. The upgrade process (including the script) will always fetch the latest available copy of Drupal core to place the frontend on.

Currently you cannot upgrade the Aegir site itself from the frontend with a Migrate task as you do for your managed sites. This may change in the future, but has not been developed yet.

This section outlines the requirements for doing a manual upgrade of Aegir to a new release. Before going ahead with this, you probably want to read the upgrade path and version-specific notes.

1. Conventions & Tips

All instructions and in general all commands must be run as aegir user, so all permissions are always set correctly.

To become aegir user you can issue this command:

su -s /bin/sh aegir

(Note you must run this as root or prefix with sudo).

Note that /bin/sh is an example. You may wish to instead use the shell of your choice, i.e /bin/bash

A standard umask of 022 is assumed. This is the default on most systems.

We assume that drush is in your path, if it is installed in /var/aegir/drush/drush.php, replace all occurences of drush by /var/aegir/drush/drush.php in the following steps, or add the following alias:

alias drush=/var/aegir/drush/drush.php

2. Upgrading Overview

2.1. Upgrading drush

As part of your Aegir upgrade, you need to upgrade Drush to the latest stable version compatible with the target Aegir release. AEgir 1.x only works with version 4.5. Versions 5 - 7 have been known to work with AEgir 2.x, however the Drush developers recommend version 6 as the most stable.

2.2. Upgrading the backend

After drush is updated, you must then proceed to upgrade the backend. The reason for upgrading the backend first before the frontend, is that the frontend upgrade process is instigated by the backend using Drush Make. Thus you need to be running the new backend first in order to successfully produce a new frontend.

In general, we try to keep the backend and the frontend compatible with each other during release cycles. That is: provision 1.8 and hosting 1.9 will always be able to talk to each other, but hosting 2.0 will have trouble talking to the 1.9 backend, so you need to upgrade the backend first when you do a major upgrade (for example, 1.9 -> 2.0).

Bottomline: first you upgrade the backend, then the frontend.

2.3. Upgrading the frontend

Once your backend is upgraded, you can upgrade your frontend. Think of this as the backend fetching a new copy of Drupal core and the Hostmaster frontend application onto your server, and then moving the Aegir site's settings.php and other bits and pieces over to the new codebase.

2.4. What hostmaster-migrate does

The command will make sure the target directory is a valid Aegir install. If the directory does not exist, provision will use drush_make to fetch and assemble the correct version of the front end for the specific release of the backend you are running.

hostmaster-migrate will also completely replace the crontab entry for the aegir user.

The command above will fetch the latest stable Drupal release, so it can simply be run again when a new security release of Drupal is made available.

3. Upgrading to AEgir 1.x

3.1. Upgrading drush and drush make

As part of your Aegir upgrade, you need to upgrade Drush to the latest stable version compatible with the target Aegir release. Aegir 1.x does not support Drush 5, although 2.x does.

If you are using the Drush Debian packages, the package should be upgraded through:

apt-get install drush

Otherwise, since drush 4.x is capable of upgrading itself, you can just run:

drush dl drush-7.x-4.5

If you are running a version before 4.x, use the following set of commands instead:

pear channel-discover pear.drush.org
pear install drush/drush-4.5.0

Provision 0.4 has added a new dependency on drush_make, which will also need to be installed to upgrade the front end if you are upgrading from a pre-0.4 release.

If you are upgrading from an earlier 0.4 release, replace your copy of drush_make with the latest recommended release.

drush dl drush_make-6.x --destination="$HOME/.drush"

3.2. Upgrading the 1.x backend

Upgrading the backend is as simple as replacing your copy of Drush, Provision, and if necessary, Drush Make, with the new versions if available. Keep a copy of the old Provision and Drush in case something goes wrong in the frontend.

drush dl provision-6.x --destination=$HOME/.drush

3.3. Upgrading the 1.x frontend

Before upgrading, we set a few key variables to make the process easier. You must replace the arguments those variables to match your configuration. This means replacing $AEGIR_DOMAIN by the URL of your Aegir install, $AEGIR_VERSION with the version number of the Aegir you are trying to install, and also $OLD_AEGIR_DIR with the path to the previous directory where Aegir was installed.

The directory passed to hostmaster-migrate must be an absolute path to where you want the new release to be stored.

OLD_AEGIR_DIR=/var/aegir/hostmaster-6.x-1.8
AEGIR_VERSION=6.x-1.11
AEGIR_DOMAIN=aegir.example.com

To upgrade your frontend, run the following commands, replacing the variables as described below:

cd $OLD_AEGIR_DIR
drush hostmaster-migrate $AEGIR_DOMAIN $HOME/hostmaster-$AEGIR_VERSION

3.4. Special configurations and troubleshooting

If the upgrade fails, try running it again with the --debug flag:

cd $OLD_AEGIR_DIR
drush hostmaster-migrate aegir.example.com $HOME/hostmaster-$AEGIR_VERSION --debug

If you have customized your Aegir installation and are maintaining your own makefile, you can use the --makefile flag so the platform is created with another makefile than the default. Be warned that this may create problems if the makefile doesn't include the right Aegir modules.

4. Upgrading to AEgir 2.x

4.1. Upgrading drush

Install Drush 6.x per the directions given at the Drush repository. The maintainers have deprecated the PEAR installation procedure and are encouraging everyone to install Drush via the Composer dependency management tool.

You should also remove your copy of drush_make from $HOME/.drush.

4.2. Upgrading the 2.x backend

Upgrading the backend is as simple as replacing your copy of Drush & Provision with the new versions if available. Keep a copy of the old Provision and Drush in case something goes wrong in the frontend.

drush dl --destination=/var/aegir/.drush provision-6.x-2.0

Drush 5+ has a commandfile cache which you need to clear before installing Aegir:

drush cache-clear drush

4.3. Upgrading the 2.x frontend

Before upgrading, we set a few key variables to make the process easier. You must replace the arguments those variables to match your configuration. This means replacing $AEGIR_DOMAIN by the URL of your Aegir install, $AEGIR_VERSION with the version number of the Aegir you are trying to install, and also $OLD_AEGIR_DIR with the path to the previous directory where Aegir was installed.

The directory passed to hostmaster-migrate must be an absolute path to where you want the new release to be stored.

OLD_AEGIR_DIR=/var/aegir/hostmaster-6.x-1.11
AEGIR_VERSION=6.x-2.0
AEGIR_DOMAIN=aegir.example.com

To upgrade your frontend, run the following commands, replacing the variables as described below:

cd $OLD_AEGIR_DIR
drush hostmaster-migrate $AEGIR_DOMAIN $HOME/hostmaster-$AEGIR_VERSION

4.4. Special configurations and troubleshooting

Read the upgrade path notes again, you will have missed something.

If the upgrade fails, try running it again with the --debug flag:

cd $OLD_AEGIR_DIR
drush hostmaster-migrate aegir.example.com $HOME/hostmaster-$AEGIR_VERSION --debug

If you have customized your Aegir installation and are maintaining your own makefile, you can use the --makefile flag so the platform is created with another makefile than the default. Be warned that this may create problems if the makefile doesn't include the right Aegir modules.

If the update fails due to a bug in module Hosting, it will ask you to run "drush hostmaster-resume help". That command does not exist. Try this one instead.

drush --debug @hostmaster hostmaster-resume /var/aegir/hostmaster-6.x-1.11 /var/aegir/hostmaster-6.x-2.0

1. Regular update process

Make sure you have the Aegir repository in your sources.list, as per the installation docs.

If you are upgrading from a Debian installation whereby you used the koumbit.org repositories, you should change this entry in your sources.list to be debian.aegirproject.org as per the instructions linked to above, and run apt-get update to refresh.

If you want to upgrade all packages in one shot, use:

apt-get update
apt-get install aegir

Note that you can upgrade Aegir in steps. Upgrading your backend to the Debian package should be as simple as running:

apt-get install aegir-provision

Upgrading the frontend to the Debian package works identically:

apt-get install aegir-hostmaster

As during install, you can use the DEBUG variable to run Drush in debugging mode:

env DEBUG=yes apt-get install aegir-hostmaster

Note: the DEBUG flag is deprecated. In 1.x releases, it is accepted, but in 2.x it won't. You should use DPKG_DEBUG instead, it is usable starting from 1.1-4.

2.x note: to upgrade to 2.x, use: apt-get install aegir2.

Note on contrib modules: some Aegir-specific contrib modules may have been installed on your Aegir deployment. This may fail if you are doing a major upgrade. In this case, you will probably want to disable those contrib modules. Look for directories in ~aegir/.drush or /usr/share/drush/commands or other components of the drush commandfiles search path, and move them out of the way. After the upgrade, download the new versions of the modules that are compatible with the new Aegir release.

2. Upgrading from non-Debian installs

The Debian package supports migrating from existing installs. You will need to move /var/aegir/.drush/provision out of the way before going ahead:

tar cfz /var/aegir/backups/provision.tgz /var/aegir/.drush/provision
rm -rf /var/aegir/.drush/provision

You'll also need to go through steps 1 through 3 of Automatic install on Debian.

Then just install the package as if you were installing from scratch.

3. Custom distributions

If you have your own makefile, you can go ahead with the above process, but change the makefile to the one you want:

echo debconf aegir/makefile string /var/aegir/makefiles/aegir/aegir-koumbit.make | debconf-set-selections
apt-get install aegir

Usually no questions are asked when upgrading - this allows you to specify the makefile path for your custom distribution of Aegir, even if you're upgrading. It's also how you can switch distributions.

An example aegir-koumbit.make file could look like:

Note that for this to work, you will need the patch from this issue, allowing drush_make to reference absolute system paths.

3.1. Keeping custom distributions up to date

This section describes how to upgrade the code for custom distributions in between debian package upgrades. Here, we assume that Aegir is already installed through the debian package.

1. Create a new Aegir makefile, or update the custom Aegir makefile. (You can use the makefile in drupal.org/project/provision as a starting point.)
2. Add modules/features/themes/libraries/whatever to the makefile. Ex:
       projects[] = token
    projects[] = views
3. Follow the manual upgrade path:
   • drush @hostmaster hostmaster-migrate URL /path/to/platform --makefile='/path/to/makefile'
   • Hope it's all green (no errors). If errors, fix makefile.
   • A new platform should exist, the new site should be in there, verifying. If the task is not running, check that hosting-queue-runner is running. If it's not, restart it using '/etc/init.d/hosting-queue-runner force-reload'. (Since hostmaster changed location, it is normal for hosting-queue-runner to crash at this point.)
   • When the debian package is upgraded, it should create a new hostmaster platform automatically. (You can test this with dpkg --configure.)

4. Rolling back the upgrade

If something went wrong with the upgrade, you can rollback by deleting the hostmaster site and redeploying on the older platform:

drush @hostmaster provision-delete
vi ~/.drush/hostmaster.alias.drushrc.php

...And edit the alias to make the following changes:

1. change the platform to point to the older platform alias
2. change the platform root path
3. change the site path

During the upgrade, a backup was done and you need to find which backup file it was in the backups directory. Use this backup to redeploy the older platform:

drush @hostmaster provision-deploy ~/backups/hostmaster.date.tgz

5. Recovering a Failed Upgrade

When using the Regular Update Process and you encounter an error it leaves the debian package in a broken state.

First you need to figure out why it failed. For example is there a permission problem?
Once you determined the issue correct it and clean up the environment. It could be necessary to remove the new hostmaster platform. It is up to you to determine what state aegir is in.

Next you need to fix the broken package by running the fix-broken parameter:

apt-get install -f 

This tells the debian package system to start through the process again.

This page describes the upgrade script in the Provision repository that tries to automate much of the upgrade process.

NOTE: At this time neither the Aegir 1.1 nor the Aegir 2.0 upgrade scripts are working for all setups. We recommend you use the Manual upgrades instead.

It is imperative that you read the version-specific upgrade notes before attempting to run the upgrade.sh script, as the script will assume you have your system set up appropriately to handle the upgrade process.

You can download the upgrade.sh script for Aegir 2.4 with the following command:

wget -O upgrade.sh 'http://drupalcode.org/project/provision.git/blob_plain/refs/tags/6.x-2.4:/upgrade.sh.txt'

or for AEgir 3.0 with the following command:

wget -O upgrade.sh 'http://drupalcode.org/project/provision.git/blob_plain/refs/tags/7.x-3.0:/upgrade.sh.txt'

Make sure you download it to somewhere that the aegir user can access in order to execute it.

You may need to edit the script to set any variables that are different from the defaults, for example to upgrade to a different Aegir version.

To do the upgrade, just run the script:

su -s /bin/sh aegir -c "sh upgrade.sh"

1. General upgrade path recommendations

In general, you shouldn't skip major releases. That is, if you are running 0.3, you should upgrade to 1.0 or 1.1, not 2.0. Upgrades within a stable branch (1.0 to 1.1, 2.0 to 2.1) are fully supported, and you can skip minor versions (1.0 to 1.2 should work fine), but you should always upgrade to the latest stable release if you are coming from a different release branch.

The rest of this page documents what version-specific changes happened that you need to make manual modifications to. If you are running the Debian packages, you probably don't need to configure anything here.

The upgrade process should make this clear, but keep in mind that you need to upgrade the backend (drush, provision) before the frontend (drupal, hostmaster profile, etc).

Provision/Drush contrib modules might require additional attention. As there is no version checking, the safest method is probably to move the module out of your .drush folder and later add the version compatible with the new Aegir version.

Hosting/Drupal contrib modules should also be handled carefully. If these were installed into the hostmaster site's directory, then they should be moved automatically to the new hostmaster platform during the upgrade. On the other hand, if they were installed on the platform, you'll need to provide the hostmaster-migrate or Debian package with a custom makefile. The default makefile in Provision (aegir.make) can be used as a model for this.

2. Changes in the 2.0 release

2.1. hosting-queue-runner renamed hosting-queued

The popular module hosting-queue-runner has been merged in the 2.0 release. In the process, it has been renamed to the more appropriate hosting-queued. The init script is also now installed directly with the Debian package, and started on install or upgrade.

You will, however, need to manually enable to module for the daemon to work (still):

drush @hostmaster en hosting_queued

Also, if you are migrating from an install using hosting-queue-runner, you will need to remove the old module and startup script. Enabling hosting-queued will already have disabled and uninstalled the module from Drupal, but you need to cleanup your filesystem:

rm /etc/init.d/hosting-queue-runner

2.2. queue daemon enabled by default

The above queue daemon is now enabled by default by the Debian package, and is properly restarted on upgrades. It can be disabled after install if necessary using the following comamnds:

service hosting-queued stop
su aegir -c "drush @hostmaster pm-disable hosting_queued"

2.3. hosting_platform_pathauto module bundled with Aegir

The popular module hosting_platform_pathauto has been bundled in the 2.0 release. If you installed it module manually then now is probably the time to remove your copy. Aegir 2.0-alpha1 comes bundled with hosting_platform_pathauto-2.0-beta1.

2.4. hosting-task --force

You used to be able to run hosting-task <nid> to re-run a task by its node ID. Because hosting-task now checks if the task is really queued, this can't be used to retry existing tasks directly, unless you use the --force argument. So this:

becomes:

2.5. Deprecated functions removed

If you are using any of those functions in your custom code, lookup in the 1.x documentation to see the replacement functions, as they have been removed from 2.x:

• hosting_alias_count_sites() (same as !hosting_alias_allow_domain())
• hosting_site_exists() (same as !hosting_alias_allow_domain())
• hosting_get_client_by_email() (use hosting_get_client() instead)
• hosting_import_client() dropped the second argument (organization)
• hosting_task_list_embedded() (use hosting_task_list() or hosting_task_list_table())

2.6. New Provision class naming convention

Provision classes used to start with provisionConfig_ or provisionService_, but these are now Provision_Config_ and Provision_Service_ respectively.

2.7. Client node type changes

• the email field was removed from the client, now you need a user associated with the client. this was already the case in 1.x but the existing field wasn't touched.
• the client_email field was removed from the site object

2.8. SSL and IP allocation refactoring changes

The SSL IP allocation refactoring has changed a good few things in the API and the way SSL certificates are managed.

2.8.1. Backend

The following functions are gone from the backend:

• provisionService_http_ssl::assign_certificate_ip
• Provision_Service_http_ssl::get_ip_certificate .
• Provision_Service_http_ssl::free_certificate_ip
• Provision_Service_http_ssl::clear_certs()

Certificates are not tracked from the backend anymore, other than to make sure that we delete a certificate when it's not used anymore. So we still use *.receipt files, but just to mark a site to SSL certificate association, not the IP allocation. The SSL directory in ~/config/server_foo/ssl.d/uri/ is removed when no site use that directory anymore.

The backend now expects the frontend to send an ip_address field and stopped sending a site_ip_addresses to the frontend.

2.8.2. Frontend

The hosting_ip_addresses table changes. A unique key has been added and it is now only for servers. It is used by the new hosting_ssl_cert_ips table to map those server IP addresses to certificates.

A new field for the IP (ip_address) is sent from the frontend during site install/verify tasks. The field is not present in non-ssl sites. It is the non-resolved IP address of the server assigned to the SSL certificate and must be used by the backend to write the vhost.

SSL certificates are removed from the frontend when sites using it are deleted.

2.9. Debian package name changed

To allow both packages to coexist in the same Debian archive, the name of the packages of the 2.x series have changed.

• aegir -> aegir2
• aegir-provision -> aegir2-provision
• aegir-hostmaster -> aegir2-hostmaster
• aegir-cluster-slave -> aegir2-cluster-slave

2.10. Platform drushrc.php moved

From Drush 5 documentation:

Drush 5 no longer looks for aliases, configs or command files in the Drupal
root folder, so if you previously used drushrc.php files in the Drupal root
you will need to move the file to sites/all/drush/drushrc.php.

Since Aegir 2 requires Drush 5 (or later), Provision now follows this standard, and places a platform's drushrc.php in sites/all/drush/drushrc.php.

2.11. Class auto-loading

Provision has been refactored to use class autoloading. This simplifies use of classes, as it obviates the need to explicitly include the files in which the class and it's parent classes are defined. In addition, it standardizes the placement of class definitions within a hierarchical file-system structure and will make name-spacing simpler if/when we begin to adopt Symfony components.

More info in the manual under Extending Aegir - Class auto-loading

This may also affect certain contrib extensions that used to have to reside in the provision directory itself. These extensions should probably be removed prior to the upgrade, and re-installed afterwards with an Aegir2-compatible version.

2.12. Other database changes

The release_id column was dropped. This column wasn't used anywhere in the code and was present only in some installs, see issue #1882708 for details.

3. Changes in the 1.0 release

3.1. Git dependency

If you intend on upgrading your system to the bleeding edge version of the code from our git repositories, you will need the git program installed. On Debian, this means:

apt-get install git-core

3.2. DNS Configuration

Aegir requires that the hostname returned by the hostname and uname -n shell commands, resolves to the IP address for this server.

Shell commands as root:

AEGIR_HOST=`uname -n`
resolveip $AEGIR_HOST

If the command returns your IP address, you are all set. If it returns an error you will need to edit your /etc/hosts file.

(Mac OSX notes: if you are running on OS X you will not likely have a resolveip binary. Just substitute ping $AEGIR_HOST ).

First line of this file looks like:

127.0.0.1 localhost

Simply add all domains you want to this line. e.g:

127.0.0.1 localhost $AEGIR_HOST $AEGIR_DOMAIN other1 other2

To be clear you cannot put $AEGIR_HOST $AEGIR_DOMAIN in your hosts file. Put in whatever uname -n returns for $AEGIR_HOST and what ever domain you want to use f or $AEGIR_DOMAIN (real domain or faked in hosts file). In OS X uname -n will return whatever you put in System Preferences -> Sharing -> Computer Name. I added that value (iMac 27 for me) to /etc/hosts and my faked aegir domain as follows:

127.0.0.1  localhost  iMac27  aegir.local

If you only intend to use Aegir on a single server, it is acceptable for the resolved IP address to be the '127.0.0.1' loopback address.

If you intend to manage multiple servers using Aegir, you will need to make sure that the IP address is the public IP of this server.

Finally, set an $AEGIR_IP environment variable for use in the Database configuration step below.

Shell commands as root:: AEGIR_IP=resolveip $AEGIR_HOST | awk {'print $6'}

(If running OS X or are otherwise missing resolveip and you just want to use Aegir on your computer use you can do this: AEGIR_IP=127.0.0.1

3.3. Unzip dependency

As of the 0.4-alpha3 release, 'unzip' is a required dependency on your server in order to successfully extract the jquery.ui library that is part of some UI improvements. On Debian, this means:

Shell commands::

apt-get install unzip

3.4. Database configuration

To make sure that the Aegir backend, and all the possible web servers can reach your database server, you need to configure mysql to listen on all the public IP addresses available to it.

/etc/mysql/my.cnf configuration line to comment out:: bind-address = 127.0.0.1

Now you need to restart mysql, to clear any caches.

Shell command as root:: /etc/init.d/mysql restart

Because you have already installed Aegir when it was using the generic grants, you will need to create new grants using the public IP address and hostname of this server.

Shell command :: mysql -uroot -p mysql

You need to generate the following grants using the hostname returned by the uname -n command, and the IP address that the resolveip command returns for that hostname.

You need to re-use the pasword you had for the account before.

Shell commands::

mysql -u root -p -e "GRANT ALL ON *.* to 'aegir_root'@'$AEGIR_HOST' IDENTIFIED BY 'xxxx' WITH GRANT OPTION;"
mysql -u root -p -e "GRANT ALL ON *.* to 'aegir_root'@'$AEGIR_IP' IDENTIFIED BY 'xxxx' WITH GRANT OPTION;"

3.5. Apache configuration

This release introduces multi-server support and required reorganizing the Apache configuration files in ~aegir/config. Instead of having all files in config/vhost.d, they are now split between vhost.d, platform.d and a single apache.conf. The vhost.d directory is for virtual hosts, platform.d is for platform-specific configuration and apache.conf is the server-wide configuration file.

You will need to change the line you added to either the httpd.conf file or /etc/apache2/conf.d/aegir file during installation.

Open your httpd.conf file and modify::

Include /var/aegir/config/vhost.d

To read ::

Include /var/aegir/config/apache.conf

If you are upgrading from 0.4 releases between alpha8 and (including) alpha14, you will need to rename your conf.d directory to post.d in Apache and pre.d in Nginx. Example, in Apache::

mv /var/aegir/config/server_master/apache/{conf.d,post.d}

Now log into Aegir, and verify the hostmaster platform. This will generate the correct apache.conf file and restart Apache.

There is no formal method for uninstalling Aegir, but there is also no real mystery either since the system tries to keep itself together in one location, typically /var/aegir.

Below are the steps to completely remove all traces of Aegir from your server. We also include to leave Aegir intact, but destroy its data, attempting to reset to a almost post-install setup.

Ideally, you would delete all sites and all platforms from the system first. That would take care of deleting all databases and users. But this can take some time and is annoying, so we provide instructions on how to destroy everything.

WARNING

Obviously if you have any sites and platforms currently managed by Aegir, you would want to move them out of the /var/aegir area before you delete it! Ensure you have set up your sites and platforms elsewhere, with Apache vhost files etc in their typical locations, or at least out of harm's way before attempting this.

WARNING: Performing these steps will remove Aegir from your server and may result in loss of data. Use with caution.

Run these commands as a privileged user (such as root). We assume your Aegir installation resides in /var/aegir.

Backup

You probably want to backup everything before trashing it.

Backup all you need to keep from the /var/aegir/ directory.

Backup your database server, we'll be also destroying that.

Uninstall script

Aegir 2.x comes with a hostmaster-uninstall script that allows you to automate good chunks of the steps below.

Destroying the data

Aegir manages three types of data:

• configuration files - yes, we consider those as data
• site and platform files
• site databases

Trashing configuration files

This step is optional if you are going to remove everything anyways.

rm /var/aegir/.drush/*alias.drushrc.php
rm -r /var/aegir/config/*

Trashing site and platform files

At this point, you could still probably recover by verifying the platforms, which would recreate config files. At this point we start really destroying data.

rm -r /var/aegir/platforms/*
rm -r /var/aegir/hostmaster-*

Drop the databases and db users

There are no generic instructions for this, since every system differs. Essentially you can perform this within a MySQL shell

mysql -u root -p

Use the DROP DATABASE $databasename; syntax to drop databases. and DROP USER $user; to delete users, example:

DROP DATABASE aegirexamplecom;
DROP USER aegirexamplecom@localhost;

This removes the Aegir user, assuming you have not created any site. If you did, you may want to cleanup those sites if you are going to delete them anyways. To see a list of GRANTs that Aegir has made for your database users, you can use a command like the following:

In Debian, the following will remove all non-system users (which may include non-aegir users!!!).

WARNING: DO NOT RUN THIS BEFORE CHECKING WHAT WILL BE DELETE BY RUNNING THE SELECT ABOVE!! THIS WILL DELETE ALL USERS FROM YOUR MYSQL DATABASE!!!

Then you will need to DROP DATABASE for every database.

Consult the GRANT and DROP documentation from MySQL for more information.

Remove the aegir user's crontab

crontab -r -u aegir

Removing everything

At this point, we have removed all data that Aegir manages and we would be ready to reinstall the frontend. If we want to remove all traces, however, there's more work to do.

Remove /var/aegir

rm -rf /var/aegir

Delete the aegir user

userdel aegir

This will also remove the user from the www-data group.

Remove the user from sudoers

visudo

Remove the line that looks something like

aegir ALL=NOPASSWD: /usr/sbin/apache2ctl

Save and exit the file.

Delete the symlink/include from Apache

Depending on your installation and OS this may vary.

Generally:

rm /etc/apache2/conf.d/aegir.conf

If your Include statements were contained in a global system httpd.conf file or similar, you will need to remove these lines manually.

Restart Apache when you have completed this.

You may occasionally want to take a Drupal site hosted on a server managed with Aegir and put it somewhere else. This is pretty easy, but not quite as simple as moving a normal Drupal site not managed by Aegir from one machine to another. In brief, you have to copy the site, delete the drushrc.php file, and replace settings.php with a copy of the default configuration file. More specifically:

• download the same copy of drupal core to the new server (and re-apply core patches, if any)
• copy sites/all/ to the new server
• copy the Aegir backup of your site to the new server and unzip in sites/yoursite.com/
• create a database on the new server & import the database backup
• copy sites/community.aegirproject.org/default.settings.php to sites/yoursite.com/settings.php
• D7: copy custom site aliases in sites/sites.php (if any) to the new server
• D6: replicate site alias symlinks in sites/ (if any) on the new server
• copy custom configuration in local.settings.php (if any) to settings.php
• edit settings.php to add the database authentication details for the new server

That's it!

Aegir is a complex system that depends on a number of components being properly integrated. This can obviously lead to difficulties on occasion. However, fear not! In all likelihood, any problem you can get yourself into has probably already been solved, and documented in this section. Just one of the benefits of using a popular open source system ;)

It is possible a task may run longer than expected and you suspect something has gone wrong. It is even possible the task may cause a server to become unresponsive. Restarting the server will not stop the task, although it may make the server become responsive again.

To stop a Task, find the related task node (install: mysite.com) in the content list: /admin/content/node/overview, and delete it. This will stop Aegir from trying to run the task.

In the case of a site install, it may also be necessary to also delete the node for the site itself. The site may have actually installed properly. Verify the affected platform and see if Aegir imports the site. If so, you may need to reset the password to gain access to the new site. If the site doesn't import in the verify, delete any files from the sites folder on the selected platform and either try again and/or research why the task may have failed.

It can also be very helpful to try running tasks from the command line with drush (the entire Aegir web frontend is basically a user-friendly interface to a series of drush commands). You can see which command is being run by looking at a task node in Aegir. For example, if you are having problems verifying a site, you could run:
drush @mysite.com provision-verify --debug

Another option is to run the hosting task itself within the hostmaster context, which will then invoke the drush command on the applicable site. You can find the task node ID in the web frontend (look at the URL generated by Aegir to create the popup box which shows the log). If the task ID was 1234, you would then run this from the command line:
drush @hostmaster hosting-task 1234 --debug

Installation and configuration of Aegir has been greatly simplified with the release of .deb packages. However, for other operating systems, or for those installing manually, making a mistake during the installation or upgrade of Aegir or Drush is easy to do, and these tips identify some of the most common mistakes.

The Aegir User

• Make sure you have an aegir user (who we call the Aegir User) and that the Aegir User is properly configured on your server:
  • cat /etc/passwd prints all users. Find the line aegir:x:1000:1000:,,,:/var/aegir:/bin/bash. aegir usually is the Aegir User. Be cautious about using a different username, and do notuse an existing user or a user that will have any other role on the server. The Aegir User should only be used for Aegir activities.
  • Verify the Aegir install directory is the user's home. Usually, the Aegir directory is /var/aegir. Be cautious about installing Aegir in a different directory only because you are likely to get confused and nearly all the documentation assumes you have used /var/aegir
  • Make sure that the node that defines your Aegir server (e.g., www.example.com/node/2) identifies the Script User as your Aegir User. (You can find this node by clicking on the Servers menu tab and then clicking on the server URI shown in the list that appears of Aegir servers.)
  • All this is detailed in the install profile wizard
• Do not run aegir as root! - It's an unsafe and unsupported configuration that is known to cause problems

Make Sure drush Is Installed Properly

• Make sure that the node that defines your Aegir Server has the correct path to drush.
  • See /var/aegir/drush/readme.txt for install instructions
• Check your Drush setup:
  • Always run drush as your aegir user, and never as "root".
  • Make sure that the Provision module is in the aegir/.drush/provision/ directory.
  • Make sure that the Hosting module is in ~aegir/hostmaster-0.x/profiles/hostmaster/modules/hosting (substitute the platform hostmaster-0.x to match the directory on your system in which you have installed the Drupal code that is running your Aegir site)
  • Run "drush help" and make sure that "provision" commands appear. "hosting" commands will not appear in the latest (after 2009/05/18) Drush versions, unless Drupal can be fully bootstrapped

Apache

• Make sure the Aegir User can restart Apache without a password and that the corresponding command is defined in your Aegir Server Node
  • As your Aegir User, run the command shown in the "Restart command" field in your Aegir Server Node to ensure that your Aegir User can restart Apache
  • On Ubuntu, it's sudo /usr/sbin/apache2ctl graceful. The command should execute and return without asking for a password when run as the Aegir User
• Make sure Apache can parse its configuration
  • On Ubuntu, sudo apache2ctl configtest should report "System Ok"

Other Things

• On a Linux system, check that /etc/sudoers is chmod 440 (i.e., read only for the file owner and group, which is usually root)
• Attempt to run the cron tasks manually from the command line
  • php /var/aegir/drush/drush.php --root=/var/aegir/hostmaster-0.x --uri=http://youraegirsite.com hosting-tasks --debug
• Or you can retry a specific task form the command line
  • php /var/aegir/drush/drush.php --root='/var/aegir/hostmaster-0.4-alpha5' --uri='youraegirsite.net' hosting-task <nid of the task> --debug

Aegir 2.x returns the following error message

strict warning: Non-static method view::load() should not be called statically in /var/aegir/hostmaster-6.x-2.1/profiles/hostmaster/modules/views/views.module on line 1113.

Cause

It's due to a conflict between Views 3.x and PHP 5.4. For example, your server uses PHP 5.4 or more recent. And you updated Drupal core for Aegir to Drupal 6.34 or more recent and this error message is showing on all Aegir pages.

Solutions

Option 1: Install "disable_messages" module. And disable all messages related to:

strict .*.

Read more here, under "How to hide only specific error messages to specific users" section.

Option 2: Patch Views 3.x. Read more at https://www.drupal.org/node/780156 or https://www.drupal.org/node/893128#comment-4760978

Option 3: Turn off Strict warnings in your "php.ini" file. Read more at https://www.drupal.org/node/1833170#comment-6994142 or https://www.drupal.org/node/465332#comment-6533810