Aegir FAQ

The Aegir Project has moved.

This Drupal group is no longer actively used.
To get involved and learn more about Aegir, you should go to our community site,
which also contains our official documentation section and the official discussion group.

The old posts and documentation are still available in the old discussion tab.

Contents

Help!

1. Where can I get help?
2. Can I ask you a question?

Installing Aegir

1. Can I run Aegir on a shared hosting environment?
2. Can I run Aegir on Windows?
3. I get an error about permissions on the settings.php when installing Aegir using the Hostmaster profile
4. Can Aegir be installed next to CPanel/Plesk/AlternC/etc?
5. Why am I having trouble installing the 0.4alpha3 release?

Using Aegir

1. The cron isn't running (scheduled tasks aren't being executed), what do I do ?
2. How do I get debug/verbose info from Drush when running the hosting commands ?
3. How do I update a sites modules using aegir?
4. Is it best to set up sites under aegir as www.example.com or just as example.com ? The aim is for both to resolve to the same.
5. How can I setup a site to use https:// under Aegir?
6. Aegir is not verifying / deleting / migrating my site because of file permission problems.
7. I can verify OpenAtrium as a platform but Aegir fails to provision an Atrium site
8. A platform with an installation profile has verified okay, but Aegir doesn't seem to be able to use the profile
9. What is a patch or 'hotfix', and how can I apply it to fix my site if I can't / don't want to upgrade to HEAD?
10. I'm getting weird "<?php" errors when running the install script, the cronjob or drush
11. I followed the installation instructions. What directory holds all of my sites now?
12. I tried to create a site, but the create task failed and retries don't succeed. How do I delete the partially created site and associated Aegir tasks?
13. I tried to migrate a site, but Aegir incorrectly reported an incompatibility between one or more modules in my source and destination platforms. How do I force Aegir to see that the two platforms are compatible?
14. What about .htaccess settings?
15. How can I tell what version of Aegir I have installed?
16. I'm using symlinks (perhaps to a GIT repo) and crazy things are happening!
17. Where does aegir store the mysql root password? My mysql root password is changed/different from what Aegir has. How do I give Aegir the new/correct password?

Help!

1) Where can I get help?

From the Documentation (which should be the first place you look) :

The Issue Queue for all the projects that make up Aegir is here: http://is.gd/ek2Dl

This is the first place to look - chances are someone's had the same problem as you before, and you'll get the quickest answers by searching for what they discovered.

Before asking a question or reporting an issue, you should read the bug reporting guidelines.

You can join the #aegir channel at Freenode on IRC. (IRC instructions for drupal users are at: http://drupal.org/irc). It's a friendly community, but a small one, so ask nicely and be patient!

If you find a solution to a problem that isn't in the documentation or in this FAQ, be the first to login and edit these pages to bring them up to date! The rest of the community thrives on your helpful information!

2) Can I ask you a question?

Of course you can! Don't ask to ask, just ask! It is polite to look if the question has already been answered in the documentation, the issue queue or here, but if not, please do ask around! If you ask a question and we have a nice answer, you can even add it to the FAQ here so that others can have your valuable answer.

Installing Aegir

1) Can I run Aegir on a shared hosting environment?

Shared hosting will not give you enough permissions to install new sites

2) Can I run Aegir on Windows?

To install Aegir you need a unix based operating system. Aegir will not work on windows.

3) I get an error about permissions on the settings.php when installing Aegir using the Hostmaster profile

Leave your settings.php writable by Apache for one extra step further than you normally would for a regular Drupal installation. See this ticket

4) Can Aegir be installed next to CPanel/Plesk/AlternC/etc?

No, or rather "it's not supported". See http://drupal.org/node/587554

5) Why am I having trouble installing the 0.4alpha3 release?

Around the time the 0.4alpha3 version was released or just after, a number of problems / bugs were encountered that were generally the responsibility of some tools that Aegir depends on: particularly Drush and Drush Make.

This has led the 0.4alpha3 release to being unusually more difficult to install than intended. Unfortunately since the fixes for these issues need to happen outside of Aegir itself, there is little the Aegir developers can do other than provide workarounds, which is what this FAQ item intends to do for you.

Problem: Drush 2.1 and Dash/php executable issues

When executing 'su -s /bin/sh aegir -c "sh install.sh"' during the installation, you may see these errors, particularly if you are using an Ubuntu server:

