System Administrator's Guide/Installing Mahara/Troubleshooting

Here is a list of common questions and problems people have while installing Mahara. There is a list of common problems in the forums that might also help you.

Q: I just see 500 Internal Server Errors when trying to load pages

A: This is probably because you are on shared hosting and your host has disabled some directives within .htaccess files, or possibly even disabled the use of .htaccess itself.

The .htaccess file lives in the htdocs/ directory. It is a "hidden" file (because of the . at the start of its name), that tells Apache how it should behave. Mahara uses it to turn off dangerous PHP settings and configure caching so that your Mahara site performs quickly. Unfortunately, if your host has disabled .htaccess then you will lose some or all of these benefits.

To resolve the issue, first comment out any line that starts with php_flag or php_value in the file, and try loading the page again. If that still doesn't work, completely remove the .htaccess file.

If you're still running into issues, you will need to check your apache error log. The log should have an error message in it telling you exactly why you're getting the 500 Internal Server Error. Mosts hosts provide at least rudimentary access the logs. If they don't, consider switching, because a host where you can't find out what's wrong is not providing you with an acceptable minimum of service.

Q: Upon successful install, I see messages like You have dangerous PHP settings, magic_quotes_gpc is on.

Mahara is trying to work around this, but you should really fix it

A: These messages warn you about PHP settings that you should have disabled. Mahara tries to disable them via .htaccess. If this has not worked, then you're probably on shared hosting, and need to tell Mahara to disable the messages. In your config.php, find this line:

$cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;

(if it exists) and change it to

$cfg->log_environ_targets = 0;

If that line didn't exist, just add the second one to your config.php.

Q: I see "Parse error: syntax error, unexpected '{' in .../htdocs/init.php on line 79"

A: You're probably running Mahara on PHP4. Mahara requires PHP 5.1 or greater.

Q: Every page I go to, Mahara wants me to log in again!

A: There's two possibilities:

1. You could have set up a Server Alias for Mahara. This is a mistake.People use ServerAlias to make their sites respond to both example.org and www.example.org. The problem with this, in the context of Mahara, is that Mahara has a wwwroot setting which is where it expects to be run from. That is, Mahara expects to always be run from exactly the same domain name.This is for a couple of reasons. Firstly, SSL keys for MNET are generated by hostname, so having your site respond on more than one hostname means that MNET communications on the other hostnames will break - leading to an inconsistent "flaky" MNET experience for your users. Secondly, cookies can be set for just the one domain, preventing the issue where you log in at www.example.org then end up on example.org, not logged in.You can still provide any number of aliases - but you should do it with an extra VirtualHost instead of many ServerAliases. Here is an example of how to do it right:

ServerName example.org
# Definitely, absolutely, NO ServerAliases in here
DocumentRoot /path/to/mahara/htdocs

ServerName www.example.org
# NOTE: ServerAliases are OK in this vhost block - if a client hits
# any host in this block they'll be redirected to the "main" wwwroot
ServerAlias mahara.example.org
Redirect permanent / http://example.org/

1. Another possibility (less likely) is that you have specified your dataroot incorrectly. Dataroot is an absolute path relative to the filesystem. It is NOT a URL, or part of one. It will also NOT work if it is a relative path.To work out where on the filesystem your Mahara is installed, if you can't find it some other way (like FTP), put a line in index.php like echo getcwd();.Your dataroot path then needs to be placed according to the normal rules, as documented in config-dist.php.

Q: My server will not allow PHP to send emails except through SMTP, how do I configure and test this?

A: The following process will step you through configuring and testing your SMTP based email messaging from a Mahara 1.1.1 installation:

1. First thing you need to do is look at email settings:

For Mahara 1.4 and above you may find them in Configure Site -> Site options -> Email.

For earlier versions Mahara use the config-default.php, found in the root folder of your Mahara site. Copy the following lines to your main config.php file and modify SMTP settings according to how your server or hosting service is set up:

// Mail handling
// If you want mahara to use SMTP servers to send mail, enter one or more here
// blank means mahara will use the default PHP method.
// $cfg->smtphosts = 'smtp1.example.com;smtp2.example.com';
// If smtp server uses port number different from 25 (e.g. for secure connections,
// port 465 is usually used with ssl, port 587 is usually used with tls),
// specify it below. Alternatively you may specify the port in smtphosts
// definition above using format [hostname:port] (e.g. 'smtp1.example.com:465').
// $cfg->smtpport = 25;
// If you have specified an smtp server above, and the server requires
// authentication, enter user credentials here:
// $cfg->smtpuser = '';
// $cfg->smtppass = '';
// If smtp server requres secure connection, specify the protocol type below.
// Valid options are '', 'ssl' or 'tls'. Setting it to '' or leaving the line
// commented means that secure connection will not be used.
// $cfg->smtpsecure = '';

2. Once that is set up, verify that you can send emails from that SMTP server BEFORE you even bother trying to test any emails from your Mahara site.  When you create an mailbox on your hosting service's email server, you specified a user name and a password.  Using your services webmail or other similar service, log into your SMTP mailbox and send a test email to anther email account, let's say a gmail account.  Once you are able to do that successfully, only then proceed with the following.

