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.

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.

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.

Drush

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

Provision

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

Apache

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

Sudo

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

Run a specific task in the queue from the command line

Run the 'Cron' queue manually from the command line