Configuration file: Difference between revisions

From MoodleDocs
m (spelling)
(→‎Setting $CFG->wwwroot correctly: css scripts -> CSS and JavaScript)
 
(18 intermediate revisions by 14 users not shown)
Line 1: Line 1:
{{Installing Moodle}}
{{Installing Moodle}}
The name for Moodle's configuration file is config.php. The file is located in the moodle directory. It is not included in the Moodle download packages and is created by the installation process from the template file config-dist.php (which is included in Moodle packages).
The name for Moodle's '''configuration file''' is config.php. The file is located in the moodle directory. It is not included in the Moodle download packages and is created by the installation process from the template file config-dist.php (which is included in Moodle packages).




Line 7: Line 7:


To get started simply copy config-dist.php to config.php, then edit config.php with you favourite editor. The file is very well commented. The important options (which you must supply) are all nearer the top. Other less common options are further down.
To get started simply copy config-dist.php to config.php, then edit config.php with you favourite editor. The file is very well commented. The important options (which you must supply) are all nearer the top. Other less common options are further down.
==Setting $CFG->wwwroot correctly==
This setting must be a fixed URL (a string constant) that points to your site. Do not try to set this with any PHP code that can generate a variable URL. This is not supported, can cause strange problems and will stop command line scripts working completely. If your site is accessed from different IP addresses this should be done with a split DNS, see [[Masquerading]]
If you change your site from http to https, you '''MUST''' update this setting. If you don't, you will have problems - for example (but not limited to) CSS and JavaScript won't load properly and you will also experience problems with logging in to your site. Also see [[Transitioning to HTTPS]]


==Enabling password salting==
==Enabling password salting==
Line 14: Line 19:
==Including passwords in backups==
==Including passwords in backups==


Hashed user passwords are no longer saved in backup files containing user data in Moodle 1.8.11 and 1.9.7 onwards.
Hashed user passwords are no longer saved in backup files containing user data.
 
If you really need passwords to be saved (in the rare case of restoring a [[Backup of user data|backup with user data]] to a different site), the following line may be added to config.php:
 
$CFG->includeuserpasswordsinbackup = true;


If you really need passwords to be saved (in the rare case of restoring a backup with user data to a different site), the following line may be added to config.php:
Note regarding restoring Moodle 2.5 backups to sites with old PHP versions:


$CFG->includeuserpasswordsinbackups
Because bcrypt is not supported in PHP versions below 5.3.7, course backups made using the $CFG->includeuserpasswordsinbackup setting on a site using PHP version 5.3.7+ that are subsequently restored to a site with PHP version < 5.3.7 will require a password reset.


==Changing default block layout for new courses==
==Changing default block layout for new courses==
Line 24: Line 33:
See [[Block layout]].
See [[Block layout]].


==Changing default theme directory location==
==Adding extra theme directory location==
The location of theme directories may be altered, using the variables ''$CFG->themewww'' and ''$CFG->themedir''. Themes from placed in the directory specified by these variables will then be available for selection using the theme selector.
It is possible to add an extra themes directory stored outside of $CFG->dirroot. This local directory does not have to be accessible from internet. Themes placed in the directory specified by these variables will then be available for selection using the theme selector.


For example, should you wish to place themes in a subdirectory called 'my_moodle_themes', your config.php might look like this:
For example, should you wish to place extra themes in a subdirectory called 'my_moodle_themes', your config.php might look like this:
<pre>
<pre>
$CFG->wwwroot  = 'http://my.moodle.site.edu';
$CFG->wwwroot  = 'http://my.moodle.site.edu';
$CFG->dirroot  = '/var/www/my.moodle.site.edu/public_html';
$CFG->dirroot  = '/var/www/my.moodle.site.edu/public_html';
$CFG->themewww  = $CFG->wwwroot . '/my_moodle_themes';
$CFG->themedir  = $CFG->dirroot . '/my_moodle_themes';
$CFG->themedir  = $CFG->dirroot . '/my_moodle_themes';
</pre>
</pre>
Line 38: Line 46:


See [[Notifications]].
See [[Notifications]].
==Enabling debugging==
See [[Debugging]].
==Forcing the value of admin settings==
As explained in config-dist.php, it is possible to specify normal admin settings here, the point is that they can not be changed through the standard admin settings pages any more. Just set the value in config.php like:
<syntaxhighlight lang="php">
$CFG->showuseridentity = 'email,idnumber,username';
$CFG->preventexecpath = true;
$CFG->pathtodu = "/usr/bin/du";
$CFG->pathtodot = "/usr/bin/dot";
$CFG->pathtogs = "/usr/bin/gs";
</syntaxhighlight>
Configuration for plugins can also be forced by the syntax is different, e.g. continuing the example above for security to always hard coded paths to all executable files:
<syntaxhighlight lang="php">
$CFG->forced_plugin_settings['filter_tex']['pathconvert'] = '/usr/bin/convert';
$CFG->forced_plugin_settings['filter_tex']['pathdvips']  = '/usr/bin/dvips';
$CFG->forced_plugin_settings['filter_tex']['pathdvisvgm'] = '/usr/bin/dvisvgm';
$CFG->forced_plugin_settings['filter_tex']['pathlatex']  = '/usr/bin/latex';
</syntaxhighlight>


==See also==
==See also==
Line 44: Line 77:


[[de:Konfigurationsdatei]]
[[de:Konfigurationsdatei]]
[[es:config.php]]
[[fr:Fichier de configuration]]
[[fr:Fichier de configuration]]
[[ja:設定ファイル]]
[[ja:設定ファイル]]

Latest revision as of 08:53, 28 October 2023

The name for Moodle's configuration file is config.php. The file is located in the moodle directory. It is not included in the Moodle download packages and is created by the installation process from the template file config-dist.php (which is included in Moodle packages).


config-dist.php

Although the installation process creates the config.php file for you, there may be times when you want to do this yourself. A sample config file, called config-dist.php, is shipped with Moodle.

To get started simply copy config-dist.php to config.php, then edit config.php with you favourite editor. The file is very well commented. The important options (which you must supply) are all nearer the top. Other less common options are further down.

Setting $CFG->wwwroot correctly

This setting must be a fixed URL (a string constant) that points to your site. Do not try to set this with any PHP code that can generate a variable URL. This is not supported, can cause strange problems and will stop command line scripts working completely. If your site is accessed from different IP addresses this should be done with a split DNS, see Masquerading

If you change your site from http to https, you MUST update this setting. If you don't, you will have problems - for example (but not limited to) CSS and JavaScript won't load properly and you will also experience problems with logging in to your site. Also see Transitioning to HTTPS

Enabling password salting

See Password salting.

Including passwords in backups

Hashed user passwords are no longer saved in backup files containing user data.

If you really need passwords to be saved (in the rare case of restoring a backup with user data to a different site), the following line may be added to config.php:

$CFG->includeuserpasswordsinbackup = true;

Note regarding restoring Moodle 2.5 backups to sites with old PHP versions:

Because bcrypt is not supported in PHP versions below 5.3.7, course backups made using the $CFG->includeuserpasswordsinbackup setting on a site using PHP version 5.3.7+ that are subsequently restored to a site with PHP version < 5.3.7 will require a password reset.

Changing default block layout for new courses

See Block layout.

Adding extra theme directory location

It is possible to add an extra themes directory stored outside of $CFG->dirroot. This local directory does not have to be accessible from internet. Themes placed in the directory specified by these variables will then be available for selection using the theme selector.

For example, should you wish to place extra themes in a subdirectory called 'my_moodle_themes', your config.php might look like this:

$CFG->wwwroot   = 'http://my.moodle.site.edu';
$CFG->dirroot   = '/var/www/my.moodle.site.edu/public_html';
$CFG->themedir  = $CFG->dirroot . '/my_moodle_themes';

Disabling update notifications

See Notifications.

Enabling debugging

See Debugging.

Forcing the value of admin settings

As explained in config-dist.php, it is possible to specify normal admin settings here, the point is that they can not be changed through the standard admin settings pages any more. Just set the value in config.php like:

$CFG->showuseridentity = 'email,idnumber,username';
$CFG->preventexecpath = true;
$CFG->pathtodu = "/usr/bin/du";
$CFG->pathtodot = "/usr/bin/dot";
$CFG->pathtogs = "/usr/bin/gs";

Configuration for plugins can also be forced by the syntax is different, e.g. continuing the example above for security to always hard coded paths to all executable files:

$CFG->forced_plugin_settings['filter_tex']['pathconvert'] = '/usr/bin/convert';
$CFG->forced_plugin_settings['filter_tex']['pathdvips']   = '/usr/bin/dvips';
$CFG->forced_plugin_settings['filter_tex']['pathdvisvgm'] = '/usr/bin/dvisvgm';
$CFG->forced_plugin_settings['filter_tex']['pathlatex']   = '/usr/bin/latex';

See also