This is because /bin/sh on your system is likely a symlink to /bin/dash . Dash is a lightweight shell that has become the 'default' shell in Ubuntu and in Debian Squeeze (testing). It has trouble reading the environment to properly execute the php file.

Possible fixes

Option 1) Workaround by using Bash instead of Dash: edit the install.sh script and change the shebang from #!/bin/sh to #!/bin/bash
Then execute it like this: su -s /bin/bash aegir -c "bash install.sh"' -- this avoids all the patching and editing below and "just works" on Ubuntu.

Option 2) Patch Drush 2.1 with this patch http://drupal.org/files/issues/586466_commandline_2.1.patch . See the whole issue http://drupal.org/node/586466
If that is not enough for it to work, try the patch from here http://drupal.org/node/637574

Option 3) Upgrade to Drush HEAD which has fixed this issue.
(temporary EDIT by steveparks 21 Dec: )An update to drush means that drush_make now thinks it is a pre 2.1 version and therefore not compatible - introducing yet more dependency hell! As a temporary workaround you need to disable this version checking if you are using drush HEAD. Edit the file /var/aegir.drush/drush_make/drush_make.utilities.inc to look like this:

Note that the drush_make team are aware of this issue so a fix may be released. This bug/workaround was correct as of 21st Dec 09. Follow the ticket here: http://drupal.org/node/662586 for any news of a fix.

This issue has been fixed in Drush HEAD.

Problem: Drush Make and undefined function curl_init()

You see an 'undefined function curl_init()' while running the install.sh script.

Drush Make 6.x-2.0-beta5 introduced a dependency on php5-curl that shouldn't exist. It should try other alternatives if curl libraries are not found on your system. The 6.x-2.0-beta6 release of Drush Make has fixed this, so if you have beta5 you should upgrade, or you already dealt with the issue via an earlier revision of this FAQ which suggested installing php5-curl or installing drush_make HEAD.

Possible fixes

Option 1) Use drush_make 6.x-2-0-beta6

Option 2) Install php5-curl (apt-get install php5-curl)

Option 3) Apply the patch from this issue: http://drupal.org/node/647546

Option 4) Edit the install.sh script to install an older version of drush_make. Change $DRUSH dl drush_make --destination=$AEGIR_HOME/.drush to $DRUSH dl drush_make-6.x-2.0-beta2 --destination=$AEGIR_HOME/.drush

Problem: Drush Make and 'unable to export hostmaster'

You see an 'unable to export hostmaster' error while running the install.sh script.

After the 0.4alpha3 release was made, Drush Make changed the way the CVS URL needs to be defined in a drush makefile. Our hostmaster.make fetches from CVS using the old version of the CVS URL with the first colon missing from ':pserver:' . See http://drupal.org/node/646748

Possible fixes

Option 1) Edit the install.sh script to install an older version of drush_make. Change $DRUSH dl drush_make --destination=$AEGIR_HOME/.drush to $DRUSH dl drush_make-6.x-2.0-beta2 --destination=$AEGIR_HOME/.drush

Option 2) Consider installing the development version of Aegir from git.aegirproject.org, which since we no longer depend on CVS, avoids this problem entirely by using git.

Phew!

Using Aegir

1) Cron isn't running (scheduled tasks aren't being executed), what do I do?

At the shell prompt as the aegir user, type

a) If you get an error that the command is not found, then you need to install cron on your server (some basic images don't include it - Linode's Ubuntu 9.04 image is one):

Now go back to the directory /var/aegir/drupal-6.13 and re-execute the hosting dispatch:

Type 'crontab -e' again.

b) You should see the default entry:

c) When cron for your sites stops working, it is possible that for some reason (system overload, broken site, timeout etc), Aegir failed to release a sites cron semaphore. To release it, use this simple recipe:

d) If this is still not working it may well be a permissions issue. An example error after running hosting-dispatch --debug :

This means the system doesn't have permissions to access /dev/null. To resolve it, give the system permissions to write to /dev/null (it should have this anyway), by executing:

e) If this still hasn't worked, have you moved the location of drush?
If so - see http://drupal.org/node/540152

