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 install.sh 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
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