Introduction to Aegir

If you are new to Aegir you may have heard great things about the project but not know about many of the benefits of using it. Here are some - feel free to add to this list.


One of the great architectural features of Drupal is that you can have multiple web sites that share a common platform of modules, themes and other code used to manage content and appearance. If you make a change to the platform (e.g. update a module, change a theme etc.) all sites based on the platform are immediately updated. At the same time, each site has its own database and file system that can be tailored to the specific needs of the site. In addition to the concept of platforms, Drupal lets you create installation profiles. A platform can have one or more profiles which allows you create different sites based on your choice of platform and profile.

Multiple Site Installations

Aegir provides a web interface to define a platform and then create multiple sites based on that platform. Aegir creates the site database, site-specific file folders and the web server files that point browser requests to the right place.

Site Management

Through the Aegir interface you can create backups, restore a specific backup, disable or delete individual sites. Thus Aegir is a very helpful way of tracking and managing lots of sites spread over several platforms. Moreover, you can perform bulk tasks on all sites based on a particular platform.

Site Development

When you are building a platform from scratch or simply extending or upgrading an existing platform, Aegir can significantly speed up development time and minimize impacts to sites in production.

With Aegir you can clone a site to the same or a different platform. So, say you have a number of sites running on a Platform A and you decide to upgrade a platform module but you want to test your sites to make sure they are compatible with the upgrade. Using Aegir you would create another platform, Platform B that is identical except for the module upgrade. Then you can use clone to create a copy of one of your sites from Platform A to Platform B. The database and all your files are copied by Aegir and you can then test your cloned site without worrying that you might impact the existing production site.

Once you are satisfied that your cloned site is working properly you can then migrate one or all of your sites from Platform A to Platform B.

This process can be very useful for building out new platforms, troubleshooting issues etc.

Site Aliasing

Through the Aegir interface you can define aliases for your web sites so that, for example, traffic to and is directed to the same site.

Multiple Servers

The Aegir interface can also be used to manage platforms and web sites on different web servers, which gives you latitude to tailor a hosting architecture to your own needs.

Scheduled Tasks (Cron)

Most Drupal sites rely on recurring scheduled tasks also known as cron jobs to perform operations like checking for updates, cleaning up log files etc. Aegir can be configured to run cron jobs for hosted sites on regular intervals without having to utilitize other tools or configure cron jobs manually on a site-by-site basis.

Operating system support

Aegir is primarily developed on Debian GNU/Linux, but it supports a whole slew of other platforms, Debian packages have been available for that platform for a while and the install instructions have been originally written primarily for Debian.

This page documents Aegir support for various operating system, including specifics on how it is best recommended to install Aegir on those platforms, quirks and problems, packaging issues and coordination.

1. Debian support

1.1. Fully supported

Aegir is fully supported in Debian, with multiple reports of successful installations, both manual and automatic installs and upgrades.

1.2. Packaging complete

Debian packaging is currently done in Koumbit's private repositories, as documented in the install instructions.

Drush is also fully supported in Debian, with regularly Debian packages in unstable, Wheezy, and Squeeze-backports.

Drush make doesn't yet have a Debian package.

To building Debian packages, follow those instructions.

2. Ubuntu support

2.1. Well supported

Because none of the core developpers actually run Ubuntu daily, it is less well supported. But because Ubuntu is actually based on Debian, lots of people are happily running Aegir on Ubuntu without problems.

2.2. Packaging almost complete

Through the Debian packages, packaging is almost complete. The key piece missing is Drush in Ubuntu Maverick and previous versions. See this bug report for more information.

