Version-specific & upgrade path information

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:

drush @hostmaster hosting-task 1234

becomes:

drush @hostmaster hosting-task --force 1234

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:

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.