community.aegirproject.org

Version-specific & upgrade path information

Updated by anarcat on 10/09/2013 - 09:04
AddedChangedDeleted

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.

Back to top

2. Changes in the 2.0 release

Back to top

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
rm -r /var/aegir/platforms/hostmaster-6.x-1.*/sites/all/modules/hosting_queue_runner

The location of the hosting_queue_runner package may vary, according to your local policies. You can find the module path with this drush call:

drush @hostmaster sqlq 'SELECT filename FROM system WHERE name = "hosting_queue_runner";'
Back to top

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"
Back to top

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.

Back to top

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

Back to top

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())
Back to top

2.6. 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
Back to top

2.7. 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.

Back to top

2.7.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.

Back to top

2.7.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.

Back to top

2.8. 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 -> aegir-provision2
  • aegir-hostmaster -> aegir-hostmaster2
  • aegir-cluster-slave -> aegir-cluster-slave2
Back to top

2.9. 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, Provision now follows this standard, and places a platform's drushrc.php in sites/all/drush/drushrc.php.

Back to top

2.10. 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 contributed modules, it is highly encouraged. If you maintain a contributed Provision extension, some re-factoring will be required to support class auto-loading.

First off, you'll need to add a registration function that will enable Provision to autoload your extensions classes. Here's an example from provision_civicrm:

/**
* Register our directory as a place to find Provision classes.
*
* This allows Provision to autoload our classes, so that we don't need to
* specifically include the manual under class.
Extending Aegir - Class auto-loading

Back to top

2.11. 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.

Back to top

3. Changes in the 1.0 release

Back to top

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
Back to top

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

Back to top

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

Back to top

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;"
Back to top

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.

Back to top
tgroff's picture
tgroff
11:17pm Jan 14, 2014

#1

Hi, I'm running the Aegir packages on Ubuntu 12.04.4 LTS. Aegir 1.11 has been working just fine, but the upgrade to 2.x fails with errors. First some database errors, then later dpkg errors, how can I further diagnose and resolve this installation failure?

I just did a simple apt upgrade and apt offered to uninstall the old aegir package and install the new aegir2 package just fine:

root@development ~ # apt-get install aegir2
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following extra packages will be installed:
  aegir2-hostmaster aegir2-provision drush
Suggested packages:
  drupal7
The following packages will be REMOVED:
  aegir aegir-hostmaster aegir-provision drush-make
The following NEW packages will be installed:
  aegir2 aegir2-hostmaster aegir2-provision
The following packages will be upgraded:
  drush
1 upgraded, 3 newly installed, 4 to remove and 0 not upgraded.
Need to get 426 kB of archives.
After this operation, 29.7 kB of additional disk space will be used.
Do you want to continue [Y/n]?

First some IP address database updates show errors:

UPDATE {hosting_ip_addresses} SET id=177 WHERE nid=3006 AND          [error]
ip_address=&#039;192.168.2.31&#039;
UPDATE {hosting_ip_addresses} SET id=178 WHERE nid=2 AND             [error]
ip_address=&#039;192.168.2.31&#039;
UPDATE {hosting_ip_addresses} SET id=179 WHERE nid=3012 AND          [error]
ip_address=&#039;192.168.2.31&#039;
UPDATE {hosting_ip_addresses} SET id=180 WHERE nid=3014 AND          [error]
ip_address=&#039;192.168.2.31&#039;
UPDATE {hosting_ip_addresses} SET id=181 WHERE nid=3017 AND          [error]
ip_address=&#039;192.168.2.31&#039;
UPDATE {hosting_ip_addresses} SET id=182 WHERE nid=3021 AND          [error]
ip_address=&#039;192.168.2.31&#039;
UPDATE {hosting_ip_addresses} SET id=183 WHERE nid=3030 AND          [error]
ip_address=&#039;15.185.167.45&#039;
UPDATE {hosting_ip_addresses} SET id=184 WHERE nid=3034 AND          [error]
ip_address=&#039;162.243.42.5&#039;
UPDATE {hosting_ip_addresses} SET id=185 WHERE nid=3085 AND          [error]
Then dkpg fails:

Changed permissions of /var/aegir/.drush/hostmaster.alias.drushrc.php[success]
to 640
Generated config Drush configuration file                            [success]
Changed permissions of /var/aegir/.drush/hostmaster.alias.drushrc.php[success]
to 440
Changed permissions of                                               [success]
/var/aegir/hostmaster-6.x-1.10/sites/aegir.groffweb.dev/settings.php
to 640
Generated config Drupal settings.php file                            [success]
Changed permissions of                                               [success]
/var/aegir/hostmaster-6.x-1.10/sites/aegir.groffweb.dev/settings.php
to 440
Change group ownership of                                            [success]
/var/aegir/hostmaster-6.x-1.10/sites/aegir.groffweb.dev/settings.php
to www-data
Platforms path /var/aegir/platforms exists.                          [success]
Platforms ownership of /var/aegir/platforms has been changed to      [success]
aegir.
Platforms permissions of /var/aegir/platforms have been changed to   [success]
755.
Platforms path /var/aegir/platforms is writable.                     [success]
Removed unused migration site package                                [success]
Generated config encrypted virtual host configuration                [success]
Generated config encrypted virtual host configuration                [success]
dpkg: error processing aegir2-hostmaster (--configure):
subprocess installed post-installation script returned error exit status 1
E: Sub-process /usr/bin/dpkg returned an error code (1)