(Ubuntu synced Drush 4.4 in Natty Narwhal 11.04, which should be released by the end of april, but we're still looking for a Ubuntu MOTU to handle the backporting on the Ubuntu side of things.)

There are unofficial install scripts also available for Ubuntu:

3. Arch Linux

3.1. Well supported

Some people definitely run Aegir in Arch Linux, as the manual install process documentation has extensive details of the Arch Linux specific steps.

3.2. No packaging

Unfortunately, no package is available for this platform.

4. CentOS and Redhat-descendants

4.1. Well supported

A few people are running Aegir on RedHat and related operating systems, mostly CentOS. There are a few tricks documented in the manual install process but it's still fairly straightward to install.

4.2. No packaging

Unfortunately, no package is available for this platform, we are looking for volunteers to write a spec file to create RPMs.

5. Gentoo

5.1. Supported

We believe that Aegir works on Gentoo right now, according to this post. Follow the manual install instructions.

5.2. No packaging

No packages are provided on this platform.

6. Mac OS X

6.1. Partially supported

OS X can be difficult for web developers, because it doesn't ship with a good Apache/PHP/MySQL stack and the UNIX internals are a bit awkward. Still, Aegir was originally developed on OS X, so it's perfectly possible to use Aegir on OS X.

6.2. No packaging

There are currently no packages for OS X and none planned. Special instructions are provided for installing on OS X but once it's installed, the usage should be similar to other platforms, including for upgrades.

7. Solaris

7.1. Supported

There are at least two Solaris installs out there, and significant work was done to make sure that Aegir was UNIX-agnostic enough to respect Solaris' idiosyncracies. The manual install instructions include some of those exceptions clearly documented and outline. Because the upgrade can be iffy, it is recommended to upgrade using the full manual install process.

7.2. No packaging

No packages are provided on this platform.

8. FreeBSD

8.1. Supported

We had one report of Aegir being installable on FreeBSD. The pre-requesites have not yet been merged into the main install instructions (see #659024 for followup on that), so you'll need a bit of guesswork.

8.2. No packaging

No packages are provided on this platform, but it should be fairly simple to make a port inspired by the Debian packaging, considering how it currently works.

9. Other platforms

Other platforms are probably supported but those have not been explicitly and clearly documented so they are not yet included here. Feel free to edit this page to add a section for those users!

Project goals



This project is developed using Git. People are free to download the source code for the project (and in fact are required to run it). Git access is available here.

After many discussions with many different developers working in this space, it has become apparent to the developers that many people have developed their own custom set of utilities and scripts to manage many of the issues this project encompasses.

This project aims to be an open framework that will allow us to collaborate on a single set of community developed / maintained utilities, so that the quality and the capabilities will improve for all of us.


This functions on both a developer and a user level.

For the user, the intent is to make the system as simple to install and operate as possible, which means drastically lowering the requirements for installing and getting up and running with the system. To that end the system has an installation script to automate the installation of Aegir, which has developed a long way from a multi-step install.php wizard and even more complex requirements before then.

The system will auto-detect as many of the settings it requires to run as is possible from within the confines of PHP, and will provide detailed and accurate inline documentation on the server configuration required, based on the configured settings.

This system aims to be self documenting, to aid in troubleshooting, in the event that an error occurs. This documentation is both translatable and extendable when new services are enabled.

For developers we aim to keep the implementation simple, clear and concise, and use as few as possible additional requirements outside of Drupal itself. We aim to provide extensive developer documentation, to lower the barrier for people wanting to integrate with the system.

The system will never require any additional core patches for the sake of base functionality. It is a 'contrib' project.

Basically, the aim is to do everything possible to ensure that the user and developer experience is a positive one.


The system aims to help maintain many sites, not just when they are initially installed, but over the entire lifetime of the site.

It is designed to install new sites, provisioning all the required services (such as Apache, Mysql and DNS), with the flexibility to provision additional services (such as Mail, LDAP etc.) through optional contributed modules or features.

It provides the ability to revert back to previous versions of your sites, as well as re-deploy existing sites under different domain names ( copied to These backups will be usable on any system with the provisioning backend installed (such as a developer's machine, or a staging server).

This aspect of the system will also be used to manage upgrades between multiple versions of Drupal, and will allow you to schedule upgrades. It will do its utmost to ensure that your site has been successfully upgraded, and features dependency tracking to keep track of which sites are eligible to be upgraded.

It will provide a mechanism that ensures the cron process is run on all your sites within the specified time frame, and additionally will allow for scheduled backups of all your sites.

Through optional modules it will be able to extract usage statistics from your hosted sites and provide an overview of site usage through the administration interface, it will also be able to keep track of server health and load for each of the configured servers.

These are the stated feature goals, many of these features will not be available in the initial releases, as they are not considered a base requirement.


The system will make sure that it has the least amount of power available to it to accomplish it's task, and will ensure that all file permissions are set to the strictest possible levels they need to be, and that no sensitive information is web accessible.

None of the functionality or code required to accomplish it's tasks will ever be available in the provisioned sites, and the hosting front end itself will make extensive usage of Drupal's access control requirements to ensure that users will not have access to things they are not meant to see.

to be extended


The system functions entirely on the command line, using unix pipes for inter-process communication.

As such, once ssh has been configured for the user the back end script is running as, it will be able to freely communicate with the external server through the only mechanism it knows how (the command line).

As an extension of the backup/restore functionality, you will be able to seamlessly move sites between servers, while providing a redirect to an always accessible site alias for users who have cached dns entries.

You will also be able to change database servers through simply modifying the site record on the user frontend.

to be extended


The system will provide accurate and complete logs of everything that has occurred on the system, as well as feature complete error reporting and notification of all issues that have occurred. It will first verify that it is able to complete the requested task, and then it will verify that the task has been completed successfully, before completing the task.

When an error occurs, it will rollback to its last working state before exiting, so that failures will not negatively affect sites.

All node types in the front end are revision controlled, to allow for complete history of all objects.

to be extended


This system aims to be as flexible as Drupal itself is.

It will provide a complete and useful set of hooks to module developers, for both the front end and the back end, to accomplish whatever tasks they need.

The administration interface will provide complete views support for all data in the site, to allow for custom reporting on your network.

The core node types are all standard Drupal nodes, that can be extended through CCK by the implementor. This could be used for tracking additional client information or additional information on sites.

You will be able to integrate Drupal contributed modules such as Organic Groups or Ecommerce/Ubercart to build support or billing functionality directly into the hosting front end.

The system is completely white boxed, so that it will work with almost any Drupal theme, and as such can have your own corporate identity.

to be extended

Project history

Aegir is a completely new iteration of the original Hostmaster project written by Adrian Rossouw. The original version has been running the hosted service provided at for nearly 4 years, hosting literally thousands of sites, and has been implemented for several large clients. Originally, the system would only manage a single Drupal instance, on a single web server with a single database server, and as the requirements grew (concurrently running multiple versions of Drupal and then needing to manage several servers), it grew considerably in (unplanned) complexity.

There were also non-ideal implementation and licensing issues, such as the choice of Python and PostgreSQL for the backend and not developing the system as an "invite-only" GPL project, which severely limited the number of developers that were attracted to the project. Because of the system requirements, it was also very difficult for new users to install, and had many unnecessary points of failure.

The Aegir hosting system has been designed with all these issues in mind, and the lessons learned have formed the basis of many of the Aegir Project Goals. The code was committed to in november 2007 and has seen multiple production-ready but still "alpha" releases there in the two following years.

  • 0.1 marked the first Drupal 5 and "multi-site" capable version.
  • 0.2 marked the first multi-platform version, which supported upgrades between different Drupal versions
  • 0.3 marked the port of the frontend to Drupal 6

Then in 2009, a major overhaul of the code was performed to provide "multi-server" support, which led to numerous 0.4-alpha releases (about 20) and, around the end of 2009, required the move to git as a version control system even though was still stuck in CVS-land, which meant started hosting the git repositories on their servers.

All this led to, about a year and a half later (early 2011), to the 1.0 release of our beloved platform and the Aegir project migrating back to at last

Aegir now exceeds the capabilities of the original HostMaster system and is in use by numerous real world projects.

Aegir is now supported by, Computer Minds and mig5 and is being used to deploy sites in universities, private companies and non-profits around the world.

On January 8, 2014 the 2.0 release ships with significant stability improvements, Drush 5 and 6 support, subdirectory multisite support, improved nginx support, native views and much, much more.


Table of Contents 
  1. 1. Help!
    1. 1.1. Where can I get help?
    2. 1.2. Can I ask you a question?
    3. 1.3. Who are the Aegir developers?
    4. 1.4. I'd like to help out / become a developer!
  2. 2. Installing Aegir
    1. 2.1. Can I run Aegir on a shared hosting environment?
    2. 2.2. Can I run Aegir on Windows?
    3. 2.3. Can Aegir be installed next to CPanel/Plesk/AlternC/etc?
    4. 2.4. Where can I get support for Barracuda/Octopus Aegir?
    5. 2.5. Do I really need to create an aegir user?
    6. 2.6. Install fails with 'dummy connection failed to fail' on Ubuntu 12.04 LTS!
    7. 2.7. How can I tell what version of Aegir I have installed?
    8. 2.8. After installing Aegir I have two servers listed, is this normal?
    9. 2.9. I followed the installation instructions. What directory holds all of my sites now?
    10. 2.10. I tried to create a site, but the create task failed and retries don't succeed. How do I delete the partially created site and associated Aegir tasks?
  3. 3. Upgrading Aegir
    1. 3.1. What is a patch or 'hotfix', and how can I apply it to fix my site if I can't / don't want to upgrade to HEAD?
    2. 3.2. I upgraded Aegir by mistake, can I downgrade it?
  4. 4. Using Aegir
    1. 4.1. Cron isn't running (scheduled tasks aren't being executed), what do I do?
    2. 4.2. How do I get debug/verbose info from Drush when running the hosting commands?
    3. 4.3. How do I update a site's or platform's modules using Aegir?
    4. 4.4. Is it best to set up sites under aegir as or just as
    5. 4.5. How can I setup a site to use https:// under Aegir?
    6. 4.6. Aegir is not verifying / deleting / migrating my site because of file permission problems.
    7. 4.7. I can verify a platform but Aegir fails to provision a site on it (often OpenAtrium)
    8. 4.8. A platform with an installation profile has verified okay, but Aegir doesn't seem to be able to use the profile
    9. 4.9. I tried to migrate a site, but Aegir incorrectly reported an incompatibility between one or more modules in my source and destination platforms. How do I force Aegir to see that the two platforms are compatible?
    10. 4.10. What about .htaccess settings?
    11. 4.11. I'm using a Git repo for a site, but symlinks make crazy things happen!
    12. 4.12. How can I tell what database name my site is using?
    13. 4.13. Can I use the subdirectory multisite feature of Drupal in Aegir?
    14. 4.14. My cache/performance settings in /admin/settings/performance keep resetting themselves!
    15. 4.15. I get [warn] NameVirtualHost *:80 has no VirtualHosts when I restart Apache
    16. 4.16. I get 'Dummy connection failed to fail' when doing $stuff
    17. 4.17. How do I make custom changes to a site's settings.php?
    18. 4.18. How to migrate site via drush

1. Help!

1.1. Where can I get help?

From the Aegir Handbook (which should be the first place you look) :

The Issue Queue for all the projects that make up Aegir is here:

This is the first place to look - chances are someone's had the same problem as you before, and you'll get the quickest answers by searching for what they discovered.

Before asking a question or reporting an issue, you should read the bug reporting guidelines.

You can join the #aegir channel at Freenode on IRC. (IRC instructions for drupal users are at: It's a friendly community, but a small one, so ask nicely and be patient!

If you find a solution to a problem that isn't in the documentation or in this FAQ, be the first to login and edit these pages to bring them up to date! The rest of the community thrives on your helpful information!

1.2. Can I ask you a question?

Of course you can! Don't ask to ask, just ask! It is polite to look if the question has already been answered in the documentation, the issue queue or here, but if not, please do ask around! If you ask a question and we have a nice answer, you can even add it to the FAQ here so that others can have your valuable answer.

1.3. Who are the Aegir developers?

The Aegir core developers are listed on the Aegir maintainers page.

1.4. I'd like to help out / become a developer!

We love people who want to help and get involved! We even made a page for you to read.

2. Installing Aegir

2.1. Can I run Aegir on a shared hosting environment?

Shared hosting will not give you enough permissions to install new sites. Toughen up, read some Linux beginners tutorials and buy a cheap VPS which will do nicely.

2.2. Can I run Aegir on Windows?

To install Aegir you need a unix based operating system (for details see: Aegir will not work on Windows and there are no plans to add support for it.

2.3. Can Aegir be installed next to CPanel/Plesk/AlternC/etc?

No, or rather "it's not supported". See

2.4. Where can I get support for Barracuda/Octopus Aegir?

Barracuda/Octopus are custom scripts for Aegir that install or set up various things that Aegir doesn't do out of the box. This is a custom solution tailored to Nginx systems, provided by and is not officially supported by the core Aegir project or team. For help or more information, please visit BOA Group, Barracuda and Octopus project pages / issue queue on

2.5. Do I really need to create an aegir user?

If you have a UNIX system, you already have a user. It just needs to not be root for safety reasons. But you don't really have to create a user.

2.6. Install fails with 'dummy connection failed to fail' on Ubuntu 12.04 LTS!

Ubuntu 12.04, by default, installs an insecure MySQL server configuration that allows anonymous users to login without a password. This must be rectified by running 'mysql_secure_installation' before attempting to apt-get install Aegir.

Please see this step in the Install Documentation and this other FAQ item.

2.7. How can I tell what version of Aegir I have installed?

This works for version 1.1 and above . . . maybe earlier too . . . .

grep '[hostmaster][download][tag]' /var/aegir/.drush/provision/aegir.make

Also, if you have drush installed someplace other than in /var/aegir/.drush, then you should grep the aegir.make file in the directory tree where you have drush installed. For example, on Ubuntu, apt-get may install drush in /usr/share/drush/. So, the file to be grep'd would be /usr/share/drush/commands/provision/aegir.make.

If you're still unsure or this didn't work, contact a developer on IRC and we'll be able to tell you after you answer a few questions.

2.8. After installing Aegir I have two servers listed, is this normal?

Yes. By default, after installing Aegir, a server node is created that represents your webserver. This also generates the 'server_master' Drush alias on your system. The second server node is called 'localhost' and has your database service attached to it, because by default MySQL listens on localhost and not your webserver's IP (or on all interfaces). This corresponds to the 'server_localhost' Drush alias on your system.

This is normally fine: you want your websites to be serve-able via your web server's IP / all interfaces, and your database server to only listen on localhost.

If you end up creating remote webservers, you'll not be able to have them use databases on this Aegir server is all.

If you know you want to have remote webservers communicate back to the Aegir server as the 'remote database server', you'll need to attach the database service type to the non-localhost server node, comment out bind-address in /etc/mysql/my.cnf and perform the necessary firewall changes to allow remote access to TCP port 3306 on the Aegir server.

But generally its recommended to create remote database servers too (or combine web + db on the one remote server), so this is generally a non-issue, rather than use the original Aegir server as a 'remote' database server for remote web servers.

2.9. I followed the installation instructions. What directory holds all of my sites now?

For a full overview of a typical Aegir filesystem structure, read this.

2.10. I tried to create a site, but the create task failed and retries don't succeed. How do I delete the partially created site and associated Aegir tasks?

See the section 'Manually deleting the site' from the documentation

3. Upgrading Aegir

3.1. What is a patch or 'hotfix', and how can I apply it to fix my site if I can't / don't want to upgrade to HEAD?

Sometimes releases are made and bugs are discovered afterward. We commit fixes for such bugs to HEAD, but HEAD is often volatile and you don't want to use a non-stable release in your environment. Fortunately we do (or should: if it's critical, please ask for a patch otherwise) provide a 'hotfix' or patch for users. A patch means that you can 'patch' your Aegir system to fix the bug without running the risks of using HEAD.

To patch an Aegir component, use the following example, in which we fix the Provision module with an imaginary patch. The same or similar steps apply for Hosting or Hostmaster (though you shouldn't need to patch Hostmaster, you only use it once to install!)

Run the steps as the aegir user.

1) Backup /var/aegir/.drush/provision to somewhere else for safety, such as /tmp/provision

2) Download the patch given in the ticket, to your server. Use wget or a similar useful tool for downloading it over the commandline. You can download the file to anywhere.

3) edit your aegir user's crontab (crontab -e) and comment out the dispatch entry (place a '#' in front of the hosting dispatch cron entry). This is a precautionary step in case you patch the module, something goes wrong and it breaks the module. The hosting dispatch cron might come around and try and run the queue dispatcher and break/complain due to a broken component. If you know what you are doing and are fast enough to fix it, you may skip this.

4) cd /var/aegir/.drush/provision/

