Getting Help

Need help with Aegir? Documentation just not covering it?

We recommend you run through the following in this order:

  1. Read the FAQ to check that your problem isn't answered there or that there isn't a workaround
  2. Review these tips on configuring Aegir, Drush, Apache and more, and avoid common mistakes.
  3. Search this site to see if your problem or question has already been addressed.
  4. Look at the current issues for all of the Aegir-related issue queues to see if the bug has already been reported.
  5. Ask the community for help (but see below for good hints on how to make this work better!)
  6. If you think you have found a a bug report or support request, head over to the bug reporting guidelines
  7. If you've exhausted all these avenues and still haven't been able to resolve your issue, or otherwise want some professional assistance, you may want to refer to our Aegir Service Provider Directory

Asking for help

If you need help from the community, you're going to have a lot more success by helping the community help you. Just saying "it doesn't work" or "it's broken" will not help us help you. When you ask for help or report a bug, please include the following information:

  • if the install failed, try the install again with the --debug flag on the hostmaster-install command, or with the DEBUG=yes environment set before running apt-get install
  • if a task failed, include a copy-paste of the complete task log, properly formatted (between <code> tags)
  • in any case, explain what you are trying to do clearly, what are the expected results and the actual results and how to reproduce your issue
  • give as much details as you can: the version of your operating system, the version of Aegir, drush and Drush make you are using, the version of Apache or Nginx you are running, which servers or platforms you are using, etc

For more information about how to ask smart questions, see How To Ask Questions The Smart Way by Eric S. Raymond.

Finally, if you're confused or don't know where to go, you can always come to us! To talk with the community and the developers directly, you can join IRC, discuss site or ask on the mailing lists. See the Community and Support page for more information.

Troubleshooting Aegir


Aegir undergoes rigorous testing, but no actively-developed software ever escapes bugs.

If you feel you have encountered a bug, the FAQ is the first place to check if there's a simple solution.

Common installation and configuration errors

Aegir is a more complex product than your average Drupal site. Something that has far-reaching control over bits of your server and your sites results in more bits and pieces working together, and inevitably it becomes possible to misconfigure, break, or miss setting up any one of these components.

The installation and upgrade procedure has evolved from these pains to becoming something almost purely automated. Nonetheless, making a mistake during the installation of Aegir or Drush is still easy to do, and these tips identify the most common mistakes.

If Something Goes Wrong

If an installation fails partway, particularly while using the script, you may not be able to run it successfully until you've rolled back any changes that the script has made. Delete the contents of the /var/aegir directory (not the directory itself) making sure to remove any hidden directories like /var/aegir/.drush. Also, drop any new MySQL database (which will be named according to the hostmaster domain name).

The Aegir User

Make sure you have an aegir user (who we call the Aegir User) and that the Aegir User is properly configured on your server.

Typing 'id aegir' on your system should print something like this as output.

aegir:~# id aegir
uid=104(aegir) gid=108(aegir) groups=108(aegir),33(www-data)

If you don't want to use a user called 'aegir' for the installation, that's possible (albeit not recommended). Be cautious about using a different username, and do not use an existing user or a user that will have any other role on the server. The Aegir User has certain privileges and should only be used for Aegir activities.

Aegir User's home directory

Verify the Aegir install directory is the user's home. In a standard installation, the Aegir directory is /var/aegir.

Be cautious about installing Aegir in a different directory - it is easy to get confused since nearly all the documentation tries to be consistent by assuming you have used /var/aegir and you'll otherwise constantly have to translate this mentally when trying to learn.

Aegir User as script user

Make sure that the 'Server' node in your Aegir system (this is usually the node located at /node/2) lists the 'Script User' as being your Aegir User. You can also find this node by clicking on the Servers menu tab and then clicking on the server URI shown in the list that appears of Aegir-managed servers. In a basic installation, there is only one server.

Do not run as root

Do not run aegir as root! It's an unsafe and unsupported configuration that is known to cause problems.


A standard Aegir installation will check that Drush is functioning properly, or if it doesn't find Drush at all, will install it for you.

Always run drush as your aegir user, and never as "root".


