Configuration file: Difference between revisions

From MoodleDocs
(→‎Enabling password salting: rewording + warning thanks to posters in discussion http://moodle.org/mod/forum/discuss.php?d=137889)
(→‎Setting $CFG->wwwroot correctly: css scripts -> CSS and JavaScript)
 
(44 intermediate revisions by 18 users not shown)
Line 1: Line 1:
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).
{{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).




==Sample config.php file==
==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. Here is a sample config.php file to work from.
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.


'''WARNING''': You may want to edit the config.php file directly if, for example, you change you database password or change servers completely. If you do so, be very careful that there are no spaces or line breaks after the final "?>" in the file. If there are such spaces, you may get blank pages.
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.


<pre><?php  /// Moodle Configuration File
==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]]


unset($CFG);
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]]
 
$CFG->dbtype    = 'mysql';
$CFG->dbhost    = 'localhost';
$CFG->dbname    = 'moodle17';
$CFG->dbuser    = 'moodleuser';
$CFG->dbpass    = 'xxxxxx';
$CFG->dbpersist =  false;
$CFG->prefix    = 'mdl_';
 
$CFG->wwwroot  = 'http://www.mymoodle.com/moodle';
$CFG->dirroot  = '/var/www/moodle';
$CFG->dataroot  = '/var/moodledata';
$CFG->admin    = 'admin';
 
$CFG->directorypermissions = 00777;  // try 02777 on a server in Safe Mode
 
$CFG->unicodedb = true;  // Database is utf8
 
require_once("$CFG->dirroot/lib/setup.php");
// MAKE SURE WHEN YOU EDIT THIS FILE THAT THERE ARE NO SPACES, BLANK LINES,
// RETURNS, OR ANYTHING ELSE AFTER THE TWO CHARACTERS ON THE NEXT LINE.
?></pre>


==Enabling password salting==
==Enabling password salting==


