Appendix: Configuration Settings
This appendix on configuration settings aims to provide you with a list of parameters that can be modified in config.php and the impact each value will have.
We will first examine config.php and explore what types of parameters are supported by Moodle. After providing this overview, we will look at two types of configuration settings:
- Administration settings: These variables are available via the Site administration menu but can be locked with values specified in config.php.
- System settings: We distinguish between default and supplementary configuration values. The former will have been created by the installer and are mostly required for Moodle to function; the latter are parameters that change various Moodle behaviors.
Configuration reference – an overview
The config.php configuration file contains several settings and variables that heavily influence how Moodle operates. It is located in the main directory of your Moodle system ($CFG->dirroot) and can be edited with any text editor.
Important note
Be careful when modifying config.php! Moodle depends heavily on its content, and any faults can cause the software to malfunction.
You should create a backup of the config file before modifying it, so you can roll back to it in case of problems. Also, ensure the file permissions are correctly set, as the file contains the plain-text database username and password. In a Linux environment, the owner should be root, the group also root, and the permissions set to 644. A sample configuration file is shown in the following screenshot:
Figure A.1 – Sample config.php file
The config.php values we are interested in are the ones that start with a dollar symbol. Each parameter has the following information format:
$<object>-><parameter> = <value>;
The <object> parameter is the part of Moodle in which the parameter is used ($CFG or $THEME). Third-party modules or custom distributions might have introduced their own objects—for example, $TOTARA. We will focus on $CFG objects as these are most relevant to administrators.
<parameter> is the name of the configuration setting. Each setting has a unique identifier.
The <value> parameter must be of the type the parameter accepts, which depends on the type of the setting. The following table provides information for each of the types:
Figure A.2 – Data types supported in configuration settings
Each parameter has to be terminated by a semi-colon. To comment out a parameter, precede it with two forward slashes.
Before we deal with the different settings, we’ll discuss some tools that might come in useful. As there is no list of available settings, you have to generate your own. To do so, execute the following shell command in your $CFG->dirroot:
grep -r -h -o '$CFG->[a-z][[:alnum:]_]*' . | sort -u
This concatenated set of commands will generate a list of all available $CFG variables in alphabetical order. The moosh config-get command (see Chapter 17, Working with Moodle Admin Tools) only provides you with a list of all config variables that can be set via Moodle’s admin interface and are stored in mdl_config; it excludes the hidden variables we are interested in here.
Moodle provides a report that lets you monitor all changes to any config settings via the administration interface. You can find the report at Site administration | Reports | Config changes.
Figure A.3 – Config changes report
The table shows any changes made to settings in the Site administration section. For each modification, Date, First name / Surname, Plugin, Setting, New value, and Original value are shown.
If you are experimenting with configuration variables, consider using the site admin presets we discussed in Chapter 17, Working with Moodle Admin Tools. The tool lets you create backups of site settings, which can then be rolled back if something goes wrong.
Configuration reference – administration settings
Each parameter in the Site administration menus can be configured via config.php. If a value has been set via this method, it is effectively hardcoded and cannot be changed via the Moodle interface, not even by the administrator.
For example, you might want to ensure that an administrator does not turn on HTTPS for logins on an internal site, even by accident. Activating this would lock everybody out of the site if no SSL certificate is installed. To do this, enter the following line in config.php:
$CFG->loginhttps=false;
How do you know what the parameter is called? Go to the respective setting in Moodle (in this case, Site administration | Security | HTTP security), and you will see the parameter’s name underneath the label.
Tip
You can search for any parameter in the search box of the administration menu.
If the value is specified in config.php, Moodle will display Defined in config.php beside the parameter, which indicates that the setting cannot be changed via the admin interface. Invalid values are also shown for these hardcoded settings. In the following screenshot, the Debug messages value is incorrect while the Display debug messages value is correct:
Figure A.4 – Hardcoded configuration settings
If you wish to force plugin settings, you must put them in a special array called forced_plugin_settings (see the reference to optional parameters later).
Configuration reference – system settings
This section contains the actual reference for configuration settings; the explanations have been taken from help pages, forum posts, and comments in the source code.
Default parameters
Default parameters are settings created by the installer, derived from config-dist.php. Most settings are compulsory for Moodle to operate, so be careful when modifying them. The parameters are listed in the order in which they appear by default in config.php:
Figure A.5 – config.php default parameters
In addition to the default parameters, there are hundreds of optional parameters, some of which we will deal with in the following subsection.
Optional parameters
There are over 300 config.php parameters that cannot be modified via the Moodle administrator interface. These hidden settings allow you to modify the behavior of Moodle without the requirement to change any code.
We only cover a representative list of settings, ignoring those that are only relevant to developers and designers. We have also disregarded obsolete and obscure parameters and ones that have a counterpart in the admin settings. Parameters have been listed in alphabetical order, and some have been grouped for simplicity.
Available types are Array, Binary, Numeric, List, and String:
|
Name |
Type |
Description | ||||||||
|
adhoctaskageerror adhoctaskagewarn |
N |
Moodle checks how old tasks are in the ad hoc queue and warns at 10 minutes and errors at 4 hours. | ||||||||
|
admineditalways |
B |
When set to true, enables admins to edit any post at any time. | ||||||||
|
apacheloguser |
N |
Logging Apache: 0 = off, 1 = user id, 2 = full name, 3 = username. | ||||||||
|
apachemaxmem |
N |
Memory threshold over which Apache children will be reaped after they complete serving the request. | ||||||||
|
backuptempdir |
S |
It is possible to specify a different backup temp directory. Use a local (fast) filesystem for normal web servers. Server clusters must use a shared filesystem for backuptempdir. The directory must not be accessible via the web. | ||||||||
|
bounceratio |
N |
The default is 20. See $CFG->handlebounces. | ||||||||
|
customfiletypes |
A |
Adding entries to Site administration | Server | File types, for instance.
| ||||||||
|
customfrontpageinclude |
S |
You can replace the home page with your own version. moodle.org uses this approach. Only the center area will be replaced, not the header, footer, or blocks. | ||||||||
|
Name |
Type |
Description | ||||||||
|
customscripts |
S |
Enabling this will allow custom scripts (to be specified with the full path name) to replace existing moodle scripts. For example, if $CFG->customscripts/course/view.php exists, then it will be used instead of $CFG->wwwroot/course/view.php. Currently, this will only work for files that include config.php and are called as part of the URL (index.php is implied). Custom scripts should not include config.php. Warning: Replacing standard Moodle scripts may pose a security risk and/or may not be compatible with upgrades. However, this is useful when having to patch a particular page without actually overwriting the core code. | ||||||||
|
debugimap debugsmtp |
B |
Enable verbose debug information while sending email messages to the IMAP/SMTP server (requires $CFG->debug to be set to DEBUG_DEVELOPER). | ||||||||
|
debugusers |
S |
Comma-separated list of user IDs that always see debug messages. | ||||||||
|
defaultblocks |
A |
Default block variables for new courses, for instance, participants, activity_modules, search_forums, admin, course_list, news_items, calendar_upcoming, recent_activity. This setting can be overridden for different course types, such as defaultblocks_social, defaultblocks_weeks, and defaultblocks_topics. | ||||||||
|
disablemycourses |
B |
This setting will prevent the My Courses page from being displayed when users log in. The home page will always show the same (logged-out) view. | ||||||||
|
disableonclickaddoninstall |
B |
Disable the plugin installation feature and hide it from the server administration user interface. | ||||||||
|
disablestatsprocessing |
B |
Prevent stats processing and hide the GUI. | ||||||||
|
disableupdateautodeploy |
B |
Disables update deployment. Useful when deployment is done via Git checkouts. | ||||||||
|
disableupdatenotifications |
B |
Disables update notifications. Useful when deployment is done via Git checkouts. | ||||||||
|
Name |
Type |
Description | ||||||||
|
disableusercreationonrestore |
B |
Completely disable user creation when restoring a course. Enabling this setting results in the restore process stopping when a user attempts to restore a course requiring users to be created. | ||||||||
|
divertallemailsto |
S |
Divert all outgoing emails to this address to test and debug emailing features. | ||||||||
|
emailconnectionerrorsto |
S |
Email database connection errors to someone. If Moodle cannot connect to the database, email this address with a notice. | ||||||||
|
expectedcronfrequency |
N |
Moodle checks that the cron is running frequently. If the time between cron runs exceeds this value (in seconds), you get a warning on the admin page. This setting only controls whether or not the warning appears; it has no other effect. | ||||||||
|
filedir |
S |
You can specify an alternative to dataroot. | ||||||||
|
filelifetime |
N |
Seconds for files to remain in caches (default is 86400, which equals 24 hours). Decrease this if you are worried about students being served outdated versions of uploaded files. | ||||||||
|
filepermissions |
Same as directorypermissions in the default parameters, but for created files. | |||||||||
|
forced_plugin_settings |
A |
Plugin settings have to be specified as an array of arrays: array('plugin1' => array('param1' => 'value1', ('param2' => 'value2', …), ('plugin2' => array('param1' => 'value1', ('param2' => 'value2', …), …); | ||||||||
|
forcedefaultmymoodle |
B |
If set, the My Moodle page cannot be customized by users. | ||||||||
|
forcefirstname forcelastname |
S |
To anonymize usernames for all students. If set, then all non-teachers will always see this for every person. | ||||||||
|
gradeoverhundredprocentmax |
N |
If unlimitedgrades is set, you can specify a maximum value (1 = 100%, default = 10). | ||||||||
|
handlebounces |
B |
This is for handling email bounces. Used in conjunction with minbounces and bounceratio. | ||||||||
|
httpswwwroot |
S |
wwwroot for SSL pages. | ||||||||
|
Name |
Type |
Description | ||||||||
|
includeuserpasswordsinbackup |
B |
Allow user passwords to be included in backup files. Use only if you can guarantee that all your backup files remain private, as password hashes can be unencrypted. | ||||||||
|
keeptempdirectoriesonbackup |
B |
Keep the temporary directories used by backup and restore without being deleted at the end of the process. See also the Managing courses in bulk section in Chapter 4, Managing Courses and Enrolments. | ||||||||
|
langlocalroot |
S |
Alternative directory to $CFG->dataroot/lang. | ||||||||
|
localcachedir |
S |
It is possible to specify different cache and temp directories. Use local (fast) filesystem for normal web servers. Server clusters must use a shared filesystem for cachedir. localcachedir is intended for server clusters; it does not have to be shared by cluster nodes. The directories must not be accessible via the web. | ||||||||
|
maildomain |
S |
Your email domain. | ||||||||
|
mailprefix |
S |
mdl+ is the separator for Exim and Postfix, mdl- is the separator for qmail. | ||||||||
|
minbounces |
N |
The default is 10. See $CFG->handlebounces. | ||||||||
|
mnetkeylifetime |
N |
The number of days until the networking key expires. See Chapter 19, Setting Up Moodle Networking, for details. | ||||||||
|
noemailever |
B |
When working with production data on test servers, no emails or other messages should ever be sent to real users. | ||||||||
|
opensslcnf |
S |
Location of the openssl.cnf file. | ||||||||
|
passwordsaltmain |
S |
Random string added to the md5 password hash. See Chapter 13, Ensuring Moodle Security, for details. | ||||||||
|
pdfexportfont |
S |
The font used in exported PDF files. When generating a PDF, Moodle embeds a subset of the font in the PDF file so it will be readable on the widest range of devices (the default is freesans). | ||||||||
|
preferlinegraphs |
B |
This setting will make some graphs (for instance, user logs) use lines instead of bars. | ||||||||
|
preventscheduledtaskchanges |
B |
Disable editing of tasks in Site administration | Server | Scheduled tasks. | ||||||||
|
reverseproxy |
B |
Enable when setting up advanced reverse proxy load balancing configurations and port forwarding. | ||||||||
|
showcrondebugging |
B |
Add debug info to cron output. | ||||||||
|
showcronsql |
B |
Show executed SQL queries during cron execution. | ||||||||
|
Name |
Type |
Description | ||||||||
|
skiplangupgrade |
B |
Disables automatic language update and lets translators (lang pack maintainers) keep their moodledata/lang/* to update manually. | ||||||||
|
sslproxy |
B |
Enable when using an external SSL appliance for performance reasons. | ||||||||
|
supportuserid |
N |
Emails to support can be redirected to another user. | ||||||||
|
tagsort |
S |
Sort tags in tag cloud by specified field; default = name. | ||||||||
|
themedir |
S |
Add an extra themes directory outside of $CFG->dirroot. | ||||||||
|
themeorder |
A |
Priority of themes from highest to lowest. The default is array('course', 'category', 'session', 'user', 'site'). | ||||||||
|
themerev |
B |
Prevent theme caching. | ||||||||
|
tracksessionip |
B |
Moodle will track the current user’s IP to ensure it hasn’t changed during a session. This will prevent the possibility of sessions being hijacked via XSS, but it may break things for users using proxies that change frequently. | ||||||||
|
trashdir |
S |
Alternative location for $CFG->dirroot/trashdir. | ||||||||
|
undeletableblocktypes |
A |
The blocks in this list are protected from deletion, for example, navigation,settings. | ||||||||
|
uninstallclionly |
B |
This stops admins from uninstalling plugins from the admin user interface and forces plugins to be uninstalled from the command-line tool only, found at admin/cli/plugin_uninstall.php. | ||||||||
|
upgradekey |
S |
Password protection during the upgrade process. See docs.moodle.org/en/Upgrade_key for details. | ||||||||
|
upgraderunning |
B |
Pretend Moodle update is running. | ||||||||
|
upgradeshowsql |
B |
Show executed SQL queries during upgrades. | ||||||||
|
usezipbackups |
B |
Use ZIP compression in backups instead of default TGZ. | ||||||||
|
wordlist |
S |
List words used by Moodle’s Word censorship filter. |