Make sure that the Provision module is in the aegir/.drush/provision/ directory. A standard Aegir installation will install this for you.


Aegir uses the 'root' user of the MySQL server to create and manage databases. If MySQL is running on the same server, Aegir will still attempt to connect to the database as if remotely. If the MySQL server is security hardened to prevent this type of access, this would result in MySQL errors during Aegir installation.

To see the root users. Connect to MySQL database and run the query

SELECT user, host, password FROM mysql.user WHERE user = 'root';

There should be separate records for the host localhost and hostname, and the password hashes should be the same to avoid confusion. If the password hashes are different, which is possible if the root user password has been updated with mysqladmin, you can make the passwords consistent by running:

UPDATE user SET Password=PASSWORD('new_password')  WHERE host='hostname' AND user='root';


Make sure the Aegir User can restart Apache without a password and that the corresponding command is defined in your Aegir 'Server' node.

As your Aegir User, run the command shown in the "Restart command" field in your Aegir 'Server' node to ensure that your Aegir User can in fact restart Apache (if not, see the Sudo information below).

On Debian/Ubuntu, the command sudo /usr/sbin/apache2ctl graceful. The command should execute and return without asking for a password when run as the Aegir User.

Make sure Apache can parse its configuration without syntax errors. On Ubuntu, sudo apache2ctl configtest should report "Syntax OK".


Check that the aegir user is in your /etc/sudoers file with the permission to restart Apache. Instructions and an example for doing this are contained in the INSTALL.txt.

On a Linux system, check that /etc/sudoers is chmod 440 (i.e., read only for the file owner and group, which is usually root)

Attempt to run the task queue manually from the command line

php /var/aegir/drush/drush.php @hostmaster hosting-tasks --debug

Run a specific task in the queue from the command line

php /var/aegir/drush/drush.php @hostmaster hosting-task <nid of the task> --debug

Run the 'Cron' queue manually from the command line

php /var/aegir/drush/drush.php @hostmaster hosting-cron --debug

Contact the community

Want to talk with the Aegir community? There are many channels with various virtues.

Discussion Forum

The community site has a discussion area that anyone can use to talk about Aegir with others or seek support.


You can join the #aegir channel at Freenode on IRC. There's a loyal community of Aegir developers and users that frequent this channel. Much development discussion also takes place here, and support questions are welcomed.

The core developers also are reachable in #aegir on IRC.

Remember that Aegir, like Drupal, transcends timezones, and even the developers are many hours apart from each other. Sometimes it's quiet, and sometimes it's very busy. Don't repeat yourself: someone will respond eventually if not immediately.

New to IRC? IRC instructions for Drupal users are at:

Mailing Lists

There are mailing lists that can be used for support, general discussion and development or announcements.

  • announce - the announce mailing list is used to announce new releases or major news
  • users - the user mailing list is used for general discussions and support for Aegir users
  • core - the core mailing list is used for internal discussions in the core team


Aegir is often present at many of the popular DrupalCamps and DrupalCons, either as a formal session or in smaller BOF sessions.

We encourage users who are confident in using Aegir to demonstrate it at any relevant events they attend, and to post slides/screencasts so that others can benefit.


As well as the News/Blog area here, the developers also often blog about new Aegir features or share handy tips for the community. Here are two blogs to stay up to date with:

Bug reporting guidelines


Reporting bugs is a great way to contribute to Aegir and it helps all of us (developers and users both) shape Aegir into the fantastic Drupal management system we want and need.

Before reporting bugs

Mis-reporting bugs that are due to not following instructions or skipping steps, not providing enough information or duplicating reports, however, can be a distraction to the development team and waste precious resources. So, help out by following these guidelines for reporting bugs.

Before you report a bug, make sure you have done things right and are sure it's a bug, by reviewing the Getting help section, if only to include the right information in your bug report.

Where to report bugs