Moodle stores passwords as md5 strings. [http://en.wikipedia.org/wiki/Salt_%28cryptography%29 Password salting] adds some random string to passwords before their md5 hash is calculated to make them practically impossible to reverse.
See [[Password salting]].
 
To enable password salting, add the following line to your config.php:
 
$CFG->passwordsaltmain = 'some long random string here with lots of characters';
 
You can use the [http://dev.moodle.org/gensalt.php Moodle Salt Generator] to obtain a suitable long random string.
 
If you wish to change the salt, you must add it to config.php as follows:


$CFG->passwordsaltalt1 = 'old long random string';
==Including passwords in backups==
$CFG->passwordsaltmain = 'new long random string';


''Warning'': If you change the salt and do not include the old one in config.php you will no longer be able to login to your site!
Hashed user passwords are no longer saved in backup files containing user data.


If you import users from another Moodle site which uses a password salt, you need to add the other site's salt to config.php too.
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:


In addition to <code>$CFG->passwordsaltmain</code>, Moodle checks for all salts defined in variables
$CFG->includeuserpasswordsinbackup = true;


$CFG->passwordsaltalt1, $CFG->passwordsaltalt2, ...  $CFG->passwordsaltalt20
Note regarding restoring Moodle 2.5 backups to sites with old PHP versions:


''Note'': For security reasons the only way to enable password salting is by editing config.php - there is no way to do so in the Moodle interface.
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.


==The config-dist.php file==
==Changing default block layout for new courses==


The config-dist.php file is the template file. It contains the usual settings of a config.php file, with some additional settings that don't have a UI for them. To use these settings you have to add them to the configuration file.  
See [[Block layout]].


Here is the contents of the config-dist.php:
==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:
<pre>
<pre>
<?PHP // $Id: config-dist.php,v 1.97 2006/09/03 15:46:21 moodler Exp $
$CFG->wwwroot  = 'http://my.moodle.site.edu';
///////////////////////////////////////////////////////////////////////////
$CFG->dirroot   = '/var/www/my.moodle.site.edu/public_html';
//                                                                      //
$CFG->themedir  = $CFG->dirroot . '/my_moodle_themes';
// Moodle configuration file                                            //
</pre>
//                                                                      //
// This file should be renamed "config.php" in the top-level directory  //
//                                                                      //
///////////////////////////////////////////////////////////////////////////
//                                                                      //
// NOTICE OF COPYRIGHT                                                  //
//                                                                      //
// Moodle - Modular Object-Oriented Dynamic Learning Environment        //
//          http://moodle.org                                            //
//                                                                      //
// Copyright (C) 1999-2004  Martin Dougiamas  http://dougiamas.com      //
//                                                                      //
// This program is free software; you can redistribute it and/or modify  //
// it under the terms of the GNU General Public License as published by  //
// the Free Software Foundation; either version 2 of the License, or    //
// (at your option) any later version.                                  //
//                                                                      //
// This program is distributed in the hope that it will be useful,      //
// but WITHOUT ANY WARRANTY; without even the implied warranty of        //
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the        //
// GNU General Public License for more details:                          //
//                                                                      //
//          http://www.gnu.org/copyleft/gpl.html                        //
//                                                                      //
///////////////////////////////////////////////////////////////////////////
unset($CFG);  // Ignore this line
 
//=========================================================================
// 1. DATABASE SETUP
//=========================================================================
// First, you need to configure the database where all Moodle data      //
// will be stored.  This database must already have been created        //
// and a username/password created to access it.                        //
//                                                                      //
//  mysql      - the prefix is optional, but useful when installing    //
//                into databases that already contain tables.            //
//
//  postgres7  - the prefix is REQUIRED, regardless of whether the      //
//                database already contains tables.                      //
//                                                                      //
// A special case exists when using PostgreSQL databases via sockets.    //
// Define dbhost as follows, leaving dbname, dbuser, dbpass BLANK!:      //
//    $CFG->dbhost = " user='muser' password='mpass' dbname='mdata'";    //
//
 
$CFG->dbtype    = 'mysql';      // mysql or postgres7 (for now)
$CFG->dbhost    = 'localhost';  // eg localhost or db.isp.com
$CFG->dbname    = 'moodle';      // database name, eg moodle
$CFG->dbuser    = 'username';    // your database username
$CFG->dbpass    = 'password';    // your database password
$CFG->prefix    = 'mdl_';        // Prefix to use for all table names
 
$CFG->dbpersist = false;        // Should database connections be reused?
                // "false" is the most stable setting
                // "true" can improve performance sometimes
 
 
//=========================================================================
// 2. WEB SITE LOCATION
//=========================================================================
// Now you need to tell Moodle where it is located. Specify the full
// web address to where moodle has been installed.  If your web site
// is accessible via multiple URLs then choose the most natural one
// that your students would use.  Do not include a trailing slash
 
$CFG->wwwroot  = 'http://example.com/moodle';
 
 
//=========================================================================
// 3. SERVER FILES LOCATION
//=========================================================================
// Next, specify the full OS directory path to this same location
// Make sure the upper/lower case is correct. Some examples:
//
//    $CFG->dirroot = 'c:\program files\easyphp\www\moodle';   // Windows
//    $CFG->dirroot = '/var/www/html/moodle';     // Redhat Linux
//    $CFG->dirroot = '/home/example/public_html/moodle'; // Cpanel host
 
$CFG->dirroot   = '/home/example/public_html/moodle';
 
 
//=========================================================================
// 4. DATA FILES LOCATION
//=========================================================================
// Now you need a place where Moodle can save uploaded files.  This
// directory should be readable AND WRITEABLE by the web server user
// (usually 'nobody' or 'apache'), but it should not be accessible
// directly via the web.
//
// - On hosting systems you might need to make sure that your "group" has
//  no permissions at all, but that "others" have full permissions.
//
// - On Windows systems you might specify something like 'c:\moodledata'
 
$CFG->dataroot  = '/home/example/moodledata';


==Disabling update notifications==


//=========================================================================
See [[Notifications]].
// 5. DATA FILES PERMISSIONS
//=========================================================================
// The following parameter sets the permissions of new directories
// created by Moodle within the data directory.  The format is in
// octal format (as used by the Unix utility chmod, for example).
// The default is usually OK, but you may want to change it to 0750
// if you are concerned about world-access to the files (you will need
// to make sure the web server process (eg Apache) can access the files.
// NOTE: the prefixed 0 is important, and don't use quotes.


$CFG->directorypermissions = 02777;
==Enabling debugging==


See [[Debugging]].


//=========================================================================
==Forcing the value of admin settings==
// 6. DIRECTORY LOCATION  (most people can just ignore this setting)
//=========================================================================
// A very few webhosts use /admin as a special URL for you to access a
// control panel or something.  Unfortunately this conflicts with the
// standard location for the Moodle admin pages.  You can fix this by
// renaming the admin directory in your installation, and putting that
// new name here.  eg "moodleadmin".  This will fix admin links in Moodle.


$CFG->admin = 'admin';
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:
// 7. OTHER MISCELLANEOUS SETTINGS (ignore these for new installations)
//=========================================================================
//
// These are additional tweaks for which no GUI exists in Moodle yet.
//
//
// Prevent users from updating their profile images
//      $CFG->disableuserimages = true;
//
// Prevent scheduled backups from operating (and hide the GUI for them)
// Useful for webhost operators who have alternate methods of backups
//      $CFG->disablescheduledbackups = true;
//
// Prevent stats processing and hide the GUI
//      $CFG->disablestatsprocessing = true;
//
// Set global password for "Login as", teacher is prompted only once in each session.
// Set your own password and tell it only to teachers that should have access to this feature.
//      $CFG->loginaspassword = 'yoursharedpassword';
//
// Setting this to true will enable admins to edit any post at any time
//      $CFG->admineditalways = true;
//
// These variables define DEFAULT block variables for new courses
// If this one is set it overrides all others and is the only one used.
//      $CFG->defaultblocks_override = 'participants,activity_modules,search_forums,admin,
course_list:news_items,calendar_upcoming,recent_activity';
//
// These variables define the specific settings for defined course formats.
// They override any settings defined in the formats own config file.
//      $CFG->defaultblocks_site = 'site_main_menu,admin,
course_list:course_summary,calendar_month';
//      $CFG->defaultblocks_social = 'participants,search_forums,calendar_month,calendar_upcoming,
social_activities,recent_activity,admin,course_list';
//      $CFG->defaultblocks_topics = 'participants,activity_modules,search_forums,admin,
course_list:news_items,calendar_upcoming,recent_activity';
//      $CFG->defaultblocks_weeks = 'participants,activity_modules,search_forums,admin,
course_list:news_items,calendar_upcoming,recent_activity';
//
// These blocks are used when no other default setting is found.
//      $CFG->defaultblocks = 'participants,activity_modules,search_forums,admin,
course_list:news_items,calendar_upcoming,recent_activity';
//
//
// This setting will put Moodle in Unicode mode. Please note that database must support it.
// Do not enable this if your database in not converted to UTF-8!
//    $CFG->unicodedb = true;
//
// Allow unicode characters in uploaded files, generated reports, etc.
// This setting is new and not much tested, there are known problems
// with backup/restore that will not be solved, because native infozip
// binaries are doing some weird conversions - use internal PHP zipping instead.
// NOT RECOMMENDED FOR PRODUCTION SITES
//    $CFG->unicodecleanfilename = true;
//
// Seconds for files to remain in caches. Decrease this if you are worried
// about students being served outdated versions of uploaded files.
//    $CFG->filelifetime = 86400;
//
// This setting will prevent the 'My Courses' page being displayed when a student
// logs in. The site front page will always show the same (logged-out) view.
//    $CFG->disablemycourses = true;
//
// If this setting is set to true, then Moodle will track the IP of the
// current user to make sure 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 coming using proxies that change all the time,
// like AOL.
//      $CFG->tracksessionip = true;
//
//
// The following lines are for handling email bounces.
//      $CFG->handlebounces = true;
//      $CFG->minbounces = 10;
//      $CFG->bounceratio = .20;
// The next lines are needed both for bounce handling and any other email to module processing.
// mailprefix must be EXACTLY four characters.
// Uncomment and customise this block for Postfix
//      $CFG->mailprefix = 'mdl+'; // + is the separator for Exim and Postfix.
//      $CFG->mailprefix = 'mdl-'; // - is the separator for qmail
//      $CFG->maildomain = 'youremaildomain.com';
//
// The following setting will tell Moodle to respect your PHP session
// settings. Use this if you want to control session configuration
// from php.ini, httpd.conf or .htaccess files.  
//      $CFG->respectsessionsettings = true;
//
// This setting will cause the userdate() function not to fix %d in
// date strings, and just let them show with a zero prefix.
//      $CFG->nofixday = true;
//
// This setting will make some graphs (eg user logs) use lines instead of bars
//      $CFG->preferlinegraphs = true;
//
// Enabling this will allow custom scripts 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
// At present this will only work for files that include config.php and are called
// as part of the url (index.php is implied).
// Some examples are:
//      http://my.moodle.site/course/view.php
//      http://my.moodle.site/index.php
//      http://my.moodle.site/admin            (index.php implied)
// Custom scripts should not include config.php
// Warning: Replacing standard moodle scripts may pose security risks and/or may not
// be compatible with upgrades. Use this option only if you are aware of the risks
// involved.
// Specify the full directory path to the custom scripts
//      $CFG->customscripts = '/home/example/customscripts';
//
// Performance profiling
//
//  If you set Debug to "Yes" in the Configuration->Variables page some
//  performance profiling data will show up on your footer (in default theme).
//  With these settings you get more granular control over the capture
//  and printout of the data
//
//  Capture performance profiling data
//  define('MDL_PERF'  , true);
//
//  Capture additional data from DB
//  define('MDL_PERFDB'  , true);
//
//  Print to log (for passive profiling of production servers)
//  define('MDL_PERFTOLOG'  , true);
//
//  Print to footer (works with the default theme)
//  define('MDL_PERFTOFOOT', true);
//
// Force displayed usernames
//  A little hack to anonymise user names for all students.  If you set these
//  then all non-teachers will always see these for every person.
//      $CFG->forcefirstname = 'Bruce';
//      $CFG->forcelastname  = 'Simpson';
//
// The following setting will turn SQL Error logging on. This will output an
// entry in apache error log indicating the position of the error and the statement
// called. This option will action disregarding error_reporting setting.
//    $CFG->dblogerror = true;
//
// The following setting will turn on username logging into Apache log. For full details regarding setting
// up of this function please refer to the install section of the document.
//    $CFG->apacheloguser = 0; // Turn this feature off. Default value.
//    $CFG->apacheloguser = 1; // Log user id.
//    $CFG->apacheloguser = 2; // Log full name in cleaned format. ie, Darth Vader will be displayed as darth_vader.
//    $CFG->apacheloguser = 3; // Log username.
// To get the values logged in Apache's log, add to your httpd.conf
// the following statements. In the General part put:
//    LogFormat "%h %l %{MOODLEUSER}n %t \"%r\" %s %b \"%{Referer}i\" \"%{User-Agent}i\"" moodleformat
// And in the part specific to your Moodle install / virtualhost:
//    CustomLog "/your/path/to/log" moodleformat
// CAUTION: Use of this option will expose usernames in the Apache log,
// If you are going to publish your log, or the output of your web stats analyzer
// this will weaken the security of your website.
//
// Email database connection errors to someone.  If Moodle cannot connect to the
// database, then email this address with a notice.
//
//    $CFG->emailconnectionerrorsto = 'your@emailaddress.com';
//
// Restore pre-1.6 behaviour where courses could still be available
// even if the category they were in was hidden
//    $CFG->allowvisiblecoursesinhiddencategories = true;
//
// NOTE: if you are using custompix in your theme, see /fixpix.php.


//=========================================================================
<syntaxhighlight lang="php">
// ALL DONE!  To continue installation, visit your main page with a browser
$CFG->forced_plugin_settings['filter_tex']['pathconvert'] = '/usr/bin/convert';
//=========================================================================
$CFG->forced_plugin_settings['filter_tex']['pathdvips']  = '/usr/bin/dvips';
if ($CFG->wwwroot == 'http://example.com/moodle') {
$CFG->forced_plugin_settings['filter_tex']['pathdvisvgm'] = '/usr/bin/dvisvgm';
    echo "<p>Error detected in configuration file</p>";
$CFG->forced_plugin_settings['filter_tex']['pathlatex'= '/usr/bin/latex';
    echo "<p>Your server address can not be: \$CFG->wwwroot = 'http://example.com/moodle';</p>";
</syntaxhighlight>
    die;
}
 
if (file_exists("$CFG->dirroot/lib/setup.php"))  {      // Do not edit
    include_once("$CFG->dirroot/lib/setup.php");
} else {
    if ($CFG->dirroot == dirname(__FILE__)) {
        echo "<p>Could not find this file: $CFG->dirroot/lib/setup.php</p>";
        echo "<p>Are you sure all your files have been uploaded?</p>";
    } else {
        echo "<p>Error detected in config.php</p>";
        echo "<p>Error in: \$CFG->dirroot = '$CFG->dirroot';</p>";
        echo "<p>Try this: \$CFG->dirroot = '".dirname(__FILE__)."';</p>";
    }
    die;
}
// MAKE SURE WHEN YOU EDIT THIS FILE THAT THERE ARE NO SPACES, BLANK LINES,
// RETURNS, OR ANYTHING ELSE AFTER THE TWO CHARACTERS ON THE NEXT LINE.
?>
</pre>


==See also==
==See also==
Line 390: Line 76:
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=137889 Moodle Salting] forum discussion
* Using Moodle [http://moodle.org/mod/forum/discuss.php?d=137889 Moodle Salting] forum discussion


[[Category: Administrator]]
[[de:Konfigurationsdatei]]
[[de:Konfigurationsdatei]]
[[es:config.php]]
[[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