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.

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.

MySQL

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

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:

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

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.

IRC

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: http://drupal.org/irc.

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

Events

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.

Blogs

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:

• http://developmentseed.org/tags/aegir
• http://mig5.net/category/tags/aegir

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 Drupal.org:

• 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!

Testers

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

Documentors

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.

Promotion

• Blog about Aegir and put your aegir term feed in our feed aggregator

• You can also make or collate screencasts and post them here for others.

Developers

Want to become an Aegir developer?

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

Donate

See the donation page.

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.

Omega8.cc

Omega8.cc 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. Omega8.cc 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)[http://drupal.org/project/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 Drupal.org: helmo

shop resources