Somehow a bug or two may have slipped into Aegir. Eek! So it's really a bug? A new bug? To report it, file an issue on

  • Hosting (if the issue is in the frontend)
  • Provision (if the issue is in the backend) or
  • Hostmaster (if it is in the installer, a documentation bug, or if you don't know where the issue should go).
  • Eldir (if it's an issue with the default Eldir theme that ships with Aegir.)

Feature Requests

Feature requests are, of course, always welcome in these queues as well. To get an idea of where Aegir is headed with new features, you should first consult the Aegir Roadmap and Project Goals - we may be already on it!

How to help?


  • download new release
  • report bugs
  • test existing issues and patches
  • use it! test everything!


Contribute to this handbook and the rest of the community site.

Contributing can mean adding new documentation, or reviewing existing docs to ensure that they haven't become out of date, incorrect or been defaced.



Want to become an Aegir developer?

Submit good patches and review existing ones and we will love you and give you commit access.


See the donation page.

Donate to the Aegir project

We are happy to take donations from users to further development and keep our community site, mailing lists, and Jenkins CI server running. Note that you can also talk with existing service providers if you have the budget to further specific functionalities, but otherwise a small (or big!) donation is always appreciated and will make sure we have funds to operate the infrastructure for the project or maybe even pay people for development work.

Help us work on one of these goals:

  • The next 7.x-3.x maintenance release
  • The next 6.x-2.x maintenance release
  • Hosting Drupal 8 sites
  • Extending Aegir with new features

You can make this happen.

Financial support can greatly accelerate our development efforts. The core team needs your help to keep this going.

You can make this happen! Can you spare $5?

  via paypal

Gratipay (formerly Gittip) logoGratipay (formerly Gittip) has a team for Aegir

The small core team that works on Aegir does this mostly because they use it themselves. That however does not cover all the time we work on Aegir.
Our passion to produce a good product, and love for Drupal, drives us to keep working on this, but there is a risk of developer burnout.
For example: supporting older versions and making upgrade paths user-friendly is a lot of work. While the core team has only limited personal need for this.
Donations validate more time being spent on this.

Please contact one of the service providers if you're looking for paid support.

Aegir Service Providers

Here is a list of consulting and hosting firms offering paid support for the Aegir Hosting System:

Koumbit Networks
Koumbit's team includes several of Aegir's core maintainers and contributors; including, among others, Anarcat, the project lead, as well as developers of several contributed projects. Koumbit manages one of the largest Aegir deployments, hosting hundreds of custom developed websites, as well as being one of the first providers to automate site ordering and provisioning. Koumbit is a dynamic team of designers, developers and sysadmins, offering support and consulting services from front-end development (design, theming and UI), through e-commerce, complex Drupal site builds and data migrations, to hosting and systems administration. This diversity has allowed Koumbit to develop deep expertise in distributed development best-practices. Koumbit has recently launched AegirVPS services, offering full root/SSH/SFTP access to robust virtual servers with Aegir pre-installed, maintained and supported. offers dedicated Aegir hosting service since July 2009, using custom developed, high performance cloud servers configuration. Hosted options include SSH and Drush access, with simplified Aegir interface. supports also remote Aegir installations and maintenance on Client's servers. Simplified and optimized for single server installations system configuration is open-sourced since 2009 and available as a dual-core Barracuda and Octopus installer.
Praxis Labs Coop

We are a worker's cooperative based in Montreal. We share an interest in web technologies and direct democracy. We've all been working with Drupal and Aegir for many years. One of our founding members (Christopher "ergonlogic" Gervais) is in fact a lead developer of the Aegir project.

We provide Aegir, Drupal and Open Atrium hosting, development, support & consulting.

Praxis is a proud partner of Koumbit networks.

ThinkDrop Consulting
ThinkDrop provides Infrastructure and Architecture consulting for Aegir and Drupal. We are the creators of (DevShop)[], the first open source Drupal Environment Manager, built on Aegir. We have also created a number of other Aegir addons like Aegir Drush Aliases and the Hosting & Provision Solr modules. The ThinkDrop team is Jon Pugh, Kevin LaPalme, and Jacinto Capote
Initfour websolutions
Initfour provides Infrastructure and Architecture consulting for Aegir and Drupal. Internally Aegir is used for hosting managed Drupal sites. Fixing what needs to be fixed, Initfour has worked in many corners of the Drupal/Aegir universe.
On helmo

Shop resources

shop resources