5) patch -p0 < /path/to/the/patch/file

6) crontab -e and uncomment the dispatch cron task

If the patch doesn't apply or prompts you to enter the filename to patch, try running patch -p1 instead of -p0 above.

If it still asks for clarification, verify that you are in the top-level directory of the component (in this case, we are inside /var/aegir/.drush/provision)

If it still doesn't work, it might be an unclean patch, and you should make a request in the relevant ticket to be given a cleaner patch to apply.

For more information on patches, please read the Drupal documentation.

3.2. I upgraded Aegir by mistake, can I downgrade it?

Short answer: no, that would be crazy.

Long answer: well... maybe. Actually, yes. But it could destroy your house, your cat, your life insurance and certainly give you headaches. We will tell you anyways because we're nice.

This assumes you have a backup from before the upgrade. We will be deploying that backup, so understand that you will loose any changes done on the frontend since the upgrade was performed (or more precisely, since that backup was done). That's the way Drupal works, you can't downgrade Drupal, and we're just cheating by restoring a previous backup.

So first, delete that frontend site:

drush @hostmaster provision-delete

This is not absolutely mandatory, but you should make a backup, and deleting the site does that, plus it's important to cleanup after ourselves. We can use the backup to restore to that upgraded version if we give up on the downgrade.

Then remove the Debian packages (if you installed through those, if not, you're on your own: but you need to at least remove the provision code):

apt-get purge aegir2 aegir2-provision aegir2-hostmaster

This may also be:

apt-get purge aegir2 aegir-provision2 aegir-hostmaster2

Depending on the release candidate you installed.

Next, you install the old provision, but only that - don't go around installing the frontend just yet because you will have an empty site to overwrite.

apt-get install aegir-provision

Then you need to edit the @hostmaster alias to point to the old platform, which supposedly exists (if not, you're in trouble: create it by hand or something).

(Alternatively, you could install aegir-hostmaster, which would create you the alias, but this could fail exactly because the alias already exists. Just edit the alias already.)

So you need to change three parameters:

  'platform' => '@platform_hostmaster6x1x',
  'root' => '/var/aegir/hostmaster-6.x-1.x',
  'site_path' => '/var/aegir/hostmaster-6.x-1.x/sites/',

Then you can deploy your backup on that platform:

drush @hostmaster provision-deploy $PWD/backups/

From there the frontend should be back. Maybe. Probably. Well, the purge earlier may have killed the aegir.conf symlink, so if you want to test the frontend right now, restore that. Otherwise, be bold and upgrade to the latest 1.x release using the debian packages, which should restore everything you need:

apt-get install aegir

This should perform an upgrade from your older 1.x release to (for example here) 1.11.

If it doesn't work, sorry, i told you it could break. :)

4. Using Aegir

4.1. Cron isn't running (scheduled tasks aren't being executed), what do I do?

If you're using Aegir 2.x ensure the "Task queue" feature is activated. To do so go to /admin/hosting/queues check "Task queue". Click on "Save changes" button. With default settings the item(s) in the queue will be process in roughly 1 min.

Below are other options to resolve that issue

At the shell prompt as the aegir user, type

crontab -e

a) If you get an error that the command is not found, then you need to install cron on your server (some basic images don't include it - Linode's Ubuntu 9.04 image is one):

