Debugging Aegir

Installation and configuration of Aegir has been greatly simplified with the release of .deb packages. However, for other operating systems, or for those installing manually, making a mistake during the installation or upgrade of Aegir or Drush is easy to do, and these tips identify some of 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:
  • cat /etc/passwd prints all users. Find the line aegir:x:1000:1000:,,,:/var/aegir:/bin/bash. aegir usually is the Aegir User. Be cautious about using a different username, and do notuse an existing user or a user that will have any other role on the server. The Aegir User should only be used for Aegir activities.
  • Verify the Aegir install directory is the user's home. Usually, the Aegir directory is /var/aegir. Be cautious about installing Aegir in a different directory only because you are likely to get confused and nearly all the documentation assumes you have used /var/aegir
  • Make sure that the node that defines your Aegir server (e.g., www.example.com/node/2) identifies the Script User as your Aegir User. (You can 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 servers.)
  • All this is detailed in the install profile wizard
• Do not run aegir as root! - It's an unsafe and unsupported configuration that is known to cause problems

Make Sure drush Is Installed Properly

• Make sure that the node that defines your Aegir Server has the correct path to drush.
  • See /var/aegir/drush/readme.txt for install instructions
• Check your Drush setup:
  • Always run drush as your aegir user, and never as "root".
  • Make sure that the Provision module is in the aegir/.drush/provision/ directory.
  • Make sure that the Hosting module is in ~aegir/hostmaster-0.x/profiles/hostmaster/modules/hosting (substitute the platform hostmaster-0.x to match the directory on your system in which you have installed the Drupal code that is running your Aegir site)
  • Run "drush help" and make sure that "provision" commands appear. "hosting" commands will not appear in the latest (after 2009/05/18) Drush versions, unless Drupal can be fully bootstrapped

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 restart Apache
  • On Ubuntu, it's 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
  • On Ubuntu, sudo apache2ctl configtest should report "System Ok"

Other Things

• 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 cron tasks manually from the command line
  • php /var/aegir/drush/drush.php --root=/var/aegir/hostmaster-0.x --uri=http://youraegirsite.com hosting-tasks --debug
• Or you can retry a specific task form the command line
  • php /var/aegir/drush/drush.php --root='/var/aegir/hostmaster-0.4-alpha5' --uri='youraegirsite.net' hosting-task <nid of the task> --debug