Contents

Help!

1. Where can I get help?
2. Can I ask you a question?
3. Who are the Aegir developers?
4. I'd like to help out / become a developer!

Installing Aegir

1. Can I run Aegir on a shared hosting environment?
2. Can I run Aegir on Windows?
3. Can Aegir be installed next to CPanel/Plesk/AlternC/etc?
4. Where can I get support for Barracuda/Octopus Aegir?
5. Do I really need to create an 'aegir' user?

Using Aegir

1. The cron isn't running (scheduled tasks/cron on sites 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 a platform but Aegir fails to provision a site on it (often OpenAtrium)
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 followed the installation instructions. What directory holds all of my sites now?
11. 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?
12. 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?
13. What about .htaccess settings?
14. How can I tell what version of Aegir I have installed?
15. I'm using symlinks (perhaps to a Git repo) and crazy things are happening!
16. How can I tell what database name my site is using?
17. Can I use the subdirectory multisite feature of Drupal in Aegir? (AKA example.com/site1 and example.com/site2)
18. After installing of Aegir I have two servers listed, is this normal?

Help!

1) Where can I get help?

From the Aegir Handbook (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.

3) Who are the Aegir developers?

The Aegir core developers are listed on the Aegir maintainers page.

4) I'd like to help out / become a developer!

We love people who want to help and get involved! We even made a page for you to read.

Installing Aegir

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

Shared hosting will not give you enough permissions to install new sites. Toughen up, read some Linux beginners tutorials and buy a cheap VPS which will do nicely.

2) Can I run Aegir on Windows?

To install Aegir you need a unix based operating system. Aegir will not work on Windows and there are no plans to add support for it.

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

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

4) Where can I get support for Barracuda/Octopus Aegir?

Barracuda/Octopus are custom scripts for Aegir that install or set up various things that Aegir doesn't do out of the box. This is a custom solution tailored to Nginx systems, provided by Omega8.cc and is not officially supported by the core Aegir project or team. For help or more information, please visit BOA Group, Barracuda and Octopus project pages / issue queue on drupal.org.

5) Do I really need to create an aegir user?

If you have a UNIX system, you already have a user. It just needs to not be root for safety reasons. But you don't really have to create a user.

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.19 and re-execute the hosting dispatch: Type 'crontab -e' again.

b) You should see the default entry:

But if this is still not working it may well be a permissions issue. An example error :

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:

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

d) 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.

e) 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:

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 replace --backend with --debug at the end of the commandline.

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

Aegir isn't a package management GUI for installing modules or themes on your site.

It's designed to help manage your site between builds. To upgrade sites, you should be using the Migrate tool to move your site between two platforms, which invokes drush updatedb.

If you aren't ready for this paradigm, and are frustrated that Aegir isn't some GUI for wildly updating or installing new modules with no regards for rollback or dealing with when it will inevitably break your site, Aegir is probably not for you.

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

Aegir supports either method and can even automatically create whichever one you didn't use as the main site name. Read more about Aliases and this feature in our documentation.

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

Aegir ships with an experimental SSL feature, but currently doesn't provide any means of managing SSL certificates.

You can follow the ongoing SSL work here.

In the meantime, to set up SSL with basic self-signed certs, follow our documentation.

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 a platform but Aegir fails to provision a site on it (often OpenAtrium)

A premature failure of a site install with an unhelpful message such as 'The external command could not be executed due to an application error' often, but not always, means your php-cli's memory_limit is set too low.

To confirm that this is an issue, try running drush @example.org provision-verify --debug from the command line to find out what caused the problem. Remember to replace 'example.org' with the URL of the site you are trying to verify.

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.

This is a common issue for OpenAtrium as it 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 machine name - which is essentially their folder name. This is also used to prefix their functions etc, so that there are no clashes. What isn't often recognised or well documented is that Drupal has a single namespace for all items - so your themes, modules and install profiles can't have the same name as each other. 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, but it isn't Aegir's fault, it's the developer's limited or lack of understanding of this Drupal caveat. 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 followed the installation instructions. What directory holds all of my sites now?

For a full overview of a typical Aegir filesystem structure, read this.

11) 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

12) 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.

13) 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.

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

This works for version 1.1 and above . . . maybe earlier too . . . .

Also, if you have drush installed someplace other than in /var/aegir/.drush, then you should grep the aegir.make file in the directory tree where you have drush installed. For example, on Ubuntu, apt-get may install drush in /usr/share/drush/. So, the file to be grep'd would be /usr/share/drush/commands/provision/aegir.make.

If you're still unsure or this didn't work, contact a developer on IRC and we'll be able to tell you after you answer a few questions.

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

If you're symlinking an entire /sites/ folder, Aegir may 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.

Storing your site's dir in git is an archaic and inefficient method of developing sites. It's 2010 and there are more elegant ways of doing things thanks to Drush Make and Aegir. 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.

16) How can I tell what database name my site is using?

Check the site's vhost configuration file in /var/aegir/config/server_$whatever/apache/vhost.d/. The db name (and user/password) are stored as 'SetEnv' parameters to Apache, allowing us to cloak database credentials in the settings.php so that they are protected in a multisite environment from prying eyes (admins with PHP filter permissions).

You can also use 'drush st' on your site to get a status report containing the database name, user, password, among other things.

In modern releases (0.4-alpha9 or so and above), the site database names have switched from site_$nid style names to more properly reflect the site name/URL itself.

17) Can I use the subdirectory multisite feature of Drupal in Aegir?

Also known as "http://example.com/site1" and "http://example.com/site2" are different sites.

Short answer: no.

Long answer: this is unlikely to be supported, because multiple sites usually end up sharing the same virtual host entry in the webserver and you will be required to upgrade/migrate all of the sites simultaneously. That is because /site1 is on the same drupal root as /site2. Another problem is that they can't be on separate servers...

To fix this, you would need to decouple virtual hosts and sites in Aegir, which is a fairly deeply rooted assumption. It would be possible to use Aliases to work around that and have the sites be in different document roots.

But even if you actually coerce Aegir into having multiple sites in the same domain, you get into crazy namespace issues. Do you want to allow the site on example.com to completely break sites example.com/site1 or example.com/site2? If so, who can? The same client? The same user? If not, you need to implement checks so there's no overlap...

Tools shouldn't dictate policy, people should. Therefore, this should probably be allowed, from a strictly technical perspective.

The thing is: domain names are cheap, contrarily to common opinion. You only have to get one domain and you can have as many sub-domains as you want. Hell, you can even have sub sub domains and have your whole domain tree down there, you're free to go. Providers often give out a free DNS namespace to their customers based on their username (full disclosure: Koumbit does :P).

The other thing is: /site1 is exactly what drupal does: ot dispatches menus callbacks based those GET URLs. So trying to make Aegir (or Apache + Drupal, rather) do that is rather backward. On the other hand, Drupal is notoriously bad (if you make exception of the Domain module) at dispatching requests based on domains, and that's where Apache, DNS, Aegir and all their happy friends gets in.

In short, it's not worth it. See this feature request for followup: http://drupal.org/node/705026

18) After installing of Aegir I have two servers listed, is this normal?

Yes, on installing Aegir a server is created that represents your webserver, and another that represents your database server. If you are in the special case of having those two servers being on the same machine, then you'll still have two servers listed in the front end. This is perfectly fine, and dosn't interfere with anything in Aegir's normal operations, it's nothing to worry about!