f) If you are a *BSD user (verified on freebsd at least)
You need to add the line :
PATH=/bin:/sbin:/usr/bin:/usr/sbin:/usr/local/bin:/usr/local/sbin at the TOP of your cron file.
Simply log in as the aegir user and type crontab -e and insert the above line on top.
Thanks goes to mauror for http://drupal.org/node/323732.

2) How do I get debug/verbose info from Drush when running the hosting commands?

Add these to the drush call :

If you're having specific problems when using the frontend, you can easily run the hosting commands from the command line by:

1. Click the view button and then copy the Drush command which was executed at the top of the log;
2. While logged in as the aegir user, paste the command in at the terminal and add --debug at the end of the commandline.

3) How do I update a site's or platform's modules using Aegir?

NOTE: the following instructions generally apply to themes as well
At the moment Aegir doesn't install or update modules in a site or platform. You can however use drush at the commandline in shell to do this.

If you wish to install a module for a specific site, you must run the following commands inside /var/aegir/[platform]/sites/sitename.com;
if you instead want to make the module available to all sites in a platform, just run the command in the /var/aegir/[platform]/ directory (drush will place these
files in /sites/all/modules).

To download a module from drupal.org:

And you can also enable it from the commandline (or simply through the site's admin area as usual)

And to update the module:

Or to update all the modules:

If you wish to see newly-installed modules inside the Aegir user interface packages list, you must first run a Verify task
for the site or platform in which the new modules were installed (Aegir does not automatically update the package list,
as Drupal would for the modules or themes page); in order to schedule this task, simply click the Run button
for the Verify task. The task will be added to the task queue to be executed by cron.

4) Is it best to set up sites under aegir as www.example.com or just as example.com ?

You want aliases by default, it adds www. So you want to set up the site as example.com. If it doesn't then automatically default to that site if you use 'www', you can then add 'www.example.com' as an alias within aegir.

5) How can I setup a site to use https:// under Aegir?

At the moment Aegir doesn't provide any means of managing SSL certificates, or accessing a site via https. There is a lot of discussion around implementing this however, and future versions are likely to include this.
You can follow the discussion here: http://drupal.org/project/issues/search/hostmaster?issue_tags=aegir-ssl

In the meantime you can set this up manually without causing problems with Aegir. See this how-to for details: http://groups.drupal.org/node/25038

6) Aegir is not verifying / deleting / migrating my site because of file permission problems.

Aegir releases prior to 0.3 RC3 encountered an error when the web server has uploaded files and made new directory in the sites/$url/files directory. A prevalent example of this occurring is with the color module and when imagecache is used (such as in atrium).

This bug (see: #203204 ) was introduced with Drupal 6, and has since been fixed with Drupal 7. The patch has however not been backported yet, and the patch won't fix existing files that were created incorrectly.

In Aegir 0.3 RC3 we introduced a work around which sets the umask for the site, which forces new files and directories to be the correct permissions, but this will only take effect after the site has been succesfully verified. To enforce the correct file ownership and permissions on the files, run the following command on each of your Drupal 6 platforms :

This will allow the verify task to correctly set the permissions and succesfully modify/remove the files.

7) I can verify OpenAtrium as a platform but Aegir fails to provision an Atrium site

Raise your memory_limit in your php cli php.ini file to something like 128MB, or maybe 64MB if that's too much. On Debian-based distributions this is /etc/php5/cli/php.ini. Apache does not need a restart for this: installations fail because the command is being executed via drush using php cli. Atrium requires more memory to run its install profile as it has a lot more to do than a regular Drupal install.

8) A platform with an installation profile has verified okay, but Aegir doesn't seem to be able to use the profile

Your platform has been setup and verified okay, but when you go to create a new site Aegir keeps giving an error message about the profile, or the list doesn't offer you the profile you're expecting. This could be a namespace issue. Modules, themes and profiles in drupal all have a name - which is essentially their folder name. This is also used to prefic their functions etc, so that there are no clashes.
What isn't often recognised (but which Vertice and Mig5 figured out) is that drupal has one namespace for all items - so your themes and modules can't share a name with an installtion profile.
Often an installation profile will be created called 'OpenPotato' and the theme for it will also be called 'OpenPotato'. This makes drupal unhappy, and when drupal's unhappy Aegir's unhappy. We don't want that.
The easiest thing is to name your installation profile directory 'OpenPotato_install' and name the profile file 'OpenPotato_install.profile'. You'll also need to rename the functions inside this file.
Then everything should work just fine.

