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.