sudo apt-get install cron
Now go back to the directory /var/aegir/drupal-6.19 and re-execute the hosting dispatch:
/var/aegir/drush/drush.php @hostmaster hosting-setup
Type 'crontab -e' again.

b) You should see the default entry:

*/1 * * * * (php  '/<path to drush>/drush.php' @hostmaster hosting-dispatch

But if this is still not working it may well be a permissions issue. An example error :

Forking : (php /<path to drush>/drush.php  --quiet @hostmaster  'hosting' 'task' '266' --backend &) > /dev/null [0.432 sec]                [notice]
sh: /dev/null: Permission denied

This means the system doesn't have permissions to access /dev/null. To resolve it, give the system permissions to write to /dev/null (it should have this anyway), by executing:

sudo chmod a+w /dev/null

c) If this still hasn't worked, have you moved the location of drush? If so - see

d) If you are a *BSD user (verified on freebsd at least) You need to add the line : PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin at the TOP of your cron file. Simply log in as the aegir user and type crontab -e and insert the above line on top. Thanks goes to mauror for

e) When cron for your sites stops working, it is possible that for some reason (system overload, broken site, timeout etc), Aegir failed to release a sites cron semaphore. To release it, use this simple recipe:

$ su -s /bin/bash - aegir
$ cd /path/to/hostmaster/sites/domain
$ drush vdel hosting_queue_cron_running -y