9) What is a patch or 'hotfix', and how can I apply it to fix my site if I can't / don't want to upgrade to HEAD?

Sometimes releases are made and bugs are discovered afterward. We commit fixes for such bugs to HEAD, but HEAD is often volatile and you don't want to use a non-stable release in your environment. Fortunately we do (or should: if it's critical, please ask for a patch otherwise) provide a 'hotfix' or patch for users. A patch means that you can 'patch' your Aegir system to fix the bug without running the risks of using HEAD.

To patch an Aegir component, use the following example, in which we fix the Provision module with an imaginary patch. The same or similar steps apply for Hosting or Hostmaster (though you shouldn't need to patch Hostmaster, you only use it once to install!)

Run the steps as the aegir user.

If the patch doesn't apply or prompts you to enter the filename to patch, try running patch -p1 instead of -p0 above.

If it still asks for clarification, verify that you are in the top-level directory of the component (in this case, we are inside /var/aegir/.drush/provision)

If it still doesn't work, it might be an unclean patch, and you should make a request in the relevant ticket to be given a cleaner patch to apply.

For more information on patches, please read the Drupal documentation.

10) I'm getting weird "<?php" errors when running the install script, the cronjob or drush

This is a known bug with Drush 2.1. You need to apply this patch on 2.1 or run Drush HEAD until a new release is out. If you are using 0.4-alpha2 or earlier, it is recommended that you run Drush 2.0 instead.

11) I followed the installation instructions. What directory holds all of my sites now?

If you follow the Aegir installation instructions closely, you will notice a series of steps in which you tar your existing sites and untar them in /var/aegir/platforms. The effect of these steps and the modifications that Aegir makes automatically to your Apache configuration is to shift the hosting of your drupal sites from whatever directory you were using (e.g., /var/www/html on a typical Ubuntu system) to /var/aegir/platforms.

12) I tried to create a site, but the create task failed and retries don't succeed. How do I delete the partially created site and associated Aegir tasks?

See the section 'Manually deleting the site' from the documentation

13) I tried to migrate a site, but Aegir incorrectly reported an imcompatibility between one or more modules in my source and destination platforms. How do I force Aegir to see that the two platforms are compatible?

This problem can arise for at least two different reasons. First, you may have updated a module in a platform that you imported and forgotten to run update.php before you imported the site into Aegir. Second, you may have updated a module in a platform and not re-verified the platform in Aegir. Be sure that you have run update.php on a drupal platform that you will be importing into Aegir before you import. Also, if you make any change to the modules in an Aegir Platform, re-verify that platform and all sites using that platform. (At least, experience suggests that doing these things will allow the migration to succeed.

14) What about .htaccess settings?

As of recent 0.4 alpha releases, Aegir now reads in the contents of a platform's .htaccess file when generating the Apache configurations. You can safely make additions/changes to the platform .htaccess and expect the relevant site to respect those changes.

15) How can I tell what version of Aegir I have installed?

This works for alpha9 and above...maybe earlier too...

16) I'm using a GIT repo for a site, but symlinks make crazy things happen!

If you're symlinking an entire /sites/ folder, aegir will not acknowledge the site, as this will cause problems when cloning/migrating a site.

If you are using GIT to version control your themes, custom modules, etc, and symlinking these into your sites folder, you will find that cloning a site will clone those symlinks (by virtue of copying the sites folder). This is probably not what you want to happen!

Themes and custom modules are better off being checked out to or symlinked into the install profile folder. If your site's install profile is 'foobar' (there's an 'install_profile' variable in the variables table), Drupal core understands to look inside the /var/aegir/yourplatform/profiles/foobar/ folder for modules and themes directories.

The files directory for uploads (which I don't think can be efficiently versioned anyway in most cases) and the settings.php file will be all that's left in your sites folder, and Aegir will happily move that all around as you clone or migrate your site between platforms.

You might like to look at mig5's excellent article where he provides some great tips on how to manage Drupal deployments & workflows with version control, drush_make, and Aegir.

17) Where does aegir store the mysql root password? My mysql root password is changed/different from what Aegir has. How do I give Aegir the new/correct password?

The root password is stored in /var/aegir/.drush/server_localhost.alias.drushrc.php and there's another place - in the hosting_db_server db in the frontend.