3. Your emails are not sent automatically from your Mahara site, instead they are lined up and sent at various times by a built-in cron system.  The instructions have already covered how to set up the cron on your server to hit your Mahara's cron system every minute, which in turn triggers its own built-in cron programs.  Since this is a new install, you may not be sure if cron is working correctly. If you have email problems, it can be confusing to determine which is at fault, the SMTP or the cron or both.  You can first try manually hitting your Mahara's cron system by typing the following:

/usr/bin/curl -s -v http://yoursite/lib/cron.php

Note that the above uses the -v or verbose flag to show you what it is doing. It should show you connecting to your site's cron.php file.

A typical cron system on a hosting service can be edited with a command such as:

EDITOR=nano crontab -e

That will bring up your cron file in the easy-to-use nano editor, which may start out empty if you have never added anything to it before.  If that does not work, check with yoru hosting service to find out their specific procedure. If that or similar command gets you into an edtor, type the following line:

* * * * * /usr/bin/curl -s </nowiki>http://yoursite/lib/cron.php

Save the file by hitting the key sequence and then exit teh editor by hitting the key sequence.

4. Now that it appears that a working cron is configured, the best way to test the Mahara email is by sending yourself a message through the contact us form.   The reason is that it is triggered very quickly by Marhara's cron system, and should therefore be sent to your admin user's email address within a minute or so. Note that other emails from the system, like notifications on new forum posts, can take a much longer time to be triggered by Mahara's cron.

5. If it does not work after giving it sufficient time to be triggered, sent, and received, the things to check are:

1. Make sure your admin email account is working - send it a test message from a gmail account or some other account.
2. If it is working, check the junk or spam folders for your contact us messages - they have been flagged before they got to your inbox.
3. Logged in as your admin user, click on the Profile tab in the menu, then click the settings button on the right (by the user picture), then click Notifications in the submenu. This should have a copy of all incoming messages of all types for the admin user.  See if your messages are showing up in there correctly.
4. Begin checking and changing the settings we already made for the SMTP and the cron.  Manually trigger the cron after each setting change, then retest the contact us form. Then recheck your email inbox, spam, and also the Notifications log. Repeat until your figure out the problem, which is probably a typo or something like authentication settings for the SMTP.
5. If you work systematically , making notes as you go through each combination your have tried, it will be easier to debug the problem and/or ask for help in the forums. In the forums, give enough detail of your settings and tests, but do not compromise your passwords.

Q: My installation hangs and never finishes

A: Your installation is probably exceeding PHP's max_execution_time limit. To fix open your php.ini file and change the following line:

max_execution_time = 30

to:

max_execution_time = 120

then restart your Apache server. You can reset this variable once installation is complete if you wish.

Q: Mahara is complaining about collation or UTF8 in MySQL

A: This forum post might be helpful.

1) Make a backup of the database using mysqldump

2) Add the following lines to the beginning of the mysql dump file:

drop database mahara_dev;
 create database mahara_dev character set UTF8;
 use mahara_dev;

3) mysql -h -u -pxxxxxx < your_dump.sql

4) Refresh browser

Q: The install is telling me that it needs javascript even though my browser has javascript enabled!

A: Re-copying all the files to the server seems to fix this.

Q: I'm trying to go to my mahara site, but I see something like "connection attempt to localhost was rejected" instead!

A: Check that your setting for $cfg->wwwroot has the correct protocol specified. https://localhost/mahara/ is not the same as http://localhost/mahara/. Remove the extra 's' and things should work.

What is happening is that mahara is starting happily, and the settings are then telling it to make sure all the URLs begin with https://localhost/mahara/. If there is not an SSL version of the site, it will not be able to connect.

Q: I see "Your PHP session.entropy_length setting is too small. Set it to at least 16 in your php.ini [...]"

A:This notice is only a warning that to let you know that you're not maximising your use of the mahara security features. Things will still work ok; this being low or unset does not stop things from working.

To set this, you need to edit your php.ini file to have a session.entropy_length setting with a number of 16 or higher.

If you are using windows, c:\windows\php.ini may be where the ini file is.

If you are using linux, this may also, but is likely at /etc/php5/apache2/php.ini

If you cannot edit your php.ini, you can try using a .htaccess file. This page tells you how to set php configuration in a .htaccess file.

If you're on shared hosting, you may be unable to do any of this, and you will need to ask the support staff to help you. It is in their best interests to help you, as this makes your site more secure, and less likely to cause problems on their server.

But don't worry too much if you cannot resolve this; if you cannot, you can simply ignore the warning.

Q: If I've locked myself out, how can I reset the password for my user?

A: From Mahara 1.4 onwards you can no longer use cleartext passwords, but when you have access to the server and need to reset the password for an account, you can temporarily install a little php script like this to reset someone's password, for example, for user 123:

<?php
define('INTERNAL', 1);
define('PUBLIC', 1);
require('init.php');
require_once('auth/lib.php');
$user = get_record('usr', 'id', 123);
$user->password = 'changeme';
reset_password($user);

Put this code in a new file in the htdocs directory. To make this reset the password, assuming you called the file mypasswordscript.php, you can then point your browser to your.mahara.url/mypasswordscript.php. It will show a blank screen but the password change will have happened.

IMPORTANT!: Don't forget to remove the script afterwards!

Q: I'm still having trouble, how can I get more help?

A: Two options available to you are:

• The forums, here on mahara.org
• The #mahara IRC channel on irc.freenode.org