4.2. How do I get debug/verbose info from Drush when running the hosting commands?

Add these to the drush call :


If you're having specific problems when using the frontend, you can easily run the hosting commands from the command line by:

  1. Click the view button and then copy the Drush command which was executed at the top of the log;
  2. While logged in as the aegir user, paste the command in at the terminal and replace --backend with --debug at the end of the commandline.

4.3. How do I update a site's or platform's modules using Aegir?

Aegir isn't a package management GUI for installing modules or themes on your site.

It's designed to help manage your site between builds. To upgrade sites, you should be using the Migrate tool to move your site between two platforms, which invokes drush updatedb.

If you aren't ready for this paradigm, and are frustrated that Aegir isn't some GUI for wildly updating or installing new modules with no regards for rollback or dealing with when it will inevitably break your site, Aegir is probably not for you.

4.4. Is it best to set up sites under aegir as or just as

Aegir supports either method and can even automatically create whichever one you didn't use as the main site name. Read more about Aliases and this feature in our documentation.

4.5. How can I setup a site to use https:// under Aegir?

Aegir ships with an experimental SSL feature, but currently doesn't provide any means of managing SSL certificates.

You can follow the ongoing SSL work here.

In the meantime, to set up SSL with basic self-signed certs, follow our documentation.

4.6. Aegir is not verifying / deleting / migrating my site because of file permission problems.

