17. Config.php variables¶
Some site options cannot be set in the administration area but need to be updated directly on the server in the config.php file. In this section, you see the settings that are possible and why you might want to include them in your config.php file for your site.
Note
Some of the config parameters have an equivalent setting in the Administration area. If you set a value explicitely in your config.php file, it overwrites any value entered in the administration, and the field becomes unavailable for editing.
The config.php file sits in the /htdocs directory of your site. If you want to view all possible variables and their default values, you can find them in /htdocs/lib/config-defaults.php. You can overwrite any default values by placing the variable in your config.php file.
17.1. Anatomy of a config variable¶
A configuration variable needs to be written in the correct syntax in order to function. In Mahara, this is done the following way: $cfg->variable = value;.
A typical configuration variable¶
$cfg->: Stands for ‘configuration’ and indicates that what follows is a configuration variable.
variable =: Here you see the variable that is to be set. Generally, it consists of one word, or words are joined together with underscores. The variable cannot contain any spaces.
value;: The value that the variable takes is displayed. The values can be different things, for example:
‘true’ or ‘false’
text
numbers
file path
Note
If you want to change the default behaviour of a variable in your instance of Mahara, copy it from the config-defaults.php file into your config.php file so it won’t get overwritten when you update the codebase. The config.php file is never changed by an update or upgrade of Mahara.
17.2. accesslistmaximum: Restrict number of access list rules¶
$cfg->accesslistmaximum = 1;
Restrict with how many people or groups of people a personal portfolio can be shared. This setting does not affect portfolio sharing on the group, institution, and site levels.
When the access restriction is in place, an alert is presented letting the portfolio author know that they can share their portfolio only with a limited number of people or groups of people. Groups of people include ‘Registered’ and ‘Public’ access.
Note
Secret URLs are not affected by this restriction. This setting is best used for sites that do not allow the use of secret URLs to control with whom portfolios can be shared.
Restrict the number of people to share a portfolio with¶
An alert indicates with how many people or groups of people the personal portfolio can be shared.
When the limit has been reached, it is not possible to add new access rules.
17.3. 
allow_copy_blocks: Copy blocks on the same page¶
$cfg->allow_copy_blocks = false; (default) or $cfg->allow_copy_blocks = true;
If you set the block copying option to ‘true’, portfolio authors see an additional icon in ‘Edit mode’, the Make a copy icon on every block. This makes it easy to copy an existing block on the same page.
The Make a copy icon is displayed on each block when block copying is allowed on the site level.¶
Note
Currently, the functionality is restricted to copying of blocks on to the same page. It also needs to be enabled in the config.php file because the Mahara product team wants to gather more feedback on the usefulness of the feature and whether to roll it out by default, make it an account setting, only allow it on certain page types etc.
17.4. developermode: Enable or disable developer mode¶
The developer mode is not available any more since MochiKit was removed a while ago.
17.5. directorypermissions: Permissions to use in dataroot¶
$cfg->directorypermissions = 0700; (default)
You can set what permissions are used for files and directories in the Mahara dataroot. The default allows only the web server account to read the data. If you are on shared hosting and might want to download the contents of your dataroot later, e.g. for backup purposes, set this to 0755. Otherwise, leave it as is.
17.6. error_reporting: Error reporting¶
$cfg->error_reporting = E_ALL & ~E_STRICT; (default)
This parameter indicates what level of errors to print to the Mahara logs. It gets passed directly to the PHP function error_reporting().
Note
There are some limitations in this method because it doesn’t get called until several scripts have already been compiled: init.php, config.php, config-defaults.php, errors.php, and the file directly invoked in the URL. So, compile-time errors in those files, which includes most strict errors, will be unaffected by this setting.
17.7. externallogin: Login via another site¶
$cfg->externallogin = 'URL';
You can overwrite the normal Mahara login page by providing an external one. This is useful if all people with access to the site shall log in via a different system and should be redirected there automatically.
Note
Be careful when you have multiple institutions turned on. If at least one institution does not log in via the same external login page, you cannot use this setting as people in that institution would not be able to log in to Mahara at all since they can never get to the login page that they need.
If you use the external login, you may need to override it at times, e.g. for troubleshooting the external authentication method or when it is not reachable. You can add a parameter at the end of the Mahara URL. You are then taken to the normal Mahara login screen.
The parameter is ?override=true
For example, https://mahara.example.com/admin/users/search.php ?override=true
Note
It doesn’t matter what value you add. You can use ‘true’ or ‘1’ or anything else.
17.9. isolatedinstitutions: Separate institutions entirely¶
$cfg->isolatedinstitutions = false; (default) or $cfg->isolatedinstitutions = true;
If you have a multi-tenanted Mahara instance but do not want people from the individual institutions to communicate on the site or share groups, you can turn on ‘Isolated institutions’.
This can be beneficial when you set up a large site for several organisations and need to adhere to privacy regulations that don’t allow people from one organisation to contact people from other organisations.
See also
See the section ‘Isolated institutions’ for more information.
17.10. log_backtrace_levels: Log backtraces¶
For example: $cfg->log_backtrace_levels = LOG_LEVEL_WARN | LOG_LEVEL_ENVIRON; (default)
The log levels that will generate backtraces. Useful for development, but probably only warnings are useful on a live site.
17.11. log_backtrace_print_args: Log backtraces¶
$cfg->log_backtrace_print_args = null; (default)
Print the values of function and method arguments when printing a backtrace. This can be useful for debugging, but it is a security risk because function parameters may include sensitive data such as passwords and private keys. Though arguments whose names suggest that they contain passwords, will still be blanked out even if this feature is enabled.
A null value here tells Mahara to hide argument values when $cfg->productionmode is enabled, and to show them otherwise. A true or false tells Mahara to always show or hide argument values in backtraces regardless of the value of $cfg->productionmode.
17.12. log_file: File containing error messages¶
$cfg->log_file = '/path/to/dataroot/error.log';
If you use LOG_TARGET_FILE, this is the file to which errors will be logged. By default, it will write to the file error.log under the dataroot. If you change this in config.php, make sure you use a folder which is writable by the web server.
17.13. log targets: Destination for log information¶
Typical production environment:
$cfg->log_dbg_targets = LOG_TARGET_ERRORLOG;$cfg->log_info_targets = LOG_TARGET_ERRORLOG;$cfg->log_warn_targets = LOG_TARGET_ERRORLOG;Typical non-production environment:
$cfg->log_dbg_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;$cfg->log_info_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;$cfg->log_warn_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;$cfg->log_environ_targets = LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG;There are 4 different types of log messages that you can log to an error log and / or display on screen:
dbg: Debugging messages
info: Informational messages
warn: Warning messages
environ: Environment errors
You can log the different messages to different destinations:
LOG_TARGET_SCREEN: Display error messages on the screen. This is useful during testing and when debugging, but should not be used on a live site.
LOG_TARGET_ADMIN: Show error messages on the screen, but only when you are in the Administration area.
LOG_TARGET_ERRORLOG: Send log information to the error log as specified in your Apache configuration. It is recommended to use this setting for all log levels no matter the other targets that you specified.
LOG_TARGET_FILE: This allows you to specify a file to which messages will be logged. It’s best to pick a path in dataroot, but note that log files tend to get very large over time. So it’s advisable to implement some kind of logrotate if you want to leave this on all the time. The other option is to just turn this option on when you are getting a specific error or want to see the logging, and know that you’re not going to let the log file get large.
You can combine the targets with bitwise operations, e.g. LOG_TARGET_SCREEN | LOG_TARGET_ERRORLOG.
17.14. noreplyaddress: System email address¶
$cfg->noreplyaddress = 'noreply@yourdomainhere';
Set the system mail address. Notifications are sent from this address (except for a few emails when a person doesn’t yet have an account). You can also set it in Administration menu → Configure site → Site options → Email settings.
Typically, the noreply address is one that is not monitored as people are not supposed to reply to it.
17.15. openbadgedisplayer_source: Open Badges displayer sources¶
$cfg->openbadgedisplayer_source = '{"shortname":"url","shortname":"url"}';
In order to display Open Badges in the ‘Open Badges’ block, the sites that host the badges need to be configured. Per default, the Mozilla Backpack and the Open Badge Passport can be connected. If you have other sources, you would need to add them to the allowed sources.
Badgr can be configured as well.
The configuration variable for The Backpack, the Open Badge Passport, and Badgr looks like the following:
$cfg->openbadgedisplayer_source = '{"backpack":"https://backpack.openbadges.org/","passport":"https://openbadgepassport.com/","badgr":"https://api.badgr.io/"}';
17.16. passwordsaltmain: Set a site-wide password salt¶
$cfg->passwordsaltmain = 'your secret phrase here';
A password salt helps ‘hash’ passwords more securely in the database to make hacking them more difficult. Using a phrase is a good start. Passwords are already not displayed in plain text in the database, they are hashed. The salt helps randomise that even more.
If you don’t have a password salt set, you see a warning on the ‘Admin home’ page.
17.17. pathtoclam: Path to virus scanner ClamAV¶
$cfg->pathtoclam = '/path/to/your/clamscan';
If you are running the antivirus engine ClamAV on your server and don’t scan for viruses on the system level, you can let Mahara know where to find it so files that are uploaded are scanned. For security reasons, the path to ClamAV on your server needs to be provided in the config.php file.
You can see the path that has been set in the ‘Security settings’.
17.18. probationenabled: Give people probation status¶
$cfg->probationenabled = true; or $cfg->probationenabled = false;
If $cfg->probationenabled = true;, you should set $cfg->probationstartingpoints = 2; as well.
You can set a spam probation level for your account holders to prevent self-registered ones from posting spam especially on a public site. Use the following two variables to do that:
$cfg->probationenabled = true;: This setting decides whether people can be put on probation.$cfg->probationstartingpoints = 2;: This setting determines how many probation points a newly self-registered person has per default. In this example, people would get two probation points that they need to get rid off before all functionality is available to them.
You can change the probation points individually on the person’s account settings page displayed by clicking on a person’s username in Administration menu → People → People search.
When you enable probation, people who leave comments on a page or artefact and are not logged in, cannot post URLs either.
17.19. productionmode: Enable or disable production mode¶
$cfg->productionmode = true; or $cfg->productionmode = false;
If production mode is disabled, a message is displayed at the top of the screen alerting to that effect.
Info message when site is not in prodution mode¶
A number of parameters are overridden with sensible defaults for a testing or development site. For the current list of parameters, please see init.php. These settings include:
Print debug, information and warning messages as well as environment targets to the screen and the error log. This helps to see error messages quickly as they appear directly on the screen.
Turn on developer mode.
Disable cache.
Note
Paradoxically, you will need to set productionmode=true if you want to fine-tune your settings on a test / development site because productionmode=false overrides a lot of settings with sensible developer mode defaults.
17.20. remoteavatarbaseurl: Remote avatar server URL¶
$cfg->remoteavatarbaseurl = 'https://example.com/avatar/';
Profile pictures of your account holders can be pulled from an avatar service such as Gravatar. If you run your own service. e.g. Libravatar, you can point Mahara directly to it with this configuration variable.
You decide in the ‘Account settings’ whether remote avatars can be displayed or not.
17.21. renamecopies: Rename copied pages and collections¶
$cfg->renamecopies = true; or $cfg->renamecopies = false;
The site administrator can decide to add ‘Copy of…’ for copied pages and collections. If $cfg->renamecopies = true;, copies of new pages and collections will have ‘Copy of’ prepended to their titles. The default setting is $cfg->renamecopies = false;.
17.22. saml_log_attributes: Log SAML attributes¶
$cfg->saml_log_attributes = false; (default) or $cfg->saml_log_attributes = true;
When the connection between Mahara and an SSO IdP needs to be investigated, it helps to see what attributes are being sent from the IdP. By setting this variable to ‘true’, the attributes are logged into the table ‘usr_login_saml’.
Warning
Once the diagnostics have been performed and the problem fixed, set this variable back to ‘false’ and clear the table.
17.23. sendemail: Send emails¶
$cfg->sendemail = true; or $cfg->sendemail = false;
Decide whether you want to send emails from your instance of Mahara. If set to false, Mahara will not send any emails. This is useful when setting up a non-production instance of Mahara with real data where you don’t want to accidentally send email to people from this particular Mahara instance.
17.24. sendallemailto: Send all emails to one address¶
$cfg->sendallemailto = 'you@yourdomain';
You can use this setting to have all emails from this instance of Mahara sent to one particular email address instead of their real recipients. Leave $cfg->sendemail = true; if you want to use this setting.
This setting is handy for test instances when you want to replicate an issue or test a new feature with real data, but do not want people to receive notifications accidentally.
17.25. sessionhandler: Select the session handler¶
$cfg->sessionhandler = 'file'; or $cfg->sessionhandler = 'memcached'; or $cfg->sessionhandler = 'redis';
Mahara supports three different session handlers:
file storage
Memcached
Redis
Memcached and Redis are recommended for large sites as data is accessed more quickly. Redis is beneficial in a cluster environment.
Both Memcached and Redis require a few more configuration variables to be set. Please review /htdocs/lib/config-defaults.php for more information.
17.26. showloginsideblock: Show or hide the login sideblock¶
$cfg->showloginsideblock = true; or $cfg->showloginsideblock = false;
You can hide the login form by adding the value $cfg->showloginsideblock = false; to your config.php file. Once you have done that, only a link to the login form is displayed for an administrator or others with internal Mahara accounts to log into the site.
Link to the login form¶
This is useful if you have single sign-on set up and automatically log in to Mahara via another site.
Per default, the value is set to ‘true’ so that the login sideblock is displayed.
17.27. sitethemeprefs: Choose your browse theme from any theme¶
$cfg->sitethemeprefs = true; or $cfg->sitethemeprefs = false;
If the site administrator allowed it, you can choose any theme that is available to you as your browse theme on your ‘Account settings’ page. In that case, you are not restricted to only use your institution theme or if you are a member of multiple institutions choose between them.
17.28. skins: Skins¶
$cfg->skins = true; or $cfg->skins = false;
You can allow your portfolio authors to personalise their portfolio pages beyond choosing a theme. This is done via skins in Mahara. Skins can be created on the site level or by individuals. Institutions can allow or deny the use of skins for their members.
17.30. usepdfexport: PDF export¶
$cfg->usepdfexport = true; or $cfg->usepdfexport = false;
Note
This is an experimental feature.
It is possible to allow the export of entire accounts or individual pages and collections into PDFs. This requires additional software to be installed on the server, which can be done by running make pdfexport.
In addition, the ‘usepdfexport’ option in the config.php file needs to be set as it does require additional software.
Once the software has been installed and the PDF export allowed in the config file, portfolios are exported as PDFs besides HTML and Leap2A.
17.31. usersuniquebyusername: The internal Mahara username prevails when connecting external authentication methods¶
$cfg->usersuniquebyusername = true; or $cfg->usersuniquebyusername = false;
This is an experimental feature. When turned on, this setting means that it does not matter which other application the a person SSOs from, they will be given the same account in Mahara as the internal username is matched and the remote username ignored.
17.32. validfiletypes: Restrict which file types can be uploaded¶
$cfg->validfiletypes = 'doc,docx,gif,jpeg,jpg,mp3,mp4,odt,pdf,png,zip'; (for example)
You can restrict which file types account holders can upload to the platform. This gives you control over the files that you allow, and which ones are not considered safe to upload.
When there is a file type restriction in place, this is mentioned in the file upload area. This does not affect sections in the administration area where you may need to upload CSV, MATRIX, or ZIP files.
See which file types you can upload if there is a restriction in place¶