Aegir releases prior to 0.3 RC3 encountered an error when the web server has uploaded files and made new directory in the sites/$url/files directory. A prevalent example of this occurring is with the color module and when imagecache is used (such as in atrium).

This bug (see: #203204 ) was introduced with Drupal 6, and has since been fixed with Drupal 7. The patch has however not been backported yet, and the patch won't fix existing files that were created incorrectly.

In Aegir 0.3 RC3 we introduced a work around which sets the umask for the site, which forces new files and directories to be the correct permissions, but this will only take effect after the site has been succesfully verified. To enforce the correct file ownership and permissions on the files, run the following command on each of your Drupal 6 platforms :

  sudo chown -R $aegir_user $platform/sites/*/files

This will allow the verify task to correctly set the permissions and succesfully modify/remove the files.

4.7. I can verify a platform but Aegir fails to provision a site on it (often OpenAtrium)

A premature failure of a site install with an unhelpful message such as 'The external command could not be executed due to an application error' often, but not always, means your php-cli's memory_limit is set too low.

To confirm that this is an issue, try running drush provision-verify --debug from the command line to find out what caused the problem. Remember to replace '' with the URL of the site you are trying to verify.

Raise your memory_limit in your php cli php.ini file to something like 128MB, or maybe 64MB if that's too much. On Debian-based distributions this is /etc/php5/cli/php.ini. Apache does not need a restart for this: installations fail because the command is being executed via drush using php cli.

This is a common issue for OpenAtrium as it requires more memory to run its install profile as it has a lot more to do than a regular Drupal install.

4.8. A platform with an installation profile has verified okay, but Aegir doesn't seem to be able to use the profile

Your platform has been setup and verified okay, but when you go to create a new site Aegir keeps giving an error message about the profile, or the list doesn't offer you the profile you're expecting. This could be a namespace issue. Modules, themes and profiles in Drupal all have a machine name - which is essentially their folder name. This is also used to prefix their functions etc, so that there are no clashes. What isn't often recognised or well documented is that Drupal has a single namespace for all items - so your themes, modules and install profiles can't have the same name as each other. Often an installation profile will be created called 'OpenPotato' and the theme for it will also be called 'OpenPotato'. This makes Drupal unhappy, and when Drupal's unhappy Aegir's unhappy. We don't want that, but it isn't Aegir's fault, it's the developer's limited or lack of understanding of this Drupal caveat. The easiest thing is to name your installation profile directory 'OpenPotato_install' and name the profile file 'OpenPotato_install.profile'. You'll also need to rename the functions inside this file. Then everything should work just fine.

4.9. I tried to migrate a site, but Aegir incorrectly reported an incompatibility between one or more modules in my source and destination platforms. How do I force Aegir to see that the two platforms are compatible?

This problem can arise for at least two different reasons. First, you may have updated a module in a platform that you imported and forgotten to run update.php before you imported the site into Aegir. Second, you may have updated a module in a platform and not re-verified the platform in Aegir. Be sure that you have run update.php on a drupal platform that you will be importing into Aegir before you import. Also, if you make any change to the modules in an Aegir Platform, re-verify that platform and all sites using that platform. (At least, experience suggests that doing these things will allow the migration to succeed.

4.10. What about .htaccess settings?

As of recent 0.4 alpha releases, Aegir now reads in the contents of a platform's .htaccess file when generating the Apache configurations. You can safely make additions/changes to the platform .htaccess and expect the relevant site to respect those changes.

If you're symlinking an entire /sites/ folder, Aegir may not acknowledge the site, as this will cause problems when cloning/migrating a site.

If you are using Git to version control your themes, custom modules, etc, and symlinking these into your sites folder, you will find that cloning a site will clone those symlinks (by virtue of copying the sites folder). This is probably not what you want to happen!

Themes and custom modules are better off being checked out to or symlinked into the install profile folder. If your site's install profile is 'foobar' (there's an 'install_profile' variable in the variables table), Drupal core understands to look inside the /var/aegir/yourplatform/profiles/foobar/ folder for modules and themes directories.

The files directory for uploads (which I don't think can be efficiently versioned anyway in most cases) and the settings.php file will be all that's left in your sites folder, and Aegir will happily move that all around as you clone or migrate your site between platforms.

Storing your site's dir in git is an archaic and inefficient method of developing sites. It's 2010 and there are more elegant ways of doing things thanks to Drush Make and Aegir. You might like to look at mig5's excellent article where he provides some great tips on how to manage Drupal deployments & workflows with version control, drush_make, and Aegir.

4.12. How can I tell what database name my site is using?

Check the site's vhost configuration file in /var/aegir/config/server_$whatever/apache/vhost.d/. The db name (and user/password) are stored as 'SetEnv' parameters to Apache, allowing us to cloak database credentials in the settings.php so that they are protected in a multisite environment from prying eyes (admins with PHP filter permissions).

You can also use 'drush st' on your site to get a status report containing the database name, user, password, among other things.

In modern releases (0.4-alpha9 or so and above), the site database names have switched from site_$nid style names to more properly reflect the site name/URL itself.

4.13. Can I use the subdirectory multisite feature of Drupal in Aegir?

Also known as "" and "" are different sites.

Short answer: not yet - at least not natively. (see the 'aegir_subfolders' experimental extension)

Long answer: this is currently not supported, because multiple sites usually end up sharing the same virtual host entry in the webserver and you will be required to upgrade/migrate all of the sites simultaneously. That is because /site1 is on the same drupal root as /site2. Another problem is that they can't be on separate servers...

To fix this, you would need to decouple virtual hosts and sites in Aegir, which is a fairly deeply rooted assumption. It would be possible to use Aliases to work around that and have the sites be in different document roots.

But even if you actually coerce Aegir into having multiple sites in the same domain, you get into crazy namespace issues. Do you want to allow the site on to completely break sites or If so, who can? The same client? The same user? If not, you need to implement checks so there's no overlap...

Tools shouldn't dictate policy, people should. Therefore, this should probably be allowed, from a strictly technical perspective.

The thing is: domain names are cheap, contrary to common opinion. You only have to get one domain and you can have as many sub-domains as you want. Hell, you can even have sub sub domains and have your whole domain tree down there, you're free to go. Providers often give out a free DNS namespace to their customers based on their username (full disclosure: Koumbit does :P).

The other thing is: /site1 is exactly what drupal does: ot dispatches menus callbacks based those GET URLs. So trying to make Aegir (or Apache + Drupal, rather) do that is rather backward. On the other hand, Drupal is notoriously bad (if you make exception of the Domain module) at dispatching requests based on domains, and that's where Apache, DNS, Aegir and all their happy friends gets in.

In short, it's been very low priority for the use cases of the development team so far. If developers step up or if funding is provided, this could very well be part of a future release. See this feature request for followup:

Also see an extension for Aegir, written by mig5, called 'aegir_subfolders', which works (mostly)

4.14. My cache/performance settings in /admin/settings/performance keep resetting themselves!

Some values such as $conf['cache'] are hardcoded in the site's settings.php, which Aegir generates. This prevents some settings from being changed in the admin interface.

You can change the value of cache, and other variables, by creating a brand new file called 'local.settings.php' inside your site directory (e.g, alongside the settings.php). Put any value you want in it, e.g:

$conf['cache'] = 3;

..leave off the closing ?> tag, and this setting will now override all others. Aegir will not edit or remove this file.

4.15. I get [warn] NameVirtualHost *:80 has no VirtualHosts when I restart Apache

This is a harmless warning that Apache throws when you have duplicate 'NameVirtualHost *:80' entries in the Apache config somewhere. It doesn't cause any problem.

Aegir inserts this config line into an Aegir-managed apache config file just to make sure it's there at least once. If it's annoying you and you want to remove this warning, you need to remove the IP address from the server node and verify the server again. Note that this may fail in 2.x if the IP address is used by an SSL certificate yet the SSL certificate is unused. This shouldn't generally happen unless you are running a pre-2.0 release candidate, see #2159265 for details and [/discuss/how-delete-unused-ssl-certificate#comment-2163](this workaround).

4.16. I get 'Dummy connection failed to fail' when doing $stuff

Aegir attempts to make a connection to your database server that is deliberately designed to fail. The intention of this, is to get the 'remote host' of your webserver as seen from the perspective of the database server. This is used to generate appropriate GRANT statements so that your Aegir-managed sites can connect to their appropriate databases.

If you get the message 'Dummy connection failed to fail', this means that Aegir was able to login to your mysql server using username 'intntnllyInvalid' with a null password. This is a security problem on your behalf!

You should secure your MySQL service by running 'mysql_secure_installation' or manually by removing users in your mysql database's User table that don't have a valid password. See for more information.

Alternatively, if your MySQL server is sufficiently secured, there's always a possibility that your MySQL server responded with something Aegir didn't understand. Aegir expects either of these error messages:

Access denied for user(.... etc)

Host (...) is not allowed to connect to (....etc).

If your MySQL server responded with something else, but is secure, please open a bug report.

4.17. How do I make custom changes to a site's settings.php?

Aegir re-generates the settings.php for a site on certain tasks (Verify, Migrate, Backup, Restore, etc). For this reason it is not wise to put custom settings in the settings.php as you will probably lose them.

Instead, create a file 'local.settings.php' alongside your site's settings.php and put your custom changes in there.

If you want to make a change and have it apply to all sites immediately, put that change in /var/aegir/config/includes/

Neither of these files will be overwritten by Aegir on any task. thus preserving your changes.

4.18. How to migrate site via drush

drush provision-migrate '@platform_new_platform_alias'

Then, to update the frontend to reflect the changes:

drush @hostmaster hosting-import ''

Ubercart Integration FAQ

These are frequently asked questions about Aegir Ubercart Integration. For basic install and usage instructions please consult the guide.


Does this module create a site install task after product is purchased?

There may be some adjustment to UI needed to make this clearer, but the short answer is "Yes".

This is done conditionally: The module adds a checkbox saying "Create my site later" to the purchase form displayed on a product, if that product has the site feature. If that checbox is checked, then we go right to payment completion, and the client will create their site later using the regular aegir interface.

If that checkbox is not checked, we throw the user into a site creation form, store the data they input, and then use it on payment completion to create the site.

Regardless of whether or not they enter their site info during ordering, their client's quota is incremented.

In the case of a product kit with multiple sites included, only the first site can be created in this manner.

Case Studies

Case studies are intended to help explain the utility of Aegir by showcasing its use in some real-world example.

Pagebuild Case Study
Pagebuild allows non technical users to build websites very quickly and easily. It was built on top of Drupal, with the idea behind it being to provide an editing interface that is so simple, even an adult could use it. This is a explanation of what we did and how we went about doing it (and why).

Wikipedia Article


Feel free to enhance and improve!